Raspberry Pi Documentation

Release 1.5.0

Runtime Infrastructure

Libraries that are used to provide efficient implementation of certain language level and C library functions, as well as CMake INTERFACE libraries abstracting the compilation and link steps in the SDK

boot_stage2

Second stage boot loaders responsible for setting up external flash.

Second stage boot loaders responsible for setting up external flash.

pico_base

Enumerations

  • enum  pico_error_codes {
      PICO_OK = 0 , PICO_ERROR_NONE = 0 , PICO_ERROR_TIMEOUT = -1 , PICO_ERROR_GENERIC = -2 ,
      PICO_ERROR_NO_DATA = -3 , PICO_ERROR_NOT_PERMITTED = -4 , PICO_ERROR_INVALID_ARG = -5 , PICO_ERROR_IO = -6 ,
      PICO_ERROR_BADAUTH = -7 , PICO_ERROR_CONNECT_FAILED = -8
    }

  •  Common return codes from pico_sdk methods that return a status.

Detailed Description

Core types and macros for the Raspberry Pi Pico SDK. This header is intended to be included by all source code as it includes configuration headers and overrides in the correct order

This header may be included by assembly code

pico_binary_info

Macros

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

  • #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.", ); *(volatile uint8_t *)&__bi_ptr_lineno_var_name;});

Detailed Description

Binary info is intended for embedding machine readable information with the binary in FLASH.

Example uses include:

  • Program identification / information

  • Pin layouts

  • Included features

  • Identifying flash regions used as block devices/storage

Macro Definition Documentation

◆ bi_decl

#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

◆ bi_decl_if_func_used

#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.", ); *(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

pico_bit_ops

Functions

  • uint32_t __rev (uint32_t bits)

  •  Reverse the bits in a 32 bit word.

  • uint64_t __revll (uint64_t bits)

  •  Reverse the bits in a 64 bit double word.

Detailed Description

Optimized bit manipulation functions. Additionally provides replacement implementations of the compiler built-ins __builtin_popcount, __builtin_clz and __bulitin_ctz

Function Documentation

◆ __rev()

uint32_t __rev ( uint32_t  bits )

Reverse the bits in a 32 bit word.

Parameters

bits 32 bit input

Returns

the 32 input bits reversed

◆ __revll()

uint64_t __revll ( uint64_t  bits )

Reverse the bits in a 64 bit double word.

Parameters

bits 64 bit input

Returns

the 64 input bits reversed

pico_bootrom

Macros

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

  •  Return a bootrom lookup code based on two ASCII characters.

Functions

  • static uint32_t rom_table_code (uint8_t c1, uint8_t c2)

  •  Return a bootrom lookup code based on two ASCII characters.

  • void * rom_func_lookup (uint32_t code)

  •  Lookup a bootrom function by code.

  • void * rom_data_lookup (uint32_t code)

  •  Lookup a bootrom address by code.

  • bool rom_funcs_lookup (uint32_t *table, unsigned int count)

  •  Helper function to lookup the addresses of multiple bootrom functions.

  • static __force_inline void * rom_func_lookup_inline (uint32_t code)

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

  • static void reset_usb_boot (uint32_t usb_activity_gpio_pin_mask, uint32_t disable_interface_mask)

  •  Reboot the device into BOOTSEL mode.

Detailed Description

Access to functions and data in the RP2040 bootrom

This header may be included by assembly code

Macro Definition Documentation

◆ ROM_TABLE_CODE

#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

c1 the first character
c2 the second character

Returns

the 'code' to use in rom_func_lookup() or rom_data_lookup()

Function Documentation

◆ reset_usb_boot()

static void reset_usb_boot ( uint32_t  usb_activity_gpio_pin_mask,
uint32_t  disable_interface_mask 
)
inlinestatic

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

usb_activity_gpio_pin_mask 0 No pins are used as per a cold boot. Otherwise a single bit set indicating which GPIO pin should be set to output and raised whenever there is mass storage activity from the host.
disable_interface_mask value to control exposed interfaces
  • 0 To enable both interfaces (as per a cold boot)

  • 1 To disable the USB Mass Storage Interface

  • 2 To disable the USB PICOBOOT Interface

◆ rom_data_lookup()

