From fc17f880fdc0b41376cb7f98b438e3a37a4d1a2b Mon Sep 17 00:00:00 2001 From: Andrew Scheller Date: Tue, 2 Mar 2021 21:37:27 +0000 Subject: [PATCH] Lots of Doxygen tweaks and fixes (#212) * 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 --- README.md | 2 +- docs/DoxygenLayout.xml | 11 ++++++----- docs/index.h | 4 +++- docs/weblinks_page.md | 11 ++++++----- src/common/pico_base/include/pico/types.h | 4 ++-- .../include/pico/binary_info.h | 6 ++++-- .../include/pico/binary_info/code.h | 4 +++- src/common/pico_time/include/pico/time.h | 6 +++--- .../hardware_clocks/include/hardware/clocks.h | 2 +- .../hardware_gpio/include/hardware/gpio.h | 9 ++++++++- .../hardware_irq/include/hardware/irq.h | 10 +++++----- .../hardware_pio/include/hardware/pio.h | 18 +++++++++--------- .../hardware_rtc/include/hardware/rtc.h | 5 +++++ .../hardware_timer/include/hardware/timer.h | 4 ++-- .../include/hardware/watchdog.h | 4 ++-- .../pico_bootsel_via_double_reset.c | 2 +- src/rp2_common/pico_multicore/multicore.c | 2 +- .../pico_platform/include/pico/platform.h | 2 +- 18 files changed, 63 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index d7eaea7..8141c33 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/docs/DoxygenLayout.xml b/docs/DoxygenLayout.xml index b67ac97..bd9ce4b 100644 --- a/docs/DoxygenLayout.xml +++ b/docs/DoxygenLayout.xml @@ -12,16 +12,17 @@ + - - - - - + + + + + diff --git a/docs/index.h b/docs/index.h index 1432ecd..53f4674 100644 --- a/docs/index.h +++ b/docs/index.h @@ -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 * @} -*/ \ No newline at end of file +*/ diff --git a/docs/weblinks_page.md b/docs/weblinks_page.md index ebe0a3d..d4b0e9c 100644 --- a/docs/weblinks_page.md +++ b/docs/weblinks_page.md @@ -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) diff --git a/src/common/pico_base/include/pico/types.h b/src/common/pico_base/include/pico/types.h index 593a58a..51debf2 100644 --- a/src/common/pico_base/include/pico/types.h +++ b/src/common/pico_base/include/pico/types.h @@ -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 diff --git a/src/common/pico_binary_info/include/pico/binary_info.h b/src/common/pico_binary_info/include/pico/binary_info.h index 3fca34c..77b1c08 100644 --- a/src/common/pico_binary_info/include/pico/binary_info.h +++ b/src/common/pico_binary_info/include/pico/binary_info.h @@ -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 \ No newline at end of file +#endif diff --git a/src/common/pico_binary_info/include/pico/binary_info/code.h b/src/common/pico_binary_info/include/pico/binary_info/code.h index af3ce55..e87a2cd 100644 --- a/src/common/pico_binary_info/include/pico/binary_info/code.h +++ b/src/common/pico_binary_info/include/pico/binary_info/code.h @@ -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 \ No newline at end of file +#endif diff --git a/src/common/pico_time/include/pico/time.h b/src/common/pico_time/include/pico/time.h index 6bed135..1c34732 100644 --- a/src/common/pico_time/include/pico/time.h +++ b/src/common/pico_time/include/pico/time.h @@ -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 diff --git a/src/rp2_common/hardware_clocks/include/hardware/clocks.h b/src/rp2_common/hardware_clocks/include/hardware/clocks.h index 433f656..297dfa2 100644 --- a/src/rp2_common/hardware_clocks/include/hardware/clocks.h +++ b/src/rp2_common/hardware_clocks/include/hardware/clocks.h @@ -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); diff --git a/src/rp2_common/hardware_gpio/include/hardware/gpio.h b/src/rp2_common/hardware_gpio/include/hardware/gpio.h index 132efae..1a7314c 100644 --- a/src/rp2_common/hardware_gpio/include/hardware/gpio.h +++ b/src/rp2_common/hardware_gpio/include/hardware/gpio.h @@ -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. * diff --git a/src/rp2_common/hardware_irq/include/hardware/irq.h b/src/rp2_common/hardware_irq/include/hardware/irq.h index 8711026..ffdc6db 100644 --- a/src/rp2_common/hardware_irq/include/hardware/irq.h +++ b/src/rp2_common/hardware_irq/include/hardware/irq.h @@ -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); diff --git a/src/rp2_common/hardware_pio/include/hardware/pio.h b/src/rp2_common/hardware_pio/include/hardware/pio.h index 0f59f7e..2478495 100644 --- a/src/rp2_common/hardware_pio/include/hardware/pio.h +++ b/src/rp2_common/hardware_pio/include/hardware/pio.h @@ -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); diff --git a/src/rp2_common/hardware_rtc/include/hardware/rtc.h b/src/rp2_common/hardware_rtc/include/hardware/rtc.h index c054af7..8757e36 100644 --- a/src/rp2_common/hardware_rtc/include/hardware/rtc.h +++ b/src/rp2_common/hardware_rtc/include/hardware/rtc.h @@ -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 diff --git a/src/rp2_common/hardware_timer/include/hardware/timer.h b/src/rp2_common/hardware_timer/include/hardware/timer.h index 6b07abd..4665ae5 100644 --- a/src/rp2_common/hardware_timer/include/hardware/timer.h +++ b/src/rp2_common/hardware_timer/include/hardware/timer.h @@ -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); diff --git a/src/rp2_common/hardware_watchdog/include/hardware/watchdog.h b/src/rp2_common/hardware_watchdog/include/hardware/watchdog.h index c739d53..cbc43a6 100644 --- a/src/rp2_common/hardware_watchdog/include/hardware/watchdog.h +++ b/src/rp2_common/hardware_watchdog/include/hardware/watchdog.h @@ -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. diff --git a/src/rp2_common/pico_bootsel_via_double_reset/pico_bootsel_via_double_reset.c b/src/rp2_common/pico_bootsel_via_double_reset/pico_bootsel_via_double_reset.c index 451a871..c535ba5 100644 --- a/src/rp2_common/pico_bootsel_via_double_reset/pico_bootsel_via_double_reset.c +++ b/src/rp2_common/pico_bootsel_via_double_reset/pico_bootsel_via_double_reset.c @@ -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 diff --git a/src/rp2_common/pico_multicore/multicore.c b/src/rp2_common/pico_multicore/multicore.c index 0033bcf..53be1ee 100644 --- a/src/rp2_common/pico_multicore/multicore.c +++ b/src/rp2_common/pico_multicore/multicore.c @@ -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); diff --git a/src/rp2_common/pico_platform/include/pico/platform.h b/src/rp2_common/pico_platform/include/pico/platform.h index 7da3103..e17dbca 100644 --- a/src/rp2_common/pico_platform/include/pico/platform.h +++ b/src/rp2_common/pico_platform/include/pico/platform.h @@ -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) {}