Difference between revisions of "Pico-sdk studies"

Revision as of 00:16, 19 August 2022

2022-08-15 Pico SDK Studies

ted@localhost:~/reference/pico-sdk$ grep -nr unreset_block_wait ./*
./src/rp2_common/hardware_resets/include/hardware/resets.h:88:static inline void unreset_block_wait(uint32_t bits) {
./src/rp2_common/hardware_uart/uart.c:34:    unreset_block_wait(uart_get_index(uart) ? RESETS_RESET_UART1_BITS : RESETS_RESET_UART0_BITS);
./src/rp2_common/pico_runtime/runtime.c:80:    unreset_block_wait(RESETS_RESET_BITS & ~(
./src/rp2_common/pico_runtime/runtime.c:110:    unreset_block_wait(RESETS_RESET_BITS);
./src/rp2_common/hardware_pll/pll.c:54:    unreset_block_wait(pll_reset);
./src/rp2_common/hardware_i2c/i2c.c:25:    unreset_block_wait(i2c == i2c0 ? RESETS_RESET_I2C0_BITS : RESETS_RESET_I2C1_BITS);
Binary file ./src/rp2_common/hardware_spi/.spi.c.swp matches
./src/rp2_common/hardware_spi/spi.c:18:    unreset_block_wait(spi == spi0 ? RESETS_RESET_SPI0_BITS : RESETS_RESET_SPI1_BITS);
./src/rp2_common/hardware_rtc/rtc.c:29:    unreset_block_wait(RESETS_RESET_RTC_BITS);
./src/rp2_common/hardware_adc/adc.c:14:    unreset_block_wait(RESETS_RESET_ADC_BITS);
./test/hardware_pwm_test/hardware_pwm_test.c:36:    unreset_block_wait(RESETS_RESET_PWM_BITS);

ted@localhost:~/reference/pico-sdk$

^ DMA driver details

2022-08-18

This section holds notes on RPi Pico SDK driver code for the RP2040 direct memory access unit. Goal here is to understand how Pico SDK structures its Application Programmers' Interface or API. We need to understand this in order to connect a Zephyr based application to code running on RP2040 and using its DMA. Likely we will need DMA when we enable and implement one or more SPI based peripherals, as SPI transmit and receive lines are often associated with a DMA controller to support high data transmission rates.

Search for . . .

ted@localhost:~/projects/zephyr-based/workspace-rpi-pico-work/pico-sdk$ grep -nr NUM_DMA_CHANNELS ./*
./src/host/pico_platform/include/hardware/platform_defs.h:12:#define NUM_DMA_CHANNELS 12u
. . .
./src/rp2040/hardware_structs/include/hardware/structs/dma.h:106:    dma_channel_hw_t ch[NUM_DMA_CHANNELS]; // 12
./src/rp2040/hardware_structs/include/hardware/structs/dma.h:194:    } ch[NUM_DMA_CHANNELS];

^ Pico assert.h definitions

RPi Pico SDK assert() definition is included in a section of this nn wiki page, as this Pico header file is included by both RPi Pico DMA driver and RPi Pico SPI driver. It is likely included by other Pico drivers and modules. We also include mention of this definition as recent studies of Zephyr third party drivers reveal that various projects each provide their own definitions of the C assert() construct.

$ find . -name assert.h
./common/pico_base/include/pico/assert.h

The contents of Pico SDK assert.h file are:

#ifdef __cplusplus

#include <cassert>

extern "C" {
#else
#include <assert.h>
#endif

// PICO_CONFIG: PARAM_ASSERTIONS_ENABLE_ALL, Global assert enable, type=bool, default=0, group=pico_base
// PICO_CONFIG: PARAM_ASSERTIONS_DISABLE_ALL, Global assert disable, type=bool, default=0, group=pico_base

#ifndef PARAM_ASSERTIONS_ENABLE_ALL
#define PARAM_ASSERTIONS_ENABLE_ALL 0
#endif

#ifndef PARAM_ASSERTIONS_DISABLE_ALL
#define PARAM_ASSERTIONS_DISABLE_ALL 0
#endif

#define PARAM_ASSERTIONS_ENABLED(x) ((PARAM_ASSERTIONS_ENABLED_ ## x || PARAM_ASSERTIONS_ENABLE_ALL) && !PARAM_ASSERTIONS_DISABLE_ALL)

#define invalid_params_if(x, test) ({if (PARAM_ASSERTIONS_ENABLED(x)) assert(!(test));})
#define valid_params_if(x, test) ({if (PARAM_ASSERTIONS_ENABLED(x)) assert(test);})
#define hard_assert_if(x, test) ({if (PARAM_ASSERTIONS_ENABLED(x)) hard_assert(!(test));})

#ifdef NDEBUG
extern void hard_assertion_failure(void);
static inline void hard_assert(bool condition, ...) {
    if (!condition)
        hard_assertion_failure();
}
#else
#define hard_assert assert
#endif

#ifdef __cplusplus
}
#endif
#endif

z z z

/*
 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

// ---------------------------------------
// THIS FILE IS AUTOGENERATED; DO NOT EDIT
// ---------------------------------------

#ifndef _PICO_VERSION_H
#define _PICO_VERSION_H

#define PICO_SDK_VERSION_MAJOR    ${PICO_SDK_VERSION_MAJOR}
#define PICO_SDK_VERSION_MINOR    ${PICO_SDK_VERSION_MINOR}
#define PICO_SDK_VERSION_REVISION ${PICO_SDK_VERSION_REVISION}
#define PICO_SDK_VERSION_STRING   "${PICO_SDK_VERSION_STRING}"

#endif

^ Study of DMA routine check_dma_channel_param()

The routine `check_dma_channel_param()` appears in file dma.c at line 24. In file dma.c references to this routine appear three three times and there is a conditionally compiled definition for it at line 97. There is a second place in Pico SDK where this routine is defined, in header file dma.h. The two definitions read as follows:

Excerpts 1 - check_dma_channel_param() definitions

 96 #if PARAM_ASSERTIONS_ENABLED(DMA)
 97 void check_dma_channel_param_impl(uint __unused channel) {
 98     valid_params_if(DMA, channel < NUM_DMA_CHANNELS);
 99 }
100 #endif

 49 static inline void check_dma_channel_param(__unused uint channel) {
 50 #if PARAM_ASSERTIONS_ENABLED(DMA)
 51     // this method is used a lot by inline functions so avoid code bloat by deferring to function
 52     extern void check_dma_channel_param_impl(uint channel);
 53     check_dma_channel_param_impl(channel);
 54 #endif
 55 }

The following pico-sdk routine like macro plays a role in the definition of the above routine:

./src/common/pico_base/include/pico/assert.h:35:#define valid_params_if(x, test) ({if (PARAM_ASSERTIONS_ENABLED(x)) assert(test);})

Perhaps another DMA routine's implementation will be easier to track down:

200 /*! \brief Set the size of each DMA bus transfer in a channel configuration object
201  *  \ingroup channel_config
202  *
203  * Set the size of each bus transfer (byte/halfword/word). The read and write addresses
204  * advance by the specific amount (1/2/4 bytes) with each transfer.
205  *
206  * \param c Pointer to channel configuration object
207  * \param size See enum for possible values.
208  */
209 static inline void channel_config_set_transfer_data_size(dma_channel_config *c, enum dma_channel_transfer_size size) {
210     assert(size == DMA_SIZE_8 || size == DMA_SIZE_16 || size == DMA_SIZE_32);
211     c->ctrl = (c->ctrl & ~DMA_CH0_CTRL_TRIG_DATA_SIZE_BITS) | (((uint)size) << DMA_CH0_CTRL_TRIG_DATA_SIZE_LSB);
212 }

^ Reference

1. pico-sdk/src/rp2_common/README.md . . . document explains convention of Pico library routines which names of form hardware_ and pico_.
2. https://iosoft.blog/2021/10/26/pico-adc-dma/