Raspberry Pi Documentation

Release 1.5.1

Hardware APIs

This group of libraries provides a thin and efficient C API / abstractions to access the RP2040 hardware without having to read and write hardware registers directly.

hardware_adc

Part of: Hardware APIs

Functions

  • void adc_init (void)

  •  Initialise the ADC HW.

  • static void adc_gpio_init (uint gpio)

  •  Initialise the gpio for use as an ADC pin.

  • static void adc_select_input (uint input)

  •  ADC input select.

  • static uint adc_get_selected_input (void)

  •  Get the currently selected ADC input channel.

  • static void adc_set_round_robin (uint input_mask)

  •  Round Robin sampling selector.

  • static void adc_set_temp_sensor_enabled (bool enable)

  •  Enable the onboard temperature sensor.

  • static uint16_t adc_read (void)

  •  Perform a single conversion.

  • static void adc_run (bool run)

  •  Enable or disable free-running sampling mode.

  • static void adc_set_clkdiv (float clkdiv)

  •  Set the ADC Clock divisor.

  • static void adc_fifo_setup (bool en, bool dreq_en, uint16_t dreq_thresh, bool err_in_fifo, bool byte_shift)

  •  Setup the ADC FIFO.

  • static bool adc_fifo_is_empty (void)

  •  Check FIFO empty state.

  • static uint8_t adc_fifo_get_level (void)

  •  Get number of entries in the ADC FIFO.

  • static uint16_t adc_fifo_get (void)

  •  Get ADC result from FIFO.

  • static uint16_t adc_fifo_get_blocking (void)

  •  Wait for the ADC FIFO to have data.

  • static void adc_fifo_drain (void)

  •  Drain the ADC FIFO.

  • static void adc_irq_set_enabled (bool enabled)

  •  Enable/Disable ADC interrupts.

Detailed Description

Analog to Digital Converter (ADC) API

The RP2040 has an internal analogue-digital converter (ADC) with the following features:

  • SAR ADC

  • 500 kS/s (Using an independent 48MHz clock)

  • 12 bit (8.7 ENOB)

  • 5 input mux:

    • 4 inputs that are available on package pins shared with GPIO[29:26]

    • 1 input is dedicated to the internal temperature sensor

  • 4 element receive sample FIFO

  • Interrupt generation

  • DMA interface

Although there is only one ADC you can specify the input to it using the adc_select_input() function. In round robin mode (adc_set_round_robin()), the ADC will use that input and move to the next one after a read.

User ADC inputs are on 0-3 (GPIO 26-29), the temperature sensor is on input 4.

Temperature sensor values can be approximated in centigrade as:

T = 27 - (ADC_Voltage - 0.706)/0.001721

The FIFO, if used, can contain up to 4 entries.

Example

#include <stdio.h>
#include "pico/stdlib.h"
#include "hardware/gpio.h"
#include "hardware/adc.h"
int main() {
printf("ADC Example, measuring GPIO26\n");
// Make sure GPIO is high-impedance, no pullups etc
// Select ADC input 0 (GPIO26)
while (1) {
// 12-bit conversion, assume max value == ADC_VREF == 3.3 V
const float conversion_factor = 3.3f / (1 << 12);
uint16_t result = adc_read();
printf("Raw value: 0x%03x, voltage: %f V\n", result, result * conversion_factor);
sleep_ms(500);
}
}
void adc_init(void)
Initialise the ADC HW.
Definition: adc.c:11
static void adc_select_input(uint input)
ADC input select.
Definition: adc.h:86
static void adc_gpio_init(uint gpio)
Initialise the gpio for use as an ADC pin.
Definition: adc.h:69
static uint16_t adc_read(void)
Perform a single conversion.
Definition: adc.h:133
bool stdio_init_all(void)
Initialize all of the present standard stdio types that are linked into the binary.
Definition: stdio.c:283
void sleep_ms(uint32_t ms)
Wait for the given number of milliseconds before returning.
Definition: time.c:429

Function Documentation

◆ adc_fifo_drain()

static void adc_fifo_drain ( void  )
inlinestatic

Drain the ADC FIFO.

Will wait for any conversion to complete then drain the FIFO, discarding any results.

◆ adc_fifo_get()

static uint16_t adc_fifo_get ( void  )
inlinestatic

Get ADC result from FIFO.

Pops the latest result from the ADC FIFO.

◆ adc_fifo_get_blocking()

static uint16_t adc_fifo_get_blocking ( void  )
inlinestatic

Wait for the ADC FIFO to have data.

Blocks until data is present in the FIFO

◆ adc_fifo_get_level()

static uint8_t adc_fifo_get_level ( void  )
inlinestatic

Get number of entries in the ADC FIFO.

The ADC FIFO is 4 entries long. This function will return how many samples are currently present.

◆ adc_fifo_is_empty()

static bool adc_fifo_is_empty ( void  )
inlinestatic

Check FIFO empty state.

Returns

Returns true if the FIFO is empty

◆ adc_fifo_setup()

static void adc_fifo_setup ( bool  en,
bool  dreq_en,
uint16_t  dreq_thresh,
bool  err_in_fifo,
bool  byte_shift 
)
inlinestatic

Setup the ADC FIFO.

FIFO is 4 samples long, if a conversion is completed and the FIFO is full, the result is dropped.

Parameters

en Enables write each conversion result to the FIFO
dreq_en Enable DMA requests when FIFO contains data
dreq_thresh Threshold for DMA requests/FIFO IRQ if enabled.
err_in_fifo If enabled, bit 15 of the FIFO contains error flag for each sample
byte_shift Shift FIFO contents to be one byte in size (for byte DMA) - enables DMA to byte buffers.

◆ adc_get_selected_input()

static uint adc_get_selected_input ( void  )
inlinestatic

Get the currently selected ADC input channel.

Returns

The currently selected input channel. 0...3 are GPIOs 26...29 respectively. Input 4 is the onboard temperature sensor.

◆ adc_gpio_init()

static void adc_gpio_init ( uint  gpio )
inlinestatic

Initialise the gpio for use as an ADC pin.

Prepare a GPIO for use with ADC by disabling all digital functions.

Parameters

gpio The GPIO number to use. Allowable GPIO numbers are 26 to 29 inclusive.

◆ adc_init()

void adc_init ( void  )

Initialise the ADC HW.

◆ adc_irq_set_enabled()

static void adc_irq_set_enabled ( bool  enabled )
inlinestatic

Enable/Disable ADC interrupts.

Parameters

enabled Set to true to enable the ADC interrupts, false to disable

◆ adc_read()

static uint16_t adc_read ( void  )
inlinestatic

Perform a single conversion.

Performs an ADC conversion, waits for the result, and then returns it.

Returns

Result of the conversion.

◆ adc_run()

static void adc_run ( bool  run )
inlinestatic

Enable or disable free-running sampling mode.

Parameters

run false to disable, true to enable free running conversion mode.

◆ adc_select_input()

static void adc_select_input ( uint  input )
inlinestatic

ADC input select.

Select an ADC input. 0...3 are GPIOs 26...29 respectively. Input 4 is the onboard temperature sensor.

Parameters

input Input to select.

◆ adc_set_clkdiv()

static void adc_set_clkdiv ( float  clkdiv )
inlinestatic

Set the ADC Clock divisor.

Period of samples will be (1 + div) cycles on average. Note it takes 96 cycles to perform a conversion, so any period less than that will be clamped to 96.

Parameters

clkdiv If non-zero, conversion will be started at intervals rather than back to back.

◆ adc_set_round_robin()

static void adc_set_round_robin ( uint  input_mask )
inlinestatic

Round Robin sampling selector.

This function sets which inputs are to be run through in round robin mode. Value between 0 and 0x1f (bit 0 to bit 4 for GPIO 26 to 29 and temperature sensor input respectively)

Parameters

input_mask A bit pattern indicating which of the 5 inputs are to be sampled. Write a value of 0 to disable round robin sampling.

◆ adc_set_temp_sensor_enabled()

static void adc_set_temp_sensor_enabled ( bool  enable )
inlinestatic

Enable the onboard temperature sensor.

Parameters

enable Set true to power on the onboard temperature sensor, false to power off.

hardware_base

Part of: Hardware APIs

Functions

  • static __force_inline void hw_set_bits (io_rw_32 *addr, uint32_t mask)

  •  Atomically set the specified bits to 1 in a HW register.

  • static __force_inline void hw_clear_bits (io_rw_32 *addr, uint32_t mask)

  •  Atomically clear the specified bits to 0 in a HW register.

  • static __force_inline void hw_xor_bits (io_rw_32 *addr, uint32_t mask)

  •  Atomically flip the specified bits in a HW register.

  • static __force_inline void hw_write_masked (io_rw_32 *addr, uint32_t values, uint32_t write_mask)

  •  Set new values for a sub-set of the bits in a HW register.

Detailed Description

Low-level types and (atomic) accessors for memory-mapped hardware registers

hardware_base defines the low level types and access functions for memory mapped hardware registers. It is included by default by all other hardware libraries.

The following register access typedefs codify the access type (read/write) and the bus size (8/16/32) of the hardware register. The register type names are formed by concatenating one from each of the 3 parts A, B, C

