diff --git a/docs/solutions/reference-designs/eval-ad9083/ad9083.rst b/docs/solutions/reference-designs/eval-ad9083/ad9083.rst new file mode 100644 index 00000000000..46f8ddd5ab9 --- /dev/null +++ b/docs/solutions/reference-designs/eval-ad9083/ad9083.rst @@ -0,0 +1,355 @@ +AD9083 Linux Driver +=================== + +Supported Devices +----------------- + +- :adi:`AD9083` + +Supported Boards +---------------- + +- :adi:`EVAL-AD9083` + +Supported HDL Cores +------------------- + +- `AD9083 FMC Card HDL Reference Design `_ + +Description +----------- + +The AD9083 is a 16-channel, 125 MHz bandwidth, continuous time Σ-Δ (CTSD) ADC. +The device features an on-chip, programmable, single-pole antialiasing filter +and termination resistor that is designed for low power, small size, and ease of +use. The 16 ADC cores features a first-order, CTSD modulator architecture with +integrated, background nonlinearity correction logic and self cancelling dither. +Each ADC features wide bandwidth inputs supporting a variety of user-selectable +input ranges. An integrated voltage reference eases design considerations. The +analog input and clock signals are differential inputs. Each ADC has a signal +processing tile to filter out of band shaped noise from the Σ-Δ ADC and reduce +the sample rate. Each tile contains a cascaded integrator comb (CIC) filter, a +quadrature digital downconverter (DDC) with multiple finite input response (FIR) +decimation filters (decimate by J block), or up to three quadrature DDC channels +with averaging decimation filters for data gating applications. Users can +configure the Subclass 1 JESD204B based, high speed serialized output in a +variety of lane configurations (up to four), depending on the DDC configuration +and the acceptable lane rate of the receiving logic device. Multiple device +synchronization is supported through the SYSREF±, TRIG±, and SYNCINB± input +pins. The AD9083 has flexible power-down options that allow significant power +savings when desired. All of these features can be programmed using a 1.8 V +capable 3-wire serial port interface (SPI). The AD9083 is available in a +Pb-free, 100-ball CSP_BGA and is specified over the −40°C to +85°C industrial +temperature range. + +Source Code +=========== + +Files +----- + ++------------+---------------------------------------------------------------------------------------------------------------+ +| Function | File | ++============+===============================================================================================================+ +| driver | :git-linux:`drivers/iio/adc/ad9083.c` | ++------------+---------------------------------------------------------------------------------------------------------------+ +| API driver | :git-linux:`drivers/iio/adc/ad9083` | ++------------+---------------------------------------------------------------------------------------------------------------+ + +Example device trees +~~~~~~~~~~~~~~~~~~~~ + ++---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Function | File | ++===============+======================================================================================================================================================================+ +| dtsi | :git-linux:`arch/arm64/boot/dts/xilinx/adi-ad9083-fmc-ebz.dtsi` | ++---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| dts | :git-linux:`arch/arm64/boot/dts/xilinx/zynqmp-zcu102-rev10-ad9083-fmc-ebz.dts` | ++---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| Documentation | :git-linux:`Documentation/devicetree/bindings/iio/adc/adi,ad9083.yaml` | ++---------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Interrelated Device Drivers +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- `JESD204 (FSM) Interface Linux Kernel Framework `_ +- `JESD204 Interface Framework `_ + +Transport Layer Receive AXI-ADC driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++----------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| Function | File | ++==========+===============================================================================================================================================+ +| driver | :git-linux:`drivers/iio/adc/cf_axi_adc_core.c` | ++----------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| driver | :git-linux:`drivers/iio/adc/cf_axi_adc_ring_stream.c` | ++----------+-----------------------------------------------------------------------------------------------------------------------------------------------+ +| include | :git-linux:`drivers/iio/adc/cf_axi_adc.h` | ++----------+-----------------------------------------------------------------------------------------------------------------------------------------------+ + +**Documentation:** `AXI ADC HDL Linux Driver `_ + +Link Layer AXI JESD204B HDL driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++----------+---------------------------------------------------------------------------------------------------------------------------------------+ +| Function | File | ++==========+=======================================================================================================================================+ +| driver | :git-linux:`drivers/iio/jesd204/axi_jesd204_rx.c` | ++----------+---------------------------------------------------------------------------------------------------------------------------------------+ +| driver | :git-linux:`drivers/iio/jesd204/axi_jesd204_tx.c` | ++----------+---------------------------------------------------------------------------------------------------------------------------------------+ + +**Documentation:** + +- `JESD204B/C Transmit Linux Driver `_ +- `JESD204B/C Receive Linux Driver `_ + +PHY Layer AXI JESD204B GT (Gigabit Tranceiver) HDL driver (XILINX/ALTERA-INTEL) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ++----------+-------------------------------------------------------------------------------------------------------------------------------+ +| Function | File | ++==========+===============================================================================================================================+ +| driver | :git-linux:`drivers/iio/jesd204/axi_adxcvr.c` | ++----------+-------------------------------------------------------------------------------------------------------------------------------+ + +**Documentation:** + +- `JESD204B/C AXI_ADXCVR Highspeed Transceivers Linux Driver `_ + +Enabling Linux driver support +============================= + +Configure kernel with "make menuconfig" (alternatively use "make xconfig" or +"make qconfig") + +.. hint:: + + The AD9083 driver depends on CONFIG_SPI + +Adding Linux driver support +=========================== + +Configure kernel with "make menuconfig" (alternatively use "make xconfig" or +"make qconfig") + +:: + + Linux Kernel Configuration + Device Drivers ---> + <*> Industrial I/O support ---> + --- Industrial I/O support + - *- Enable ring buffer support within IIO + - *- Industrial I/O lock free software ring + - *- Enable triggered sampling support + + Direct Digital Synthesis + [--snip--] + + <*> Analog Devices CoreFPGA AXI DDS driver + <*> Analog Devices AD9083 16-Channel, 125 MHz Bandwidth, JESD204B ADC + + [--snip--] + +Device Tree Example +------------------- + +.. code:: dts + + #include + &spi0 { + adc0_ad9083: ad9083@0 { + compatible = "adi,ad9083"; + reg = <0>; + + jesd204-device; + #jesd204-cells = <2>; + jesd204-top-device = <0>; + jesd204-link-ids = <0>; + jesd204-inputs = <&axi_ad9083_core_rx 0 0>; + + spi-max-frequency = <1000000>; + clocks = <&ad9528 13>; + clock-names = "adc_ref_clk"; + adi,adc-frequency-hz= /bits/ 64 <2000000000>; /* 2 GHz */ + + /* adi_ad9083 config */ + + adi,vmax-microvolt = <1800>; + adi,fc-hz = /bits/ 64 <800000000>; + adi,rterm-ohms = <100>; + adi,backoff = <0>; + adi,finmax-hz = /bits/ 64 <100000000>; + adi,nco0_freq-hz = /bits/ 64 <0>; + adi,nco1_freq-hz = /bits/ 64 <0>; + adi,nco2_freq-hz = /bits/ 64 <0>; + adi,cic_decimation = /bits/ 8 ; + adi,j_decimation = /bits/ 8 ; + adi,g_decimation = /bits/ 8 <0>; + adi,h_decimation = /bits/ 8 <0>; + adi,nco0_datapath_mode = /bits/ 8 ; + + /* JESD204 parameters */ + + adi,octets-per-frame = <8>; + adi,frames-per-multiframe = <32>; + adi,converter-resolution = <16>; + adi,bits-per-sample = <16>; + adi,converters-per-device = <16>; + adi,control-bits-per-sample = <0>; + adi,lanes-per-device = <4>; + adi,subclass = <0>; + }; + }; + +Driver testing +============== + +In case the driver probes successfully and the device gets instantiated. Your +systems kernel messages should include some line, which may look like the one +shown below. + +:: + + [ 8.404405] ad9083 spi1.0: AD9083 Rev. 1 Grade 0 (API 1.0.1) probed + +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. + +.. container:: box bggreen + + This specifies any shell prompt running on the target + + + :: + + root@analog:/sys/bus/iio/devices# ls + iio:device0 iio:device1 iio:device2 iio_sysfs_trigger + + root@analog:/sys/bus/iio/devices# cd iio:device2 + root@analog:/sys/bus/iio/devices/iio:device2# cat name + axi-ad9083-rx-hpc + root@analog:/sys/bus/iio/devices/iio:device2# ls -l + total 0 + drwxr-xr-x 2 root root 0 Jun 23 08:02 buffer + -r--r--r-- 1 root root 4096 Jun 23 08:02 dev + -rw-r--r-- 1 root root 4096 Jun 23 08:02 jesd204_fsm_ctrl + -r--r--r-- 1 root root 4096 Jun 23 08:02 jesd204_fsm_error + -r--r--r-- 1 root root 4096 Jun 23 08:02 jesd204_fsm_paused + --w------- 1 root root 4096 Jun 23 08:02 jesd204_fsm_resume + -r--r--r-- 1 root root 4096 Jun 23 08:02 jesd204_fsm_state + -r--r--r-- 1 root root 4096 Jun 23 08:02 name + lrwxrwxrwx 1 root root 0 Jun 23 08:02 of_node -> ../../../../../firmware/devicetree/base/fpga-axi0 + drwxr-xr-x 2 root root 0 Jun 23 08:02 power + drwxr-xr-x 2 root root 0 Jun 23 08:02 scan_elements + lrwxrwxrwx 1 root root 0 Jun 23 08:02 subsystem -> ../../../../../bus/iio + -rw-r--r-- 1 root root 4096 Jun 23 08:02 uevent + + +Low level register access via debugfs (direct_reg_access) +========================================================= + +Some IIO drivers feature an optional debug facility, allowing users to read or +write registers directly. Special care needs to be taken when using this +feature, since you can modify registers on the back of the driver. Accessing +debugfs requires root privileges. + +In order to identify if the IIO device in question feature this option you first +need to identify the IIO device number. + +Therefore read the name attribute of each IIO device + +.. container:: box bggreen + + This specifies any shell prompt running on the target + + + :: + + root@analog:/sys/bus/iio/devices# ls + iio:device0 iio:device1 iio:device2 iio_sysfs_trigger + root@analog:/sys/bus/iio/devices# cd iio:device2 + root@analog:/sys/bus/iio/devices/iio:device2# cat name + axi-ad9083-rx-hpc + + +Change directory to /sys/kernel/debug/iio/iio:deviceX and check if the +direct_reg_access file exists. + +.. container:: box bggreen + + This specifies any shell prompt running on the target + + + :: + + root@analog:~# cd /sys/kernel/debug/iio/iio\:device2/ + root@analog:/sys/kernel/debug/iio/iio:device2# ls direct_reg_access + ls direct_reg_access + root@analog:/sys/kernel/debug/iio/iio:device2# + + +Reading + +.. container:: box bggreen + + This specifies any shell prompt running on the target + + + :: + + root@analog:/sys/kernel/debug/iio/iio:device2# echo 0x0 > direct_reg_access + + root@analog:/sys/kernel/debug/iio/iio:device2# cat direct_reg_access + 0xAD + root@analog:/sys/kernel/debug/iio/iio:device2# + + +Writing + +Write ADDRESS VALUE + +.. container:: box bggreen + + This specifies any shell prompt running on the target + + + :: + + root@analog:/sys/kernel/debug/iio/iio:device2# echo 0x3D 0x80 > direct_reg_access + root@analog:/sys/kernel/debug/iio/iio:device2# cat direct_reg_access + 0x80 + root@analog:/sys/kernel/debug/iio/iio:device2# + + +More Information +================ + +- IIO mailing list: linux-iio@vger.kernel.org +- `IIO Linux Kernel Documentation sysfs-bus-iio-\* `_ +- `IIO Documentation `_ +- `IIO test and visualization application `_ +- `libiio - IIO system library `_ +- `libiio - Internals `_ +- `Pointers and good books `_ +- `IIO High Speed `_ +- `Software Defined Radio using the IIO framework `_ +- + +|libiio introduction| + +*Need Help?* + +- :ez:`Analog Devices Linux Device Drivers Help Forum ` +- `Ask a Question `_ + +.. |libiio introduction| image:: https://wiki.analog.com/_media/software/linux/docs/iio/youtube>p_vntewue24 diff --git a/docs/solutions/reference-designs/eval-ad9083/index.rst b/docs/solutions/reference-designs/eval-ad9083/index.rst new file mode 100644 index 00000000000..7dc9e71cb9f --- /dev/null +++ b/docs/solutions/reference-designs/eval-ad9083/index.rst @@ -0,0 +1,44 @@ +.. _eval_ad9083 eval: + +EVAL AD9083 +=================================================================== + +.. TODO: Add a picture of the chip/board + +Overview +------------------------------------------------------------------------------- + +.. TODO: Describe in max 10 rows the main features and applications. + +Features: + +- feature 1 +- feature 2 + +Applications: + +- application 1 +- application 2 + +.. toctree:: + :hidden: + + ad9083 + +------------------------------------------------------------------------------- + +People who follow the flow that is outlined, have a much better experience with +things. However, like many things, documentation is never as complete as it +should be. If you have any questions, feel free to ask on our +:ref:`EngineerZone forums `, but before that, please make +sure you read our documentation thoroughly. + +Warning +------------------------------------------------------------------------------- + +.. esd-warning:: + +Help and support +------------------------------------------------------------------------------- + +Please go to :ref:`Help and Support ` page.