Difference between revisions of "Pico-sdk studies"

Revision as of 11:34, 21 August 2022

2022-08-15 Pico SDK Studies

^ 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];

So we have looked up a symbol which reflects that RP2040 DMA controller has twelve independent channels for memory to memory transfers. The Synopsys device bindings file however specifies that we must assign to node property "dma-cells" a fixed value of 1. Another good starting point to understand Pico SPI driver is in the "hello_dma" sample app. Before configuring any DMA attributes source file main.c first calls routine . . .

Another instructive Pico sample app is the DMA control block sample which uses two DMA channels to transfer a series of data blocks.

^ 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 routine is defined in dma.c. An interesting feature of this definition is the use of an extern statement within the scope of the routine body. Perhaps the C compiler does not care whether an extern qualified expression is locally scoped or file scoped, in a sense that the compiler only needs to know that given routine is defined somewhere and will be known to the linker at link time.

The following 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);})

and PARAM_ASSERTIONS_ENABLED(x) is defined,

./src/common/pico_base/include/pico/assert.h:32:#define PARAM_ASSERTIONS_ENABLED(x) ((PARAM_ASSERTIONS_ENABLED_ ## x || PARAM_ASSERTIONS_ENABLE_ALL) && !PARAM_ASSERTIONS_DISABLE_ALL)

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 }

^ *

^ Pico SDK start up APIs

Code excerpt, start up code from file [pico-sdk]/src/rp2_common/pico_stdio/stdio.c:

269 
270 void stdio_init_all(void) {
271     // todo add explicit custom, or registered although you can call stdio_enable_driver explicitly anyway
272     // These are well known ones
273 #if LIB_PICO_STDIO_UART
274     stdio_uart_init();
275 #endif
276 
277 #if LIB_PICO_STDIO_SEMIHOSTING
278     stdio_semihosting_init();
279 #endif
280 
281 #if LIB_PICO_STDIO_USB
282     stdio_usb_init();
283 #endif
284 }
285

^ 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/