docs: Update user guide, remove legacy code (#1242)

Signed-off-by: Jorge Marques <jorge.marques@analog.com>

docs/conf.py

@@ -13,7 +13,6 @@ release = 'v0.1'
 
 import os, sys
 
-user = os.environ.get("USER")
 sys.path.append(os.path.abspath("./extensions"))
 
 extensions = [
@@ -38,11 +37,6 @@ validate_links = False
 todo_include_todos = True
 todo_emit_warnings = True
 
-# -- Symbolator configuration -------------------------------------------------
-
-symbolator_cmd = f"/home/{user}/.local/bin/symbolator"
-symbolator_cmd_args = ['-t', '--scale=0.75']
-
 # -- Options for HTML output --------------------------------------------------
 
 html_theme = 'furo'

docs/library/spi_engine/axi_spi_engine.rst

@@ -148,24 +148,30 @@ the ID of the last completed event.
 Interrupts
 --------------------------------------------------------------------------------
 
-The SPI Engine AXI peripheral has 4 internal interrupts. One for each of the
+The SPI Engine AXI peripheral has 4 internal interrupts, which are
-FIFOs which are asserted when the FIFO level falls bellow the almost empty level
+asserted when:
-(for the command or SDO FIFO) or rises above the almost full level (for the SDI
+
-FIFO).
+* ``CMD_ALMOST_EMPTY``: the level falls bellow the almost empty level.
-And one interrupt which is asserted when a new synchronization event arrives.
+* ``SDO_ALMOST_EMPTY``: the level falls bellow the almost empty level.
+* ``SDI_ALMOST_FULL``: the level rises above the almost full level.
+* ``SYNC_EVENT``: a new synchronization event arrives.
+
 The peripheral has 1 external interrupt which is supposed to be connected to the
 upstream interrupt controller.
 The external interrupt is a logical OR-operation over the internal interrupts,
 meaning if at least one of the internal interrupts is asserted the external
 interrupt is asserted and only if all internal interrupts are de-asserted the
-external interrupt is de-asserted. In addition, each interrupt has a mask bit
+external interrupt is de-asserted.
-which can be used to stop the propagation of the internal interrupt to the
+
-external interrupt. If an interrupt is masked it will count towards the external
+In addition, each interrupt has a mask bit which can be used to stop the propagation
-interrupt state as if it were not asserted.
+of the internal interrupt to the external interrupt.
-The mask bits can be modified by writing to the IRQ_MASK register.
+If an interrupt is masked it will count towards the external interrupt state as if
-The raw interrupt status can be read from the IRQ_SOURCE register and the
+it were not asserted.
-combined state of the IRQ_MASK and raw interrupt state can be read from the
+
-IRQ_PENDING register.
+The mask bits can be modified by writing to the ``IRQ_MASK`` register.
+The raw interrupt status can be read from the ``IRQ_SOURCE`` register and the
+combined state of the ``IRQ_MASK`` and raw interrupt state can be read from the
+``IRQ_PENDING`` register:
 
 .. code::
 
@@ -176,7 +182,8 @@ FIFO Threshold Interrupts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The FIFO threshold interrupts can be used by software for flow control of the
-command, SDI and SDO streams.
+command, ``SDI`` and ``SDO`` streams.
+
 If an application wants to send more data than what fits into the FIFO can write
 samples into the FIFO until it is full then suspend operation wait for the almost
 empty interrupt and continue writing data to the FIFO.
@@ -191,10 +198,10 @@ watermark.
 SYNC_EVENT Interrupt
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The SYNC_EVENT interrupt is asserted when a new sync event is received from the
+The ``SYNC_EVENT`` interrupt is asserted when a new sync event is received from
-sync stream.
+the sync stream.
-An application that generated a SYNC instruction on the command stream can use
+An application that generated a ``SYNC`` instruction on the command stream can
-this interrupt to be notified when the sync instruction has been completed.
+use this interrupt to be notified when the sync instruction has been completed.
-To de-assert, the SYNC_EVENT interrupt the reception of the interrupt needs to
+
-be acknowledged by the application by writing a 1 to the SYNC_EVENT bit in the
+To de-assert the ``SYNC_EVENT`` interrupt, the application needs to acknowledge its
-IRQ_PENDING register.
+reception by writing 1 to the ``SYNC_EVENT`` bit in the ``IRQ_PENDING`` register.

docs/user_guide/build_hdl.rst

@@ -532,53 +532,37 @@ inside its sub-folders. What this means is that if you run ``make`` inside
 **hdl/projects/daq2**, it builds all the carriers (**kc705**, **a10soc**,
 **kcu105**, **zc706** to **zcu102**) instead of just the target carrier.
 
-The following 'targets' are supported.
+The following targets/arguments are supported:
 
-+------------------+--------------------------------------------------+
+* ``all``:
-| argument         | description                                      |
+  This builds everything in the current folder and its sub-folders, for example:
-+==================+==================================================+
+
-| all              | This builds everything in the current folder and |
+  * ``make -C library/axi_ad9122 all; # build AD9122 library component (AMD only).``
-|                  | its sub-folders, see context examples below.     |
+  * ``make -C library all; # build ALL library components inside 'library' (AMD only).``
-+------------------+--------------------------------------------------+
+  * ``make -C projects/daq2/zc706 all; # build DAQ2_ZC706 (AMD) project.``
-|                  | make -C library/axi_ad9122 all; ## build AD9122  |
+  * ``make -C projects/daq2/a10soc all; # build DAQ2_A10SOC (Intel) project.``
-|                  | library component (AMD only).                    |
+  * ``make -C projects/daq2 all; # build DAQ2 ALL carrier (Intel & AMD) projects.``
-+------------------+--------------------------------------------------+
+  * ``make -C projects all; # build ALL projects (not recommended).``
-|                  | make -C library all; ## build **ALL** library    |
+* ``clean``:
-|                  | components inside 'library' (AMD only).          |
+  Removes all tool and temporary files in the current folder and its
-+------------------+--------------------------------------------------+
+  sub-folders, same context as above.
-|                  | make -C projects/daq2/zc706 all; ## build        |
+* ``clean-all``:
-|                  | DAQ2_ZC706 (AMD) project.                        |
+  This removes all tool and temporary files in the current folder, its
-+------------------+--------------------------------------------------+
+  sub-folders and from all the IPs that are specified in the Makefile file;
-|                  | make -C projects/daq2/a10soc all; ## build       |
+  same context as above.
-|                  | DAQ2_A10SOC(Intel) project.                      |
+* ``lib``: This is same as ``all`` in the library folder, ignored inside project
-+------------------+--------------------------------------------------+
+  folders.
-|                  | make -C projects/daq2 all; ## build DAQ2 **ALL** |
+* ``projects.platform``: This is a special target available only in the 'hdl' root
-|                  | carrier (including Intel & AMD) projects.        |
+  folder and is ignored everywhere else, see syntax:
-+------------------+--------------------------------------------------+
+
-|                  | make -C projects all; ## build **ALL** projects  |
+  * ``make daq2.a10soc ; # build projects/daq2/a10soc.``
-|                  | (something you really should NOT do).            |
+  * ``make daq2.zc706 ; # build projects/daq2/zc706.``
-+------------------+--------------------------------------------------+
+
-| clean            | This removes all tool and temporary files in the |
+To speed up the building process, especially libraries, you can use the ``-j``
-|                  | current folder and its sub-folders, same context |
+option to run the targets in parallel, e.g. ``make -j4``.
-|                  | as above.                                        |
+
-+------------------+--------------------------------------------------+
+All artifacts generated by the build process should be "git"-ignored,
-| clean-all        | This removes all tool and temporary files in the |
+e.g. ``component.xml`` and ``.lock`` files.
-|                  | current folder, its sub-folders and from all the |
-|                  | IPs that are specified in the Makefile file;     |
-|                  | same context as above.                           |
-+------------------+--------------------------------------------------+
-| lib              | This is same as 'all' in the library folder,     |
-|                  | ignored inside project folders.                  |
-+------------------+--------------------------------------------------+
-| project.platform | This is a special target available only in the   |
-|                  | 'hdl' root folder and is ignored everywhere      |
-|                  | else, see syntax below.                          |
-+------------------+--------------------------------------------------+
-|                  | make daq2.a10soc ; ## build                      |
-|                  | projects/daq2/a10soc.                            |
-+------------------+--------------------------------------------------+
-|                  | make daq2.zc706 ; ## build projects/daq2/zc706.  |
-+------------------+--------------------------------------------------+
 
 Tools and their versions
 -------------------------------------------------------------------------------