iio: adc: ad4000: Add SPI offload support

FPGA HDL projects can include a PWM generator in addition to SPI-Engine. The PWM IP is used to trigger SPI-Engine offload modules that in turn set SPI-Engine to execute transfers to poll data from the ADC. That allows data to be read at the maximum sample rates. Also, it is possible to set a specific sample rate by setting the proper PWM duty cycle and related state parameters, thus allowing an adjustable ADC sample rate when a PWM (offload trigger) is used in combination with SPI-Engine.

Add support for SPI offload.

Signed-off-by Marcelo Schmitt <[email protected]>

drivers/iio/adc/ad4000.c +3 -0

+	return 0;
+}
 
 
+

+ * bits_per_word to ensure the minimum of SCLK cycles are used. And a delay is
+ * added to make sure we meet the minimum quiet time before releasing the CS
+ * line. Plus the CS change delay is set to ensure that we meet the minimum
+ * quiet time before asserting CS again.
+ *
+ * This timing is only valid if turbo mode is enabled (reading during conversion).
+ */

drivers/iio/adc/ad4000.c +4 -0

+static int ad4000_prepare_offload_turbo_message(struct ad4000_state *st,
+						const struct iio_chan_spec *chan)
+{
+

+ * bits_per_word to ensure the minimum of SCLK cycles are used. And a delay is
+ * added to make sure we meet the minimum quiet time before releasing the CS
+ * line. Plus the CS change delay is set to ensure that we meet the minimum
+ * conversion time before asserting CS again.
+ *
+ * This timing is only valid if turbo mode is disabled (reading during acquisition).
+ */

drivers/iio/adc/ad4000.c +3 -0

+static int ad4000_prepare_offload_message(struct ad4000_state *st,
+					  const struct iio_chan_spec *chan)
+

drivers/iio/adc/ad4000.c +1 -0

+		xfers[1].bits_per_word = chan->scan_type.realbits;

@@ -733,6 +1023,9 @@ static int ad4000_config(struct ad4000_state *st)
 	if (device_property_present(&st->spi->dev, "adi,high-z-input"))
 		reg_val |= FIELD_PREP(AD4000_CFG_HIGHZ, 1);
 

drivers/iio/adc/ad4000.c +8 -1

+		}
+
+		/*
+		 * Call ad4000_prepare_3wire_mode_message() so single-shot read
+		 * SPI messages are always initialized.
+		 */
 		ret = ad4000_prepare_3wire_mode_message(st, &indio_dev->channels[0]);
 		if (ret)
-			return ret;
+			return dev_err_probe(dev, ret,
+					     "Failed to optimize SPI msg\n");
 
 		ret = ad4000_config(st);
 		if (ret < 0)

drivers/iio/adc/ad4000.c +1 -6

 	ret = devm_mutex_init(dev, &st->lock);
 	if (ret)

@@ -853,12 +1201,6 @@ static int ad4000_probe(struct spi_device *spi)
 
 	ad4000_fill_scale_tbl(st, &indio_dev->channels[0]);
 
-	ret = devm_iio_triggered_buffer_setup(dev, indio_dev,
-					      &iio_pollfunc_store_time,
-					      &ad4000_trigger_handler, NULL);
-	if (ret)
-		return ret;
-
 	return devm_iio_device_register(dev, indio_dev);
 }
 

@@ -947,3 +1289,4 @@ module_spi_driver(ad4000_driver);
 MODULE_AUTHOR("Marcelo Schmitt <[email protected]>");
 MODULE_DESCRIPTION("Analog Devices AD4000 ADC driver");
 MODULE_LICENSE("GPL");
+MODULE_IMPORT_NS("IIO_DMAENGINE_BUFFER");

Quoted 4 lines

drivers/iio/adc/ad4000.c +0 -0

index 4fe8dee48da9..6c9b71e7a2fb 100644

