Add pin-lock functionality and remove providers

In order to remove the need for users to define their own SiliconStep
and pin layout.This introduces a number of mechanisms:

 - PinSignature: a mechanism for Components to label wiring that should
   be routed to pads/pins and the requriments.
 - Pin lock mechanism: addition of `pins` subcommand to `chipflow` cli
   tool. This inspects the top level components and maps the ports to
   pins, with pin behaviour defined by the package definition.
 - Package definitions - basis for package definitions in chipflow-lib
 - General purpose SiliconStep

Still remaining follow on changes are:
 - Encoding power, clock, heartbeat and jtag pin locations in package
   definitions.
 - Pin lock for FPGA boards
 - Removal of need for user to define other steps (sim, software, board,
   export verilog)

Author: robtaylor

chipflow_lib/__init__.py

@@ -1,4 +1,144 @@
-# SPDX-License-Identifier: BSD-2-Clause
+import importlib.metadata
+import jsonschema
+import os
+import sys
+import tomli
+
+__version__ = importlib.metadata.version("chipflow_lib")
+
 
 class ChipFlowError(Exception):
     pass
+
+
+def _get_cls_by_reference(reference, context):
+    module_ref, _, class_ref = reference.partition(":")
+    try:
+        module_obj = importlib.import_module(module_ref)
+    except ModuleNotFoundError as e:
+        raise ChipFlowError(f"Module `{module_ref}` referenced by {context} is not found") from e
+    try:
+        return getattr(module_obj, class_ref)
+    except AttributeError as e:
+        raise ChipFlowError(f"Module `{module_ref}` referenced by {context} does not define "
+                          f"`{class_ref}`") from e
+
+
+def _ensure_chipflow_root():
+    if "CHIPFLOW_ROOT" not in os.environ:
+        os.environ["CHIPFLOW_ROOT"] = os.getcwd()
+    if os.environ["CHIPFLOW_ROOT"] not in sys.path:
+        sys.path.append(os.environ["CHIPFLOW_ROOT"])
+    return os.environ["CHIPFLOW_ROOT"]
+
+
+# TODO: convert to pydantic, one truth of source for the schema
+config_schema = {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://chipflow.io/meta/chipflow.toml.schema.json",
+    "title": "chipflow.toml",
+    "type": "object",
+    "required": [
+        "chipflow"
+    ],
+    "properties": {
+        "chipflow": {
+            "type": "object",
+            "required": [
+                "steps",
+                "silicon"
+            ],
+            "additionalProperties": False,
+            "properties": {
+                "project_name": {
+                    "type": "string",
+                },
+                "top": {
+                    "type": "object",
+                },
+                "steps": {
+                    "type": "object",
+                },
+                "clocks": {
+                    "type": "object",
+                    "patternPropertues": {
+                        ".+": {"type": "string"}
+                    },
+                },
+                "resets": {
+                    "type": "object",
+                    "patternPropertues": {
+                        ".+": {"type": "string"}
+                    },
+                },
+                "silicon": {
+                    "type": "object",
+                    "required": [
+                        "process",
+                        "package",
+                    ],
+                    "additionalProperties": False,
+                    "properties": {
+                        "process": {
+                            "enum": ["sky130", "gf180", "customer1", "gf130bcd", "ihp_sg13g2"]
+                        },
+                        "package": {
+                            "enum": ["caravel", "cf20", "pga144"]
+                        },
+                        "pads": {"$ref": "#/$defs/pin"},
+                        "power": {"$ref": "#/$defs/pin"},
+                        "debug": {
+                            "type": "object",
+                            "properties": {
+                                "heartbeat": {"type": "boolean"}
+                            }
+                        }
+                    },
+                },
+            },
+        },
+    },
+    "$defs": {
+        "pin": {
+            "type": "object",
+            "additionalProperties": False,
+            "minProperties": 1,
+            "patternProperties": {
+                ".+": {
+                    "type": "object",
+                    "required": [
+                        "type",
+                        "loc",
+                    ],
+                    "additionalProperties": False,
+                    "properties": {
+                        "type": {
+                            "enum": ["io", "i", "o", "oe", "clock", "reset", "power", "ground"]
+                        },
+                        "loc": {
+                            "type": "string",
+                            "pattern": "^[NSWE]?[0-9]+$"
+                        },
+                    }
+                }
+            }
+        }
+    }
+}
+
+
+def _parse_config():
+    chipflow_root = _ensure_chipflow_root()
+    config_file = f"{chipflow_root}/chipflow.toml"
+    return _parse_config_file(config_file)
+
+
+def _parse_config_file(config_file):
+    with open(config_file, "rb") as f:
+        config_dict = tomli.load(f)
+
+    try:
+        jsonschema.validate(config_dict, config_schema)
+        return config_dict
+    except jsonschema.ValidationError as e:
+        raise ChipFlowError(f"Syntax error in `chipflow.toml` at `{'.'.join(e.path)}`: {e.message}")

