Merge branch 'main' of https://git.beagleboard.org/docs/docs.beagleboard.io

boards/beaglev/fire/02-quick-start.rst

@@ -92,5 +92,8 @@ It will be different for Mac and Windows operatig systems. To find serial port f
 Demos and Tutorials
 *******************
 
-:ref:`beaglev-fire-flashing-board`
+* :ref:`beaglev-fire-gateware-version`
+* :ref:`beaglev-fire-flashing-board`
+* :ref:`beaglev-fire-gateware-design`
+* :ref:`beaglev-fire-mchp-fpga-tools-installation-guide`
 

boards/beaglev/fire/05-demos.rst

@@ -15,4 +15,6 @@ Demos
     :maxdepth: 1
     
     demos-and-tutorials/flashing-board
-    demos-and-tutorials/mchp-fpga-tools-installation-guide
+    demos-and-tutorials/mchp-fpga-tools-installation-guide
\ No newline at end of file
+    demos-and-tutorials/gateware/index
+    demos-and-tutorials/gateware/how-to-find-out-whats-on-the-board

boards/beaglev/fire/demos-and-tutorials/flashing-board.rst

@@ -3,6 +3,12 @@
 Flashing gateware and Linux image
 ##################################
 
+.. todo::
+
+   This is the *hard* way! Special cables and FlashPros are not required when using the firmware we initially ship on the board. This tutorial should be
+   rescripted as how to _unbrick_ your board. Also, we have other work-arounds using software and GPIOs rather than FlashPros. Let's not put this in user's
+   face as *the* experience when it is far more painful than using the `change-gateware.sh` script and "hold BOOT button when applying power" solutions we've created!
+
 In this tutorial we are going to learn to flash the gateware image
 to FPGA and ``sdcard.image`` to eMMC storage.
 

boards/beaglev/fire/demos-and-tutorials/gateware/how-to-find-out-whats-on-the-board.rst

+.. _beaglev-fire-gateware-version:
+
+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.

boards/beaglev/fire/demos-and-tutorials/gateware/index.rst

+.. _beaglev-fire-gateware-design:
+
+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/demos-and-tutorials/mchp-fpga-tools-installation-guide.rst

@@ -5,6 +5,15 @@ Microchip FPGA Tools Installation Guide
 
 Instructions for installing the Microchip FPGA tools on a Ubuntu 20.04 desktop.
 
+.. important::
+
+   We will be providing instances of Libero that you can run from git.beagleboard.org's gitlab-runners such that you do not need to install the tools on
+   your local machine.
+
+.. todo::
+
+   Make sure people know about the alternative and we provide links to details on that before we send them down this process.
+
 Install Libero 2022.3
 ************************
 

boards/beaglev/fire/index.rst

@@ -3,6 +3,21 @@
 BeagleV-Fire
 ###################
 
+BeagleV®-Fire is a revolutionary SBC powered by the Microchip's PolarFire® MPFS025T RISC-V System on Chip 
+(SoC) with FPGA fabric. BeagleV®-Fire opens up new horizons for developers, tinkerers, and the open-source community to explore the vast potential 
+of RISC-V architecture and FPGA technology. It has the same P8 & P9 cape header pins as BeagleBone Black allowing you to stack your favorite BeagleBone 
+cape on top to expand it's capability. Built around the powerful and energy-efficient RISC-V instruction set architecture (ISA) along with its versatile FPGA fabric, 
+BeagleV®-Fire SBC offers unparalleled opportunities for developers, hobbyists, and researchers to explore and experiment with RISC-V technology.
+
+.. admonition:: License Terms
+
+    * This documentation is licensed under a `Creative Commons Attribution-ShareAlike 4.0 International License <http://creativecommons.org/licenses/by-sa/4.0/>`__
+    * Design materials and license can be found in the `git repository <https://git.beagleboard.org/beaglev-fire/beaglev-fire>`__
+    * Use of the boards or design materials constitutes an agreement to the :ref:`boards-terms-and-conditions`
+    * Software images and purchase links available on the `board page <https://www.beagleboard.org/boards/beaglev-fire>`__
+    * For export, emissions and other compliance, see :ref:`beaglev-fire-support`
+
+
 .. image:: media/BeagleV-Fire-hero.*
     :align: center
     :alt: BeagleV-Fire hero image
@@ -11,17 +26,6 @@ BeagleV-Fire
     This is a work in progress, for latest documentation please 
     visit https://docs.beagleboard.org/latest/
 
-.. admonition:: Contributors
-
-    This work is licensed under a `Creative Commons Attribution-ShareAlike
-    4.0 International License <http://creativecommons.org/licenses/by-sa/4.0/>`__
-
-.. note::
-    Make sure to read and accept all the terms & condition provided in the :ref:`boards-terms-and-conditions` page.
-
-    Use of either the boards or the design materials constitutes agreement to the T&C including any
-    modifications done to the hardware or software solutions provided by beagleboard.org foundation.
-
 .. only:: html
 
   .. grid:: 1 1 2 3