drivers/iio/adc/ad4000.c static const struct iio_info ad4000_reg_access_info = { · line 837

Quoted 6 lines

drivers/iio/adc/ad4000.c +6 -0

+
+static int ad4000_offload_buffer_postdisable(struct iio_dev *indio_dev)
+{
+	struct ad4000_state *st = iio_priv(indio_dev);
+
+	spi_offload_trigger_disable(st->offload, st->offload_trigger);

Trivial. Prefer a blank line before a 'simple return' like this one.

Quoted 2 lines

drivers/iio/adc/ad4000.c +2 -0

+	return 0;
+}

Quoted 10 lines

+/*
+ * This executes a data sample transfer when using SPI offloading for when the
+ * device connections are in "3-wire" mode, selected when the adi,sdi-pin device
+ * tree property is set to "high". In this connection mode, the ADC SDI pin is
+ * connected to VIO and ADC CNV pin is connected to a SPI controller CS (it
+ * can't be connected to a GPIO).
+ *
+ * In order to achieve the maximum sample rate, we only do one transfer per
+ * SPI offload trigger. This has the effect that the first sample data is not
+ * valid because it is reading the previous conversion result. We also use

Say what happens to that invalid sample. Is it dropped or provided to userspace as if it were valid? (I hope dropped!)

Quoted 11 lines

+ * bits_per_word to ensure the minimum of SCLK cycles are used. And a delay is
+ * added to make sure we meet the minimum quiet time before releasing the CS
+ * line. Plus the CS change delay is set to ensure that we meet the minimum
+ * conversion time before asserting CS again.
+ *
+ * This timing is only valid if turbo mode is disabled (reading during acquisition).
+ */

drivers/iio/adc/ad4000.c +3 -0

+static int ad4000_prepare_offload_message(struct ad4000_state *st,
+					  const struct iio_chan_spec *chan)
+

Quoted 7 lines

drivers/iio/adc/ad4000.c +1 -0

+		xfers[1].bits_per_word = chan->scan_type.realbits;
 	xfers[1].delay.value = st->time_spec->t_quiet2_ns;
 	xfers[1].delay.unit = SPI_DELAY_UNIT_NSECS;

@@ -719,7 +1007,9 @@ static int ad4000_prepare_4wire_mode_message(struct ad4000_state *st,
 	xfers[0].delay.unit = SPI_DELAY_UNIT_NSECS;
 

drivers/iio/adc/ad4000.c static int ad4000_prepare_3wire_mode_message(struct ad4000_state *st, · line 979

Quoted 4 lines

drivers/iio/adc/ad4000.c +2 -1

 	xfers[1].rx_buf = &st->scan.data;
-	xfers[1].len = BITS_TO_BYTES(chan->scan_type.storagebits);
+	xfers[1].len = chan->scan_type.realbits > 16 ? 4 : 2;
+	if (chan->scan_type.endianness != IIO_BE)

This is odd enough to require a comment. Why is endianness relevant?

drivers/iio/adc/ad4000.c static int ad4000_probe(struct spi_device *spi) · line 1113

Quoted 3 lines

drivers/iio/adc/ad4000.c +2 -0

+		if (st->using_offload) {
+			indio_dev->channels = &chip->reg_access_offload_chan_spec;

Set num_channels here

Quoted 1 line

drivers/iio/adc/ad4000.c +1 -0

+			ret = ad4000_prepare_offload_turbo_message(st, indio_dev->channels);

Also set size here. Obviously this means a little duplication but still good to keep them together.

Quoted 8 lines

drivers/iio/adc/ad4000.c +1 -0

+		}
 
 	case AD4000_SDI_GND:

@@ -830,7 +1175,10 @@ static int ad4000_probe(struct spi_device *spi)
 	}
 

drivers/iio/adc/ad4000.c static int ad4000_probe(struct spi_device *spi) · line 1181

Quoted 6 lines

drivers/iio/adc/ad4000.c +4 -1

 	indio_dev->name = chip->dev_name;
-	indio_dev->num_channels = 2;
+	if (st->using_offload)
+		indio_dev->num_channels = 1;
+	else
+		indio_dev->num_channels = 2;

Move this up to where you set channels so that the array and size are set together.

...

Quoted 11 lines

Quoted 10 lines

+/*
+ * This executes a data sample transfer when using SPI offloading for when the
+ * device connections are in "3-wire" mode, selected when the adi,sdi-pin device
+ * tree property is set to "high". In this connection mode, the ADC SDI pin is
+ * connected to VIO and ADC CNV pin is connected to a SPI controller CS (it
+ * can't be connected to a GPIO).
+ *
+ * In order to achieve the maximum sample rate, we only do one transfer per
+ * SPI offload trigger. This has the effect that the first sample data is not
+ * valid because it is reading the previous conversion result. We also use

Quoted 2 lines

Say what happens to that invalid sample. Is it dropped or provided to userspace as if it were valid? (I hope dropped!)

TL;DR: The invalid sample goes into the buffer as a valid one.

In AD4000 '3-wire' mode, data capture has a latency (delay) of one sample.

The ADC begins sampling data N at CNV rising edge

          |   +-- CNV (usually SPI CS) is brought low to begin reading the data
          |   |                                +-- Data N + 1 that will be read
          |   |                                |   on the next transfer starts 
          v   v                                v   being sampled at end of transfer N.

___ ____
CNV _____/ \________________________________/ \_____
_ _ _
SCLK ______________/ \___/ \_ ... ___/ \_______________

                   ___   ___           ___
SDO  _____________/___\_/___\ ...   __/___\_______________
                    ^
                    |
             Data from conversion N is output from here on

A better drawing can be found in datasheet page 29, Figure 57.
https://www.analog.com/media/en/technical-documentation/data-sheets/ADAQ4003.pdf

In sum, we're always reading a conversion that started at the end of the previous SPI transfer or, in other words, the data comes out with a latency (delay) of one read.

Datasheet somehow mentions that by saying
When turbo mode is enabled, the conversion result read on SDO corresponds to the result of the previous conversion.

I think I can do a dummy SPI transfer on buffer preenable so at least the first data is not invalid. Would that be better?

Quoted 13 lines

Quoted 12 lines

+ * bits_per_word to ensure the minimum of SCLK cycles are used. And a delay is
+ * added to make sure we meet the minimum quiet time before releasing the CS
+ * line. Plus the CS change delay is set to ensure that we meet the minimum
+ * conversion time before asserting CS again.
+ *
+ * This timing is only valid if turbo mode is disabled (reading during acquisition).
+ */

drivers/iio/adc/ad4000.c +3 -0

+static int ad4000_prepare_offload_message(struct ad4000_state *st,
+					  const struct iio_chan_spec *chan)
+

...

Quoted 7 lines

Quoted 7 lines

drivers/iio/adc/ad4000.c +1 -0

+		xfers[1].bits_per_word = chan->scan_type.realbits;
 	xfers[1].delay.value = st->time_spec->t_quiet2_ns;
 	xfers[1].delay.unit = SPI_DELAY_UNIT_NSECS;

@@ -719,7 +1007,9 @@ static int ad4000_prepare_4wire_mode_message(struct ad4000_state *st,
 	xfers[0].delay.unit = SPI_DELAY_UNIT_NSECS;
 

Quoted 6 lines

drivers/iio/adc/ad4000.c static int ad4000_prepare_3wire_mode_message(struct ad4000_state *st, · line 979

Quoted 4 lines

drivers/iio/adc/ad4000.c +2 -1

 	xfers[1].rx_buf = &st->scan.data;
-	xfers[1].len = BITS_TO_BYTES(chan->scan_type.storagebits);
+	xfers[1].len = chan->scan_type.realbits > 16 ? 4 : 2;
+	if (chan->scan_type.endianness != IIO_BE)

This is odd enough to require a comment. Why is endianness relevant?

When using SPI offloading (at least with PULSAR-ADC HDL project [1]), ADC data is read by SPI controller and pushed to DMA memory in CPU endianness. I don't know exactly where data gets rearranged in the data path (whether SPI-Engine, the DMA controller, or something else rearranges ADC data into CPU endianess). But I know, from testing with these ADCs and HDL project, that data is correct when read in CPU endianness because it converts back to expected mV values. When IIO buffers were set to IIO_BE and SPI offloading is used, data just looked weird and didn't convert to expected values in mV.

[1]: https://analogdevicesinc.github.io/hdl/projects/pulsar_adc/index.html

Other IIO drivers also set IIO_CPU buffer endianness when using offload support, e.g. ad7944, ad7380.

They only say buffer would use 32 storagebits when using SPI offload.
https://lore.kernel.org/linux-iio/20250207-dlech-mainline-spi-engine-offload-2-v8-10-e48a489be48c@baylibre.com/
https://lore.kernel.org/linux-iio/20250220-wip-bl-spi-offload-ad7380-v1-1-838aa873e62a@baylibre.com/#t

I also didn't expect to find out HDL support for 16-bit data width was removed. We used to have a build parameter for 16-bit precision ADCs.
https://github.com/analogdevicesinc/hdl/commit/b2dc91b30dae891b6319d88e083f26e726f43ba0#diff-1117c2618353232e5f22aa6a12e8ae976757fa897b3425f470a12123cae26535L13

Would something like 'because SPI offloading leads to data being pushed to memory in CPU endianness' be a reasonable comment?

Quoted 41 lines · Marcelo Schmitt

...

Quoted 11 lines

Quoted 10 lines

+/*
+ * This executes a data sample transfer when using SPI offloading for when the
+ * device connections are in "3-wire" mode, selected when the adi,sdi-pin device
+ * tree property is set to "high". In this connection mode, the ADC SDI pin is
+ * connected to VIO and ADC CNV pin is connected to a SPI controller CS (it
+ * can't be connected to a GPIO).
+ *
+ * In order to achieve the maximum sample rate, we only do one transfer per
+ * SPI offload trigger. This has the effect that the first sample data is not
+ * valid because it is reading the previous conversion result. We also use

Quoted 2 lines

Say what happens to that invalid sample. Is it dropped or provided to userspace as if it were valid? (I hope dropped!)

TL;DR: The invalid sample goes into the buffer as a valid one.

In AD4000 '3-wire' mode, data capture has a latency (delay) of one sample.

The ADC begins sampling data N at CNV rising edge

          |   +-- CNV (usually SPI CS) is brought low to begin reading the data
          |   |                                +-- Data N + 1 that will be read
          |   |                                |   on the next transfer starts 
          v   v                                v   being sampled at end of transfer N.

___ ____
CNV _____/ \________________________________/ \_____
_ _ _
SCLK ______________/ \___/ \_ ... ___/ \_______________

                   ___   ___           ___
SDO  _____________/___\_/___\ ...   __/___\_______________
                    ^
                    |
             Data from conversion N is output from here on

A better drawing can be found in datasheet page 29, Figure 57.
https://www.analog.com/media/en/technical-documentation/data-sheets/ADAQ4003.pdf

In sum, we're always reading a conversion that started at the end of the previous SPI transfer or, in other words, the data comes out with a latency (delay) of one read.

Quoted 6 lines

Datasheet somehow mentions that by saying
When turbo mode is enabled, the conversion result read on SDO corresponds to the result of the previous conversion.

I think I can do a dummy SPI transfer on buffer preenable so at least the first data is not invalid. Would that be better?

Not really. There will be a relatively long delay between that conversion trigger and when the sample is read. So the data might be slightly less stale in that case, but still not particularly useful, e.g. if you are doing any kind of signal processing that expects equal time between all samples.

On similar chips, like ad7944, we just documented that the first sample does not contain valid data and needs to be discarded.

Quoted 3 lines

I also didn't expect to find out HDL support for 16-bit data width was removed. We used to have a build parameter for 16-bit precision ADCs.
https://github.com/analogdevicesinc/hdl/commit/b2dc91b30dae891b6319d88e083f26e726f43ba0#diff-1117c2618353232e5f22aa6a12e8ae976757fa897b3425f470a12123cae26535L13

A while back the HDL engineers mentioned to us that they wanted to standardize on 32-bit data words everywhere. While not the most efficient use of memory, having fewer options does make things simpler across the entire software stack.

Quoted 3 lines

Would something like 'because SPI offloading leads to data being pushed to memory in CPU endianness' be a reasonable comment?

Another way to say it is that SPI offload reads data in complete words and not in separate 8-bit xfers (bits_per_word = realbits vs. bits_per_word = 8).

Hi, comments inline.

Quoted 56 lines · David Lechner

Quoted 41 lines · Marcelo Schmitt

...

Quoted 11 lines

Quoted 10 lines

+/*
+ * This executes a data sample transfer when using SPI offloading for when the
+ * device connections are in "3-wire" mode, selected when the adi,sdi-pin device
+ * tree property is set to "high". In this connection mode, the ADC SDI pin is
+ * connected to VIO and ADC CNV pin is connected to a SPI controller CS (it
+ * can't be connected to a GPIO).
+ *
+ * In order to achieve the maximum sample rate, we only do one transfer per
+ * SPI offload trigger. This has the effect that the first sample data is not
+ * valid because it is reading the previous conversion result. We also use

Quoted 2 lines

Say what happens to that invalid sample. Is it dropped or provided to userspace as if it were valid? (I hope dropped!)

TL;DR: The invalid sample goes into the buffer as a valid one.

In AD4000 '3-wire' mode, data capture has a latency (delay) of one sample.

The ADC begins sampling data N at CNV rising edge

          |   +-- CNV (usually SPI CS) is brought low to begin reading the data
          |   |                                +-- Data N + 1 that will be read
          |   |                                |   on the next transfer starts 
          v   v                                v   being sampled at end of transfer N.

___ ____
CNV _____/ \________________________________/ \_____
_ _ _
SCLK ______________/ \___/ \_ ... ___/ \_______________

                   ___   ___           ___
SDO  _____________/___\_/___\ ...   __/___\_______________
                    ^
                    |
             Data from conversion N is output from here on

A better drawing can be found in datasheet page 29, Figure 57.
https://www.analog.com/media/en/technical-documentation/data-sheets/ADAQ4003.pdf

In sum, we're always reading a conversion that started at the end of the previous SPI transfer or, in other words, the data comes out with a latency (delay) of one read.

Quoted 6 lines

Datasheet somehow mentions that by saying
When turbo mode is enabled, the conversion result read on SDO corresponds to the result of the previous conversion.

I think I can do a dummy SPI transfer on buffer preenable so at least the first data is not invalid. Would that be better?

Not really. There will be a relatively long delay between that conversion trigger and when the sample is read. So the data might be slightly less stale in that case, but still not particularly useful, e.g. if you are doing any kind of signal processing that expects equal time between all samples.

Quoted 3 lines

On similar chips, like ad7944, we just documented that the first sample does not contain valid data and needs to be discarded.

Okay, I'll assume that to be acceptable and do the same for this one.

...

Quoted 8 lines

Quoted 3 lines

I also didn't expect to find out HDL support for 16-bit data width was removed. We used to have a build parameter for 16-bit precision ADCs.
https://github.com/analogdevicesinc/hdl/commit/b2dc91b30dae891b6319d88e083f26e726f43ba0#diff-1117c2618353232e5f22aa6a12e8ae976757fa897b3425f470a12123cae26535L13

A while back the HDL engineers mentioned to us that they wanted to standardize on 32-bit data words everywhere. While not the most efficient use of memory, having fewer options does make things simpler across the entire software stack.

Ack

Quoted 1 line

Quoted 1 line

Quoted 6 lines

Quoted 2 lines

Would something like 'because SPI offloading leads to data being pushed to memory in CPU endianness' be a reasonable comment?

Another way to say it is that SPI offload reads data in complete words and not in separate 8-bit xfers (bits_per_word = realbits vs. bits_per_word = 8).

Ah sure, I recall the effect of setting .bits_per_word now. Will add a comment explaining why the difference in endianness.

Thanks,
Marcelo

When SPI offloading is supported, the IIO device provides different sysfs interfaces to allow using the adjusting the sample rate. Document SPI offload support for AD4000 and similar devices.

Signed-off-by Marcelo Schmitt <[email protected]>

---
 Documentation/iio/ad4000.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Documentation/iio/ad4000.rst +0 -0

index 468d30dc9214..2d56b0762570 100644

Documentation/iio/ad4000.rst +11 -0

+
+.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/pulsar_adc/index.html
+
+When set for SPI offload support, the IIO device will provide different
+interfaces.
+
+* Either ``in_voltage0_sampling_frequency`` or
+  ``in_voltage0-voltage1_sampling_frequency`` file is provided to allow setting
+  the sample rate.
+* IIO trigger device is not provided (no ``trigger`` directory).
+* ``timestamp`` channel is not provided.

Quoted 14 lines · On Fri, 14 Mar 2025 14:19:33 -0300 Marcelo Schmitt…

When SPI offloading is supported, the IIO device provides different sysfs interfaces to allow using the adjusting the sample rate. Document SPI offload support for AD4000 and similar devices.

Signed-off-by Marcelo Schmitt <[email protected]>

---
 Documentation/iio/ad4000.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Documentation/iio/ad4000.rst +0 -0

index 468d30dc9214..2d56b0762570 100644
@@ -191,3 +191,20 @@ Typical voltage channel attributes of a differential AD4000 series device:

Documentation/iio/ad4000.rst Typical voltage channel attributes of a differential AD4000 series device: · line 199

Quoted 5 lines

Documentation/iio/ad4000.rst +5 -0

+SPI offload support
+-------------------
+
+To be able to achieve the maximum sample rate, the driver can be used with the
+`AXI SPI Engine`_ to provide SPI offload support.

Can we make this more generic?
"the driver can be used with SPI offload engine, such as the ...

I'm rather hoping we see others in the long run as useful little things!

Quoted 3 lines

Documentation/iio/ad4000.rst +3 -0

+
+.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/pulsar_adc/index.html
+