chipflow_lib/cli.py

@@ -1,173 +1,83 @@
 # SPDX-License-Identifier: BSD-2-Clause
-
-import os
-import sys
-import inspect
-import importlib
 import argparse
-import tomli
-import jsonschema
-
-from . import ChipFlowError
-
-
-def _get_cls_by_reference(reference, context):
-    module_ref, _, class_ref = reference.partition(":")
-    try:
-        module_obj = importlib.import_module(module_ref)
-    except ModuleNotFoundError as e:
-        raise ChipFlowError(f"Module `{module_ref}` referenced by {context} is not found")
-    try:
-        return getattr(module_obj, class_ref)
-    except AttributeError as e:
-        raise ChipFlowError(f"Module `{module_ref}` referenced by {context} does not define "
-                            f"`{class_ref}`") from None
-
-
-def _ensure_chipflow_root():
-    if "CHIPFLOW_ROOT" not in os.environ:
-        os.environ["CHIPFLOW_ROOT"] = os.getcwd()
-    if os.environ["CHIPFLOW_ROOT"] not in sys.path:
-        sys.path.append(os.environ["CHIPFLOW_ROOT"])
-    return os.environ["CHIPFLOW_ROOT"]
+import inspect
+import sys
+import traceback
+import logging
 
+from pprint import pformat
 
-config_schema = {
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://chipflow.io/meta/chipflow.toml.schema.json",
-    "title": "chipflow.toml",
-    "type": "object",
-    "required": [
-        "chipflow"
-    ],
-    "properties": {
-        "chipflow": {
-            "type": "object",
-            "required": [
-                "steps",
-                "silicon"
-            ],
-            "additionalProperties": False,
-            "properties": {
-                "project_id": {
-                    "type": "integer",
-                },
-                "steps": {
-                    "type": "object",
-                },
-                "silicon": {
-                    "type": "object",
-                    "required": [
-                        "process",
-                        "pad_ring",
-                        "pads",
-                    ],
-                    "additionalProperties": False,
-                    "properties": {
-                        "process": {
-                            "enum": ["sky130", "gf180", "customer1", "gf130bcd", "ihp_sg13g2"]
-                        },
-                        "pad_ring": {
-                            "enum": ["caravel", "cf20", "pga144"]
-                        },
-                        "pads": {
-                            "type": "object",
-                            "additionalProperties": False,
-                            "minProperties": 1,
-                            "patternProperties": {
-                                ".+": {
-                                    "type": "object",
-                                    "required": [
-                                        "type",
-                                        "loc",
-                                    ],
-                                    "additionalProperties": False,
-                                    "properties": {
-                                        "type": {
-                                            "enum": ["io", "i", "o", "oe", "clk"]
-                                        },
-                                        "loc": {
-                                            "type": "string",
-                                            "pattern": "^[NSWE]?[0-9]+$"
-                                        },
-                                    }
-                                }
-                            }
-                        },
-                        "power": {
-                            "type": "object",
-                            "additionalProperties": False,
-                            "patternProperties": {
-                                ".+": {
-                                    "type": "object",
-                                    "required": [
-                                        "loc",
-                                    ],
-                                    "additionalProperties": False,
-                                    "properties": {
-                                        "loc": {
-                                            "type": "string",
-                                            "pattern": "^[NSWE]?[0-9]+$"
-                                        },
-                                    }
-                                }
-                            }
-                        },
-                    }
-                },
-            },
-        }
-    }
-}
+from . import (
+    ChipFlowError,
+    _get_cls_by_reference,
+    _parse_config,
+)
+from .pin_lock import PinCommand
 
 
-def _parse_config():
-    chipflow_root = _ensure_chipflow_root()
-    config_file = f"{chipflow_root}/chipflow.toml"
-    return _parse_config_file(config_file)
+logging.basicConfig(stream=sys.stdout, level=logging.WARNING)
 
 
-def _parse_config_file(config_file):
-    with open(config_file, "rb") as f:
-        config_dict = tomli.load(f)
-
-    try:
-        jsonschema.validate(config_dict, config_schema)
-        return config_dict
-    except jsonschema.ValidationError as e:
-        raise ChipFlowError(f"Syntax error in `chipflow.toml` at `{'.'.join(e.path)}`: {e.message}")
+class UnexpectedError(ChipFlowError):
+    pass
 
 
 def run(argv=sys.argv[1:]):
     config = _parse_config()
 