void * rom_data_lookup ( uint32_t  code )

Lookup a bootrom address by code.

Parameters

code the code

Returns

a pointer to the data, or NULL if the code does not match any bootrom function

◆ rom_func_lookup()

void * rom_func_lookup ( uint32_t  code )

Lookup a bootrom function by code.

Parameters

code the code

Returns

a pointer to the function, or NULL if the code does not match any bootrom function

◆ rom_func_lookup_inline()

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

code the code

Returns

a pointer to the function, or NULL if the code does not match any bootrom function

◆ rom_funcs_lookup()

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

table an IN/OUT array, elements are codes on input, function pointers on success.
count the number of elements in the table

Returns

true if all the codes were found, and converted to function pointers, false otherwise

◆ rom_table_code()

static uint32_t rom_table_code ( uint8_t  c1,
uint8_t  c2 
)
inlinestatic

Return a bootrom lookup code based on two ASCII characters.

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

Parameters

c1 the first character
c2 the second character

Returns

the 'code' to use in rom_func_lookup() or rom_data_lookup()

pico_bootsel_via_double_reset

When the 'pico_bootsel_via_double_reset' library is linked, a function is injected before main() which will detect when the system has been reset twice in quick succession, and enter the USB ROM bootloader (BOOTSEL mode) when this happens. This allows a double tap of a reset button on a development board to be used to enter the ROM bootloader, provided this library is always linked.

pico_cxx_options

non-code library controlling C++ related compile options

non-code library controlling C++ related compile options

pico_divider

Files

  • file  divider.h

  •  High level APIs including combined quotient and remainder functions for 32 and 64 bit accelerated by the hardware divider.

Functions

  • int32_t div_s32s32 (int32_t a, int32_t b)

  •  Integer divide of two signed 32-bit values.

  • static int32_t divmod_s32s32_rem (int32_t a, int32_t b, int32_t *rem)

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

  • divmod_result_t divmod_s32s32 (int32_t a, int32_t b)

  •  Integer divide of two signed 32-bit values.

  • uint32_t div_u32u32 (uint32_t a, uint32_t b)

  •  Integer divide of two unsigned 32-bit values.

  • static uint32_t divmod_u32u32_rem (uint32_t a, uint32_t b, uint32_t *rem)

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

  • divmod_result_t divmod_u32u32 (uint32_t a, uint32_t b)

  •  Integer divide of two unsigned 32-bit values.

  • int64_t div_s64s64 (int64_t a, int64_t b)

  •  Integer divide of two signed 64-bit values.

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

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

  • int64_t divmod_s64s64 (int64_t a, int64_t b)

  •  Integer divide of two signed 64-bit values.

  • uint64_t div_u64u64 (uint64_t a, uint64_t b)

  •  Integer divide of two unsigned 64-bit values.

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

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

  • uint64_t divmod_u64u64 (uint64_t a, uint64_t b)

  •  Integer divide of two signed 64-bit values.

  • int32_t div_s32s32_unsafe (int32_t a, int32_t b)

  •  Unsafe integer divide of two signed 32-bit values.

  • 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.

  • int64_t divmod_s32s32_unsafe (int32_t a, int32_t b)

  •  Unsafe integer divide of two unsigned 32-bit values.

  • uint32_t div_u32u32_unsafe (uint32_t a, uint32_t b)

  •  Unsafe integer divide of two unsigned 32-bit values.

  • 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.

  • uint64_t divmod_u32u32_unsafe (uint32_t a, uint32_t b)

  •  Unsafe integer divide of two unsigned 32-bit values.

  • int64_t div_s64s64_unsafe (int64_t a, int64_t b)

  •  Unsafe integer divide of two signed 64-bit values.

  • 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.

  • int64_t divmod_s64s64_unsafe (int64_t a, int64_t b)

  •  Unsafe integer divide of two signed 64-bit values.

  • uint64_t div_u64u64_unsafe (uint64_t a, uint64_t b)

  •  Unsafe integer divide of two unsigned 64-bit values.

  • 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.

  • uint64_t divmod_u64u64_unsafe (uint64_t a, uint64_t b)

  •  Unsafe integer divide of two signed 64-bit values.

Detailed Description

