Merge pull request #472 from raspberrypi/release.1.2.0

SDK 1.2.0 release; see release notes for details

.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