Documentation: Info on hex file format

[microbit-carlos]

It'd be good to document for developers how the hex file is formed, how/where the user code is added into the known flash location, how we are adding the version info into the UICR and its implications in adding user code into the hex.

[dpgeorge]

Yes, I can write such documentation. Is it needed for v1.0.0?

[microbit-carlos]

If you can that would be great, I can probably spend some time early next week to put something together as well.
Doesn't need to be massive, just some general info so that anybody developing an editor or tool knows what's going on . For example, we had to do these two small changes in the Python Editor and uFlash for the UICR addition: bbcmicrobit/PythonEditor@5348388
https://github.com/ntoll/uflash/pull/52/files

[dpgeorge]

Here is a brief description of the .hex file.

General memory-address layout (appearing in this order in the hex):

0x00000000: firmware
0x100010c0: UICR data, 28 bytes
0x0003e000: appended script (optional)

Steps in creating the hex file:

1. yotta builds the source and creates a bare hex file with just the firmware in it (first section above)
2. tools/adduicr.py adds the UICR to the bare hex (second section above); puts output in build/firmware.hex; this is what ships as the official firmware
3. user can optionally append a script using tools/makecombinedhex.py (or otherwise)

UICR format (everything stored as little endian):

• 4-byte integer with magic value 0x17eeb07c
• 4-byte integer with value 0xffffffff
• 4-byte integer with value 10 (log base 2 of the flash page size, being 1024 bytes)
• 2-byte integer with value 0 (start page of the firmware)
• 2-byte integer storing number of pages used by the firmware
• 4-byte integer with value 0xffffffff
• 4-byte integer with the address in the firmware of the version string
• 4-byte integer with value 0

Appended script format:

• 2 bytes "MP"
• 2-byte little endian integer for the length (in bytes) of the appended script that follows this 4 byte header
• script bytes

[microbit-carlos]

Implemented in #561.