drivers/periph/timer: document timer_init re-initialization precondition

[andrewlihhh]

Contribution description

This PR documents the usage model of timer_init() for the same timer device.

The discussion in #22384 pointed out that the periph_timer API did not clearly
state whether calling timer_init() again on an already active timer is
supported.

This PR clarifies that callers must not call timer_init() again on the same
timer while it is active. A timer must either not have been initialized before,
or it must be stopped with timer_stop() before calling timer_init() again.

The change is documentation-only. It does not change any timer implementation.

Testing procedure

Documentation-only change.

To review:

1. Check the new @pre entry in drivers/include/periph/timer.h.
2. Check the updated periph_timer entry in
   drivers/include/periph/doc.txt.
3. Verify that no driver implementation is changed.

Issues/PRs references

Refs #22384

Declaration of AI-Tools / LLMs usage:

AI-Tools / LLMs that were used are:

• OpenAI Codex for drafting the documentation wording and pull request text, with user review

[github-actions]

Hey @andrewlihhh, thank you for your first contribution! We really appreciate it! If you haven't already, please take a look at our contributing guidelines before the review process starts. Also, due to how the GitHub review system works, please avoid force-pushing or squashing your commits unless asked to by a maintainer (or unless your commit is still in "draft commit" stage). Lastly, make sure to comply with our AI Policy when using AI. Your pull request will be reviewed as soon as possible.

[riot-ci]

Murdock results

✔️ PASSED

3de6585 Update drivers/include/periph/timer.h

Success	Failures	Total	Runtime
11124	0	11124	15m:17s

Artifacts

• Documentation preview

[crasbe]

Thank you for the Pull Request. Can you provide some testing traces of the board before and after your PR to show the changes?

Also, you don't have to open a separate issue if you intend to open a PR too, that's redundant.

[andrewlihhh]

I do not have the original lpc23xx/mcb2388 board locally, so I prepared a small supplemental QEMU + RIOT reproduction on a RIOT-supported Cortex-M target (microbit / nrf51) to show the before/after timing difference.

This is not meant as exact board-level validation for lpc23xx. I am only using it as supplemental evidence that the change affects when a pending timer IRQ can observe the callback context during re-initialization.

What changes is the delivery point of the same pending IRQ relative to the re-init window.

Before, the pending IRQ can be handled during the re-init window:

[drv] timer_init before NVIC_EnableIRQ phase=1
[drv] inject pending compare0 IRQ phase=1
[drv] irq_handler enter num=0 phase=1 flags=0x01 evt0=0 inten=0x00010000
[drv] timer_init after NVIC_EnableIRQ phase=1
[app] CB_NEW phase=1 chan=0 hits_old=0 hits_new=1 cc0=32 evt0=0

After, the same pending IRQ is deferred until the end of the interrupt-masked region:

[drv] timer_init before NVIC_EnableIRQ phase=1
[drv] inject pending compare0 IRQ phase=1
[drv] timer_init after NVIC_EnableIRQ phase=1
[drv] timer_init after TASKS_START phase=1
[drv] irq_handler enter num=0 phase=1 flags=0x01 evt0=1 inten=0x00010000
[app] CB_NEW phase=1 chan=0 hits_old=0 hits_new=1 cc0=32 evt0=0
[drv] timer_init after irq_restore phase=1

So while this is not a direct lpc23xx hardware trace, it does show the intended effect of the change: without protection, a pending IRQ may run inside the callback-context update / re-enable window; with the protected version, delivery is pushed to the end of that region.

[andrewlihhh]

I reworked this PR into a documentation-only change as suggested. It now documents the timer_init() re-initialization precondition instead of changing the lpc23xx driver implementation.

[crasbe]

Thank you for addressing the changes! Please squash!