A B C Meaning
io_ A Memory mapped IO register
  ro_ read-only access
  rw_ read-write access
  wo_ write-only access (can't actually be enforced via C API)
  8 8-bit wide access
  16 16-bit wide access
  32 32-bit wide access

When dealing with these types, you will always use a pointer, i.e. io_rw_32 *some_reg is a pointer to a read/write 32 bit register that you can write with *some_reg = value, or read with value = *some_reg.

RP2040 hardware is also aliased to provide atomic setting, clear or flipping of a subset of the bits within a hardware register so that concurrent access by two cores is always consistent with one atomic operation being performed first, followed by the second.

See hw_set_bits(), hw_clear_bits() and hw_xor_bits() provide for atomic access via a pointer to a 32 bit register

Additionally given a pointer to a structure representing a piece of hardware (e.g. dma_hw_t *dma_hw for the DMA controller), you can get an alias to the entire structure such that writing any member (register) within the structure is equivalent to an atomic operation via hw_set_alias(), hw_clear_alias() or hw_xor_alias()...

For example hw_set_alias(dma_hw)->inte1 = 0x80; will set bit 7 of the INTE1 register of the DMA controller, leaving the other bits unchanged.

Function Documentation

◆ hw_clear_bits()

static __force_inline void hw_clear_bits ( io_rw_32 *  addr,
uint32_t  mask 
)
static

Atomically clear the specified bits to 0 in a HW register.

Parameters

addr Address of writable register
mask Bit-mask specifying bits to clear

◆ hw_set_bits()

static __force_inline void hw_set_bits ( io_rw_32 *  addr,
uint32_t  mask 
)
static

Atomically set the specified bits to 1 in a HW register.

Parameters

addr Address of writable register
mask Bit-mask specifying bits to set

◆ hw_write_masked()

static __force_inline void hw_write_masked ( io_rw_32 *  addr,
uint32_t  values,
uint32_t  write_mask 
)
static

Set new values for a sub-set of the bits in a HW register.

Sets destination bits to values specified in values, if and only if corresponding bit in write_mask is set

Note: this method allows safe concurrent modification of different bits of a register, but multiple concurrent access to the same bits is still unsafe.

Parameters

addr Address of writable register
values Bits values
write_mask Mask of bits to change

◆ hw_xor_bits()

static __force_inline void hw_xor_bits ( io_rw_32 *  addr,
uint32_t  mask 
)
static

Atomically flip the specified bits in a HW register.

Parameters

addr Address of writable register
mask Bit-mask specifying bits to invert

hardware_claim

Part of: Hardware APIs

Functions

  • void hw_claim_or_assert (uint8_t *bits, uint bit_index, const char *message)

  •  Atomically claim a resource, panicking if it is already in use.

  • int hw_claim_unused_from_range (uint8_t *bits, bool required, uint bit_lsb, uint bit_msb, const char *message)

  •  Atomically claim one resource out of a range of resources, optionally asserting if none are free.

  • bool hw_is_claimed (const uint8_t *bits, uint bit_index)

  •  Determine if a resource is claimed at the time of the call.

  • void hw_claim_clear (uint8_t *bits, uint bit_index)

  •  Atomically unclaim a resource.

  • uint32_t hw_claim_lock (void)

  •  Acquire the runtime mutual exclusion lock provided by the hardware_claim library.

  • void hw_claim_unlock (uint32_t token)

  •  Release the runtime mutual exclusion lock provided by the hardware_claim library.

Detailed Description

Lightweight hardware resource management

hardware_claim provides a simple API for management of hardware resources at runtime.

This API is usually called by other hardware specific claiming APIs and provides simple multi-core safe methods to manipulate compact bit-sets representing hardware resources.

This API allows any other library to cooperatively participate in a scheme by which both compile time and runtime allocation of resources can co-exist, and conflicts can be avoided or detected (depending on the use case) without the libraries having any other knowledge of each other.

Facilities are providing for:

  1. Claiming resources (and asserting if they are already claimed)

  2. Freeing (unclaiming) resources

  3. Finding unused resources

Function Documentation

◆ hw_claim_clear()

void hw_claim_clear ( uint8_t *  bits,
uint  bit_index 
)

Atomically unclaim a resource.

The resource ownership is indicated by the bit_index bit in an array of bits.

Parameters

bits pointer to an array of bits (8 bits per byte)
bit_index resource to unclaim (bit index into array of bits)

◆ hw_claim_lock()

uint32_t hw_claim_lock ( void  )

Acquire the runtime mutual exclusion lock provided by the hardware_claim library.

This method is called automatically by the other hw_claim_ methods, however it is provided as a convenience to code that might want to protect other hardware initialization code from concurrent use.

Note
hw_claim_lock() uses a spin lock internally, so disables interrupts on the calling core, and will deadlock if the calling core already owns the lock.

Returns

a token to pass to hw_claim_unlock()

◆ hw_claim_or_assert()

void hw_claim_or_assert ( uint8_t *  bits,
uint  bit_index,
const char *  message 
)

Atomically claim a resource, panicking if it is already in use.

The resource ownership is indicated by the bit_index bit in an array of bits.

Parameters

bits pointer to an array of bits (8 bits per byte)
bit_index resource to claim (bit index into array of bits)
message string to display if the bit cannot be claimed; note this may have a single printf format "%d" for the bit

◆ hw_claim_unlock()

void hw_claim_unlock ( uint32_t  token )

Release the runtime mutual exclusion lock provided by the hardware_claim library.

Note
This method MUST be called from the same core that call hw_claim_lock()

Parameters

token the token returned by the corresponding call to hw_claim_lock()

◆ hw_claim_unused_from_range()

int hw_claim_unused_from_range ( uint8_t *  bits,
bool  required,
uint  bit_lsb,
uint  bit_msb,
const char *  message 
)

Atomically claim one resource out of a range of resources, optionally asserting if none are free.

Parameters

bits pointer to an array of bits (8 bits per byte)
required true if this method should panic if the resource is not free
bit_lsb the lower bound (inclusive) of the resource range to claim from
bit_msb the upper bound (inclusive) of the resource range to claim from
message string to display if the bit cannot be claimed

Returns

the bit index representing the claimed or -1 if none are available in the range, and required = false

◆ hw_is_claimed()

bool hw_is_claimed ( const uint8_t *  bits,
uint  bit_index 
)
inline

Determine if a resource is claimed at the time of the call.

The resource ownership is indicated by the bit_index bit in an array of bits.

Parameters

bits pointer to an array of bits (8 bits per byte)
bit_index resource to check (bit index into array of bits)

Returns

true if the resource is claimed

hardware_clocks

Part of: Hardware APIs

Typedefs

Enumerations

Functions

  • void clocks_init (void)

  •  Initialise the clock hardware.

  • bool clock_configure (enum clock_index clk_index, uint32_t src, uint32_t auxsrc, uint32_t src_freq, uint32_t freq)

  •  Configure the specified clock.

  • void clock_stop (enum clock_index clk_index)

  •  Stop the specified clock.

  • uint32_t clock_get_hz (enum clock_index clk_index)

  •  Get the current frequency of the specified clock.

  • uint32_t frequency_count_khz (uint src)

  •  Measure a clocks frequency using the Frequency counter.

  • void clock_set_reported_hz (enum clock_index clk_index, uint hz)

  •  Set the "current frequency" of the clock as reported by clock_get_hz without actually changing the clock.

  • void clocks_enable_resus (resus_callback_t resus_callback)

  •  Enable the resus function. Restarts clk_sys if it is accidentally stopped.

  • void clock_gpio_init_int_frac (uint gpio, uint src, uint32_t div_int, uint8_t div_frac)

  •  Output an optionally divided clock to the specified gpio pin.

  • static void clock_gpio_init (uint gpio, uint src, float div)

  •  Output an optionally divided clock to the specified gpio pin.

  • bool clock_configure_gpin (enum clock_index clk_index, uint gpio, uint32_t src_freq, uint32_t freq)

  •  Configure a clock to come from a gpio input.

Detailed Description

Clock Management API

This API provides a high level interface to the clock functions.

The clocks block provides independent clocks to on-chip and external components. It takes inputs from a variety of clock sources allowing the user to trade off performance against cost, board area and power consumption. From these sources it uses multiple clock generators to provide the required clocks. This architecture allows the user flexibility to start and stop clocks independently and to vary some clock frequencies whilst maintaining others at their optimum frequencies

Please refer to the datasheet for more details on the RP2040 clocks.

The clock source depends on which clock you are attempting to configure. The first table below shows main clock sources. If you are not setting the Reference clock or the System clock, or you are specifying that one of those two will be using an auxiliary clock source, then you will need to use one of the entries from the subsequent tables.

Main Clock Sources

Source Reference Clock System Clock
ROSC CLOCKS_CLK_REF_CTRL_SRC_VALUE_ROSC_CLKSRC_PH
Auxiliary CLOCKS_CLK_REF_CTRL_SRC_VALUE_CLKSRC_CLK_REF_AUX CLOCKS_CLK_SYS_CTRL_SRC_VALUE_CLKSRC_CLK_SYS_AUX
XOSC CLOCKS_CLK_REF_CTRL_SRC_VALUE_XOSC_CLKSRC
Reference CLOCKS_CLK_SYS_CTRL_SRC_VALUE_CLK_REF

Auxiliary Clock Sources

The auxiliary clock sources available for use in the configure function depend on which clock is being configured. The following table describes the available values that can be used. Note that for clk_gpout[x], x can be 0-3.

Aux Source clk_gpout[x] clk_ref clk_sys
System PLL CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS
GPIO in 0 CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 CLOCKS_CLK_REF_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0
GPIO in 1 CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 CLOCKS_CLK_REF_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1
USB PLL CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB CLOCKS_CLK_REF_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB
ROSC CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_ROSC_CLKSRC CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_ROSC_CLKSRC
XOSC CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_XOSC_CLKSRC CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_ROSC_CLKSRC
System clock CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_SYS
USB Clock CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_USB
ADC clock CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_ADC
RTC Clock CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_RTC
Ref clock CLOCKS_CLK_GPOUTx_CTRL_AUXSRC_VALUE_CLK_REF
Aux Source clk_peri clk_usb clk_adc
System PLL CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS
GPIO in 0 CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0 CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0
GPIO in 1 CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1 CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1
USB PLL CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB
ROSC CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_ROSC_CLKSRC_PH CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_ROSC_CLKSRC_PH CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_ROSC_CLKSRC_PH
XOSC CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_XOSC_CLKSRC CLOCKS_CLK_USB_CTRL_AUXSRC_VALUE_XOSC_CLKSRC CLOCKS_CLK_ADC_CTRL_AUXSRC_VALUE_XOSC_CLKSRC
System clock CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLK_SYS
Aux Source clk_rtc
System PLL CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_CLKSRC_PLL_SYS
GPIO in 0 CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_CLKSRC_GPIN0
GPIO in 1 CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_CLKSRC_GPIN1
USB PLL CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB
ROSC CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_ROSC_CLKSRC_PH
XOSC CLOCKS_CLK_RTC_CTRL_AUXSRC_VALUE_XOSC_CLKSRC

Example

#include <stdio.h>
#include "pico/stdlib.h"
#include "hardware/pll.h"
#include "hardware/structs/pll.h"
#include "hardware/structs/clocks.h"
void measure_freqs(void) {
uint f_pll_sys = frequency_count_khz(CLOCKS_FC0_SRC_VALUE_PLL_SYS_CLKSRC_PRIMARY);
uint f_pll_usb = frequency_count_khz(CLOCKS_FC0_SRC_VALUE_PLL_USB_CLKSRC_PRIMARY);
uint f_rosc = frequency_count_khz(CLOCKS_FC0_SRC_VALUE_ROSC_CLKSRC);
uint f_clk_sys = frequency_count_khz(CLOCKS_FC0_SRC_VALUE_CLK_SYS);
uint f_clk_peri = frequency_count_khz(CLOCKS_FC0_SRC_VALUE_CLK_PERI);
uint f_clk_usb = frequency_count_khz(CLOCKS_FC0_SRC_VALUE_CLK_USB);
uint f_clk_adc = frequency_count_khz(CLOCKS_FC0_SRC_VALUE_CLK_ADC);
uint f_clk_rtc = frequency_count_khz(CLOCKS_FC0_SRC_VALUE_CLK_RTC);
printf("pll_sys = %dkHz\n", f_pll_sys);
printf("pll_usb = %dkHz\n", f_pll_usb);
printf("rosc = %dkHz\n", f_rosc);
printf("clk_sys = %dkHz\n", f_clk_sys);
printf("clk_peri = %dkHz\n", f_clk_peri);
printf("clk_usb = %dkHz\n", f_clk_usb);
printf("clk_adc = %dkHz\n", f_clk_adc);
printf("clk_rtc = %dkHz\n", f_clk_rtc);
// Can't measure clk_ref / xosc as it is the ref
}
int main() {
printf("Hello, world!\n");
measure_freqs();
// Change clk_sys to be 48MHz. The simplest way is to take this from PLL_USB
// which has a source frequency of 48MHz
CLOCKS_CLK_SYS_CTRL_SRC_VALUE_CLKSRC_CLK_SYS_AUX,
CLOCKS_CLK_SYS_CTRL_AUXSRC_VALUE_CLKSRC_PLL_USB,
48 * MHZ,
48 * MHZ);
// Turn off PLL sys for good measure
pll_deinit(pll_sys);
// CLK peri is clocked from clk_sys so need to change clk_peri's freq
0,
CLOCKS_CLK_PERI_CTRL_AUXSRC_VALUE_CLK_SYS,
48 * MHZ,
48 * MHZ);
// Re init uart now that clk_peri has changed
measure_freqs();
printf("Hello, 48MHz");
return 0;
}
bool clock_configure(enum clock_index clk_index, uint32_t src, uint32_t auxsrc, uint32_t src_freq, uint32_t freq)
Configure the specified clock.
Definition: clocks.c:48
uint32_t frequency_count_khz(uint src)
Measure a clocks frequency using the Frequency counter.
Definition: clocks.c:211
@ clk_peri
Peripheral clock for UART and SPI.
Definition: clocks.h:34
@ clk_sys
Processors, bus fabric, memory, memory mapped registers.
Definition: clocks.h:33
void pll_deinit(PLL pll)
Release/uninitialise specified PLL.
Definition: pll.c:75
bool stdio_init_all(void)
Initialize all of the present standard stdio types that are linked into the binary.
Definition: stdio.c:283

Typedef Documentation

◆ resus_callback_t

typedef void(* resus_callback_t) (void)

Resus callback function type.

User provided callback for a resus event (when clk_sys is stopped by the programmer and is restarted for them).

Enumeration Type Documentation

◆ clock_index

Enumeration identifying a hardware clock.

Enumerator
clk_gpout0 

GPIO Muxing 0.

clk_gpout1 

GPIO Muxing 1.

clk_gpout2 

GPIO Muxing 2.

clk_gpout3 

GPIO Muxing 3.

clk_ref 

Watchdog and timers reference clock.

clk_sys 

Processors, bus fabric, memory, memory mapped registers.

clk_peri 

Peripheral clock for UART and SPI.

clk_usb 

USB clock.

clk_adc 

ADC clock.

clk_rtc 

Real time clock.

Function Documentation

◆ clock_configure()

bool clock_configure ( enum clock_index  clk_index,
uint32_t  src,
uint32_t  auxsrc,
uint32_t  src_freq,
uint32_t  freq 
)

Configure the specified clock.

See the tables in the description for details on the possible values for clock sources.

Parameters

clk_index The clock to configure
src The main clock source, can be 0.
auxsrc The auxiliary clock source, which depends on which clock is being set. Can be 0
src_freq Frequency of the input clock source
freq Requested frequency

◆ clock_configure_gpin()

bool clock_configure_gpin ( enum clock_index  clk_index,
uint  gpio,
uint32_t  src_freq,
uint32_t  freq 
)

Configure a clock to come from a gpio input.

Parameters

clk_index The clock to configure
gpio The GPIO pin to run the clock from. Valid GPIOs are: 20 and 22.
src_freq Frequency of the input clock source
freq Requested frequency

◆ clock_get_hz()

uint32_t clock_get_hz ( enum clock_index  clk_index )

Get the current frequency of the specified clock.

Parameters

clk_index Clock

Returns

Clock frequency in Hz

◆ clock_gpio_init()

static void clock_gpio_init ( uint  gpio,
uint  src,
float  div 
)
inlinestatic

