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 Length | Block Type |
---|---|
2-byte | 1-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.
Block Type
This value specifies the type of data contained within the block.
Metadata Block | Flash Block | EEPROM Block |
---|---|---|
0x01 | 0x02 | 0x03 |
Metadata Block | Flash Block | EEPROM Block |
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 Header | Image Format Version | Device ID | Write Size (in bytes) | App Start Address | Page Erase Key | Page Write Key | Byte Write Key | Page Read Key |
---|---|---|---|---|---|---|---|---|
3 bytes | 3 bytes | 4 bytes | 2 bytes | 4 bytes | 2 bytes | 2 bytes | 2 bytes | 2 bytes |
Image Format Version
3-Byte Sematic Versioning
Versioning Guidelines
- 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.
- 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).
- 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 Header | Block Start Address | Page Erase Key | Page Write Key | Byte Write Key | Page Read Key | Data Payload |
---|---|---|---|---|---|---|
3 bytes | 4 bytes | 2 bytes | 2 bytes | 2 bytes | 2 bytes | X 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 Name | Description |
---|---|
ARCH | This 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_VERSION | The image format’s semantic version, provided as a string (e.g., "0.3.0"). |
PAGE_ERASE_KEY | The Page Erase key that must be included in each header. |
PAGE_READ_KEY | The Page Read key that must be included in each header. |
PAGE_WRITE_KEY | The Page Write key that needs to be included in each header. |
BYTE_WRITE_KEY | The Byte or Word Write key that must be included in each header. |
DEVICE_ID | A 32-bit device ID value to be included in the metadata block. |
WRITE_BLOCK_SIZE | The size, in bytes, that the bootloader is able to write. |
FLASH_START | This address defines the first address in the output binary image. |
FLASH_END | This address defines the address where the update will stop. |
EEPROM_START | This address defines the first address of the EEPROM range. |
EEPROM_END | This address defines the end of the EEPROM range. |
CONFIG_START | This address defined the start of the Configuration bits / FUSEs range. |
CONFIG_END | This address defined the end of the Configuration bits / FUSEs range. |
VERIFICATION | This string defines the Memory Verification scheme used. |
NUMBER_OF_APPLICATION_IMAGE | This value defines the number of application images available. |
Host Configurations
Configuration Name | Description |
---|---|
TBD | ... |