From 9dfd00018ae29a48d05921b30fcb8f4672076d6d Mon Sep 17 00:00:00 2001 From: StancaPop <53567076+StancaPop@users.noreply.github.com> Date: Mon, 27 Nov 2023 12:53:21 +0200 Subject: [PATCH] docs: Improve consistency (#1229) * docs: Improve consistency The following rules have been implemented: 1. Tables/lists should contain only the carriers that we support for that reference design. 2. Hexadecimal addresses should be written in caps and separated by an underscore (eg. 0x9C4A_0000). 3. Block diagrams should contain subtitles only if there are at least two different diagrams. 4. The GPIOs should be listed in descending order and should have the number of bits specified next to their name. 5. All the source code links references should contain the project name. 6. The infrastructure documentation, if exists, should be listed after the IP list. --- docs/projects/ad469x_fmc/index.rst | 31 ++++---- docs/projects/ad7616_sdz/index.rst | 49 ++++++------- docs/projects/ad9081_fmca_ebz/index.rst | 98 +++++++++++++------------ docs/projects/ad9783_ebz/index.rst | 14 +--- docs/projects/adaq7980_sdz/index.rst | 60 +++++++-------- docs/projects/template/index.rst | 30 +++++--- 6 files changed, 141 insertions(+), 141 deletions(-) diff --git a/docs/projects/ad469x_fmc/index.rst b/docs/projects/ad469x_fmc/index.rst index de16ef28d..dc56141aa 100755 --- a/docs/projects/ad469x_fmc/index.rst +++ b/docs/projects/ad469x_fmc/index.rst @@ -43,6 +43,8 @@ data stream at maximum data rate, is triggered by the BUSY signal of the device. Block diagram ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The data path and clock domains are depicted in the below diagram: + .. image:: ad469x_hdl.svg :width: 800 :align: center @@ -51,14 +53,17 @@ Block diagram CPU/Memory interconnects addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -===================== ========== +The addresses are dependent on the architecture of the FPGA, having an offset +added to the base address from HDL(see more at :ref:`architecture`). + +===================== =========== Instance Address -===================== ========== -axi_ad469x_dma 0x44a30000 -spi_clkgen 0x44a70000 -spi_ad469x_axi_regmap 0x44a00000 -ad469x_trigger_gen 0x44b00000 -===================== ========== +===================== =========== +axi_ad469x_dma 0x44A3_0000 +spi_clkgen 0x44A7_0000 +spi_ad469x_axi_regmap 0x44A0_0000 +ad469x_trigger_gen 0x44B0_0000 +===================== =========== I2C connections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -157,11 +162,6 @@ A more comprehensive build guide can be found in the :ref:`build_hdl` user guide Resources ------------------------------------------------------------------------------- -Systems related -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- :dokuwiki:`AD469X User guide ` - Hardware related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -175,8 +175,7 @@ Hardware related HDL related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-hdl:`ad469x_fmc HDL project ` -- :ref:`SPI_ENGINE ` +- :git-hdl:`AD469X_FMC HDL project source code ` .. list-table:: :widths: 30 35 35 @@ -225,10 +224,12 @@ HDL related - :git-hdl:`library/util_i2c_mixer ` - :ref:`here ` +- :ref:`SPI Engine Framework documentation ` + Software related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-no-os:`No-OS project ` +- :git-no-os:`AD469X_FMCZ No-OS project source code ` - :dokuwiki:`How to build No-OS ` diff --git a/docs/projects/ad7616_sdz/index.rst b/docs/projects/ad7616_sdz/index.rst index 9670bd1aa..661ffe228 100644 --- a/docs/projects/ad7616_sdz/index.rst +++ b/docs/projects/ad7616_sdz/index.rst @@ -7,11 +7,11 @@ Overview ------------------------------------------------------------------------------- The :adi:`AD7616` is a 16-bit, data acquisition system (DAS) that supports -dual simultaneous sampling of 16 channels. The :adi:`AD7616` operates from a -single 5 V supply and can accommodate ±10 V, ±5 V, and ±2.5 V true bipolar -input signals while sampling at throughput rates up to 1 MSPS per channel pair -with 90 dB SNR. Higher SNR performance can be achieved with the on-chip -oversampling mode; 92 dB for an oversampling ratio of 2. +dual simultaneous sampling of 16 channels. It operates from a single 5 V supply +and can accommodate ±10 V, ±5 V, and ±2.5 V true bipolar input signals while +sampling at throughput rates up to 1 MSPS per channel pair with 90 dB SNR. +Higher SNR performance can be achieved with the on-chip oversampling mode; +92 dB for an oversampling ratio of 2. The input clamp protection circuitry can tolerate voltages up to ±20 V. The :adi:`AD7616` has 1 MΩ analog input impedance regardless of sampling @@ -57,6 +57,8 @@ The data path of the HDL design is simple as follows: Block diagram ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The data path and clock domains are depicted in the below diagrams: + AD7616_SDZ serial interface ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -120,15 +122,18 @@ LK41 A Onboard 3v3 power supply selected CPU/Memory interconnects addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -======================== ========== +The addresses are dependent on the architecture of the FPGA, having an offset +added to the base address from HDL(see more at :ref:`architecture`). + +======================== =========== Instance Address -======================== ========== -axi_ad7616_dma 0x44a30000 -spi_clkgen 0x44a70000 -ad7616_pwm_gen 0x44b00000 -spi_ad7616_axi_regmap ** 0x44a00000 -axi_ad7616 * 0x44a80000 -======================== ========== +======================== =========== +axi_ad7616_dma 0x44A3_0000 +spi_clkgen 0x44A7_0000 +ad7616_pwm_gen 0x44B0_0000 +spi_ad7616_axi_regmap ** 0x44A0_0000 +axi_ad7616 * 0x44A8_0000 +======================== =========== .. admonition:: Legend :class: note @@ -198,11 +203,11 @@ The Software GPIO number is calculated as follows: - OUT - 43 - 97 - * - adc_hw_rngsel + * - adc_hw_rngsel[1:0] - OUT - 42:41 - 96:95 - * - adc_os ** + * - adc_os[2:0] ** - OUT - 40:38 - 94:92 @@ -214,7 +219,7 @@ The Software GPIO number is calculated as follows: - OUT - 36 - 90 - * - adc_chsel + * - adc_chsel[2:0] - OUT - 35:33 - 89:87 @@ -297,12 +302,6 @@ Connections and hardware changes Resources ------------------------------------------------------------------------------- -Systems related -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- :dokuwiki:`AD7616 User guide ` -- :dokuwiki:`How to build No-OS ` - Hardware related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -313,7 +312,7 @@ Hardware related HDL related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-hdl:`ad7616_sdz HDL project ` +- :git-hdl:`AD7616_SDZ HDL project source code ` .. list-table:: :widths: 30 35 35 @@ -374,12 +373,12 @@ HDL related - ``*`` instantiated only for SER_PAR_N=0 (parallel interface) - ``**`` instantiated only for SER_PAR_N=1 (serial interface) -- :ref:`SPI_ENGINE ` +- :ref:`SPI Engine Framework documentation ` Software related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-no-os:`No-OS project ` +- :git-no-os:`AD7616_SDZ No-OS project source code ` - :dokuwiki:`How to build No-OS ` diff --git a/docs/projects/ad9081_fmca_ebz/index.rst b/docs/projects/ad9081_fmca_ebz/index.rst index 8c91b3ff7..8f24fe648 100644 --- a/docs/projects/ad9081_fmca_ebz/index.rst +++ b/docs/projects/ad9081_fmca_ebz/index.rst @@ -107,6 +107,8 @@ Block design Block diagram ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The data path and clock domains are depicted in the below diagrams: + Example block design for Single link; M=8; L=4 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -370,61 +372,61 @@ GPIOs - - Zynq-7000 - Zynq MP - * - gpio[0:10] - - INOUT - - 32-42 - - 86-96 - - 110-120 - * - hmc_gpio1 - - INOUT - - 43 - - 97 - - 121 - * - agc0[0:1] - - IN - - 44, 45 - - 98, 99 - - 122, 123 - * - agc1[0:1] - - IN - - 46, 47 - - 100, 101 - - 124, 125 - * - agc2[0:1] - - IN - - 48, 49 - - 102, 103 - - 126, 127 - * - agc3[0:1] - - IN - - 50, 51 - - 104, 105 - - 128, 129 - * - irqb[0:1] - - IN - - 52, 53 - - 106, 107 - - 130, 131 - * - hmc_sync + * - txen[1:0] - OUT - - 54 - - 108 - - 132 + - 59:58 + - 113:112 + - 137:136 + * - rxen[1:0] + - OUT + - 57:56 + - 111:110 + - 135:134 * - rstb - OUT - 55 - 109 - 133 - * - rxen[0:1] + * - hmc_sync - OUT - - 56, 57 - - 110, 111 - - 134, 135 - * - txen[0:1] - - OUT - - 58, 59 - - 112, 113 - - 136, 137 + - 54 + - 108 + - 132 + * - irqb[1:0] + - IN + - 53:52 + - 107:106 + - 131:130 + * - agc3[1:0] + - IN + - 51:50 + - 105:104 + - 129:128 + * - agc2[1:0] + - IN + - 49:48 + - 103:102 + - 127:126 + * - agc1[1:0] + - IN + - 47:46 + - 101:100 + - 125:124 + * - agc0[1:0] + - IN + - 45:44 + - 99:98 + - 123:122 + * - hmc_gpio1 + - INOUT + - 43 + - 97 + - 121 + * - gpio[10:0] + - INOUT + - 42:32 + - 96:86 + - 120:110 Interrupts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/projects/ad9783_ebz/index.rst b/docs/projects/ad9783_ebz/index.rst index 4e84face6..0d5d721cf 100644 --- a/docs/projects/ad9783_ebz/index.rst +++ b/docs/projects/ad9783_ebz/index.rst @@ -141,21 +141,13 @@ Systems related Here you can find the quick start guides available for these evaluation boards: .. list-table:: - :widths: 20 10 20 20 20 10 + :widths: 50 50 :header-rows: 1 * - Evaluation board - - Zynq-7000 - Zynq UltraScale+ MP - - Microblaze - - Versal - - Arria 10 * - AD9783-EBZ - - --- - :dokuwiki:`[Wiki] ZCU102 ` - - --- - - --- - - --- Hardware related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -199,8 +191,8 @@ HDL related Software related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-linux:`Linux device tree zynqmp-zcu102-rev10-ad9783.dts ` -- :git-linux:`Linux driver ad9783.c ` +- :git-linux:`Linux device tree zynqmp-zcu102-rev10-ad9783.dts ` +- :git-linux:`Linux driver ad9783.c ` .. include:: ../common/more_information.rst diff --git a/docs/projects/adaq7980_sdz/index.rst b/docs/projects/adaq7980_sdz/index.rst index 85d6ce72f..3b1095dcf 100755 --- a/docs/projects/adaq7980_sdz/index.rst +++ b/docs/projects/adaq7980_sdz/index.rst @@ -60,6 +60,8 @@ Block design Block diagram ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The data path and clock domains are depicted in the below diagram: + .. image:: adaq7980_sdz_hdl.svg :width: 800 :align: center @@ -68,14 +70,17 @@ Block diagram CPU/Memory interconnects addresses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -=========================== ========== +The addresses are dependent on the architecture of the FPGA, having an offset +added to the base address from HDL (see more at :ref:`architecture`). + +=========================== =========== Instance Address -=========================== ========== -axi_adaq7980_dma 0x44a30000 -spi_clkgen 0x44a70000 -spi_adaq7980_adc_axi_regmap 0x44a00000 -spi_trigger_gen 0x44b00000 -=========================== ========== +=========================== =========== +axi_adaq7980_dma 0x44A3_0000 +spi_clkgen 0x44A7_0000 +spi_adaq7980_adc_axi_regmap 0x44A0_0000 +spi_trigger_gen 0x44B0_0000 +=========================== =========== I2C connections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -143,7 +148,7 @@ The Software GPIO number is calculated as follows: - INOUT - 40 - 94 - * - adaq7980_gpio + * - adaq7980_gpio[7:0] - INOUT - 39:32 - 93:86 @@ -182,12 +187,6 @@ A more comprehensive build guide can be found in the :ref:`build_hdl` user guide Resources ------------------------------------------------------------------------------- -Systems related -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- :dokuwiki:`ADAQ7980 User guide ` -- :dokuwiki:`How to build No-OS ` - Hardware related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -198,8 +197,7 @@ Hardware related HDL related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-hdl:`adaq7980_sdz HDL project ` -- :ref:`SPI_ENGINE ` +- :git-hdl:`ADAQ7980_SDZ HDL project source code ` .. list-table:: :widths: 30 35 35 @@ -209,49 +207,51 @@ HDL related - Source code link - Documentation link * - AXI_CLKGEN - - :git-hdl:`library/axi_dmac ` + - :git-hdl:`library/axi_dmac ` - :dokuwiki:`[Wiki] ` * - AXI_DMAC - - :git-hdl:`library/axi_dmac ` + - :git-hdl:`library/axi_dmac ` - :ref:`here ` * - AXI_HDMI_TX - - :git-hdl:`library/axi_hdmi_tx ` + - :git-hdl:`library/axi_hdmi_tx ` - :dokuwiki:`[Wiki] ` * - AXI_I2S_ADI - - :git-hdl:`library/axi_i2s_adi ` + - :git-hdl:`library/axi_i2s_adi ` - --- * - AXI_PWM_GEN - - :git-hdl:`library/axi_pwm_gen ` + - :git-hdl:`library/axi_pwm_gen ` - :dokuwiki:`[Wiki] ` * - AXI_SPDIF_TX - - :git-hdl:`library/axi_spdif_tx ` + - :git-hdl:`library/axi_spdif_tx ` - --- * - AXI_SPI_ENGINE - - :git-hdl:`library/spi_engine/axi_spi_engine ` + - :git-hdl:`library/spi_engine/axi_spi_engine ` - :ref:`here ` * - AXI_SYSID - - :git-hdl:`library/axi_sysid ` + - :git-hdl:`library/axi_sysid ` - :dokuwiki:`[Wiki] ` * - SPI_ENGINE_EXECUTION - - :git-hdl:`library/spi_engine/spi_engine_execution ` + - :git-hdl:`library/spi_engine/spi_engine_execution ` - :ref:`here ` * - SPI_ENGINE_INTERCONNECT - - :git-hdl:`library/spi_engine/spi_engine_interconnect ` + - :git-hdl:`library/spi_engine/spi_engine_interconnect ` - :ref:`here ` * - SPI_ENGINE_OFFLOAD - - :git-hdl:`library/spi_engine/spi_engine_offload ` + - :git-hdl:`library/spi_engine/spi_engine_offload ` - :ref:`here ` * - SYSID_ROM - - :git-hdl:`library/sysid_rom ` + - :git-hdl:`library/sysid_rom ` - :dokuwiki:`[Wiki] ` * - UTIL_I2C_MIXER - - :git-hdl:`library/util_i2c_mixer ` + - :git-hdl:`library/util_i2c_mixer ` - :ref:`here ` +- :ref:`SPI Engine Framework documentation ` + Software related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :git-no-os:`No-OS project ` +- :git-no-os:`ADAQ7980_SDZ No-OS project ` - :dokuwiki:`How to build No-OS ` diff --git a/docs/projects/template/index.rst b/docs/projects/template/index.rst index 0c82a8eb3..e4f1abf81 100644 --- a/docs/projects/template/index.rst +++ b/docs/projects/template/index.rst @@ -277,21 +277,21 @@ GPIOs - - Zynq-7000 - Zynq MP - * - signal name + * - signal_name[31:0] - IN/OUT/INOUT - - 32-63 - - 86-117 - - 110-141 - * - signal name + - 127:96 + - 181:150 + - 205:174 + * - signal_name[31:0] - IN/OUT/INOUT - - 64-95 - - 118-149 - - 142-173 - * - signal name + - 95:64 + - 149:118 + - 173:142 + * - signal_name[31:0] - IN/OUT/INOUT - - 96-127 - - 150-181 - - 174-205 + - 63:32 + - 117:86 + - 141:110 Interrupts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -702,9 +702,15 @@ HDL related - :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_dac` - :dokuwiki:`[Wiki] ` +\**\* MENTION THESE for JESD reference designs \**\* + - :dokuwiki:`[Wiki] Generic JESD204B block designs ` - :dokuwiki:`[Wiki] JESD204B High-Speed Serial Interface Support ` +\**\* MENTION THIS for SPI Engine reference designs \**\* + +- :ref:`SPI Engine Framework documentation ` + Software related ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~