1 Microchip MCU8 Firmware Update Image Specification
Overview
The image format designed by MCU8 is agnostic to the devices that we support. The same image format is being used for PIC18, PIC16, and AVR microcontrollers.
To enable that support we have grouped the image into chunks that contain a specified number of PCODE bytes as well as a specified number of metadata bytes that are understood as header information. This header information is used to describe how to write the data into the target no matter the type of device. We are using a common header format for every block type for simplicity.
General Rules to Remember:
Every block should 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 should be padded out with NULL data defined by the architecture. (PIC16 -> 0x3FFF, PIC18 -> 0xFF)
Every block will contain the same unlock keys
Header data is understood as little endian
A TOML file will be used to communicate the configurations needed by the formatter tool
Addresses used in the TOML file are not remapped
Addresses of the TOML file will be in words when a PIC16 is used
The image builder tool should allow for an option to remove 'null' data blocks from the output image. If one or more of the blocks in the image only contain 'empty' data bytes then that block can be excluded using a CLI option flag
Block Header
| Block Length | Block Type |
|---|---|
| 2 byte | 1 byte |
Block Length
This value defines the number of bytes in each block. This will be kept at the total block size for now but in the future we would like this to contain a count of total valid data bytes in the block. If this data reflected the number of valid bytes populated by the formatter tool then the bootloader would be capable of writing any length data just by reading the length at the front of the header and passing that length to the memory extension functions.
Block Type
This value defines the type of data housed in the block.
| Metadata Block | Flash Block | EEPROM Block |
|---|---|---|
| 0x01 | 0x02 | 0x03 |
| Metadata Block | Flash Block | EEPROM Block |
Metadata Block
The metadata block is used as a form of pre-image validation. The metadata block will contain information that the bootloader must process and return a success code otherwise the rest 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 Rules
A minor revision of the image format means that the updated version added additional information into one or more of the operational blocks but did not change the size or orientation of the previous revisions format. For example, a bootloader that was originally designed to work on version 1.0 of the image format should also be able to support loading an image that is using version 1.1 of the image format. Since no information that was previously understood changed locations or sizes, we can still fully understand the format given in 1.1.
A major revision of the image means that past versions of the bootloader handler will be unable to understand the new data orientation because of a few different reasons:
A value in the image format changed sizes. Ex. Data Length being changed from 16-bit to 8-bit would break the version.
One or more values in the image format changed locations in the payload. Ex. Data Length is moved to byte 2 and 3 (after the block type).
A patch version in the file format would indicate that there was an error in documentation but the bootloader functionality and file data did not change.
Device ID
This value will define the ID of the device that this image is meant to be booted with.
Write Size
This value will define the maximum size in bytes that the bootloader can write at one time.
App Start Address
This value will define the start address of the image that will be booted. This value is the word address when a PIC16 is used.
Page Erase Key
This value will define the key value to be used for any operation that triggers a page erase.
Page Write Key
This value will define the key value to be used for any operation that triggers a page write.
Byte Write Key
This value will define the key value to be used for any operation that triggers a byte write. (Or word write depending on the architecture)
Page Read Key
This value will define the key value to be used for any operation that triggers a page read.
Flash or EEPROM Write Block
Operational write blocks are blocks that should be passed 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 will define the start address of the data held in this block. This value is the word address when a PIC16 is used.
Key Definitions do not change from block to block.
Configuration TOML Overview
In order for the image builder tool to understand how it can create these blocks and headers, we must provide some form of input to the tool. The agreed upon format that we will use to communicate the bootloader configuration to the image builder tool is through a TOML file. This TOML file will contain information needed by the image builder tool to parse over the hex file and create the necessary blocks in the output image file. TOML configuration parts will be described below:
Bootloader Configurations
Note: For PIC16F devices, the address values that are seen in this TOML file are word addresses.
| Configuration Name | Description |
|---|---|
| ARCH | This string defined the architecture that was configured in the bootloader. If this value is PIC16 some extra steps may be required to correct the word vs. byte addressing |
| IMAGE_FORMAT_VERSION | Semantic version value of the image format given in string format. e.g. "0.3.0" |
| PAGE_ERASE_KEY | Page Erase key to be written into each header |
| PAGE_READ_KEY | Page Read key to be written into each header |
| PAGE_WRITE_KEY | Page Write key to be written into each header |
| BYTE_WRITE_KEY | Byte or Word Write key to be written into each header |
| DEVICE_ID | 32-bit device id value to be used in the metadata block |
| WRITE_BLOCK_SIZE | The size that the bootloader is able to write in bytes |
| 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 |
Host Configurations
| Configuration Name | Description |
|---|---|
| TBD | ... |