enum gpio_override missing in SDK documentation

[magy00]

Was mentioned in #265 (comment) but still (or again) an issue.

For example, the links to gpio_override in gpio_set_inover() and gpio_set_outover() are not working but GPIO_OVERRIDE_INVERT can be found in the source code. PDF version affected as well. Maybe others also (like struct alarm_pool in 4.2.11.5.1. Detailed Description of 4.2.11.5. alarm).

\see and \sa seem to start a new paragraph, so don't work so well in some places (look for See also in PDF):

4.1.28.7.34. timer_time_us_64
4.1.15.10.6. pio_claim_free_sm_and_add_program_for_gpio_range
4.1.15.11.3. Function Documentation: sm_config_set_mov_status

Some See also entries in the following entries are not linked:

4.1.7.10.10. dma_channel_is_claimed
4.1.15.10.5. pio_claim_free_sm_and_add_program
4.1.15.10.6. pio_claim_free_sm_and_add_program_for_gpio_range
4.1.15.10.13. pio_get_funcsel
4.1.26.5.13. next_striped_spin_lock_num
4.1.28.7.7. hardware_alarm_claim_unused
4.1.28.7.21. timer_get_index
4.1.28.7.24. timer_hardware_alarm_claim
4.1.28.7.25. timer_hardware_alarm_claim_unused
4.1.28.7.31. timer_hardware_alarm_unclaim
4.2.2.5.1. async_at_time_worker_t
4.2.2.5.2. async_when_pending_worker_t
4.2.6.8.4. Function Documentation: multicore_doorbell_claim
…

Maybe you create some scripts to do some consistency checking (or run some AI tool to do it; also for constants and their short versions and their correspondence between hardware registers and SDK).

[lurch]

From a very quick look, there's several different issues here... I'll try to set aside some time later in the week (if I get some spare time) to do an in-depth investigation.

Maybe you create some scripts to do some consistency checking

