Updated documnetation for all sections of the chipflow.toml

Author: lanserge

docs/chipflow-toml-guide.rst

@@ -28,13 +28,31 @@ 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 <``module instance name``>="`\<module class path\>`_".
+
+_`\<module class path\>`
+========================
+
+The module class path offers a similar way to locate Python objects as entry points.
+It consists of a module's `qualified name`_ followed by a colon (:) and then the `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`_.
 
 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 `\<module class path\>`_ :
 
 .. code-block:: TOML
 
@@ -44,7 +62,7 @@ and add the following to your `chipflow.toml`, with the appropriate Python `qual
 
 You probably won't need to change these if you're starting from an example repository.
 
-.. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib]
+.. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib
 .. _qualified name: https://docs.python.org/3/glossary.html#term-qualified-name
 
 
@@ -57,7 +75,7 @@ You probably won't need to change these if you're starting from an example repos
    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 `type`_ equal to ``clock``.
+These pads need to be specified in the `[silicon.pads]`_ section with the `type`_ set to ``clock``.
 The ``default`` clock domain is associated with the Amaranth ``sync`` clock domain.
 Currently, only one ``default`` clock domain is supported.
 
@@ -71,7 +89,7 @@ Currently, only one ``default`` clock domain is supported.
    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 `type`_ equal to ``reset``.
+These pads need to be specified in the `[silicon.pads]`_ section with the `type`_ set to ``reset``.
 The logic that synchronizes the reset signal with the clock will be generated automatically.
 
 ``[chipflow.silicon]``
@@ -145,14 +163,6 @@ clock
 reset
    External reset input.
 
-i
-   Input.
-
-o
-   Output.
-
-io
-   Both input and output.
 
 _`loc`
 ------
@@ -162,7 +172,9 @@ This is the physical location of the pad on your chosen pad ring. How these are
 silicon.power
 =============
 
-This section describes how the pads should be connected to the power available on the chosen process and package.
+This section outlines the connection of pads to the power supply available for the selected process and package.
+These pads are declared with the ``type`` and `loc`_ parameters, similar to the `[silicon.pads]`_ section.
+Note that in this context, the ``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.