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

@@ -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
+axi_ad469x_dma         0x44A3_0000
-spi_clkgen             0x44a70000
+spi_clkgen             0x44A7_0000
-spi_ad469x_axi_regmap  0x44a00000
+spi_ad469x_axi_regmap  0x44A0_0000
-ad469x_trigger_gen     0x44b00000
+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 <resources/eval/user-guides/ad469x>`
-
 Hardware related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -175,8 +175,7 @@ Hardware related
 HDL related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-hdl:`ad469x_fmc HDL project <projects/ad469x_fmc>`
+-  :git-hdl:`AD469X_FMC HDL project source code <projects/ad469x_fmc>`
--  :ref:`SPI_ENGINE <spi_engine>`
 
 .. list-table::
    :widths: 30 35 35
@@ -225,10 +224,12 @@ HDL related
      - :git-hdl:`library/util_i2c_mixer <library/util_i2c_mixer>`
      - :ref:`here <spi_engine offload>`
 
+-  :ref:`SPI Engine Framework documentation <spi_engine>`
+
 Software related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-no-os:`No-OS project <projects/ad469x_fmcz>`
+-  :git-no-os:`AD469X_FMCZ No-OS project source code  <projects/ad469x_fmcz>`
 
 -  :dokuwiki:`How to build No-OS <resources/no-os/build>`
 

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
+dual simultaneous sampling of 16 channels. It operates from a single 5 V supply
-single 5 V supply and can accommodate ±10 V, ±5 V, and ±2.5 V true bipolar
+and can accommodate ±10 V, ±5 V, and ±2.5 V true bipolar input signals while
-input signals while sampling at throughput rates up to 1 MSPS per channel pair
+sampling at throughput rates up to 1 MSPS per channel pair with 90 dB SNR.
-with 90 dB SNR. Higher SNR performance can be achieved with the on-chip
+Higher SNR performance can be achieved with the on-chip oversampling mode;
-oversampling mode; 92 dB for an oversampling ratio of 2.
+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
+axi_ad7616_dma            0x44A3_0000
-spi_clkgen                0x44a70000
+spi_clkgen                0x44A7_0000
-ad7616_pwm_gen            0x44b00000
+ad7616_pwm_gen            0x44B0_0000
-spi_ad7616_axi_regmap **  0x44a00000
+spi_ad7616_axi_regmap **  0x44A0_0000
-axi_ad7616 *              0x44a80000
+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 <resources/eval/user-guides/ad7616-sdz>`
--  :dokuwiki:`How to build No-OS <resources/no-os/build>`
-
 Hardware related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -313,7 +312,7 @@ Hardware related
 HDL related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-hdl:`ad7616_sdz HDL project <projects/ad7616_sdz>`
+-  :git-hdl:`AD7616_SDZ HDL project source code <projects/ad7616_sdz>`
 
 .. 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 <spi_engine>`
+-  :ref:`SPI Engine Framework documentation <spi_engine>`
 
 Software related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-no-os:`No-OS project <projects/ad7616-sdz>`
+-  :git-no-os:`AD7616_SDZ No-OS project source code <projects/ad7616-sdz>`
 
 -  :dokuwiki:`How to build No-OS <resources/no-os/build>`
 

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]
+   * - txen[1:0]
-     - 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
      - OUT
-     - 54
+     - 59:58
-     - 108
+     - 113:112
-     - 132
+     - 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
+     - 54
-     - 110, 111
+     - 108
-     - 134, 135
+     - 132
-   * - txen[0:1]
+   * - irqb[1:0]
-     - OUT
+     - IN
-     - 58, 59
+     - 53:52
-     - 112, 113
+     - 107:106
-     - 136, 137
+     - 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 <resources/fpga/xilinx/interposer/ad9783>`
-     - ---
-     - ---
-     - ---
 
 Hardware related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -199,8 +191,8 @@ HDL related
 Software related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-linux:`Linux device tree zynqmp-zcu102-rev10-ad9783.dts <master:arch/arm64/boot/dts/xilinx/zynqmp-zcu102-rev10-ad9783.dts>`
+-  :git-linux:`Linux device tree zynqmp-zcu102-rev10-ad9783.dts <arch/arm64/boot/dts/xilinx/zynqmp-zcu102-rev10-ad9783.dts>`
--  :git-linux:`Linux driver ad9783.c <master:drivers/iio/frequency>`
+-  :git-linux:`Linux driver ad9783.c <drivers/iio/frequency>`
 
 .. include:: ../common/more_information.rst
 

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
+axi_adaq7980_dma             0x44A3_0000
-spi_clkgen                   0x44a70000
+spi_clkgen                   0x44A7_0000
-spi_adaq7980_adc_axi_regmap  0x44a00000
+spi_adaq7980_adc_axi_regmap  0x44A0_0000
-spi_trigger_gen              0x44b00000
+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 <resources/eval/user-guides/adaq7980-sdz>`
--  :dokuwiki:`How to build No-OS <resources/no-os/build>`
-
 Hardware related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -198,8 +197,7 @@ Hardware related
 HDL related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-hdl:`adaq7980_sdz HDL project <projects/adaq7980_sdz>`
+-  :git-hdl:`ADAQ7980_SDZ HDL project source code <projects/adaq7980_sdz>`
--  :ref:`SPI_ENGINE <spi_engine>`
 
 .. list-table::
    :widths: 30 35 35
@@ -209,49 +207,51 @@ HDL related
      - Source code link
      - Documentation link
    * - AXI_CLKGEN
-     - :git-hdl:`library/axi_dmac <main:library/axi_clkgen>`
+     - :git-hdl:`library/axi_dmac <library/axi_clkgen>`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_clkgen>`
    * - AXI_DMAC