Output an optionally divided clock to the specified gpio pin.

Parameters

gpio The GPIO pin to output the clock to. Valid GPIOs are: 21, 23, 24, 25. These GPIOs are connected to the GPOUT0-3 clock generators.
src The source clock. See the register field CLOCKS_CLK_GPOUT0_CTRL_AUXSRC for a full list. The list is the same for each GPOUT clock generator.
div The float amount to divide the source clock by. This is useful to not overwhelm the GPIO pin with a fast clock.

◆ clock_gpio_init_int_frac()

void clock_gpio_init_int_frac ( uint  gpio,
uint  src,
uint32_t  div_int,
uint8_t  div_frac 
)

Output an optionally divided clock to the specified gpio pin.

Parameters

gpio The GPIO pin to output the clock to. Valid GPIOs are: 21, 23, 24, 25. These GPIOs are connected to the GPOUT0-3 clock generators.
src The source clock. See the register field CLOCKS_CLK_GPOUT0_CTRL_AUXSRC for a full list. The list is the same for each GPOUT clock generator.
div_int The integer part of the value to divide the source clock by. This is useful to not overwhelm the GPIO pin with a fast clock. this is in range of 1..2^24-1.
div_frac The fractional part of the value to divide the source clock by. This is in range of 0..255 (/256).

◆ clock_set_reported_hz()

void clock_set_reported_hz ( enum clock_index  clk_index,
uint  hz 
)

Set the "current frequency" of the clock as reported by clock_get_hz without actually changing the clock.

See alsoclock_get_hz()

◆ clock_stop()

void clock_stop ( enum clock_index  clk_index )

Stop the specified clock.

Parameters

clk_index The clock to stop

◆ clocks_enable_resus()

void clocks_enable_resus ( resus_callback_t  resus_callback )

Enable the resus function. Restarts clk_sys if it is accidentally stopped.

The resuscitate function will restart the system clock if it falls below a certain speed (or stops). This could happen if the clock source the system clock is running from stops. For example if a PLL is stopped.

Parameters

resus_callback a function pointer provided by the user to call if a resus event happens.

◆ clocks_init()

void clocks_init ( void  )

Initialise the clock hardware.

Must be called before any other clock function.

◆ frequency_count_khz()

uint32_t frequency_count_khz ( uint  src )

Measure a clocks frequency using the Frequency counter.

Uses the inbuilt frequency counter to measure the specified clocks frequency. Currently, this function is accurate to +-1KHz. See the datasheet for more details.

hardware_divider

Part of: Hardware APIs

Functions

Detailed Description

Low-level hardware-divider access

The SIO contains an 8-cycle signed/unsigned divide/modulo circuit, per core. Calculation is started by writing a dividend and divisor to the two argument registers, DIVIDEND and DIVISOR. The divider calculates the quotient / and remainder % of this division over the next 8 cycles, and on the 9th cycle the results can be read from the two result registers DIV_QUOTIENT and DIV_REMAINDER. A 'ready' bit in register DIV_CSR can be polled to wait for the calculation to complete, or software can insert a fixed 8-cycle delay

This header provides low level macros and inline functions for accessing the hardware dividers directly, and perhaps most usefully performing asynchronous divides. These functions however do not follow the regular SDK conventions for saving/restoring the divider state, so are not generally safe to call from interrupt handlers

The pico_divider library provides a more user friendly set of APIs over the divider (and support for 64 bit divides), and of course by default regular C language integer divisions are redirected through that library, meaning you can just use C level / and % operators and gain the benefits of the fast hardware divider.

See alsopico_divider

Example

#include <stdio.h>
#include "pico/stdlib.h"
int main() {
printf("Hello, divider!\n");
// This is the basic hardware divider function
int32_t dividend = 123456;
int32_t divisor = -321;
divmod_result_t result = hw_divider_divmod_s32(dividend, divisor);
printf("%d/%d = %d remainder %d\n", dividend, divisor, to_quotient_s32(result), to_remainder_s32(result));
// Is it right?
printf("Working backwards! Result %d should equal %d!\n\n",
to_quotient_s32(result) * divisor + to_remainder_s32(result), dividend);
// This is the recommended unsigned fast divider for general use.
int32_t udividend = 123456;
int32_t udivisor = 321;
divmod_result_t uresult = hw_divider_divmod_u32(udividend, udivisor);
printf("%d/%d = %d remainder %d\n", udividend, udivisor, to_quotient_u32(uresult), to_remainder_u32(uresult));
// Is it right?
printf("Working backwards! Result %d should equal %d!\n\n",
to_quotient_u32(result) * divisor + to_remainder_u32(result), dividend);
// You can also do divides asynchronously. Divides will be complete after 8 cycles.
hw_divider_divmod_s32_start(dividend, divisor);
// Do something for 8 cycles!
// In this example, our results function will wait for completion.
// Use hw_divider_result_nowait() if you don't want to wait, but are sure you have delayed at least 8 cycles
printf("Async result %d/%d = %d remainder %d\n", dividend, divisor, to_quotient_s32(result),
to_remainder_s32(result));
// For a really fast divide, you can use the inlined versions... the / involves a function call as / always does
// when using the ARM AEABI, so if you really want the best performance use the inlined versions.
// Note that the / operator function DOES use the hardware divider by default, although you can change
// that behavior by calling pico_set_divider_implementation in the cmake build for your target.
printf("%d / %d = (by operator %d) (inlined %d)\n", dividend, divisor,
dividend / divisor, hw_divider_s32_quotient_inlined(dividend, divisor));
// Note however you must manually save/restore the divider state if you call the inlined methods from within an IRQ
// handler.
hw_divider_divmod_s32_start(dividend, divisor);
printf("inner %d / %d = %d\n", 123, 7, hw_divider_s32_quotient_wait());
printf("outer divide %d / %d = %d\n", dividend, divisor, tmp);
return 0;
}
divmod_result_t hw_divider_divmod_u32(uint32_t a, uint32_t b)
Do an unsigned HW divide and wait for result.
static uint32_t to_quotient_u32(divmod_result_t r)
Efficient extraction of unsigned quotient from 32p32 fixed point.
Definition: divider.h:205
static int32_t hw_divider_s32_quotient_inlined(int32_t a, int32_t b)
Do a hardware signed HW divide, wait for result, return quotient.
Definition: divider.h:352
static void hw_divider_divmod_s32_start(int32_t a, int32_t b)
Start a signed asynchronous divide.
Definition: divider.h:54
static int32_t to_quotient_s32(divmod_result_t r)
Efficient extraction of signed quotient from 32p32 fixed point.
Definition: divider.h:215
static int32_t to_remainder_s32(divmod_result_t r)
Efficient extraction of signed remainder from 32p32 fixed point.
Definition: divider.h:239
static int32_t hw_divider_s32_quotient_wait(void)
Return result of last asynchronous HW divide, signed quotient only.
Definition: divider.h:144
static divmod_result_t hw_divider_result_wait(void)
Return result of last asynchronous HW divide.
Definition: divider.h:120
divmod_result_t hw_divider_divmod_s32(int32_t a, int32_t b)
Do a signed HW divide and wait for result.
static uint32_t to_remainder_u32(divmod_result_t r)
Efficient extraction of unsigned remainder from 32p32 fixed point.
Definition: divider.h:227
void hw_divider_save_state(hw_divider_state_t *dest)
Save the calling cores hardware divider state.
void hw_divider_restore_state(hw_divider_state_t *src)
Load a saved hardware divider state into the current core's hardware divider.
bool stdio_init_all(void)
Initialize all of the present standard stdio types that are linked into the binary.
Definition: stdio.c:283
Definition: divider.h:375

Function Documentation

◆ hw_divider_divmod_s32()

divmod_result_t hw_divider_divmod_s32 ( int32_t  a,
int32_t  b 
)

Do a signed HW divide and wait for result.

Divide a by b, wait for calculation to complete, return result as a pair of 32-bit quotient/remainder values.

Parameters

a The dividend
b The divisor

Returns

Results of divide as a pair of 32-bit quotient/remainder values.

◆ hw_divider_divmod_s32_start()

static void hw_divider_divmod_s32_start ( int32_t  a,
int32_t  b 
)
inlinestatic

Start a signed asynchronous divide.

Start a divide of the specified signed parameters. You should wait for 8 cycles (__div_pause()) or wait for the ready bit to be set (hw_divider_wait_ready()) prior to reading the results.

Parameters

a The dividend
b The divisor

◆ hw_divider_divmod_u32()

divmod_result_t hw_divider_divmod_u32 ( uint32_t  a,
uint32_t  b 
)

Do an unsigned HW divide and wait for result.

Divide a by b, wait for calculation to complete, return result as a pair of 32-bit quotient/remainder values.

Parameters

a The dividend
b The divisor

Returns

Results of divide as a pair of 32-bit quotient/remainder values.

◆ hw_divider_divmod_u32_start()

static void hw_divider_divmod_u32_start ( uint32_t  a,
uint32_t  b 
)
inlinestatic

Start an unsigned asynchronous divide.

Start a divide of the specified unsigned parameters. You should wait for 8 cycles (__div_pause()) or wait for the ready bit to be set (hw_divider_wait_ready()) prior to reading the results.

Parameters

a The dividend
b The divisor

◆ hw_divider_quotient_s32()

static int32_t hw_divider_quotient_s32 ( int32_t  a,
int32_t  b 
)
inlinestatic

Do a signed HW divide, wait for result, return quotient.

Divide a by b, wait for calculation to complete, return quotient.

Parameters

a The dividend
b The divisor

Returns

Quotient results of the divide

◆ hw_divider_remainder_s32()

static int32_t hw_divider_remainder_s32 ( int32_t  a,
int32_t  b 
)
inlinestatic

Do a signed HW divide, wait for result, return remainder.

Divide a by b, wait for calculation to complete, return remainder.

Parameters

a The dividend
b The divisor

Returns

Remainder results of the divide

◆ hw_divider_restore_state()

void hw_divider_restore_state ( hw_divider_state_t src )

Load a saved hardware divider state into the current core's hardware divider.

Copy the passed hardware divider state into the hardware divider.

Parameters

src the location to load the divider state from

◆ hw_divider_result_nowait()

static divmod_result_t hw_divider_result_nowait ( void  )
inlinestatic

Return result of HW divide, nowait.

Note
This is UNSAFE in that the calculation may not have been completed.

Returns

Current result. Most significant 32 bits are the remainder, lower 32 bits are the quotient.

◆ hw_divider_result_wait()

static divmod_result_t hw_divider_result_wait ( void  )
inlinestatic

Return result of last asynchronous HW divide.

This function waits for the result to be ready by calling hw_divider_wait_ready().

Returns

Current result. Most significant 32 bits are the remainder, lower 32 bits are the quotient.

◆ hw_divider_s32_quotient_inlined()

static int32_t hw_divider_s32_quotient_inlined ( int32_t  a,
int32_t  b 
)
inlinestatic

Do a hardware signed HW divide, wait for result, return quotient.

Divide a by b, wait for calculation to complete, return quotient.

Parameters

a The dividend
b The divisor

Returns

Quotient result of the divide

◆ hw_divider_s32_quotient_wait()

static int32_t hw_divider_s32_quotient_wait ( void  )
inlinestatic

Return result of last asynchronous HW divide, signed quotient only.

This function waits for the result to be ready by calling hw_divider_wait_ready().

Returns

Current signed quotient result.

◆ hw_divider_s32_remainder_inlined()

static int32_t hw_divider_s32_remainder_inlined ( int32_t  a,
int32_t  b 
)
inlinestatic

Do a hardware signed HW divide, wait for result, return remainder.

Divide a by b, wait for calculation to complete, return remainder.

Parameters

a The dividend
b The divisor

Returns

Remainder result of the divide

◆ hw_divider_s32_remainder_wait()

static int32_t hw_divider_s32_remainder_wait ( void  )
inlinestatic

Return result of last asynchronous HW divide, signed remainder only.

This function waits for the result to be ready by calling hw_divider_wait_ready().

Returns

Current remainder results.

◆ hw_divider_save_state()

void hw_divider_save_state ( hw_divider_state_t dest )

Save the calling cores hardware divider state.

Copy the current core's hardware divider state into the provided structure. This method waits for the divider results to be stable, then copies them to memory. They can be restored via hw_divider_restore_state()

Parameters

dest the location to store the divider state

◆ hw_divider_u32_quotient()

static uint32_t hw_divider_u32_quotient ( uint32_t  a,
uint32_t  b 
)
inlinestatic

Do an unsigned HW divide, wait for result, return quotient.

Divide a by b, wait for calculation to complete, return quotient.

Parameters

a The dividend
b The divisor

Returns

Quotient results of the divide

◆ hw_divider_u32_quotient_inlined()

static uint32_t hw_divider_u32_quotient_inlined ( uint32_t  a,
uint32_t  b 
)
inlinestatic

