Merge 171daf787eab618ed0433e26d3ae6eb4b712047f into 65a8907828ad87acd6a8e3363f175a64337b65cd

src/cmake/on_device.cmake

@@ -15,16 +15,22 @@ function(pico_get_runtime_output_directory TARGET output_path_name)
     set(${output_path_name} ${output_path} PARENT_SCOPE)
 endfunction()
 
+# pico_add_hex_output(TARGET)
+# Generate a hex file for the target
 function(pico_add_hex_output TARGET)
     pico_get_runtime_output_directory(${TARGET} output_path)
     add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_OBJCOPY} -Oihex $<TARGET_FILE:${TARGET}> ${output_path}$<IF:$<BOOL:$<TARGET_PROPERTY:${TARGET},OUTPUT_NAME>>,$<TARGET_PROPERTY:${TARGET},OUTPUT_NAME>,$<TARGET_PROPERTY:${TARGET},NAME>>.hex VERBATIM)
 endfunction()
 
+# pico_add_bin_output(TARGET)
+# Generate a bin file for the target
 function(pico_add_bin_output TARGET)
     pico_get_runtime_output_directory(${TARGET} output_path)
     add_custom_command(TARGET ${TARGET} POST_BUILD COMMAND ${CMAKE_OBJCOPY} -Obinary $<TARGET_FILE:${TARGET}> ${output_path}$<IF:$<BOOL:$<TARGET_PROPERTY:${TARGET},OUTPUT_NAME>>,$<TARGET_PROPERTY:${TARGET},OUTPUT_NAME>,$<TARGET_PROPERTY:${TARGET},NAME>>.bin VERBATIM)
 endfunction()
 
+# pico_add_dis_output(TARGET)
+# Generate a disassembly file for the target
 function(pico_add_dis_output TARGET)
     pico_get_runtime_output_directory(${TARGET} output_path)
 
@@ -45,6 +51,8 @@ function(pico_add_dis_output TARGET)
             )
 endfunction()
 
+# pico_add_extra_outputs(TARGET)
+# Perform picotool processing and add disassembly, hex, bin, map, and uf2 outputs for the target
 function(pico_add_extra_outputs TARGET)
     # Disassembly will be nonsense for encrypted binaries,
     # so disassemble before picotool processing

src/common/pico_binary_info/CMakeLists.txt

@@ -9,11 +9,15 @@ endif()
 
 target_link_libraries(pico_binary_info INTERFACE pico_binary_info_headers)
 
+# pico_set_program_name(TARGET name)
+# Set the program name for the target
 function(pico_set_program_name TARGET name)
     # PICO_BUILD_DEFINE: PICO_PROGRAM_NAME, value passed to pico_set_program_name, type=string, group=pico_binary_info
     target_compile_definitions(${TARGET} PRIVATE -DPICO_PROGRAM_NAME="${name}")
 endfunction()
 
+# pico_set_program_description(TARGET description)
+# Set the program description for the target
 function(pico_set_program_description TARGET description)
     # since this is the command line, we will remove newlines
     string(REPLACE "\n" " " description ${description})
@@ -22,11 +26,15 @@ function(pico_set_program_description TARGET description)
     target_compile_definitions(${TARGET} PRIVATE -DPICO_PROGRAM_DESCRIPTION="${description}")
 endfunction()
 
+# pico_set_program_url(TARGET url)
+# Set the program URL for the target
 function(pico_set_program_url TARGET url)
     # PICO_BUILD_DEFINE: PICO_PROGRAM_URL, value passed to pico_set_program_url, type=string, group=pico_binary_info
     target_compile_definitions(${TARGET} PRIVATE -DPICO_PROGRAM_URL="${url}")
 endfunction()
 
+# pico_set_program_version(TARGET version)
+# Set the program version for the target
 function(pico_set_program_version TARGET version)
     # PICO_BUILD_DEFINE: PICO_PROGRAM_VERSION_STRING, value passed to pico_set_program_version, type=string, group=pico_binary_info
     target_compile_definitions(${TARGET} PRIVATE -DPICO_PROGRAM_VERSION_STRING="${version}")