-     - :git-hdl:`library/axi_dmac <master:library/axi_dmac>`
+     - :git-hdl:`library/axi_dmac <library/axi_dmac>`
      - :ref:`here <axi_dmac>`
    * - AXI_HDMI_TX
-     - :git-hdl:`library/axi_hdmi_tx <main:library/axi_hdmi_tx>`
+     - :git-hdl:`library/axi_hdmi_tx <library/axi_hdmi_tx>`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_hdmi_tx>`
    * - AXI_I2S_ADI
-     - :git-hdl:`library/axi_i2s_adi <main:library/axi_i2s_adi>`
+     - :git-hdl:`library/axi_i2s_adi <library/axi_i2s_adi>`
      - ---
    * - AXI_PWM_GEN
-     - :git-hdl:`library/axi_pwm_gen <main:library/axi_pwm_gen>`
+     - :git-hdl:`library/axi_pwm_gen <library/axi_pwm_gen>`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_pwm_gen>`
    * - AXI_SPDIF_TX
-     - :git-hdl:`library/axi_spdif_tx <main:library/axi_spdif_tx>`
+     - :git-hdl:`library/axi_spdif_tx <library/axi_spdif_tx>`
      - ---
    * - AXI_SPI_ENGINE
-     - :git-hdl:`library/spi_engine/axi_spi_engine <main:library/spi_engine/axi_spi_engine>`
+     - :git-hdl:`library/spi_engine/axi_spi_engine <library/spi_engine/axi_spi_engine>`
      - :ref:`here <spi_engine axi>`
    * - AXI_SYSID
-     - :git-hdl:`library/axi_sysid <main:library/axi_sysid>`
+     - :git-hdl:`library/axi_sysid <library/axi_sysid>`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
    * - SPI_ENGINE_EXECUTION
-     - :git-hdl:`library/spi_engine/spi_engine_execution <main:library/spi_engine/spi_engine_execution>`
+     - :git-hdl:`library/spi_engine/spi_engine_execution <library/spi_engine/spi_engine_execution>`
      - :ref:`here <spi_engine execution>`
    * - SPI_ENGINE_INTERCONNECT
-     - :git-hdl:`library/spi_engine/spi_engine_interconnect <main:library/spi_engine/spi_engine_interconnect>`
+     - :git-hdl:`library/spi_engine/spi_engine_interconnect <library/spi_engine/spi_engine_interconnect>`
      - :ref:`here <spi_engine interconnect>`
    * - SPI_ENGINE_OFFLOAD
-     - :git-hdl:`library/spi_engine/spi_engine_offload <main:library/spi_engine/spi_engine_offload>`
+     - :git-hdl:`library/spi_engine/spi_engine_offload <library/spi_engine/spi_engine_offload>`
      - :ref:`here <spi_engine offload>`
    * - SYSID_ROM
-     - :git-hdl:`library/sysid_rom <main:library/sysid_rom>`
+     - :git-hdl:`library/sysid_rom <library/sysid_rom>`
      - :dokuwiki:`[Wiki] <resources/fpga/docs/axi_sysid>`
    * - UTIL_I2C_MIXER
-     - :git-hdl:`library/util_i2c_mixer <main:library/util_i2c_mixer>`
+     - :git-hdl:`library/util_i2c_mixer <library/util_i2c_mixer>`
      - :ref:`here <spi_engine offload>`
 
+-  :ref:`SPI Engine Framework documentation <spi_engine>`
+
 Software related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
--  :git-no-os:`No-OS project <projects/adaq7980_sdz>`
+-  :git-no-os:`ADAQ7980_SDZ No-OS project <projects/adaq7980_sdz>`
 
 -  :dokuwiki:`How to build No-OS <resources/no-os/build>`
 

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
+     - 127:96
-     - 86-117
+     - 181:150
-     - 110-141
+     - 205:174
-   * - signal name
+   * - signal_name[31:0]
      - IN/OUT/INOUT
-     - 64-95
+     - 95:64
-     - 118-149
+     - 149:118
-     - 142-173
+     - 173:142
-   * - signal name
+   * - signal_name[31:0]
      - IN/OUT/INOUT
-     - 96-127
+     - 63:32
-     - 150-181
+     - 117:86
-     - 174-205
+     - 141:110
 
 Interrupts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -702,9 +702,15 @@ HDL related
      - :git-hdl:`library/jesd204/ad_ip_jesd204_tpl_dac`
      - :dokuwiki:`[Wiki] <resources/fpga/peripherals/jesd204/jesd204_tpl_dac>`
 
+\**\* MENTION THESE for JESD reference designs \**\*
+
 -  :dokuwiki:`[Wiki] Generic JESD204B block designs <resources/fpga/docs/hdl/generic_jesd_bds>`
 -  :dokuwiki:`[Wiki] JESD204B High-Speed Serial Interface Support <resources/fpga/peripherals/jesd204>`
 
+\**\* MENTION THIS for SPI Engine reference designs \**\*
+
+-  :ref:`SPI Engine Framework documentation <spi_engine>`
+
 Software related
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~