Chipflow toml docs

docs/chipflow-toml-guide.rst

@@ -28,29 +28,71 @@ Let's start with a typical example:
 
 The ``project_name`` is a human-readable identifier for this project. If not set, the tool and library will use the project name configured in ``pyproject.toml``.
 
+``[chipflow.top]``
+------------------
+
+.. code-block:: TOML
+
+   [chipflow.top]
+   soc = "my_design.design:MySoC"
+
+This section outlines the design modules that need to be instantiated.
+A new top module will be automatically generated, incorporating all specified modules along with their interfaces.
+Each entry follows the format `<instance name> = <module class path>`.
+
+The instance name is the name the python object will be given in your design, and the :term:`module class path`
+
+.. glossary::
+
+   module class path
+       The module class path offers a way to locate Python objects as entry points.
+       It consists of a module's :term:`qualified name` followed by a colon (:) and then the :term:`qualified name` of the class within that module.
+
 ``[chipflow.steps]``
 --------------------
 
-The ``steps`` section allows overriding or addition to the standard steps available from `chipflow_lib`_.
+The ``steps`` section allows overriding or addition to the standard steps available from `chipflow_lib`.
 
 For example, if you want to override the standard silicon preparation step, you could derive from :class:`chipflow_lib.steps.silicon.SiliconStep`, add your custom functionality
-and add the following to your `chipflow.toml`, with the appropriate Python `qualified name`_ :
+and add the following to your `chipflow.toml`, with the appropriate :term:`module class path`:
 
 .. code-block:: TOML
 
-   [chipflow.stepe]
+   [chipflow.steps]
    silicon = "my_design.steps.silicon:SiliconStep"
 
 
 You probably won't need to change these if you're starting from an example repository.
 
-.. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib]
-.. _qualified name: https://docs.python.org/3/glossary.html#term-qualified-name
+.. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib
 
 
 ``[chipflow.clocks]``
 ---------------------
 
+.. code-block:: TOML
+
+   [chipflow.clocks]
+   default = 'sys_clk'
+
+This section links the clock domains utilized in the design to specific pads.
+These pads need to be specified in the `[silicon.pads]`_ section with the :term:type set to :term:clock.
+The ``default`` clock domain is associated with the Amaranth :any:`sync <lang-domains>` :ref:`clock domain <lang-clockdomains>`.
+Currently, only one ``default`` clock domain is supported.
+
+
+``[chipflow.resets]``
+---------------------
+
+.. code-block:: TOML
+
+   [chipflow.resets]
+   default = 'sys_rst_n'
+
+This section identifies the input pads designated for reset functionality.
+These pads need to be specified in the `[silicon.pads]`_ section with the :term:type set to :term:reset.
+The logic that synchronizes the reset signal with the clock will be generated automatically.
+
 ``[chipflow.silicon]``
 ----------------------
 
@@ -61,7 +103,7 @@ You probably won't need to change these if you're starting from an example repos
    package = "pga144"
 
 
-The ``silicon`` section sets the Foundry ``process`` (i.e. PDK) that we are targeting for manufacturing, and the physical ``package`` we want to place our design inside.
+The ``silicon`` section sets the Foundry ``process`` (i.e. PDK) that we are targeting for manufacturing, and the physical ``package`` (pad ring) we want to place our design inside.
 You'll choose the ``process`` and ``package`` based in the requirements of your design.
 
 Available processes
@@ -87,11 +129,6 @@ Available pad rings
 | Pad ring | Pad count | Pad locations      | Notes                              |
 +==========+===========+====================+====================================+
 +----------+-----------+--------------------+------------------------------------+
-|| cf20    || 20       || ``N1`` ... ``N7`` ||   Bare die package with 20 pins   |
-||         ||          || ``S1`` ... ``S7`` ||                                   |
-||         ||          || ``E1`` ... ``E3`` ||                                   |
-||         ||          || ``W1`` ... ``W3`` ||                                   |
-+----------+-----------+--------------------+------------------------------------+
 | pga144   | 144       | ``1`` ... ``144``  |                                    |
 +----------+-----------+--------------------+------------------------------------+
 || TBA     ||          ||                   || If you require a different        |
@@ -100,43 +137,44 @@ Available pad rings
 +----------+-----------+--------------------+------------------------------------+
 
 
+``[silicon.pads]``
+------------------
 
+The ``silicon.pads`` section lists special pads. In general you are unlikely to need to add to this.
+Each pad specified with the name used by the design and two parameters: :term:type and :term:`loc`.
 
-silicon.pads
-============
-
-The ``silicon.pads`` section lists special pads. In general you are unlikely to need to add to this. 
-
-For each pad, there's a label which is used by our design, and what ``type`` and ``loc`` each pad should be.
+.. code-block:: TOML
 
-type
-----
+   [chipflow.silicon.pads]
+   sys_clk   = { type = "clock", loc = "114" }
+   sys_rst_n = { type = "reset", loc = "115" }
 
-The ``type`` for each pad can be set to one of:
+In the above example two pads specified, ``sys_clk`` pad for clock input and ``sys_rst_n`` for reset.
 
-clock
-   External clock input.
+.. glossary::
 
-i
-   Input.
+   loc
+       This is the physical location of the pad on your chosen pad ring. How these are indexed varies by the pad ring.
 
-o
-   Output.
+   type
+       The :term:type for each pad can be set to one of :term:clock or :term:reset.
 
-io
-   Input or output.
+   clock
+       External clock input.
 
-loc
-----
+   reset
+       External reset input.
 
-This is the physical location of the pad on your chosen pad ring. How these are indexed varies by the pad ring.
 
-silicon.power
-=============
+``[silicon.power]``
+-------------------
 
-This section describes how the pads should be connected to the power available on the chosen process.
+This section outlines the connection of pads to the power supply available for the selected process and package.
+These pads are declared with the :term:type and :term:loc parameters, similar to the `[silicon.pads]`_ section.
+Note that in this context, the :term:type parameter can only be ``ground`` or ``power``.
 
 This is a work in progress, and currently you can use the defaults provided by customer support.
 
-
 .. _Caravel Harness: https://caravel-harness.readthedocs.io/en/latest/
+
+

docs/conf.py

@@ -80,15 +80,15 @@
 # Napoleon settings
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True
+napoleon_use_ivar = True
 napoleon_include_init_with_doc = True
-napoleon_include_private_with_doc = True
 napoleon_include_special_with_doc = True
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
-napoleon_use_ivar = False
-napoleon_use_param = True
-napoleon_use_rtype = True
+napoleon_custom_sections = [
+    ("Arguments", "params_style"), # by default displays as "Parameters"
+    ("Attributes", "params_style"), # by default displays as "Variables", which is confusing
+    ("Members", "params_style"), # `amaranth.lib.wiring` signature members
+]
+
 
 rst_prolog = """
 .. role:: py(code)