Update tests and docs. Rename config 'pad-ring' to 'package'

Author: robtaylor

chipflow_lib/__init__.py

@@ -73,15 +73,14 @@ def _ensure_chipflow_root():
                     "type": "object",
                     "required": [
                         "process",
-                        "pad_ring",
-                        "pads",
+                        "package",
                     ],
                     "additionalProperties": False,
                     "properties": {
                         "process": {
                             "enum": ["sky130", "gf180", "customer1", "gf130bcd", "ihp_sg13g2"]
                         },
-                        "pad_ring": {
+                        "package": {
                             "enum": ["caravel", "cf20", "pga144"]
                         },
                         "pads": {"$ref": "#/$defs/pin"},

chipflow_lib/pin_lock.py

@@ -82,7 +82,7 @@ def lock_pins() -> None:
         oldlock = LockFile.model_validate_json(json_string)
 
     print(f"Locking pins: {'using pins.lock' if lockfile.exists() else ''}")
-    package_name = config["chipflow"]["silicon"]["pad_ring"]
+    package_name = config["chipflow"]["silicon"]["package"]
 
     if package_name not in PACKAGE_DEFINITIONS:
         logger.debug(f"Package '{package_name} is unknown")

chipflow_lib/steps/silicon.py

@@ -135,7 +135,7 @@ def submit(self, rtlil_path, *, dry_run=False):
             "dependency_versions": dep_versions,
             "silicon": {
                 "process": self.silicon_config["process"],
-                "pad_ring": self.silicon_config["pad_ring"],
+                "package": self.silicon_config["package"],
                 "pads": pads,
                 "power": self.silicon_config.get("power", {})
             }

docs/chipflow-toml-guide.rst

@@ -1,5 +1,5 @@
-Intro to chipflow.toml
-======================
+Intro to ``chipflow.toml``
+==========================
 
 The ``chipflow.toml`` file provides configuration for your design with the ChipFlow platform.
 
@@ -14,25 +14,55 @@ Let's start with a typical example:
    # Assert that example-chipflow.toml matches the current config schema. If 
    # this test fails, then its likely that the content in this file will need
    # to be updated.
-   from chipflow_lib.cli import _parse_config_file
+   from chipflow_lib import _parse_config_file
    _parse_config_file("docs/example-chipflow.toml")
 
-project_id
-===========
+``[chipflow]``
+--------------
 
-The ``project_id`` is set to the project ID which you can get from the ChipFlow app project page.
+.. code-block:: TOML
+
+   [chipflow]
+   project_name = "my_project"
+
+
+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.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 :ref:`SiliconStep`, add your custom functionality
+and add the following to your `chipflow.toml`, with the appropriate Python `qualified name`_ :
+
+.. code-block:: TOML
+
+   [chipflow.stepe]
+   silicon = "my_design.steps.silicon:SiliconStep"
 
-steps
-=====
 
-The ``steps`` define the Python class which will be used as an entry point to these parts of the ChipFlow process.
 You probably won't need to change these if you're starting from an example repository.
 
-silicon
-=======
+.. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib]
+.. _qualified name: https://docs.python.org/3/glossary.html#term-qualified-name
 
-The ``silicon`` section sets the Foundry ``process`` we are targeting for manufacturing, and the physical ``pad_ring`` we want to place our design inside.
-You'll choose the ``process`` and ``pad_ring`` based in the requirements of your design. 
+
+``[chipflow.clocks]``
+---------------------
+
+``[chipflow.silicon]``
+----------------------
+
+.. code-block:: TOML
+
+   [chipflow.silicon]
+   process = "ihp_sg13g2"
+   package = "pga144"
+
+
+The ``silicon`` section sets the Foundry ``process`` we are targeting for manufacturing, and the physical ``package`` we want to place our design inside.
+You'll choose the ``process`` and ``package`` based in the requirements of your design. 
 
 Available processes
 -------------------
@@ -56,12 +86,8 @@ Available pad rings
 +----------+-----------+--------------------+------------------------------------+
 | Pad ring | Pad count | Pad locations      | Notes                              |
 +==========+===========+====================+====================================+
-|| caravel || TBC      || TBC               || The `Caravel Harness`_ contains   |
-||         ||          ||                   || additional logic which wraps your |
-||         ||          ||                   || design.                           |
-||         ||          ||                   || It handles its own power pins.    |
 +----------+-----------+--------------------+------------------------------------+
-|| cf20    || 20       || ``N1`` ... ``N7`` ||                                   |
+|| cf20    || 20       || ``N1`` ... ``N7`` ||   Bare die package with 20 pins   |
 ||         ||          || ``S1`` ... ``S7`` ||                                   |
 ||         ||          || ``E1`` ... ``E3`` ||                                   |
 ||         ||          || ``W1`` ... ``W3`` ||                                   |
@@ -74,10 +100,12 @@ Available pad rings
 +----------+-----------+--------------------+------------------------------------+
 
 
+
+
 silicon.pads
 ============
 
-The ``silicon.pads`` section lists the pads we will be using. 
+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.
 
@@ -86,8 +114,8 @@ type
 
 The ``type`` for each pad can be set to one of:
 
-clk
-   External clock.
+clock
+   External clock input.
 
 i
    Input.

docs/conf.py

@@ -3,6 +3,9 @@
 
 # Add parent folder to path so we can pick up module
 import os
+import sys
+sys.path.insert(0, os.path.abspath('../../chipflow_lib'))
+
 doctest_path = [os.path.abspath('..')]
 
 # -- Project information
@@ -22,13 +25,39 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon'
 ]
 
