From d727f99fb897090f38ed9645f8c0869c23f5c2d0 Mon Sep 17 00:00:00 2001 From: Serge Rabyking Date: Wed, 30 Apr 2025 16:29:06 +0100 Subject: [PATCH 1/3] Updates to chipflow-toml-guide.rst --- docs/chipflow-toml-guide.rst | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/chipflow-toml-guide.rst b/docs/chipflow-toml-guide.rst index 255569a1..5f3bb8ae 100644 --- a/docs/chipflow-toml-guide.rst +++ b/docs/chipflow-toml-guide.rst @@ -38,7 +38,7 @@ and add the following to your `chipflow.toml`, with the appropriate Python `qual .. code-block:: TOML - [chipflow.stepe] + [chipflow.steps] silicon = "my_design.steps.silicon:SiliconStep" @@ -80,18 +80,13 @@ Available processes | ihp_sg13g2 | pga144 | IHP SG13G2 130nm SiGe | +------------+------------+---------------------------+ -Available pad rings -------------------- +Available pad rings (``package``) +--------------------------------- +----------+-----------+--------------------+------------------------------------+ | 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 | @@ -105,9 +100,16 @@ Available pad rings silicon.pads ============ -The ``silicon.pads`` section lists special pads. In general you are unlikely to need to add to this. +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: ``type`` and ``loc``. + +.. code-block:: TOML + + [chipflow.silicon.pads] + sys_clk = { type = "clock", loc = "114" } + sys_rst_n = { type = "reset", loc = "115" } -For each pad, there's a label which is used by our design, and what ``type`` and ``loc`` each pad should be. +In the above example two pads specified, ``sys_clk`` pad for clock input and ``sys_rst_n`` for reset. type ---- @@ -117,6 +119,9 @@ The ``type`` for each pad can be set to one of: clock External clock input. +reset + External reset input. + i Input. @@ -124,7 +129,7 @@ o Output. io - Input or output. + Both input and output. loc ---- @@ -134,7 +139,7 @@ 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. +This section describes how the pads should be connected to the power available on the chosen process and package. This is a work in progress, and currently you can use the defaults provided by customer support. From 80f6396429412c8dc2b701ca9c21f206f48d2121 Mon Sep 17 00:00:00 2001 From: Serge Rabyking Date: Wed, 30 Apr 2025 23:57:02 +0100 Subject: [PATCH 2/3] Documented clocks and resets sections of the chipflow.toml --- docs/chipflow-toml-guide.rst | 41 ++++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/docs/chipflow-toml-guide.rst b/docs/chipflow-toml-guide.rst index 5f3bb8ae..8b64fd9f 100644 --- a/docs/chipflow-toml-guide.rst +++ b/docs/chipflow-toml-guide.rst @@ -51,6 +51,29 @@ You probably won't need to change these if you're starting from an example repos ``[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 `type`_ equal to ``clock``. +The ``default`` clock domain is associated with the Amaranth ``sync`` 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 `type`_ equal to ``reset``. +The logic that synchronizes the reset signal with the clock will be generated automatically. + ``[chipflow.silicon]`` ---------------------- @@ -61,7 +84,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 @@ -80,7 +103,7 @@ Available processes | ihp_sg13g2 | pga144 | IHP SG13G2 130nm SiGe | +------------+------------+---------------------------+ -Available pad rings (``package``) +Available pad rings --------------------------------- +----------+-----------+--------------------+------------------------------------+ @@ -97,11 +120,11 @@ Available pad rings (``package``) -silicon.pads -============ +_`[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: ``type`` and ``loc``. +Each pad specified with the name used by the design and two parameters: `type`_ and `loc`_. .. code-block:: TOML @@ -111,8 +134,8 @@ Each pad specified with the name used by the design and two parameters: ``type`` In the above example two pads specified, ``sys_clk`` pad for clock input and ``sys_rst_n`` for reset. -type ----- +_`type` +------- The ``type`` for each pad can be set to one of: @@ -131,8 +154,8 @@ o io Both input and output. -loc ----- +_`loc` +------ This is the physical location of the pad on your chosen pad ring. How these are indexed varies by the pad ring. From 6d1d59db79e7976aa1478ebff9ef302f7434c745 Mon Sep 17 00:00:00 2001 From: Serge Rabyking Date: Thu, 1 May 2025 18:16:29 +0100 Subject: [PATCH 3/3] Updated documnetation for all sections of the chipflow.toml --- docs/chipflow-toml-guide.rst | 82 ++++++++++++++++++++---------------- docs/conf.py | 14 +++--- 2 files changed, 53 insertions(+), 43 deletions(-) diff --git a/docs/chipflow-toml-guide.rst b/docs/chipflow-toml-guide.rst index 8b64fd9f..15534832 100644 --- a/docs/chipflow-toml-guide.rst +++ b/docs/chipflow-toml-guide.rst @@ -28,13 +28,33 @@ 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 @@ -44,8 +64,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] -.. _qualified name: https://docs.python.org/3/glossary.html#term-qualified-name +.. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib ``[chipflow.clocks]`` @@ -57,8 +76,8 @@ 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``. -The ``default`` clock domain is associated with the Amaranth ``sync`` clock domain. +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. @@ -71,7 +90,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 :term:type set to :term:reset. The logic that synchronizes the reset signal with the clock will be generated automatically. ``[chipflow.silicon]`` @@ -104,7 +123,7 @@ Available processes +------------+------------+---------------------------+ Available pad rings ---------------------------------- +------------------- +----------+-----------+--------------------+------------------------------------+ | Pad ring | Pad count | Pad locations | Notes | @@ -118,13 +137,11 @@ Available pad rings +----------+-----------+--------------------+------------------------------------+ - - -_`[silicon.pads]` -================== +``[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: `type`_ and `loc`_. +Each pad specified with the name used by the design and two parameters: :term:type and :term:`loc`. .. code-block:: TOML @@ -134,37 +151,30 @@ Each pad specified with the name used by the design and two parameters: `type`_ In the above example two pads specified, ``sys_clk`` pad for clock input and ``sys_rst_n`` for reset. -_`type` -------- - -The ``type`` for each pad can be set to one of: - -clock - External clock input. - -reset - External reset 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 - Both input and 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 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 :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)