Runtime Infrastructure

#define pico_board_cmake_set(x, y)

A marker used in board headers to specify a CMake variable and value that should be set in the CMake build when the board header is used.

Based on the PICO_BOARD CMake variable, the build will scan the board header for pico_board_cmake_set(var, value) and set these variables very early in the build configuration process. This allows setting CMake variables like PICO_PLATFORM from the board header, and thus affecting, for example, the choice of compiler made by the build

#define pico_board_cmake_set_default(x, y)

A marker used in board headers to specify a CMake variable and value that should be set in the CMake build when the board header is used, if that CMake variable has not already been set.

Based on the PICO_BOARD CMake variable, the build will scan the board header for pico_board_cmake_set_default(var, value) and set these variables very early in the build configuration process. This allows setting CMake variables like PICO_PLATFORM from the board header, and thus affecting, for example, the choice of compiler made by the build

enum pico_error_codes

Common return codes from pico_sdk methods that return a status.

All PICO_ERROR_ values are negative so they can be returned from functions that also want to return a zero or positive value on success.

Note these error codes may be returned via bootrom functions too.

#define bi_decl(_decl) __bi_mark_enclosure _decl; __bi_decl(__bi_ptr_lineno_var_name, &__bi_lineno_var_name.core, ".binary_info.keep.", __used);

Declare some binary information that will be included if the contain source file/line is compiled into the binary.

#define bi_decl_if_func_used(_decl) ({__bi_mark_enclosure _decl; __bi_decl(__bi_ptr_lineno_var_name, &__bi_lineno_var_name.core, ".binary_info.", ); *(const volatile uint8_t *)&__bi_ptr_lineno_var_name;});

Declare some binary information that will be included if the function containing the decl is linked into the binary. The SDK uses –gc-sections, so functions that are never called will be removed by the linker, and any associated binary information declared this way will also be stripped.

typedef struct _binary_info_core binary_info_core_t

Common header fields shared by all binary info entries.

Every binary info structure begins with this core header, which identifies the entry type and the tag namespace it belongs to.

typedef struct _binary_info_raw_data binary_info_raw_data_t

Binary info entry carrying raw, uninterpreted byte data.

typedef struct _binary_info_sized_data binary_info_sized_data_t

Binary info entry carrying a length-prefixed byte buffer.

typedef struct _binary_info_list_zero_terminated binary_info_list_zero_terminated_t

Binary info entry holding a null-terminated list of binary info pointers.

typedef struct _binary_info_id_and_int binary_info_id_and_int_t

Binary info entry associating a 32-bit integer value with an ID.

typedef struct _binary_info_id_and_string binary_info_id_and_string_t

Binary info entry associating a string value with an ID.

typedef struct _binary_info_ptr_int32_with_name binary_info_ptr_int32_with_name_t

Binary info entry holding a pointer to a named 32-bit integer variable.

typedef struct _binary_info_ptr_string_with_name binary_info_ptr_string_with_name_t

Binary info entry holding a pointer to a named string variable.

typedef struct _binary_info_block_device binary_info_block_device_t

Binary info entry describing a block device in the binary.

typedef struct _binary_info_pins_with_func binary_info_pins_with_func_t

Binary info entry describing one or more GPIO pins and their assigned function, supporting pin numbers <32, and up to 5 pins.

typedef struct _binary_info_pins64_with_func binary_info_pins64_with_func_t

Binary info entry describing one or more GPIO pins and their assigned function, supporting pin numbers <256, and up to 7 pins.

typedef struct _binary_info_pins_with_name binary_info_pins_with_name_t

Binary info entry associating a human-readable label with a set of GPIO pins.

typedef struct _binary_info_pins64_with_name binary_info_pins64_with_name_t

Binary info entry associating a human-readable label with a set of GPIO pins (up to 64)

typedef struct _binary_info_named_group binary_info_named_group_t

Binary info entry defining a named group of related binary info entries.

Named groups allow tools to present related binary info entries together under a common label, with configurable display behaviour.

#define ROM_TABLE_CODE(c1, c2) ((c1) | ((c2) << 8))

Return a bootrom lookup code based on two ASCII characters.

These codes are uses to lookup data or function addresses in the bootrom

Parameters

static void rom_connect_internal_flash (void) [inline], [static]

Connect the SSI/QMI to the QSPI pads.

Restore all QSPI pad controls to their default state, and connect the SSI/QMI peripheral to the QSPI pads.

On RP2350 if a secondary flash chip select GPIO has been configured via OTP OTP_DATA_FLASH_DEVINFO, or by writing to the runtime copy of FLASH_DEVINFO in bootram, then this bank 0 GPIO is also initialised and the QMI peripheral is connected. Otherwise, bank 0 IOs are untouched.

void * rom_data_lookup (uint32_t code)

Lookup a bootrom data address by its code.

Parameters

static __force_inline void * rom_data_lookup_inline (uint32_t code) [static]

Lookup a bootrom data address by its code. This method is forcibly inlined into the caller for FLASH/RAM sensitive code usage.

Parameters

static void rom_flash_enter_cmd_xip (void) [inline], [static]

Configure the SSI/QMI with a standard command.

Configure the SSI/QMI to generate a standard 03h serial read command, with 24 address bits, upon each XIP access. This is a slow XIP configuration, but is widely supported. CLKDIV is set to 12 on RP2350. The debugger may call this function to ensure that flash is readable following a program/erase operation.

Note that the same setup is performed by flash_exit_xip(), and the RP2350 flash program/erase functions do not leave XIP in an inaccessible state, so calls to this function are largely redundant on RP2350. It is provided on RP2350 for compatibility with RP2040.

static void rom_flash_exit_xip (void) [inline], [static]

Return the QSPI device from its XIP state to a serial command state.

On RP2040, first set up the SSI for serial-mode operations, then issue the fixed XIP exit sequence described in Section 2.8.1.2 of the datasheet. Note that the bootrom code uses the IO forcing logic to drive the CS pin, which must be cleared before returning the SSI to XIP mode (e.g. by a call to _flash_flush_cache). This function configures the SSI with a fixed SCK clock divisor of /6.

