diff --git a/.circleci/config.yml b/.circleci/config.yml index dfadcba6..dc018859 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -145,6 +145,17 @@ jobs: name: Check that the tutorial-setup patches apply command: | scripts/tutorial-setup.sh + documentation-check: + executor: main-env + steps: + - checkout + - run: + name: Check that documentation builds with no warnings/errors + command: | + sudo apt-get update -y + sudo apt-get install -y python3-pip + sudo pip3 install -r docs/requirements.txt + make -C docs html install-riscv-toolchain: executor: main-env @@ -357,6 +368,9 @@ workflows: # Attempt to apply the tutorial patches - tutorial-setup-check + # Check that documentation builds + - documentation-check + # Build extra tests - build-extra-tests: requires: diff --git a/docs/Generators/IceNet.rst b/docs/Generators/IceNet.rst index a8595038..f7daa71e 100644 --- a/docs/Generators/IceNet.rst +++ b/docs/Generators/IceNet.rst @@ -78,7 +78,7 @@ Configuration To add IceNIC to your design, add ``HasPeripheryIceNIC`` to your lazy module and ``HasPeripheryIceNICModuleImp`` to the module implementation. If you are confused about the distinction between lazy module and module -implementation, refer to :ref:`Cake Pattern`. +implementation, refer to :ref:`Cake Pattern / Mixin`. Then add the ``WithIceNIC`` config fragment to your configuration. This will define ``NICKey``, which IceNIC uses to determine its parameters. The config fragment diff --git a/docs/Makefile b/docs/Makefile index fe9f0963..a6e1b4fd 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,8 +2,8 @@ # # You can set these variables from the command line. -SPHINXOPTS = -w warnings.txt -SPHINXBUILD = python -msphinx +SPHINXOPTS = -w warnings.txt -n -W +SPHINXBUILD = python3 -msphinx SPHINXPROJ = Chipyard SOURCEDIR = . BUILDDIR = _build diff --git a/docs/TileLink-Diplomacy-Reference/Widgets.rst b/docs/TileLink-Diplomacy-Reference/Widgets.rst index 41fc033b..7eba871b 100644 --- a/docs/TileLink-Diplomacy-Reference/Widgets.rst +++ b/docs/TileLink-Diplomacy-Reference/Widgets.rst @@ -169,7 +169,7 @@ transactions. - ``minSize: Int`` - Minimum size of transfers supported by all outward managers. - ``maxSize: Int`` - Maximum size of transfers supported after the Fragmenter is applied. - ``alwaysMin: Boolean`` - (optional) Fragment all requests down to minSize (else fragment to maximum supported by manager). (default: false) - - ``earlyAck: EarlyAck.T`` - (optional) Should a multibeat Put be acknowledged on the first beat or last beat? + - ``earlyAck: EarlyAck.T`` - (optional) Should a multibeat Put be acknowledged on the first beat or last beat? Possible values (default: ``EarlyAck.None``): - ``EarlyAck.AllPuts`` - always acknowledge on first beat. @@ -270,7 +270,7 @@ the client to see a particular width. **Example Usage:** -.. code-block:: +.. code-block:: scala // Assume the manager node sets beatBytes to 8 // With WidthWidget, client sees beatBytes of 4 @@ -398,11 +398,11 @@ package, not the ``freechips.rocketchip.tilelink`` package like the others. - ``size: Int`` - The size of the memory in bytes - ``contentsDelayed: => Seq[Byte]`` - A function which, when called generates the byte contents of the ROM. - - ``executable: Boolean`` - (optional) Specify whether the CPU can fetch + - ``executable: Boolean`` - (optional) Specify whether the CPU can fetch instructions from the ROM (default: ``true``). - - ``beatBytes: Int`` - (optional) The width of the interface in bytes. + - ``beatBytes: Int`` - (optional) The width of the interface in bytes. (default: 4). - - ``resources: Seq[Resource]`` - (optional) Sequence of resources to add to + - ``resources: Seq[Resource]`` - (optional) Sequence of resources to add to the device tree. **Example Usage:** @@ -429,13 +429,13 @@ The TLRAM and AXI4RAM widgets provide read-write memories implemented as SRAMs. **Arguments:** - ``address: AddressSet`` - The address range that this RAM will cover. - - ``cacheable: Boolean`` - (optional) Can the contents of this RAM be cached. + - ``cacheable: Boolean`` - (optional) Can the contents of this RAM be cached. (default: ``true``) - - ``executable: Boolean`` - (optional) Can the contents of this RAM be fetched + - ``executable: Boolean`` - (optional) Can the contents of this RAM be fetched as instructions. (default: ``true``) - - ``beatBytes: Int`` - (optional) Width of the TL/AXI4 interface in bytes. + - ``beatBytes: Int`` - (optional) Width of the TL/AXI4 interface in bytes. (default: 4) - - ``atomics: Boolean`` - (optional, TileLink only) Does the RAM support + - ``atomics: Boolean`` - (optional, TileLink only) Does the RAM support atomic operations? (default: ``false``) **Example Usage:** diff --git a/docs/Tools/Barstools.rst b/docs/Tools/Barstools.rst index 34562227..9089c947 100644 --- a/docs/Tools/Barstools.rst +++ b/docs/Tools/Barstools.rst @@ -131,5 +131,5 @@ This, unfortunately, breaks the process-agnostic RTL abstraction, so it is recom The simplest way to do this is to have a config fragment that when included updates instantiates the IO cells and connects them in the test harness. When simulating chip-specific designs, it is important to include the IO cells. The IO cell behavioral models will often assert if they are connected incorrectly, which is a useful runtime check. -They also keep the IO interface at the chip and test harness boundary (see :ref:`Separating the top module from the test harness`) consistent after synthesis and place-and-route, +They also keep the IO interface at the chip and test harness boundary (see :ref:`Separating the Top module from the TestHarness module`) consistent after synthesis and place-and-route, which allows the RTL simulation test harness to be reused. diff --git a/docs/VLSI/Building-A-Chip.rst b/docs/VLSI/Building-A-Chip.rst index b684a07b..9ce283eb 100644 --- a/docs/VLSI/Building-A-Chip.rst +++ b/docs/VLSI/Building-A-Chip.rst @@ -45,8 +45,8 @@ It is possible to write this IR directly, or to generate it using simple python While we certainly look forward to having a more featureful toolkit, we have built many chips to date in this way. -Running the VLSI flow ---------------------- +Running the VLSI tool flow +-------------------------- For the full documentation on how to use the VLSI tool flow, see the `Hammer Documentation `__. For an example of how to use the VLSI in the context of Chipyard, see :ref:`ASAP7 Tutorial`.