docs: Update Memory layout, Partial Flashing, Building for V2, BLE (b…

…bcmicrobit#705) * Add layout table and partial flashing * deprecated appending script * add build info for v2 * Add section on BLE DFU for V2 * Carlos' feedback * fix filesystem link * fixup! fix filesystem link * fixup! fixup! fix filesystem link * formatting * formatting * fix filesystem link * Update docs/devguide/hexformat.rst Co-authored-by: Carlos Pereira Atencio <[email protected]>
microbit-carlos · Feb 26, 2024 · 952a00b · 952a00b
1 parent b416f68
commit 952a00b
Show file tree

Hide file tree

Showing 2 changed files with 101 additions and 6 deletions.
diff --git a/docs/ble.rst b/docs/ble.rst
@@ -1,10 +1,13 @@
 Bluetooth
 *********
 
+micro:bit V1
+============
+
 While the BBC micro:bit has hardware capable of allowing the device to work as
 a Bluetooth Low Energy (BLE) device, it only has 16k of RAM. The BLE stack
 alone takes up 12k RAM which means there's not enough memory for MicroPython
-to support Bluetooth.
+to support Bluetooth on a micro:bit V1.
 
 .. note::
     MicroPython uses the radio hardware with the :mod:`radio` module. This
@@ -13,3 +16,15 @@ to support Bluetooth.
 
     Furthermore, the protocol used in the :mod:`radio` module is a lot simpler
     than BLE, making it far easier to use in an educational context.
+
+micro:bit V2
+============
+
+The nRF52833 used by the micro:bit V2 has 128k of RAM, allowing Micropython to make
+use of the BLE stack. Currently the only implemented feature is BLE flashing, allowing 
+a user to update the firmware on the micro:bit over Bluetooth.
+
+At the time that this was written the `Nordic DFU service <https://infocenter.nordicsemi.com/topic/sdk_nrf5_v16.0.0/lib_bootloader_dfu_process.html>`_ is implemented, and partial flashing is currently working but in
+beta. The Nordic DFU service updates everything in flash and will take a (relatively) long
+time to complete, whereas the partial flashing service only updates the filesystem containing
+the user scripts.
diff --git a/docs/devguide/hexformat.rst b/docs/devguide/hexformat.rst
@@ -22,8 +22,8 @@ The general memory layout used is:
     addresses of the data stored progress in incremental order.
     If there is an address jump backwards DAPLink will fail to flash the file.
 
-UICR format
------------
+UICR format (micro:bit V1)
+---------------------------
 
 The User Information Configuration Registers (UICR) is a region of Non-Volatile
 Memory available to store user-specific settings.
@@ -42,9 +42,62 @@ the UICR customer[16] register:
 - ``0x100010d4``: 4-byte integer with the address in the firmware of the version string
 - ``0x100010d8``: 4-byte integer with value ``0x00000000``
 
+Layout table (micro:bit V2)
+---------------------------
+
+A flash layout table is appended to the the hex file when building MicroPython
+for a micro:bit V2.
+
+The layout table is a sequence of 16-byte entries.  The last entry contains the
+header (including magic numbers) and is aligned to the end of a page such that
+the final byte of the layout table is the final byte of the page it resides in.
+This is so it can be quickly and easily searched for.
+
+The layout table has the following format.  All integer values are unsigned and
+store little endian.
+
+::
+
+    0x00  0x01  0x02  0x03  0x04  0x05  0x06  0x07  0x08  0x09  0x0a  0x0b  0x0c  0x0d  0x0e
+    
+    ID    HT    REG_PAGE    REG_LEN                 HASH_DATA
+    (additional regions)
+    ...
+    MAGIC1                  VERSION     TABLE_LEN   NUM_REG     PSIZE_LOG2  MAGIC2
+    
+    The values are:
+    
+    ID         - 1 byte  - region id for this entry, defined by the region
+    HT         - 1 byte  - hash type of the region hash data
+    REG_PAGE   - 2 bytes - starting page number of the region
+    REG_LEN    - 4 bytes - length in bytes of the region
+    HASH_DATA  - 8 bytes - data for the hash of this region
+                           HT=0: hash data is empty
+                           HT=1: hash data contains 8 bytes of verbatim data
+                           HT=2: hash data contains a 4-byte pointer to a string
+    
+    MAGIC1     - 4 bytes - 0x597F30FE
+    VERSION    - 2 bytes - table version (currently 1)
+    TABLE_LEN  - 2 bytes - length in bytes of the table excluding this header row
+    NUM_REG    - 2 bytes - number of regions
+    PSIZE_LOG2 - 2 bytes - native page size of the flash, log-2
+    MAGIC2     - 4 bytes - 0xC1B1D79D
+
+
+This layout table is used to communicate the version of MicroPython and the
+current memory layout to a Bluetooth client and enable `partial flashing <https://github.com/microbit-sam/codal-microbit-v2/blob/initial-docs-pf-and-memory-map/docs/bluetooth/MicroBitPartialFlashing.md>`_
+(only updating the Python script, and keeping the existing version of
+MicroPython in flash).
+
 Steps to create the firmware.hex file
 -------------------------------------
 
+micro:bit V1
+============
+
+This applies to MicroPython for the micro:bit V1, the source of which can be
+found here: `bbcmicrobit/micropython <https://github.com/bbcmicrobit/micropython>`_.
+
 The yotta tool is used to build MicroPython, but before that takes place
 additional files have to be generated by the Makefile in preparation for the
 build, and additional data is added to the hex file after.
@@ -59,6 +112,33 @@ Running the ``make all`` command executes the following steps:
 - The user can optionally append a script using ``tools/makecombinedhex.py``
   (or other tools)
 
+micro:bit V2
+============
+
+This applies to MicroPython for the micro:bit V2, the source of which can be 
+found here: `microbit-foundation/micropython-microbit-v2 <https://github.com/microbit-foundation/micropython-microbit-v2>`_.
+
+This is a port of MicroPython to the micro:bit which uses CODAL as the 
+underlying target platform.
+
+After cloning this repository update the submodules::
+
+    $ git submodule update --init
+
+Then build the MicroPython cross-compiler::
+
+    $ make -C lib/micropython/mpy-cross
+
+After setting up, go to the src/ directory and build::
+
+    $ cd src
+
+    $ make
+
+That will build both ``libmicropython.a`` (from source in ``src/codal_port/``) and the 
+CODAL app (from source in ``src/codal_app/``). The resulting firmware will be 
+``MICROBIT.hex`` in the ``src/`` directory which can be copied to the micro:bit.
+
 Including a user script
 -----------------------
 
@@ -73,10 +153,10 @@ add the filesystem to HEX files for MicroPython V1 & V2, and then combine both
 into a `Universal HEX <https://tech.microbit.org/software/hex-format/#universal-hex-files>`_
 file to ensure compatibility with both hardware variants.
 
-Appended script format (Deprecated)
-===================================
+Appended script format (Deprecated) V1
+======================================
 
-This method of appending the script to the end of MicroPython
+This method of appending the script to the end of MicroPython for micro:bit V1
 is no longer used. Python files are now stored in the
 `filesystem <../filesystem.html>`_ and ``main.py`` is the program entry point.