Do a hardware unsigned HW divide, wait for result, return quotient.

Divide a by b, wait for calculation to complete, return quotient.

Parameters

a The dividend
b The divisor

Returns

Quotient result of the divide

◆ hw_divider_u32_quotient_wait()

static uint32_t hw_divider_u32_quotient_wait ( void  )
inlinestatic

Return result of last asynchronous HW divide, unsigned quotient only.

This function waits for the result to be ready by calling hw_divider_wait_ready().

Returns

Current unsigned quotient result.

◆ hw_divider_u32_remainder()

static uint32_t hw_divider_u32_remainder ( uint32_t  a,
uint32_t  b 
)
inlinestatic

Do an unsigned HW divide, wait for result, return remainder.

Divide a by b, wait for calculation to complete, return remainder.

Parameters

a The dividend
b The divisor

Returns

Remainder results of the divide

◆ hw_divider_u32_remainder_inlined()

static uint32_t hw_divider_u32_remainder_inlined ( uint32_t  a,
uint32_t  b 
)
inlinestatic

Do a hardware unsigned HW divide, wait for result, return remainder.

Divide a by b, wait for calculation to complete, return remainder.

Parameters

a The dividend
b The divisor

Returns

Remainder result of the divide

◆ hw_divider_u32_remainder_wait()

static uint32_t hw_divider_u32_remainder_wait ( void  )
inlinestatic

Return result of last asynchronous HW divide, unsigned remainder only.

This function waits for the result to be ready by calling hw_divider_wait_ready().

Returns

Current unsigned remainder result.

◆ hw_divider_wait_ready()

static void hw_divider_wait_ready ( void  )
inlinestatic

Wait for a divide to complete.

Wait for a divide to complete

◆ to_quotient_s32()

static int32_t to_quotient_s32 ( divmod_result_t  r )
inlinestatic

Efficient extraction of signed quotient from 32p32 fixed point.

Parameters

r A pair of 32-bit quotient/remainder values.

Returns

Unsigned quotient

◆ to_quotient_u32()

static uint32_t to_quotient_u32 ( divmod_result_t  r )
inlinestatic

Efficient extraction of unsigned quotient from 32p32 fixed point.

Parameters

r A pair of 32-bit quotient/remainder values.

Returns

Unsigned quotient

◆ to_remainder_s32()

static int32_t to_remainder_s32 ( divmod_result_t  r )
inlinestatic

Efficient extraction of signed remainder from 32p32 fixed point.

Parameters

r A pair of 32-bit quotient/remainder values.

Returns

Signed remainder

Note
On arm this is just a 32 bit register move or a nop

◆ to_remainder_u32()

static uint32_t to_remainder_u32 ( divmod_result_t  r )
inlinestatic

Efficient extraction of unsigned remainder from 32p32 fixed point.

Parameters

r A pair of 32-bit quotient/remainder values.

Returns

Unsigned remainder

Note
On Arm this is just a 32 bit register move or a nop

hardware_dma

Part of: Hardware APIs

Modules

Enumerations

Functions

Detailed Description

DMA Controller API

The RP2040 Direct Memory Access (DMA) master performs bulk data transfers on a processor’s behalf. This leaves processors free to attend to other tasks, or enter low-power sleep states. The data throughput of the DMA is also significantly higher than one of RP2040’s processors.

The DMA can perform one read access and one write access, up to 32 bits in size, every clock cycle. There are 12 independent channels, which each supervise a sequence of bus transfers, usually in one of the following scenarios:

  • Memory to peripheral

  • Peripheral to memory

  • Memory to memory

Enumeration Type Documentation

◆ dma_channel_transfer_size

Enumeration of available DMA channel transfer sizes.

Names indicate the number of bits.

Enumerator
DMA_SIZE_8 

Byte transfer (8 bits)

DMA_SIZE_16 

Half word transfer (16 bits)

DMA_SIZE_32 

Word transfer (32 bits)

Function Documentation

◆ dma_channel_abort()

static void dma_channel_abort ( uint  channel )
inlinestatic

Stop a DMA transfer.

Function will only return once the DMA has stopped.

Note that due to errata RP2040-E13, aborting a channel which has transfers in-flight (i.e. an individual read has taken place but the corresponding write has not), the ABORT status bit will clear prematurely, and subsequently the in-flight transfers will trigger a completion interrupt once they complete.

The effect of this is that you may see a spurious completion interrupt on the channel as a result of calling this method.

The calling code should be sure to ignore a completion IRQ as a result of this method. This may not require any additional work, as aborting a channel which may be about to complete, when you have a completion IRQ handler registered, is inherently race-prone, and so code is likely needed to disambiguate the two occurrences.

If that is not the case, but you do have a channel completion IRQ handler registered, you can simply disable/re-enable the IRQ around the call to this method as shown by this code fragment (using DMA IRQ0).

// disable the channel on IRQ0
// abort the channel
// clear the spurious IRQ (if there was one)
// re-enable the channel on IRQ0
static void dma_channel_abort(uint channel)
Stop a DMA transfer.
Definition: dma.h:527
static void dma_channel_set_irq0_enabled(uint channel, bool enabled)
Enable single DMA channel's interrupt via DMA_IRQ_0.
Definition: dma.h:541
static void dma_channel_acknowledge_irq0(uint channel)
Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_0.
Definition: dma.h:665

Parameters

channel DMA channel

◆ dma_channel_acknowledge_irq0()

static void dma_channel_acknowledge_irq0 ( uint  channel )
inlinestatic

Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_0.

Parameters

channel DMA channel

◆ dma_channel_acknowledge_irq1()

static void dma_channel_acknowledge_irq1 ( uint  channel )
inlinestatic

Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_1.

Parameters

channel DMA channel

◆ dma_channel_claim()

void dma_channel_claim ( uint  channel )

Mark a dma channel as used.

Method for cooperative claiming of hardware. Will cause a panic if the channel is already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways.

Parameters

channel the dma channel

◆ dma_channel_cleanup()

void dma_channel_cleanup ( uint  channel )

Performs DMA channel cleanup after use.

This can be used to cleanup dma channels when they're no longer needed, such that they are in a clean state for reuse. IRQ's for the channel are disabled, any in flight-transfer is aborted and any outstanding interrupts are cleared. The channel is then clear to be reused for other purposes.

if (dma_channel >= 0) {
dma_channel_cleanup(dma_channel);
dma_channel_unclaim(dma_channel);
dma_channel = -1;
}
void dma_channel_cleanup(uint channel)
Performs DMA channel cleanup after use.
Definition: dma.c:73
void dma_channel_unclaim(uint channel)
Mark a dma channel as no longer used.
Definition: dma.c:34

Parameters

channel DMA channel

◆ dma_channel_configure()

static void dma_channel_configure ( uint  channel,
const dma_channel_config config,
volatile void *  write_addr,
const volatile void *  read_addr,
uint  transfer_count,
bool  trigger 
)
inlinestatic

Configure all DMA parameters and optionally start transfer.

Parameters

channel DMA channel
config Pointer to DMA config structure
write_addr Initial write address
read_addr Initial read address
transfer_count Number of transfers to perform
trigger True to start the transfer immediately

◆ dma_channel_get_irq0_status()

static bool dma_channel_get_irq0_status ( uint  channel )
inlinestatic

Determine if a particular channel is a cause of DMA_IRQ_0.

Parameters

channel DMA channel

Returns

true if the channel is a cause of DMA_IRQ_0, false otherwise

◆ dma_channel_get_irq1_status()

static bool dma_channel_get_irq1_status ( uint  channel )
inlinestatic

Determine if a particular channel is a cause of DMA_IRQ_1.

Parameters

channel DMA channel

Returns

true if the channel is a cause of DMA_IRQ_1, false otherwise

◆ dma_channel_is_busy()

static bool dma_channel_is_busy ( uint  channel )
inlinestatic

Check if DMA channel is busy.

Parameters

channel DMA channel

Returns

true if the channel is currently busy

◆ dma_channel_is_claimed()

bool dma_channel_is_claimed ( uint  channel )

Determine if a dma channel is claimed.

Parameters

channel the dma channel

Returns

true if the channel is claimed, false otherwise

See alsodma_channel_claim dma_channel_claim_mask

◆ dma_channel_set_config()

static void dma_channel_set_config ( uint  channel,
const dma_channel_config config,
bool  trigger 
)
inlinestatic

Set a channel configuration.

Parameters

channel DMA channel
config Pointer to a config structure with required configuration
trigger True to trigger the transfer immediately

◆ dma_channel_set_irq0_enabled()

static void dma_channel_set_irq0_enabled ( uint  channel,
bool  enabled 
)
inlinestatic

Enable single DMA channel's interrupt via DMA_IRQ_0.

Parameters

channel DMA channel
enabled true to enable interrupt 0 on specified channel, false to disable.

◆ dma_channel_set_irq1_enabled()

static void dma_channel_set_irq1_enabled ( uint  channel,
bool  enabled 
)
inlinestatic

Enable single DMA channel's interrupt via DMA_IRQ_1.

Parameters

channel DMA channel
enabled true to enable interrupt 1 on specified channel, false to disable.

◆ dma_channel_set_read_addr()

static void dma_channel_set_read_addr ( uint  channel,
const volatile void *  read_addr,
bool  trigger 
)
inlinestatic

Set the DMA initial read address.

Parameters

channel DMA channel
read_addr Initial read address of transfer.
trigger True to start the transfer immediately

◆ dma_channel_set_trans_count()

static void dma_channel_set_trans_count ( uint  channel,
uint32_t  trans_count,
bool  trigger 
)
inlinestatic

Set the number of bus transfers the channel will do.

Parameters

channel DMA channel
trans_count The number of transfers (not NOT bytes, see channel_config_set_transfer_data_size)
trigger True to start the transfer immediately

◆ dma_channel_set_write_addr()

static void dma_channel_set_write_addr ( uint  channel,
volatile void *  write_addr,
bool  trigger 
)
inlinestatic

Set the DMA initial write address.

Parameters

channel DMA channel
write_addr Initial write address of transfer.
trigger True to start the transfer immediately

◆ dma_channel_start()

static void dma_channel_start ( uint  channel )
inlinestatic

Start a single DMA channel.

Parameters

channel DMA channel

◆ dma_channel_transfer_from_buffer_now()

static void dma_channel_transfer_from_buffer_now ( uint  channel,
const volatile void *  read_addr,
uint32_t  transfer_count 
)
inlinestatic

Start a DMA transfer from a buffer immediately.

Parameters

channel DMA channel
read_addr Sets the initial read address
transfer_count Number of transfers to make. Not bytes, but the number of transfers of channel_config_set_transfer_data_size() to be sent.

◆ dma_channel_transfer_to_buffer_now()

static void dma_channel_transfer_to_buffer_now ( uint  channel,
volatile void *  write_addr,
uint32_t  transfer_count 
)
inlinestatic

Start a DMA transfer to a buffer immediately.

Parameters

channel DMA channel
write_addr Sets the initial write address
transfer_count Number of transfers to make. Not bytes, but the number of transfers of channel_config_set_transfer_data_size() to be sent.

◆ dma_channel_unclaim()

void dma_channel_unclaim ( uint  channel )

Mark a dma channel as no longer used.

Parameters

channel the dma channel to release

◆ dma_channel_wait_for_finish_blocking()

static void dma_channel_wait_for_finish_blocking ( uint  channel )
inlinestatic

Wait for a DMA channel transfer to complete.

Parameters

channel DMA channel

◆ dma_claim_mask()

void dma_claim_mask ( uint32_t  channel_mask )

Mark multiple dma channels as used.

Method for cooperative claiming of hardware. Will cause a panic if any of the channels are already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways.

Parameters

channel_mask Bitfield of all required channels to claim (bit 0 == channel 0, bit 1 == channel 1 etc)

◆ dma_claim_unused_channel()

int dma_claim_unused_channel ( bool  required )

Claim a free dma channel.

Parameters

required if true the function will panic if none are available

Returns

the dma channel number or -1 if required was false, and none were free

◆ dma_claim_unused_timer()

int dma_claim_unused_timer ( bool  required )

Claim a free dma timer.

Parameters

required if true the function will panic if none are available

Returns

the dma timer number or -1 if required was false, and none were free

◆ dma_get_timer_dreq()

static uint dma_get_timer_dreq ( uint  timer_num )
inlinestatic

Return the DREQ number for a given DMA timer.

Parameters

timer_num DMA timer number 0-3

◆ dma_irqn_acknowledge_channel()

static void dma_irqn_acknowledge_channel ( uint  irq_index,
uint  channel 
)
inlinestatic

Acknowledge a channel IRQ, resetting it as the cause of DMA_IRQ_N.

Parameters

irq_index the IRQ index; either 0 or 1 for DMA_IRQ_0 or DMA_IRQ_1
channel DMA channel

