diff --git a/boards/beaglev/fire/05-demos.rst b/boards/beaglev/fire/05-demos.rst
index 6c059cd81cbf0f075c23439bcf5dcf0f41b9f139..02646cbeba0f36e2537f2d5bb0f0010ea60ac41e 100644
--- a/boards/beaglev/fire/05-demos.rst
+++ b/boards/beaglev/fire/05-demos.rst
@@ -22,3 +22,4 @@ Demos
demos-and-tutorials/gateware/gateware-full-flow
demos-and-tutorials/gateware/gateware-tcl-scripts-structure
demos-and-tutorials/gateware/customize-cape-gateware-verilog
+ demos-and-tutorials/gateware/exploring-gateware-design-libero
diff --git a/boards/beaglev/fire/demos-and-tutorials/flashing-board.rst b/boards/beaglev/fire/demos-and-tutorials/flashing-board.rst
index ec0379e3bd059840df11991b6d51f83016f94b65..80dd98b9e8fd3677bc3f0410d244c247c3818552 100644
--- a/boards/beaglev/fire/demos-and-tutorials/flashing-board.rst
+++ b/boards/beaglev/fire/demos-and-tutorials/flashing-board.rst
@@ -103,8 +103,8 @@ Following the annotation in the image above:
2. Click on ``RUN`` button
3. Shows the progress
-If you see a lot of green color and progess bar says
-`PASSED`` then well done you have successfully flashed
+If you see a lot of green color and the progress bar says
+``PASSED`` then well done you have successfully flashed
the gateware image on your BeagleV-Fire board.
Flashing eMMC
@@ -127,8 +127,8 @@ in the
:align: center
:alt: BeagleV-Fire booting HSS with progress bar
-Once you see that progress bar on your screem you can start pressing any
-button (0-9/a-z) which whill stop the board from fully botting and you'll be
+Once you see that progress bar on your screen you can start pressing any
+button (0-9/a-z) which will stop the board from fully booting and you'll be
able to access Hart Software Services (HSS) prompt. BeagleV-Fire's eMMC content is
written by the Hart Software Services (HSS) using the ``usbdmsc`` command. The
HSS ``usbdmsc`` command exposes the eMMC as a USB mass storage device USB type C connector.
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/customize-cape-gateware-verilog.rst b/boards/beaglev/fire/demos-and-tutorials/gateware/customize-cape-gateware-verilog.rst
index 00112f422af6fdd572f28dca0f866e2682e9d4ac..f759122339a844eb3c06d3a75c8cae82d5c38a45 100644
--- a/boards/beaglev/fire/demos-and-tutorials/gateware/customize-cape-gateware-verilog.rst
+++ b/boards/beaglev/fire/demos-and-tutorials/gateware/customize-cape-gateware-verilog.rst
@@ -30,7 +30,7 @@ Fork BeagleV-Fire Gateware Repository
.. important::
All new users need to be manually approved to protect from BOT spam. You will not be able to fork the Gateware
- Repository until you have been approved. A request to 'the forum <https://forum.beagleboard.org/t/requesting-access-to-gitlab-to-fork-gateware/37494>'
+ Repository until you have been approved. A request to `the forum <https://forum.beagleboard.org/t/requesting-access-to-gitlab-to-fork-gateware/37494>`_
may expedite the process.
Navigate to BeagleV-Fire's `gateware source code repository <https://git.beagleboard.org/beaglev-fire/gateware>`_.
@@ -205,11 +205,11 @@ We will add a simple Verilog source file, ``blinky.v``, in the ``MY_LOVELY_CAPE`
begin
if(~resetn)
begin
- counter <= 16'h0000;
+ counter <= 23'h0;
end
else
begin
- counter <= counter + 1;
+ counter <= counter + 23'b1;
end
end
endmodule
@@ -392,7 +392,7 @@ On BeagleV-Fire, initiate the reprogramming of the FPGA with your gateware bitst
.. code:: shell
- sudo /usr/share/beagleboard/gateware/changes-gateware.sh ./my_custom_fpga_design
+ sudo /usr/share/beagleboard/gateware/change-gateware.sh ./my_custom_fpga_design
Wait for a couple of minutes for the BeagleV-Fire to reprogram itself.
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/exploring-gateware-design-libero.rst b/boards/beaglev/fire/demos-and-tutorials/gateware/exploring-gateware-design-libero.rst
new file mode 100644
index 0000000000000000000000000000000000000000..daa89c220c1c879174c1bdc1707eae524df2992e
--- /dev/null
+++ b/boards/beaglev/fire/demos-and-tutorials/gateware/exploring-gateware-design-libero.rst
@@ -0,0 +1,273 @@
+.. _beaglev-fire-exploring-gateware-design-libero:
+
+Exploring Gateware Design with Libero
+######################################
+
+In this demonstration, we'll be exploring the BeagleV-Fire gateware in the `Libero Design Suite <https://www.microchip.com/en-us/products/fpgas-and-plds/fpga-and-soc-design-tools/fpga/libero-software-later-versions>`_, making changes
+to the default gateware. This demo will serve as an introduction to the design tool, an alternative method
+for developing gateware.
+
+Prerequisites
+*************
+
+The prerequisites required for creating the libero project locally are:
+
+1. Microchip design tools: Refer to the document here for :ref:`installation instructions<beaglev-fire-mchp-fpga-tools-installation-guide>` of microchip FPGA tools.
+2. Python requirements for gateware build scripts:
+
+.. code-block:: shell
+
+ pip3 install gitpython
+ pip3 install pyyaml
+
+3. Environment variables: The following environment variables are required for compilation
+ - ``SC_INSTALL_DIR``
+ - ``FPGENPROG``
+ - ``LIBERO_INSTALL_DIR``
+ - ``LM_LICENSE_FILE``
+
+ A script is provided for setting up these variables in the :ref:`fpga tools installation <beaglev-fire-mchp-fpga-tools-installation-guide>` section. An example script for setting up the environment is available `here <https://openbeagle.org/beaglev-fire/Microchip-FPGA-Tools-Setup>`_.
+
+4. It is highly recommended to go through the :ref:`beaglev-fire-customize-cape-gateware-verilog` tutorial to understand the
+basics of the gateware structure.
+
+Cloning and Building the Gateware
+**********************************
+
+First, we must source the environment to include the microchip tools.
+
+.. code-block:: shell
+
+ source /path/to/microchip/fpga/tools/setup-microchip-tools.sh
+
+Next, we'll clone the gateware repository to get a local copy of the project.
+
+.. code-block:: shell
+
+ git clone https://openbeagle.org/beaglev-fire/gateware.git
+ cd gateware
+
+We can use the ``build-gateware`` script to generate a libero project for us, where we
+can start making our changes.
+
+.. important::
+
+ Make sure to source the microchip setup script before starting this one.
+
+
+.. code-block:: shell
+
+ python build-gateware.py ./build-options/default.yaml # exploring the default gateware
+
+
+This should start a big log stating the compilation of the project. First, the device tree
+overlays are compiled, which contain information for linux about the gateware being compiled.
+
+Next, the Hart Software Services (HSS) is compiled. This acts as a zero-stage bootloader, configuring
+the Polarfire SoC and allowing services like loading the next stage bootloader and flashing the eMMC
+of the board.
+
+Then the libero project generating is started. Here, TCL scripts inside the ``sources`` directory are
+executed, starting with ``BUILD_BVF_GATEWARE.tcl`` script. This stitches each HDL module, IP,
+hardware configuration in the gateware.
+
+Once bitstream generation is completed, the Libero project is ready to be opened. Start Libero on the
+same terminal in linux, or from the start menu in Windows, and open the project file by pressing
+``CTRL+O`` and selecting the generated project as ``gateware/work/libero/BVF_GATEWARE_025T.prjx`` .
+
+.. figure:: images/libero-project-location.png
+ :align: center
+ :width: 1040
+ :alt: Libero project location
+
+ Libero project location
+
+Exploring The Design
+********************
+
+Let the IDE load everything, and then you're all set to browse around! You can go to the
+``Design Hierarchy`` view to look at all Smart Design components. Here, all the gateware components
+are listed in block-like views. Select the ``DEFAULT_******`` option in the hierarchy to have a look
+at the whole gateware. You should also be able to see the cape, M.2 interface and the RISC-V subsystem
+modules. These modules are explained in `Gateware Introduction <beaglev-fire-gateware-design>`_.
+
+.. figure:: images/libero-gateware-overview.png
+ :align: center
+ :width: 1040
+ :alt: Libero gateware overview
+
+ Libero gateware overview
+
+Adding Custom HDL
+*****************
+
+Once you're done exploring, we can start by adding our first HDL to the design. Create a new HDL file through the
+menu bar, and name it ``blinky`` . Once created, you can find the HDL file under the ``User HDL Source Files``
+heading in the Design Hierarchy.
+
+.. figure:: images/libero-add-new-hdl.png
+ :align: center
+ :width: 1040
+ :alt: Adding new HDL
+
+ Adding new HDL
+
+Next, add this code to the file
+
+.. code-block:: verilog
+
+ `timescale 1ns/100ps
+ module blinky(
+ input clk,
+ input resetn,
+ input [27:0] gpio_out,
+ input [27:0] gpio_enable,
+ output [27:0] modified_gpio,
+ output [27:0] modified_gpio_enable
+ );
+
+ reg [22:0] counter;
+ assign modified_gpio = {gpio_out[27:6], counter[22], gpio_out[4:0]};
+ assign modified_gpio_enable = {gpio_enable[27:6], 1'b1, gpio_enable[4:0]};
+
+ always@(posedge clk or negedge resetn)
+ begin
+ if(~resetn)
+ begin
+ counter <= 23'h0;
+ end
+ else
+ begin
+ counter <= counter + 23'b1;
+ end
+ end
+ endmodule
+
+After adding it, press the ``Build Hierarchy`` button in the Design Hierarchy window to refresh it and bring the
+added HDL to the work directory. Right click on it to select the “Create Core from HDL….†option. Press No on the
+dialog that follows since we've described the ports perfectly in our HDL.
+
+.. figure:: images/libero-create-core-from-hdl.png
+ :align: center
+ :width: 1040
+ :alt: Create core from HDL
+
+ Create core from HDL
+
+Now, open the ``CAPE`` design under the ``DEFAULT_****`` smart design, to have a look at what's in the cape. Drag
+and drop the ``blinky`` file appearing in the work section into the cape design. You will have successfully instantiated
+the new verilog file into the cape smart design.
+
+.. figure:: images/libero-add-blinky-to-cape.png
+ :align: center
+ :width: 1040
+ :alt: Add blinky to cape
+
+ Add blinky to cape
+
+Making The Connections
+======================
+
+You should see the blinky module within the CAPE design, and it should be fairly obvious where we're going to be connecting
+the module if you've gone through the previous demo. First, delete the wires connecting the ``GPIO_OUT`` and ``GPIO_OE`` to
+the ``CAPE_DEFAULT_GPIOS`` module. Then, simply connect the ``GPIO_OUT`` and the ``GPIO_OE`` terminals of the cape to the
+``gpio_out`` and the ``gpio_enable`` pins respectively. Similarly connect the outputs of the blinky module to the
+``CAPE_DEFAULT_GPIOS`` module.
+
+.. figure:: images/libero-connect-blinky-to-cape.png
+ :align: center
+ :width: 1040
+ :alt: Connect blinky to cape
+
+ Connect blinky to cape
+
+Finally, connect the CLK and the RESET pins to the ``PCLK`` and the ``PRESETN`` pins below in the cape. You can use the
+compress layout button in the toolbar to make the design neat once you're done connecting the wires.
+
+Go ahead and save the CAPE file. You can also verify the design by pressing the checkmark icon in the editor toolbar.
+Now, it's time to export our design back to the gateware repository.
+
+Exporting The Design
+*********************
+
+Exporting the Cape
+==================
+
+The SmartDesigns you have changed should show an “i†icon in front of them indicating that they need to be regenerated.
+First, regenerate the designs by right clicking on them and selecting “Generate Componentâ€.
+Rebuild the Hierarchy too as we've done before.
+
+.. figure:: images/libero-regenerate-designs.png
+ :align: center
+ :width: 1040
+ :alt: Regenerate designs
+
+ Regenerate designs
+
+Next, right-click on the cape and select “Export Component Description (TCL)†to export it as a script which can be used
+in the gateware repository. I suggest creating an export directory where you can temporarily store the exported gateware
+files before getting them into the repository.
+
+Now, simply copy it into the gateware at the following path.
+
+.. code-block:: shell
+
+ cp ~/export/gateware/CAPE.tcl ~/gateware/sources/FPGA-design/script_support/components/CAPE/DEFAULT/
+
+Exporting The HDL
+=================
+
+To add new HDL to the gateware repository, first we need to copy it to the HDL directory at
+`gateware/sources/FPGA-design/script_support/HDL`. You can do that by just creating a folder named blinky inside and
+copying the HDL to it.
+
+.. code-block:: shell
+
+ mkdir ~/gateware/sources/FPGA-design/script_support/HDL/BLINKY
+ cp ~/export/gateware/blinky.v ~/gateware/sources/FPGA-design/script_support/HDL/BLINKY/
+
+Now, to add the TCL script to import this design for the CAPE scripts, we can export the script by right-clicking on the
+HDL file in the Design Hierarchy and select ``Export Component Description``.
+
+.. figure:: images/libero-export-hdl.png
+ :align: center
+ :width: 1040
+ :alt: Export HDL
+
+ Export HDL
+
+Now, copy the contents of this exported file to our gateware's HDL sourcing script at `gateware/sources/FPGA-design/script_support/hdl_source.tcl`.
+
+First, copy the contents of the exported TCL file to the bottom of the file. Replace the ``-file`` argument
+in the line with ``-file $project_dir/hdl/blinky.v``. Finally, source the file by add a line below line no. 11 as:
+
+.. code-block:: tcl
+
+ -hdl_source {script_support/HDL/AXI4_address_shim/AXI4_address_shim.v} \
+ -hdl_source {script_support/HDL/BLINKY/blinky.v} # ⓵ Source the script below line 11
+
+ #......
+ #...... towards the end of the file
+
+ hdl_core_assign_bif_signal -hdl_core_name {AXI_ADDRESS_SHIM} -bif_name {AXI4_INITIATOR} -bif_signal_name {RREADY} -core_signal_name {INITIATOR_OUT_RREADY}
+
+ create_hdl_core -file $project_dir/hdl/blinky.v -module {blinky} -library {work} -package {}
+ # ⓶ Add the core at the end of the file
+
+Verify your script as above, save it and now you're good to compile your project!
+
+Go ahead and run the python script to build the gateware and verify your changes to the gateware.
+
+.. code-block:: shell
+
+ python build-bitstream.py ./build-options/default.yaml # run this in the gateware di
+
+If at any point the compilation fails, you can debug the script at the mentioned line. If it compiles successfully, it will mention by saying:
+
+.. code-block:: text
+
+ The Execute Script command succeeded.
+ The BVF_GATEWARE_025T project was closed.
+
+Now, you can commit the changes to your gateware repository fork, download the artifacts after compilation, and program
+the gateware using the ``change_gateware.sh`` script. Have fun!
\ No newline at end of file
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/gateware-tcl-scripts-structure.rst b/boards/beaglev/fire/demos-and-tutorials/gateware/gateware-tcl-scripts-structure.rst
index 6c42f12434ddca42fd5ba54a4408b1feebe18c67..e858c6134e50fa3d4c9c03978562b0a0b8556ed2 100644
--- a/boards/beaglev/fire/demos-and-tutorials/gateware/gateware-tcl-scripts-structure.rst
+++ b/boards/beaglev/fire/demos-and-tutorials/gateware/gateware-tcl-scripts-structure.rst
@@ -70,7 +70,7 @@ The component directory contains subdirectories for:
.. figure:: images/gateware-cape-robotics-dirs.png
:align: center
-Gareware TCL Scripts
+Gateware TCL Scripts
--------------------
The component directory contains the TCL scripts executed by Libero to generate the gateware.
@@ -81,4 +81,17 @@ are typically IP configuration scripts and SmartDesign stiching scripts.
.. figure:: images/gateware-cape-robotics-files.png
:align: center
+Opening the gateware as a libero project
+========================================
+
+It can be slightly difficult to explore the gateware design through the TCL files. To inspect the
+gateware design in detail easily, you can open the gateware as a Libero project. This is done by running the
+following command in the gateware directory:
+
+.. code-block:: shell
+
+ python build-bitstream.py ./build-options/default.yaml # build option depending on the gateware
+
+You will need to have all microchip tools installed and the environment variables set up correctly. Refer
+to the `microchip tools installation guide<mchp-fpga-tools-installation-guide>`_ for information on how to install these tools.
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-add-blinky-to-cape.png b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-add-blinky-to-cape.png
new file mode 100644
index 0000000000000000000000000000000000000000..022a7a180e5d60a4265e7a6ce2562fbe4f3cd132
Binary files /dev/null and b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-add-blinky-to-cape.png differ
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-add-new-hdl.png b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-add-new-hdl.png
new file mode 100644
index 0000000000000000000000000000000000000000..72817646fa9759b9e187e92d8457e96941906f90
Binary files /dev/null and b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-add-new-hdl.png differ
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-connect-blinky-to-cape.png b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-connect-blinky-to-cape.png
new file mode 100644
index 0000000000000000000000000000000000000000..b66be042af4175ad0d676aea7a66fc32f0cae979
Binary files /dev/null and b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-connect-blinky-to-cape.png differ
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-create-core-from-hdl.png b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-create-core-from-hdl.png
new file mode 100644
index 0000000000000000000000000000000000000000..e2fca64b29a8ef0031e338ea9b6811ed5d740153
Binary files /dev/null and b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-create-core-from-hdl.png differ
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-export-hdl.png b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-export-hdl.png
new file mode 100644
index 0000000000000000000000000000000000000000..8b2f3debb2aa9116c524b56110ca41157c1f4f9a
Binary files /dev/null and b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-export-hdl.png differ
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-gateware-overview.png b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-gateware-overview.png
new file mode 100644
index 0000000000000000000000000000000000000000..8fc2894d7ba6d029cc16371d04fd761d002ebf69
Binary files /dev/null and b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-gateware-overview.png differ
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-project-location.png b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-project-location.png
new file mode 100644
index 0000000000000000000000000000000000000000..9cd50b0e95989a10faed056267e7cd857ba57a57
Binary files /dev/null and b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-project-location.png differ
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-regenerate-designs.png b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-regenerate-designs.png
new file mode 100644
index 0000000000000000000000000000000000000000..21442136db08792be190be92ac0f4a7ee1ce4cbe
Binary files /dev/null and b/boards/beaglev/fire/demos-and-tutorials/gateware/images/libero-regenerate-designs.png differ
diff --git a/boards/beaglev/fire/demos-and-tutorials/gateware/index.rst b/boards/beaglev/fire/demos-and-tutorials/gateware/index.rst
index 90bd297691112dde3b41bd3c842ed72cb9da2b49..cff1cee816f00579d2ef87f6a27d3d493824b7c4 100644
--- a/boards/beaglev/fire/demos-and-tutorials/gateware/index.rst
+++ b/boards/beaglev/fire/demos-and-tutorials/gateware/index.rst
@@ -19,7 +19,8 @@ The diagram below is a simplified overview of the gateware's structure.
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.
+all clocked and reset by another "Clock and Resets" block not showed in the diagram for clarity. A 125MHz,
+and a 160MHz clock are provided for use by the gateware blocks.
Each gateware block is associated with one of BeagleV-Fire's connectors.