AnasSarkiz/usb-c-pd-brushed-motor

docs/STM32-ADC.md

# STM32 raw ADC acquisition — A20

The real STM32G030 ADC1 register backend now acquires VBUS on PA0/channel0, VM on PA1/channel1 and VREFINT on channel13. This completes a raw peripheral layer only. It does not convert counts to qualified rail voltages, grant motor permission, or constitute flashable firmware.

## Source and configuration

The device/CMSIS definitions remain byte-exact vendor files under firmware/vendor, verified by configured tests. Unchanged ST LL ADC/RCC reference headers and Git-blob/SHA-256 provenance are archived in evidence/stm32-ll-{adc,rcc}-reference-A20.{h,json}; they are evidence, not modified vendor definitions or compiled dependencies. Sources: [ST ADC driver](https://github.com/STMicroelectronics/stm32g0xx-hal-driver/blob/master/Inc/stm32g0xx_ll_adc.h), [ST RCC driver](https://github.com/STMicroelectronics/stm32g0xx-hal-driver/blob/master/Inc/stm32g0xx_ll_rcc.h), [STM32G030 datasheet DS12991](https://www.st.com/resource/en/datasheet/stm32g030f6.pdf).

ADC uses the undivided HSI16 kernel (RCC ADCSEL=HSI; the SYSCLK HSI divider is preserved), asynchronous ADC prescaler DIV2, nominal8 MHz,12-bit right-aligned single software conversions, fixed sequencer, no DMA, auto-off, continuous mode, oversampling, external trigger or ADC interrupts. SMPR common sampling1=160.5 cycles (~20.06 us nominal), sampling2 selectors remain zero. This is longer than the documented4 us VREFINT sampling minimum; actual divider/filter settling, clock tolerance and switching noise still require characterization. The published characterized ADC total-error figure is at35 MHz; no unconditional8 MHz accuracy guarantee is inferred from it.

Initialization commands HOST_ALLOW low and open-drain bridge inhibition through the A18 GPIO port before ADC operations. PA0/PA1 must already be analog/no-pull with the PA1 analog clamp disabled. Old PD/measurement provenance must be invalidated and access serialized by the future firmware owner. An enabled, calibrating, stopping or converting ADC is rejected rather than reconfigured live. The fault latch cannot be cleared by another initialization call.

All owned configuration is read back before calibration, including disabling DMA/auto-off. The ADC regulator waits at least20 us; calibration must self-clear ADCAL and assert EOCAL; a further1 us exceeds the LL two-ADC-clock requirement; ADEN must generate fresh ADRDY. An additional12 us reference delay after ready conservatively meets reference-buffer startup. Factory VREFINT calibration word at0x1FFF75AA must be1..4095 and remain unchanged. It is returned raw, without treating3.0 V calibration supply, temperature or reference drift as exact.

## Acquisition and failure behavior

Each channel clears old conversion/channel flags through real W1C writes, writes exactly one channel, waits for fresh CCRDY, commands ADSTART without replaying other read/set command bits, requires EOC and EOS, verifies idle/enabled/configuration, reads a12-bit count and clears flags again. Existing or new OVR rejects the entire frame. Zero VREFINT, out-of-range data, lost configuration, missing flags or expired time return an all-zero invalid result and command motor inhibition. No partial frame or cached rail value is returned.

Frames include operation start/completion timestamps and completion time for each channel. Both rail counts may legitimately be zero, including VM during discharge. The three measurements are sequential, not simultaneous; their skew and the approximately0.91 ms external filter lag must be handled by qualification. A500 us whole-frame deadline and1 ms whole-initialization deadline are proposed conservative software limits, not measured target timing. Every wait has an independent4096-poll cap, including delays, so a stalled time callback cannot hang. Unsigned elapsed time accepts one uint32 microsecond rollover; backwards or excessively late progress faults. Caller supplies an independently proven monotonic clock and must control cadence/freshness. There is no CPU-delay fallback.

The target factory supplies actual ADC1/ADC1_COMMON addresses and direct MMIO writes. Register-model callbacks only emulate documented W1C and read/set/self-clearing properties for tests. These models are not hardware measurements. GPIO inhibition cannot guarantee an electrically damaged transistor, rail or CPU behaves as commanded; power-loss/watchdog/physical protection remains essential.

## Verification and remaining work

Host tests exercise all4096 rail counts, full-scale/zero rails, sequential fresh frames, lost MMIO writes, configuration corruption before/during acquisition, HSI/calibration/ADRDY/CCRDY/conversion timeouts, missing calibration/EOS flags, overrun, invalid/zero-reference data, stalled/backwards/jumping clocks, both startup and capture rollover, bad factory words and latched inhibition. Lost-write testing exposed the missing pre-calibration readback; production was corrected. A separate rollover fixture artificially moved time backwards after initialization; it was corrected to cross rollover naturally. All failed logs are retained.

Strict host compilation and the configured test suite pass; the ADC plus all existing production modules also compile as freestanding Cortex-M0+ objects with ARM GCC. No linked image, startup/vector table, proven timer, I2C peripheral, watchdog or event owner exists yet. A19 uncertainty intervals, VREFINT supply calibration, temperature/noise/filter qualification and PD-state integration remain required. Neither product placement nor routing is enabled by this software step.

A21 policy consumes whole physical voltage intervals; this raw driver cannot set their qualified validity flag directly. See PD-VOLTAGE-INTERVALS.md.