src/rp2040/boot_stage2/CMakeLists.txt

@@ -33,7 +33,9 @@ set(PICO_BOOT_STAGE2_DIR "${CMAKE_CURRENT_LIST_DIR}" CACHE INTERNAL "")
 pico_add_library(boot_stage2_headers)
 target_include_directories(boot_stage2_headers SYSTEM INTERFACE ${CMAKE_CURRENT_LIST_DIR}/include)
 
-# by convention the first source file name without extension is used for the binary info name
+# pico_define_boot_stage2(NAME SOURCES)
+# Define a boot stage 2 target.
+# By convention the first source file name without extension is used for the binary info name
 function(pico_define_boot_stage2 NAME SOURCES)
     add_executable(${NAME}
             ${SOURCES}
@@ -97,6 +99,7 @@ endmacro()
 
 pico_define_boot_stage2(bs2_default ${PICO_DEFAULT_BOOT_STAGE2_FILE})
 
+# pico_clone_default_boot_stage2(NAME)
 # Create a new boot stage 2 target using the default implementation for the current build (PICO_BOARD derived)
 function(pico_clone_default_boot_stage2 NAME)
     pico_define_boot_stage2(${NAME} ${PICO_DEFAULT_BOOT_STAGE2_FILE})

src/rp2350/boot_stage2/CMakeLists.txt

@@ -33,7 +33,9 @@ set(PICO_BOOT_STAGE2_DIR "${CMAKE_CURRENT_LIST_DIR}" CACHE INTERNAL "")
 pico_add_library(boot_stage2_headers)
 target_include_directories(boot_stage2_headers SYSTEM INTERFACE ${CMAKE_CURRENT_LIST_DIR}/include)
 
-# by convention the first source file name without extension is used for the binary info name
+# pico_define_boot_stage2(NAME SOURCES)
+# Define a boot stage 2 target.
+# By convention the first source file name without extension is used for the binary info name
 function(pico_define_boot_stage2 NAME SOURCES)
     add_executable(${NAME}
             ${SOURCES}
@@ -97,6 +99,7 @@ endmacro()
 
 pico_define_boot_stage2(bs2_default ${PICO_DEFAULT_BOOT_STAGE2_FILE})
 
+# pico_clone_default_boot_stage2(NAME)
 # Create a new boot stage 2 target using the default implementation for the current build (PICO_BOARD derived)
 function(pico_clone_default_boot_stage2 NAME)
     pico_define_boot_stage2(${NAME} ${PICO_DEFAULT_BOOT_STAGE2_FILE})

src/rp2_common/pico_btstack/CMakeLists.txt

@@ -302,8 +302,9 @@ if (EXISTS ${PICO_BTSTACK_PATH}/${BTSTACK_TEST_PATH})
 
     pico_promote_common_scope_vars()
 
-    # Make a GATT header file from a BTstack GATT file
-    # Pass the target library name library type and path to the GATT input file
+    # pico_btstack_make_gatt_header(TARGET_LIB TARGET_TYPE GATT_FILE)
+    # Make a GATT header file from a BTstack GATT file.
+    # Pass the target library name, library type, and path to the GATT input file.
     # To add additional directories to the gatt #import path, add them to the end of the argument list.
     function(pico_btstack_make_gatt_header TARGET_LIB TARGET_TYPE GATT_FILE)
             find_package (Python3 REQUIRED COMPONENTS Interpreter)

src/rp2_common/pico_cyw43_driver/CMakeLists.txt

@@ -131,15 +131,15 @@ if (EXISTS ${PICO_CYW43_DRIVER_PATH}/${CYW43_DRIVER_TEST_FILE})
                 )
     endif()
 
-    # Set an ip address in a compile definition
-    # target name, target type, compile definition name to set then address in a string
-    # This can be used to set the following compile definitions
-    # CYW43_DEFAULT_IP_STA_ADDRESS
-    # CYW43_DEFAULT_IP_STA_GATEWAY
-    # CYW43_DEFAULT_IP_AP_ADDRESS
-    # CYW43_DEFAULT_IP_AP_GATEWAY
-    # CYW43_DEFAULT_IP_MASK
-    # CYW43_DEFAULT_IP_DNS
+    # pico_configure_ip4_address(TARGET_LIB TARGET_TYPE DEF_NAME IP_ADDRESS_STR)
+    # Set an ip address in a compile definition;
+    # This can be used to set the following compile definitions;
+    # CYW43_DEFAULT_IP_STA_ADDRESS;
+    # CYW43_DEFAULT_IP_STA_GATEWAY;
+    # CYW43_DEFAULT_IP_AP_ADDRESS;
+    # CYW43_DEFAULT_IP_AP_GATEWAY;
+    # CYW43_DEFAULT_IP_MASK;
+    # CYW43_DEFAULT_IP_DNS;
     # e.g. pico_configure_ip4_address(picow_tcpip_server_background PRIVATE CYW43_DEFAULT_IP_STA_ADDRESS "10.3.15.204")
     function(pico_configure_ip4_address TARGET_LIB TARGET_TYPE DEF_NAME IP_ADDRESS_STR)
             string(REGEX MATCHALL "[0-9]+" IP_ADDRESS_LIST ${IP_ADDRESS_STR})

src/rp2_common/pico_lwip/tools/CMakeLists.txt

@@ -1,5 +1,6 @@
-# Compile the http content into a source file "pico_fsdata.inc" in a format suitable for the lwip httpd server
-# Pass the target library name library type and the list of httpd content
+# pico_set_lwip_httpd_content(TARGET_LIB TARGET_TYPE HTTPD_FILES...)
+# Compile the http content into a source file "pico_fsdata.inc" in a format suitable for the lwip httpd server.
+# Pass the target library name library type and the list of httpd content files to compile.
 function(pico_set_lwip_httpd_content TARGET_LIB TARGET_TYPE)
     find_package (Python3 REQUIRED COMPONENTS Interpreter)
     set(HTTPD_CONTENT_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/generated")

src/rp2_common/pico_runtime/CMakeLists.txt

@@ -51,22 +51,22 @@ elseif (PICO_C_COMPILER_IS_CLANG)
    # target_link_options(pico_runtime INTERFACE "-nostdlib")
 endif()
 
-# pico_minimize_runtime((INCLUDE ...) (EXCLUDE ...))
+# pico_minimize_runtime([INCLUDE ...] [EXCLUDE ...])
 #
 # INCLUDE/EXCLUDE can contain any of the following (all defaulting to not included)
 #
-# DEFAULT_ALARM_POOL    - default alarm pool setup
-# PRINTF                - full printf support
-# PRINTF_MINIMAL        - printf support without the following
-# PRINTF_FLOAT          - to control float support if printf is enabled
-# PRINTF_EXPONENTIAL
-# PRINTF_LONG_LONG
-# PRINTF_PTRDIFF_T
-# FLOAT                 - support for single-precision floating point
-# DOUBLE                - support for double-precision floating point
-# FPGA_CHECK            - checks for FPGA which allows Raspberry Pi to run your binary on FPGA
-# PANIC                 - default panic impl which brings in stdio
-# AUTO_INIT_MUTEX       - auto init mutexes; without this you get no printf mutex either               -
+# DEFAULT_ALARM_POOL    - default alarm pool setup;
+# PRINTF                - full printf support;
+# PRINTF_MINIMAL        - printf support without the following;
+# PRINTF_FLOAT          - to control float support if printf is enabled;
+# PRINTF_EXPONENTIAL    - to control exponential support if printf is enabled;
+# PRINTF_LONG_LONG      - to control long long support if printf is enabled;
+# PRINTF_PTRDIFF_T      - to control ptrdiff_t support if printf is enabled;
+# FLOAT                 - support for single-precision floating point;
+# DOUBLE                - support for double-precision floating point;
+# FPGA_CHECK            - checks for FPGA which allows Raspberry Pi to run your binary on FPGA;
+# PANIC                 - default panic impl which brings in stdio;
+# AUTO_INIT_MUTEX       - auto init mutexes, without this you get no printf mutex either;
 function(pico_minimize_runtime TARGET)
     set(ALL_ITEMS
             DEFAULT_ALARM_POOL

src/rp2_common/pico_standard_link/CMakeLists.txt

@@ -5,6 +5,8 @@ if (NOT TARGET pico_standard_link)
         target_link_libraries(pico_standard_link INTERFACE boot_stage2_headers)
     endif()
 
+    # pico_add_link_depend(TARGET dependency)
+    # Add a link time dependency to the target
     function(pico_add_link_depend TARGET dependency)
         get_target_property(target_type ${TARGET} TYPE)
         if (${target_type} STREQUAL "INTERFACE_LIBRARY")
@@ -21,11 +23,14 @@ if (NOT TARGET pico_standard_link)
         set_target_properties(${TARGET} PROPERTIES ${PROP} "${_LINK_DEPENDS}")
     endfunction()
 
-    # need this because cmake does not appear to have a way to override an INTERFACE variable
+    # pico_set_linker_script(TARGET LDSCRIPT)
+    # Set the linker script for the target
     function(pico_set_linker_script TARGET LDSCRIPT)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_LINKER_SCRIPT ${LDSCRIPT})
     endfunction()
 
+    # pico_set_binary_type(TARGET TYPE)
+    # Set the binary type for the target
     function(pico_set_binary_type TARGET TYPE)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_BINARY_TYPE ${TYPE})
     endfunction()

src/rp2_common/pico_stdio/CMakeLists.txt

@@ -26,18 +26,26 @@ if (NOT TARGET pico_stdio)
         pico_mirrored_target_link_libraries(pico_stdio INTERFACE pico_printf)
     endif()
 
+    # pico_enable_stdio_uart(TARGET ENABLED)
+    # Enable stdio UART for the target
     function(pico_enable_stdio_uart TARGET ENABLED)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_STDIO_UART ${ENABLED})
     endfunction()
 
