Docs: Add information about the hex file format #561
Conversation
| .. note:: | ||
| If you append any data or modify the Intel Hex file, please ensure the | ||
| addresses of the data stored progress in incremental order. | ||
| If there is an address jump backwards DAPLink will fail to flash the file. |
There was a problem hiding this comment.
Hmm, this contradicts what is done by makecombinedhex.py: it appends the user script (at 0x3e000) to the build/firmware.hex file, with the latter having the UICR info at the end of the .hex. So the final hex looks like this:
0x00000000 - uPy firmware
0x100010c0 - UICR info
0x0003e000 - appended script
And DAPLink seems fine with this, it seems to flash it without error.
There was a problem hiding this comment.
I'm on the move at the moment, so I cannot really look into this in much detail for a couple of hours, but if I download a hex file with RC5 + the default code from https://python.microbit.org/v/beta and manually move the UICR data between MicroPython and the appended code, the hex is not flashed correctly in my test:
...
:1082400005050505050505FF00000401E90000001E
:10825000852B000051340000257800006D6101007D
:108260004563010095630100C9880100C100000059
:020000041000EA
:1010C0007CB0EE17FFFFFFFF0A0000000000E10008
:0C10D000FFFFFFFF6D0E0300000000009A
:020000040003F7
:10E000004D509900232041646420796F757220502F
:10E010007974686F6E20636F646520686572652E21
:10E0200020452E672E0A66726F6D206D6963726FD0
:10E0300062697420696D706F7274202A0A0A0A7707
:10E0400068696C6520547275653A0A202020206446
:10E050006973706C61792E7363726F6C6C282748DA
:10E06000656C6C6F2C20576F726C642127290A2015
:10E07000202020646973706C61792E73686F772833
:10E08000496D6167652E4845415254290A20202078
:10E0900020736C6565702832303030290A0000002A
:0400000500019C0951
:00000001FF
Can you replicate this?
I'll have a look how makecombinedhex is combining the files, maybe I am missing something.
There was a problem hiding this comment.
I cannot replicate. This test (of manually moving the UICR data for the default code) works fine for me (scrolling hello world, then a heart image, looping).
There was a problem hiding this comment.
This is an important issue to work out, because makecombinedhex.py needs to be changed if it doesn't work with DAPLink.
There was a problem hiding this comment.
Yes, I've been looking into this, and I think it works in older version of DAPLink, but not the new ones.
I was testing this today with version 0249 and didn't work, and also I'm pretty sure it didn't work either on the latest available version released during the time we were first looking into adding the UICR region, likely v0246.
The current DAPLink if the hex order is UICR + MicroPython + code, we get a fail.txt file. However if the hex file has MicroPython + UICR + code, then it fails silently (flashing MicroPython and the UICR, but not the appended code).
This limitation has been designed within DAPLink, however until today I didn't realised it wasn't present in older versions:
https://github.com/ARMmbed/DAPLink/blob/ab7abed209eb166a98a8ecc69b05a4dcbe86adc6/source/daplink/drag-n-drop/flash_manager.c#L127-L134
I found a micro:bit running 0234 and that one flashed both hex files correctly.
There was a problem hiding this comment.
Okay, so DAPLink 0241 which has been shipped from factory for quite a while already presents this limitation, and the new boards will be running 0249, so we should update makecombinedhex.py to append the code before the UICR.
docs/devguide/hexformat.rst
Outdated
|
|
||
| Running the ``make all`` command executes the following steps: | ||
|
|
||
| - Interned strings are added to the ``qstrdefsport.h`` file |
There was a problem hiding this comment.
This needs to be done manually, it's not done by make. Probably best to just remove it.
There was a problem hiding this comment.
I do have a personal aversion to calling it firmware (as a firmware engineer, this is not firmware, it is a runtime image and library packaged alongside the user application).
Might be too late to fix now, but we do get confusion occuring when we say 'update the firmware' and we mean 'update the interface chip firmware by putting the micro:bit into MAINTENANCE mode' and they think they have to update the MicroPython firmware.
While it does pass some of the early 'what is firmware' tests in this article (nvol, device access etc), the strict difference here is that firmware is mostly programmed once and only updated a small number of times across the lifecycle of a product.
https://en.wikipedia.org/wiki/Firmware
It's a personal opinion I have, feel free to ignore me, but I felt this was the best time to mention it if you are updating docs.
There was a problem hiding this comment.
I completely understand the confusion it can create since we call DAPLink the "microbit firmware". I'm happy to call it something else, but I'm not 100% sure what's the best term. Is it "MicroPython runtime"? @dpgeorge do you have any other suggestions?
There was a problem hiding this comment.
I think it's too late now to change these names. With the latest Mu it is anyway more like firmware because there only the user scripts are updated on the filesystem, not the firmware anymore.
There was a problem hiding this comment.
The issue with changing it now is that it requires changes to the Makefile, at least. The word "firmware" is referenced a lot in the code base (git grep firmware shows 40 lines).
There was a problem hiding this comment.
With the latest Mu it is anyway more like firmware because there only the user scripts are updated on the filesystem, not the firmware anymore.
Users will still flash the full flash when switchin to MakeCode or the online Python editor, so that is still a relatively common action.
I wouldn't change any actual code or things like the Makefile, but there is a lot of documentation that will have to be updated (https://github.com/bbcmicrobit/micropython/issues?q=is%3Aopen+is%3Aissue+label%3Adocs) and if we decide to change it, then we could edit the occurrences we find them.
As a small note, it ooks like "MicroPython runtime" has only been used once, in the storage tutorial: https://bbcmicrobitmicropython.readthedocs.io/en/latest/tutorials/storage.html
To be completely honest I don't feel strongly either way.
|
Ok, this looks good now, I've merged it in 60e5e3d Re naming it "firmware": let's not make such a change now, we need to just do the necessary changes only for v1.0.0. |
@dpgeorge please feel free to edit or correct anything as you see fit.