Documentation polish

docs/source/bitstream_format.rst

@@ -4,14 +4,16 @@ Bitstream Formatting
 Bitstream data is generated in this flow in multiple formats:
 
 * `FASM <https://fasm.readthedocs.io/en/latest/>`_ is the bitstream format supported within the Verilog-to-Routing flow.  This format is a plain text, human-readable format originally developed for `F4PGA <https://f4pga.org/>`_ and its predecessor projects.  The genfasm step in this flow emits bitstreams in FASM format.
-* A JSON representation of the bitstream is generated to provide a convenient intermediate representation between the FASM-formatted bitstream and the final binary bitstream.  It is generally used for internal purposes only but can be used in addition to or instead of FASM to gain insight into the organization of configuration bits on chip.  See below for details on configuration bit organization.
+* A JSON intermediate representation of the bitstream is generated to provide a convenient intermediate representation between the FASM-formatted bitstream and the final binary bitstream.  It is generally used for internal purposes only.  See below for details on configuration bit organization.
 * A binary representation of the bitstream is generated for delivery of the bitstream to other applications.  Generation of this file is referred to in the flow as bitstream finishing.
 
 Understanding the details of bitstream formatting is typically necessary only for writing software drivers to perform bitstream loading for particular FPGA chips.
 
-.. warning::
+.. note::
 
-   As of this writing, the FPGA architecture supported in this flow is supplied for demonstration purposes and does not have an associated physical chip.  The following sections outline how bitstreams are organized for educational purposes only.
+   The logik_demo eFPGA architecture supported in this flow is supplied for demonstration purposes and is not available in physical chips.
+
+The following sections outline how bitstreams are organized in a general sense without specifying the bitstream format for a particular FPGA or eFPGA architecture.
 
 Working with FASM Bitstream Data
 --------------------------------
@@ -27,16 +29,16 @@ JSON is used as the file format for storing an intermediate representation (IR)
 
 The IR organizes the bitstream into a four-dimensional on-chip address space organized by array location.  Each bit in the bitstream can thus be indexed by an X coordinate, Y coordinate, word address, and bit index in this IR.
 
-For each FPGA architecture supported by the flow, a bitstream map file is provided that maps FASM features into this address space.  The bitstream finishing step uses this bitstream map file to convert FASM to the IR.  The IR is then written out in JSON format.
+For each FPGA architecture supported by the flow, a bitstream map file is provided that maps FASM features into this address space.  The bitstream finishing step in Logik uses this bitstream map file to convert FASM to the IR.
 
-.. warning::
+.. note::
 
    Architecture bitstream map files are cached by Silicon Compiler for use within the flow and may not be easily accessible by end users.
 
 Working with Binary Bitstream Data
 ----------------------------------
 
-The binary representation of bitstream data consolidates bitstream IR described above into a ROM-style format.  The four-dimensional address space of individual is collapsed into a one-dimensional address space of bitstream words.  The mapping is as shown in the table below
+The binary representation of bitstream data consolidates the bitstream IR described above into a ROM-style format.  The four-dimensional address space of individual bits is collapsed into a one-dimensional address space of bitstream words.  The mapping is as shown in the table below
 
 +-------------------------+------------------------------+------------------------+
 | most significant bits   | next most significant bits   | least significant bits |
@@ -46,7 +48,7 @@ The binary representation of bitstream data consolidates bitstream IR described
 
 When mapped into this address space, bitstream words are ordered from lowest address value to highest address value.
 
-The binary format does not specify a word size; instead, this is dictated by the FPGA Architecture.  Words are treated as binary strings that, when read left to right, are read MSB to LSB.  The packing of bitstream words into bytes in a binary file is dictated by Python's tofile() function.  Implementations of a binary bitstream file reader should account for this so that when the bitstream is read back word ordering in this address space is preserved.
+The binary format does not specify a word size; instead, this is dictated by the FPGA/eFPGA architecture.  Words are treated as binary strings that, when read left to right, are read MSB to LSB.  The packing of bitstream words into bytes in a binary file is dictated by Python's tofile() function.  Implementations of a binary bitstream file reader should account for this so that when the bitstream is read back word ordering in this address space is preserved.
 
 To make this more concrete, consider the logik_demo architecture.  logik_demo is organized as a 37x31 array of elements.  This means that six bits are needed to represent the X coordinate and five bits are needed to represent the Y coordinate.  The number of word addresses needed at each (X,Y) coordinate in the array varies.  To make a uniform address space, the maximum required word address dictates the number of bits of word address used.  In the case of logik_demo, the maximum word address is 141, so eight bits of word address are needed.  The binary bitstream address format is thus nineteen bits wide and organized as follows:
 