+    # pico_enable_stdio_usb(TARGET ENABLED)
+    # Enable stdio USB for the target
     function(pico_enable_stdio_usb TARGET ENABLED)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_STDIO_USB ${ENABLED})
     endfunction()
 
+    # pico_enable_stdio_semihosting(TARGET ENABLED)
+    # Enable stdio semi-hosting for the target
     function(pico_enable_stdio_semihosting TARGET ENABLED)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_STDIO_SEMIHOSTING ${ENABLED})
     endfunction()
 
+    # pico_enable_stdio_rtt(TARGET ENABLED)
+    # Enable stdio RTT for the target
     function(pico_enable_stdio_rtt TARGET ENABLED)
         set_target_properties(${TARGET} PROPERTIES PICO_TARGET_STDIO_RTT ${ENABLED})
     endfunction()

tools/CMakeLists.txt

@@ -175,13 +175,14 @@ function(picotool_check_default_keys TARGET)
     picotool_compare_keys(${TARGET} ${picotool_enc_sigfile} private.pem "encrypted signing")
 endfunction()
 
+# pico_generate_pio_header(TARGET PIO_FILES... [OUTPUT_FORMAT <format>] [OUTPUT_DIR <dir>])
 # Generate pio header and include it in the build
-# PICO_CMAKE_CONFIG: PICO_DEFAULT_PIOASM_OUTPUT_FORMAT, Default output format used by pioasm when using pico_generate_pio_header, type=string, default=c-sdk, group=build
 function(pico_generate_pio_header TARGET)
     pico_init_pioasm()
     # Note that PATH is not a valid argument but was previously ignored (and happens to be passed by pico-extras)
     cmake_parse_arguments(pico_generate_pio_header "" "OUTPUT_FORMAT;OUTPUT_DIR;PATH" "" ${ARGN} )
 