◆ dma_irqn_get_channel_status()

static bool dma_irqn_get_channel_status ( uint  irq_index,
uint  channel 
)
inlinestatic

Determine if a particular channel is a cause of DMA_IRQ_N.

Parameters

irq_index the IRQ index; either 0 or 1 for DMA_IRQ_0 or DMA_IRQ_1
channel DMA channel

Returns

true if the channel is a cause of the DMA_IRQ_N, false otherwise

◆ dma_irqn_set_channel_enabled()

static void dma_irqn_set_channel_enabled ( uint  irq_index,
uint  channel,
bool  enabled 
)
inlinestatic

Enable single DMA channel interrupt on either DMA_IRQ_0 or DMA_IRQ_1.

Parameters

irq_index the IRQ index; either 0 or 1 for DMA_IRQ_0 or DMA_IRQ_1
channel DMA channel
enabled true to enable interrupt via irq_index for specified channel, false to disable.

◆ dma_irqn_set_channel_mask_enabled()

static void dma_irqn_set_channel_mask_enabled ( uint  irq_index,
uint32_t  channel_mask,
bool  enabled 
)
inlinestatic

Enable multiple DMA channels' interrupt via either DMA_IRQ_0 or DMA_IRQ_1.

Parameters

irq_index the IRQ index; either 0 or 1 for DMA_IRQ_0 or DMA_IRQ_1
channel_mask Bitmask of all the channels to enable/disable. Channel 0 = bit 0, channel 1 = bit 1 etc.
enabled true to enable all the interrupts specified in the mask, false to disable all the interrupts specified in the mask.

◆ dma_set_irq0_channel_mask_enabled()

static void dma_set_irq0_channel_mask_enabled ( uint32_t  channel_mask,
bool  enabled 
)
inlinestatic

Enable multiple DMA channels' interrupts via DMA_IRQ_0.

Parameters

channel_mask Bitmask of all the channels to enable/disable. Channel 0 = bit 0, channel 1 = bit 1 etc.
enabled true to enable all the interrupts specified in the mask, false to disable all the interrupts specified in the mask.

◆ dma_set_irq1_channel_mask_enabled()

static void dma_set_irq1_channel_mask_enabled ( uint32_t  channel_mask,
bool  enabled 
)
inlinestatic

Enable multiple DMA channels' interrupts via DMA_IRQ_1.

Parameters

channel_mask Bitmask of all the channels to enable/disable. Channel 0 = bit 0, channel 1 = bit 1 etc.
enabled true to enable all the interrupts specified in the mask, false to disable all the interrupts specified in the mask.

◆ dma_sniffer_disable()

static void dma_sniffer_disable ( void  )
inlinestatic

Disable the DMA sniffer.

◆ dma_sniffer_enable()

static void dma_sniffer_enable ( uint  channel,
uint  mode,
bool  force_channel_enable 
)
inlinestatic

Enable the DMA sniffing targeting the specified channel.

The mode can be one of the following:

Mode Function
0x0 Calculate a CRC-32 (IEEE802.3 polynomial)
0x1 Calculate a CRC-32 (IEEE802.3 polynomial) with bit reversed data
0x2 Calculate a CRC-16-CCITT
0x3 Calculate a CRC-16-CCITT with bit reversed data
0xe XOR reduction over all data. == 1 if the total 1 population count is odd.
0xf Calculate a simple 32-bit checksum (addition with a 32 bit accumulator)

Parameters

channel DMA channel
mode See description
force_channel_enable Set true to also turn on sniffing in the channel configuration (this is usually what you want, but sometimes you might have a chain DMA with only certain segments of the chain sniffed, in which case you might pass false).

◆ dma_sniffer_get_data_accumulator()

static uint32_t dma_sniffer_get_data_accumulator ( void  )
inlinestatic

Get the sniffer's data accumulator value.

Read value calculated by the hardware from sniffing the DMA stream

◆ dma_sniffer_set_byte_swap_enabled()

static void dma_sniffer_set_byte_swap_enabled ( bool  swap )
inlinestatic

Enable the Sniffer byte swap function.

Locally perform a byte reverse on the sniffed data, before feeding into checksum.

Note that the sniff hardware is downstream of the DMA channel byteswap performed in the read master: if channel_config_set_bswap() and dma_sniffer_set_byte_swap_enabled() are both enabled, their effects cancel from the sniffer’s point of view.

Parameters

swap Set true to enable byte swapping

◆ dma_sniffer_set_data_accumulator()

static void dma_sniffer_set_data_accumulator ( uint32_t  seed_value )
inlinestatic

Set the sniffer's data accumulator with initial value.

Generally, CRC algorithms are used with the data accumulator initially seeded with 0xFFFF or 0xFFFFFFFF (for crc16 and crc32 algorithms)

Parameters

seed_value value to set data accumulator

◆ dma_sniffer_set_output_invert_enabled()

static void dma_sniffer_set_output_invert_enabled ( bool  invert )
inlinestatic

Enable the Sniffer output invert function.

If enabled, the sniff data result appears bit-inverted when read. This does not affect the way the checksum is calculated.

Parameters

invert Set true to enable output bit inversion

◆ dma_sniffer_set_output_reverse_enabled()

static void dma_sniffer_set_output_reverse_enabled ( bool  reverse )
inlinestatic

Enable the Sniffer output bit reversal function.

If enabled, the sniff data result appears bit-reversed when read. This does not affect the way the checksum is calculated.

Parameters

reverse Set true to enable output bit reversal

◆ dma_start_channel_mask()

static void dma_start_channel_mask ( uint32_t  chan_mask )
inlinestatic

Start one or more channels simultaneously.

Parameters

chan_mask Bitmask of all the channels requiring starting. Channel 0 = bit 0, channel 1 = bit 1 etc.

◆ dma_timer_claim()

void dma_timer_claim ( uint  timer )

Mark a dma timer as used.

Method for cooperative claiming of hardware. Will cause a panic if the timer is already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways.

Parameters

timer the dma timer

◆ dma_timer_is_claimed()

bool dma_timer_is_claimed ( uint  timer )

Determine if a dma timer is claimed.

Parameters

timer the dma timer

Returns

true if the timer is claimed, false otherwise

See alsodma_timer_claim

◆ dma_timer_set_fraction()

static void dma_timer_set_fraction ( uint  timer,
uint16_t  numerator,
uint16_t  denominator 
)
inlinestatic

Set the divider for the given DMA timer.

The timer will run at the system_clock_freq * numerator / denominator, so this is the speed that data elements will be transferred at via a DMA channel using this timer as a DREQ

Parameters

timer the dma timer
numerator the fraction's numerator
denominator the fraction's denominator

◆ dma_timer_unclaim()

void dma_timer_unclaim ( uint  timer )

Mark a dma timer as no longer used.

Method for cooperative claiming of hardware.

Parameters

timer the dma timer to release

◆ dma_unclaim_mask()

void dma_unclaim_mask ( uint32_t  channel_mask )

Mark multiple dma channels as no longer used.

Parameters

channel_mask Bitfield of all channels to unclaim (bit 0 == channel 0, bit 1 == channel 1 etc)

channel_config

DMA channel configuration. More...

Functions

Detailed Description

DMA channel configuration.

A DMA channel needs to be configured, these functions provide handy helpers to set up configuration structures. See dma_channel_config

Function Documentation

◆ channel_config_get_ctrl_value()
static uint32_t channel_config_get_ctrl_value ( const dma_channel_config config )
inlinestatic

Get the raw configuration register from a channel configuration.

Parameters

config Pointer to a config structure.

Returns

Register content

◆ channel_config_set_bswap()
static void channel_config_set_bswap ( dma_channel_config c,
bool  bswap 
)
inlinestatic

Set DMA byte swapping config in a channel configuration object.

No effect for byte data, for halfword data, the two bytes of each halfword are swapped. For word data, the four bytes of each word are swapped to reverse their order.

Parameters

c Pointer to channel configuration object
bswap True to enable byte swapping
◆ channel_config_set_chain_to()
static void channel_config_set_chain_to ( dma_channel_config c,
uint  chain_to 
)
inlinestatic

Set DMA channel chain_to channel in a channel configuration object.

When this channel completes, it will trigger the channel indicated by chain_to. Disable by setting chain_to to itself (the same channel)

Parameters

c Pointer to channel configuration object
chain_to Channel to trigger when this channel completes.
◆ channel_config_set_dreq()
static void channel_config_set_dreq ( dma_channel_config c,
uint  dreq 
)
inlinestatic

Select a transfer request signal in a channel configuration object.

The channel uses the transfer request signal to pace its data transfer rate. Sources for TREQ signals are internal (TIMERS) or external (DREQ, a Data Request from the system). 0x0 to 0x3a -> select DREQ n as TREQ 0x3b -> Select Timer 0 as TREQ 0x3c -> Select Timer 1 as TREQ 0x3d -> Select Timer 2 as TREQ (Optional) 0x3e -> Select Timer 3 as TREQ (Optional) 0x3f -> Permanent request, for unpaced transfers.

Parameters

c Pointer to channel configuration data
dreq Source (see description)
◆ channel_config_set_enable()
static void channel_config_set_enable ( dma_channel_config c,
bool  enable 
)
inlinestatic

Enable/Disable the DMA channel in a channel configuration object.

When false, the channel will ignore triggers, stop issuing transfers, and pause the current transfer sequence (i.e. BUSY will remain high if already high)

Parameters

c Pointer to channel configuration object
enable True to enable the DMA channel. When enabled, the channel will respond to triggering events, and start transferring data.
◆ channel_config_set_high_priority()
static void channel_config_set_high_priority ( dma_channel_config c,
bool  high_priority 
)
inlinestatic

Set the channel priority in a channel configuration object.

When true, gives a channel preferential treatment in issue scheduling: in each scheduling round, all high priority channels are considered first, and then only a single low priority channel, before returning to the high priority channels.

This only affects the order in which the DMA schedules channels. The DMA's bus priority is not changed. If the DMA is not saturated then a low priority channel will see no loss of throughput.

Parameters

c Pointer to channel configuration object
high_priority True to enable high priority
◆ channel_config_set_irq_quiet()
static void channel_config_set_irq_quiet ( dma_channel_config c,
bool  irq_quiet 
)
inlinestatic

Set IRQ quiet mode in a channel configuration object.

In QUIET mode, the channel does not generate IRQs at the end of every transfer block. Instead, an IRQ is raised when NULL is written to a trigger register, indicating the end of a control block chain.

Parameters

c Pointer to channel configuration object
irq_quiet True to enable quiet mode, false to disable.
◆ channel_config_set_read_increment()
static void channel_config_set_read_increment ( dma_channel_config c,
bool  incr 
)
inlinestatic

Set DMA channel read increment in a channel configuration object.

Parameters

c Pointer to channel configuration object
incr True to enable read address increments, if false, each read will be from the same address Usually disabled for peripheral to memory transfers
◆ channel_config_set_ring()
static void channel_config_set_ring ( dma_channel_config c,
bool  write,
uint  size_bits 
)
inlinestatic

Set address wrapping parameters in a channel configuration object.

Size of address wrap region. If 0, don’t wrap. For values n > 0, only the lower n bits of the address will change. This wraps the address on a (1 << n) byte boundary, facilitating access to naturally-aligned ring buffers. Ring sizes between 2 and 32768 bytes are possible (size_bits from 1 - 15)

0x0 -> No wrapping.

Parameters

c Pointer to channel configuration object
write True to apply to write addresses, false to apply to read addresses
size_bits 0 to disable wrapping. Otherwise the size in bits of the changing part of the address. Effectively wraps the address on a (1 << size_bits) byte boundary.
◆ channel_config_set_sniff_enable()
static void channel_config_set_sniff_enable ( dma_channel_config c,
bool  sniff_enable 
)
inlinestatic

Enable access to channel by sniff hardware in a channel configuration object.

Sniff HW must be enabled and have this channel selected.

Parameters

c Pointer to channel configuration object
sniff_enable True to enable the Sniff HW access to this DMA channel.
◆ channel_config_set_transfer_data_size()
static void channel_config_set_transfer_data_size ( dma_channel_config c,
enum dma_channel_transfer_size  size 
)
inlinestatic

Set the size of each DMA bus transfer in a channel configuration object.

Set the size of each bus transfer (byte/halfword/word). The read and write addresses advance by the specific amount (1/2/4 bytes) with each transfer.

Parameters

c Pointer to channel configuration object
size See enum for possible values.
◆ channel_config_set_write_increment()
static void channel_config_set_write_increment ( dma_channel_config c,
bool  incr 
)
inlinestatic

Set DMA channel write increment in a channel configuration object.

Parameters

c Pointer to channel configuration object
incr True to enable write address increments, if false, each write will be to the same address Usually disabled for memory to peripheral transfers
◆ dma_channel_get_default_config()
static dma_channel_config dma_channel_get_default_config ( uint  channel )
inlinestatic