Optimized 32 and 64 bit division functions accelerated by the RP2040 hardware divider. Additionally provides integration with the C / and % operators

Function Documentation

◆ div_s32s32()

int32_t div_s32s32 ( int32_t  a,
int32_t  b 
)

Integer divide of two signed 32-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient

◆ div_s32s32_unsafe()

int32_t div_s32s32_unsafe ( int32_t  a,
int32_t  b 
)

Unsafe integer divide of two signed 32-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient

Do not use in interrupts

◆ div_s64s64()

int64_t div_s64s64 ( int64_t  a,
int64_t  b 
)

Integer divide of two signed 64-bit values.

Parameters

a Dividend
b Divisor

Returns

Quotient

◆ div_s64s64_unsafe()

int64_t div_s64s64_unsafe ( int64_t  a,
int64_t  b 
)

Unsafe integer divide of two signed 64-bit values.

Parameters

a Dividend
b Divisor

Returns

Quotient

Do not use in interrupts

◆ div_u32u32()

uint32_t div_u32u32 ( uint32_t  a,
uint32_t  b 
)

Integer divide of two unsigned 32-bit values.

Parameters

a Dividend
b Divisor

Returns

Quotient

◆ div_u32u32_unsafe()

uint32_t div_u32u32_unsafe ( uint32_t  a,
uint32_t  b 
)

Unsafe integer divide of two unsigned 32-bit values.

Parameters

a Dividend
b Divisor

Returns

Quotient

Do not use in interrupts

◆ div_u64u64()

uint64_t div_u64u64 ( uint64_t  a,
uint64_t  b 
)

Integer divide of two unsigned 64-bit values.

Parameters

a Dividend
b Divisor

Returns

Quotient

◆ div_u64u64_unsafe()

uint64_t div_u64u64_unsafe ( uint64_t  a,
uint64_t  b 
)

Unsafe integer divide of two unsigned 64-bit values.

Parameters

a Dividend
b Divisor

Returns

Quotient

Do not use in interrupts

◆ divmod_s32s32()

divmod_result_t divmod_s32s32 ( int32_t  a,
int32_t  b 
)

Integer divide of two signed 32-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient in low word/r0, remainder in high word/r1

◆ divmod_s32s32_rem()

static int32_t divmod_s32s32_rem ( int32_t  a,
int32_t  b,
int32_t *  rem 
)
inlinestatic

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

Parameters

a Dividend
b Divisor
[out] rem The remainder of dividend/divisor

Returns

Quotient result of dividend/divisor

◆ divmod_s32s32_rem_unsafe()

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

a Dividend
b Divisor
[out] rem The remainder of dividend/divisor

Returns

Quotient result of dividend/divisor

Do not use in interrupts

◆ divmod_s32s32_unsafe()

int64_t divmod_s32s32_unsafe ( int32_t  a,
int32_t  b 
)

Unsafe integer divide of two unsigned 32-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient in low word/r0, remainder in high word/r1

Do not use in interrupts

◆ divmod_s64s64()

int64_t divmod_s64s64 ( int64_t  a,
int64_t  b 
)

Integer divide of two signed 64-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient in result (r0,r1), remainder in regs (r2, r3)

◆ divmod_s64s64_rem()

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

a Dividend
b Divisor
[out] rem The remainder of dividend/divisor

Returns

Quotient result of dividend/divisor

◆ divmod_s64s64_rem_unsafe()

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

a Dividend
b Divisor
[out] rem The remainder of dividend/divisor

Returns

Quotient result of dividend/divisor

Do not use in interrupts

◆ divmod_s64s64_unsafe()

int64_t divmod_s64s64_unsafe ( int64_t  a,
int64_t  b 
)

Unsafe integer divide of two signed 64-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient in result (r0,r1), remainder in regs (r2, r3)

Do not use in interrupts

◆ divmod_u32u32()

divmod_result_t divmod_u32u32 ( uint32_t  a,
uint32_t  b 
)

Integer divide of two unsigned 32-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient in low word/r0, remainder in high word/r1

◆ divmod_u32u32_rem()

static uint32_t divmod_u32u32_rem ( uint32_t  a,
uint32_t  b,
uint32_t *  rem 
)
inlinestatic

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

Parameters

a Dividend
b Divisor
[out] rem The remainder of dividend/divisor

Returns

Quotient result of dividend/divisor

◆ divmod_u32u32_rem_unsafe()

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

a Dividend
b Divisor
[out] rem The remainder of dividend/divisor

Returns

Quotient result of dividend/divisor

Do not use in interrupts

◆ divmod_u32u32_unsafe()

uint64_t divmod_u32u32_unsafe ( uint32_t  a,
uint32_t  b 
)

Unsafe integer divide of two unsigned 32-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient in low word/r0, remainder in high word/r1

Do not use in interrupts

◆ divmod_u64u64()

uint64_t divmod_u64u64 ( uint64_t  a,
uint64_t  b 
)

Integer divide of two signed 64-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient in result (r0,r1), remainder in regs (r2, r3)

◆ divmod_u64u64_rem()

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

a Dividend
b Divisor
[out] rem The remainder of dividend/divisor

Returns

Quotient result of dividend/divisor

◆ divmod_u64u64_rem_unsafe()

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

a Dividend
b Divisor
[out] rem The remainder of dividend/divisor

Returns

Quotient result of dividend/divisor

Do not use in interrupts

◆ divmod_u64u64_unsafe()

uint64_t divmod_u64u64_unsafe ( uint64_t  a,
uint64_t  b 
)

Unsafe integer divide of two signed 64-bit values.

Parameters

a Dividend
b Divisor

Returns

quotient in result (r0,r1), remainder in regs (r2, r3)

Do not use in interrupts

pico_double

Optimized double-precision floating point functions

(Replacement) optimized implementations are provided of the following compiler built-ins and math library functions:

  • __aeabi_dadd, __aeabi_ddiv, __aeabi_dmul, __aeabi_drsub, __aeabi_dsub, __aeabi_cdcmpeq, __aeabi_cdrcmple, __aeabi_cdcmple, __aeabi_dcmpeq, __aeabi_dcmplt, __aeabi_dcmple, __aeabi_dcmpge, __aeabi_dcmpgt, __aeabi_dcmpun, __aeabi_i2d, __aeabi_l2d, __aeabi_ui2d, __aeabi_ul2d, __aeabi_d2iz, __aeabi_d2lz, __aeabi_d2uiz, __aeabi_d2ulz, __aeabi_d2f

  • sqrt, cos, sin, tan, atan2, exp, log, ldexp, copysign, trunc, floor, ceil, round, asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh, exp2, log2, exp10, log10, pow,, hypot, cbrt, fmod, drem, remainder, remquo, expm1, log1p, fma

  • powint, sincos (GNU extensions)

The following additional optimized functions are also provided:

  • fix2double, ufix2double, fix642double, ufix642double, double2fix, double2ufix, double2fix64, double2ufix64, double2int, double2int64, double2int_z, double2int64_z

pico_float

Optimized single-precision floating point functions

(Replacement) optimized implementations are provided of the following compiler built-ins and math library functions:

  • __aeabi_fadd, __aeabi_fdiv, __aeabi_fmul, __aeabi_frsub, __aeabi_fsub, __aeabi_cfcmpeq, __aeabi_cfrcmple, __aeabi_cfcmple, __aeabi_fcmpeq, __aeabi_fcmplt, __aeabi_fcmple, __aeabi_fcmpge, __aeabi_fcmpgt, __aeabi_fcmpun, __aeabi_i2f, __aeabi_l2f, __aeabi_ui2f, __aeabi_ul2f, __aeabi_f2iz, __aeabi_f2lz, __aeabi_f2uiz, __aeabi_f2ulz, __aeabi_f2d, sqrtf, cosf, sinf, tanf, atan2f, expf, logf

  • ldexpf, copysignf, truncf, floorf, ceilf, roundf, asinf, acosf, atanf, sinhf, coshf, tanhf, asinhf, acoshf, atanhf, exp2f, log2f, exp10f, log10f, powf, hypotf, cbrtf, fmodf, dremf, remainderf, remquof, expm1f, log1pf, fmaf

  • powintf, sincosf (GNU extensions)

The following additional optimized functions are also provided:

  • fix2float, ufix2float, fix642float, ufix642float, float2fix, float2ufix, float2fix64, float2ufix64, float2int, float2int64, float2int_z, float2int64_z

pico_int64_ops

Optimized replacement implementations of the compiler built-in 64 bit multiplication

This library does not provide any additional functions

pico_malloc

Multi-core safety for malloc, calloc and free

This library does not provide any additional functions

pico_mem_ops

Provides optimized replacement implementations of the compiler built-in memcpy, memset and related functions:

  • memset, memcpy

  • __aeabi_memset, __aeabi_memset4, __aeabi_memset8, __aeabi_memcpy, __aeabi_memcpy4, __aeabi_memcpy8

This library does not provide any additional functions

pico_platform

Macros

  • #define __isr

  •  Marker for an interrupt handlerFor example an IRQ handler function called my_interrupt_handler:

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

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

  • #define __not_in_flash(group)   __attribute__((section(".time_critical." group)))

  •  Section attribute macro for placement not in flash (i.e in RAM)

  • #define __scratch_x(group)   __attribute__((section(".scratch_x." group)))

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

  • #define __scratch_y(group)   __attribute__((section(".scratch_y." group)))

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

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

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

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

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

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

  •  Indicates a function should not be stored in flash.

  • #define __time_critical_func(func_name)   __not_in_flash_func(func_name)

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

  • #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.

  • #define __force_inline   __always_inline

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

  • #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 host_safe_hw_ptr(x)   ((uintptr_t)(x))

  •  Macro for converting memory addresses to 32 bit addresses suitable for DMA.

  • #define __fast_mul(a, b)

  •  multiply two integer values using the fastest method possible

  • #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.

Functions

  • static void __breakpoint (void)

  •  Execute a breakpoint instruction.

  • static __always_inline void __compiler_memory_barrier (void)

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

  • void panic_unsupported (void)

  •  Panics with the message "Unsupported".

  • void panic (const char *fmt,...)

  •  Displays a panic message and halts execution.

  • uint8_t rp2040_chip_version (void)

  •  Returns the RP2040 chip revision number.

  • static uint8_t rp2040_rom_version (void)

  •  Returns the RP2040 rom version number.

  • static __always_inline void tight_loop_contents (void)

  •  No-op function for the body of tight loops.

  • static __always_inline int32_t __mul_instruction (int32_t a, int32_t b)

  •  Multiply two integers using an assembly MUL instruction.

  • static uint __get_current_exception (void)

  •  Get the current exception level on this core.

  • static void busy_wait_at_least_cycles (uint32_t minimum_cycles)

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

  • static __always_inline uint get_core_num (void)

  •  Get the current core number.

Detailed Description

Macros and definitions (and functions when included by non assembly code) for the RP2 family device / architecture to provide a common abstraction over low level compiler / platform specifics.

This header may be included by assembly code

Macro Definition Documentation

◆ __after_data

#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

uint32_t __after_data("my_group_name") a_big_array[400];

The section attribute is .after_data.<group>

Parameters

group a string suffix to use in the section name to distinguish groups that can be linker garbage-collected independently

◆ __check_type_compatible

#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)

◆ __fast_mul

#define __fast_mul (   a,
 
)
Value:
__builtin_choose_expr(__builtin_constant_p(b) && !__builtin_constant_p(a), \
(__builtin_popcount(b) >= 2 ? __mul_instruction(a,b) : (a)*(b)), \
(a)*(b))
static __always_inline int32_t __mul_instruction(int32_t a, int32_t b)
Multiply two integers using an assembly MUL instruction.
Definition: platform.h:370

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

a the first operand
b the second operand

Returns

a * b

◆ __force_inline

#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:

int __force_inline my_function(int x) {

◆ __in_flash

#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!)

uint32_t __in_flash("my_group_name") foo = 23;

The section attribute is .flashdata.<group>

Parameters

group a string suffix to use in the section name to distinguish groups that can be linker garbage-collected independently

◆ __isr

#define __isr

Marker for an interrupt handlerFor example an IRQ handler function called my_interrupt_handler:

void __isr my_interrupt_handler(void) {

◆ __no_inline_not_in_flash_func

#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:

void __no_inline_not_in_flash_func(my_func)(int some_arg) {

The function is placed in the .time_critical.<func_name> linker section

◆ __not_in_flash

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

Section attribute macro for placement not in flash (i.e in RAM)

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

static const uint32_t __not_in_flash("my_group_name") an_array[3];

The section attribute is .time_critical.<group>

Parameters

group a string suffix to use in the section name to distinguish groups that can be linker garbage-collected independently

◆ __not_in_flash_func

#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:

void __not_in_flash_func(my_func)(int some_arg) {

The function is placed in the .time_critical.<func_name> linker section

See also__no_inline_not_in_flash_func

◆ __scratch_x

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

Section attribute macro for placement in the SRAM bank 4 (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"

uint32_t __scratch_x("my_group_name") foo = 23;

The section attribute is .scratch_x.<group>

Parameters

group a string suffix to use in the section name to distinguish groups that can be linker garbage-collected independently

◆ __scratch_y

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

Section attribute macro for placement in the SRAM bank 5 (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"

uint32_t __scratch_y("my_group_name") foo = 23;

The section attribute is .scratch_y.<group>

Parameters

group a string suffix to use in the section name to distinguish groups that can be linker garbage-collected independently

◆ __time_critical_func

#define __time_critical_func (   func_name )    __not_in_flash_func(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 (assuming it is not inlined into a flash function by the compiler) to avoid possible flash latency. Currently this macro is identical in implementation to __not_in_flash_func, however the semantics are distinct and a __time_critical_func may in the future be treated more specially to reduce the overhead when calling such function from a flash function.

For example a function called my_func taking an int parameter:

void __time_critical(my_func)(int some_arg) {

The function is placed in the .time_critical.<func_name> linker section

See also__not_in_flash_func

◆ __uninitialized_ram

#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.

uint32_t __uninitialized_ram(foo);

The section attribute is .uninitialized_data.<group>

Parameters

group a string suffix to use in the section name to distinguish groups that can be linker garbage-collected independently

◆ host_safe_hw_ptr

#define host_safe_hw_ptr (   x )    ((uintptr_t)(x))

Macro for converting memory addresses to 32 bit addresses suitable for DMA.

This is just a cast to uintptr_t on the RP2040, however you may want to use this when developing code that also runs in "host" mode. If the host mode is 64 bit and you are embedding data pointers in other data (e.g. DMA chaining), then there is a need in "host" mode to convert a 64 bit native pointer to a 32 bit value for storage, which can be done using this macro.

Function Documentation

◆ __compiler_memory_barrier()

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:

*some_memory_location = var_a;
__compiler_memory_barrier();
uint32_t var_b = *some_other_memory_location

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!)

◆ __get_current_exception()

static uint __get_current_exception ( void  )
inlinestatic

Get the current exception level on this core.

Returns

the exception number if the CPU is handling an exception, or 0 otherwise

◆ __mul_instruction()

static __always_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

a the first operand
b the second operand

Returns

a * b

◆ busy_wait_at_least_cycles()

static void busy_wait_at_least_cycles ( uint32_t  minimum_cycles )
inlinestatic

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

minimum_cycles the minimum number of system clock cycles to delay for

◆ get_core_num()

static __always_inline uint get_core_num ( void  )
static

Get the current core number.

Returns

The core number the call was made from

◆ panic()

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

fmt format string (printf-like)
... printf-like arguments

◆ panic_unsupported()

void panic_unsupported ( void  )

Panics with the message "Unsupported".

See alsopanic

◆ rp2040_chip_version()

uint8_t rp2040_chip_version ( void  )

Returns the RP2040 chip revision number.

Returns

the RP2040 chip revision number (1 for B0/B1, 2 for B2)

◆ rp2040_rom_version()

static uint8_t rp2040_rom_version ( void  )
inlinestatic

Returns the RP2040 rom version number.

Returns

the RP2040 rom version number (1 for RP2040-B0, 2 for RP2040-B1, 3 for RP2040-B2)

◆ tight_loop_contents()

static __always_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

pico_printf

Compact replacement for printf by Marco Paland (info@.nosp@m.pala.nosp@m.nd.co.nosp@m.m)

pico_stdio

Modules

Functions

  • bool stdio_init_all (void)

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

  • void stdio_flush (void)

  •  Flushes any buffered output.

  • int getchar_timeout_us (uint32_t timeout_us)

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

  • 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.

  • void stdio_filter_driver (stdio_driver_t *driver)

  •  Control limiting of output to a single driver.

  • void stdio_set_translate_crlf (stdio_driver_t *driver, bool translate)

  •  control conversion of line feeds to carriage return on transmissions

  • int putchar_raw (int c)

  •  putchar variant that skips any CR/LF conversion if enabled

  • int puts_raw (const char *s)

  •  puts variant that skips any CR/LF conversion if enabled

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

  •  get notified when there are input characters available

Detailed Description

Customized stdio support allowing for input and output from UART, USB, semi-hosting etc.

Note the API for adding additional input output devices is not yet considered stable

Function Documentation

◆ getchar_timeout_us()

int getchar_timeout_us ( uint32_t  timeout_us )

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

Parameters

timeout_us the timeout in microseconds, or 0 to not wait for a character if none available.

Returns

the character from 0-255 or PICO_ERROR_TIMEOUT if timeout occurs

◆ stdio_filter_driver()

void stdio_filter_driver ( stdio_driver_t driver )

Control limiting of output to a single driver.

Note
this method should always be called on an initialized driver

Parameters

driver if non-null then output only that driver will be used for input/output (assuming it is in the list of enabled drivers). if NULL then all enabled drivers will be used

◆ stdio_init_all()

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 and semihosting 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)

Returns

true if at least one output was successfully initialized, false otherwise.

See alsostdio_uart, stdio_usb, stdio_semihosting

◆ stdio_set_chars_available_callback()

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

get notified when there are input characters available

Parameters

fn Callback function to be called when characters are available. Pass NULL to cancel any existing callback
param Pointer to pass to the callback

◆ stdio_set_driver_enabled()

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.

Note
this method should always be called on an initialized driver and is not re-entrant

Parameters

driver the driver
enabled true to add, false to remove

◆ stdio_set_translate_crlf()

void stdio_set_translate_crlf ( stdio_driver_t driver,
bool  translate 
)

control conversion of line feeds to carriage return on transmissions

Note
this method should always be called on an initialized driver

Parameters

driver the driver
translate If true, convert line feeds to carriage return on transmissions

pico_stdio_semihosting

Experimental support for stdout using RAM semihosting. More...

Functions

  • void stdio_semihosting_init (void)

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

Detailed Description

Experimental support for stdout using RAM semihosting.

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

Function Documentation

◆ stdio_semihosting_init()
void stdio_semihosting_init ( void  )

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

Note
this method is automatically called by stdio_init_all() if pico_stdio_semihosting is included in the build

pico_stdio_uart

Support for stdin/stdout using UART. More...

Functions

  • void stdio_uart_init (void)

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

  • void stdout_uart_init (void)

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

  • void stdin_uart_init (void)

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

  • 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.

Detailed Description

Support for stdin/stdout using UART.

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

Function Documentation

◆ stdin_uart_init()
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

◆ stdio_uart_init()
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.

Note
this method is automatically called by stdio_init_all() if pico_stdio_uart is included in the build
◆ stdio_uart_init_full()
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

uart the uart instance to use, uart0 or uart1
baud_rate the baud rate in Hz
tx_pin the UART pin to use for stdout (or -1 for no stdout)
rx_pin the UART pin to use for stdin (or -1 for no stdin)
◆ stdout_uart_init()
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

pico_stdio_usb

Support for stdin/stdout over USB serial (CDC) More...

Functions

  • bool stdio_usb_init (void)

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

  • bool stdio_usb_connected (void)

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

Detailed Description

Support for stdin/stdout over USB serial (CDC)

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 RP2040 to be reset over the USB interface.

Function Documentation

◆ stdio_usb_connected()
bool stdio_usb_connected ( void  )

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

Returns

true if stdio is connected over CDC

◆ stdio_usb_init()
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.

Returns

true if the USB CDC was initialized, false if an error occurred

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

SPDX-License-Identifier: BSD-3-Clause

Standard link step providing the basics for creating a runnable binary.

Standard link step providing the basics for creating a runnable binary.

This includes

  • C runtime initialization

  • Linker scripts for 'default', 'no_flash', 'blocked_ram' and 'copy_to_ram' binaries

  • 'Binary Information' support

  • Linker option control