+    # PICO_CMAKE_CONFIG: PICO_DEFAULT_PIOASM_OUTPUT_FORMAT, Default output format used by pioasm when using pico_generate_pio_header, type=string, default=c-sdk, group=build
     if (pico_generate_pio_header_OUTPUT_FORMAT)
         set(OUTPUT_FORMAT "${pico_generate_pio_header_OUTPUT_FORMAT}")
     elseif(DEFINED PICO_DEFAULT_PIOASM_OUTPUT_FORMAT)
@@ -233,6 +234,7 @@ endfunction()
 # Package a UF2 output to be written to the PACKADDR address. This can be
 # used with a no_flash binary to write the UF2 to flash when dragging &
 # dropping, and it will be copied to SRAM by the bootrom before execution.
+#
 # This sets PICOTOOL_UF2_PACKAGE_ADDR to PACKADDR.
 function(pico_package_uf2_output TARGET PACKADDR)
     picotool_check_configurable(${TARGET})
@@ -243,6 +245,7 @@ endfunction()
 
 # pico_set_otp_key_output_file(TARGET OTPFILE)
 # Output the public key hash and other necessary rows to an otp JSON file.
+#
 # This sets PICOTOOL_OTP_FILE to OTPFILE.
 function(pico_set_otp_key_output_file TARGET OTPFILE)
     picotool_check_configurable(${TARGET})