docs/source/external_links.rst

@@ -1,16 +1,22 @@
 External Links for Open Source Tools
 ====================================
 
-Click "Github" to go to the project github page.  Click "Documentation" to go to the project's online documentation/home page.
+Below is a set of links to documentation for open source tools used by Logik.  For each tool, the "Github" to go to the project github page.  The "Documentation" link links to the project's online documentation/home page.  If a tool does not contain a documentation link below, please consult its Github repository README for documentation.
 
 +------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------+
 | F4PGA (FASM format authors)  | `F4PGA Github <https://github.com/chipsalliance/f4pga>`_                     | `F4PGA Documentation <https://f4pga.org/>`_                            |
 +------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------+
+| GHDL                         | `GHDL Github <https://github.com/ghdl/ghdl>`_                                | `GHDL Documentation <https://ghdl.github.io/ghdl/>`_                   |
++------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------+
 | GTKWave                      | `Gtkwave Github <https://github.com/gtkwave/gtkwave>`_                       | `Gtkwave Documentation <https://gtkwave.sourceforge.net/>`_            |
 +------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------+
-| Icarus Verilog               | `Icarus Github <https://github.com/steveicarus/iverilog>`_                   | `Icarus Documentation <http://iverilog.icarus.com/>`_                  |
+| Icarus Verilog               | `Icarus Github <https://github.com/steveicarus/iverilog>`_                   | `Icarus Documentation <https://steveicarus.github.io/iverilog/>`_      |
++------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------+
+| Silicon Compiler             | `SC Github <https://github.com/siliconcompiler/siliconcompiler>`_            | `SC Documentation <https://docs.siliconcompiler.com/en/stable>`_       |
++------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------+
+| Surelog                      | `Surelog Github <https://github.com/chipsalliance/Surelog>`_                 |                                                                        |
 +------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------+
-| Silicon Compiler             | `SC Github <https://github.com/siliconcompiler/siliconcompiler>`_            | `SC Documentation <https://docs.siliconcompiler.com>`_                 |
+| sv2v                         | `sv2v Github <https://github.com/zachjs/sv2v>`_                              |                                                                        |
 +------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------+
 | Verilator                    | `Verilator Github <https://github.com/verilator/verilator>`_                 | `Verilator Documentation <https://verilator.org/guide/latest/>`_       |
 +------------------------------+------------------------------------------------------------------------------+------------------------------------------------------------------------+

docs/source/prerequisites.rst

@@ -21,20 +21,16 @@ The following general purpose software must be installed on your system to use t
 Required EDA Software Tools
 ---------------------------
 
-+------------------------------+------------------------------------------------------------------------------------------------+
-| Silicon Compiler             | `SC Documentation <https://docs.siliconcompiler.com>`_                                         |
-+------------------------------+------------------------------------------------------------------------------------------------+
-| Surelog                      | `Surelog Documentation <https://github.com/chipsalliance/Surelog?tab=readme-ov-file#surelog>`_ |
-+------------------------------+------------------------------------------------------------------------------------------------+
-| Verilog-to-Routing (VPR)     | `VPR Documentation <https://docs.verilogtorouting.org/en/latest/>`_                            |
-+------------------------------+------------------------------------------------------------------------------------------------+
-| Yosys                        | `Yosys Documentation <https://yosyshq.readthedocs.io/en/latest/>`_                             |
-+------------------------------+------------------------------------------------------------------------------------------------+
+* Silicon Compiler
+* Surelog
+* Yosys
+* VPR
 
-For VHDL support, `GHDL <https://ghdl.github.io/ghdl/>`_ is also required.
+For VHDL support, GHDL is also required
 
-For SystemVerilog support, `sv2v <https://github.com/zachjs/sv2v?tab=readme-ov-file#sv2v-systemverilog-to-verilog>`_ is also required.
+For SystemVerilog support, sv2v is also required.
 
+For links to all EDA software Github repositories and documentation pages, please consult the :doc:`external_links`.
 
 Optional EDA Software Tools
 ---------------------------
@@ -43,14 +39,12 @@ While not required to run the RTL-to-bitstream flow, HDL simulation support is r
 
 Either of the following open-source simulators may be used for HDL simulation:
 
-+------------------------------+------------------------------------------------------------------------+
-| Icarus Verilog               | `Icarus Documentation <http://iverilog.icarus.com/>`_                  |
-+------------------------------+------------------------------------------------------------------------+
-| Verilator                    | `Verilator Documentation <https://verilator.org/guide/latest/>`_       |
-+------------------------------+------------------------------------------------------------------------+
-
+* Icarus Verilog
+* Verilator
+
 For waveform viewing, GTKWave is an available open source viewer:
 
