Replace providers

.github/workflows/deploy-docs.yml

@@ -0,0 +1,30 @@
+# .github/workflows/deploy.yml
+name: Deploy
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@v4
+        with:
+          python-version: 3.12
+          cache: true
+
+      - name: Install dependencies
+        run: pdm install
+
+      - name: Build docs
+        run: pdm docs
+
+      - uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/_build
+          branch: gh-pages
+          clean-exclude: pr-preview
+          force: false

.github/workflows/main.yaml

@@ -19,7 +19,6 @@ jobs:
         uses: pdm-project/setup-pdm@v4
       - name: Install dependencies
         run: |
-          pdm lock --dev
           pdm install
       - name: Run tests
         run: |
@@ -40,48 +39,3 @@ jobs:
       - name: Check source code licenses
         run: |
           docker run --platform=linux/amd64 -v ${PWD}:/src ghcr.io/google/addlicense -v -check -l BSD-2-Clause -c "ChipFlow" -s=only -ignore **/__init__.py **/*.py
-
-  build-docs:
-    needs: test
-    runs-on: ubuntu-22.04
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Set up PDM
-        uses: pdm-project/setup-pdm@v4
-        with:
-          python-version: 3.9
-      - name: Install deps
-        run: pdm install
-      - name: Build docs
-        run: pdm run document
-      - name: Upload docs artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: docs
-          path: docs/_build
-
-  publish-docs:
-    needs: build-docs
-    if: ${{ github.repository == 'chipflow/chipflow-lib' }}
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Download docs artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: docs
-          path: docs/
-      - name: Publish "latest" docs
-        if: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/main' }}
-        uses: JamesIves/github-pages-deploy-action@releases/v4
-        with:
-          repository-name: chipflow/chipflow.github.io
-          ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
-          branch: main
-          folder: docs/
-          target-folder: chipflow-lib/latest/
-

.github/workflows/preview-docs.yml

@@ -0,0 +1,36 @@
+# .github/workflows/preview.yml
+name: Deploy PR previews
+concurrency: preview-${{ github.ref }}
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@v4
+        with:
+          python-version: 3.12
+          cache: true
+
+      - name: Install dependencies
+        run: pdm install
+
+      - name: Build docs
+        run: pdm docs
+        if: github.event.action != 'closed'
+
+      - uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: docs/_build
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview
+          action: auto
+          pages-base-url: chipflow-lib.docs.chipflow-infra.com

.gitignore

@@ -2,13 +2,14 @@
 __pycache__/
 *.egg-info
 /dist
+/log*
 
 # pdm
 /.pdm-plugins
 /.pdm-python
 /.pdm-build
 /.venv
-/pdm.lock
+/.coverage
 
 # pytest
 /.pytest_cache

README.md

@@ -1,14 +1,12 @@
 # ChipFlow library
 
-WIP
-
+This is a small library to make working with the ChipFlow platform easy and straightforward.
 
 ## Installation and usage
 
 This library uses [PDM](https://pdm.fming.dev/) for dependency management, testing, building, and publishing. Install PDM first. Then run:
 
 ```
-pdm lock
 pdm install
 ```
 

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}")