From 136079b40d6bdd26f576ad4d6eadaaa8bf0ed791 Mon Sep 17 00:00:00 2001
From: Deepak Khatri <lorforlinux@beagleboard.org>
Date: Thu, 21 Dec 2023 00:29:59 +0530
Subject: [PATCH] Fix callout warnings and other syntax warnings
---
.../customize-cape-gateware-verilog.rst | 78 +++++++++----------
1 file changed, 39 insertions(+), 39 deletions(-)
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 210413cc..c0bc93a6 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,18 +30,18 @@ Fork BeagleV-Fire Gateware Repository
Navigate to BeagleV-Fire's `gateware source code repository <https://git.beagleboard.org/beaglev-fire/gateware>`_.
-Click on the **Forks** button on the top-right corner.
+Click on the ``Forks`` button on the top-right corner.
.. figure:: media/gateware-beaglev-fire-fork.png
:align: center
:width: 1040
- :alt: BeagleV-Fire gateware repo fork bytton
+ :alt: BeagleV-Fire gateware repo fork button
- BeagleV-Fire gateware repo fork bytton
+ BeagleV-Fire gateware repo fork button
On the Fork Project page, select your namespace and adjust the project name to help you manage multiple
-custom gateware (e.g. my-lovely-gateware). Click the **Fork project** button.
+custom gateware (e.g. ``my-lovely-gateware``). Click the ``Fork project`` button.
.. figure:: media/verilog-gateware-fork.png
:align: center
@@ -55,9 +55,9 @@ Clone the forked repository
.. code-block:: shell
- git clone git@git.beagleboard.org:<MY-NAMESPACE>>/my-lovely-gateware.git
+ git clone git@git.beagleboard.org:<MY-NAMESPACE>/my-lovely-gateware.git
-Where **<MY-NAMESPACE>** is your Gitlab user space/user name.
+Where ``<MY-NAMESPACE>`` is your Gitlab username or userspace.
Create A Custom Gateware Build Option
**************************************
@@ -65,11 +65,11 @@ Create A Custom Gateware Build Option
BeagleV-Fire's gateware build system uses "build configuration" YAML files to describe the combination
of gateware components options that will be used to build the gateware programming bitstream. You need
to create one such file to describe to the gateware build system that you want your own custom gateware
-to be built. You need to have one such file describing your gateware in directory **custom-fpga-design**.
+to be built. You need to have one such file describing your gateware in directory ``custom-fpga-design``.
-Let's modify the **./custom-fpga-design/my_custom_fpga_design.yaml** build configuration file to
+Let's modify the ``./custom-fpga-design/my_custom_fpga_design.yaml`` build configuration file to
specify that your custom cape gateware should be included in the gateware bitstream. In this instance will
-call our custom cape gateware MY_LOVELY_CAPE.
+call our custom cape gateware ``MY_LOVELY_CAPE``.
.. callout::
@@ -89,7 +89,8 @@ call our custom cape gateware MY_LOVELY_CAPE.
<1> On the gateware build-args line, replace VERILOG_TUTORIAL with MY_LOVELY_CAPE.
-.. note:: The **custom-fpga-design** directory has a special meaning for the Beagleboard Gitlab CI system.
+.. note::
+ The **custom-fpga-design** directory has a special meaning for the Beagleboard Gitlab CI system.
Any build configuration found in this directory will be built by the CI system. This allows generating
FPGA programming bitstreams without the requirement for having the Microchip FPGA toolchain installed
on your computer.
@@ -130,16 +131,16 @@ Move to your custom gateware source directory
cd MY_LOVELY_CAPE
-You will need to first edit the ADD_CAPE.tcl TCL script to use your source code within your custom
+You will need to first edit the ``ADD_CAPE.tcl`` TCL script to use your source code within your custom
gateware directory and not the Verilog template source code. In this example this means using source
-code within the MY_LOVELY_CAPE directory rather the VERILOG_TEMPLATE directory.
+code within the ``MY_LOVELY_CAPE`` directory rather the VERILOG_TEMPLATE directory.
Edit ADD_CAPE.tcl
==================
-Replace VERILOG_TEMPLATE with MY_LOVELY_CAPE in file ADD_CAPE.tcl.
+Replace ``VERILOG_TEMPLATE`` with ``MY_LOVELY_CAPE`` in file ``ADD_CAPE.tcl``.
-.. code-block:: verilog
+.. code-block:: tcl
#-------------------------------------------------------------------------------
# Import HDL source files
@@ -155,12 +156,12 @@ Add the path to your additional Verilog source code files.
.. callout::
- .. code-block:: text
+ .. code-block:: tcl
#-------------------------------------------------------------------------------
# Import HDL source files
#-------------------------------------------------------------------------------
- import_files -hdl_source {script_support/components/CAPE/MY_LOVELY_CAPE/HDL/blinky.v} # <1>
+ import_files -hdl_source {script_support/components/CAPE/MY_LOVELY_CAPE/HDL/blinky.v} // <1>
import_files -hdl_source {script_support/components/CAPE/MY_LOVELY_CAPE/HDL/apb_ctrl_status.v}
import_files -hdl_source {script_support/components/CAPE/MY_LOVELY_CAPE/HDL/P8_IOPADS.v}
import_files -hdl_source {script_support/components/CAPE/MY_LOVELY_CAPE/HDL/P9_11_18_IOPADS.v}
@@ -172,14 +173,14 @@ Add the path to your additional Verilog source code files.
<1> In our case we will be adding a new Verilog source file called blinky.v.
-You will only need to revisit the content of ADD_CAPE.tcl if you want to add more Verilog source files
+You will only need to revisit the content of ``ADD_CAPE.tcl`` if you want to add more Verilog source files
or want to modify how the cape interfaces with the rest of the gateware (RISC-V processor subsystem,
clock and reset blocks).
Customize The Cape's Verilog source code
=========================================
-We will add a simple Verilog source file, blinky.v, in the MY_LOVELY_CAPE directory. Code below:
+We will add a simple Verilog source file, ``blinky.v``, in the ``MY_LOVELY_CAPE`` directory. Code below:
.. code-block:: verilog
@@ -208,13 +209,13 @@ We will add a simple Verilog source file, blinky.v, in the MY_LOVELY_CAPE direct
end
endmodule
-Let's connect the blinky Verilog module within the cape by editing the CAPE.v file.
+Let's connect the blinky Verilog module within the cape by editing the ``CAPE.v`` file.
Add the instantiation of the blinky module:
.. callout::
- .. code-block:: text
+ .. code-block:: devicetree
//--------P9_41_42_IOPADS
P9_41_42_IOPADS P9_41_42_IOPADS_0(
@@ -229,10 +230,10 @@ Add the instantiation of the blinky module:
);
//--------blinky
- blinky blinky_0( # <1>
- .clk ( PCLK ), # <2>
- .resetn ( PRESETN ), # <3>
- .blink ( BLINK ) # <4>
+ blinky blinky_0( // <1>
+ .clk ( PCLK ), // <2>
+ .resetn ( PRESETN ), // <3>
+ .blink ( BLINK ) // <4>
);
endmodule
@@ -251,11 +252,11 @@ Add the BLINK wire:
.. callout::
- .. code-block:: text
+ .. code-block:: verilog
wire PCLK;
wire PRESETN;
- wire BLINK; # <1>
+ wire BLINK; // <1>
wire [31:0] APB_SLAVE_PRDATA_net_0;
wire [27:0] GPIO_IN_net_1;
@@ -285,13 +286,13 @@ We are going to hijack the 6th I/O with our blinky's output:
.. callout::
- .. code-block:: text
+ .. code-block:: verilog
//--------------------------------------------------------------------
// Concatenation assignments
//--------------------------------------------------------------------
- assign GPIO_OE_net_0 = { 16'h0000, GPIO_OE[27:6], 1'b1, GPIO_OE[4:0] }; # <1>
- assign GPIO_OUT_net_0 = { 16'h0000 , GPIO_OUT[27:6], BLINK, GPIO_OUT[4:0] }; # <2>
+ assign GPIO_OE_net_0 = { 16'h0000, GPIO_OE[27:6], 1'b1, GPIO_OE[4:0] }; // <1>
+ assign GPIO_OUT_net_0 = { 16'h0000 , GPIO_OUT[27:6], BLINK, GPIO_OUT[4:0] }; // <2>
.. annotations::
@@ -309,14 +310,14 @@ programmed on your BeagleV-Fire.
.. callout::
- .. code-block:: text
+ .. code-block:: devicetree
/dts-v1/;
/plugin/;
&{/chosen} {
overlays {
- MY-LOVELY-CAPE-GATEWARE = "GATEWARE_GIT_VERSION"; # <1>
+ MY-LOVELY-CAPE-GATEWARE = "GATEWARE_GIT_VERSION"; // <1>
};
};
@@ -324,7 +325,7 @@ programmed on your BeagleV-Fire.
<1> Replace VERILOG-CAPE-GATEWARE with MY-LOVELY-CAPE-GATEWARE.
-This change will result in MY-LOVELY-CAPE-GATEWARE being visible in /proc/device-tree/chosen/overlays
+This change will result in ``MY-LOVELY-CAPE-GATEWARE`` being visible in ``/proc/device-tree/chosen/overlays``
at run-time, allowing to check that my lovely gateware is successfully programmed on BeagleV-Fire.
@@ -333,13 +334,13 @@ Commit And Push Changes To Your Forked Repository
Move back up to the root directory of your gateware project. This is the my-lovely-gateware directory in our current example.
-Add the my-lovely-gateware/sources/FPGA-design/script_support/components/CAPE/MY_LOVELY_CAPE directory content to your git repository.
+Add the ``my-lovely-gateware/sources/FPGA-design/script_support/components/CAPE/MY_LOVELY_CAPE`` directory content to your git repository.
.. code:: shell
git add sources/FPGA-design/script_support/components/CAPE/MY_LOVELY_CAPE/
-Commit changes to my-lovely-gateware/custom-fpga-design/my_custom_fpga_design.yaml
+Commit changes to ``my-lovely-gateware/custom-fpga-design/my_custom_fpga_design.yaml``
.. code:: shell
@@ -356,7 +357,7 @@ Retrieve The Forked Repositories Artifacts
*******************************************
Navigate to your forked repository. Click Pipelines in the left pane then the Download Artifacts
-button on the right handside. Select build-job:archive. This will result in an artifacts.zip file
+button on the right handside. Select ``build-job:archive``. This will result in an ``artifacts.zip`` file
being downloaded.
.. figure:: media/gateware-pipeline.png
@@ -369,14 +370,14 @@ being downloaded.
Program BeagleV-Fire With Your Custom Bitstream
************************************************
-Unzip the downloaded artifacts.zip file. Go to the gateware-builds-tester/artifacts/bitstreams directory:
+Unzip the downloaded ``artifacts.zip`` file. Go to the ``gateware-builds-tester/artifacts/bitstreams`` directory:
.. code:: shell
cd gateware-builds-tester/artifacts/bitstreams
On your Linux host development computer, use the scp command to copy the bitstream to BeagleV-Fire
-home directory, replacing <IP_ADDRESS> with the IP address of your BeagleV-Fire.
+home directory, replacing ``<IP_ADDRESS>`` with the IP address of your BeagleV-Fire.
.. code:: shell
@@ -386,8 +387,7 @@ On BeagleV-Fire, initiate the reprogramming of the FPGA with your gateware bitst
.. code:: shell
- sudo su
- /usr/share/beagleboard/gateware/changes-gateware.sh ./my_custom_fpga_design
+ sudo /usr/share/beagleboard/gateware/changes-gateware.sh ./my_custom_fpga_design
Wait for a couple of minutes for the BeagleV-Fire to reprogram itself.
--
GitLab