Release.1.2.0 (#469)

See release notes for more descriptive details

* Delete some redundant CMake parts (#240)

* pio: Add 'pragma once' to generated header files (#237)

* pio: allow programs with 32 instructions (#236)

* Fixup incorrect doxygen for multicore_fifo_wready

* Add param-validation to spin_lock_instance

* Fix back-to-front description of IRQ priority in doxygen (#245)

* Fix ROSC typo (#259)

* Typo (#251)

* Add gpio_get_out_level() accessor, and correct SIO GPIO_OUT struct ty… (#247)

* Add gpio_get_out_level() accessor, and correct SIO GPIO_OUT struct type from WO to RW

* Add pico_get_unique_board_id_string API (#281)

* Clean up -Wconversion=error issues

* move PLL reset code from clocks driver to pll driver (#110)

* Don't clear PLL PWR/FBDIV after reset as unnecessary. Call out in runtime.c why USB/syscfg aren't reset.

* i2c: set hold time of SDA during transmit to an appropriate value (#273)

* i2c: set hold time of SDA during transmit to 2 for TCS34725 color sensor

* i2c: fix issues in i2c_write_blocking_internal

* i2c: rename sda_hold_count to sda_tx_hold_count

* use assert rather than invalid_params_if for internal consistency checks

* i2c: use a more appropriate sda tx hold time at higher baudrates

* i2c: reduce 120/1e9 to the smallest possible integer numerator and denominator

* Update NULL GPIO function to 0x1f (#320)

* i2c: set high and low times to values that conform to the i2c specification (#314)

* Make flash_do_cmd public (#269)

* Fix implementation config listing in structs/i2c.h (#324)

* Clarify that cache is flushed, but that function is intended for low-level metadata access during startup (#322)

* Fix implementation config listing in structs/i2c.h (#325)

* Fix param-validation for PIO sideset encoding (#311)

* Remove MASTER_ON_HOLD bit from I2C status registers. Fix typos. (#326)

* Fixing arithmetic underflow in SPI I/O loops #337 (#338)

* Source code licence clarification (#340)

* Updated existing Pimoroni board headers to match latest style, and added a new board (#343)

* Added new pimoroni board headers

* SPI Definitions for SparkFun boards (#344)

* SPI Definitions for SparkFun boards


* Clarify multicore_fifo doxygen (#323)

Based on my observations in #284

* correct adafruit flash size for itsybitsy and qt rp2040 (#348)

from 4 MB to 8 MB

* Small typos (#366)

* make spi_init return baud rate set (#296)

* Fix path + typo in README.md (#347)

* Fix path + typo in README.md

* Remove incorrect path change

* Remove typo

* disable core 0 SIO FIFO IRQ handler during core 1 launch in case someone has already installed one (#375)

* add PICO_DIVIDER_DISABLE_INTERRUPTS flag which makes PICO_DIVIDER disable interrupts around division rather than using co-operative guards to protect nested use (i.e. within IRQ/exception). Use of this flag can simplify porting of RTOSes but with a different performance profile (#372)

* make all non hardware_ libraries foo add C preprocessor definition LIB_FOO=1, and remove bespoke definitions which were all undocumented anyway (#374)

* Change various (confusing to user) message to be DEBUG only (#365)

* add small delay to stdio_get_until to prevent starvation of USB IRQ handler due to in use mutex. build was non deterministic due to missing link wrapping of getchar (#364)

* Some cmake build improvements (#376)

* Change some cmake output to DEBUG level
Make SDK build more consistent with other libraries (use an INTERFACE marker library for inclusion tests)
Add PICO_SDK_PRE_LIST_FILES, PICO_SDK_POST_LIST_FILES build vars

* fix typo

* remove leftover debugging message

* i2c: improve communication with i2c devices in i2c_write_blocking

* Definitions for IC_TX_BUFFER_DEPTH inconsistent (fixes #335) (#381)

* Add hardware_exception for setting exception handlers at runtime (#380)

* add __always_inline to trivial super low level inline functions (#379)

* Rework lock_core / timers (#378)

* remove spurious sys/select.h include (#377)

* Fixup IRQ_PRIORITY #define values (#393)

* Correct doxygen for mutex_try_enter (#392)

* Fix a bunch of doxygen typos (#391)

* Rework ordering of cmake, so that libraries in subdirectories can add to internal lists as PICO_SDK_POST_LIST_FILES, PICO_CONFIG_HEADER_FILES etc. (#382)

* Fix some hardware_library dependencies (#383)

* make host pico_platform.h and binary_info.h CMakeLists.txt safe for inclusion in non SDK build (#388)

* Add basic CMSIS core headers (#384)

* Fix the PICO_CONFIG default value for PICO_CMSIS_RENAME_EXCEPTIONS (#399)

* add timeout_us/until to mutex/sem blocking methods (#402)

* Fixup divider save_restore for floating point too; improve tests (#405)

* fix pico_promote_common_scope_vars (#397)

* add comment about using clk_gpout0 enable bit (Fixes #413)

* pioasm: prevent double inclusion for C SDK generated headers (#417)

* Add missing cast to uint32_t in hw_divider_u32_quotient for host (#436)

* Optional feature to get the max level that has ever been held by a queue (#444)

* Fix wrong format string in alarm_pool_dump_key (#437)

* Add support for Arduino Nano RP2040 Connect (#425)

* Add support for Arduino Nano RP2040 Connect

* Add support for at25sf128a flash

* Fix function-name misspelling (#443)

* Update host multicore.h to match multicore.h in rp2_common (#439)

* Implement `uart_write_blocking` and `uart_read_blocking` for host (#438)

* Define `__STRING` for other compilers than MSVC in the host platform.h file (#434)

* Prevent warnings about some unused parameters in pico_stdio_usb when building with -Wextra (#431)

* Fix warnings about some unused parameters in pico_stdio_usb

* Use `__unused` for the unused parameter in tud_descriptor_configuration_cb

* Remove redundant inclusions of `pico/platform.h`

* Define `void operator delete[](void *p, std::size_t n)` in new_delete.cpp (#430)

* queue: make data pointers const in queue_try_add and queue_add_blocking (#423)

* misc interp_ fixes (#428)

* some typo fixes (#408)

* Prevent the literal string DEBUG from being appended to some messages in CMake < 3.15 (#433)

* Add function to get the currently selected channel (#451)

* Add missing board detection macros (#448)

* add board detection macros for Sparkfun & RPi Pico / VGA Board

* dma_channel_transfer_[from/to]_buffer_now: added const volatile to read_addr and volatile to write_addr (#449)

* Change the quick-start instructions to include installation of the (#92)

* added spi_get_baudrate() + some consistency changes (#395)

* Allow lengthening xosc startup delay with a compile option (#457)

* Add hardware_gpio accessors for Schmitt, slew rate, drive strength (fixes #290) (#464)

* Add some spin lock related doxygen

* Move to Tinyusb 0.10.0 (#462)

* Add usb device dpram to svd file. Fixes #351 (#465)

* Add PICO_PANIC_FUNCTION define to allow replacement of the default panic function (#463)

* Add missing DREQ_ definitions

* store actual clock frequency in clock_configure (fixes #368)

* Fix hw_is_claimed, and add xxx_is_claimed APIs

* Add some PIO irq helper methods

* Add DMA channel IRQ status getter and clear methods

* Implement the correct PIO IRQ status/clear methods (good to have methods here as the h/w interrupt registers are super confusing)

* fix pico_multicore dependencies

* add missing wrapper func __aeabi_f2d

* Further DMA/PIO IRQ API cleanup (and review fixes)

* add PICO_INT64_OPS_IN_RAM flag

* fix qtpy rp2040 uart rx rev B (#466)

* Move to tinyusb 0.10.1 (upstream tinyusb repo) ($467)

* Add gpio_set_irqover to match inover/outover/oeover (fixes #265) (#470)

Co-authored-by: Andrew Scheller <andrew.scheller@raspberrypi.com>
Co-authored-by: Christian Flach <cmfcmf.flach@gmail.com>
Co-authored-by: Luke Wren <wren6991@gmail.com>
Co-authored-by: Earle F. Philhower, III <earlephilhower@yahoo.com>
Co-authored-by: majbthrd <majbthrd@gmail.com>
Co-authored-by: Peter Lawrence <12226419+majbthrd@users.noreply.github.com>
Co-authored-by: Brian Cooke <bdscooke@gmail.com>
Co-authored-by: Scott Shawcroft <scott@tannewt.org>
Co-authored-by: Michael Stoops <spam@michaelstoops.com>
Co-authored-by: ZodiusInfuser <christopher.parrott2@gmail.com>
Co-authored-by: Kirk Benell <36707344+kirk-sfe@users.noreply.github.com>
Co-authored-by: Ha Thach <thach@tinyusb.org>
Co-authored-by: Exr0n <spotyie@gmail.com>
Co-authored-by: Joni Kähärä <joni.kahara@async.fi>
Co-authored-by: Rafael G. Martins <rafael@rafaelmartins.eng.br>
Co-authored-by: Jonathan Reichelt Gjertsen <jonath.re@gmail.com>
Co-authored-by: Martino Facchin <m.facchin@arduino.cc>
Co-authored-by: Rene <reneg973@gmail.com>
Co-authored-by: Brendan <2bndy5@gmail.com>
Co-authored-by: geurtv <48989893+geurtv@users.noreply.github.com>
Co-authored-by: ewpa <34030942+ewpa@users.noreply.github.com>
Co-authored-by: Dan Halbert <halbert@halwitz.org>
Co-authored-by: Liam Fraser <liam@raspberrypi.com>

.gitmodules

@@ -1,4 +1,3 @@
 [submodule "tinyusb"]
 	path = lib/tinyusb
-	url = https://github.com/raspberrypi/tinyusb.git
-	branch = pico
+	url = https://github.com/hathach/tinyusb.git

CMakeLists.txt

@@ -1,6 +1,10 @@
 cmake_minimum_required(VERSION 3.13)
+
+# Note: this CMakeLists.txt can be used as a top-level CMakeLists.txt for the SDK itself. For all other uses
+# it is included as a subdirectory via the pico_sdk_init() method provided by pico_sdk_init.cmake
 if (NOT TARGET _pico_sdk_inclusion_marker)
     add_library(_pico_sdk_inclusion_marker INTERFACE)
+    # This is a no-op unless we are the top-level CMakeLists.txt
     include(pico_sdk_init.cmake)
 
     project(pico_sdk C CXX ASM)
@@ -24,6 +28,7 @@ if (NOT TARGET _pico_sdk_inclusion_marker)
 
     # allow customization
     add_sub_list_dirs(PICO_SDK_PRE_LIST_DIRS)
+    add_sub_list_files(PICO_SDK_PRE_LIST_FILES)
 
     add_subdirectory(tools)
     add_subdirectory(src)
@@ -32,6 +37,7 @@ if (NOT TARGET _pico_sdk_inclusion_marker)
 
     # allow customization
     add_sub_list_dirs(PICO_SDK_POST_LIST_DIRS)
+    add_sub_list_files(PICO_SDK_POST_LIST_FILES)
 
     if (PICO_SDK_TOP_LEVEL_PROJECT AND NOT DEFINED PICO_SDK_TESTS_ENABLED)
         set(PICO_SDK_TESTS_ENABLED 1)
@@ -44,5 +50,9 @@ if (NOT TARGET _pico_sdk_inclusion_marker)
 
     # add docs at the end, as we gather documentation dirs as we go
     add_subdirectory(docs)
+
+    if (NOT PICO_SDK_TOP_LEVEL_PROJECT)
+        pico_promote_common_scope_vars()
+    endif()
 endif()
 

README.md

@@ -4,7 +4,7 @@ The Raspberry Pi Pico SDK (henceforth the SDK) provides the headers, libraries a
 necessary to write programs for the RP2040-based devices such as the Raspberry Pi Pico
 in C, C++ or assembly language.
 
-The SDK  is designed to provide an API and programming environment that is familiar both to non-embedded C developers and embedded C developers alike.
+The SDK is designed to provide an API and programming environment that is familiar both to non-embedded C developers and embedded C developers alike.
 A single program runs on the device at a time and starts with a conventional `main()` method. Standard C/C++ libraries are supported along with
 C level libraries/APIs for accessing all of the RP2040's hardware include PIO (Programmable IO).
 
@@ -38,7 +38,7 @@ instructions for other platforms, and just in general, we recommend you see [Ras
 
 1. Install CMake (at least version 3.13), and GCC cross compiler
    ```
-   sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi
+   sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib
    ```
 1. Set up your project to point to use the Raspberry Pi Pico SDK
 

cmake/pico_pre_load_toolchain.cmake

@@ -36,8 +36,8 @@ if (DEFINED PICO_COMPILER)
                 select one from \"cmake/toolchains\" folder.")
         endif ()
     endif ()
+    message("PICO compiler is ${PICO_COMPILER}")
 endif ()
 
-message("PICO compiler is ${PICO_COMPILER}")
 unset(PICO_COMPILER CACHE)
 

cmake/preload/toolchains/pico_arm_gcc.cmake

@@ -12,7 +12,7 @@ if (NOT PICO_GCC_TRIPLE)
         message("PICO_GCC_TRIPLE set from environment: $ENV{PICO_GCC_TRIPLE}")
     else()
         set(PICO_GCC_TRIPLE arm-none-eabi)
-        message("PICO_GCC_TRIPLE defaulted to arm-none-eabi")
+        #pico_message_debug("PICO_GCC_TRIPLE defaulted to arm-none-eabi")
     endif()
 endif()
 

docs/CMakeLists.txt

@@ -1,4 +1,4 @@
-find_package(Doxygen)
+find_package(Doxygen QUIET)
 if (PICO_SDK_TOP_LEVEL_PROJECT AND ${DOXYGEN_FOUND})
     set(PICO_BUILD_DOCS_DEFAULT 1)
 endif()

docs/examples.md

@@ -1,6 +1,6 @@
 ## Examples Index {#examples_page}
 
-This page links to the various example code fragments in this documentation. For more complete examples, please see the pico_examples repository, which contains complete buildable projects.
+This page links to the various example code fragments in this documentation. For more complete examples, please see the [pico-examples](https://github.com/raspberrypi/pico-examples) repository, which contains complete buildable projects.
 
  - [RTC example](@ref rtc_example)
  - [UART example](@ref uart_example)

docs/index.h

@@ -17,6 +17,7 @@
  * \defgroup hardware_clocks hardware_clocks
  * \defgroup hardware_divider hardware_divider
  * \defgroup hardware_dma hardware_dma
+ * \defgroup hardware_exception hardware_exception
  * \defgroup hardware_flash hardware_flash
  * \defgroup hardware_gpio hardware_gpio
  * \defgroup hardware_i2c hardware_i2c

docs/mainpage.md

@@ -25,7 +25,6 @@ The SDK builds an executable which is bare metal, i.e. it includes the entirety
 ## Examples
 
 
-This SDK contains a number of example code fragments. An index of these examples can be found [here](@ref examples_page)
-
+This SDK documentation contains a number of example code fragments. An index of these examples can be found [here](@ref examples_page). These examples, and any other source code included in this documentation, is Copyright © 2020 Raspberry Pi (Trading) Ltd. and licensed under the [3-Clause BSD](https://opensource.org/licenses/BSD-3-Clause) license.
 
 

pico_sdk_init.cmake

@@ -1,54 +1,94 @@
-# Initialize the Raspberry Pi Pico SDK
+# Pre-initialize the Raspberry Pi Pico SDK, setting up the platform and toolchain and some CMake utility functions
 # This file must be included prior to the project() call
 
-if (_PICO_SDK_INIT)
-    return()
-endif ()
-set(_PICO_SDK_INIT 1)
+# Note: this file is perhaps named badly, as it provides a method pico_sdk_init which
+# the enclosing project calls LATER to actually "initialize" the SDK (by including the CMakeLists.txt from this
+# same directory)
 
-function(pico_is_top_level_project VAR)
-    string(TOLOWER ${CMAKE_CURRENT_LIST_DIR} __list_dir)
-    string(TOLOWER ${CMAKE_SOURCE_DIR} __source_dir)
-    if (__source_dir STREQUAL __list_dir)
-        set(${VAR} 1 PARENT_SCOPE)
-    else()
-        set(${VAR} 0 PARENT_SCOPE)
-    endif()
-endfunction()
+if (NOT TARGET _pico_sdk_pre_init_marker)
+    add_library(_pico_sdk_pre_init_marker INTERFACE)
 
-if (NOT PICO_SDK_PATH)
-    set(PICO_SDK_PATH ${CMAKE_CURRENT_LIST_DIR})
-endif ()
+    function(pico_is_top_level_project VAR)
+        string(TOLOWER ${CMAKE_CURRENT_LIST_DIR} __list_dir)
+        string(TOLOWER ${CMAKE_SOURCE_DIR} __source_dir)
+        if (__source_dir STREQUAL __list_dir)
+            set(${VAR} 1 PARENT_SCOPE)
+        else()
+            set(${VAR} 0 PARENT_SCOPE)
+        endif()
+    endfunction()
 
-get_filename_component(PICO_SDK_PATH "${PICO_SDK_PATH}" REALPATH BASE_DIR "${CMAKE_BINARY_DIR}")
+    function(pico_message_debug MESSAGE)
+        # The log-level system was added in CMake 3.15.
+        if(${CMAKE_VERSION} VERSION_LESS "3.15.0")
+            message(${MESSAGE})
+        else()
+            message(DEBUG ${MESSAGE})
+        endif()
+    endfunction()
 
-set(PICO_SDK_PATH ${CMAKE_CURRENT_LIST_DIR} CACHE PATH "Path to the Raspberry Pi Pico SDK" FORCE)
+    if (NOT PICO_SDK_PATH)
+        set(PICO_SDK_PATH ${CMAKE_CURRENT_LIST_DIR})
+    endif ()
 
-list(APPEND CMAKE_MODULE_PATH ${PICO_SDK_PATH}/cmake)
+    get_filename_component(PICO_SDK_PATH "${PICO_SDK_PATH}" REALPATH BASE_DIR "${CMAKE_BINARY_DIR}")
 
-include(${CMAKE_CURRENT_LIST_DIR}/pico_sdk_version.cmake)
-include(pico_utils)
+    set(PICO_SDK_PATH ${CMAKE_CURRENT_LIST_DIR} CACHE PATH "Path to the Raspberry Pi Pico SDK" FORCE)
 
-message("PICO_SDK_PATH is ${CMAKE_CURRENT_LIST_DIR}")
+    list(APPEND CMAKE_MODULE_PATH ${PICO_SDK_PATH}/cmake)
 
-include(pico_pre_load_platform)
+    include(${CMAKE_CURRENT_LIST_DIR}/pico_sdk_version.cmake)
+    include(pico_utils)
 
-# todo perhaps this should be included by the platform instead?
-# We want to configure correct toolchain prior to project load
-include(pico_pre_load_toolchain)
+    message("PICO_SDK_PATH is ${CMAKE_CURRENT_LIST_DIR}")
 
-macro(pico_sdk_init)
-    if (NOT CMAKE_PROJECT_NAME)
-        message(WARNING "pico_sdk_init() should be called after the project is created (and languages added)")
-    endif()
-    add_subdirectory(${PICO_SDK_PATH} pico-sdk)
-endmacro()
+    include(pico_pre_load_platform)
 
-macro(add_sub_list_dirs var)
-    foreach(LIST_DIR IN LISTS ${var})
-        get_filename_component(SHORT_NAME "${LIST_DIR}" NAME)
-        message("Including custom CMakeLists.txt ${SHORT_NAME}")
-        add_subdirectory(${LIST_DIR} ${SHORT_NAME})
-    endforeach()
-endmacro()
+    # We want to configure correct toolchain prior to project load
+    # todo perhaps this should be included by the platform instead?
+    include(pico_pre_load_toolchain)
 
+    macro(pico_sdk_init)
+        if (NOT CMAKE_PROJECT_NAME)
+            message(WARNING "pico_sdk_init() should be called after the project is created (and languages added)")
+        endif()
+        add_subdirectory(${PICO_SDK_PATH} pico-sdk)
+        pico_is_top_level_project(ISTOP)
+    endmacro()
+
+    macro(add_sub_list_dirs var)
+        foreach(LIST_DIR IN LISTS ${var})
+            get_filename_component(SHORT_NAME "${LIST_DIR}" NAME)
+            pico_message_debug("Including custom CMakeLists.txt ${SHORT_NAME}")
+            add_subdirectory(${LIST_DIR} ${SHORT_NAME})
+        endforeach()
+    endmacro()
+
+    macro(add_sub_list_files var)
+        foreach(LIST_FILE IN LISTS ${var})
+            pico_message_debug("Including custom CMake file ${LIST_FILE}")
+            include(${LIST_FILE})
+        endforeach()
+    endmacro()
+
+    macro(pico_register_common_scope_var NAME)
+        if (NOT ${NAME} IN_LIST PICO_PROMOTE_COMMON_SCOPE_VARS)
+            list(APPEND PICO_PROMOTE_COMMON_SCOPE_VARS ${NAME})
+        endif()
+    endmacro()
+
+    set(PICO_PROMOTE_COMMON_SCOPE_VARS
+            PICO_INCLUDE_DIRS
+            PICO_SDK_POST_LIST_DIRS
+            PICO_SDK_POST_LIST_FILES
+            PICO_CONFIG_HEADER_FILES
+            PICO_RP2040_CONFIG_HEADER_FILES
+    )
+
+    macro(pico_promote_common_scope_vars)
+        set(PICO_PROMOTE_COMMON_SCOPE_VARS ${PICO_PROMOTE_COMMON_SCOPE_VARS} PARENT_SCOPE)
+        foreach(VAR IN LISTS PICO_PROMOTE_COMMON_SCOPE_VARS)
+            SET(${VAR} ${${VAR}} PARENT_SCOPE)
+        endforeach()
+    endmacro()
+endif()

pico_sdk_version.cmake

@@ -3,13 +3,12 @@
 set(PICO_SDK_VERSION_MAJOR 1)
 # PICO_BUILD_DEFINE: PICO_SDK_VERSION_MINOR, SDK minor version number, type=int, group=pico_base
 # PICO_CONFIG: PICO_SDK_VERSION_MINOR, SDK minor version number, type=int, group=pico_base
-set(PICO_SDK_VERSION_MINOR 1)
+set(PICO_SDK_VERSION_MINOR 2)
 # PICO_BUILD_DEFINE: PICO_SDK_VERSION_REVISION, SDK version revision, type=int, group=pico_base
 # PICO_CONFIG: PICO_SDK_VERSION_REVISION, SDK version revision, type=int, group=pico_base
-set(PICO_SDK_VERSION_REVISION 2)
+set(PICO_SDK_VERSION_REVISION 0)
 # PICO_BUILD_DEFINE: PICO_SDK_VERSION_PRE_RELEASE_ID, optional SDK pre-release version identifier, type=string, group=pico_base
 # PICO_CONFIG: PICO_SDK_VERSION_PRE_RELEASE_ID, optional SDK pre-release version identifier, type=string, group=pico_base
-#set(PICO_SDK_VERSION_PRE_RELEASE_ID develop)
 
 # PICO_BUILD_DEFINE: PICO_SDK_VERSION_STRING, SDK version, type=string, group=pico_base
 # PICO_CONFIG: PICO_SDK_VERSION_STRING, SDK version, type=string, group=pico_base

src/CMakeLists.txt

@@ -11,23 +11,28 @@ if (NOT EXISTS "${PICO_PLATFORM_CMAKE_FILE}")
     Either specify a valid PICO_PLATFORM (or PICO_PLATFORM_CMAKE_FILE).")
 endif ()
 
+# Initialize board related build/compile settings
 include(${CMAKE_CURRENT_LIST_DIR}/board_setup.cmake)
 
-# todo add option to disable skip flag
+# call add_subdirectory(subdir) unless SKIP_SUBDIR evaluates to true
 function(pico_add_subdirectory subdir)
+    # todo add option to disable skip flag
     string(TOUPPER ${subdir} subdir_upper)
     set(replace_flag SKIP_${subdir_upper})
     if (NOT ${replace_flag})
         add_subdirectory(${subdir})
     else ()
         message("Not including ${subdir} because ${replace_flag} defined.")
     endif ()
+    pico_promote_common_scope_vars()
 endfunction()
 
+# add a link option to wrap the given function name; i.e. -Wl:wrap=FUNCNAME for gcc
 function(pico_wrap_function TARGET FUNCNAME)
     target_link_options(${TARGET} INTERFACE "LINKER:--wrap=${FUNCNAME}")
 endfunction()
 
+# add map file generation for the given target
 function(pico_add_map_output TARGET)
     get_target_property(target_type ${TARGET} TYPE)
     if ("EXECUTABLE" STREQUAL "${target_type}")
@@ -37,11 +42,23 @@ function(pico_add_map_output TARGET)
     endif ()
 endfunction()
 
+# create a hardware_NAME_headers target (see pico_pico_simple_hardware_headers_target)
+# create a hardware_NAME target (see pico_pico_simple_hardware_target)
 macro(pico_simple_hardware_target NAME)
     pico_simple_hardware_headers_target(${NAME})
     pico_simple_hardware_impl_target(${NAME})
 endmacro()
 
+# create an INTERFACE library named target, and define LIB_TARGET=1 (upper case) as a compile option
+function(pico_add_impl_library target)
+    add_library(${target} INTERFACE)
+    string(TOUPPER ${target} TARGET_UPPER)
+    target_compile_definitions(${target} INTERFACE LIB_${TARGET_UPPER}=1)
+endfunction()
+
+# create an INTERFACE library named hardware_NAME_headers INTERFACE library if it doesn't already exist,
+#        and add include/ relative to the calling directory to the includes.
+#        and hardware_structs and hardware_claim as dependencies of the library
 macro(pico_simple_hardware_headers_target NAME)
     if (NOT TARGET hardware_${NAME}_headers)
         add_library(hardware_${NAME}_headers INTERFACE)
@@ -54,8 +71,15 @@ macro(pico_simple_hardware_headers_target NAME)
     endif()
 endmacro()
 
+# create an INTERFACE library named hardware_NAME if it doesn't exist, along with a hardware_NAME_headers
+#        INTERFACE library that it depends on. The hardware_NAME_headers library add include/ relative to
+#        and pico_base_headers, and harddware_structs as a dependency of the library
 macro(pico_simple_hardware_headers_only_target NAME)
     if (NOT TARGET hardware_${NAME})
+        # Choosing not to add LIB_HARDWARE_ defines to avoid command line bloat pending a need (they aren't
+        #   super interesting except to determine functionality as they are mostly passive accessors, however
+        #   they could be useful to determine if the header is available.
+        # pico_add_sdk_impl_library(hardware_${NAME})
         add_library(hardware_${NAME} INTERFACE)
 
         target_include_directories(hardware_${NAME} INTERFACE ${CMAKE_CURRENT_LIST_DIR}/include)
@@ -66,8 +90,14 @@ macro(pico_simple_hardware_headers_only_target NAME)
     endif()
 endmacro()
 
+# create an INTERFACE library named hardware_NAME if it doesn't exist, dependent on a pre-existing  hardware_NAME_headers
+#        INTERFACE library and pico_platform. The file NAME.c relative to the caller is added to the C sources for the hardware_NAME
 macro(pico_simple_hardware_impl_target NAME)
     if (NOT TARGET hardware_${NAME})
+        # Choosing not to add LIB_HARDWARE_ defines to avoid command line bloat pending a need (they aren't
+        #   super interesting except to determine functionality as they are mostly passive accessors, however
+        #   they could be useful to determine if the header is available.
+        # pico_add_sdk_impl_library(hardware_${NAME})
         add_library(hardware_${NAME} INTERFACE)
 
         target_sources(hardware_${NAME} INTERFACE
@@ -86,4 +116,6 @@ function(pico_add_doxygen_exclude SOURCE_DIR)
     set(PICO_DOXYGEN_EXCLUDE_PATHS "${PICO_DOXYGEN_EXCLUDE_PATHS} ${SOURCE_DIR}" CACHE INTERNAL "")
 endfunction()
 
-include(${PICO_PLATFORM_CMAKE_FILE})
+include(${PICO_PLATFORM_CMAKE_FILE})
+
+pico_promote_common_scope_vars()

src/boards/include/boards/adafruit_feather_rp2040.h

@@ -15,6 +15,11 @@
 // For board detection
 #define ADAFRUIT_FEATHER_RP2040
 
+// On some samples, the xosc can take longer to stabilize than is usual
+#ifndef PICO_XOSC_STARTUP_DELAY_MULTIPLIER
+#define PICO_XOSC_STARTUP_DELAY_MULTIPLIER 64
+#endif
+
 //------------- UART -------------//
 #ifndef PICO_DEFAULT_UART
 #define PICO_DEFAULT_UART 0

src/boards/include/boards/adafruit_itsybitsy_rp2040.h

@@ -15,6 +15,11 @@
 // For board detection
 #define ADAFRUIT_ITSYBITSY_RP2040
 
+// On some samples, the xosc can take longer to stabilize than is usual
+#ifndef PICO_XOSC_STARTUP_DELAY_MULTIPLIER
+#define PICO_XOSC_STARTUP_DELAY_MULTIPLIER 64
+#endif
+
 //------------- UART -------------//
 #ifndef PICO_DEFAULT_UART
 #define PICO_DEFAULT_UART 0
@@ -80,7 +85,7 @@
 #endif
 
 #ifndef PICO_FLASH_SIZE_BYTES
-#define PICO_FLASH_SIZE_BYTES (4 * 1024 * 1024)
+#define PICO_FLASH_SIZE_BYTES (8 * 1024 * 1024)
 #endif
 
 // All boards have B1 RP2040