Merge branch 'gateware-doc' into 'main'

Gateware design overview and version retrieval

See merge request beaglev-fire/docs!1

boards/beaglev/fire/gateware/gateware-design-intro.rst

+Gateware Design Introduction
+############################
+
+The PolarFire SoC device used on BeagleV-Fire is an SoC FPGA which includes a RISC-V processors
+subsystem and a PolarFire FPGA on the same die. The gateware configures the Microcprosessor
+subsystem's hardware and programs the FPGA with digital logic allowing customization of the use of
+BeagleV-Fire connectors.
+
+Gateware Architecture
+=====================
+
+The diagram below is a simplified overview of the gateware's structure.
+
+.. figure:: media/Gateware-Flow-simplified-overview.png
+    :align: center
+    :alt: BeagleV-Fire Simplified Gateware
+
+    
+The overall gateware is made-up of several blocks, some of them interchangeable. These blocks are
+all clocked and reset by another "Clock and Resets" block not showed in the diagram for clarity.
+
+Each gateware block is associated with one of BeagleV-Fire's connectors.
+
+All gateware blocks have an AMBA APB target interface for software to access control and status registers
+defined by the gateware to operate digital logic defined by the gateware block. This is the
+software's control path into the gateware block.
+
+Some gateware blocks also have an AMBA AXI target and/or source interfaces. The AXI interfaces are
+typically used to move high volume of data at high throughput in and out of DDR memory. For example,
+the M.2 gateware uses these interfaces to transfer data in and out of its PCIe root port.
+
+Cape Gateware
+-------------
+The cape gateware handles the P8 and P9 connectors signals. This is where support for specific capes is
+implemented.
+
+This is a very good place to start learning about FPGA and how to customize gateware.
+
+
+SYZYGY Gateware
+---------------
+The SYZYGY gateware handles the high-speed connector signals. This connector includes:
+ - up to three transceivers capable of 12.7Gbps communications
+ - One SGMII interface
+ - 10 high-speed I/Os
+ - Clock inputs
+
+There is a lot of fun that can be had with this interface given its high-speed capabilities.
+
+Please note that only two tranceivers can be used when the M.2 interface is enabled.
+
+MIPI-CSI Gateware
+-----------------
+The MIPI gateware handles the signals coming from the camera interface.
+
+Gateware for the MIPI-CSI interface is Work-In-Progress.
+
+
+M.2 Gateware
+------------
+The M.2 gateware implements the PCIe interface used for Wi-Fi modules. It connects the processor subsystem
+to the PCIe controller associated with the tranceivers bank.
+
+There is limited fun to have here. You either include this block or not in your bitstream.
+
+The M.2 gateware uses one of the four available 12.7 Gbps transceivers. Only two out of the three SYZYGY
+tranceivers can be used when the M.2 is included in the bitstream. This gateware needs to omited from
+the bitstream if you want to use all three 12.7Gbps transceivers on the SYZYGY high-speed connector.
+
+RISC-V Processors subsystem
+---------------------------
+The RISC-V Processors Subsystem also includes some gateware mostly dealing with exposing AMBA bus interfaces
+for the other gateware blocks to attach to. It also handles immutable aspects of the gateware related to how
+some PolarFire-SoC signals are used to connect BeagleV-Fire peripherals such as the ADC and EEPROM.
+As such the RISC-V Processors Subsystem gateware is not intended to be customized.
+
+
+
+
+

boards/beaglev/fire/gateware/gateware-howto-find-out-whats-on-the-board.rst

+How to retrieve BeagleV-Fire's gateware version
+###############################################
+
+There are two methods to find out what gateware is programmed on a board.
+
+Device Tree
+===========
+The device tree overlays contains the list of gateware blocks included in the overall gateware design.
+You can retrieve that information using the following command:
+
+.. code-block::
+
+    tree /proc/device-tree/chosen/overlays/
+
+This should give an output similar to the one below.
+
+.. figure:: media/dts-design-info.png
+    :align: center
+
+The gateware version can be retrieve by reading one of the overlay files. For example, the command:
+
+.. code-block::
+
+    cat /proc/device-tree/chosen/overlays/ROBOTICS-CAPE-GATEWARE
+
+
+should result in:
+
+.. figure:: media/dts-design-version.png
+    :align: center
+
+where the result of a "git describe" command on the gateware repository is displayed. This provides the
+most recent tag on the gateware repository followed by information about additionanl commits if some
+exist. In the example above, the gateware was created from a gateware repository hash 3e0d338 which is
+5 commits more recent than tag BVF-0.3.0.
+
+Bootloader messages
+===================
+The Hart Software Services display the gateware design name and design version retrieve from the FPGA
+at system start-up.
+
+.. figure:: media/hss-design-info.png
+    :align: center
+
+The design name is the name of the build option selected when using the bitstream-builder to generate
+the bitstream. The number at the end of the design name is the hash of the gateware repository used
+to build the bitstream.
+
+The design version is specified as part of the bitstream-builder build configuration option.
+
+Please note that design name "BVF_GATEWARE" indicates that the bitstream used to program the board was
+generated directly from the gateware repositories scripts and not the bitstream-builder. You might
+see this when customizing the gateware. Seeing "BVF_GATEWARE" as the design name should be a warning
+sign that there is a disconnect between the hardware and software on your board.