AD4003/AD4007/AD4011/AD4020/ADAQ4001/ADAQ4003

AD4003/AD4007/AD4011/AD4020/ADAQ4001/ADAQ4003 Linux Driver.

Supported Devices

• AD4000

• AD4001

• AD4002

• AD4003

• AD4004

• AD4005

• AD4006

• AD4007

• AD4008

• AD4010

• AD4011

• AD4020

• AD4021

• AD4022

• ADAQ4003

Evaluation Boards

• EVAL-AD400x-FMCZ

• EVAL-ADAQ40xx

Description

Analog Devices AD4000 and the above listed devices are high accuracy, high speed, low power SAR ADCs.

This is the Linux industrial I/O (Linux Industrial I/O Subsystem) subsystem driver, targeting single channel SPI interface AD4000 and similar ADC devices. The industrial I/O subsystem provides a unified framework for drivers for many different types of converters and sensors using a number of different physical interfaces (I2C, SPI, etc). See Linux Industrial I/O Subsystem for more information.

See the Evaluating AD400X and ADAQ400X devices user guide for instructions on how to setup and evaluate devices supported by the ad4000 Linux driver.

Source Code

Status

Source	Mainlined?
drivers/iio/adc/ad4000.c	Yes

Files

Function	File
driver	drivers/iio/adc/ad4000.c
devicetree bindings	adi,ad4000.yaml
ZedBoard example devicetree	arch/arm/boot/dts/zynq-zed-adv7511-ad4020.dts
CoraZ7 example devicetree	arch/arm/boot/dts/zynq-coraz7s-adaq4003.dts

Adding Linux driver support

Kernel configuration

Configure kernel with make menuconfig (alternatively use make xconfig or make qconfig)

Note

The driver depends on CONFIG_SPI and selects IIO_BUFFER, IIO_BUFFER_DMAENGINE, IIO_TRIGGERED_BUFFER and SPI_OFFLOAD.

Linux Kernel Configuration
    Device Drivers  --->
        ...
        <*>     Industrial I/O support --->
            --- Industrial I/O support
            ...
            Analog to digital converters  --->
                ...
                <*>   Analog Devices AD4000 ADC Driver
                ...
            ...
        ...

Driver setup

AD4003/AD4007/AD4011/AD4020 are high speed analog-to-digital converters with sample rates up to 2 MSPS. On FPGA-based platforms the device is driven through the following HDL components:

• SPI Engine

• AXI DMAC

The devicetree binding requires compatible, reg, vdd-supply, vio-supply and ref-supply. adi,sdi-pin describes how the ADC SDI pin is wired (high, low, cs or sdi); cnv-gpios gives the GPIO connected to the CNV pin when the host drives it directly. ADAQ4001 and ADAQ4003 additionally support adi,gain-milli to describe the hardware gain set by the external resistor network, and adi,high-z-input to select High-Z input mode (only available when adi,sdi-pin is not set, i.e. SDI tied to MOSI).

#include <dt-bindings/gpio/gpio.h>
spi {
    #address-cells = <1>;
    #size-cells = <0>;
    adc@0 {
        compatible = "adi,ad4020";
        reg = <0>;
        spi-max-frequency = <71000000>;
        vdd-supply = <&supply_1_8v>;
        vio-supply = <&supply_1_8v>;
        ref-supply = <&supply_5v>;
        adi,sdi-pin = "cs";
        cnv-gpios = <&gpio0 88 GPIO_ACTIVE_HIGH>;
    };
};

spi {
    #address-cells = <1>;
    #size-cells = <0>;
    adc@0 {
        compatible = "adi,adaq4003";
        reg = <0>;
        spi-max-frequency = <80000000>;
        vdd-supply = <&supply_1_8v>;
        vio-supply = <&supply_1_8v>;
        ref-supply = <&supply_5v>;
        adi,high-z-input;
        adi,gain-milli = /bits/ 16 <454>;
    };
};

See the Evaluating AD400X and ADAQ400X devices user guide for examples of device trees used with devices supported by the ad4000 Linux driver.

Driver testing

Each and every IIO device, typically a hardware chip, has a device folder under /sys/bus/iio/devices/iio:deviceX. Where X is the IIO index of the device. Under every of these directory folders reside a set of files, depending on the characteristics and features of the hardware device in question. These files are consistently generalized and documented in the IIO ABI documentation. In order to determine which IIO deviceX corresponds to which hardware device, the user can read the name file /sys/bus/iio/devices/iio:deviceX/name. In case the sequence in which the iio device drivers are loaded/registered is constant, the numbering is constant and may be known in advance.

Tip

An example program which uses the interface can be found here:

• IIO Oscilloscope

