1 Microchip 8-bit Device Firmware Update Image Specification

Overview

The image format is designed to be device-agnostic and is used for both 8-bit PIC® and AVR® microcontrollers (MCUs).

To enable this support, we have organized the image into chunks, each containing a defined number of PCODE bytes along with a specified amount of metadata bytes that serve as header information. This header describes how the data must be written to the target device, regardless of its type. For simplicity, we use a common header format across all block types.

Key Guidelines to Keep in Mind:

  • Every block needs to be X + 15 bytes long where X is the amount of data bytes read out from the .hex file. If a block does not contain X+15 bytes then the rest of the block must be padded out with NULL data defined by the architecture. (PIC16 -> 0x3FFF, PIC18 -> 0xFF)
  • Each block will include identical unlock keys.
  • Header data is interpreted in little-endian format.
  • Configuration details required by the formatter tool will be provided through a TOML file.
  • Addresses specified in the TOML file are used as they are, without remapping.
  • For PIC16 devices, addresses in the TOML file are given in words.
  • The image builder tool must provide an option to exclude 'null' data blocks from the output image. If any block consists solely of 'empty' data bytes, it can be omitted using a command-line flag.

Block Header

Block LengthBlock Type
2-byte1-byte

Block Length

This value specifies the number of bytes in each block. Currently, it will represent the total block size, but in the future, we plan for it to indicate the actual count of valid data bytes within the block. If this value reflected the number of valid bytes generated by the formatter tool, the bootloader could write data of any length by simply reading the length from the header and using it with the memory extension functions.

Metadata Block

The metadata block serves as a means of pre-image validation. It contains information that the bootloader must process and confirm with a success code; if this validation fails, the remainder of the update is aborted.

Note: Each metadata entry will have a little-endian value.

Block HeaderImage Format VersionDevice IDWrite Size (in bytes)App Start AddressPage Erase KeyPage Write KeyByte Write KeyPage Read Key
3 bytes3 bytes4 bytes2 bytes4 bytes2 bytes2 bytes2 bytes2 bytes

Image Format Version

3-Byte Sematic Versioning

Versioning Guidelines

  1. A minor revision to the image format indicates that new information has been added to one or more operational blocks, but the size and structure of the previous format remain unchanged. For example, a bootloader designed for version 1.0 of the image format needs to be compatible with version 1.1, as no existing data has been relocated or resized, ensuring full compatibility with the updated format.
  2. A major revision signifies that earlier versions of the bootloader handler will not be able to interpret the new data structure. This incompatibility can arise for several reasons:
  • The size of a value in the image format has changed (e.g., changing Data Length from 16-bit to 8-bit would break compatibility).
  • One or more values have been moved to different locations within the payload (e.g., relocating Data Length to bytes 2 and 3, after the block type).
  1. A patch version reflects corrections to the documentation only, with no changes to bootloader functionality or the file data itself.

Device ID

This value specifies the device ID for which this image is intended to be booted.

Write Size

This value specifies the maximum number of bytes the bootloader is capable of writing in a single operation.

App Start Address

This value specifies the start address of the image to be booted. For PIC16 devices, this value represents the word address.

Page Erase Key

This value specifies the key that must be provided to authorize any operation that initiates a page erase.

Page Write Key

This value specifies the key that must be provided to authorize any operation that initiates a page write.

Byte Write Key

This value specifies the key that must be provided to authorize any operation that initiates a byte write (or word write, depending on the architecture).

Page Read Key

This value specifies the key that must be provided to authorize any operation that initiates a page read.

Flash or EEPROM Write Block

Operational write blocks are segments that need to be provided to the bootloader for processing.

Block HeaderBlock Start AddressPage Erase KeyPage Write KeyByte Write KeyPage Read KeyData Payload
3 bytes4 bytes2 bytes2 bytes2 bytes2 bytesX bytes

Start Address

This value specifies the starting address of the data contained within this block. For PIC16 devices, this value represents a word address. Key Definitions do not change from block to block.

Configuration TOML Overview

To enable the image builder tool to generate the required blocks and headers, we need to supply it with specific input. We have chosen to use a TOML file as the standardized format for conveying bootloader configuration details to the image builder tool. This TOML file will include all the information the tool needs to parse the hex file and construct the appropriate blocks in the output image file. The components of the TOML configuration will be described below:

Bootloader Configurations

Note: For PIC16F devices, the address values specified in this TOML file are word addresses.

Configuration NameDescription
ARCHThis string specifies the architecture configured in the bootloader. If the value is PIC16, additional steps may be necessary to address differences between word and byte addressing.
IMAGE_FORMAT_VERSIONThe image format’s semantic version, provided as a string (e.g., "0.3.0").
PAGE_ERASE_KEYThe Page Erase key that must be included in each header.
PAGE_READ_KEYThe Page Read key that must be included in each header.
PAGE_WRITE_KEYThe Page Write key that needs to be included in each header.
BYTE_WRITE_KEYThe Byte or Word Write key that must be included in each header.
DEVICE_IDA 32-bit device ID value to be included in the metadata block.
WRITE_BLOCK_SIZEThe size, in bytes, that the bootloader is able to write.
FLASH_STARTThis address defines the first address in the output binary image.
FLASH_ENDThis address defines the address where the update will stop.
EEPROM_STARTThis address defines the first address of the EEPROM range.
EEPROM_ENDThis address defines the end of the EEPROM range.
CONFIG_STARTThis address defined the start of the Configuration bits / FUSEs range.
CONFIG_ENDThis address defined the end of the Configuration bits / FUSEs range.
VERIFICATIONThis string defines the Memory Verification scheme used.
NUMBER_OF_APPLICATION_IMAGEThis value defines the number of application images available.

Host Configurations

Configuration NameDescription
TBD...