abawo/pico-sdk
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Lots of Doxygen tweaks and fixes (#212)

Browse Source 
* Add documentation for gpio_irq_callback_t and rtc_callback_t (fixes #175)
 * Hook up pico_binary_info and pico_bootsel_via_double_reset to the Doxygen index
 * Add link to new Raspberry Pi Pico FAQ
 * Consistently add parentheses for \sa or \see links to function-names
 * Use consistent capitalisation for 'GitHub'
 * Small typos and markup errors
This commit is contained in:
Andrew Scheller 2021-03-02 21:37:27 +00:00 committed by graham sanderson
parent b64cb686ae
commit fc17f880fd
18 changed files with 63 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -85,7 +85,7 @@ instructions for other platforms, and just in general, we recommend you see [Ras
```
* Or with automatic download from github :
* Or with automatic download from GitHub :
1. Copy [pico_sdk_import.cmake](https://github.com/raspberrypi/pico-sdk/blob/master/external/pico_sdk_import.cmake)
from the SDK into your project directory
1. Setup a `CMakeLists.txt` like:

11
docs/DoxygenLayout.xml
View File

@ -12,16 +12,17 @@
<tab type="user" url="https://rptl.io/pico-c-sdk" visible="yes" title="Raspberry Pi Pico C/C++ SDK" intro=""/>
<tab type="user" url="https://rptl.io/pico-micropython" visible="yes" title="Raspberry Pi Pico Python SDK" intro=""/>
<tab type="user" url="https://rptl.io/pico-get-started" visible="yes" title="Getting started with Raspberry Pi Pico" intro=""/>
<tab type="user" url="https://rptl.io/pico-faq" visible="yes" title="Raspberry Pi Pico FAQ" intro=""/>
</tab>
<tab type="usergroup" url="@ref weblinks_page" visible="yes" title="Web" intro="useful weblinks">
<tab type="user" url="https://www.raspberrypi.org/" visible="yes" title="Raspberry Pi Site" intro=""/>
<tab type="user" url="https://rptl.io/rp2040-get-started" visible="yes" title="Raspberry Pi Pico Page" intro=""/>
<tab type="user" url="https://www.raspberrypi.org/forums" visible="yes" title="Raspberry Pi Forums" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-sdk" visible="yes" title="Raspberry Pi Pico SDK on Github" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-examples" visible="yes" title="Pico Examples on Github" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-extras" visible="yes" title="Pico Extras on Github" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-playground" visible="yes" title="Pico Playground on Github" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-bootrom" visible="yes" title="Pico Bootrom on Github" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-sdk" visible="yes" title="Raspberry Pi Pico SDK on GitHub" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-examples" visible="yes" title="Pico Examples on GitHub" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-extras" visible="yes" title="Pico Extras on GitHub" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-playground" visible="yes" title="Pico Playground on GitHub" intro=""/>
<tab type="user" url="https://github.com/raspberrypi/pico-bootrom" visible="yes" title="Pico Bootrom on GitHub" intro=""/>
</tab>
<tab type="pages" visible="no" title="" intro=""/>
<tab type="namespaces" visible="yes" title="">

4
docs/index.h
View File

@ -62,8 +62,10 @@
* @{
* \defgroup boot_stage2 boot_stage2
* \defgroup pico_base pico_base
* \defgroup pico_binary_info pico_binary_info
* \defgroup pico_bit_ops pico_bit_ops
* \defgroup pico_bootrom pico_bootrom
* \defgroup pico_bootsel_via_double_reset pico_bootsel_via_double_reset
* \defgroup pico_cxx_options pico_cxx_options
* \defgroup pico_divider pico_divider
* \defgroup pico_double pico_double
@ -84,4 +86,4 @@
* \defgroup boot_picoboot boot_picoboot
* \defgroup boot_uf2 boot_uf2
* @}
*/
*/

11
docs/weblinks_page.md
View File

@ -3,11 +3,12 @@
The full documentation for the RP2040 and Raspberry Pi Pico board can be found at the following links
- [RP2040 Datasheet](https://rptl.io/rp2040-datasheet)
- [Raspberry Pi Pico datasheet](https://rptl.io/pico-datasheet)
- [Hardware Design with the RP2040](https://rptl.io/rp2040-design)
- [Raspberry Pi Pico Datasheet](https://rptl.io/pico-datasheet)
- [Hardware design with the RP2040](https://rptl.io/rp2040-design)
- [Raspberry Pi Pico C/C++ SDK](https://rptl.io/pico-c-sdk)
- [Raspberry Pi Pico Python SDK](https://rptl.io/pico-micropython)
- [Getting Started with Raspberry Pi Pico](https://rptl.io/pico-get-started)
- [Getting started with Raspberry Pi Pico](https://rptl.io/pico-get-started)
- [Raspberry Pi Pico FAQ](https://rptl.io/pico-faq)
### Weblinks
@ -19,9 +20,9 @@ For the main Raspberry Pi website, [see here](https://www.raspberrypi.org)
For the Raspberry Pi Pico page, [see here](https://rptl.io/rp2040-get-started)
### Github
### GitHub
All the source code for the Raspberry Pi Pico SDK, examples and other libraries can be found on Github.
All the source code for the Raspberry Pi Pico SDK, examples and other libraries can be found on GitHub.
- [Raspberry Pi Pico SDK](https://github.com/raspberrypi/pico-sdk)
- [Pico Examples](https://github.com/raspberrypi/pico-examples)

4
src/common/pico_base/include/pico/types.h
View File

@ -21,8 +21,8 @@ typedef unsigned int uint;
The type is used instead of a raw uint64_t to prevent accidentally passing relative times or times in the wrong
time units where an absolute time is required. It is equivalent to uint64_t in release builds.
\see to_us_since_boot
\see update_us_since_boot
\see to_us_since_boot()
\see update_us_since_boot()
\ingroup timestamp
*/
#ifndef NDEBUG

6
src/common/pico_binary_info/include/pico/binary_info.h
View File

@ -7,7 +7,9 @@
#ifndef _PICO_BINARY_INFO_H
#define _PICO_BINARY_INFO_H
/**
/** \file binary_info.h
* \defgroup pico_binary_info pico_binary_info
*
* Binary info is intended for embedding machine readable information with the binary in FLASH.
*
* Example uses include:
@ -26,4 +28,4 @@
#if !PICO_NO_BINARY_INFO
#include "pico/binary_info/code.h"
#endif
#endif
#endif

4
src/common/pico_binary_info/include/pico/binary_info/code.h
View File

@ -25,12 +25,14 @@
#endif
/**
* Declare some binary information that will be included if the contain source file/line is compiled into the binary
* \ingroup pico_binary_info
*/
#define bi_decl(_decl) __bi_mark_enclosure _decl; __bi_decl(__bi_ptr_lineno_var_name, &__bi_lineno_var_name.core, ".binary_info.keep.", __used);
/**
* Declare some binary information that will be included if the function containing the decl is linked into the binary.
* The SDK uses --gc-sections, so functions that are never called will be removed by the linker, and any associated
* binary information declared this way will also be stripped
* \ingroup pico_binary_info
*/
#define bi_decl_if_func_used(_decl) ({__bi_mark_enclosure _decl; __bi_decl(__bi_ptr_lineno_var_name, &__bi_lineno_var_name.core, ".binary_info.", ); *(volatile uint8_t *)&__bi_ptr_lineno_var_name;});
@ -136,4 +138,4 @@ static const struct _binary_info_named_group __bi_lineno_var_name = { \
#define bi_3pins_with_names(p0, name0, p1, name1, p2, name2) bi_pin_mask_with_names((1u << (p0)) | (1u << (p1)) | (1u << (p2)), name0 "|" name1 "|" name2)
#define bi_4pins_with_names(p0, name0, p1, name1, p2, name2, p3, name3) bi_pin_mask_with_names((1u << (p0)) | (1u << (p1)) | (1u << (p2)) | (1u << (p3)), name0 "|" name1 "|" name2 "|" name3)
#endif
#endif

6
src/common/pico_time/include/pico/time.h
View File

@ -77,7 +77,7 @@ static inline uint32_t us_to_ms(uint64_t us) {
* \brief Convert a timestamp into a number of milliseconds since boot.
* \param t an absolute_time_t value to convert
* \return the number of microseconds since boot represented by t
* \sa to_us_since_boot
* \sa to_us_since_boot()
*/
static inline uint32_t to_ms_since_boot(absolute_time_t t) {
uint64_t us = to_us_since_boot(t);
@ -171,7 +171,7 @@ extern const absolute_time_t nil_time;
* \ingroup timestamp
* \param t the timestamp
* \return true if the timestamp is nil
* \sa nil_time()
* \sa nil_time
*/
static inline bool is_nil_time(absolute_time_t t) {
return !to_us_since_boot(t);
@ -230,7 +230,7 @@ void sleep_ms(uint32_t ms);
/*! \brief Helper method for blocking on a timeout
* \ingroup sleep
*
* This method will return in response to a an event (as per __wfe) or
* This method will return in response to an event (as per __wfe) or
* when the target time is reached, or at any point before.
*
* This method can be used to implement a lower power polling loop waiting on

2
src/rp2_common/hardware_clocks/include/hardware/clocks.h
View File

@ -140,7 +140,7 @@ uint32_t frequency_count_khz(uint src);
/*! \brief Set the "current frequency" of the clock as reported by clock_get_hz without actually changing the clock
* \ingroup hardware_clocks
*
* \see clock_get_hz
* \see clock_get_hz()
*/
void clock_set_reported_hz(enum clock_index clk_index, uint hz);

9
src/rp2_common/hardware_gpio/include/hardware/gpio.h
View File

@ -124,6 +124,13 @@ enum gpio_irq_level {
GPIO_IRQ_EDGE_RISE = 0x8u,
};
/*! Callback function type for GPIO events
* \ingroup hardware_gpio
*
* \param gpio Which GPIO caused this interrupt
* \param events Which events caused this interrupt. See \ref gpio_set_irq_enabled for details.
* \sa gpio_set_irq_enabled_with_callback()
*/
typedef void (*gpio_irq_callback_t)(uint gpio, uint32_t events);
enum gpio_override {
@ -267,7 +274,7 @@ void gpio_set_irq_enabled(uint gpio, uint32_t events, bool enabled);
* the processor that calls the function.
*
* \param gpio GPIO number
* \param events Which events will cause an interrupt See \ref gpio_set_irq_enabled for details.
* \param events Which events will cause an interrupt. See \ref gpio_set_irq_enabled for details.
* \param enabled Enable or disable flag
* \param callback user function to call on GPIO irq. Note only one of these can be set per processor.
*

10
src/rp2_common/hardware_irq/include/hardware/irq.h
View File

@ -166,7 +166,7 @@ void irq_set_mask_enabled(uint32_t mask, bool enabled);
*
* \param num Interrupt number \ref interrupt_nums
* \param handler The handler to set. See \ref irq_handler_t
* \see irq_add_shared_handler
* \see irq_add_shared_handler()
*/
void irq_set_exclusive_handler(uint num, irq_handler_t handler);
@ -177,7 +177,7 @@ void irq_set_exclusive_handler(uint num, irq_handler_t handler);
* by irq_set_exclusive_handler if there is one.
*
* \param num Interrupt number \ref interrupt_nums
* \see irq_set_exclusive_handler
* \see irq_set_exclusive_handler()
* \return handler The handler if an exclusive handler is set for the IRQ,
* NULL if no handler is set or shared/shareable handlers are installed
*/
@ -202,7 +202,7 @@ irq_handler_t irq_get_exclusive_handler(uint num);
* rule of thumb is to use PICO_SHARED_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY if you don't much care, as it is in the middle of
* the priority range by default.
*
* \see irq_set_exclusive_handler
* \see irq_set_exclusive_handler()
*/
void irq_add_shared_handler(uint num, irq_handler_t handler, uint8_t order_priority);
@ -219,8 +219,8 @@ void irq_add_shared_handler(uint num, irq_handler_t handler, uint8_t order_prior
*
* \param num Interrupt number \ref interrupt_nums
* \param handler The handler to removed.
* \see irq_set_exclusive_handler
* \see irq_add_shared_handler
* \see irq_set_exclusive_handler()
* \see irq_add_shared_handler()
*/
void irq_remove_handler(uint num, irq_handler_t handler);

18
src/rp2_common/hardware_pio/include/hardware/pio.h
View File

@ -230,7 +230,7 @@ static inline void sm_config_set_clkdiv(pio_sm_config *c, float div) {
* \param c Pointer to the configuration structure to modify
* \param div_int Integer part of the divisor
* \param div_frac Fractional part in 1/256ths
* \sa sm_config_set_clkdiv
* \sa sm_config_set_clkdiv()
*/
static inline void sm_config_set_clkdiv_int_frac(pio_sm_config *c, uint16_t div_int, uint8_t div_frac) {
c->clkdiv =
@ -463,7 +463,7 @@ bool pio_can_add_program_at_offset(PIO pio, const pio_program_t *program, uint o
/*! \brief Attempt to load the program, panicking if not possible
* \ingroup hardware_pio
*
* \see pico_can_add_program if you need to check whether the program can be loaded
* \see pio_can_add_program() if you need to check whether the program can be loaded
*
* \param pio The PIO instance; either \ref pio0 or \ref pio1
* \param program the program definition
@ -474,7 +474,7 @@ uint pio_add_program(PIO pio, const pio_program_t *program);
/*! \brief Attempt to load the program at the specified instruction memory offset, panicking if not possible
* \ingroup hardware_pio
*
* \see pico_can_add_program_at_offset if you need to check whether the program can be loaded
* \see pio_can_add_program_at_offset() if you need to check whether the program can be loaded
*
* \param pio The PIO instance; either \ref pio0 or \ref pio1
* \param program the program definition
@ -536,7 +536,7 @@ static inline void pio_sm_set_enabled(PIO pio, uint sm, bool enabled) {
* Note that this method just sets the enabled state of the state machine;
* if now enabled they continue exactly from where they left off.
*
* \see pio_enable_sm_mask_in_sync if you wish to enable multiple state machines
* \see pio_enable_sm_mask_in_sync() if you wish to enable multiple state machines
* and ensure their clock dividers are in sync.
*
* \param pio The PIO instance; either \ref pio0 or \ref pio1
@ -673,7 +673,7 @@ static inline uint8_t pio_sm_get_pc(PIO pio, uint sm) {
*
* This instruction is executed instead of the next instruction in the normal control flow on the state machine.
* Subsequent calls to this method replace the previous executed
* instruction if it is still running. \see pio_sm_is_exec_stalled to see if an executed instruction
* instruction if it is still running. \see pio_sm_is_exec_stalled() to see if an executed instruction
* is still running (i.e. it is stalled on some condition)
*
* \param pio The PIO instance; either \ref pio0 or \ref pio1
@ -704,7 +704,7 @@ static inline bool pio_sm_is_exec_stalled(PIO pio, uint sm) {
*
* This instruction is executed instead of the next instruction in the normal control flow on the state machine.
* Subsequent calls to this method replace the previous executed
* instruction if it is still running. \see pio_sm_is_exec_stalled to see if an executed instruction
* instruction if it is still running. \see pio_sm_is_exec_stalled() to see if an executed instruction
* is still running (i.e. it is stalled on some condition)
*
* \param pio The PIO instance; either \ref pio0 or \ref pio1
@ -825,7 +825,7 @@ static inline void pio_sm_set_sideset_pins(PIO pio, uint sm, uint sideset_base)
* \param sm State machine index (0..3)
* \param data the 32 bit data value
*
* \sa pio_sm_put_blocking
* \sa pio_sm_put_blocking()
*/
static inline void pio_sm_put(PIO pio, uint sm, uint32_t data) {
check_pio_param(pio);
@ -846,7 +846,7 @@ static inline void pio_sm_put(PIO pio, uint sm, uint32_t data) {
* \param pio The PIO instance; either \ref pio0 or \ref pio1
* \param sm State machine index (0..3)
*
* \sa pio_sm_get_blocking
* \sa pio_sm_get_blocking()
*/
static inline uint32_t pio_sm_get(PIO pio, uint sm) {
check_pio_param(pio);
@ -974,7 +974,7 @@ static inline uint32_t pio_sm_get_blocking(PIO pio, uint sm) {
* \param pio The PIO instance; either \ref pio0 or \ref pio1
* \param sm State machine index (0..3)
*
* \sa pio_sm_clear_fifos
* \sa pio_sm_clear_fifos()
*/
void pio_sm_drain_tx_fifo(PIO pio, uint sm);

5
src/rp2_common/hardware_rtc/include/hardware/rtc.h
View File

@ -32,6 +32,11 @@
extern "C" {
#endif
/*! Callback function type for RTC alarms
* \ingroup hardware_rtc
*
* \sa rtc_set_alarm()
*/
typedef void (*rtc_callback_t)(void);
/*! \brief Initialise the RTC system

4
src/rp2_common/hardware_timer/include/hardware/timer.h
View File

@ -115,7 +115,7 @@ static inline bool time_reached(absolute_time_t t) {
* \ingroup hardware_timer
*
* \param alarm_num the hardware alarm number
* \sa hardware_alarm_set_callback
* \sa hardware_alarm_set_callback()
*/
typedef void (*hardware_alarm_callback_t)(uint alarm_num);
@ -151,7 +151,7 @@ void hardware_alarm_unclaim(uint alarm_num);
* \param alarm_num the hardware alarm number
* \param callback the callback to install, or NULL to unset
*
* \sa hardware_alarm_set_target
* \sa hardware_alarm_set_target()
*/
void hardware_alarm_set_callback(uint alarm_num, hardware_alarm_callback_t callback);

4
src/rp2_common/hardware_watchdog/include/hardware/watchdog.h
View File

@ -32,7 +32,7 @@ extern "C" {
/*! \brief Define actions to perform at watchdog timeout
* \ingroup hardware_watchdog
*
* \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \ref delay_ms
* \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms
* parameter will not be in microseconds. See the datasheet for more details.
*
* By default the SDK assumes a 12MHz XOSC and sets the \ref watchdog_start_tick appropriately.
@ -61,7 +61,7 @@ void watchdog_update(void);
* \brief Enable the watchdog
* \ingroup hardware_watchdog
*
* \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \ref delay_ms
* \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms
* parameter will not be in microseconds. See the datasheet for more details.
*
* By default the SDK assumes a 12MHz XOSC and sets the \ref watchdog_start_tick appropriately.

2
src/rp2_common/pico_bootsel_via_double_reset/pico_bootsel_via_double_reset.c
View File

@ -24,7 +24,7 @@
#define PICO_BOOTSEL_VIA_DOUBLE_RESET_INTERFACE_DISABLE_MASK 0u
#endif
/** \defgroup pico_bootsel_via_double_reset
/** \defgroup pico_bootsel_via_double_reset pico_bootsel_via_double_reset
*
* When the 'pico_bootsel_via_double_reset' library is linked, a function is
* injected before main() which will detect when the system has been reset

2
src/rp2_common/pico_multicore/multicore.c
View File

@ -91,7 +91,7 @@ int core1_wrapper(int (*entry)(void), void *stack_base) {
}
void multicore_reset_core1() {
// Use atomic aliases just in case core 1 is also manipulating some posm state
// Use atomic aliases just in case core 1 is also manipulating some PSM state
io_rw_32 *power_off = (io_rw_32 *) (PSM_BASE + PSM_FRCE_OFF_OFFSET);
io_rw_32 *power_off_set = hw_set_alias(power_off);
io_rw_32 *power_off_clr = hw_clear_alias(power_off);

2
src/rp2_common/pico_platform/include/pico/platform.h
View File

@ -119,7 +119,7 @@ static inline uint8_t rp2040_rom_version(void) {
/**
* Empty function intended to be called by any tight hardware polling loop. using this ubiquitously
* makes it much easier to find tight loops, but also in the future #ifdef-ed support for lockup
* makes it much easier to find tight loops, but also in the future \#ifdef-ed support for lockup
* debugging might be added
*/
static inline void tight_loop_contents(void) {}