Yup, I've previously partially done that with e.g. https://github.com/raspberrypi/pico-sdk/blob/develop/tools/check_doxygen_groups.py
(which is why I'm assigning this issue to myself).

also for constants and their short versions and their correspondence between hardware registers and SDK

Could you explain in more detail what you mean here please?

[magy00]

I guess this applies more to the RP2350 datasheet but the PIOASM chapter is shared with the SDK. For example, under 3.4.4. JMP → 3.4.4.2. Operation, there is EXECCTRL_JMP_PIN mentioned but it doesn't point to anywhere (should at least be a link) and searching for it in the SDK docs as well as in the RP2350 datasheet yields only 1 result each.

In the datasheet, bits in the registers sometimes have different names than the corresponding constants for the SDK API. It would be nice if they would somehow be cross-referenced (maybe through some kind of glossary or a keyword index, etc.) because the description of one might be different than the other.

An initial simple check could be to just count all all-caps words with at least an underscore. Words that are only once mentioned (or twice and not somehow linked) would probably be suspect. Words that are a sub-string of another (or otherwise similar) possibly also. Then maybe a similar check for function names (identifier followed by (), etc.

And basically the individual words count of the source and the produced HTML and PDF docs should be about the same (minus markup, etc.) if nothing is lost.

However, I suspect that nowadays some of the AI-based tools (like Grok 3 and others that accept larger files) could be instructed to search for inconsistencies in a (PDF) text…

[lurch]

In the datasheet, bits in the registers sometimes have different names than the corresponding constants for the SDK API.

Could you point to some specific examples please? We have internal tooling which means that the register-tables in the SDK PDF and the actual pico-sdk header files are generated from the same "source data". For example, compare section 12.5.3. of https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf with https://github.com/raspberrypi/pico-sdk/blob/master/src/rp2350/hardware_regs/include/hardware/regs/pwm.h (as well as https://github.com/raspberrypi/pico-sdk/blob/master/src/rp2350/hardware_structs/include/hardware/structs/pwm.h which is also auto-generated).
So if that process is going wrong somewhere, it'd be great to know!

[lurch]

there is EXECCTRL_JMP_PIN mentioned but it doesn't point to anywhere (should at least be a link) and searching for it in the SDK docs as well as in the RP2350 datasheet yields only 1 result each.

Yeah, there's a (fairly old) separate issue for that: #242

[magy00]

It looks like I mixed up the repositories, and that part is a duplicate of raspberrypi/pico-feedback#437. #2129 is possibly also related.

[lurch]

As I hinted at earlier, there's a range of different issues here (thanks for your comprehensive list), so I'll go through them one at a time...

For example, the links to gpio_override in gpio_set_inover() and gpio_set_outover() are not working but GPIO_OVERRIDE_INVERT can be found in the source code. PDF version affected as well.

This is because enum gpio_overrride is missing a doxygen-comment, and thus it doesn't appear at https://www.raspberrypi.com/documentation/pico-sdk/hardware.html#enumerations-4 . By contrast enum gpio_slew_rate does have a doxygen-comment, and thus it does appear in the list of hardware_gpio Enumerations.

Maybe others also (like struct alarm_pool in 4.2.11.5.1. Detailed Description of 4.2.11.5. alarm).

alarm_pool is a 'struct', and there are a lot of those in pico-sdk, and we've not yet added support for structs to https://github.com/raspberrypi/doxygentoasciidoc
You may be interested to learn that our doxygentoasciidoc repo is used both to create the API documentation in chapter 4 of the Pico SDK PDF and also the online SDK API documentation, so it's highly likely that any errors in one will also be present in the other. For example you can see the non-functional struct alarm_pool link here.

4.1.28.7.34. timer_time_us_64

Unfortunately this is a weird Doxygen bug (which we've seen previously). For an unknown reason it sometimes randomly repeats a sentence in an unexpected place! For example if you look at hardware/timer.h you can see that the string "Busy wait wasting cycles for the given (32 bit) number of microseconds using the given timer instance" only appears once, and the string "Busy wait wasting cycles for the given (64 bit) number of microseconds using the given timer instance" also only appears once. However if you search in the pico-sdk PDF (or at https://www.raspberrypi.com/documentation/pico-sdk/hardware.html#group_hardware_timer ), the string "Busy wait wasting cycles for the given (64 bit) number of microseconds using the given timer instance" (correctly) only appears twice, but the string "Busy wait wasting cycles for the given (32 bit) number of microseconds using the given timer instance" unexpectedly appears 3 times! We've not reported this to the upstream Doxygen project because it's a very low priority, and it happens so rarely that we've not been able to create a standalone testcase.

\see and \sa seem to start a new paragraph, so don't work so well in some places (look for See also in PDF):
pio_claim_free_sm_and_add_program_for_gpio_range

Yeah, that's unfortunate - also visible in the online version https://www.raspberrypi.com/documentation/pico-sdk/hardware.html#group_hardware_pio_1ga53c3bbe939b3c58585d0e19ffe91e18e
I guess we need to modify our doxygen-comments to only use \see and \sa at the end of the comment, rather than interspersed with the text 🤦

4.1.15.11.3. Function Documentation: sm_config_set_mov_status

I can't see any problem here??

4.1.7.10.10. dma_channel_is_claimed

Yeah, looks like it isn't linking to dma_channel_claim_mask, because it actually should have been linking to dma_claim_mask instead.

4.1.15.10.5. pio_claim_free_sm_and_add_program

Looks like it isn't linking to pio_remove_program_unclaim_sm because it should have been linking to pio_remove_program_and_unclaim_sm.

4.1.15.10.6. pio_claim_free_sm_and_add_program_for_gpio_range

Again, should have been linking to pio_remove_program_and_unclaim_sm instead of pio_remove_program_unclaim_sm.

4.1.15.10.13. pio_get_funcsel

Looks like it should have been linking to gpio_function_t instead of gpio_function.

4.1.26.5.13. next_striped_spin_lock_num

It's trying to link to PICO_SPINLOCK_ID_STRIPED_FIRST and PICO_SPINLOCK_ID_STRIPED_LAST but these are just defines in hardware/sync/spin_lock.h without any doxygen comments.

4.1.28.7.7. hardware_alarm_claim_unused
4.1.28.7.24. timer_hardware_alarm_claim
4.1.28.7.25. timer_hardware_alarm_claim_unused
4.1.28.7.31. timer_hardware_alarm_unclaim

There are actually 11 places which do \sa hardware_claiming, all of which are non-functional. My best guess is that they were supposed to be \sa hardware_claim.

4.1.28.7.21. timer_get_index

This one took a bit of head-scratching - it's trying to link to TIMER_NUM which does have doxygen-comments, but it's not appearing here, even though the similar-looking TIMER_ALARM_IRQ_NUM macro does appear in the output. I think what's happening is that the C preprocessor is being run with no values defined before Doxygen parses the source, and so:

#if NUM_GENERIC_TIMERS == 1
#define TIMER_NUM(timer) ({ (void) (timer); 0; })
#elif NUM_GENERIC_TIMERS == 2
#define TIMER_NUM(timer) ((timer) == timer1_hw)
#endif

gets reduced to nothing, and so doxygen doesn't believe that the macro exists.
Whereas:

#if NUM_GENERIC_TIMERS == 1
static_assert(TIMER_IRQ_3 == TIMER_IRQ_0 + 3, "");
#define TIMER_ALARM_IRQ_NUM(timer, alarm_num) ({ ((void)(timer)); (TIMER_IRQ_0 + (alarm_num)); })
#else
static_assert(TIMER1_IRQ_3 == TIMER0_IRQ_0 + 7, "");
#define TIMER_ALARM_IRQ_NUM(timer, alarm_num) (TIMER0_IRQ_0 + TIMER_NUM(timer) * NUM_ALARMS + (alarm_num))
#endif

gets reduced to:

static_assert(TIMER1_IRQ_3 == TIMER0_IRQ_0 + 7, "");
#define TIMER_ALARM_IRQ_NUM(timer, alarm_num) (TIMER0_IRQ_0 + TIMER_NUM(timer) * NUM_ALARMS + (alarm_num))

and so doxygen does see the TIMER_ALARM_IRQ_NUM macro.

Feel free to read Appendix B of https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf and then have a fiddle around with https://github.com/raspberrypi/pico-sdk/blob/develop/docs/Doxyfile.in and https://www.doxygen.nl/manual/preprocessing.html to see if you can get any better results, but that's not something that I have time for myself!

4.2.2.5.1. async_at_time_worker_t
4.2.2.5.2. async_when_pending_worker_t

Both are trying to link to async_context_add_worker_at and async_context_add_worker_in_ms which should probably have been async_context_add_at_time_worker_at and async_context_add_at_time_worker_in_ms.

BTW, it's possible that some of these errors were already being reported by doxygen, but the pico-sdk codebase is very extensive, and the doxygen output is so verbose, that nobody ever bothers checking it! 🤣

[magy00]

4.1.15.11.3. Function Documentation: sm_config_set_mov_status

I can't see any problem here??

Maybe it's fixed now, but in the 20 February 2025 PDF (bottom of page 239), the See also header breaks the Parameters header into 2 headers: first listing c and status_sel, and then a lone status_n with its own (repeated) header.

[lurch]

the See also header breaks the Parameters header into 2 headers

Oh yes! I hadn't spotted that 🤦

Yeah, the good news is that this was caught in #2390 by my review of the all the \see tags that don't occur at the start of a line 😅