On RP2350, Initialise the QMI for serial operations (direct mode), and also initialise a basic XIP mode, where the QMI will perform 03h serial read commands at low speed (CLKDIV=12) in response to XIP reads.

Then, issue a sequence to the QSPI device on chip select 0, designed to return it from continuous read mode ("XIP mode") and/or QPI mode to a state where it will accept serial commands. This is necessary after system reset to restore the QSPI device to a known state, because resetting RP2350 does not reset attached QSPI devices. It is also necessary when user code, having already performed some continuous-read-mode or QPI-mode accesses, wishes to return the QSPI device to a state where it will accept the serial erase and programming commands issued by the bootrom’s flash access functions.

If a GPIO for the secondary chip select is configured via FLASH_DEVINFO, then the XIP exit sequence is also issued to chip select 1.

The QSPI device should be accessible for XIP reads after calling this function; the name flash_exit_xip refers to returning the QSPI device from its XIP state to a serial command state.

static void rom_flash_flush_cache (void) [inline], [static]

Flush the XIP cache.

Flush and enable the XIP cache. Also clears the IO forcing on QSPI CSn, so that the SSI can drive the flash chip select as normal.

Flush the entire XIP cache, by issuing an invalidate by set/way maintenance operation to every cache line. This ensures that flash program/erase operations are visible to subsequent cached XIP reads.

Note that this unpins pinned cache lines, which may interfere with cache-as-SRAM use of the XIP cache.

No other operations are performed.

static void rom_flash_range_erase (uint32_t addr, size_t count, uint32_t block_size, uint8_t block_cmd) [inline], [static]

Erase bytes in flash.

Erase count bytes, starting at addr (offset from start of flash). Optionally, pass a block erase command e.g. D8h block erase, and the size of the block erased by this command - this function will use the larger block erase where possible, for much higher erase speed. addr must be aligned to a 4096-byte sector, and count must be a multiple of 4096 bytes.

This is a low-level flash API, and no validation of the arguments is performed.

See rom_flash_op on RP2350 for a higher-level API which checks alignment, flash bounds and partition permissions, and can transparently apply a runtime-to-storage address translation.

The QSPI device must be in a serial command state before calling this API, which can be achieved by calling rom_connect_internal_flash() followed by rom_flash_exit_xip(). After the erase, the flash cache should be flushed via rom_flash_flush_cache() to ensure the modified flash data is visible to cached XIP accesses.

Finally, the original XIP mode should be restored by copying the saved XIP setup function from bootram into SRAM, and executing it: the bootrom provides a default function which restores the flash mode/clkdiv discovered during flash scanning, and user programs can override this with their own XIP setup function.

For the duration of the erase operation, QMI is in direct mode and attempting to access XIP from DMA, the debugger or the other core will return a bus fault. XIP becomes accessible again once the function returns.

Parameters

static void rom_flash_range_program (uint32_t addr, const uint8_t * data, size_t count) [inline], [static]

Program bytes in flash.

Program data to a range of flash addresses starting at addr (offset from the start of flash) and count bytes in size. addr must be aligned to a 256-byte boundary, and count must be a multiple of 256.

This is a low-level flash API, and no validation of the arguments is performed.

See rom_flash_op on RP2350 for a higher-level API which checks alignment, flash bounds and partition permissions, and can transparently apply a runtime-to-storage address translation.

The QSPI device must be in a serial command state before calling this API - see notes on rom_flash_range_erase

Parameters

void * rom_func_lookup (uint32_t code)

Lookup a bootrom function by its code.

Parameters

static __force_inline void * rom_func_lookup_inline (uint32_t code) [static]

Lookup a bootrom function by code. This method is forcibly inlined into the caller for FLASH/RAM sensitive code usage.

Parameters

bool rom_funcs_lookup (uint32_t * table, unsigned int count)

Helper function to lookup the addresses of multiple bootrom functions.

This method looks up the 'codes' in the table, and convert each table entry to the looked up function pointer, if there is a function for that code in the bootrom.

Parameters

void rom_reset_usb_boot (uint32_t usb_activity_gpio_pin_mask, uint32_t disable_interface_mask)

Reboot the device into BOOTSEL mode.