@@ -253,8 +256,9 @@ endfunction()
 
 # pico_load_map_clear_sram(TARGET)
 # Adds an entry to the load map to instruct the bootrom to clear all of SRAM
-# before loading the binary. This appends the `--clear` argument
-# to PICOTOOL_EXTRA_PROCESS_ARGS.
+# before loading the binary.
+#
+# This appends the `--clear` argument to PICOTOOL_EXTRA_PROCESS_ARGS.
 function(pico_load_map_clear_sram TARGET)
     picotool_check_configurable(${TARGET})
     # get and set, to inherit list
@@ -270,9 +274,11 @@ endfunction()
 
 # pico_set_binary_version(<TARGET> [MAJOR <version>] [MINOR <version>] [ROLLBACK <version>] [ROLLBACK_ROWS <rows...>])
 # Adds a version item to the metadata block, with the given major, minor and
-# rollback version, along with the rollback rows. These are appended as arguments
-# to PICOTOOL_EXTRA_PROCESS_ARGS if setting the rollback version, or set as compile
-# definitions if only setting the major/minor versions.
+# rollback version, along with the rollback rows.
+#
+# These are appended as arguments to PICOTOOL_EXTRA_PROCESS_ARGS if setting the
+# rollback version, or set as compile definitions if only setting the major/minor
+# versions.
 function(pico_set_binary_version TARGET)
     picotool_check_configurable(${TARGET})
     set(oneValueArgs MAJOR MINOR ROLLBACK)
@@ -322,6 +328,7 @@ endfunction()
 
 # pico_set_uf2_family(TARGET FAMILY)
 # Set the UF2 family to use when creating the UF2.
+#
 # This sets PICOTOOL_UF2_FAMILY to FAMILY.
 function(pico_set_uf2_family TARGET FAMILY)
     picotool_check_configurable(${TARGET})
@@ -331,10 +338,12 @@ function(pico_set_uf2_family TARGET FAMILY)
 endfunction()
 
 # pico_sign_binary(TARGET [SIGFILE])
-# Sign the target binary with the given PEM signature. This sets
-# PICOTOOL_SIGN_OUTPUT to true, PICOTOOL_SIGFILE to SIGFILE (if specified),
-# and PICOTOOL_OTP_FILE to ${TARGET}.otp.json (if not already set). To
-# specify a common SIGFILE for multiple targets, the SIGFILE property can be
+# Sign the target binary with the given PEM signature.
+#
+# This sets PICOTOOL_SIGN_OUTPUT to true, PICOTOOL_SIGFILE to SIGFILE (if
+# specified), and PICOTOOL_OTP_FILE to ${TARGET}.otp.json (if not already set).
+#
+# To specify a common SIGFILE for multiple targets, the SIGFILE property can be
 # set for a given scope, and then the SIGFILE argument is optional.
 function(pico_sign_binary TARGET)
     picotool_check_configurable(${TARGET})
@@ -361,7 +370,9 @@ function(pico_sign_binary TARGET)
 endfunction()
 
 # pico_hash_binary(TARGET)