root@analog:~# ls -l /sys/bus/iio/devices/
total 0
lrwxrwxrwx 1 root root 0 Apr  2 21:42 iio:device0 -> ../../../devices/soc0/axi/f8007100.adc/iio:device0
lrwxrwxrwx 1 root root 0 Apr  2 21:43 iio:device1 -> ../../../devices/soc0/fpga-axi@0/44a00000.spi/spi_master/spi0/spi0.0/iio:device1
lrwxrwxrwx 1 root root 0 Apr  2 21:42 iio_sysfs_trigger -> ../../../devices/iio_sysfs_trigger

root@analog:~# ls -l /sys/bus/iio/devices/iio:device1/
total 0
drwxr-xr-x 2 root root    0 Apr  2 21:43 buffer
drwxr-xr-x 2 root root    0 Apr  2 21:43 buffer0
-r--r--r-- 1 root root 4096 Apr  2 21:43 dev
-rw-r--r-- 1 root root 4096 Apr  2 21:43 in_voltage0-voltage1_offset
-rw-r--r-- 1 root root 4096 Apr  2 21:43 in_voltage0-voltage1_raw
-rw-r--r-- 1 root root 4096 Apr  2 21:43 in_voltage0-voltage1_scale
-r--r--r-- 1 root root 4096 Apr  2 21:43 name
lrwxrwxrwx 1 root root    0 Apr  2 21:43 of_node -> ../../../../../../../../firmware/devicetree/base/fpga-axi@0/spi@44a00000/adc@0
drwxr-xr-x 2 root root    0 Apr  2 21:43 power
-rw-r--r-- 1 root root 4096 Apr  2 21:43 in_voltage0-voltage1_sampling_frequency
drwxr-xr-x 2 root root    0 Apr  2 21:43 scan_elements
lrwxrwxrwx 1 root root    0 Apr  2 21:43 subsystem -> ../../../../../../../../bus/iio
-rw-r--r-- 1 root root 4096 Apr  2 21:43 uevent

Identify the device

root@analog:~# cat /sys/bus/iio/devices/iio:device1/name
adaq4003

Show channel scale

Description: Scale to be applied to in_voltage0-voltage1_raw in order to obtain the measured voltage in millivolts

root@analog:~# cat /sys/bus/iio/devices/iio:device1/in_voltage0-voltage1_scale
0.019073486

Configure sampling rate

The sampling-frequency attribute exists only when the ADC is driven through SPI offload, and is per channel: in_voltage0-voltage1_sampling_frequency for differential parts such as AD4003/AD4007/AD4011/AD4020/ADAQ4001/ADAQ4003, or in_voltage0_sampling_frequency for pseudo-differential parts such as AD4000. Without SPI offload, an IIO trigger paces capture and there is no sampling-frequency attribute.

root@analog:~# cat /sys/bus/iio/devices/iio:device1/in_voltage0-voltage1_sampling_frequency
2000000
root@analog:~# echo 1000000 > /sys/bus/iio/devices/iio:device1/in_voltage0-voltage1_sampling_frequency
root@analog:~# cat /sys/bus/iio/devices/iio:device1/in_voltage0-voltage1_sampling_frequency
1000000

Buffer management

root@analog:~# ls -l /sys/bus/iio/devices/iio:device1/buffer/
total 0
-r--r--r-- 1 root root 4096 Apr  3 08:11 data_available
-r--r--r-- 1 root root 4096 Apr  3 08:11 direction
-rw-r--r-- 1 root root 4096 Apr  3 08:11 enable
-rw-r--r-- 1 root root 4096 Apr  3 08:11 length
-r--r--r-- 1 root root 4096 Apr  3 08:11 length_align_bytes
-r--r--r-- 1 root root 4096 Apr  3 08:11 watermark

The Industrial I/O subsystem supports buffered data acquisition. Buffer implementation and capabilities depend on the driver. Devices with buffer support expose each buffer at /sys/bus/iio/devices/iio:deviceX/bufferY, where Y is the buffer index, starting at 0. The first buffer is additionally exposed through the legacy buffer directory, which contains its buffer-control attributes. Its scan configuration is exposed through the legacy scan_elements directory, while multi-buffer systems expose the scan attributes in the corresponding bufferY directory. Read samples from the device character node /dev/iio:deviceX; the selected buffer is determined by the active buffer configuration.

length

Get/set the number of sample sets that may be held by the buffer.

enable

Enables/disables the buffer. This file should be written last, after length and selection of scan elements.

watermark

A single positive integer specifying the maximum number of scan elements to wait for. Poll will block until the watermark is reached. Blocking read will wait until the minimum between the requested read amount or the low water mark is available. Non-blocking read will retrieve the available samples from the buffer even if there are less samples then watermark level. This allows the application to block on poll with a timeout and read the available samples after the timeout expires and thus have a maximum delay guarantee.

data_available