Get the default channel configuration for a given channel.

Setting Default
Read Increment true
Write Increment false
DReq DREQ_FORCE
Chain to self
Data size DMA_SIZE_32
Ring write=false, size=0 (i.e. off)
Byte Swap false
Quiet IRQs false
High Priority false
Channel Enable true
Sniff Enable false

Parameters

channel DMA channel

Returns

the default configuration which can then be modified.

◆ dma_get_channel_config()
static dma_channel_config dma_get_channel_config ( uint  channel )
inlinestatic

Get the current configuration for the specified channel.

Parameters

channel DMA channel

Returns

The current configuration as read from the HW register (not cached)

hardware_exception

Part of: Hardware APIs

Typedefs

Enumerations

  • enum  exception_number {
      NMI_EXCEPTION = -14 , HARDFAULT_EXCEPTION = -13 , SVCALL_EXCEPTION = -5 , PENDSV_EXCEPTION = -2 ,
      SYSTICK_EXCEPTION = -1
    }

  •  Exception number definitions. More...

Functions

Detailed Description

Methods for setting processor exception handlers

Exceptions are identified by a exception_number which is a number from -15 to -1; these are the numbers relative to the index of the first IRQ vector in the vector table. (i.e. vector table index is exception_num plus 16)

There is one set of exception handlers per core, so the exception handlers for each core as set by these methods are independent.

Note
That all exception APIs affect the executing core only (i.e. the core calling the function).

Typedef Documentation

◆ exception_handler_t

typedef void(* exception_handler_t) (void)

Exception handler function type.

All exception handlers should be of this type, and follow normal ARM EABI register saving conventions

Enumeration Type Documentation

◆ exception_number

Exception number definitions.

Note for consistency with irq numbers, these numbers are defined to be negative. The VTABLE index is the number here plus 16.

Name Value Exception
NMI_EXCEPTION -14 Non Maskable Interrupt
HARDFAULT_EXCEPTION -13 HardFault
SVCALL_EXCEPTION -5 SV Call
PENDSV_EXCEPTION -2 Pend SV
SYSTICK_EXCEPTION -1 System Tick

Function Documentation

◆ exception_get_vtable_handler()

exception_handler_t exception_get_vtable_handler ( enum exception_number  num )

Get the current exception handler for the specified exception from the currently installed vector table of the execution core.

Parameters

num Exception number

Returns

the address stored in the VTABLE for the given exception number

◆ exception_restore_handler()

void exception_restore_handler ( enum exception_number  num,
exception_handler_t  original_handler 
)

Restore the original exception handler for an exception on this core.

This method may be used to restore the exception handler for an exception on this core to the state prior to the call to exception_set_exclusive_handler(), so that exception_set_exclusive_handler() may be called again in the future.

Parameters

num Exception number exception_number
original_handler The original handler returned from exception_set_exclusive_handler

See alsoexception_set_exclusive_handler()

◆ exception_set_exclusive_handler()

exception_handler_t exception_set_exclusive_handler ( enum exception_number  num,
exception_handler_t  handler 
)

Set the exception handler for an exception on the executing core.

This method will assert if an exception handler has been set for this exception number on this core via this method, without an intervening restore via exception_restore_handler.

Note
this method may not be used to override an exception handler that was specified at link time by providing a strong replacement for the weakly defined stub exception handlers. It will assert in this case too.

Parameters

num Exception number
handler The handler to set

See alsoexception_number

hardware_flash

Part of: Hardware APIs

Functions

  • void flash_range_erase (uint32_t flash_offs, size_t count)

  •  Erase areas of flash.

  • void flash_range_program (uint32_t flash_offs, const uint8_t *data, size_t count)

  •  Program flash.

  • void flash_get_unique_id (uint8_t *id_out)

  •  Get flash unique 64 bit identifier.

  • void flash_do_cmd (const uint8_t *txbuf, uint8_t *rxbuf, size_t count)

  •  Execute bidirectional flash command.

Detailed Description

Low level flash programming and erase API

Note these functions are unsafe if you are using both cores, and the other is executing from flash concurrently with the operation. In this could be the case, you must perform your own synchronisation to make sure that no XIP accesses take place during flash programming. One option is to use the lockout functions.

Likewise they are unsafe if you have interrupt handlers or an interrupt vector table in flash, so you must disable interrupts before calling in this case.

If PICO_NO_FLASH=1 is not defined (i.e. if the program is built to run from flash) then these functions will make a static copy of the second stage bootloader in SRAM, and use this to reenter execute-in-place mode after programming or erasing flash, so that they can safely be called from flash-resident code.

Example

#include <stdio.h>
#include <stdlib.h>
#include "pico/stdlib.h"
#include "hardware/flash.h"
// We're going to erase and reprogram a region 256k from the start of flash.
// Once done, we can access this at XIP_BASE + 256k.
#define FLASH_TARGET_OFFSET (256 * 1024)
const uint8_t *flash_target_contents = (const uint8_t *) (XIP_BASE + FLASH_TARGET_OFFSET);
void print_buf(const uint8_t *buf, size_t len) {
for (size_t i = 0; i < len; ++i) {
printf("%02x", buf[i]);
if (i % 16 == 15)
printf("\n");
else
printf(" ");
}
}
int main() {
uint8_t random_data[FLASH_PAGE_SIZE];
for (int i = 0; i < FLASH_PAGE_SIZE; ++i)
random_data[i] = rand() >> 16;
printf("Generated random data:\n");
print_buf(random_data, FLASH_PAGE_SIZE);
// Note that a whole number of sectors must be erased at a time.
printf("\nErasing target region...\n");
flash_range_erase(FLASH_TARGET_OFFSET, FLASH_SECTOR_SIZE);
printf("Done. Read back target region:\n");
print_buf(flash_target_contents, FLASH_PAGE_SIZE);
printf("\nProgramming target region...\n");
flash_range_program(FLASH_TARGET_OFFSET, random_data, FLASH_PAGE_SIZE);
printf("Done. Read back target region:\n");
print_buf(flash_target_contents, FLASH_PAGE_SIZE);
bool mismatch = false;
for (int i = 0; i < FLASH_PAGE_SIZE; ++i) {
if (random_data[i] != flash_target_contents[i])
mismatch = true;
}
if (mismatch)
printf("Programming failed!\n");
else
printf("Programming successful!\n");
}
void __no_inline_not_in_flash_func() flash_range_program(uint32_t flash_offs, const uint8_t *data, size_t count)
Program flash.
Definition: flash.c:86
void __no_inline_not_in_flash_func() flash_range_erase(uint32_t flash_offs, size_t count)
Erase areas of flash.
Definition: flash.c:63
bool stdio_init_all(void)
Initialize all of the present standard stdio types that are linked into the binary.
Definition: stdio.c:283

Function Documentation

◆ flash_do_cmd()

void flash_do_cmd ( const uint8_t *  txbuf,
uint8_t *  rxbuf,
size_t  count 
)

Execute bidirectional flash command.

Low-level function to execute a serial command on a flash device attached to the QSPI interface. Bytes are simultaneously transmitted and received from txbuf and to rxbuf. Therefore, both buffers must be the same length, count, which is the length of the overall transaction. This is useful for reading metadata from the flash chip, such as device ID or SFDP parameters.

The XIP cache is flushed following each command, in case flash state has been modified. Like other hardware_flash functions, the flash is not accessible for execute-in-place transfers whilst the command is in progress, so entering a flash-resident interrupt handler or executing flash code on the second core concurrently will be fatal. To avoid these pitfalls it is recommended that this function only be used to extract flash metadata during startup, before the main application begins to run: see the implementation of pico_get_unique_id() for an example of this.

Parameters

txbuf Pointer to a byte buffer which will be transmitted to the flash
rxbuf Pointer to a byte buffer where data received from the flash will be written. txbuf and rxbuf may be the same buffer.
count Length in bytes of txbuf and of rxbuf

◆ flash_get_unique_id()

void flash_get_unique_id ( uint8_t *  id_out )

Get flash unique 64 bit identifier.

Use a standard 4Bh RUID instruction to retrieve the 64 bit unique identifier from a flash device attached to the QSPI interface. Since there is a 1:1 association between the MCU and this flash, this also serves as a unique identifier for the board.

Parameters

id_out Pointer to an 8-byte buffer to which the ID will be written

◆ flash_range_erase()

void flash_range_erase ( uint32_t  flash_offs,
size_t  count 
)

Erase areas of flash.

Parameters

flash_offs Offset into flash, in bytes, to start the erase. Must be aligned to a 4096-byte flash sector.
count Number of bytes to be erased. Must be a multiple of 4096 bytes (one sector).

◆ flash_range_program()

void flash_range_program ( uint32_t  flash_offs,
const uint8_t *  data,
size_t  count 
)

Program flash.

Parameters

flash_offs Flash address of the first byte to be programmed. Must be aligned to a 256-byte flash page.
data Pointer to the data to program into flash
count Number of bytes to program. Must be a multiple of 256 bytes (one page).

hardware_gpio

Part of: Hardware APIs

Typedefs

Enumerations

Functions

Detailed Description

General Purpose Input/Output (GPIO) API

RP2040 has 36 multi-functional General Purpose Input / Output (GPIO) pins, divided into two banks. In a typical use case, the pins in the QSPI bank (QSPI_SS, QSPI_SCLK and QSPI_SD0 to QSPI_SD3) are used to execute code from an external flash device, leaving the User bank (GPIO0 to GPIO29) for the programmer to use. All GPIOs support digital input and output, but GPIO26 to GPIO29 can also be used as inputs to the chip’s Analogue to Digital Converter (ADC). Each GPIO can be controlled directly by software running on the processors, or by a number of other functional blocks.

The function allocated to each GPIO is selected by calling the gpio_set_function function.

Note
Not all functions are available on all pins.

Each GPIO can have one function selected at a time. Likewise, each peripheral input (e.g. UART0 RX) should only be selected on one GPIO at a time. If the same peripheral input is connected to multiple GPIOs, the peripheral sees the logical OR of these GPIO inputs. Please refer to the datasheet for more information on GPIO function select.

Function Select Table

GPIO F1 F2 F3 F4 F5 F6 F7 F8 F9
0 SPI0 RX UART0 TX I2C0 SDA PWM0 A SIO PIO0 PIO1 USB OVCUR DET
1 SPI0 CSn UART0 RX I2C0 SCL PWM0 B SIO PIO0 PIO1 USB VBUS DET
2 SPI0 SCK UART0 CTS I2C1 SDA PWM1 A SIO PIO0 PIO1 USB VBUS EN
3 SPI0 TX UART0 RTS I2C1 SCL PWM1 B SIO PIO0 PIO1 USB OVCUR DET
4 SPI0 RX UART1 TX I2C0 SDA PWM2 A SIO PIO0 PIO1 USB VBUS DET
5 SPI0 CSn UART1 RX I2C0 SCL PWM2 B SIO PIO0 PIO1 USB VBUS EN
6 SPI0 SCK UART1 CTS I2C1 SDA PWM3 A SIO PIO0 PIO1 USB OVCUR DET
7 SPI0 TX UART1 RTS I2C1 SCL PWM3 B SIO PIO0 PIO1 USB VBUS DET
8 SPI1 RX UART1 TX I2C0 SDA PWM4 A SIO PIO0 PIO1 USB VBUS EN
9 SPI1 CSn UART1 RX I2C0 SCL PWM4 B SIO PIO0 PIO1 USB OVCUR DET
10 SPI1 SCK UART1 CTS I2C1 SDA PWM5 A SIO PIO0 PIO1 USB VBUS DET
11 SPI1 TX UART1 RTS I2C1 SCL PWM5 B SIO PIO0 PIO1 USB VBUS EN
12 SPI1 RX UART0 TX I2C0 SDA PWM6 A SIO PIO0 PIO1 USB OVCUR DET
13 SPI1 CSn UART0 RX I2C0 SCL PWM6 B SIO PIO0 PIO1 USB VBUS DET
14 SPI1 SCK UART0 CTS I2C1 SDA PWM7 A SIO PIO0 PIO1 USB VBUS EN
15 SPI1 TX UART0 RTS I2C1 SCL PWM7 B SIO PIO0 PIO1 USB OVCUR DET
16 SPI0 RX UART0 TX I2C0 SDA PWM0 A SIO PIO0 PIO1 USB VBUS DET
17 SPI0 CSn UART0 RX I2C0 SCL PWM0 B SIO PIO0 PIO1 USB VBUS EN
18 SPI0 SCK UART0 CTS I2C1 SDA PWM1 A SIO PIO0 PIO1 USB OVCUR DET
19 SPI0 TX UART0 RTS I2C1 SCL PWM1 B SIO PIO0 PIO1 USB VBUS DET
20 SPI0 RX UART1 TX I2C0 SDA PWM2 A SIO PIO0 PIO1 CLOCK GPIN0 USB VBUS EN
21 SPI0 CSn UART1 RX I2C0 SCL PWM2 B SIO PIO0 PIO1 CLOCK GPOUT0 USB OVCUR DET
22 SPI0 SCK UART1 CTS I2C1 SDA PWM3 A SIO PIO0 PIO1 CLOCK GPIN1 USB VBUS DET
23 SPI0 TX UART1 RTS I2C1 SCL PWM3 B SIO PIO0 PIO1 CLOCK GPOUT1 USB VBUS EN
24 SPI1 RX UART1 TX I2C0 SDA PWM4 A SIO PIO0 PIO1 CLOCK GPOUT2 USB OVCUR DET
25 SPI1 CSn UART1 RX I2C0 SCL PWM4 B SIO PIO0 PIO1 CLOCK GPOUT3 USB VBUS DET
26 SPI1 SCK UART1 CTS I2C1 SDA PWM5 A SIO PIO0 PIO1 USB VBUS EN
27 SPI1 TX UART1 RTS I2C1 SCL PWM5 B SIO PIO0 PIO1 USB OVCUR DET
28 SPI1 RX UART0 TX I2C0 SDA PWM6 A SIO PIO0 PIO1 USB VBUS DET
29 SPI1 CSn UART0 RX I2C0 SCL PWM6 B SIO PIO0 PIO1 USB VBUS EN