-    steps = {}
+    commands = {}
+    commands["pin"] = PinCommand(config)
+
     for step_name, step_reference in config["chipflow"]["steps"].items():
         step_cls = _get_cls_by_reference(step_reference, context=f"step `{step_name}`")
         try:
-            steps[step_name] = step_cls(config)
+            commands[step_name] = step_cls(config)
         except Exception:
             raise ChipFlowError(f"Encountered error while initializing step `{step_name}` "
-                                f"using `{step_reference}`")
-
-    parser = argparse.ArgumentParser()
-    step_argument = parser.add_subparsers(dest="step", required=True)
-    for step_name, step_cls in steps.items():
-        step_subparser = step_argument.add_parser(step_name, help=inspect.getdoc(step_cls))
+                              f"using `{step_reference}`")
+
+    parser = argparse.ArgumentParser(
+        prog="chipflow",
+        description="Command line tool for interacting with the ChipFlow platform")
+
+    parser.add_argument(
+        "--verbose", "-v",
+        dest="log_level",
+        action="append_const",
+        const=10,
+        help="increase verbosity of messages; can be supplied multiple times to increase verbosity"
+    )
+
+    command_argument = parser.add_subparsers(dest="command", required=True)
+    for command_name, command in commands.items():
+        command_subparser = command_argument.add_parser(command_name, help=inspect.getdoc(command))
         try:
-            step_cls.build_cli_parser(step_subparser)
+            command.build_cli_parser(command_subparser)
         except Exception:
             raise ChipFlowError(f"Encountered error while building CLI argument parser for "
-                                f"step `{step_name}`")
+                              f"step `{command_name}`")
 
+    # each verbose flag increases versbosity (e.g. -v -v, -vv, --verbose --verbose)
+    # cute trick using append_const and summing
     args = parser.parse_args(argv)
-    try:
-        steps[args.step].run_cli(args)
-    except ChipFlowError:
-        raise
-    except Exception:
-        raise ChipFlowError(f"Encountered error while running CLI for step `{args.step}`")
-
+    if args.log_level:
+        log_level = max(logging.DEBUG, logging.WARNING - sum(args.log_level))
+        logging.getLogger().setLevel(log_level)
 
-if __name__ == '__main__':
-    run()
+    try:
+        try:
+            commands[args.command].run_cli(args)
+        except ChipFlowError:
+            raise
+        except Exception as e:
+            # convert to ChipFlowError so all handling is same.
+            raise UnexpectedError(
+                f"Unexpected error, please report to ChipFlow:\n"
+                f"args =\n{pformat(args)}\n"
+                f"traceback =\n{''.join(traceback.format_exception(e))}"
+            ) from e
+    except ChipFlowError as e:
+        cmd = args.command
+        if hasattr(args, "action"):
+            cmd += f" {args.action}"
+        print(f"Error while executing `{cmd}`: {e}")

chipflow_lib/errors.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: BSD-2-Clause
+class ChipFlowError(Exception):
+    pass