docs: iio-adc: add ADEMA127 driver documentation

[mhennerich]

Driver documentation for the ADEMA124/ADEMA127 poly-phase energy
metering ADC driver submitted in #3481: supported devices, device tree
wiring for both capture paths (per-DREADY software triggered buffer and
hardware-triggered SPI Offload streaming on SC846), the offload scan
layout (le:s24/32>>8 native long frames + trailer channel), watermark /
interrupt-rate behavior, and the DSP-RAM-backed calibration attributes.

Split out of #3481 per review guidance: driver documentation lives on
the ci branch's docs/ tree (picked up by the glob toctree under
docs/drivers/, same layout as the neighbouring iio-adc driver docs).

[github-actions]

LLM review

This series adds Sphinx documentation for the (not-yet-mainlined) ADEMA124/ADEMA127 IIO ADC driver.

run: 31366287533

008dedd9df914 - docs: iio-adc: add ADEMA127 driver documentation

Cross-checked the new docs/drivers/iio-adc/adema127.rst against the ADEMA124/ADEMA127 datasheet.
Most content (SPI framing, CRC-8/CRC-CCITT parameters, PRODUCT_ID values, scale factor, sampling-rate
table, most register addresses) is accurate. Four factual errors were found:

• DC-block alpha register mapping is wrong. The doc says DATAPATH_ALPHA_CHx at 0x03D + N (one
  register per channel). The datasheet packs two channels per byte as nibbles:
  DATAPATH_ALPHA_CH0_1 (0x03D), CH2_3 (0x03E), CH4_5 (0x03F), CH6 (0x040).
• in_voltageN_phase signedness/range is wrong. Doc claims signed 13-bit, range -4096..4095. The
  datasheet defines PHASE_OFFSET as unsigned, 0x0000..0x1FFF (0..8191), a fraction of one sample
  period — no two's-complement encoding.
• Crosstalk direction is inverted. Doc says the aggressor contribution is "decremented". The
  datasheet says the hardware adds xt_gain * channel[xt_aggressor]; subtraction requires a negative
  xt_gain.
• Wrong settle-time value/citation. Doc says "50 µs... matching Table 5 of the datasheet". Table 5
  is "Absolute Maximum Ratings" (unrelated). The datasheet's Configuration Procedure section documents
  "approximately 40 µs".

CI warnings

None — /tmp/tmp.CFbVosXBzg.txt (CI notes) and the PR discussion export were both empty for this range.
The Sphinx doc build (docs/, replicating .github/workflows/doc.yml) was run locally with
make html SPHINXOPTS='-jauto -W --keep-going' and succeeds with zero warnings both before and after
the suggested fix.

Verification data

Datasheet adema124-127.pdf was located via the ADI PDF sitemap and fetched pre-converted as
media/en/technical-documentation/data-sheets/adema124-127.md from the doctools docling mirror. It was
used to check register addresses/bitfields (PRODUCT_ID, ADC_GAIN, ADC_INV, SYNC_SNAP, WR_LOCK,
DATAPATH_CONFIG_LOCK, DATAPATH_CONFIG_CHx, PHASE_OFFSET_CHx, DATAPATH_ALPHA_CHx, XT_AGGRESSOR,
XT_GAIN, GAIN, OFFSET), CRC-8/CRC-CCITT parameters, the 4,772,275 codes/V scale factor, SPI timing
(22 MHz max SCLK, mode 3), and the datapath lock/unlock settle time.

Suggested patches

Apply the suggested patches with:

cd path/to/repository
export GITHUB_TOKEN=ghp_***
apply-patches --repo=analogdevicesinc/linux 31366287533

Install instructions

The following one-liner installs the script if not present already:

curl -fSsL "https://raw.githubusercontent.com/analogdevicesinc/doctools/refs/heads/main/ci/scripts/apply-patches.sh"      -o ~/.local/bin/apply-patches.sh &&   grep -q "/apply-patches.sh" ~/.bashrc || echo "source ~/.local/bin/apply-patches.sh" >> $_ ; . $_

More information at AI Usage.

[mhennerich]

force pushed fixes for these new LLM findings in both PRs

[github-actions]

LLM review

This series adds Sphinx documentation for the (not-yet-mainlined) ADEMA124/ADEMA127 IIO ADC driver.

run: 31381302029

41595343e20a - docs: iio-adc: add ADEMA127 driver documentation

This is an amended version of the previously-reviewed commit (008dedd9df914). All four
factual errors raised in the earlier review round are correctly fixed here:

• DATAPATH_ALPHA_CHx nibble-packed mapping (0x03D + N/2, even channel in [3:0], odd in [7:4]).
• in_voltageN_phase is now documented as unsigned, range 0..8191 (PHASE_OFFSET_CHx, 13
  fractional bits, max 0x1FFF).
• Crosstalk direction: doc now says the aggressor contribution is added, with a negative
  xt_gain used to subtract it — matches the datasheet.
• Settle-time citation now correctly points at the Configuration Procedure section
  ("approximately 40 µs") instead of Table 5.

New ordering bug found: in_voltageN_calibbias still states "The offset is subtracted from
the sample before scaling." The datasheet's Gain, Offset, and Crosstalk Compensation section
explicitly states the opposite: "gain compensation is applied before offset compensation." A
fixup patch is included below.

CI warnings

None. The Sphinx doc build (docs/, replicating .github/workflows/doc.yml) was run locally
with make html SPHINXOPTS='-jauto -W --keep-going' and succeeds with zero warnings, both before
and after the suggested fix. The page has no explicit toctree entry but is picked up
automatically by the :glob: toctree in docs/drivers/index.rst.

Verification data

Datasheet adema124-127.pdf was located via the ADI PDF sitemap and fetched pre-converted as
media/en/technical-documentation/data-sheets/adema124-127.md from the doctools docling mirror.
It was used to re-verify the four previously-reported fixes and to check register
addresses/bitfields (PRODUCT_ID, ADC_GAIN, ADC_INV, SYNC_SNAP, WR_LOCK,
DATAPATH_CONFIG_LOCK, DATAPATH_CONFIG_CHx, PHASE_OFFSET_CHx, DATAPATH_ALPHA_CHx,
XT_AGGRESSOR, XT_GAIN, GAIN, OFFSET, SWRST, DATARATE, STREAM_DBG), CRC-8/CRC-CCITT
parameters, the 4,772,275 codes/V scale factor, SPI timing (22 MHz max SCLK, mode 3), short/long
frame sizes, and the gain-before-offset application order.

Suggested patches

Apply the suggested patches with:

cd path/to/repository
export GITHUB_TOKEN=ghp_***
apply-patches --repo=analogdevicesinc/linux 31381302029

Install instructions

The following one-liner installs the script if not present already:

curl -fSsL "https://raw.githubusercontent.com/analogdevicesinc/doctools/refs/heads/main/ci/scripts/apply-patches.sh"      -o ~/.local/bin/apply-patches.sh &&   grep -q "/apply-patches.sh" ~/.bashrc || echo "source ~/.local/bin/apply-patches.sh" >> $_ ; . $_

More information at AI Usage.