-+------------------------------+------------------------------------------------------------------------+
-| GTKWave                      | `Gtkwave Documentation <https://gtkwave.sourceforge.net/>`_            |
-+------------------------------+------------------------------------------------------------------------+
+* GTKWave
+
+For links to all EDA software Github repositories and documentation pages, please consult the :doc:`external_links`.
+

docs/source/sc_preparation.rst

@@ -1,7 +1,7 @@
 Preparing the Silicon Compiler Run Script
 =========================================
 
-Developing a Silicon Compiler run script for RTL-to-bitstream flow execution follows the same fundamental approach as developing a script for any Silicon Compiler flow execution.  Additional resources for understanding Silicon Compiler fundamentals are available at `docs.siliconcompiler.com <https://docs.siliconcompiler.com>`_
+Developing a Silicon Compiler run script for RTL-to-bitstream flow execution follows the same fundamental approach as developing a script for any Silicon Compiler flow execution.  Additional resources for understanding Silicon Compiler fundamentals are available at `docs.siliconcompiler.com <https://docs.siliconcompiler.com/en/stable>`_
 
 For most designs, the example Silicon Compiler run scripts provided with <tool_name> can be used as templates for creating your own.  The commands used in these examples and the general method for constructing run scripts are described below.
 
@@ -17,16 +17,17 @@ Constructing a Silicon Compiler run script can be broken down into the following
 * :ref:`Set_timing_constraints`
 * :ref:`Set_pin_constraints`
 * :ref:`Add_options`
+* :ref:`Configure_remote_execution`
 * :ref:`Add_execution_calls`
 
 .. _import_modules:
 
-Import modules
+Import Modules
 --------------
 
 All Silicon Compiler run scripts are pure Python scripts that import Silicon Compiler functionality like any other Python module.  Similarly, the <tool_name> RTL-to-bitstream flow is enabled as a set of Python modules that integrate to Silicon Compiler.
 
-The minimum import requirements in a <tool_name> Silicon Compiler run script are:
+The minimum import requirements in a Logik Silicon Compiler run script are:
 
 ::
 
@@ -41,7 +42,7 @@ Additional module imports may be required depending on project-specific requirem
 Create Main Function
 --------------------
 
-Since the Silicon Compiler run script is just a Python script, executing it from the command-line requires the same infrastructure as any other Python script.  In most design flows, the most convenient way to enable this will be to simply encapsulate the script in a main() function:
+Since the Silicon Compiler run script is just a Python script, executing it from the command line requires the same infrastructure as any other Python script.  In most design flows, the most convenient way to enable this will be to simply encapsulate the script in a main() function:
 
 In Python, an executable main() function is implemented with the following code:
 
@@ -76,9 +77,11 @@ Throughout this documentation, "chip" will be used to refer to the Chip class in
 
 .. _Select_part_name:
 
-Select part name
+Select Part Name
 ----------------
 
+Silicon Compiler associates each FPGA/eFPGA architecture with a unique ID called a part name.
+
 .. note::
 
    As of this writing, the only part name that is enabled for use is "logik_demo"
@@ -116,7 +119,7 @@ An example use case for the package registry is shown below, outlining how to im
 
 .. _Import_libraries:
 
-Set input source files
+Set Input Source Files
 ----------------------
 
 All HDL source files must be added to the Silicon Compiler chip object for inclusion.  For each HDL file, include the following call in your Silicon Compiler run script
@@ -157,7 +160,7 @@ For large designs, it may be convenient to organize your HDL files into a direct
 
 .. _Set_input_source_files:
 
-Adding source files from a registered package
+Adding Source Files From a Registered Package
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 When importing IP from a package in the Silicon Compiler package registry, the same function calls are used as described above, but it is also necessary to specify the package name.  The call takes the form:
@@ -250,6 +253,16 @@ In particular, any compiler directives that are required for HDL synthesis shoul
 
    chip.add('option', 'define', <compiler_directive>)
 
+
+.. _Configure_remote_execution:
+
+Configure Remote Execution (optional)
+-------------------------------------
+
+Silicon Compiler supports job submission to remote servers.
+
+There are multiple ways to enable this execution model.  Consult `Silicon Compiler remote processing <https://docs.siliconcompiler.com/en/stable/development_guide/remote_processing.html>`_ documentation for details.
+
 .. _Add_execution_calls:
 
 Add Execution Calls