+html_static_path = ['_static']
+html_logo = '_static/chipflow-logo.png'
+logo_only = True
+html_theme = 'sphinx_book_theme'
+
+html_sidebars = {
+    '**': [
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+    ]
+}
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
     'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+    'chipflow': ('https://docs.chipflow.io/', None),
 }
 intersphinx_disabled_domains = ['std']
 
+# Napoleon settings
+napoleon_google_docstring = True
+napoleon_numpy_docstring = 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
+
 # -- Options for EPUB output
 epub_show_urls = 'footnote'

docs/example-chipflow.toml

@@ -1,38 +1,43 @@
 [chipflow]
-project_id = 8
+project_name = "test-chip"
+
+[chipflow.top]
+soc = "my_design.design:MySoC"
 
 [chipflow.steps]
-sim = "my_design.steps.sim:MySimStep"
-board = "my_design.steps.board:MyBoardStep"
-silicon = "my_design.steps.silicon:MySiliconStep"
-software = "my_design.steps.software:MySoftwareStep"
+silicon = "chipflow_lib.steps.silicon:SiliconStep"
+
+[chipflow.clocks]
+default = 'sys_clk'
+
+[chipflow.resets]
+default = 'sys_rst_n'
 
 [chipflow.silicon]
-process = "sky130"
-pad_ring = "caravel"
+process = "gf130bcd"
+package = "pga144"
 
 [chipflow.silicon.pads]
-sys_clk   = { type = "clk", loc = "0" }
-sys_rstn  = { type = "i",   loc = "1" }
-uart_tx   = { type = "o",   loc = "2" }
-uart_rx   = { type = "i",   loc = "3" }
-flash_clk = { type = "o",   loc = "4" }
-flash_csn = { type = "o",   loc = "5" }
-flash_d0  = { type = "io",  loc = "6" }
-flash_d1  = { type = "io",  loc = "7" }
-flash_d2  = { type = "io",  loc = "8" }
-flash_d3  = { type = "io",  loc = "9" }
-gpio_0    = { type = "io",  loc = "10" }
-gpio_1    = { type = "io",  loc = "11" }
-gpio_2    = { type = "io",  loc = "12" }
-gpio_3    = { type = "io",  loc = "13" }
-gpio_4    = { type = "io",  loc = "14" }
-gpio_5    = { type = "io",  loc = "15" }
-gpio_6    = { type = "io",  loc = "16" }
-gpio_7    = { type = "io",  loc = "17" }
-btn_0     = { type = "io",  loc = "18" }
-btn_1     = { type = "io",  loc = "19" }
-jtag_tck  = { type = "i",   loc = "33" }
-jtag_tms  = { type = "i",   loc = "34" }
-jtag_tdi  = { type = "i",   loc = "35" }
-jtag_tdo  = { type = "o",   loc = "36" }
+# System
+sys_clk   = { type = "clock", loc = "114" }
+sys_rst_n = { type = "reset", loc = "115" }
+
+[chipflow.silicon.power]
+dvss0        = { type = "source", loc =   "1" }
+dvdd0        = { type = "drain", loc =   "9" }
+vss0         = { type = "source", loc =  "17" }
+vdd0         = { type = "drain", loc =  "25" }
+dvss1        = { type = "source", loc =  "33" }
+dvdd1        = { type = "drain", loc =  "41" }
+vss1         = { type = "source", loc =  "49" }
+vdd1         = { type = "drain", loc =  "57" }
+dvss2        = { type = "source", loc =  "65" }
+dvdd2        = { type = "drain", loc =  "73" }
+vss2         = { type = "source", loc =  "81" }
+vdd2         = { type = "drain", loc =  "89" }
+dvss3        = { type = "source", loc =  "97" }
+dvdd3        = { type = "drain", loc = "105" }
+vss3         = { type = "source", loc = "113" }
+vdd3         = { type = "drain", loc = "121" }
+dvss4        = { type = "source", loc = "129" }
+dvdd4        = { type = "drain", loc = "137" }

pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
     "requests>=2.30.0",
     "python-dotenv>=1.0.1",
     "pydantic>=2.10.6",
+    "sphinx-book-theme>=1.1.3",
 ]
 
 [project.scripts]
@@ -61,7 +62,7 @@ test-cov.cmd = "pytest --cov=chipflow_lib --cov-report=html"
 test.cmd = "pytest"
 test-docs.cmd = "sphinx-build -b doctest docs/ docs/_build"
 lint.cmd = "ruff check"
-document.cmd = "sphinx-build docs/ docs/_build/ -W --keep-going"
+docs.cmd = "sphinx-build docs/ docs/_build/ -W --keep-going"
 
 
 [dependency-groups]

tests/fixtures/mock.toml

@@ -5,8 +5,8 @@ project_name = "proj-name"
 silicon = "chipflow_lib.steps.silicon:SiliconStep"
 
 [chipflow.silicon]
-process = "test"
-pad_ring = "cf20"
+process = "ihp_sg13g2"
+package = "pga144"
 
 [chipflow.clocks]
 default = 'sys_clk'

tests/test_silicon_platform.py

@@ -17,7 +17,7 @@ class SiliconPlatformTestCase(unittest.TestCase):
     def setUp(self):
         os.environ["CHIPFLOW_ROOT"] = os.path.dirname(os.path.dirname(__file__))
         current_dir = os.path.dirname(__file__)
-        customer_config = f"{current_dir}/fixtures/chipflow-flexic.toml"
+        customer_config = f"{current_dir}/fixtures/mock.toml"
         with open(customer_config, "rb") as f:
             self.config = tomli.load(f)
 

tests/test_silicon_step.py

@@ -5,6 +5,7 @@
 import tomli
 import unittest
 from contextlib import redirect_stdout
+from pprint import pformat
 from unittest.mock import patch
 
 from chipflow_lib.steps.silicon import SiliconStep
@@ -43,7 +44,7 @@ def setUp(self):
     @patch('dotenv.load_dotenv')
     @patch('requests.post', side_effect=mocked_requests_post)
     def test_submit_happy_path(self, mock_requests_post, mock_dotenv):
-        customer_config = f"{current_dir}/fixtures/chipflow-flexic.toml"
+        customer_config = f"{current_dir}/fixtures/mock.toml"
         with open(customer_config, "rb") as f:
             config_dict = tomli.load(f)
 
@@ -73,10 +74,10 @@ def test_submit_happy_path(self, mock_requests_post, mock_dotenv):
             "amaranth-orchard", "amaranth-vexriscv",
         ], "We have entries for the the dependency versions"
 
+        print(pformat(config))
         assert config["silicon"] == {
-            'process': 'customer1',
-            'pad_ring':
-            'cf20',
+            'process': 'ihp130',
+            'package': 'pga144',
             'pads': {},
             'power': {
                 'vss': {'loc': 'N1'},