kywwilson11 opened a new pull request, #16904:
URL: https://github.com/apache/nuttx/pull/16904
## Summary
This series improves the **STM32H5 ADC** driver by adding practical **Analog
Watchdog (AWD1/2/3)** support and a small event-delivery path so user space can
react to window violations without busy polling.
Key pieces:
- **AWD configuration ioctls (H5-specific)** to configure thresholds,
per-watchdog channel selection/masks, and optional signaling to a user task.
- **Lightweight watchdog event queue** in the driver (simple ring).
**Coalesced POSIX signal** is delivered from HP workqueue to avoid doing heavy
work in ISR context.
- **Helpers for safe reconfiguration:**
- `adc_stopifstarted()` / `adc_startifstopped()` — pause conversions,
apply AWD config, then resume.
- `adc_reset_dma()` — reinitialize DMA when a full stop/restart is
required (e.g., to realign circular DMA with the scan sequence after a pause).
- **Driver comments/cleanups** for the new helpers and watchdog paths.
Rationale:
I evaluated several other watchdog implementations and found them
unsatisfactory. The wdog lower and upper ioctls were kept and remain relatively
unchanged. Below are the main changes and rationale.
I did not like what was done previously in the adc_interrupt functions for
the analog watchdog. The function did the following for AWD1 - Read DR register
and then disable ADC conversions. This is not desirable. What if the
application wants conversions to continue? How does the application know the
watchdog occurred? Also, what was in the DR at the time of the interrupt (in my
experience) does not match the value that caused the interrupt. So reading DR
was pointless.
Instead of this, I just disable the interrupt to prevent constant interrupts
and a stuck MCU, then I schedule a signal for the watchdog and push a watchdog
event into a watchdog event queue. This provides a mechanism to handle the
watchdog event from the applications. If the application wants to re-enable the
watchdog, it will use the provided watchdog configure ioctl.
## Impact
- **API surface:** Adds STM32H5-specific ioctls for AWD config and
(optionally) signal routing. Existing applications are unaffected unless they
opt in.
- **Runtime behavior:**
- Watchdog events are recorded in a queue regardless of whether signaling
is enabled; signaling is opt-in and maskable per-watchdog.
- Reconfiguring watchdogs while conversions are running is supported
**only if** the application understands the DMA/sequence alignment
implications. The helpers are provided for an explicit stop→configure→(optional
DMA reset)→start path when deterministic alignment is required.
- Related Change - interrupts are now enabled for DMA mode. But EOC
interrupts are not enabled for DMA.
- **No default behavior changes** for boards/configs that don’t use the new
ioctls.
## Testing
Created an external app (attached below). The app sets up a watchdog, sets
up a signal for our watchdog, uses sigtimedwait to wait for the signal, then
gets watchdog events if signaled through GET_EVENT ioctl. Repeat until 20
events found.
[adc_wdg_q.zip](https://github.com/user-attachments/files/21974499/adc_wdg_q.zip)
- **Build/Host:** Linux x86_64; arm-none-eabi toolchain.
- **Targets:** STM32H5 family boards (ADC enabled; configs with/without DMA).
Scenarios exercised:
1. **Non-DMA (interrupt/polling):**
- Configure AWD1/2/3 thresholds and channels.
- Violate window(s) and verify events recorded; optional signal received
once per coalesced burst.
2. **DMA one-shot:**
- Trigger conversions; verify watchdog events and that re-arming from
user space works as expected.
3. **DMA circular + continuous:**
- Start free-running scan; violate window(s); verify events.
- Demonstrate that *mid-run* AWD reconfiguration can desynchronize
channel/value alignment unless conversions (and DMA) are stopped and restarted
together.
- Use `adc_stopifstarted()` + `adc_reset_dma()` + restart to realign;
confirm correct labeling after restart.
Artifacts:
- NSH logs from the sample watchdog app (`adc_wdg_q`) showing AWD events and
channel snapshots.
```
NuttShell (NSH) NuttX-12.10.0
nsh> adc_wdg_q
Usage:
adc_wdg_q <dev> 1 <chan|-1=all> <low12> <high12> [filter]
adc_wdg_q <dev> 2 <mask> <low8> <high8>
adc_wdg_q <dev> 3 <mask> <low8> <high8>
nsh> adc_wdg_q /dev/adc0 1 10 2048 4095
[1] [AWD1] isr=0x0000008a
-> ch10 snapshot: 0 (0x000)
[2] [AWD1] isr=0x0000008a
-> ch10 snapshot: 4 (0x004)
[3] [AWD1] isr=0x0000008a
-> ch10 snapshot: 0 (0x000)
[4] [AWD1] isr=0x0000008a
-> ch10 snapshot: 4 (0x004)
[5] [AWD1] isr=0x0000008a
-> ch10 snapshot: 0 (0x000)
[6] [AWD1] isr=0x0000008a
-> ch10 snapshot: 476 (0x1dc)
[7] [AWD1] isr=0x0000008a
-> ch10 snapshot: 503 (0x1f7)
nsh> adc_wdg_q /dev/adc0 2 10 128 255
[1] [AWD2] isr=0x00000102
-> ch1 snapshot: n/a
-> ch3 snapshot: 47 (0x02f)
[2] [AWD2] isr=0x0000010a
-> ch1 snapshot: n/a
-> ch3 snapshot: 49 (0x031)
[3] [AWD2] isr=0x0000010a
-> ch1 snapshot: n/a
-> ch3 snapshot: 54 (0x036)
[4] [AWD2] isr=0x0000010a
-> ch1 snapshot: n/a
-> ch3 snapshot: 50 (0x032)
[5] [AWD2] isr=0x0000010a
-> ch1 snapshot: n/a
-> ch3 snapshot: 57 (0x039)
nsh> adc_wdg_q /dev/adc0 3 10 0 128
[1] [AWD3] isr=0x0000020a
-> ch1 snapshot: n/a
-> ch3 snapshot: 3514 (0xdba)
[2] [AWD3] isr=0x0000020a
-> ch1 snapshot: n/a
-> ch3 snapshot: 3509 (0xdb5)
[3] [AWD3] isr=0x0000020a
-> ch1 snapshot: n/a
-> ch3 snapshot: 3519 (0xdbf)
[4] [AWD3] isr=0x0000020a
-> ch1 snapshot: n/a
-> ch3 snapshot: 3513 (0xdb9)
[5] [AWD3] isr=0x0000020a
-> ch1 snapshot: n/a
-> ch3 snapshot: 3519 (0xdbf)
[6] [AWD3] isr=0x0000020a
-> ch1 snapshot: n/a
-> ch3 snapshot: 3522 (0xdc2)
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscr...@nuttx.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