This function reboots the device into the BOOTSEL mode ('usb boot"). Facilities are provided to enable an "activity light" via GPIO attached LED for the USB Mass Storage Device, and to limit the USB interfaces exposed.

Parameters

void rom_reset_usb_boot_extra (int usb_activity_gpio_pin, uint32_t disable_interface_mask, bool usb_activity_gpio_pin_active_low)

Reboot the device into BOOTSEL mode.

This function reboots the device into the BOOTSEL mode ('usb boot"). Facilities are provided to enable an "activity light" via GPIO attached LED for the USB Mass Storage Device, and to limit the USB interfaces exposed.

Parameters

static uint32_t rom_table_code (uint8_t c1, uint8_t c2) [inline], [static]

Return a bootrom lookup code based on two ASCII characters.

These codes are uses to lookup data or function addresses in the bootrom

Parameters

uint32_t __rev (uint32_t bits)

Reverse the bits in a 32 bit word.

Parameters

uint64_t __revll (uint64_t bits)

Reverse the bits in a 64 bit double word.

Parameters

int32_t div_s32s32 (int32_t a, int32_t b)

Integer divide of two signed 32-bit values.

Parameters

int32_t div_s32s32_unsafe (int32_t a, int32_t b)

Unsafe integer divide of two signed 32-bit values.

Parameters

Do not use in interrupts

int64_t div_s64s64 (int64_t a, int64_t b)

Integer divide of two signed 64-bit values.

Parameters

int64_t div_s64s64_unsafe (int64_t a, int64_t b)

Unsafe integer divide of two signed 64-bit values.

Parameters

Do not use in interrupts

uint32_t div_u32u32 (uint32_t a, uint32_t b)

Integer divide of two unsigned 32-bit values.

Parameters

uint32_t div_u32u32_unsafe (uint32_t a, uint32_t b)

Unsafe integer divide of two unsigned 32-bit values.

Parameters

Do not use in interrupts

uint64_t div_u64u64 (uint64_t a, uint64_t b)

Integer divide of two unsigned 64-bit values.

Parameters

uint64_t div_u64u64_unsafe (uint64_t a, uint64_t b)

Unsafe integer divide of two unsigned 64-bit values.

Parameters

Do not use in interrupts

divmod_result_t divmod_s32s32 (int32_t a, int32_t b)

Integer divide of two signed 32-bit values.

Parameters

static int32_t divmod_s32s32_rem (int32_t a, int32_t b, int32_t * rem) [inline], [static]

Integer divide of two signed 32-bit values, with remainder.

Parameters

int32_t divmod_s32s32_rem_unsafe (int32_t a, int32_t b, int32_t * rem)

Unsafe integer divide of two signed 32-bit values, with remainder.

Parameters

Do not use in interrupts

divmod_result_t divmod_s32s32_unsafe (int32_t a, int32_t b)

Unsafe integer divide of two signed 32-bit values.

Parameters

Do not use in interrupts

int64_t divmod_s64s64_rem (int64_t a, int64_t b, int64_t * rem)

Integer divide of two signed 64-bit values, with remainder.

Parameters

int64_t divmod_s64s64_rem_unsafe (int64_t a, int64_t b, int64_t * rem)

Unsafe integer divide of two signed 64-bit values, with remainder.

Parameters

Do not use in interrupts

int64_t divmod_s64s64_unsafe (int64_t a, int64_t b)

Unsafe integer divide of two signed 64-bit values.

Parameters

Do not use in interrupts

divmod_result_t divmod_u32u32 (uint32_t a, uint32_t b)

Integer divide of two unsigned 32-bit values.

Parameters

static uint32_t divmod_u32u32_rem (uint32_t a, uint32_t b, uint32_t * rem) [inline], [static]

Integer divide of two unsigned 32-bit values, with remainder.

Parameters

uint32_t divmod_u32u32_rem_unsafe (uint32_t a, uint32_t b, uint32_t * rem)

Unsafe integer divide of two unsigned 32-bit values, with remainder.

Parameters

Do not use in interrupts

divmod_result_t divmod_u32u32_unsafe (uint32_t a, uint32_t b)

Unsafe integer divide of two unsigned 32-bit values.

Parameters

Do not use in interrupts

uint64_t divmod_u64u64_rem (uint64_t a, uint64_t b, uint64_t * rem)

Integer divide of two unsigned 64-bit values, with remainder.

Parameters

uint64_t divmod_u64u64_rem_unsafe (uint64_t a, uint64_t b, uint64_t * rem)

Unsafe integer divide of two unsigned 64-bit values, with remainder.

Parameters

Do not use in interrupts

uint64_t divmod_u64u64_unsafe (uint64_t a, uint64_t b)

Unsafe integer divide of two unsigned 64-bit values.

Parameters

Do not use in interrupts

#define PICO_DOUBLE_HAS_INT32_TO_DOUBLE_CONVERSIONS 1

Set if int2double and uint2double are available.

#define PICO_DOUBLE_HAS_INT64_TO_DOUBLE_CONVERSIONS 1

Set if int642double and uint642double are available.

#define PICO_DOUBLE_HAS_DOUBLE_TO_INT32_Z_CONVERSIONS 1

Set if double2int_z and double2uint_z are available (rounding towards zero)

#define PICO_DOUBLE_HAS_DOUBLE_TO_INT64_Z_CONVERSIONS 1

Set if double2int64_z and double2uint64_z are available (rounding towards zero)

#define PICO_DOUBLE_HAS_FIX32_TO_DOUBLE_CONVERSIONS 1

Set if fix2double and ufix2double are available.

#define PICO_DOUBLE_HAS_FIX64_TO_DOUBLE_CONVERSIONS 1

Set if fix642double and ufix642double are available.

#define PICO_DOUBLE_HAS_DOUBLE_TO_FIX32_Z_CONVERSIONS 1

Set if double2fix_z and double2ufix_z are available (rounding towards zero)

#define PICO_DOUBLE_HAS_DOUBLE_TO_FIX64_Z_CONVERSIONS 1

Set if double2fix64_z and double2ufix64_z are available (rounding towards zero)

#define PICO_DOUBLE_HAS_DOUBLE_TO_INT32_M_CONVERSIONS 1

Set if double2int and double2uint are available (rounding towards -Infinity)

#define PICO_DOUBLE_HAS_DOUBLE_TO_INT64_M_CONVERSIONS 1

Set if double2int64 and double2uint64 are available (rounding towards -Infinity)

#define PICO_DOUBLE_HAS_DOUBLE_TO_FIX32_M_CONVERSIONS 1

Set if double2fix and double2ufix are available (rounding towards -Infinity)

#define PICO_DOUBLE_HAS_DOUBLE_TO_FIX64_M_CONVERSIONS 1

Set if double2fix64 and double2ufix64 are available (rounding towards -Infinity)

#define PICO_DOUBLE_HAS_DDIV_FAST 1

Set if ddiv_fast is available.

#define PICO_DOUBLE_HAS_SQRT_FAST 1

Set if sqrt_fast is available.

#define PICO_DOUBLE_HAS_FMA_FAST 1

Set if fma_fast is available.

#define PICO_DOUBLE_HAS_POWINT 1

Set if powint is available.

double ddiv_fast (double n, double d)

Perform a fast floating point divide with reduced accuracy.

int32_t double2fix (double d, int e)

Convert a double to a signed 32-bit fixed-point integer with the given number of fractional bits, rounding towards -Infinity. This conversion is saturating (to INT32_MAX/INT32_MIN) for out of range input.

int64_t double2fix64 (double d, int e)

Convert a double to a signed 64-bit fixed-point integer with the given number of fractional bits, rounding towards -Infinity. This conversion is saturating (to INT64_MAX/INT64_MIN) for out of range input.

int64_t double2fix64_z (double d, int e)

Convert a double to a signed 64-bit fixed-point integer with the given number of fractional bits, rounding towards zero. On Arm this conversion is saturating (to INT64_MAX/INT64_MIN) for out of range input except when using pico_double compiler

int32_t double2fix_z (double d, int e)

Convert a double to a signed 32-bit fixed-point integer with the given number of fractional bits, rounding towards zero. On Arm this conversion is saturating (to INT32_MAX/INT32_MIN) for out of range input except when using pico_double compiler

int32_t double2int (double d)

Convert a double to a signed 32-bit integer, rounding towards -Infinity. This conversion is saturating (to INT32_MAX/INT32_MIN) for out of range input.

int64_t double2int64 (double d)

Convert a double to a signed 64-bit integer, rounding towards -Infinity. This conversion is saturating (to INT64_MAX/INT64_MIN) for out of range input.

int64_t double2int64_z (double d)

Convert a double to a signed 64-bit integer, rounding towards zero. On Arm this conversion is saturating (to INT64_MAX/INT64_MIN) for out of range input except when using pico_double compiler

int32_t double2int_z (double d)

Convert a double to a signed 32-bit integer, rounding towards zero. On Arm this conversion is saturating (to INT32_MAX/INT32_MIN) for out of range input except when using pico_double compiler

uint32_t double2ufix (double d, int e)

Convert a double to an unsigned 32-bit fixed-point integer with the given number of fractional bits, rounding towards -Infinity. This conversion is saturating (to UINT32_MAX/UINT32_MIN) for out of range input.

uint64_t double2ufix64 (double d, int e)

Convert a double to an unsigned 64-bit fixed-point integer with the given number of fractional bits, rounding towards -Infinity. This conversion is saturating (to UINT64_MAX/UINT64_MIN) for out of range input.

uint64_t double2ufix64_z (double d, int e)

Convert a double to an unsigned 64-bit fixed-point integer with the given number of fractional bits, rounding towards zero. This conversion is saturating (to UINT64_MAX/UINT64_MIN) for out of range input.

uint32_t double2ufix_z (double d, int e)

Convert a double to an unsigned 32-bit fixed-point integer with the given number of fractional bits, rounding towards zero. This conversion is saturating (to UINT32_MAX/UINT32_MIN) for out of range input.

uint32_t double2uint (double d)

Convert a double to an unsigned 32-bit integer, rounding towards -Infinity. This conversion is saturating (to UINT32_MAX/UINT32_MIN) for out of range input.

uint64_t double2uint64 (double d)

Convert a double to an usigned 64-bit integer, rounding towards -Infinity. This conversion is saturating (to UINT64_MAX/UINT64_MIN) for out of range input.

uint64_t double2uint64_z (double d)

Convert a double to an unsigned 64-bit integer, rounding towards zero. On Arm this conversion is saturating (to UINT64_MAX/UINT64_MIN) for out of range input except when using pico_double compiler

uint32_t double2uint_z (double d)

Convert a double to an unsigned 32-bit integer, rounding towards zero On Arm this conversion is saturating (to UINT32_MAX/UINT32_MIN) for out of range input except when using pico_double compiler

double exp10 (double x)

Evaluate 10.0 to the power of the given value.

double fix2double (int32_t m, int e)

Convert a signed 32-bit fixed-point integer with the given number of fractional bits to the nearest double Out of range inputs will convert to +/- Infinity.

double fix642double (int64_t m, int e)

Convert a signed 64-bit fixed-point integer with the given number of fractional bits to the nearest double Out of range inputs will convert to +/- Infinity.

double fma_fast (double x, double y, double z)

Perform a fast (non-fused) multiply-add (x * y + z) with reduced accuracy.

double int2double (int32_t i)

Convert a signed 32-bit integer to the nearest double.

double int642double (int64_t i)

Convert a signed 64-bit integer to the nearest double.

double mla (double x, double y, double z)

Perform a fast multiply-add (x * y + z) with reduced accuracy (not fused multiply-add). This is another name for fma_fast.

double powint (double x, int32_t y)

Raise a floating point number to an integer power.

void sincos (double x, double * sinx, double * cosx)

Return both the sine and cosine of an angle efficiently.

double sqrt_fast (double d)

Perform a fast floating point square-root with reduced accuracy.

double ufix2double (uint32_t m, int e)

Convert an unsigned 32-bit fixed-point integer with the given number of fractional bits to the nearest double Out of range inputs will convert to +Infinity.

double ufix642double (uint64_t m, int e)

Convert an unsigned 64-bit fixed-point integer with the given number of fractional bits to the nearest double Out of range inputs will convert to +Infinity.

double uint2double (uint32_t u)

Convert an unsigned 32-bit integer to the nearest double.

double uint642double (uint64_t u)

Convert an unsigned 64-bit integer to the nearest double.

#define PICO_FLOAT_HAS_INT32_TO_FLOAT_CONVERSIONS 1

Set if int2float and uint2float are available.

#define PICO_FLOAT_HAS_INT64_TO_FLOAT_CONVERSIONS 1

Set if int642float and uint642float are available.

#define PICO_FLOAT_HAS_FLOAT_TO_INT32_Z_CONVERSIONS 1

Set if float2int_z and float2uint_z are available (rounding towards zero)

#define PICO_FLOAT_HAS_FLOAT_TO_INT64_Z_CONVERSIONS 1

Set if float2int64_z and float2uint64_z are available (rounding towards zero)

#define PICO_FLOAT_HAS_FIX32_TO_FLOAT_CONVERSIONS 1

Set if fix2float and ufix2float are available.

#define PICO_FLOAT_HAS_FIX64_TO_FLOAT_CONVERSIONS 1

Set if fix642float and ufix642float are available.

#define PICO_FLOAT_HAS_FLOAT_TO_FIX32_Z_CONVERSIONS 1

Set if float2fix_z and float2ufix_z are available (rounding towards zero)

#define PICO_FLOAT_HAS_FLOAT_TO_FIX64_Z_CONVERSIONS 1

Set if float2fix64_z and float2ufix64_z are available (rounding towards zero)

#define PICO_FLOAT_HAS_FLOAT_TO_INT32_M_CONVERSIONS 1

Set if float2int and float2uint are available (rounding towards -Infinity)

#define PICO_FLOAT_HAS_FLOAT_TO_INT64_M_CONVERSIONS 1

Set if float2int64 and float2uint64 are available (rounding towards -Infinity)

#define PICO_FLOAT_HAS_FLOAT_TO_FIX32_M_CONVERSIONS 1

Set if float2fix and float2ufix are available (rounding towards -Infinity)

#define PICO_FLOAT_HAS_FLOAT_TO_FIX64_M_CONVERSIONS 1

Set if float2fix64 and float2ufix64 are available (rounding towards -Infinity)

#define PICO_FLOAT_HAS_FDIV_FAST 1

Set if fdiv_fast is available.

#define PICO_FLOAT_HAS_SQRTF_FAST 1

Set if sqrtf_fast is available.

#define PICO_FLOAT_HAS_POWINTF 1

Set if powintf is available.

float exp10f (float x)

Evaluate 10.0f to the power of the given value.

float fdiv_fast (float n, float d)

Perform a fast floating point divide with reduced accuracy.

float fix2float (int32_t m, int e)

Convert a signed 32-bit fixed-point integer with the given number of fractional bits to the nearest float Out of range inputs will convert to +/- Infinity.

float fix642float (int64_t m, int e)

Convert a signed 64-bit fixed-point integer with the given number of fractional bits to the nearest float Out of range inputs will convert to +/- Infinity.

int32_t float2fix (float f, int e)

Convert a float to a signed 32-bit fixed-point integer with the given number of fractional bits, rounding towards -Infinity. This conversion is saturating (to INT32_MAX/INT32_MIN) for out of range input.

int64_t float2fix64 (float f, int e)

Convert a float to a signed 64-bit fixed-point integer with the given number of fractional bits, rounding towards -Infinity. This conversion is saturating (to INT64_MAX/INT64_MIN) for out of range input.

int64_t float2fix64_z (float f, int e)

Convert a float to a signed 64-bit fixed-point integer with the given number of fractional bits, rounding towards zero. On Arm this conversion is saturating (to INT64_MAX/INT64_MIN) for out of range input except when using pico_float compiler

int32_t float2fix_z (float f, int e)

Convert a float to a signed 32-bit fixed-point integer with the given number of fractional bits, rounding towards zero. On Arm this conversion is saturating (to INT32_MAX/INT32_MIN) for out of range input except when using pico_float compiler

int32_t float2int (float f)

Convert a float to a signed 32-bit integer, rounding towards -Infinity. This conversion is saturating (to INT32_MAX/INT32_MIN) for out of range input.

int64_t float2int64 (float f)

Convert a float to a signed 64-bit integer, rounding towards -Infinity. This conversion is saturating (to INT64_MAX/INT64_MIN) for out of range input.

int64_t float2int64_z (float f)

Convert a float to a signed 64-bit integer, rounding towards zero. On Arm this conversion is saturating (to INT64_MAX/INT64_MIN) for out of range input except when using pico_float compiler

int32_t float2int_z (float f)

Convert a float to a signed 32-bit integer, rounding towards zero. On Arm this conversion is saturating (to INT32_MAX/INT32_MIN) for out of range input except when using pico_float compiler

uint32_t float2ufix (float f, int e)

Convert a float to an unsigned 32-bit fixed-point integer with the given number of fractional bits, rounding towards -Infinity. This conversion is saturating (to UINT32_MAX/UINT32_MIN) for out of range input.

uint64_t float2ufix64 (float f, int e)

Convert a float to an unsigned 64-bit fixed-point integer with the given number of fractional bits, rounding towards -Infinity. This conversion is saturating (to UINT64_MAX/UINT64_MIN) for out of range input.

uint64_t float2ufix64_z (float f, int e)

Convert a float to an unsigned 64-bit fixed-point integer with the given number of fractional bits, rounding towards zero. This conversion is saturating (to UINT64_MAX/UINT64_MIN) for out of range input.

uint32_t float2ufix_z (float f, int e)

Convert a float to an unsigned 32-bit fixed-point integer with the given number of fractional bits, rounding towards zero. This conversion is saturating (to UINT32_MAX/UINT32_MIN) for out of range input.

uint32_t float2uint (float f)

Convert a float to an unsigned 32-bit integer, rounding towards -Infinity. This conversion is saturating (to UINT32_MAX/UINT32_MIN) for out of range input.

uint64_t float2uint64 (float f)

Convert a float to an unsigned 64-bit integer, rounding towards -Infinity. This conversion is saturating (to UINT64_MAX/UINT64_MIN) for out of range input.

uint64_t float2uint64_z (float f)

Convert a float to an unsigned 64-bit integer, rounding towards zero. On Arm this conversion is saturating (to UINT64_MAX/UINT64_MIN) for out of range input except when using pico_float compiler

uint32_t float2uint_z (float f)

Convert a float to an unsigned 32-bit integer, rounding towards zero On Arm this conversion is saturating (to UINT32_MAX/UINT32_MIN) for out of range input except when using pico_float compiler

float int2float (int32_t i)

Convert a signed 32-bit integer to the nearest float.

float int642float (int64_t i)

Convert a signed 64-bit integer to the nearest float.

float powintf (float x, int32_t y)

Raise a floating point number to an integer power.

void sincosf (float x, float * sinx, float * cosx)

Return both the sine and cosine of an angle efficiently.

float sqrtf_fast (float f)

Perform a fast floating point square-root with reduced accuracy.

float ufix2float (uint32_t m, int e)

Convert an unsigned 32-bit fixed-point integer with the given number of fractional bits to the nearest float Out of range inputs will convert to +Infinity.

float ufix642float (uint64_t m, int e)

Convert an unsigned 64-bit fixed-point integer with the given number of fractional bits to the nearest float Out of range inputs will convert to +Infinity.

float uint2float (uint32_t u)

Convert an unsigned 32-bit integer to the nearest float.

float uint642float (uint64_t u)

Convert an unsigned 64-bit integer to the nearest float.

#define __fast_mul(a, b) (__builtin_constant_p(b) && !__builtin_constant_p(a) && __builtin_popcount(b) >= 2 ? __mul_instruction(a,b) : (a)*(b))

multiply two integer values using the fastest method possible

Efficiently multiplies value a by possibly constant value b.

If b is known to be constant and not zero or a power of 2, then a mul instruction is used rather than gcc’s default which is often a slow combination of shifts and adds. If b is a power of 2 then a single shift is of course preferable and will be used

Parameters

#define __isr

Marker for an interrupt handler.

For example an IRQ handler function called my_interrupt_handler:

#define __force_inline __always_inline

Attribute to force inlining of a function regardless of optimization level.

For example my_function here will always be inlined:

#define count_of(a) (sizeof(a)/sizeof((a)[0]))

Macro to determine the number of elements in an array.

#define MAX(a, b) ((a)>(b)?(a):(b))

Macro to return the maximum of two comparable values.

#define MIN(a, b) ((b)>(a)?(a):(b))

Macro to return the minimum of two comparable values.

#define __check_type_compatible(type_a, type_b) static_assert(__builtin_types_compatible_p(type_a, type_b), __STRING(type_a) " is not compatible with " __STRING(type_b));

Utility macro to assert two types are equivalent.

This macro can be useful in other macros along with typeof to assert that two parameters are of equivalent type (or that a single parameter is of an expected type)

#define __after_data(group) __attribute__((section(".after_data." group)))

Section attribute macro for placement in RAM after the .data section.

For example a 400 element uint32_t array placed after the .data section

The section attribute is .after_data.<group>

Parameters

#define __in_ram(group) __attribute__((section(".time_critical." group)))

Section attribute macro for placement in RAM.

For example a 3 element uint32_t array placed in RAM (even though it is static const)

The section attribute is .time_critical.<group>, which is used to maintain compatibility with older linker scripts

Parameters

#define __in_scratch_x(group) __attribute__((section(".scratch_x." group)))

Section attribute macro for placement in the penultimate SRAM bank (known as "scratch X")

Scratch X is commonly used for critical data and functions accessed only by one core (when only one core is accessing the RAM bank, there is no opportunity for stalls)

For example a uint32_t variable placed in "scratch X"

The section attribute is .scratch_x.<group>

Parameters

#define __scratch_x(group) __in_scratch_x(group)

Section attribute macro for placement in the penultimate SRAM bank (known as "scratch X")

Alias for __in_scratch_x

Parameters

#define __in_scratch_y(group) __attribute__((section(".scratch_y." group)))

Section attribute macro for placement in the final SRAM bank (known as "scratch Y")

Scratch Y is commonly used for critical data and functions accessed only by one core (when only one core is accessing the RAM bank, there is no opportunity for stalls)

For example a uint32_t variable placed in "scratch Y"

The section attribute is .scratch_y.<group>

Parameters

#define __scratch_y(group) __in_scratch_y(group)

Section attribute macro for placement in the final SRAM bank (known as "scratch Y")

Alias for __in_scratch_y

Parameters

#define __in_psram(group) __attribute__((section(".psram_initialised." group)))

Section attribute macro for placement in PSRAM.

PSRAM is commonly used for extra data sections. You can place data in initialised or uninitialised PSRAM, depending on how the data is loaded into the PSRAM.

For example a uint32_t variable placed in PSRAM

Or placed in uninitialised PSRAM

The section attribute is .psram_initialised.<group> or .psram_uninitialised.<group>

Parameters

#define __uninitialized_psram(group) __attribute__((section(".psram_uninitialised." group)))

Section attribute macro for placement in uninitialised PSRAM.

The version of __in_psram to use for uninitialised data

Parameters

#define __in_xip_ram(group) __attribute__((section(".xip_ram." group)))

Section attribute macro for placement in XIP SRAM.

The XIP Cache can be used as SRAM for extra data sections, however it will give a performance penalty if your binary runs from Flash (e.g. the default binary type).

For example a uint32_t variable placed in XIP SRAM

The section attribute is .xip_ram.<group>

Parameters

#define __uninitialized_ram(group) __attribute__((section(".uninitialized_data." #group))) group

Section attribute macro for data that is to be left uninitialized.

Data marked this way will retain its value across a reset (normally uninitialized data - in the .bss section) is initialized to zero during runtime initialization

For example a uint32_t foo that will retain its value if the program is restarted by reset.

The section attribute is .uninitialized_data.<group>

Parameters

#define __persistent_data(name) __attribute__((section(".persistent_data." #name))) name

Section attribute macro for placement in a section persisted across default POWMAN resets.

Data marked this way will retain its value across a default POWMAN reset, and will be zeroed on any other reset.

For example a uint32_t foo that will be zeroed initially, then retain its value if the program is restarted by default POWMAN reset.

The section attribute is .persistent_data.<name>

Parameters

#define __in_flash(group) __attribute__((section(".flashdata." group)))

Section attribute macro for placement in flash even in a COPY_TO_RAM binary.

For example a uint32_t variable explicitly placed in flash (it will hard fault if you attempt to write it!)

The section attribute is .flashdata.<group>

Parameters

#define __not_in_flash(group) PICO_NOT_IN_FLASH_PLACEMENT(group)

Section attribute macro for placement not in flash.

For example a 3 element uint32_t array placed in RAM (even though it is static const)

By default, this is identical to __in_ram, but this can be adjusted using the PICO_NOT_IN_FLASH_PLACEMENT define. This define can be set using the pico_set_not_in_flash_placement CMake function.

For example, for binaries that only use core 0, there is the option to use pico_set_not_in_flash_placement(TARGET scratch_x) to place this code/data in scratch X to move it out of the striped SRAM.

Parameters

#define __not_in_flash_func(func_name) __not_in_flash(__STRING(func_name)) func_name

Indicates a function should not be stored in flash.

Decorates a function name, such that the function will execute from RAM (assuming it is not inlined into a flash function by the compiler)

For example a function called my_func taking an int parameter:

The function is placed using __not_in_flash, which defaults to __in_ram

#define __no_inline_not_in_flash_func(func_name) __noinline __not_in_flash_func(func_name)

Indicate a function should not be stored in flash and should not be inlined.

Decorates a function name, such that the function will execute from RAM, explicitly marking it as noinline to prevent it being inlined into a flash function by the compiler

For example a function called my_func taking an int parameter:

The function is placed using __not_in_flash, which defaults to __in_ram

#define __time_critical_func(func_name) __noinline PICO_TIME_CRITICAL_PLACEMENT(__STRING(func_name)) func_name

Indicates a function is time/latency critical and should not run from flash.

Decorates a function name, such that the function will execute from RAM to avoid possible flash latency. By default, this macro is identical in implementation to __no_inline_not_in_flash_func, however the semantics are distinct and a __time_critical_func can be treated more specially to reduce the overhead when calling such a function.

For example a function called my_func taking an int parameter:

By default, the function is placed using __in_ram, but this can be adjusted using the PICO_TIME_CRITICAL_PLACEMENT define. This define can be set using the pico_set_time_critical_placement CMake function.

For example, for binaries that are not executing from flash (e.g. copy_to_ram and no_flash), there is the option to use pico_set_time_critical_placement(TARGET xip_ram) to place these functions in XIP RAM, as the XIP AHB ports would be otherwise unused.

static __force_inline void __breakpoint (void) [static]

Execute a breakpoint instruction.

static __always_inline void __compiler_memory_barrier (void) [static]

Ensure that the compiler does not move memory access across this method call.

For example in the following code:

The compiler will not move the load from some_other_memory_location above the memory barrier (which it otherwise might - even above the memory store!)

static __force_inline uint __get_current_exception (void) [static]

Get the current exception level on this core.

On Cortex-M this is the exception number defined in the architecture reference, which is equal to VTABLE_FIRST_IRQ + irq num if inside an interrupt handler. (VTABLE_FIRST_IRQ is defined in platform_defs.h).

On Hazard3, this function returns VTABLE_FIRST_IRQ + irq num if inside of an external IRQ handler (or a fault from such a handler), and 0 otherwise, generally aligning with the Cortex-M values.

static __force_inline int32_t __mul_instruction (int32_t a, int32_t b) [static]

Multiply two integers using an assembly MUL instruction.

This multiplies a by b using multiply instruction using the ARM mul instruction regardless of values (the compiler might otherwise choose to perform shifts/adds), i.e. this is a 1 cycle operation.

Parameters

static void busy_wait_at_least_cycles (uint32_t minimum_cycles) [inline], [static]

Helper method to busy-wait for at least the given number of cycles.

This method is useful for introducing very short delays.

This method busy-waits in a tight loop for the given number of system clock cycles. The total wait time is only accurate to within 2 cycles, and this method uses a loop counter rather than a hardware timer, so the method will always take longer than expected if an interrupt is handled on the calling core during the busy-wait; you can of course disable interrupts to prevent this.

You can use clock_get_hz(clk_sys) to determine the number of clock cycles per second if you want to convert an actual time duration to a number of cycles.

Parameters

static __force_inline uint get_core_num (void) [static]

Get the current core number.

void panic (const char * fmt, …​)

Displays a panic message and halts execution.

An attempt is made to output the message to all registered STDOUT drivers after which this method executes a BKPT instruction.

Parameters

void panic_unsupported (void)

Panics with the message "Unsupported".

static __force_inline void tight_loop_contents (void) [static]

No-op function for the body of tight loops.

No-op function intended to be called by any tight hardware polling loop. Using this ubiquitously makes it much easier to find tight loops, but also in the future #ifdef-ed support for lockup debugging might be added

void __weak hard_assertion_failure (void)

Handle a hard_assert condition failure.

This weak function provides the default implementation (call panic with "Hard assert") for if a hard_assert condition fail in non debug builds. You can provide your own strong implementation to replace the default behavior

void runtime_init (void)

Run all the initializations that are usually called by crt0.S before entering main.

This method is useful to set up the runtime after performing a watchdog or powman reboot via scratch vector.

static void clocks_init (void) [inline], [static]

Initialise the clock hardware.

Must be called before any other clock function.

int __printflike (1, 0)

Alias for printf that definitely does not go thru the implementation in the standard C library even when PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0.

static int getchar_timeout_us (uint32_t timeout_us) [inline], [static]

Alias for stdio_getchar_timeout_us for backwards compatibility.

static int putchar_raw (int c) [inline], [static]

Alias for stdio_putchar_raw for backwards compatibility.

static int puts_raw (const char * s) [inline], [static]

Alias for stdio_puts_raw for backwards compatibility.

bool stdio_deinit_all (void)

Deinitialize all of the present standard stdio types that are linked into the binary.

This method currently only supports stdio_uart and stdio_semihosting

void stdio_filter_driver (stdio_driver_t * driver)

Control limiting of output to a single driver.

Parameters

void stdio_flush (void)

Flushes any buffered output.

int stdio_get_until (char * buf, int len, absolute_time_t until)

Waits until a timeout to read at least one character into a buffer.

This method returns as soon as input is available, but more characters may be returned up to the end of the buffer.

Parameters

Parameters

int stdio_getchar (void)

Alias for getchar that definitely does not go thru the implementation in the standard C library even when PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0.

int stdio_getchar_timeout_us (uint32_t timeout_us)

Return a character from stdin if there is one available within a timeout.

Parameters

bool stdio_init_all (void)

Initialize all of the present standard stdio types that are linked into the binary.

Call this method once you have set up your clocks to enable the stdio support for UART, USB, semihosting, and RTT based on the presence of the respective libraries in the binary.

When stdio_usb is configured, this method can be optionally made to block, waiting for a connection via the variables specified in stdio_usb_init (i.e. PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS)

int stdio_put_string (const char * s, int len, bool newline, bool cr_translation)

Prints a buffer to stdout, optionally appending a newline.

Writes s to every registered stdio driver. The call returns once each driver has accepted the bytes

Parameters

int stdio_putchar (int c)

Alias for putchar that definitely does not go thru the implementation in the standard C library even when PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0.

int stdio_putchar_raw (int c)

putchar variant that skips any CR/LF conversion if enabled

int stdio_puts (const char * s)

Alias for puts that definitely does not go thru the implementation in the standard C library even when PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0.

int stdio_puts_raw (const char * s)

puts variant that skips any CR/LF conversion if enabled

void stdio_set_chars_available_callback (void(*)(void *) fn, void * param)

get notified when there are input characters available

Parameters

void stdio_set_driver_enabled (stdio_driver_t * driver, bool enabled)

Adds or removes a driver from the list of active drivers used for input/output.

Parameters

void stdio_set_translate_crlf (stdio_driver_t * driver, bool translate)

control conversion of line feeds to carriage return on transmissions

Parameters

int stdio_vprintf (const char * format, va_list va)

Alias for vprintf that definitely does not go thru the implementation in the standard C library even when PICO_STDIO_SHORT_CIRCUIT_CLIB_FUNCS == 0.

Linking this library or calling pico_enable_stdio_semihosting(TARGET ENABLED) in the CMake (which achieves the same thing) will add semihosting to the drivers used for standard output

void stdio_semihosting_deinit (void)

Explicitly deinitialize stdout over semihosting and add it to the current set of stdout targets.

void stdio_semihosting_init (void)

Explicitly initialize stdout over semihosting and add it to the current set of stdout targets.

Linking this library or calling pico_enable_stdio_uart(TARGET ENABLED) in the CMake (which achieves the same thing) will add UART to the drivers used for standard input/output

void stdin_uart_deinit (void)

Explicitly deinitialize stdin only (no stdout) over UART and remove it from the current set of stdin drivers.

This method disables PICO_DEFAULT_UART_RX_PIN for UART input (if defined), and leaves the pads isolated

void stdin_uart_init (void)

Explicitly initialize stdin only (no stdout) over UART and add it to the current set of stdin drivers.

This method sets up PICO_DEFAULT_UART_RX_PIN for UART input (if defined) , and configures the baud rate as PICO_DEFAULT_UART_BAUD_RATE

void stdio_uart_deinit (void)

Explicitly deinitialize stdin/stdout over UART and remove it from the current set of stdin/stdout drivers.

This method disables PICO_DEFAULT_UART_TX_PIN for UART output (if defined), PICO_DEFAULT_UART_RX_PIN for input (if defined) and leaves the pads isolated.

void stdio_uart_deinit_full (uart_inst_t * uart, int tx_pin, int rx_pin)

Perform custom deinitialization deinitialize stdin/stdout over UART and remove it from the current set of stdin/stdout drivers.

Parameters

void stdio_uart_init (void)

Explicitly initialize stdin/stdout over UART and add it to the current set of stdin/stdout drivers.

This method sets up PICO_DEFAULT_UART_TX_PIN for UART output (if defined), PICO_DEFAULT_UART_RX_PIN for input (if defined) and configures the baud rate as PICO_DEFAULT_UART_BAUD_RATE.

void stdio_uart_init_full (uart_inst_t * uart, uint baud_rate, int tx_pin, int rx_pin)

Perform custom initialization initialize stdin/stdout over UART and add it to the current set of stdin/stdout drivers.

Parameters

void stdout_uart_deinit (void)

Explicitly deinitialize stdout only (no stdin) over UART and remove it from the current set of stdout drivers.

This method disables PICO_DEFAULT_UART_TX_PIN for UART output (if defined), and leaves the pad isolated

void stdout_uart_init (void)

Explicitly initialize stdout only (no stdin) over UART and add it to the current set of stdout drivers.

This method sets up PICO_DEFAULT_UART_TX_PIN for UART output (if defined) , and configures the baud rate as PICO_DEFAULT_UART_BAUD_RATE

Linking this library or calling pico_enable_stdio_rtt(TARGET) in the CMake (which achieves the same thing) will add RTT to the drivers used for standard output

void stdio_rtt_deinit (void)

Explicitly deinitialize stdin/stdout over RTT and remove it from the current set of stdin/stdout drivers.

void stdio_rtt_init (void)

Explicitly initialize stdin/stdout over RTT and add it to the current set of stdin/stdout drivers.

Linking this library or calling pico_enable_stdio_usb(TARGET ENABLED) in the CMake (which achieves the same thing) will add USB CDC to the drivers used for standard input/output

Note this library is a developer convenience. It is not applicable in all cases; for one it takes full control of the USB device precluding your use of the USB in device or host mode. For this reason, this library will automatically disengage if you try to using it alongside tinyusb_device or tinyusb_host. It also takes control of a lower level IRQ and sets up a periodic background task.

This library also includes (by default) functionality to enable the RP-series microcontroller to be reset over the USB interface.

void stdio_usb_call_chars_available_callback (void)

Explicitly calls the registered USB stdio chars_available_callback.

This method is normally called by the internal USB stdio background thread when there is new USB CDC data available to read. However, if the internal background thread is disabled (e.g. when the user directly links tinyUSB), the user will need to implement their own background thread and call this method directly.

bool stdio_usb_connected (void)

Check if there is an active stdio CDC connection to a host.

bool stdio_usb_deinit (void)

Explicitly deinitialize USB stdio and remove it from the current set of stdin drivers.

bool stdio_usb_init (void)

Explicitly initialize USB stdio and add it to the current set of stdin drivers.

PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS can be set to cause this method to wait for a CDC connection from the host before returning, which is useful if you don’t want any initial stdout output to be discarded before the connection is established.

Copyright (c) 2020 Raspberry Pi (Trading) Ltd.

SPDX-License-Identifier: BSD-3-Clause