mirror/pico-sdk
1
0
Fork 0
mirror of https://github.com/raspberrypi/pico-sdk.git synced 2025-04-17 08:45:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add descriptions for all functions missing them

Browse Source
This commit is contained in:
William Vinnicombe 2025-04-14 15:58:11 +01:00
parent 677667dc0d
commit 4236c24084
10 changed files with 81 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
src/cmake/on_device.cmake
View File

@ -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

8
src/common/pico_binary_info/CMakeLists.txt
View File

@ -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}")

5
src/rp2040/boot_stage2/CMakeLists.txt
View File

@ -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(TARGET 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(TARGET 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})

5
src/rp2350/boot_stage2/CMakeLists.txt
View File

@ -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(TARGET 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(TARGET 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})

1
src/rp2_common/pico_btstack/CMakeLists.txt
View File

@ -302,6 +302,7 @@ if (EXISTS ${PICO_BTSTACK_PATH}/${BTSTACK_TEST_PATH})
pico_promote_common_scope_vars()
# 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.

18
src/rp2_common/pico_cyw43_driver/CMakeLists.txt
View File

@ -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})

5
src/rp2_common/pico_lwip/tools/CMakeLists.txt
View File

@ -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")

7
src/rp2_common/pico_standard_link/CMakeLists.txt
View File

@ -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()

8
src/rp2_common/pico_stdio/CMakeLists.txt
View File

@ -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()

34
tools/extract_cmake_functions.py
View File

@ -28,9 +28,31 @@ 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'^#(.*)((\n\s*#.*)*)\nfunction\(([^\s]*)', re.MULTILINE)
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)
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 = {}
@ -39,7 +61,11 @@ all_functions = {}
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)
@ -56,8 +82,8 @@ for dirpath, dirnames, filenames in os.walk(scandir):
for match in CMAKE_PICO_FUNCTIONS_RE.finditer(text):
name = match.group(1)
if name not in all_functions:
print(f"Warning: {name} function has no description")
if name not in all_functions and name not in allowed_missing_functions:
print(f"Warning: {name} function has no description in {file_path}")
with open(outfile, 'w', newline='') as csvfile: