Facilitate RP2040 XIP-cache-as-RAM feature (#2653)

The pico-sdk and RP2040 hardware provide a few facilities that improve performance by moving runtime code and data into SRAM:
1. "pico/platform/sections.h" currently provides the "__not_in_flash", "__not_in_flash_func", and "__time_critical_func" macros for placing runtime code and data into SRAM by assigning them linker section names in the source code.
2. The pico-sdk CMake scripts allow any of four binary types to be selected with similarly named project properties for the RP2040: "default", "blocked_ram", "copy_to_ram", or "no_flash"
3. The RP2040's eXecute-In-Place (XIP) cache has its own connection to the main AHB bus and provides SRAM speeds on cache hits when retrieving runtime code and data from flash

But this regime isn't perfect. The 16kB of XIP cache and its connection to the main AHB bus go mostly unused for PICO_COPY_TO_RAM and PICO_NO_FLASH binary type builds, leaving some performance opportunities unrealized in their implementations.

The RP2040's eXecute-In-Place (XIP) cache can be disabled by clearing its CTRL.EN bit which allows its 16kB of memory to be used as SRAM directly.

These changes are aiming to update the pico-sdk to support the following:

1. Use the "__time_critical_func" macro to place runtime code into XIP RAM for PICO_COPY_TO_RAM and PICO_NO_FLASH binary type builds
2. Add a couple new "copy_to_ram_using_xip_ram" and "no_flash_using_xip_ram" binary type builds for the RP2040
3. Add a new "PICO_USE_XIP_CACHE_AS_RAM" CMake property to enable the XIP cache's use as RAM for time critical instructions in PICO_COPY_TO_RAM and PICO_NO_FLASH binary type builds
4. Add a couple new CMake functions "pico_sections_not_in_flash(TARGET [list_of_sources])" and "pico_sections_time_critical(TARGET [list_of_sources])" that target selected source files or a whole CMake build target's list of source files for placement into RAM and/or XIP RAM

I believe I've achieved these 4 goals, but note: I've only tested them manually with CMake based builds on the RP2040 hardware that I have. Though I have made an effort to fail fast when configuration properties are incompatible, and I've also made an effort to stay compatible with the preexisting section names and the preexisting linker scripts.

Author: steffen.yount

src/cmake/rp2_common.cmake

@@ -3,7 +3,7 @@
 include(cmake/on_device.cmake)
 
 # PICO_CMAKE_CONFIG: PICO_NO_FLASH, Option to default all binaries to not use flash i.e. run from SRAM, type=bool, default=0, group=build, docref=cmake-binary-type-config
-option(PICO_NO_FLASH "Default binaries to not not use flash")
+option(PICO_NO_FLASH "Default binaries to not use flash")
 # PICO_CMAKE_CONFIG: PICO_COPY_TO_RAM, Option to default all binaries to copy code from flash to SRAM before running, type=bool, default=0, group=build, docref=cmake-binary-type-config
 option(PICO_COPY_TO_RAM "Default binaries to copy code to RAM when booting from flash")
 

src/rp2040/boot_stage2/BUILD.bazel

@@ -35,6 +35,7 @@ BOOT2_CHOICE_DEFINE_MAP["compile_time_choice"] = []
 cc_library(
     name = "config",
     hdrs = [
+        "asminclude/embedded_xip_cache_enable_block.inc.S",
         "asminclude/boot2_helpers/exit_from_boot2.S",
         "asminclude/boot2_helpers/read_flash_sreg.S",
         "asminclude/boot2_helpers/wait_ssi_ready.S",

src/rp2040/boot_stage2/asminclude/embedded_xip_cache_enable_block.inc.S

@@ -0,0 +1,16 @@
+#include "hardware/regs/addressmap.h"
+#include "hardware/regs/xip.h"
+
+#if defined(PICO_USE_XIP_CACHE_AS_RAM) && PICO_USE_XIP_CACHE_AS_RAM
+    // Disable the XIP cache making its 16k of XIP RAM available for storage
+_b2_disable_xip_cache:
+    ldr r0, =(REG_ALIAS_CLR_BITS + XIP_CTRL_BASE + XIP_CTRL_OFFSET)
+    movs r1, #XIP_CTRL_EN_BITS
+    str r1, [r0]
+#else
+    // Enable the XIP cache (hardware default)
+_b2_enable_xip_cache:
+    ldr r0, =(REG_ALIAS_SET_BITS + XIP_CTRL_BASE + XIP_CTRL_OFFSET)
+    movs r1, #XIP_CTRL_EN_BITS
+    str r1, [r0]
+#endif

src/rp2040/boot_stage2/boot2_at25sf128a.S

@@ -266,6 +266,8 @@ configure_ssi:
 // Bus accesses to the XIP window will now be transparently serviced by the
 // external flash on cache miss. We are ready to run code from flash.
 
+#include "embedded_xip_cache_enable_block.inc.S"
+
 // Pull in standard exit routine
 #include "boot2_helpers/exit_from_boot2.S"
 

src/rp2040/boot_stage2/boot2_generic_03h.S

@@ -96,6 +96,8 @@ regular_func _stage2_boot
 // translated by the SSI into 03h read commands to the external flash (if cache is missed),
 // and the data will be returned to the bus.
 
+#include "embedded_xip_cache_enable_block.inc.S"
+
 // Pull in standard exit routine
 #include "boot2_helpers/exit_from_boot2.S"
 

src/rp2040/boot_stage2/boot2_is25lp080.S

@@ -248,6 +248,8 @@ configure_ssi:
 // We are now in XIP mode, with all transactions using Dual I/O and only
 // needing to send 24-bit addresses (plus mode bits) for each read transaction.
 
+#include "embedded_xip_cache_enable_block.inc.S"
+
 // Pull in standard exit routine
 #include "boot2_helpers/exit_from_boot2.S"
 

src/rp2040/boot_stage2/boot2_w25q080.S

@@ -268,6 +268,8 @@ configure_ssi:
 // Bus accesses to the XIP window will now be transparently serviced by the
 // external flash on cache miss. We are ready to run code from flash.
 
+#include "embedded_xip_cache_enable_block.inc.S"
+
 // Pull in standard exit routine
 #include "boot2_helpers/exit_from_boot2.S"
 

src/rp2040/boot_stage2/boot2_w25x10cl.S

@@ -187,6 +187,8 @@ regular_func _stage2_boot
 // We are now in XIP mode, with all transactions using Dual I/O and only
 // needing to send 24-bit addresses (plus mode bits) for each read transaction.
 
+#include "embedded_xip_cache_enable_block.inc.S"
+
 // Pull in standard exit routine
 #include "boot2_helpers/exit_from_boot2.S"
 

src/rp2_common/pico_crt0/BUILD.bazel

@@ -28,6 +28,14 @@ alias(
     }),
 )
 
+alias(
+    name = "copy_to_ram_using_xip_ram_linker_script",
+    actual = select({
+        "//bazel/constraint:rp2040": "//src/rp2_common/pico_crt0/rp2040:copy_to_ram_using_xip_ram_linker_script",
+        "//conditions:default": "//bazel:incompatible_cc_lib",
+    }),
+)
+
 alias(
     name = "no_flash_linker_script",
     actual = select({
@@ -37,6 +45,14 @@ alias(
     }),
 )
 
+alias(
+    name = "no_flash_using_xip_ram_linker_script",
+    actual = select({
+        "//bazel/constraint:rp2040": "//src/rp2_common/pico_crt0/rp2040:no_flash_using_xip_ram_linker_script",
+        "//conditions:default": "//bazel:incompatible_cc_lib",
+    }),
+)
+
 cc_library(
     name = "no_warn_rwx_flag",
     linkopts = select({

src/rp2_common/pico_crt0/crt0.S

@@ -11,6 +11,7 @@
 
 #include "hardware/regs/addressmap.h"
 #include "hardware/regs/sio.h"
+#include "hardware/regs/xip.h"
 #include "pico/binary_info/defs.h"
 #include "boot/picobin.h"
 #include "pico/bootrom.h"
@@ -457,6 +458,22 @@ hold_non_core0_in_bootrom:
     b _enter_vtable_in_r0
 1:
 
+#if PICO_RP2040 && PICO_NO_FLASH
+    #if PICO_USE_XIP_CACHE_AS_RAM
+        // Disable the XIP cache making its 16k of XIP RAM available for storage
+_disable_xip_cache:
+        ldr r0, =(REG_ALIAS_CLR_BITS + XIP_CTRL_BASE + XIP_CTRL_OFFSET)
+        movs r1, #XIP_CTRL_EN_BITS
+        str r1, [r0]
+    #else
+        // Enable the XIP cache (hardware default)
+_enable_xip_cache:
+        ldr r0, =(REG_ALIAS_SET_BITS + XIP_CTRL_BASE + XIP_CTRL_OFFSET)
+        movs r1, #XIP_CTRL_EN_BITS
+        str r1, [r0]
+    #endif
+#endif
+
 #if !PICO_RP2040 && PICO_EMBED_XIP_SETUP && !PICO_NO_FLASH
     // Execute boot2 on the core 0 stack (it also gets copied into BOOTRAM due
     // to inclusion in the data copy table below). Note the reference
@@ -552,6 +569,12 @@ data_cpy_table:
 .word __data_start__
 .word __data_end__
 
+#if PICO_RP2040 && PICO_USE_XIP_CACHE_AS_RAM
+.word __xip_ram_text_source__
+.word __xip_ram_text_start__
+.word __xip_ram_text_end__
+#endif
+
 .word __scratch_x_source__
 .word __scratch_x_start__
 .word __scratch_x_end__