Typedef Documentation

◆ gpio_irq_callback_t

typedef void(* gpio_irq_callback_t) (uint gpio, uint32_t event_mask)

Callback function type for GPIO events

Parameters

gpio Which GPIO caused this interrupt
event_mask Which events caused this interrupt. See gpio_irq_level for details.

See alsogpio_set_irq_enabled_with_callback() gpio_set_irq_callback()

Enumeration Type Documentation

◆ gpio_drive_strength

Drive strength levels for GPIO outputs.

Drive strength levels for GPIO outputs.

See alsogpio_set_drive_strength

Enumerator
GPIO_DRIVE_STRENGTH_2MA 

2 mA nominal drive strength

GPIO_DRIVE_STRENGTH_4MA 

4 mA nominal drive strength

GPIO_DRIVE_STRENGTH_8MA 

8 mA nominal drive strength

GPIO_DRIVE_STRENGTH_12MA 

12 mA nominal drive strength

◆ gpio_function

GPIO function definitions for use with function select.

GPIO function selectors

Each GPIO can have one function selected at a time. Likewise, each peripheral input (e.g. UART0 RX) should only be selected on one GPIO at a time. If the same peripheral input is connected to multiple GPIOs, the peripheral sees the logical OR of these GPIO inputs.

Please refer to the datasheet for more information on GPIO function selection.

◆ gpio_irq_level

GPIO Interrupt level definitions (GPIO events)

GPIO Interrupt levels

An interrupt can be generated for every GPIO pin in 4 scenarios:

  • Level High: the GPIO pin is a logical 1

  • Level Low: the GPIO pin is a logical 0

  • Edge High: the GPIO has transitioned from a logical 0 to a logical 1

  • Edge Low: the GPIO has transitioned from a logical 1 to a logical 0

The level interrupts are not latched. This means that if the pin is a logical 1 and the level high interrupt is active, it will become inactive as soon as the pin changes to a logical 0. The edge interrupts are stored in the INTR register and can be cleared by writing to the INTR register.

◆ gpio_slew_rate

Slew rate limiting levels for GPIO outputs.

Slew rate limiting increases the minimum rise/fall time when a GPIO output is lightly loaded, which can help to reduce electromagnetic emissions.

See alsogpio_set_slew_rate

Enumerator
GPIO_SLEW_RATE_SLOW 

Slew rate limiting enabled.

GPIO_SLEW_RATE_FAST 

Slew rate limiting disabled.

Function Documentation

◆ gpio_acknowledge_irq()

void gpio_acknowledge_irq ( uint  gpio,
uint32_t  event_mask 
)

Acknowledge a GPIO interrupt for the specified events on the calling core.

Note
This may be called with a mask of any of valid bits specified in gpio_irq_level, however it has no effect on level sensitive interrupts which remain pending while the GPIO is at the specified level. When handling level sensitive interrupts, you should generally disable the interrupt (see gpio_set_irq_enabled) and then set it up again later once the GPIO level has changed (or to catch the opposite level).

Parameters

gpio GPIO number
Note
For callbacks set with gpio_set_irq_enabled_with_callback, or gpio_set_irq_callback, this function is called automatically.

Parameters

event_mask Bitmask of events to clear. See gpio_irq_level for details.

◆ gpio_add_raw_irq_handler()

static void gpio_add_raw_irq_handler ( uint  gpio,
irq_handler_t  handler 
)
inlinestatic

Adds a raw GPIO IRQ handler for a specific GPIO on the current core.

In addition to the default mechanism of a single GPIO IRQ event callback per core (see gpio_set_irq_callback), it is possible to add explicit GPIO IRQ handlers which are called independent of the default event callback.

This method adds such a callback, and disables the "default" callback for the specified GPIO.

Note
Multiple raw handlers should not be added for the same GPIO, and this method will assert if you attempt to.

A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:

void my_irq_handler(void) {
if (gpio_get_irq_event_mask(my_gpio_num) & my_gpio_event_mask) {
gpio_acknowledge_irq(my_gpio_num, my_gpio_event_mask);
// handle the IRQ
}
}
void gpio_acknowledge_irq(uint gpio, uint32_t events)
Acknowledge a GPIO interrupt for the specified events on the calling core.
Definition: gpio.c:225
static uint32_t gpio_get_irq_event_mask(uint gpio)
Return the current interrupt status (pending events) for the given GPIO.
Definition: gpio.h:461

Parameters

gpio the GPIO number that will no longer be passed to the default callback for this core
handler the handler to add to the list of GPIO IRQ handlers for this core

◆ gpio_add_raw_irq_handler_masked()

void gpio_add_raw_irq_handler_masked ( uint  gpio_mask,
irq_handler_t  handler 
)

Adds a raw GPIO IRQ handler for the specified GPIOs on the current core.

In addition to the default mechanism of a single GPIO IRQ event callback per core (see gpio_set_irq_callback), it is possible to add explicit GPIO IRQ handlers which are called independent of the default event callback.

This method adds such a callback, and disables the "default" callback for the specified GPIOs.

Note
Multiple raw handlers should not be added for the same GPIOs, and this method will assert if you attempt to.

A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:

void my_irq_handler(void) {
if (gpio_get_irq_event_mask(my_gpio_num) & my_gpio_event_mask) {
gpio_acknowledge_irq(my_gpio_num, my_gpio_event_mask);
// handle the IRQ
}
if (gpio_get_irq_event_mask(my_gpio_num2) & my_gpio_event_mask2) {
gpio_acknowledge_irq(my_gpio_num2, my_gpio_event_mask2);
// handle the IRQ
}
}

Parameters

gpio_mask a bit mask of the GPIO numbers that will no longer be passed to the default callback for this core
handler the handler to add to the list of GPIO IRQ handlers for this core

◆ gpio_add_raw_irq_handler_with_order_priority()

static void gpio_add_raw_irq_handler_with_order_priority ( uint  gpio,
irq_handler_t  handler,
uint8_t  order_priority 
)
inlinestatic

Adds a raw GPIO IRQ handler for a specific GPIO on the current core.

In addition to the default mechanism of a single GPIO IRQ event callback per core (see gpio_set_irq_callback), it is possible to add explicit GPIO IRQ handlers which are called independent of the default callback. The order relative to the default callback can be controlled via the order_priority parameter(the default callback has the priority GPIO_IRQ_CALLBACK_ORDER_PRIORITY which defaults to the lowest priority with the intention of it running last).

This method adds such a callback, and disables the "default" callback for the specified GPIO.

Note
Multiple raw handlers should not be added for the same GPIO, and this method will assert if you attempt to.

A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:

void my_irq_handler(void) {
if (gpio_get_irq_event_mask(my_gpio_num) & my_gpio_event_mask) {
gpio_acknowledge_irq(my_gpio_num, my_gpio_event_mask);
// handle the IRQ
}
}

Parameters

gpio the GPIO number that will no longer be passed to the default callback for this core
handler the handler to add to the list of GPIO IRQ handlers for this core
order_priority the priority order to determine the relative position of the handler in the list of GPIO IRQ handlers for this core.

◆ gpio_add_raw_irq_handler_with_order_priority_masked()

void gpio_add_raw_irq_handler_with_order_priority_masked ( uint  gpio_mask,
irq_handler_t  handler,
uint8_t  order_priority 
)

Adds a raw GPIO IRQ handler for the specified GPIOs on the current core.

In addition to the default mechanism of a single GPIO IRQ event callback per core (see gpio_set_irq_callback), it is possible to add explicit GPIO IRQ handlers which are called independent of the default callback. The order relative to the default callback can be controlled via the order_priority parameter (the default callback has the priority GPIO_IRQ_CALLBACK_ORDER_PRIORITY which defaults to the lowest priority with the intention of it running last).

This method adds such an explicit GPIO IRQ handler, and disables the "default" callback for the specified GPIOs.

Note
Multiple raw handlers should not be added for the same GPIOs, and this method will assert if you attempt to.

A raw handler should check for whichever GPIOs and events it handles, and acknowledge them itself; it might look something like:

void my_irq_handler(void) {
if (gpio_get_irq_event_mask(my_gpio_num) & my_gpio_event_mask) {
gpio_acknowledge_irq(my_gpio_num, my_gpio_event_mask);
// handle the IRQ
}
if (gpio_get_irq_event_mask(my_gpio_num2) & my_gpio_event_mask2) {
gpio_acknowledge_irq(my_gpio_num2, my_gpio_event_mask2);
// handle the IRQ
}
}

Parameters

gpio_mask a bit mask of the GPIO numbers that will no longer be passed to the default callback for this core
handler the handler to add to the list of GPIO IRQ handlers for this core
order_priority the priority order to determine the relative position of the handler in the list of GPIO IRQ handlers for this core.

◆ gpio_clr_mask()

static void gpio_clr_mask ( uint32_t  mask )
inlinestatic

Drive low every GPIO appearing in mask.

Parameters

mask Bitmask of GPIO values to clear, as bits 0-29

◆ gpio_deinit()

void gpio_deinit ( uint  gpio )

Resets a GPIO back to the NULL function, i.e. disables it.

Parameters

gpio GPIO number

◆ gpio_disable_pulls()

static void gpio_disable_pulls ( uint  gpio )
inlinestatic

Disable pulls on specified GPIO.

Parameters

gpio GPIO number

◆ gpio_get()

static bool gpio_get ( uint  gpio )
inlinestatic

Get state of a single specified GPIO.

Parameters

gpio GPIO number

Returns

Current state of the GPIO. 0 for low, non-zero for high

◆ gpio_get_all()

static uint32_t gpio_get_all ( void  )
inlinestatic

Get raw value of all GPIOs.

Returns

Bitmask of raw GPIO values, as bits 0-29

◆ gpio_get_dir()

static uint gpio_get_dir ( uint  gpio )
inlinestatic

Get a specific GPIO direction.

Parameters

gpio GPIO number

Returns

1 for out, 0 for in

◆ gpio_get_drive_strength()

enum gpio_drive_strength gpio_get_drive_strength ( uint  gpio )

Determine current slew rate for a specified GPIO.

See alsogpio_set_drive_strength

Parameters

gpio GPIO number

Returns

Current drive strength of that GPIO

◆ gpio_get_function()

enum gpio_function gpio_get_function ( uint  gpio )

Determine current GPIO function.

Parameters

gpio GPIO number

Returns

Which GPIO function is currently selected from list gpio_function

◆ gpio_get_irq_event_mask()

static uint32_t gpio_get_irq_event_mask ( uint  gpio )
inlinestatic

Return the current interrupt status (pending events) for the given GPIO.

Parameters

gpio GPIO number

Returns

Bitmask of events that are currently pending for the GPIO. See gpio_irq_level for details.

See alsogpio_acknowledge_irq

◆ gpio_get_out_level()

static bool gpio_get_out_level ( uint  gpio )
inlinestatic

Determine whether a GPIO is currently driven high or low.

This function returns the high/low output level most recently assigned to a GPIO via gpio_put() or similar. This is the value that is presented outward to the IO muxing, not the input level back from the pad (which can be read using gpio_get()).

To avoid races, this function must not be used for read-modify-write sequences when driving GPIOs – instead functions like gpio_put() should be used to atomically update GPIOs. This accessor is intended for debug use only.

Parameters

gpio GPIO number

Returns

true if the GPIO output level is high, false if low.

◆ gpio_get_slew_rate()

enum gpio_slew_rate gpio_get_slew_rate ( uint  gpio )

Determine current slew rate for a specified GPIO.

See alsogpio_set_slew_rate

Parameters

gpio GPIO number

Returns

Current slew rate of that GPIO

◆ gpio_init()

void gpio_init ( uint  gpio )

Initialise a GPIO for (enabled I/O and set func to GPIO_FUNC_SIO)

Clear the output enable (i.e. set to input). Clear any output value.

Parameters

gpio GPIO number

◆ gpio_init_mask()

void gpio_init_mask ( uint  gpio_mask )

Initialise multiple GPIOs (enabled I/O and set func to GPIO_FUNC_SIO)

Clear the output enable (i.e. set to input). Clear any output value.

Parameters

gpio_mask Mask with 1 bit per GPIO number to initialize

◆ gpio_is_dir_out()

static bool gpio_is_dir_out ( uint  gpio )
inlinestatic

Check if a specific GPIO direction is OUT.

Parameters

gpio GPIO number

Returns

true if the direction for the pin is OUT

◆ gpio_is_input_hysteresis_enabled()

bool gpio_is_input_hysteresis_enabled ( uint  gpio )

Determine whether input hysteresis is enabled on a specified GPIO.

See alsogpio_set_input_hysteresis_enabled

Parameters

gpio GPIO number

◆ gpio_is_pulled_down()

static bool gpio_is_pulled_down ( uint  gpio )
inlinestatic

Determine if the specified GPIO is pulled down.

Parameters

gpio GPIO number

Returns

true if the GPIO is pulled down

◆ gpio_is_pulled_up()

static bool gpio_is_pulled_up ( uint  gpio )
inlinestatic

Determine if the specified GPIO is pulled up.

Parameters

gpio GPIO number

Returns

true if the GPIO is pulled up

◆ gpio_pull_down()

static void gpio_pull_down ( uint  gpio )
inlinestatic

Set specified GPIO to be pulled down.

Parameters

gpio GPIO number

◆ gpio_pull_up()

static void gpio_pull_up ( uint  gpio )
inlinestatic

Set specified GPIO to be pulled up.

Parameters

gpio GPIO number

◆ gpio_put()

static void gpio_put ( uint  gpio,
bool  value 
)
inlinestatic

Drive a single GPIO high/low.

Parameters

gpio GPIO number
value If false clear the GPIO, otherwise set it.

◆ gpio_put_all()

static void gpio_put_all ( uint32_t  value )
inlinestatic

Drive all pins simultaneously.

Parameters

value Bitmask of GPIO values to change, as bits 0-29

◆ gpio_put_masked()

static void gpio_put_masked ( uint32_t  mask,
uint32_t  value 
)
inlinestatic

Drive GPIO high/low depending on parameters.

Parameters

mask Bitmask of GPIO values to change, as bits 0-29
value Value to set

For each 1 bit in mask, drive that pin to the value given by corresponding bit in value, leaving other pins unchanged. Since this uses the TOGL alias, it is concurrency-safe with e.g. an IRQ bashing different pins from the same core.

◆ gpio_remove_raw_irq_handler()

static void gpio_remove_raw_irq_handler ( uint  gpio,
irq_handler_t  handler 
)
inlinestatic

Removes a raw GPIO IRQ handler for the specified GPIO on the current core.

In addition to the default mechanism of a single GPIO IRQ event callback per core (see gpio_set_irq_callback), it is possible to add explicit GPIO IRQ handlers which are called independent of the default event callback.

This method removes such a callback, and enables the "default" callback for the specified GPIO.

Parameters

gpio the GPIO number that will now be passed to the default callback for this core
handler the handler to remove from the list of GPIO IRQ handlers for this core

◆ gpio_remove_raw_irq_handler_masked()

void gpio_remove_raw_irq_handler_masked ( uint  gpio_mask,
irq_handler_t  handler 
)

Removes a raw GPIO IRQ handler for the specified GPIOs on the current core.

In addition to the default mechanism of a single GPIO IRQ event callback per core (see gpio_set_irq_callback), it is possible to add explicit GPIO IRQ handlers which are called independent of the default event callback.

This method removes such a callback, and enables the "default" callback for the specified GPIOs.

Parameters

gpio_mask a bit mask of the GPIO numbers that will now be passed to the default callback for this core
handler the handler to remove from the list of GPIO IRQ handlers for this core

◆ gpio_set_dir()

static void gpio_set_dir ( uint  gpio,
bool  out 
)
inlinestatic

Set a single GPIO direction.

Parameters

gpio GPIO number
out true for out, false for in

◆ gpio_set_dir_all_bits()

static void gpio_set_dir_all_bits ( uint32_t  values )
inlinestatic

Set direction of all pins simultaneously.

Parameters

values individual settings for each gpio; for GPIO N, bit N is 1 for out, 0 for in

◆ gpio_set_dir_in_masked()

static void gpio_set_dir_in_masked ( uint32_t  mask )
inlinestatic

Set a number of GPIOs to input.

Parameters

mask Bitmask of GPIO to set to input, as bits 0-29

◆ gpio_set_dir_masked()

static void gpio_set_dir_masked ( uint32_t  mask,
uint32_t  value 
)
inlinestatic

Set multiple GPIO directions.

Parameters

mask Bitmask of GPIO to set to input, as bits 0-29
value Values to set

For each 1 bit in "mask", switch that pin to the direction given by corresponding bit in "value", leaving other pins unchanged. E.g. gpio_set_dir_masked(0x3, 0x2); -> set pin 0 to input, pin 1 to output, simultaneously.

◆ gpio_set_dir_out_masked()

static void gpio_set_dir_out_masked ( uint32_t  mask )
inlinestatic

Set a number of GPIOs to output.

Switch all GPIOs in "mask" to output

Parameters

mask Bitmask of GPIO to set to output, as bits 0-29

◆ gpio_set_dormant_irq_enabled()

void gpio_set_dormant_irq_enabled ( uint  gpio,
uint32_t  event_mask,
bool  enabled 
)

Enable dormant wake up interrupt for specified GPIO and events.

This configures IRQs to restart the XOSC or ROSC when they are disabled in dormant mode

Parameters

gpio GPIO number
event_mask Which events will cause an interrupt. See gpio_irq_level for details.
enabled Enable/disable flag

◆ gpio_set_drive_strength()

void gpio_set_drive_strength ( uint  gpio,
enum gpio_drive_strength  drive 
)

Set drive strength for a specified GPIO.

See alsogpio_get_drive_strength

Parameters

gpio GPIO number
drive GPIO output drive strength

◆ gpio_set_function()

void gpio_set_function ( uint  gpio,
enum gpio_function  fn 
)

Select GPIO function.

Parameters

gpio GPIO number
fn Which GPIO function select to use from list gpio_function

◆ gpio_set_inover()

void gpio_set_inover ( uint  gpio,
uint  value 
)

Select GPIO input override.

Parameters

gpio GPIO number
value See gpio_override

◆ gpio_set_input_enabled()

void gpio_set_input_enabled ( uint  gpio,
bool  enabled 
)

Enable GPIO input.

Parameters

gpio GPIO number
enabled true to enable input on specified GPIO

◆ gpio_set_input_hysteresis_enabled()

void gpio_set_input_hysteresis_enabled ( uint  gpio,
bool  enabled 
)

Enable/disable GPIO input hysteresis (Schmitt trigger)

Enable or disable the Schmitt trigger hysteresis on a given GPIO. This is enabled on all GPIOs by default. Disabling input hysteresis can lead to inconsistent readings when the input signal has very long rise or fall times, but slightly reduces the GPIO's input delay.

See alsogpio_is_input_hysteresis_enabled

Parameters

gpio GPIO number
enabled true to enable input hysteresis on specified GPIO

◆ gpio_set_irq_callback()

void gpio_set_irq_callback ( gpio_irq_callback_t  callback )

Set the generic callback used for GPIO IRQ events for the current core.

This function sets the callback used for all GPIO IRQs on the current core that are not explicitly hooked via gpio_add_raw_irq_handler or other gpio_add_raw_irq_handler_ functions.

This function is called with the GPIO number and event mask for each of the (not explicitly hooked) GPIOs that have events enabled and that are pending (see gpio_get_irq_event_mask).

Note
The IO IRQs are independent per-processor. This function affects the processor that calls the function.

Parameters

callback default user function to call on GPIO irq. Note only one of these can be set per processor.

◆ gpio_set_irq_enabled()

void gpio_set_irq_enabled ( uint  gpio,
uint32_t  event_mask,
bool  enabled 
)

Enable or disable specific interrupt events for specified GPIO.

This function sets which GPIO events cause a GPIO interrupt on the calling core. See gpio_set_irq_callback, gpio_set_irq_enabled_with_callback and gpio_add_raw_irq_handler to set up a GPIO interrupt handler to handle the events.

Note
The IO IRQs are independent per-processor. This configures the interrupt events for the processor that calls the function.

Parameters

gpio GPIO number
event_mask Which events will cause an interrupt
enabled Enable or disable flag

Events is a bitmask of the following gpio_irq_level values:

bit | constant | interrupt -—|-------------------------------------------------------— 0 | GPIO_IRQ_LEVEL_LOW | Continuously while level is low 1 | GPIO_IRQ_LEVEL_HIGH | Continuously while level is high 2 | GPIO_IRQ_EDGE_FALL | On each transition from high to low 3 | GPIO_IRQ_EDGE_RISE | On each transition from low to high

which are specified in gpio_irq_level

◆ gpio_set_irq_enabled_with_callback()

void gpio_set_irq_enabled_with_callback ( uint  gpio,
uint32_t  event_mask,
bool  enabled,
gpio_irq_callback_t  callback 
)

Convenience function which performs multiple GPIO IRQ related initializations.

This method is a slightly eclectic mix of initialization, that:

  • Updates whether the specified events for the specified GPIO causes an interrupt on the calling core based on the enable flag.

  • Sets the callback handler for the calling core to callback (or clears the handler if the callback is NULL).

  • Enables GPIO IRQs on the current core if enabled is true.

This method is commonly used to perform a one time setup, and following that any additional IRQs/events are enabled via gpio_set_irq_enabled. All GPIOs/events added in this way on the same core share the same callback; for multiple independent handlers for different GPIOs you should use gpio_add_raw_irq_handler and related functions.

This method is equivalent to:

gpio_set_irq_enabled(gpio, event_mask, enabled);
if (enabled) irq_set_enabled(IO_IRQ_BANK0, true);
void gpio_set_irq_enabled(uint gpio, uint32_t events, bool enabled)
Enable or disable specific interrupt events for specified GPIO.
Definition: gpio.c:176
void gpio_set_irq_callback(gpio_irq_callback_t callback)
Set the generic callback used for GPIO IRQ events for the current core.
Definition: gpio.c:190
void irq_set_enabled(uint num, bool enabled)
Enable or disable a specific interrupt on the executing core.
Definition: irq.c:49
Note
The IO IRQs are independent per-processor. This method affects only the processor that calls the function.

Parameters

gpio GPIO number
event_mask Which events will cause an interrupt. See gpio_irq_level for details.
enabled Enable or disable flag
callback user function to call on GPIO irq. if NULL, the callback is removed

◆ gpio_set_irqover()

void gpio_set_irqover ( uint  gpio,
uint  value 
)

Set GPIO IRQ override.

Optionally invert a GPIO IRQ signal, or drive it high or low

Parameters

gpio GPIO number
value See gpio_override

◆ gpio_set_mask()

static void gpio_set_mask ( uint32_t  mask )
inlinestatic

Drive high every GPIO appearing in mask.

Parameters

mask Bitmask of GPIO values to set, as bits 0-29

◆ gpio_set_oeover()

void gpio_set_oeover ( uint  gpio,
uint  value 
)

Select GPIO output enable override.

Parameters

gpio GPIO number
value See gpio_override

◆ gpio_set_outover()

void gpio_set_outover ( uint  gpio,
uint  value 
)

Set GPIO output override.

Parameters

gpio GPIO number
value See gpio_override

◆ gpio_set_pulls()

void gpio_set_pulls ( uint  gpio,
bool  up,
bool  down 
)

Select up and down pulls on specific GPIO.

Parameters

gpio GPIO number
up If true set a pull up on the GPIO
down If true set a pull down on the GPIO
Note
On the RP2040, setting both pulls enables a "bus keep" function, i.e. a weak pull to whatever is current high/low state of GPIO.

◆ gpio_set_slew_rate()

void gpio_set_slew_rate ( uint  gpio,
enum gpio_slew_rate  slew 
)

Set slew rate for a specified GPIO.

See alsogpio_get_slew_rate

Parameters

gpio GPIO number
slew GPIO output slew rate

◆ gpio_xor_mask()

static void gpio_xor_mask ( uint32_t  mask )
inlinestatic

Toggle every GPIO appearing in mask.