Better documentation leading to wider integration/compatibility (eg Zephyr)

[dmalnati]

I love the drag/drop UF2 bootloader and it should become the standard for all microcontrollers IMO.

I'm in the process of building an application on Zephyr, but they don't offer bootloaders with the UF2 functionality the Adafruit bootloader offers.

So I've done some deep diving on how to integrate the two. I'm not 100% sure I'm there yet but the struggle leads me to make this post.

Basically, more documentation I think would lead to greater adoption of the bootloader, even if just for hobbiests. This benefits Adafruit as well, since, for example, I'm building a Zephyr application running on the feather nRF52840, which I got from Adafruit.

Specifics - Interoperability

I could not find documentation easily about the Adafruit bootloader talking about what I would need to do with my compiled binary to get it to boot once I flashed the Adafruit loader.

Later I did learn it by reading through the source code (deeply).

(link) I put a post on the Nordic boards for others to see. Finding that I needed the application to start at 0x1000 was harder than it needed to be, though, and I felt like I had read other incorrect answers in the process of trying to determine it.

Specifics - Flash Memory Partitioning

I am in the process of working through this at the moment, but I cannot find any particular documentation describing how the Adafruit bootloader chops up and makes use of Flash memory.

Reading through the code, I was able to find the ASCII comment showing the layout.

       *                          -------------         -------------
       *                         |             |       |             |
       *                         |  Bootloader |       |  Bootloader |
       *  BOOTLOADER_ADDR_START--|-------------|       |-------------|
       *                         |  App Data   |       |  App Data   |
       *       USER_FLASH_END ---|-------------|       |-------------|
       *                         |             |       |             |
       *                         |             |       |     New     |
       *                         | Application | ----> | Application |
       *                         |             |       |             |
       *       USER_FLASH_START--|-------------|       |-------------|
       *                         |     MBR     |       |     MBR     |
       *                          -------------         -------------

I subsequently modified the firmware to print out the specifics for my build (nRF52840) regarding addresses and capacities (cap) of sections:
(Note -- in DEBUG=1 mode the DFU_APP_DATA_RESERVED value is set to 0, but not during normal build, is this good?)

===== Memory Map ====
| FLASHEND                               = 0x00100000
|
| | BOOTLOADER_(settings_end)            = 0x00100000 [cap=0x00002000,   8192]
| |   BOOTLOADER_SETTINGS_ADDRESS        = 0x000FF000
| |   BOOTLOADER_MBR_PARAMS_PAGE_ADDRESS = 0x000FE000
| | BOOTLOADER_(settings_start)          = 0x000FE000
|
| | BOOTLOADER_ADDR_END                  = 0x000FE000 [cap=0x00011000,  69632]
| | BOOTLOADER_ADDR_START                = 0x000ED000
|
| | DFU_APP_DATA_RESERVED (end)          = 0x000ED000 [cap=0x0000A000,  40960]
| | DFU_APP_DATA_RESERVED (start)        = 0x000E3000
|
| | USER_FLASH_END                       = 0x000E3000 [cap=0x000E2000, 925696]
| | USER_FLASH_START                     = 0x00001000
|
| | MBREND                               = 0x00001000 [cap=0x00001000,   4096]
| | MBRSTART                             = 0x00000000
|
| FLASHSTART                             = 0x00000000

The memory layout is not problematic and leaves a lot of space for the application, which is good.
It does differ from Zephyr in the layout though, and I'm in the process of determining if it is a direct conflict (which I think it is).

Specifically, Zephyr applications, depending on configuration, make more or less use of a "Device Tree" laying out memory, and adhering to "partitions" of the memory.

By default, here is the layout of the DeviceTree for the Adafruit Feather nRF52840 (each partition 'reg' value indicating the starting address and capacity):

&flash0 {
	partitions {
		compatible = "fixed-partitions";
		#address-cells = <1>;
		#size-cells = <1>;

		boot_partition: partition@0 {
			label = "mcuboot";
			reg = <0x000000000 0x0000C000>;
		};
		slot0_partition: partition@c000 {
			label = "image-0";
			reg = <0x0000C000 0x00067000>;
		};
		slot1_partition: partition@73000 {
			label = "image-1";
			reg = <0x00073000 0x00067000>;
		};
		scratch_partition: partition@da000 {
			label = "image-scratch";
			reg = <0x000da000 0x0001e000>;
		};

		/*
		 * The flash starting at 0x000f8000 and ending at
		 * 0x000fffff is reserved for use by the application.
		 */

		/* Storage partition will be used by FCB/NFFS/NVS if enabled. */
		storage_partition: partition@f8000 {
			label = "storage";
			reg = <0x000f8000 0x00008000>;
		};
	};
};

What isn't obvious is that the "storage" partition is the default Flash area to write data to by Zephyr underlying libraries (such as BLE).

I'm in the process of testing, but based on the fact that the "storage" partition occupies the last 0x8000 (32,768) bytes, that this is a direct conflict and overlap with the Adafruit bootloader and bootloader settings.

Perhaps I'll find I'm wrong, but the fact that there is no guide leading the investigation makes it necessary to experiment.

If I'm right, I will be re-configuring the device tree to identify the area of Flash that is safe to call "storage" (the DFU_APP_DATA_RESERVED data).

Conclusion

Zephyr has a long LONG way to go in order to be more user friendly. I think the Adafruit bootloader is much closer, and would benefit the community and Adafruit if more time was put toward making it easier to use.

Thanks.