A read-only value indicating the bytes of data available in the buffer. In the case of an output buffer, this indicates the amount of empty space available to write data to. In the case of an input buffer, this indicates the amount of data available for reading.

length_align_bytes

Using the high-speed interface. DMA buffers may have an alignment requirement for the buffer length. Newer versions of the kernel will report the alignment requirements associated with a device through the length_align_bytes property.

scan_elements

The scan_elements directory contains interfaces for elements that will be captured for a single triggered sample set in the buffer.

root@analog:~# ls -l /sys/bus/iio/devices/iio:device1/scan_elements/
total 0
-rw-r--r-- 1 root root 4096 Apr  3 08:11 in_voltage0-voltage1_en
-r--r--r-- 1 root root 4096 Apr  3 08:11 in_voltage0-voltage1_index
-r--r--r-- 1 root root 4096 Apr  3 08:11 in_voltage0-voltage1_type

in_voltageX_en / in_voltageX-voltageY_en / in_timestamp_en:

Scan element control for triggered data capture. Writing 1 will enable the scan element, writing 0 will disable it

in_voltageX_type / in_voltageX-voltageY_type / in_timestamp_type:

Describes the scan element’s representation in the buffer. The format is [be|le]:[s|u]bits/storagebits[Xrepeat]>>shift. The prefix gives byte order; s or u specifies signed (two’s complement) or unsigned data. bits is the number of meaningful bits and storagebits is the storage width. The optional repeat count describes repeated elements. After interpreting byte order, shift the storage value right by shift and mask it to bits; signed values also require sign extension. For example, be:u12/16>>1 describes an unsigned 12-bit value in big-endian 16-bit storage, shifted right by one bit. Account for alignment padding when combining enabled elements into a complete scan.

in_voltageX_index / in_voltageX-voltageY_index / in_timestamp_index:

A nonnegative integer specifying the ordering of this scan element in the buffer. Note these are not dependent on what is enabled and may not be contiguous. Thus for user-space to establish the full layout these must be used in conjunction with all _en attributes to establish which channels are present, and the relevant _type attributes to establish the data storage format.

root@analog:/sys/bus/iio/devices/iio:device1/scan_elements# grep "" *
in_voltage0-voltage1_en:0
in_voltage0-voltage1_index:0
in_voltage0-voltage1_type:le:s18/32>>0

Buffer Example

When the buffer is enabled, the ad4000 driver prepares a read transfer and configures the SPI Engine Offload Module module to repeat that transfer each time the offload module is triggered. Then, the driver sets a PWM device to trigger the offload module at the rate specified by the sampling_frequency attribute. With that, ADC readings are gathered continuously while the buffer remains enabled.

root@analog:~# echo 1 > /sys/bus/iio/devices/iio:device1/scan_elements/in_voltage0-voltage1_en
root@analog:~# cat /sys/bus/iio/devices/iio:device1/scan_elements/in_voltage0-voltage1_en
1
root@analog:~# echo 1 > /sys/bus/iio/devices/iio:device1/buffer/enable
root@analog:~# cat /sys/bus/iio/devices/iio:device1/buffer/data_available
32768

Data interpretation

Each buffer entry contains one sample. The amount of bits and their meaning will vary according to ADC precision and output code pattern (whether output code is twos complement or not). Buffer raw data may be retrieved by reading the character device associated with the ADC device.

root@analog:~# hexdump -n 512 -e ' 32 "%d " "\n"' /dev/iio:device1
4864 4889 4730 4716 4695 4678 4667 4659 4662 4676 4706 4738 4770 4789 4786 4785 4775 4763 4752 4737 4723 4703 4686 4673 4666 4672 4688 4715 4762 4799 4820 4821
4816 4807 4788 4773 4757 4737 4718 4694 4676 4664 4668 4692 4727 4777 4814 4837 4836 4829 4822 4808 4796 4771 4748 4728 4707 4685 4664 4654 4651 4659 4675 4709
4757 4801 4823 4826 4812 4800 4789 4770 4749 4724 4700 4677 4653 4644 4633 4639 4659 4695 4738 4777 4798 4799 4794 4785 4772 4755 4735 4712 4692 4668 4652 4646
4641 4648 4674 4709 4753 4793 4817 4818 4808 4797 4780 4764 4748 4724 4699 4674 4656 4639 4627 4633 4644 4677 4716 4765 4794 4804 4801 4791 4778 4763 4744 4721

Remove the -n parameter to keep reading the buffer continuously. To stop capture, disable the buffer by writing 0 to /sys/bus/iio/devices/iio:device1/buffer/enable.

More Information

• IIO mailing list: linux-iio@vger.kernel.org

• IIO Linux Kernel Documentation sysfs-bus-iio-*

• IIO Documentation

• IIO Oscilloscope

• Libiio

• About libiio

• IIO High Speed

• Software Defined Radio using the IIO framework

• libiio introduction