diff --git a/boards/beaglev/fire/gateware/gateware-design-intro.rst b/boards/beaglev/fire/gateware/gateware-design-intro.rst new file mode 100644 index 0000000000000000000000000000000000000000..05a3e3e30257061db6f00eccbecbf625cdb0a4f1 --- /dev/null +++ b/boards/beaglev/fire/gateware/gateware-design-intro.rst @@ -0,0 +1,80 @@ +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. + + + + + diff --git a/boards/beaglev/fire/gateware/gateware-howto-find-out-whats-on-the-board.rst b/boards/beaglev/fire/gateware/gateware-howto-find-out-whats-on-the-board.rst new file mode 100644 index 0000000000000000000000000000000000000000..f026c3f78caa48c40e69f29b7b68cb8cf8cc6dfb --- /dev/null +++ b/boards/beaglev/fire/gateware/gateware-howto-find-out-whats-on-the-board.rst @@ -0,0 +1,54 @@ +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. diff --git a/boards/beaglev/fire/gateware/media/Gateware-Flow-bitstream-builder-full-picture.png b/boards/beaglev/fire/gateware/media/Gateware-Flow-bitstream-builder-full-picture.png new file mode 100644 index 0000000000000000000000000000000000000000..7d37d3d8d7cb97d37cbe908ac39f4fae7c068d55 Binary files /dev/null and b/boards/beaglev/fire/gateware/media/Gateware-Flow-bitstream-builder-full-picture.png differ diff --git a/boards/beaglev/fire/gateware/media/Gateware-Flow-simplified-overview.png b/boards/beaglev/fire/gateware/media/Gateware-Flow-simplified-overview.png new file mode 100644 index 0000000000000000000000000000000000000000..b9d513bf5957f258ea7232558409e74672f48181 Binary files /dev/null and b/boards/beaglev/fire/gateware/media/Gateware-Flow-simplified-overview.png differ diff --git a/boards/beaglev/fire/gateware/media/dts-design-info.png b/boards/beaglev/fire/gateware/media/dts-design-info.png new file mode 100644 index 0000000000000000000000000000000000000000..a97eb3351c3dc6496f99821f4da5bd0128e50b91 Binary files /dev/null and b/boards/beaglev/fire/gateware/media/dts-design-info.png differ diff --git a/boards/beaglev/fire/gateware/media/dts-design-version.png b/boards/beaglev/fire/gateware/media/dts-design-version.png new file mode 100644 index 0000000000000000000000000000000000000000..a848d98bf719372ae1a1e9e7dceee8026b88e038 Binary files /dev/null and b/boards/beaglev/fire/gateware/media/dts-design-version.png differ diff --git a/boards/beaglev/fire/gateware/media/hss-design-info.png b/boards/beaglev/fire/gateware/media/hss-design-info.png new file mode 100644 index 0000000000000000000000000000000000000000..723a8f4b15f708c30e601defa56748c48c375cd6 Binary files /dev/null and b/boards/beaglev/fire/gateware/media/hss-design-info.png differ