-# Hash the target binary. This sets PICOTOOL_HASH_OUTPUT to true.
+# Hash the target binary.
+#
+# This sets PICOTOOL_HASH_OUTPUT to true.
 function(pico_hash_binary TARGET)
     picotool_check_configurable(${TARGET})
     # Enforce hashing through target properties
@@ -372,7 +383,9 @@ endfunction()
 
 # pico_embed_pt_in_binary(TARGET PTFILE)
 # Create the specified partition table from JSON, and embed it in the
-# block loop. This sets PICOTOOL_EMBED_PT to PTFILE.
+# block loop.
+#
+# This sets PICOTOOL_EMBED_PT to PTFILE.
 function(pico_embed_pt_in_binary TARGET PTFILE)
     picotool_check_configurable(${TARGET})
     set_target_properties(${TARGET} PROPERTIES

tools/extract_cmake_functions.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2025 Raspberry Pi (Trading) Ltd.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+#
+#
+# Script to scan the Raspberry Pi Pico SDK tree searching for CMake functions
+# Outputs a tab separated file of the function:
+# name	signature	description	group
+#
+# Usage:
+#
+# tools/extract_cmake_functions.py <root of repo> [output file]
+#
+# If not specified, output file will be `pico_cmake_functions.tsv`
+
+
+import os
+import sys
+import re
+import csv
+import logging
+
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+scandir = sys.argv[1]
+outfile = sys.argv[2] if len(sys.argv) > 2 else 'pico_cmake_functions.tsv'
+
+CMAKE_FUNCTION_RE = re.compile(r'^\s*#(.*)((\n\s*#.*)*)\n\s*function\(([^\s]*)', re.MULTILINE)
+
+CMAKE_PICO_FUNCTIONS_RE = re.compile(r'^\s*function\((pico_[^\s\)]*)', re.MULTILINE)
+
+# Files containing internal functions that don't need to be documented publicly
+skip_files = set([
+    "pico_sdk_init.cmake",
+    "pico_utils.cmake",
+    "no_hardware.cmake",
+    "find_compiler.cmake",
+])
+
+skip_groups = set([
+    "src",  # skip the root src/CMakeLists.txt
+])
+
+# Other internal functions that don't need to be documented publicly
+allowed_missing_functions = set([
+    "pico_init_pioasm",
+    "pico_init_picotool",
+    "pico_add_platform_library",
+    "pico_get_runtime_output_directory",
+    "pico_set_printf_implementation",
+    "pico_expand_pico_platform",
+])
+
+all_functions = {}
+
+
+# Scan all CMakeLists.txt and .cmake files in the specific path, recursively.
+
+for dirpath, dirnames, filenames in os.walk(scandir):
+    for filename in filenames:
+        if filename in skip_files:
+            continue
+        group = os.path.basename(dirpath)
+        if group in skip_groups:
+            continue
+        file_ext = os.path.splitext(filename)[1]
+        if filename == 'CMakeLists.txt' or file_ext == '.cmake':
+            file_path = os.path.join(dirpath, filename)
+
+            with open(file_path, encoding="ISO-8859-1") as fh:
+                text = fh.read()
+                for match in CMAKE_FUNCTION_RE.finditer(text):
+                    name = match.group(4)
+                    signature = match.group(1).strip()
+                    description = match.group(2)
+                    description = description.replace('#', '').strip()
+                    if signature.startswith(name):
+                        all_functions[name] = (signature, description, group)
+
+                for match in CMAKE_PICO_FUNCTIONS_RE.finditer(text):
+                    name = match.group(1)
+                    if name not in all_functions and name not in allowed_missing_functions:
+                        logger.warning("{} function has no description in {}".format(name, file_path))
+
+
+with open(outfile, 'w', newline='') as csvfile:
+    fieldnames = ('name', 'signature', 'description', 'group')
+    writer = csv.DictWriter(csvfile, fieldnames=fieldnames, extrasaction='ignore', dialect='excel-tab')
+
+    writer.writeheader()
+    for name, (signature, description, group) in sorted(all_functions.items(), key=lambda x: all_functions[x[0]][2]):
+        writer.writerow({'name': name, 'signature': signature, 'description': description, 'group': group})