diff --git a/docs/chipflow-toml-guide.rst b/docs/chipflow-toml-guide.rst index 255569a1..15534832 100644 --- a/docs/chipflow-toml-guide.rst +++ b/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 ` = `. + +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 ` :ref:`clock domain `. +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/ + + diff --git a/docs/conf.py b/docs/conf.py index 14e581d2..50de5314 100644 --- a/docs/conf.py +++ b/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)