Add function docs, add separate universal README, and fixup main README

Also switch to board_type instead of is_w so the functions are clearer

Author: will-v-pi

README.md

@@ -408,12 +408,14 @@ App|Description
 
 These are examples of how to build universal binaries which run on RP2040, and RP2350 Arm & RISC-V.
 These require you to set `PICO_ARM_TOOLCHAIN_PATH` and `PICO_RISCV_TOOLCHAIN_PATH` to appropriate paths, to ensure you have compilers for both architectures.
+These are designed for dragging & dropping onto a device, so may not load as expected when using `picotool`.
+See the separate [README](universal/README.md) for more details of how these work.
 
 App|Description
 ---|---
-[blink_universal](universal/CMakeLists.txt#L126) | Same as the [blink](blink) example, but universal.
+[blink_universal](universal/blink_universal) | A universal blink which works for all Pico-series and Pico W-series boards.
 [hello_universal](universal/hello_universal) | The obligatory Hello World program for Pico (USB and serial output). On RP2350 it will reboot to the other architecture after every 10 prints.
-[nuke_universal](universal/CMakeLists.txt#L132) | Same as the [nuke](flash/nuke) example, but universal. On RP2350 runs as a packaged SRAM binary, so it is written to flash and copied to SRAM by the bootloader.
+[nuke_universal](universal/CMakeLists.txt) | Same as the [nuke](flash/nuke) example, but universal.
 
 ### USB Device
 

universal/CMakeLists.txt

@@ -20,6 +20,10 @@ include(ExternalProject)
 #
 # The build will output a TARGET.bin file which can be written using picotool, and a
 # TARGET.uf2 file which can be dragged and dropped onto the device in BOOTSEL mode
+#
+# If SEPARATE_RP2040 is set, the RP2040 binary will not be included in the block loop,
+# so the RP2040 UF2 file will only contain the RP2040 binary, and the RP2350 UF2 file will
+# contain the combined binary excluding the RP2040 binary.
 function (add_universal_target TARGET SOURCE)
     set(zeroValueArgs SEPARATE_RP2040)
     set(oneValueArgs SOURCE_TARGET PADDING PACKADDR BOARD_RP2040 BOARD_RP2350)
@@ -169,7 +173,9 @@ add_universal_target(blink_universal
     SOURCE_TARGET blink_universal
     BOARD_RP2040 universal
     BOARD_RP2350 universal
-    SEPARATE_RP2040 PLATFORMS "rp2040;rp2350-arm-s" # Skip RISC-V and keep RP2040 separate, as wifi firmware takes up lots of space
+    # Skip RISC-V and keep RP2040 separate, as wifi firmware takes up lots of space
+    PLATFORMS "rp2040;rp2350-arm-s"
+    SEPARATE_RP2040
     )
 
 # nuke binary - is no_flash, so needs to be sent to SRAM on RP2040

universal/README.md

@@ -0,0 +1,55 @@
+# Universal Examples
+
+These examples show ways to load the same code onto different chips, and package
+it in such a way that the bootrom only executes the code compatible with that chip.
+
+## Universal Binary vs Universal UF2
+
+There is a difference between a **Universal Binary** and a **Universal UF2**,
+for the purposes of these examples:
+- A **Universal Binary** is a `.bin` file that can be loaded into flash (or sram) and executed,
+allowing RP2040 and RP2350 (Arm & RISC-V) to run from identical flash contents.
+- A **Universal UF2** is multiple individual `.uf2` files with different family IDs
+concatenated together to create a single `.uf2` file. When dragged & dropped onto a device, 
+only the file with a family ID corresponding to that device will be loaded onto it, and the
+rest of the files will be ignored.
+
+A **Universal Binary** can be packaged into a UF2 file for loading onto a device. However,
+as there isn't a common family ID between RP2040 and RP2350, you would have to package it into a **Universal UF2** with two copies (using `rp2040` and `absolute` family IDs), thus creating a **Universal UF2** of a **Universal Binary**.
+
+## How Universal Binaries work
+
+Universal binaries must be recognised by both the RP2040 and RP2350 bootroms. Therefore, they need the following structure for flash binaries:
+- RP2040 boot2
+  - Required by the RP2040 bootrom
+- RP2040 binary containing an embedded block
+  - The embedded block contains an `IGNORED` item due to RP2350-E13, but you can use an RP2040
+  `IMAGE_DEF` item instead if not using RP2350-A2 chips
+- RP2350 Arm binary containing an embedded block
+  - In addition to the RP2350 `IMAGE_DEF` item, this embedded block contains a
+  `ROLLING_WINDOW_DELTA` item to translate this binary to the start of flash for execution
+- RP2350 RISC-V binary containing an embedded block
+  - Same as the Arm one
+
+All of the embedded blocks are linked into one big block loop.
+
+These are then booted by the respective bootroms:
+- **RP2040** - sees the boot2 at the start and uses that to execute the RP2040 binary, as
+RP2040 has no support for embedded blocks.
+- **RP2350** - sees the block loop and parses it to find the correct embedded block to boot
+from (Arm vs RISC-V). It then translates the flash address according to the
+`ROLLING_WINDOW_DELTA` so that the binary containing that embedded block is at the start of the
+flash address space, and executes from there.
+
+For no_flash binaries the RP2040 boot2 is omitted as the bootrom just executes from the start
+of SRAM, and instead of `ROLLING_WINDOW_DELTA` items the RP2350 binaries use `LOAD_MAP` items,
+to copy the code in SRAM to the correct location for execution rather than using address
+translation.
+
+## How you should use them
+
+For most use cases, **Universal UF2s** are the best option to use. They will only load into
+flash the code that runs on that device. The [blink_universal](blink_universal) example uses a
+Universal UF2 for that reason, as the Wi-Fi firmware is quite large. **Universal Binaries**
+are only currently useful when the commonality of having a single `.bin` file for programming
+outweighs the disadvantage of the extra flash usage.

universal/blink_universal/blink_universal.c

@@ -12,7 +12,21 @@
 #define LED_DELAY_MS 250
 #endif
 
-bool detect_is_w_using_adc(void) {
+enum BOARD_TYPE {
+    BOARD_TYPE_PICO,
+    BOARD_TYPE_PICO_W,
+    BOARD_TYPE_UNKNOWN,
+};
+
+// Detects if PICO_VSYS_PIN is actually connected to the VSYS voltage divider,
+// to determine the board type.
+// Also checks that the LED pin is low, which should be the case for both
+// Pico-series and Pico W-series boards.
+// This will work provided that the board is being powered from VSYS (i.e. it
+// is using the onboard voltage regulator).
+// This method is documented in section 2.4 of Connecting to the Internet with
+// Raspberry Pi Pico W-series (https://pip.raspberrypi.com/documents/RP-008257-DS).
+enum BOARD_TYPE detect_board_type(void) {
     adc_init();
     adc_gpio_init(PICO_VSYS_PIN);
     adc_select_input(PICO_VSYS_PIN - ADC_BASE_PIN);
@@ -25,15 +39,20 @@ bool detect_is_w_using_adc(void) {
     bool value = gpio_get(PICO_DEFAULT_LED_PIN);
 
     if (value == 0 && voltage < 0.1) {
-        return true;
+        // Pico W-series board
+        return BOARD_TYPE_PICO_W;
+    } else if (value == 0) {
+        // Pico-series board
+        return BOARD_TYPE_PICO;
     } else {
-        return false;
+        // Unknown board
+        return BOARD_TYPE_UNKNOWN;
     }
 }
 
 // Perform initialisation
-int pico_led_init(bool is_w) {
-    if (is_w) {
+int pico_led_init(enum BOARD_TYPE board_type) {
+    if (board_type == BOARD_TYPE_PICO_W) {
         return cyw43_arch_init();
     } else {
         // A device like Pico that uses a GPIO for the LED will define PICO_DEFAULT_LED_PIN
@@ -45,22 +64,22 @@ int pico_led_init(bool is_w) {
 }
 
 // Turn the led on or off
-void pico_set_led(bool led_on, bool is_w) {
-    if (is_w) {
+void pico_set_led(bool led_on, enum BOARD_TYPE board_type) {
+    if (board_type == BOARD_TYPE_PICO_W) {
         cyw43_arch_gpio_put(CYW43_WL_GPIO_LED_PIN, led_on);
     } else {
         gpio_put(PICO_DEFAULT_LED_PIN, led_on);
     }
 }
 
 int main() {
-    bool is_w = detect_is_w_using_adc();
-    int rc = pico_led_init(is_w);
+    enum BOARD_TYPE board_type = detect_board_type();
+    int rc = pico_led_init(board_type);
     hard_assert(rc == PICO_OK);
     while (true) {
-        pico_set_led(true, is_w);
+        pico_set_led(true, board_type);
         sleep_ms(LED_DELAY_MS);
-        pico_set_led(false, is_w);
+        pico_set_led(false, board_type);
         sleep_ms(LED_DELAY_MS);
     }
 }