From c315652b2ff9894987de0ee20338c168d86c8f52 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 28 Oct 2025 14:16:22 +0000 Subject: [PATCH 1/7] Rename chipflow_lib to chipflow with backward compatibility MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename the main package from chipflow_lib to chipflow, maintaining full backward compatibility through a compatibility shim. Changes: - Renamed chipflow_lib/ directory to chipflow/ - Updated all internal imports from chipflow_lib to chipflow - Created chipflow_lib/ backward compatibility package that re-exports from chipflow with deprecation warnings - Updated pyproject.toml package name and references - Updated all documentation references from chipflow_lib to chipflow - Updated test imports and mock patches - Changed simulatable_interface default base from "com.chipflow.chipflow_lib" to "com.chipflow.chipflow" The chipflow_lib backward compatibility shim: - Shows deprecation warning on import - Re-exports all symbols from chipflow via __path__ manipulation - Allows existing code using chipflow_lib to continue working - Will be maintained temporarily before removal in future version All tests pass with the new package structure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- chipflow/__init__.py | 42 ++++++++++++ {chipflow_lib => chipflow}/_doit.py | 0 {chipflow_lib => chipflow}/_pin_lock.py | 2 +- {chipflow_lib => chipflow}/cli.py | 6 +- .../common/sim/main.cc.jinja | 0 .../common/sim/models.cc | 0 .../common/sim/models.h | 0 .../common/sim/vendor/cxxrtl/cxxrtl_replay.h | 0 .../common/sim/vendor/cxxrtl/cxxrtl_server.h | 0 .../common/sim/vendor/nlohmann/json.hpp | 0 {chipflow_lib => chipflow}/config.py | 2 +- {chipflow_lib => chipflow}/config/__init__.py | 0 {chipflow_lib => chipflow}/config/models.py | 0 {chipflow_lib => chipflow}/config/parser.py | 0 {chipflow_lib => chipflow}/config_models.py | 2 +- {chipflow_lib => chipflow}/errors.py | 0 {chipflow_lib => chipflow}/models/hyperram.cc | 0 {chipflow_lib => chipflow}/models/log.cc | 0 {chipflow_lib => chipflow}/models/log.h | 0 {chipflow_lib => chipflow}/models/spiflash.cc | 0 {chipflow_lib => chipflow}/models/spiflash.h | 0 {chipflow_lib => chipflow}/models/uart.cc | 0 {chipflow_lib => chipflow}/models/wb_mon.cc | 0 {chipflow_lib => chipflow}/models/wb_mon.h | 0 .../packaging/__init__.py | 0 .../packaging/allocation.py | 0 {chipflow_lib => chipflow}/packaging/base.py | 0 .../packaging/commands.py | 0 .../packaging/grid_array.py | 0 .../packaging/lockfile.py | 0 .../packaging/openframe.py | 0 {chipflow_lib => chipflow}/packaging/pins.py | 0 .../packaging/port_desc.py | 0 .../packaging/standard.py | 0 {chipflow_lib => chipflow}/packaging/utils.py | 0 .../platform/__init__.py | 2 +- {chipflow_lib => chipflow}/platform/base.py | 0 .../platform/board_step.py | 0 .../platform/io/__init__.py | 0 .../platform/io/annotate.py | 0 .../platform/io/iosignature.py | 0 .../platform/io/signatures.py | 2 +- .../platform/io/sky130.py | 0 .../platform/silicon.py | 0 .../platform/silicon_step.py | 0 {chipflow_lib => chipflow}/platform/sim.py | 2 +- .../platform/sim_step.py | 4 +- .../platform/software.py | 0 .../platform/software_build.py | 0 .../platform/software_step.py | 0 chipflow/platforms/.__init__.py.swp | Bin 0 -> 12288 bytes .../platforms/__init__.py | 2 +- .../platforms/_packages.py | 0 .../platforms/silicon.py | 2 +- {chipflow_lib => chipflow}/serialization.py | 0 .../software/__init__.py | 0 .../software/_builder.py | 0 .../software/soft_gen.py | 0 {chipflow_lib => chipflow}/steps/__init__.py | 2 +- .../steps/_json_compare.py | 0 {chipflow_lib => chipflow}/steps/board.py | 2 +- {chipflow_lib => chipflow}/steps/silicon.py | 2 +- {chipflow_lib => chipflow}/steps/sim.py | 2 +- {chipflow_lib => chipflow}/steps/software.py | 2 +- {chipflow_lib => chipflow}/utils.py | 0 chipflow_lib/__init__.py | 53 ++++++--------- docs/architecture.rst | 8 +-- docs/chipflow-toml-guide.rst | 8 +-- docs/conf.py | 8 +-- docs/contributor-pin-signature-internals.rst | 52 +++++++------- docs/getting-started.rst | 4 +- docs/index.rst | 2 +- docs/platform-api.rst | 64 +++++++++--------- docs/simulation-guide.rst | 14 ++-- docs/using-pin-signatures.rst | 12 ++-- pdm.lock | 24 +++---- pyproject.toml | 11 +-- tests/fixtures/mock_top.py | 2 +- tests/test_cli.py | 40 +++++------ tests/test_init.py | 8 +-- tests/test_package_pins.py | 2 +- tests/test_pin_lock.py | 2 +- tests/test_silicon_platform_port.py | 2 +- tests/test_utils.py | 2 +- tests/test_utils_additional.py | 2 +- 85 files changed, 212 insertions(+), 186 deletions(-) create mode 100644 chipflow/__init__.py rename {chipflow_lib => chipflow}/_doit.py (100%) rename {chipflow_lib => chipflow}/_pin_lock.py (83%) rename {chipflow_lib => chipflow}/cli.py (95%) rename {chipflow_lib => chipflow}/common/sim/main.cc.jinja (100%) rename {chipflow_lib => chipflow}/common/sim/models.cc (100%) rename {chipflow_lib => chipflow}/common/sim/models.h (100%) rename {chipflow_lib => chipflow}/common/sim/vendor/cxxrtl/cxxrtl_replay.h (100%) rename {chipflow_lib => chipflow}/common/sim/vendor/cxxrtl/cxxrtl_server.h (100%) rename {chipflow_lib => chipflow}/common/sim/vendor/nlohmann/json.hpp (100%) rename {chipflow_lib => chipflow}/config.py (86%) rename {chipflow_lib => chipflow}/config/__init__.py (100%) rename {chipflow_lib => chipflow}/config/models.py (100%) rename {chipflow_lib => chipflow}/config/parser.py (100%) rename {chipflow_lib => chipflow}/config_models.py (90%) rename {chipflow_lib => chipflow}/errors.py (100%) rename {chipflow_lib => chipflow}/models/hyperram.cc (100%) rename {chipflow_lib => chipflow}/models/log.cc (100%) rename {chipflow_lib => chipflow}/models/log.h (100%) rename {chipflow_lib => chipflow}/models/spiflash.cc (100%) rename {chipflow_lib => chipflow}/models/spiflash.h (100%) rename {chipflow_lib => chipflow}/models/uart.cc (100%) rename {chipflow_lib => chipflow}/models/wb_mon.cc (100%) rename {chipflow_lib => chipflow}/models/wb_mon.h (100%) rename {chipflow_lib => chipflow}/packaging/__init__.py (100%) rename {chipflow_lib => chipflow}/packaging/allocation.py (100%) rename {chipflow_lib => chipflow}/packaging/base.py (100%) rename {chipflow_lib => chipflow}/packaging/commands.py (100%) rename {chipflow_lib => chipflow}/packaging/grid_array.py (100%) rename {chipflow_lib => chipflow}/packaging/lockfile.py (100%) rename {chipflow_lib => chipflow}/packaging/openframe.py (100%) rename {chipflow_lib => chipflow}/packaging/pins.py (100%) rename {chipflow_lib => chipflow}/packaging/port_desc.py (100%) rename {chipflow_lib => chipflow}/packaging/standard.py (100%) rename {chipflow_lib => chipflow}/packaging/utils.py (100%) rename {chipflow_lib => chipflow}/platform/__init__.py (96%) rename {chipflow_lib => chipflow}/platform/base.py (100%) rename {chipflow_lib => chipflow}/platform/board_step.py (100%) rename {chipflow_lib => chipflow}/platform/io/__init__.py (100%) rename {chipflow_lib => chipflow}/platform/io/annotate.py (100%) rename {chipflow_lib => chipflow}/platform/io/iosignature.py (100%) rename {chipflow_lib => chipflow}/platform/io/signatures.py (99%) rename {chipflow_lib => chipflow}/platform/io/sky130.py (100%) rename {chipflow_lib => chipflow}/platform/silicon.py (100%) rename {chipflow_lib => chipflow}/platform/silicon_step.py (100%) rename {chipflow_lib => chipflow}/platform/sim.py (99%) rename {chipflow_lib => chipflow}/platform/sim_step.py (97%) rename {chipflow_lib => chipflow}/platform/software.py (100%) rename {chipflow_lib => chipflow}/platform/software_build.py (100%) rename {chipflow_lib => chipflow}/platform/software_step.py (100%) create mode 100644 chipflow/platforms/.__init__.py.swp rename {chipflow_lib => chipflow}/platforms/__init__.py (95%) rename {chipflow_lib => chipflow}/platforms/_packages.py (100%) rename {chipflow_lib => chipflow}/platforms/silicon.py (88%) rename {chipflow_lib => chipflow}/serialization.py (100%) rename {chipflow_lib => chipflow}/software/__init__.py (100%) rename {chipflow_lib => chipflow}/software/_builder.py (100%) rename {chipflow_lib => chipflow}/software/soft_gen.py (100%) rename {chipflow_lib => chipflow}/steps/__init__.py (90%) rename {chipflow_lib => chipflow}/steps/_json_compare.py (100%) rename {chipflow_lib => chipflow}/steps/board.py (80%) rename {chipflow_lib => chipflow}/steps/silicon.py (88%) rename {chipflow_lib => chipflow}/steps/sim.py (83%) rename {chipflow_lib => chipflow}/steps/software.py (84%) rename {chipflow_lib => chipflow}/utils.py (100%) diff --git a/chipflow/__init__.py b/chipflow/__init__.py new file mode 100644 index 00000000..6756b2e4 --- /dev/null +++ b/chipflow/__init__.py @@ -0,0 +1,42 @@ +# SPDX-License-Identifier: BSD-2-Clause +""" +Chipflow library + +This is the main entry point for the ChipFlow library, providing tools for +building ASIC designs using the Amaranth HDL framework. +""" + +import importlib.metadata +from typing import TYPE_CHECKING + +# Import core utilities +from .utils import ( + ChipFlowError, + ensure_chipflow_root, + get_cls_by_reference, + get_src_loc, +) + +if TYPE_CHECKING: + from .config import Config + +__version__ = importlib.metadata.version("chipflow") + + +# Maintain backward compatibility with underscore-prefixed names +_get_cls_by_reference = get_cls_by_reference +_ensure_chipflow_root = ensure_chipflow_root +_get_src_loc = get_src_loc + + +def _parse_config() -> 'Config': + """Parse the chipflow.toml configuration file.""" + from .config.parser import _parse_config as config_parse + return config_parse() + + +__all__ = [ + '__version__', + 'ChipFlowError', + 'ensure_chipflow_root', +] diff --git a/chipflow_lib/_doit.py b/chipflow/_doit.py similarity index 100% rename from chipflow_lib/_doit.py rename to chipflow/_doit.py diff --git a/chipflow_lib/_pin_lock.py b/chipflow/_pin_lock.py similarity index 83% rename from chipflow_lib/_pin_lock.py rename to chipflow/_pin_lock.py index 89197e2e..a06864c6 100644 --- a/chipflow_lib/_pin_lock.py +++ b/chipflow/_pin_lock.py @@ -3,7 +3,7 @@ Backward compatibility shim for pin lock functionality. This module re-exports pin lock functionality from the packaging module. -New code should import directly from chipflow_lib.packaging instead. +New code should import directly from chipflow.packaging instead. """ # Re-export from packaging module for backward compatibility diff --git a/chipflow_lib/cli.py b/chipflow/cli.py similarity index 95% rename from chipflow_lib/cli.py rename to chipflow/cli.py index 379bacac..99b139c0 100644 --- a/chipflow_lib/cli.py +++ b/chipflow/cli.py @@ -23,9 +23,9 @@ class UnexpectedError(ChipFlowError): DEFAULT_STEPS = { - "silicon": "chipflow_lib.steps.silicon:SiliconStep", - "sim": "chipflow_lib.steps.sim:SimStep", - "software": "chipflow_lib.steps.software:SoftwareStep" + "silicon": "chipflow.steps.silicon:SiliconStep", + "sim": "chipflow.steps.sim:SimStep", + "software": "chipflow.steps.software:SoftwareStep" } diff --git a/chipflow_lib/common/sim/main.cc.jinja b/chipflow/common/sim/main.cc.jinja similarity index 100% rename from chipflow_lib/common/sim/main.cc.jinja rename to chipflow/common/sim/main.cc.jinja diff --git a/chipflow_lib/common/sim/models.cc b/chipflow/common/sim/models.cc similarity index 100% rename from chipflow_lib/common/sim/models.cc rename to chipflow/common/sim/models.cc diff --git a/chipflow_lib/common/sim/models.h b/chipflow/common/sim/models.h similarity index 100% rename from chipflow_lib/common/sim/models.h rename to chipflow/common/sim/models.h diff --git a/chipflow_lib/common/sim/vendor/cxxrtl/cxxrtl_replay.h b/chipflow/common/sim/vendor/cxxrtl/cxxrtl_replay.h similarity index 100% rename from chipflow_lib/common/sim/vendor/cxxrtl/cxxrtl_replay.h rename to chipflow/common/sim/vendor/cxxrtl/cxxrtl_replay.h diff --git a/chipflow_lib/common/sim/vendor/cxxrtl/cxxrtl_server.h b/chipflow/common/sim/vendor/cxxrtl/cxxrtl_server.h similarity index 100% rename from chipflow_lib/common/sim/vendor/cxxrtl/cxxrtl_server.h rename to chipflow/common/sim/vendor/cxxrtl/cxxrtl_server.h diff --git a/chipflow_lib/common/sim/vendor/nlohmann/json.hpp b/chipflow/common/sim/vendor/nlohmann/json.hpp similarity index 100% rename from chipflow_lib/common/sim/vendor/nlohmann/json.hpp rename to chipflow/common/sim/vendor/nlohmann/json.hpp diff --git a/chipflow_lib/config.py b/chipflow/config.py similarity index 86% rename from chipflow_lib/config.py rename to chipflow/config.py index a0788ed2..a12af22a 100644 --- a/chipflow_lib/config.py +++ b/chipflow/config.py @@ -3,7 +3,7 @@ Backward compatibility shim for config parsing. This module re-exports config parsing utilities from the config module. -New code should import directly from chipflow_lib.config instead. +New code should import directly from chipflow.config instead. """ # Re-export from config.parser module for backward compatibility diff --git a/chipflow_lib/config/__init__.py b/chipflow/config/__init__.py similarity index 100% rename from chipflow_lib/config/__init__.py rename to chipflow/config/__init__.py diff --git a/chipflow_lib/config/models.py b/chipflow/config/models.py similarity index 100% rename from chipflow_lib/config/models.py rename to chipflow/config/models.py diff --git a/chipflow_lib/config/parser.py b/chipflow/config/parser.py similarity index 100% rename from chipflow_lib/config/parser.py rename to chipflow/config/parser.py diff --git a/chipflow_lib/config_models.py b/chipflow/config_models.py similarity index 90% rename from chipflow_lib/config_models.py rename to chipflow/config_models.py index 154c7a72..6717351b 100644 --- a/chipflow_lib/config_models.py +++ b/chipflow/config_models.py @@ -3,7 +3,7 @@ Backward compatibility shim for config models. This module re-exports configuration models from the config module. -New code should import directly from chipflow_lib.config instead. +New code should import directly from chipflow.config instead. """ # Re-export from config module for backward compatibility diff --git a/chipflow_lib/errors.py b/chipflow/errors.py similarity index 100% rename from chipflow_lib/errors.py rename to chipflow/errors.py diff --git a/chipflow_lib/models/hyperram.cc b/chipflow/models/hyperram.cc similarity index 100% rename from chipflow_lib/models/hyperram.cc rename to chipflow/models/hyperram.cc diff --git a/chipflow_lib/models/log.cc b/chipflow/models/log.cc similarity index 100% rename from chipflow_lib/models/log.cc rename to chipflow/models/log.cc diff --git a/chipflow_lib/models/log.h b/chipflow/models/log.h similarity index 100% rename from chipflow_lib/models/log.h rename to chipflow/models/log.h diff --git a/chipflow_lib/models/spiflash.cc b/chipflow/models/spiflash.cc similarity index 100% rename from chipflow_lib/models/spiflash.cc rename to chipflow/models/spiflash.cc diff --git a/chipflow_lib/models/spiflash.h b/chipflow/models/spiflash.h similarity index 100% rename from chipflow_lib/models/spiflash.h rename to chipflow/models/spiflash.h diff --git a/chipflow_lib/models/uart.cc b/chipflow/models/uart.cc similarity index 100% rename from chipflow_lib/models/uart.cc rename to chipflow/models/uart.cc diff --git a/chipflow_lib/models/wb_mon.cc b/chipflow/models/wb_mon.cc similarity index 100% rename from chipflow_lib/models/wb_mon.cc rename to chipflow/models/wb_mon.cc diff --git a/chipflow_lib/models/wb_mon.h b/chipflow/models/wb_mon.h similarity index 100% rename from chipflow_lib/models/wb_mon.h rename to chipflow/models/wb_mon.h diff --git a/chipflow_lib/packaging/__init__.py b/chipflow/packaging/__init__.py similarity index 100% rename from chipflow_lib/packaging/__init__.py rename to chipflow/packaging/__init__.py diff --git a/chipflow_lib/packaging/allocation.py b/chipflow/packaging/allocation.py similarity index 100% rename from chipflow_lib/packaging/allocation.py rename to chipflow/packaging/allocation.py diff --git a/chipflow_lib/packaging/base.py b/chipflow/packaging/base.py similarity index 100% rename from chipflow_lib/packaging/base.py rename to chipflow/packaging/base.py diff --git a/chipflow_lib/packaging/commands.py b/chipflow/packaging/commands.py similarity index 100% rename from chipflow_lib/packaging/commands.py rename to chipflow/packaging/commands.py diff --git a/chipflow_lib/packaging/grid_array.py b/chipflow/packaging/grid_array.py similarity index 100% rename from chipflow_lib/packaging/grid_array.py rename to chipflow/packaging/grid_array.py diff --git a/chipflow_lib/packaging/lockfile.py b/chipflow/packaging/lockfile.py similarity index 100% rename from chipflow_lib/packaging/lockfile.py rename to chipflow/packaging/lockfile.py diff --git a/chipflow_lib/packaging/openframe.py b/chipflow/packaging/openframe.py similarity index 100% rename from chipflow_lib/packaging/openframe.py rename to chipflow/packaging/openframe.py diff --git a/chipflow_lib/packaging/pins.py b/chipflow/packaging/pins.py similarity index 100% rename from chipflow_lib/packaging/pins.py rename to chipflow/packaging/pins.py diff --git a/chipflow_lib/packaging/port_desc.py b/chipflow/packaging/port_desc.py similarity index 100% rename from chipflow_lib/packaging/port_desc.py rename to chipflow/packaging/port_desc.py diff --git a/chipflow_lib/packaging/standard.py b/chipflow/packaging/standard.py similarity index 100% rename from chipflow_lib/packaging/standard.py rename to chipflow/packaging/standard.py diff --git a/chipflow_lib/packaging/utils.py b/chipflow/packaging/utils.py similarity index 100% rename from chipflow_lib/packaging/utils.py rename to chipflow/packaging/utils.py diff --git a/chipflow_lib/platform/__init__.py b/chipflow/platform/__init__.py similarity index 96% rename from chipflow_lib/platform/__init__.py rename to chipflow/platform/__init__.py index 865f8a4e..8cf9a8ee 100644 --- a/chipflow_lib/platform/__init__.py +++ b/chipflow/platform/__init__.py @@ -35,7 +35,7 @@ from ..utils import top_components, get_software_builds __all__ = [ - # Steps (primarily accessed via chipflow_lib.steps.*) + # Steps (primarily accessed via chipflow.steps.*) 'SiliconStep', 'SimStep', 'SoftwareStep', diff --git a/chipflow_lib/platform/base.py b/chipflow/platform/base.py similarity index 100% rename from chipflow_lib/platform/base.py rename to chipflow/platform/base.py diff --git a/chipflow_lib/platform/board_step.py b/chipflow/platform/board_step.py similarity index 100% rename from chipflow_lib/platform/board_step.py rename to chipflow/platform/board_step.py diff --git a/chipflow_lib/platform/io/__init__.py b/chipflow/platform/io/__init__.py similarity index 100% rename from chipflow_lib/platform/io/__init__.py rename to chipflow/platform/io/__init__.py diff --git a/chipflow_lib/platform/io/annotate.py b/chipflow/platform/io/annotate.py similarity index 100% rename from chipflow_lib/platform/io/annotate.py rename to chipflow/platform/io/annotate.py diff --git a/chipflow_lib/platform/io/iosignature.py b/chipflow/platform/io/iosignature.py similarity index 100% rename from chipflow_lib/platform/io/iosignature.py rename to chipflow/platform/io/iosignature.py diff --git a/chipflow_lib/platform/io/signatures.py b/chipflow/platform/io/signatures.py similarity index 99% rename from chipflow_lib/platform/io/signatures.py rename to chipflow/platform/io/signatures.py index 2ffb96e5..b4d038b2 100644 --- a/chipflow_lib/platform/io/signatures.py +++ b/chipflow/platform/io/signatures.py @@ -131,7 +131,7 @@ def _unpack_dict(d: dict) -> str: It is expected that a model that takes parameters is implmemted as a template, with the parameters in the order given. """ -def simulatable_interface(base="com.chipflow.chipflow_lib"): +def simulatable_interface(base="com.chipflow.chipflow"): def decorate(klass): assert _VALID_UID(base) dec = amaranth_annotate(SimInterface, SIM_ANNOTATION_SCHEMA) diff --git a/chipflow_lib/platform/io/sky130.py b/chipflow/platform/io/sky130.py similarity index 100% rename from chipflow_lib/platform/io/sky130.py rename to chipflow/platform/io/sky130.py diff --git a/chipflow_lib/platform/silicon.py b/chipflow/platform/silicon.py similarity index 100% rename from chipflow_lib/platform/silicon.py rename to chipflow/platform/silicon.py diff --git a/chipflow_lib/platform/silicon_step.py b/chipflow/platform/silicon_step.py similarity index 100% rename from chipflow_lib/platform/silicon_step.py rename to chipflow/platform/silicon_step.py diff --git a/chipflow_lib/platform/sim.py b/chipflow/platform/sim.py similarity index 99% rename from chipflow_lib/platform/sim.py rename to chipflow/platform/sim.py index e42030ea..21ef4d88 100644 --- a/chipflow_lib/platform/sim.py +++ b/chipflow/platform/sim.py @@ -236,7 +236,7 @@ def build(self, e, top): env = Environment( - loader=PackageLoader("chipflow_lib", "common/sim"), + loader=PackageLoader("chipflow", "common/sim"), autoescape=select_autoescape() ) template = env.get_template("main.cc.jinja") diff --git a/chipflow_lib/platform/sim_step.py b/chipflow/platform/sim_step.py similarity index 97% rename from chipflow_lib/platform/sim_step.py rename to chipflow/platform/sim_step.py index 9a464aba..2d76e02f 100644 --- a/chipflow_lib/platform/sim_step.py +++ b/chipflow/platform/sim_step.py @@ -23,8 +23,8 @@ @contextmanager def common(): - chipflow_lib = importlib.resources.files('chipflow_lib') - common = chipflow_lib.joinpath('common', 'sim') + chipflow = importlib.resources.files('chipflow') + common = chipflow.joinpath('common', 'sim') with importlib.resources.as_file(common) as f: yield f diff --git a/chipflow_lib/platform/software.py b/chipflow/platform/software.py similarity index 100% rename from chipflow_lib/platform/software.py rename to chipflow/platform/software.py diff --git a/chipflow_lib/platform/software_build.py b/chipflow/platform/software_build.py similarity index 100% rename from chipflow_lib/platform/software_build.py rename to chipflow/platform/software_build.py diff --git a/chipflow_lib/platform/software_step.py b/chipflow/platform/software_step.py similarity index 100% rename from chipflow_lib/platform/software_step.py rename to chipflow/platform/software_step.py diff --git a/chipflow/platforms/.__init__.py.swp b/chipflow/platforms/.__init__.py.swp new file mode 100644 index 0000000000000000000000000000000000000000..1cf8293de7f90a35805c01e769f908a0a016071a GIT binary patch literal 12288 zcmeI2J&YSg9K|OPArv?ck_M+|TwJIn4Y zhZ`b_RDASEbV!s4QbeLeG(Z6b1syc$s3?(A@b+W&>|LX)iDsprcIWNPc>iynEv-D0 z=1r?dUv2CX98VK+=Pu!@dH-zZM?yk5@j|88LdY<={a?pH+Apg2nA4W>s6Gs3Lr8~- z(tr<_C*0{s*W2mLc+eH{c*nuT6c=^DCq=_f8i8PHD#LlSW82*4%C;N9qBOH<8V8I6 zr#rAgu3X-2CjGW*7wLubH%=d7dKd?c1I7X4fN{V$U>q6|ys$v9vfFb)_8j0462p##h%Njwku4cr4?g3rJw;A1cX&x7Z{2Kf64LjC~1g73gr;8PHTTc8bI0?z^h z{z9FrX z#OGB>a7X&5$U_+_JxQCpJX}+T;uQqqd79D0|sOwFW9lOc1(MWM2s6c`!_i3@I_v8Zzc`*%JDQj5*^$Mj) zTa`*V%Wf{EEEB33%k-6mWztH%GHE$onX;U%Oj$`*CY6^ypRBa-nOa%)yz|NmYpn=^ z7Sb5#MzP#ls4jMPN4u)ioU13P*TPEX*NREvFXfqO=+)Jkd7+Y!1F!CVkmf0kSutQP z-B@@O`@QJ|A;OP~OC326nBo&IxWdNoTCGOLGak{rZyGY>Q_V0g_MIedEa^%YGNy5q z<_(u2CUQNhBvmXt^i(=P?>{dBNl1OoL9|25k;V(JcbrWc&15WGT`s=wo} 'Config': - """Parse the chipflow.toml configuration file.""" - from .config.parser import _parse_config as config_parse - return config_parse() - +# Re-export everything from chipflow +from chipflow import * # noqa: F401, F403 +from chipflow import __version__, _parse_config, _get_cls_by_reference, _ensure_chipflow_root, _get_src_loc # noqa: F401 -__all__ = [ - '__version__', - 'ChipFlowError', - 'ensure_chipflow_root', -] +# Maintain backward compatibility for submodules by making this a namespace package +# When someone imports chipflow_lib.something, Python will look for chipflow.something +__path__ = __import__('chipflow').__path__ diff --git a/docs/architecture.rst b/docs/architecture.rst index 2bce1689..8e01166f 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -433,7 +433,7 @@ To attach a simulation model to your custom signature: .. code-block:: python - from chipflow_lib.platform import SimModel, BasicCxxBuilder + from chipflow.platform import SimModel, BasicCxxBuilder # Define the C++ model MY_BUILDER = BasicCxxBuilder( @@ -458,7 +458,7 @@ Override default behavior: .. code-block:: python - from chipflow_lib.platform import SiliconStep + from chipflow.platform import SiliconStep class MySiliconStep(SiliconStep): def prepare(self): @@ -481,7 +481,7 @@ Define new package types: .. code-block:: python - from chipflow_lib.packaging import BasePackageDef + from chipflow.packaging import BasePackageDef class MyPackageDef(BasePackageDef): def __init__(self): @@ -499,7 +499,7 @@ Add new target platforms: .. code-block:: python - from chipflow_lib.platform import StepBase + from chipflow.platform import StepBase class MyPlatformStep(StepBase): def build(self, m, top): diff --git a/docs/chipflow-toml-guide.rst b/docs/chipflow-toml-guide.rst index 3ccec959..ad6513cf 100644 --- a/docs/chipflow-toml-guide.rst +++ b/docs/chipflow-toml-guide.rst @@ -14,7 +14,7 @@ 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.config.parser import _parse_config_file + from chipflow.config.parser import _parse_config_file _parse_config_file("docs/example-chipflow.toml") ``[chipflow]`` table @@ -79,9 +79,9 @@ The instance name is the name the python object will be given in your design, an |optional| -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`. -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 +For example, if you want to override the standard silicon preparation step, you could derive from :class:`chipflow.steps.silicon.SiliconStep`, add your custom functionality and add the following to your `chipflow.toml`, with the appropriate :term:`module class path`: .. code-block:: TOML @@ -92,7 +92,7 @@ and add the following to your `chipflow.toml`, with the appropriate :term:`modul You probably won't need to change these if you're starting from an example repository. -.. _chipflow_lib: https://github.com/ChipFlow/chipflow-lib +.. _chipflow: https://github.com/ChipFlow/chipflow-lib ``[chipflow.silicon]`` diff --git a/docs/conf.py b/docs/conf.py index 792bff01..3a7338b0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,9 +6,9 @@ import sys from pprint import pformat -sys.path.insert(0, os.path.abspath('../../chipflow_lib')) +sys.path.insert(0, os.path.abspath('../../chipflow')) -from chipflow_lib import __version__ +from chipflow import __version__ doctest_path = [os.path.abspath('..')] @@ -70,7 +70,7 @@ # TODO: Re-enable AutoAPI once import issues are resolved # # autoapi_dirs = [ -# "../chipflow_lib", +# "../chipflow", # ] # autoapi_generate_api_docs = False # autoapi_template_dir = "_templates/autoapi" @@ -137,7 +137,7 @@ from amaranth.lib import wiring from amaranth.lib.wiring import In, Out, connect, flipped from amaranth_soc import csr, wishbone -from chipflow_lib.platforms import ( +from chipflow.platforms import ( UARTSignature, GPIOSignature, SPISignature, I2CSignature, QSPIFlashSignature, JTAGSignature, IOTripPoint, Sky130DriveMode, diff --git a/docs/contributor-pin-signature-internals.rst b/docs/contributor-pin-signature-internals.rst index 477a1b52..bbc417cb 100644 --- a/docs/contributor-pin-signature-internals.rst +++ b/docs/contributor-pin-signature-internals.rst @@ -18,7 +18,7 @@ This metadata is preserved through the entire flow from Python design → RTLIL Annotation Infrastructure -------------------------- -Core Module: ``chipflow_lib/platform/io/annotate.py`` +Core Module: ``chipflow/platform/io/annotate.py`` The annotation system uses Amaranth's ``meta.Annotation`` framework combined with Pydantic for type-safe JSON schema generation. @@ -49,7 +49,7 @@ The core function is ``amaranth_annotate()``: .. code-block:: python from typing_extensions import TypedDict, NotRequired - from chipflow_lib.platform.io.annotate import amaranth_annotate + from chipflow.platform.io.annotate import amaranth_annotate # Define schema as TypedDict class MyModel(TypedDict): @@ -92,7 +92,7 @@ Platforms extract annotations from the design using ``submodule_metadata()``: .. code-block:: python - from chipflow_lib.platform.io.annotate import submodule_metadata + from chipflow.platform.io.annotate import submodule_metadata frag = Fragment.get(m, None) for component, name, meta in submodule_metadata(frag, "top"): @@ -106,7 +106,7 @@ Platforms extract annotations from the design using ``submodule_metadata()``: I/O Signature Base Classes --------------------------- -Core Module: ``chipflow_lib/platform/io/iosignature.py`` +Core Module: ``chipflow/platform/io/iosignature.py`` IOModelOptions TypedDict ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -194,7 +194,7 @@ The base class for all I/O signatures, decorated with ``@amaranth_annotate``: Concrete Pin Signatures ------------------------ -Core Module: ``chipflow_lib/platform/io/signatures.py`` +Core Module: ``chipflow/platform/io/signatures.py`` Concrete pin signatures (UART, GPIO, SPI, etc.) combine I/O signatures with simulation metadata. @@ -207,7 +207,7 @@ This decorator adds simulation model metadata for interface type identification: .. code-block:: python - def simulatable_interface(base="com.chipflow.chipflow_lib"): + def simulatable_interface(base="com.chipflow.chipflow"): def decorate(klass): # Apply amaranth_annotate for SimInterface dec = amaranth_annotate(SimInterface, SIM_ANNOTATION_SCHEMA) @@ -233,7 +233,7 @@ This decorator adds simulation model metadata for interface type identification: **What it does:** 1. Applies ``amaranth_annotate(SimInterface, ...)`` to the class -2. Assigns a unique identifier (UID) like ``"com.chipflow.chipflow_lib.UARTSignature"`` +2. Assigns a unique identifier (UID) like ``"com.chipflow.chipflow.UARTSignature"`` 3. Wraps ``__init__`` to populate ``__chipflow_annotation__`` with UID and parameters 4. Allows signatures to specify parameters via ``__chipflow_parameters__()`` method @@ -252,7 +252,7 @@ Example: UARTSignature **Annotations on this signature:** -1. ``SIM_ANNOTATION_SCHEMA``: ``{"uid": "com.chipflow.chipflow_lib.UARTSignature", "parameters": []}`` +1. ``SIM_ANNOTATION_SCHEMA``: ``{"uid": "com.chipflow.chipflow.UARTSignature", "parameters": []}`` 2. Nested ``IO_ANNOTATION_SCHEMA`` on ``tx`` and ``rx`` sub-signatures Example: GPIOSignature with Parameters @@ -326,7 +326,7 @@ This signature wrapper attaches driver files to peripherals: .. code-block:: python - from chipflow_lib.platforms import UARTSignature, SoftwareDriverSignature + from chipflow.platforms import UARTSignature, SoftwareDriverSignature from amaranth_soc import csr class UARTPeripheral(wiring.Component): @@ -375,7 +375,7 @@ Platform Consumption Silicon Platform ~~~~~~~~~~~~~~~~ -Core Module: ``chipflow_lib/platform/silicon.py`` +Core Module: ``chipflow/platform/silicon.py`` The silicon platform creates actual I/O ports from pin signatures. @@ -416,7 +416,7 @@ The platform reads the top-level signature and creates ports: .. code-block:: python - # chipflow_lib/platform/silicon.py (in SiliconPlatform.create_ports) + # chipflow/platform/silicon.py (in SiliconPlatform.create_ports) for key in top.signature.members.keys(): member = getattr(top, key) port_desc = self._get_port_desc(member) # Extracts IOModel from annotations @@ -456,7 +456,7 @@ The platform reads the top-level signature and creates ports: Software Platform ~~~~~~~~~~~~~~~~~ -Core Module: ``chipflow_lib/platform/software.py`` +Core Module: ``chipflow/platform/software.py`` The software platform extracts driver models and builds software. @@ -505,7 +505,7 @@ The software platform extracts driver models and builds software. **SoftwareGenerator - Code Generation:** -Located in ``chipflow_lib/software/soft_gen.py``: +Located in ``chipflow/software/soft_gen.py``: .. code-block:: python @@ -561,7 +561,7 @@ Step 1: Define a Peripheral with Driver .. code-block:: python # chipflow_digital_ip/io/_uart.py - from chipflow_lib.platforms import UARTSignature, SoftwareDriverSignature + from chipflow.platforms import UARTSignature, SoftwareDriverSignature class UARTPeripheral(wiring.Component): def __init__(self, *, init_divisor=0): @@ -607,7 +607,7 @@ Step 3: Annotations Applied **On ``self.uart`` (top-level):** -- ``SIM_ANNOTATION_SCHEMA``: ``{"uid": "com.chipflow.chipflow_lib.UARTSignature", "parameters": []}`` +- ``SIM_ANNOTATION_SCHEMA``: ``{"uid": "com.chipflow.chipflow.UARTSignature", "parameters": []}`` - ``IO_ANNOTATION_SCHEMA`` on ``tx``: ``{"direction": "output", "width": 1, ...}`` - ``IO_ANNOTATION_SCHEMA`` on ``rx``: ``{"direction": "input", "width": 1, ...}`` @@ -695,8 +695,8 @@ To add a new pin signature type: def __chipflow_parameters__(self): return [('param1', self._param1), ('param2', self._param2)] -2. **Add to exports in** ``chipflow_lib/platform/__init__.py`` -3. **Add to re-export in** ``chipflow_lib/platforms/__init__.py`` (for backward compatibility) +2. **Add to exports in** ``chipflow/platform/__init__.py`` +3. **Add to re-export in** ``chipflow/platforms/__init__.py`` (for backward compatibility) 4. **Create simulation model** (if needed) matching the UID 5. **Update documentation** in ``docs/using-pin-signatures.rst`` @@ -709,8 +709,8 @@ To add a new platform that consumes annotations: .. code-block:: python - from chipflow_lib.platform.io.annotate import submodule_metadata - from chipflow_lib.platform.io.signatures import DRIVER_MODEL_SCHEMA, SIM_ANNOTATION_SCHEMA + from chipflow.platform.io.annotate import submodule_metadata + from chipflow.platform.io.signatures import DRIVER_MODEL_SCHEMA, SIM_ANNOTATION_SCHEMA from pydantic import TypeAdapter 2. **Walk the design and extract annotations:** @@ -741,7 +741,7 @@ All annotations generate JSON schemas that are: .. code-block:: python - from chipflow_lib.platform.io.iosignature import _chipflow_schema_uri + from chipflow.platform.io.iosignature import _chipflow_schema_uri # Generates: "https://chipflow.com/schemas/my-thing/v0" MY_SCHEMA = str(_chipflow_schema_uri("my-thing", 0)) @@ -758,12 +758,12 @@ Pydantic's ``TypeAdapter`` provides: Key Files --------- -- ``chipflow_lib/platform/io/annotate.py`` - Core annotation infrastructure -- ``chipflow_lib/platform/io/iosignature.py`` - I/O signature base classes -- ``chipflow_lib/platform/io/signatures.py`` - Concrete signatures and decorators -- ``chipflow_lib/platform/silicon.py`` - Silicon platform consumption -- ``chipflow_lib/platform/software.py`` - Software platform consumption -- ``chipflow_lib/software/soft_gen.py`` - Code generation +- ``chipflow/platform/io/annotate.py`` - Core annotation infrastructure +- ``chipflow/platform/io/iosignature.py`` - I/O signature base classes +- ``chipflow/platform/io/signatures.py`` - Concrete signatures and decorators +- ``chipflow/platform/silicon.py`` - Silicon platform consumption +- ``chipflow/platform/software.py`` - Software platform consumption +- ``chipflow/software/soft_gen.py`` - Code generation See Also -------- diff --git a/docs/getting-started.rst b/docs/getting-started.rst index 6f0ca5d7..8514b663 100644 --- a/docs/getting-started.rst +++ b/docs/getting-started.rst @@ -149,8 +149,8 @@ This should return something like: :: - INFO:chipflow_lib.steps.silicon:Submitting c23dab6-dirty for project chipflow-examples-minimal - INFO:chipflow_lib.steps.silicon:Submitted design: {'build_id': '3f51a69c-b3e3-4fd3-88fd-52826ac5e5dd'} + INFO:chipflow.steps.silicon:Submitting c23dab6-dirty for project chipflow-examples-minimal + INFO:chipflow.steps.silicon:Submitted design: {'build_id': '3f51a69c-b3e3-4fd3-88fd-52826ac5e5dd'} Design submitted successfully! Build URL: https://build-staging.chipflow.org//build/3f51a69c-b3e3-4fd3-88fd-52826ac5e5dd Your design will now start building: pictures and logs of the build are diff --git a/docs/index.rst b/docs/index.rst index dad768c2..b17bc011 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ ChipFlow Library Documentation ============================== -``chipflow_lib`` is a Python library and tools for working with the `ChipFlow Platform `__ +``chipflow`` is a Python library and tools for working with the `ChipFlow Platform `__ It is developed at https://github.com/chipFlow/chipflow-lib/ and licensed `BSD 2-Clause `__ diff --git a/docs/platform-api.rst b/docs/platform-api.rst index 609239f9..4bf1d4e1 100644 --- a/docs/platform-api.rst +++ b/docs/platform-api.rst @@ -1,29 +1,29 @@ Platform API Reference ====================== -This page documents the complete public API of the ``chipflow_lib.platform`` module. +This page documents the complete public API of the ``chipflow.platform`` module. -All symbols listed here are re-exported from submodules for convenience and can be imported directly from ``chipflow_lib.platform``. +All symbols listed here are re-exported from submodules for convenience and can be imported directly from ``chipflow.platform``. Platforms --------- -.. autoclass:: chipflow_lib.platform.sim.SimPlatform +.. autoclass:: chipflow.platform.sim.SimPlatform :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.silicon.SiliconPlatform +.. autoclass:: chipflow.platform.silicon.SiliconPlatform :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.silicon.SiliconPlatformPort +.. autoclass:: chipflow.platform.silicon.SiliconPlatformPort :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.software.SoftwarePlatform +.. autoclass:: chipflow.platform.software.SoftwarePlatform :members: :undoc-members: :show-inheritance: @@ -31,27 +31,27 @@ Platforms Build Steps ----------- -.. autoclass:: chipflow_lib.platform.base.StepBase +.. autoclass:: chipflow.platform.base.StepBase :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.sim_step.SimStep +.. autoclass:: chipflow.platform.sim_step.SimStep :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.silicon_step.SiliconStep +.. autoclass:: chipflow.platform.silicon_step.SiliconStep :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.software_step.SoftwareStep +.. autoclass:: chipflow.platform.software_step.SoftwareStep :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.board_step.BoardStep +.. autoclass:: chipflow.platform.board_step.BoardStep :members: :undoc-members: :show-inheritance: @@ -62,22 +62,22 @@ IO Signatures Base IO Signatures ~~~~~~~~~~~~~~~~~~ -.. autoclass:: chipflow_lib.platform.io.iosignature.IOSignature +.. autoclass:: chipflow.platform.io.iosignature.IOSignature :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.iosignature.OutputIOSignature +.. autoclass:: chipflow.platform.io.iosignature.OutputIOSignature :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.iosignature.InputIOSignature +.. autoclass:: chipflow.platform.io.iosignature.InputIOSignature :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.iosignature.BidirIOSignature +.. autoclass:: chipflow.platform.io.iosignature.BidirIOSignature :members: :undoc-members: :show-inheritance: @@ -85,32 +85,32 @@ Base IO Signatures Protocol-Specific Signatures ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. autoclass:: chipflow_lib.platform.io.signatures.UARTSignature +.. autoclass:: chipflow.platform.io.signatures.UARTSignature :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.signatures.GPIOSignature +.. autoclass:: chipflow.platform.io.signatures.GPIOSignature :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.signatures.SPISignature +.. autoclass:: chipflow.platform.io.signatures.SPISignature :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.signatures.I2CSignature +.. autoclass:: chipflow.platform.io.signatures.I2CSignature :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.signatures.QSPIFlashSignature +.. autoclass:: chipflow.platform.io.signatures.QSPIFlashSignature :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.signatures.JTAGSignature +.. autoclass:: chipflow.platform.io.signatures.JTAGSignature :members: :undoc-members: :show-inheritance: @@ -118,35 +118,35 @@ Protocol-Specific Signatures Software Integration ~~~~~~~~~~~~~~~~~~~~ -.. autoclass:: chipflow_lib.platform.io.signatures.SoftwareDriverSignature +.. autoclass:: chipflow.platform.io.signatures.SoftwareDriverSignature :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.signatures.SoftwareBuild +.. autoclass:: chipflow.platform.io.signatures.SoftwareBuild :members: :undoc-members: :show-inheritance: -.. autofunction:: chipflow_lib.platform.io.signatures.attach_data +.. autofunction:: chipflow.platform.io.signatures.attach_data IO Configuration ---------------- -.. autoclass:: chipflow_lib.platform.io.iosignature.IOModel +.. autoclass:: chipflow.platform.io.iosignature.IOModel :members: :undoc-members: -.. autoclass:: chipflow_lib.platform.io.iosignature.IOModelOptions +.. autoclass:: chipflow.platform.io.iosignature.IOModelOptions :members: :undoc-members: -.. autoclass:: chipflow_lib.platform.io.iosignature.IOTripPoint +.. autoclass:: chipflow.platform.io.iosignature.IOTripPoint :members: :undoc-members: :show-inheritance: -.. autoclass:: chipflow_lib.platform.io.sky130.Sky130DriveMode +.. autoclass:: chipflow.platform.io.sky130.Sky130DriveMode :members: :undoc-members: :show-inheritance: @@ -154,14 +154,14 @@ IO Configuration Utility Functions ----------------- -.. autofunction:: chipflow_lib.platform.base.setup_amaranth_tools +.. autofunction:: chipflow.platform.base.setup_amaranth_tools -.. autofunction:: chipflow_lib.utils.top_components +.. autofunction:: chipflow.utils.top_components -.. autofunction:: chipflow_lib.utils.get_software_builds +.. autofunction:: chipflow.utils.get_software_builds Constants --------- -.. autodata:: chipflow_lib.platform.io.iosignature.IO_ANNOTATION_SCHEMA +.. autodata:: chipflow.platform.io.iosignature.IO_ANNOTATION_SCHEMA :annotation: diff --git a/docs/simulation-guide.rst b/docs/simulation-guide.rst index 9364d752..bd5676dc 100644 --- a/docs/simulation-guide.rst +++ b/docs/simulation-guide.rst @@ -98,7 +98,7 @@ ChipFlow includes built-in models for common peripherals: .. code-block:: python - # From chipflow_lib/platform/sim.py + # From chipflow/platform/sim.py _COMMON_BUILDER = BasicCxxBuilder( models=[ SimModel('spi', 'chipflow::models', SPISignature), @@ -112,7 +112,7 @@ ChipFlow includes built-in models for common peripherals: When you use ``UARTSignature()`` in your design, SimPlatform automatically: -1. Extracts the ``SimInterface`` annotation with UID ``"com.chipflow.chipflow_lib.UARTSignature"`` +1. Extracts the ``SimInterface`` annotation with UID ``"com.chipflow.chipflow.UARTSignature"`` 2. Looks up the model in ``_COMMON_BUILDER._table`` 3. Generates: ``chipflow::models::uart uart_0("uart_0", top.p_uart__0____tx____o, top.p_uart__0____rx____i)`` @@ -379,8 +379,8 @@ ChipFlow's built-in simulation models cover common peripherals (UART, SPI, I2C, 1. **Study existing models**: The best way to learn is to examine ChipFlow's built-in implementations: - - ``chipflow_lib/common/sim/models.h`` - Model interfaces and helper functions - - ``chipflow_lib/common/sim/models.cc`` - Complete implementations for: + - ``chipflow/common/sim/models.h`` - Model interfaces and helper functions + - ``chipflow/common/sim/models.cc`` - Complete implementations for: - ``uart`` - UART transceiver with baud rate control - ``spiflash`` - QSPI flash memory with command processing @@ -399,7 +399,7 @@ Once you've written a model (e.g., ``design/sim/my_model.h``), register it with .. code-block:: python - from chipflow_lib.platform import SimPlatform, SimModel, BasicCxxBuilder + from chipflow.platform import SimPlatform, SimModel, BasicCxxBuilder from pathlib import Path MY_BUILDER = BasicCxxBuilder( @@ -479,7 +479,7 @@ No UART Output Model Not Found ~~~~~~~~~~~~~~~ -**Symptom**: ``Unable to find a simulation model for 'com.chipflow.chipflow_lib.XXX'`` +**Symptom**: ``Unable to find a simulation model for 'com.chipflow.chipflow.XXX'`` **Causes**: - Using a signature without a corresponding model @@ -505,7 +505,7 @@ Design (design/design.py) from chipflow_digital_ip.io import UARTPeripheral, GPIOPeripheral from chipflow_digital_ip.memory import QSPIFlash - from chipflow_lib.platforms import ( + from chipflow.platforms import ( UARTSignature, GPIOSignature, QSPIFlashSignature, attach_data, SoftwareBuild ) diff --git a/docs/using-pin-signatures.rst b/docs/using-pin-signatures.rst index 42de28dd..d561af40 100644 --- a/docs/using-pin-signatures.rst +++ b/docs/using-pin-signatures.rst @@ -67,7 +67,7 @@ All pin signatures accept ``IOModelOptions`` to configure the electrical and beh .. code-block:: python - from chipflow_lib.platforms import GPIOSignature, IOTripPoint + from chipflow.platforms import GPIOSignature, IOTripPoint super().__init__({ # Basic GPIO @@ -113,7 +113,7 @@ For Sky130 chips, you can configure the I/O cell drive mode: .. code-block:: python - from chipflow_lib.platforms import Sky130DriveMode, GPIOSignature + from chipflow.platforms import Sky130DriveMode, GPIOSignature # Use open-drain with strong pull-down for I2C super().__init__({ @@ -137,7 +137,7 @@ Here's how to create a peripheral that includes software driver code: from amaranth.lib.wiring import In, Out from amaranth_soc import csr - from chipflow_lib.platforms import UARTSignature, SoftwareDriverSignature + from chipflow.platforms import UARTSignature, SoftwareDriverSignature class UARTPeripheral(wiring.Component): def __init__(self, *, addr_width=5, data_width=8, init_divisor=0): @@ -240,7 +240,7 @@ Here's a complete example of using peripherals with driver code in your top-leve from amaranth_soc import csr from chipflow_digital_ip.io import UARTPeripheral, GPIOPeripheral - from chipflow_lib.platforms import UARTSignature, GPIOSignature + from chipflow.platforms import UARTSignature, GPIOSignature class MySoC(wiring.Component): def __init__(self): @@ -287,7 +287,7 @@ Basic Usage .. code-block:: python from pathlib import Path - from chipflow_lib.platforms import attach_data, SoftwareBuild + from chipflow.platforms import attach_data, SoftwareBuild def elaborate(self, platform): m = Module() @@ -340,7 +340,7 @@ Here's a complete working example combining all concepts: from chipflow_digital_ip.io import UARTPeripheral, GPIOPeripheral from chipflow_digital_ip.memory import QSPIFlash - from chipflow_lib.platforms import ( + from chipflow.platforms import ( UARTSignature, GPIOSignature, QSPIFlashSignature, Sky130DriveMode, attach_data, SoftwareBuild ) diff --git a/pdm.lock b/pdm.lock index b7ee2c2a..0e14bb08 100644 --- a/pdm.lock +++ b/pdm.lock @@ -5,7 +5,7 @@ groups = ["default", "dev"] strategy = ["inherit_metadata"] lock_version = "4.5.0" -content_hash = "sha256:f1145c9a91330ea00ab20b72f4ea09eb60f51f381dce9a1326303eee6123e5ac" +content_hash = "sha256:177489a4de81171e46607258cf0a63c85875fadf70d820c9701eb3a4056465db" [[metadata.targets]] requires_python = ">=3.11,<3.14" @@ -1560,23 +1560,19 @@ files = [ [[package]] name = "ziglang" -version = "0.15.1" +version = "0.11.0" requires_python = "~=3.5" summary = " Zig is a general-purpose programming language and toolchain for\nmaintaining robust, optimal, and reusable software." groups = ["default"] files = [ - {file = "ziglang-0.15.1-py3-none-macosx_12_0_arm64.whl", hash = "sha256:f2f92404599822152eff2ef2830632e9ebeb18e55168dddd5f68f6bfeb2c5f4d"}, - {file = "ziglang-0.15.1-py3-none-macosx_12_0_x86_64.whl", hash = "sha256:77348af083caf1c364466b931b5e7f9608687c88670bdda77c237570096bde09"}, - {file = "ziglang-0.15.1-py3-none-manylinux_2_12_i686.manylinux2010_i686.musllinux_1_1_i686.whl", hash = "sha256:129c6b9b9e428ae48a6949ea6da55239f8bd6480656df1eb0b6947f75f851fdf"}, - {file = "ziglang-0.15.1-py3-none-manylinux_2_12_x86_64.manylinux2010_x86_64.musllinux_1_1_x86_64.whl", hash = "sha256:4e45994a0e608d9b16ecad255698f5557a2e24de0bd7ba9efb156ab3f3683d9a"}, - {file = "ziglang-0.15.1-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl", hash = "sha256:6c32697f9e165b7b6c5950ab0a1cd2e2bc3e72f4ff2d59bc5121b2b71955a77a"}, - {file = "ziglang-0.15.1-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.musllinux_1_1_armv7l.whl", hash = "sha256:f9d2493ff7c44967c584212100ce57bb00800ec9545527acfce677b4b3225242"}, - {file = "ziglang-0.15.1-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.musllinux_1_1_ppc64le.whl", hash = "sha256:b261fe992100fdfb3e61cdd0758335ac8514c8aa4029e3604490648c6a337466"}, - {file = "ziglang-0.15.1-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.musllinux_1_1_s390x.whl", hash = "sha256:9118903a47bbcc747ce47b1456c552a04bb6a0e1be28275ab20bbccf8104e474"}, - {file = "ziglang-0.15.1-py3-none-manylinux_2_31_riscv64.musllinux_1_1_riscv64.whl", hash = "sha256:6a49c03d692e31a9a312ec45c0829bc281572196a9df52318bb0be0d05ae20ea"}, - {file = "ziglang-0.15.1-py3-none-win32.whl", hash = "sha256:b8ba52adc1401c470707a420f2e5e199fce142436717aa822e00a93a18a9ea25"}, - {file = "ziglang-0.15.1-py3-none-win_amd64.whl", hash = "sha256:dae4c6aef5bf9d64f6eb71ae57603e2fd0ad5e79efdd5ca3ea058fb1e738d961"}, - {file = "ziglang-0.15.1-py3-none-win_arm64.whl", hash = "sha256:5965248dd7f72769ff339a04bd8e29e13fa205758c64766ef9cc55eaafbaedb8"}, + {file = "ziglang-0.11.0-py3-none-macosx_10_9_x86_64.whl", hash = "sha256:bd046eeab97ad51048575768f6dae10468b3a4449f4467ed61dae621faf6ee55"}, + {file = "ziglang-0.11.0-py3-none-macosx_11_0_arm64.whl", hash = "sha256:038b95cac9adef0c6dce9b72bdad895a0e4e0654c77c4a8f84fe79d2909a366e"}, + {file = "ziglang-0.11.0-py3-none-manylinux_2_12_i686.manylinux2010_i686.musllinux_1_1_i686.whl", hash = "sha256:4f848c8cca520cb12357cfa3d303bf1149a30566f4c1e5999284dbdf921cc2b8"}, + {file = "ziglang-0.11.0-py3-none-manylinux_2_12_x86_64.manylinux2010_x86_64.musllinux_1_1_x86_64.whl", hash = "sha256:45e8116428267e20529b9ee43a7e7364791c1a092845d2143b248a1dbf6760b0"}, + {file = "ziglang-0.11.0-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.musllinux_1_1_aarch64.whl", hash = "sha256:d6372bada34714a5395539cc4d76e9cc6062739cee5ce9949a250f7c525ceb94"}, + {file = "ziglang-0.11.0-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.musllinux_1_1_armv7l.whl", hash = "sha256:5fe81f91fd872fc32ed0f82807df6c680a82cbea56a9f24f818e9da299049022"}, + {file = "ziglang-0.11.0-py3-none-win32.whl", hash = "sha256:97ac4312a358d2a4ba2c153fdb1827caf6bc158501a468ebd6a554b50edee42e"}, + {file = "ziglang-0.11.0-py3-none-win_amd64.whl", hash = "sha256:a7edc7020e7ffbbb3af3a40c17a9bda65d5a65132ff933e153ffa80d8f5ad731"}, ] [[package]] diff --git a/pyproject.toml b/pyproject.toml index 384a6b24..d391ab3c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ # Project metadata [project] -name = "chipflow-lib" +name = "chipflow" dynamic = ["version"] description = "ChipFlow common tools." authors = [ @@ -32,7 +32,7 @@ dependencies = [ ] [project.scripts] -chipflow = "chipflow_lib.cli:run" +chipflow = "chipflow.cli:run" # Build system configuration @@ -48,6 +48,7 @@ typeCheckingMode = "standard" [tool.ruff] include = [ + "chipflow/**/*.py", "chipflow_lib/**/*.py", "tests/**.py", "chipflow.toml", @@ -64,10 +65,10 @@ source = "scm" [tool.pdm.scripts] test.cmd = "pytest" -test-cov.cmd = "pytest --cov=chipflow_lib --cov-report=term" -test-cov-html.cmd = "pytest --cov=chipflow_lib --cov-report=html" +test-cov.cmd = "pytest --cov=chipflow --cov-report=term" +test-cov-html.cmd = "pytest --cov=chipflow --cov-report=html" test-docs.cmd = "sphinx-build -b doctest docs/ docs/_build" -lint.composite = [ "./tools/license_check.sh", "ruff check {args}", "pyright chipflow_lib"] +lint.composite = [ "./tools/license_check.sh", "ruff check {args}", "pyright chipflow"] docs.cmd = "sphinx-build docs/ docs/_build/ -W --keep-going" _check-project.call = "tools.check_project:main" chipflow.shell = "cd $PDM_RUN_CWD && chipflow" diff --git a/tests/fixtures/mock_top.py b/tests/fixtures/mock_top.py index 27cfbff9..f157881f 100644 --- a/tests/fixtures/mock_top.py +++ b/tests/fixtures/mock_top.py @@ -3,7 +3,7 @@ from amaranth.lib import wiring from amaranth.lib.wiring import In, Out -from chipflow_lib.platforms import InputIOSignature, OutputIOSignature, BidirIOSignature +from chipflow.platforms import InputIOSignature, OutputIOSignature, BidirIOSignature __all__ = ["MockTop"] diff --git a/tests/test_cli.py b/tests/test_cli.py index 03c03fb9..d55d1e6a 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -8,8 +8,8 @@ from unittest import mock from chipflow_lib import ChipFlowError -from chipflow_lib.cli import run -from chipflow_lib.config_models import Config, ChipFlowConfig +from chipflow.cli import run +from chipflow.config_models import Config, ChipFlowConfig class MockCommand: """Mock command for testing CLI""" @@ -30,9 +30,9 @@ def run_cli(self, args): )) class TestCLI(unittest.TestCase): - @mock.patch("chipflow_lib.cli._parse_config") - @mock.patch("chipflow_lib.cli.PinCommand") - @mock.patch("chipflow_lib.cli._get_cls_by_reference") + @mock.patch("chipflow.cli._parse_config") + @mock.patch("chipflow.cli.PinCommand") + @mock.patch("chipflow.cli._get_cls_by_reference") def test_run_success(self, mock_get_cls, mock_pin_command, mock_parse_config): """Test CLI run with successful command execution""" # Setup mocks @@ -52,9 +52,9 @@ def test_run_success(self, mock_get_cls, mock_pin_command, mock_parse_config): # No error message should be printed mock_stdout.write.assert_not_called() - @mock.patch("chipflow_lib.cli._parse_config") - @mock.patch("chipflow_lib.cli.PinCommand") - @mock.patch("chipflow_lib.cli._get_cls_by_reference") + @mock.patch("chipflow.cli._parse_config") + @mock.patch("chipflow.cli.PinCommand") + @mock.patch("chipflow.cli._get_cls_by_reference") def test_run_command_error(self, mock_get_cls, mock_pin_command, mock_parse_config): """Test CLI run with command raising ChipFlowError""" # Setup mocks @@ -77,9 +77,9 @@ def test_run_command_error(self, mock_get_cls, mock_pin_command, mock_parse_conf self.assertIn("Error while executing `test error`", buffer.getvalue()) - @mock.patch("chipflow_lib.cli._parse_config") - @mock.patch("chipflow_lib.cli.PinCommand") - @mock.patch("chipflow_lib.cli._get_cls_by_reference") + @mock.patch("chipflow.cli._parse_config") + @mock.patch("chipflow.cli.PinCommand") + @mock.patch("chipflow.cli._get_cls_by_reference") def test_run_unexpected_error(self, mock_get_cls, mock_pin_command, mock_parse_config): """Test CLI run with command raising unexpected exception""" # Setup mocks @@ -104,8 +104,8 @@ def test_run_unexpected_error(self, mock_get_cls, mock_pin_command, mock_parse_c self.assertIn("Error while executing `test unexpected`", buffer.getvalue()) self.assertIn("Unexpected error", buffer.getvalue()) - @mock.patch("chipflow_lib.cli._parse_config") - @mock.patch("chipflow_lib.cli.PinCommand") + @mock.patch("chipflow.cli._parse_config") + @mock.patch("chipflow.cli.PinCommand") def test_step_init_error(self, mock_pin_command, mock_parse_config): """Test CLI run with error initializing step""" # Setup mocks @@ -115,7 +115,7 @@ def test_step_init_error(self, mock_pin_command, mock_parse_config): mock_pin_command.return_value = mock_pin_cmd # Make _get_cls_by_reference raise an exception during step initialization - with mock.patch("chipflow_lib.cli._get_cls_by_reference") as mock_get_cls: + with mock.patch("chipflow.cli._get_cls_by_reference") as mock_get_cls: mock_get_cls.return_value = mock.Mock(side_effect=Exception("Init error")) with self.assertRaises(ChipFlowError) as cm: @@ -123,9 +123,9 @@ def test_step_init_error(self, mock_pin_command, mock_parse_config): self.assertIn("Encountered error while initializing step", str(cm.exception)) - @mock.patch("chipflow_lib.cli._parse_config") - @mock.patch("chipflow_lib.cli.PinCommand") - @mock.patch("chipflow_lib.cli._get_cls_by_reference") + @mock.patch("chipflow.cli._parse_config") + @mock.patch("chipflow.cli.PinCommand") + @mock.patch("chipflow.cli._get_cls_by_reference") def test_build_parser_error(self, mock_get_cls, mock_pin_command, mock_parse_config): """Test CLI run with error building CLI parser""" # Setup mocks @@ -145,9 +145,9 @@ def test_build_parser_error(self, mock_get_cls, mock_pin_command, mock_parse_con self.assertIn("Encountered error while building CLI argument parser", str(cm.exception)) -# @mock.patch("chipflow_lib.cli._parse_config") -# @mock.patch("chipflow_lib.cli.PinCommand") -# @mock.patch("chipflow_lib.cli._get_cls_by_reference") +# @mock.patch("chipflow.cli._parse_config") +# @mock.patch("chipflow.cli.PinCommand") +# @mock.patch("chipflow.cli._get_cls_by_reference") # def test_verbosity_flags(self, mock_get_cls, mock_pin_command, mock_parse_config): # """Test CLI verbosity flags""" # # Setup mocks diff --git a/tests/test_init.py b/tests/test_init.py index 304b36a5..3ec38093 100644 --- a/tests/test_init.py +++ b/tests/test_init.py @@ -13,8 +13,8 @@ _ensure_chipflow_root, _parse_config ) -from chipflow_lib.config.parser import _parse_config_file -from chipflow_lib.config_models import Config, ChipFlowConfig +from chipflow.config.parser import _parse_config_file +from chipflow.config_models import Config, ChipFlowConfig # Process is not part of the public API, so we won't test it here @@ -118,8 +118,8 @@ def test_parse_config_file_valid(self): # Process enum is not part of the public API, so we just check that process has a string value self.assertEqual(str(config.chipflow.silicon.process), "sky130") - @mock.patch("chipflow_lib.config.parser.ensure_chipflow_root") - @mock.patch("chipflow_lib.config.parser._parse_config_file") + @mock.patch("chipflow.config.parser.ensure_chipflow_root") + @mock.patch("chipflow.config.parser._parse_config_file") def test_parse_config(self, mock_parse_config_file, mock_ensure_chipflow_root): """Test _parse_config which uses ensure_chipflow_root and _parse_config_file""" mock_ensure_chipflow_root.return_value = Path("/mock/chipflow/root") diff --git a/tests/test_package_pins.py b/tests/test_package_pins.py index 3b176f6f..4ff5c8e0 100644 --- a/tests/test_package_pins.py +++ b/tests/test_package_pins.py @@ -1,7 +1,7 @@ # SPDX-License-Identifier: BSD-2-Clause import unittest -from chipflow_lib.platforms import PACKAGE_DEFINITIONS +from chipflow.platforms import PACKAGE_DEFINITIONS class TestPackageDefinitions(unittest.TestCase): diff --git a/tests/test_pin_lock.py b/tests/test_pin_lock.py index 7d0e8686..165bb972 100644 --- a/tests/test_pin_lock.py +++ b/tests/test_pin_lock.py @@ -1,7 +1,7 @@ # SPDX-License-Identifier: BSD-2-Clause import unittest -from chipflow_lib.platforms import PACKAGE_DEFINITIONS +from chipflow.platforms import PACKAGE_DEFINITIONS class TestPinLock(unittest.TestCase): diff --git a/tests/test_silicon_platform_port.py b/tests/test_silicon_platform_port.py index d06d0ae7..0eb503cb 100644 --- a/tests/test_silicon_platform_port.py +++ b/tests/test_silicon_platform_port.py @@ -1,7 +1,7 @@ # SPDX-License-Identifier: BSD-2-Clause import unittest -from chipflow_lib.platforms.silicon import SiliconPlatformPort +from chipflow.platforms.silicon import SiliconPlatformPort class TestSiliconPlatformPort(unittest.TestCase): diff --git a/tests/test_utils.py b/tests/test_utils.py index 61b912d2..88aead85 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -5,7 +5,7 @@ from amaranth import Const from amaranth.lib import io -from chipflow_lib.platforms import IOSignature, OutputIOSignature, InputIOSignature, BidirIOSignature +from chipflow.platforms import IOSignature, OutputIOSignature, InputIOSignature, BidirIOSignature logger = logging.getLogger(__name__) diff --git a/tests/test_utils_additional.py b/tests/test_utils_additional.py index 61fd0d47..a9404036 100644 --- a/tests/test_utils_additional.py +++ b/tests/test_utils_additional.py @@ -3,7 +3,7 @@ from amaranth.lib import io -from chipflow_lib.platforms import ( +from chipflow.platforms import ( IOSignature, IOModel, PACKAGE_DEFINITIONS From e4617a4e894f0c5dcca422078a98a5bd785c3bf4 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 28 Oct 2025 15:24:17 +0000 Subject: [PATCH 2/7] Minimize backward compatibility API surface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace wildcard import in chipflow_lib with explicit minimal API based on actual usage in chipflow-digital-ip and chipflow-examples repositories. Changes: - chipflow_lib/__init__.py: Only export ChipFlowError, __version__, and internal API functions (_parse_config, etc.) - chipflow_lib/platforms/__init__.py: Stub module exporting pin signatures and software build utilities used by dependent packages - chipflow_lib/steps/{board,sim,software}.py: Stub modules exporting step classes used by chipflow-examples - chipflow_lib/config.py: Stub module proxying to chipflow.config - tests/fixtures/mock.toml: Updated step references to use new module names All backward compatibility stubs now show deprecation warnings encouraging users to migrate to the new 'chipflow' package name. Tests: 37 passed, 4 skipped. All backward compatibility imports verified. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- chipflow_lib/__init__.py | 15 ++++++----- chipflow_lib/config.py | 25 ++++++++++++++++++ chipflow_lib/platforms/__init__.py | 41 ++++++++++++++++++++++++++++++ chipflow_lib/steps/__init__.py | 10 ++++++++ chipflow_lib/steps/board.py | 21 +++++++++++++++ chipflow_lib/steps/sim.py | 21 +++++++++++++++ chipflow_lib/steps/software.py | 21 +++++++++++++++ tests/fixtures/mock.toml | 6 ++--- 8 files changed, 151 insertions(+), 9 deletions(-) create mode 100644 chipflow_lib/config.py create mode 100644 chipflow_lib/platforms/__init__.py create mode 100644 chipflow_lib/steps/__init__.py create mode 100644 chipflow_lib/steps/board.py create mode 100644 chipflow_lib/steps/sim.py create mode 100644 chipflow_lib/steps/software.py diff --git a/chipflow_lib/__init__.py b/chipflow_lib/__init__.py index 561d39b1..f185d753 100644 --- a/chipflow_lib/__init__.py +++ b/chipflow_lib/__init__.py @@ -20,10 +20,13 @@ stacklevel=2 ) -# Re-export everything from chipflow -from chipflow import * # noqa: F401, F403 -from chipflow import __version__, _parse_config, _get_cls_by_reference, _ensure_chipflow_root, _get_src_loc # noqa: F401 +# Re-export only the symbols actually used by chipflow-digital-ip and chipflow-examples +# Top-level exports (used by chipflow-examples) +from chipflow import ChipFlowError # noqa: F401 +from chipflow import __version__ # noqa: F401 -# Maintain backward compatibility for submodules by making this a namespace package -# When someone imports chipflow_lib.something, Python will look for chipflow.something -__path__ = __import__('chipflow').__path__ +# Internal API (used by tests and CLI) +from chipflow import _parse_config, _get_cls_by_reference, _ensure_chipflow_root, _get_src_loc # noqa: F401 + +# Note: Submodule imports (chipflow_lib.platforms, chipflow_lib.steps, chipflow_lib.config) +# are handled by stub modules in their respective subdirectories diff --git a/chipflow_lib/config.py b/chipflow_lib/config.py new file mode 100644 index 00000000..24a4c4ce --- /dev/null +++ b/chipflow_lib/config.py @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: BSD-2-Clause +""" +Backward compatibility module for chipflow_lib.config. + +This module has been renamed to 'chipflow.config'. This compatibility layer +will be maintained for some time but is deprecated. Please update your imports. +""" + +import warnings + +# Issue deprecation warning +warnings.warn( + "The 'chipflow_lib.config' module has been renamed to 'chipflow.config'. " + "Please update your imports to use 'chipflow.config' instead. " + "This compatibility shim will be removed in a future version.", + DeprecationWarning, + stacklevel=2 +) + +# Re-export the entire config module (used by chipflow-examples via 'import chipflow_lib.config') +from chipflow import config as _config +import sys + +# Make this module act as a proxy for chipflow.config +sys.modules[__name__] = _config diff --git a/chipflow_lib/platforms/__init__.py b/chipflow_lib/platforms/__init__.py new file mode 100644 index 00000000..26df4693 --- /dev/null +++ b/chipflow_lib/platforms/__init__.py @@ -0,0 +1,41 @@ +# SPDX-License-Identifier: BSD-2-Clause +""" +Backward compatibility module for chipflow_lib.platforms. + +This module has been renamed to 'chipflow.platforms'. This compatibility layer +will be maintained for some time but is deprecated. Please update your imports. +""" + +import warnings + +# Issue deprecation warning +warnings.warn( + "The 'chipflow_lib.platforms' module has been renamed to 'chipflow.platforms'. " + "Please update your imports to use 'chipflow.platforms' instead. " + "This compatibility shim will be removed in a future version.", + DeprecationWarning, + stacklevel=2 +) + +# Re-export symbols used by chipflow-digital-ip and chipflow-examples +from chipflow.platforms import ( # noqa: F401 + # Pin signatures (used by both repos) + BidirIOSignature, + GPIOSignature, + I2CSignature, + InputIOSignature, + OutputIOSignature, + QSPIFlashSignature, + SPISignature, + UARTSignature, + + # Software driver support (used by both repos) + SoftwareDriverSignature, + + # Platform-specific configuration (used by chipflow-examples) + Sky130DriveMode, + + # Data attachment (used by chipflow-examples) + attach_data, + SoftwareBuild, +) diff --git a/chipflow_lib/steps/__init__.py b/chipflow_lib/steps/__init__.py new file mode 100644 index 00000000..82518cb5 --- /dev/null +++ b/chipflow_lib/steps/__init__.py @@ -0,0 +1,10 @@ +# SPDX-License-Identifier: BSD-2-Clause +""" +Backward compatibility module for chipflow_lib.steps. + +This module has been renamed to 'chipflow.steps'. This compatibility layer +will be maintained for some time but is deprecated. Please update your imports. +""" + +# Note: Individual step imports (BoardStep, SimStep, SoftwareStep) are handled +# by their respective stub modules: board.py, sim.py, software.py diff --git a/chipflow_lib/steps/board.py b/chipflow_lib/steps/board.py new file mode 100644 index 00000000..64af43ff --- /dev/null +++ b/chipflow_lib/steps/board.py @@ -0,0 +1,21 @@ +# SPDX-License-Identifier: BSD-2-Clause +""" +Backward compatibility module for chipflow_lib.steps.board. + +This module has been renamed to 'chipflow.steps.board'. This compatibility layer +will be maintained for some time but is deprecated. Please update your imports. +""" + +import warnings + +# Issue deprecation warning +warnings.warn( + "The 'chipflow_lib.steps.board' module has been renamed to 'chipflow.steps.board'. " + "Please update your imports to use 'chipflow.steps.board' instead. " + "This compatibility shim will be removed in a future version.", + DeprecationWarning, + stacklevel=2 +) + +# Re-export BoardStep (used by chipflow-examples) +from chipflow.steps.board import BoardStep # noqa: F401 diff --git a/chipflow_lib/steps/sim.py b/chipflow_lib/steps/sim.py new file mode 100644 index 00000000..6526df8a --- /dev/null +++ b/chipflow_lib/steps/sim.py @@ -0,0 +1,21 @@ +# SPDX-License-Identifier: BSD-2-Clause +""" +Backward compatibility module for chipflow_lib.steps.sim. + +This module has been renamed to 'chipflow.steps.sim'. This compatibility layer +will be maintained for some time but is deprecated. Please update your imports. +""" + +import warnings + +# Issue deprecation warning +warnings.warn( + "The 'chipflow_lib.steps.sim' module has been renamed to 'chipflow.steps.sim'. " + "Please update your imports to use 'chipflow.steps.sim' instead. " + "This compatibility shim will be removed in a future version.", + DeprecationWarning, + stacklevel=2 +) + +# Re-export SimStep (used by chipflow-examples) +from chipflow.steps.sim import SimStep # noqa: F401 diff --git a/chipflow_lib/steps/software.py b/chipflow_lib/steps/software.py new file mode 100644 index 00000000..a95f1df0 --- /dev/null +++ b/chipflow_lib/steps/software.py @@ -0,0 +1,21 @@ +# SPDX-License-Identifier: BSD-2-Clause +""" +Backward compatibility module for chipflow_lib.steps.software. + +This module has been renamed to 'chipflow.steps.software'. This compatibility layer +will be maintained for some time but is deprecated. Please update your imports. +""" + +import warnings + +# Issue deprecation warning +warnings.warn( + "The 'chipflow_lib.steps.software' module has been renamed to 'chipflow.steps.software'. " + "Please update your imports to use 'chipflow.steps.software' instead. " + "This compatibility shim will be removed in a future version.", + DeprecationWarning, + stacklevel=2 +) + +# Re-export SoftwareStep (used by chipflow-examples) +from chipflow.steps.software import SoftwareStep # noqa: F401 diff --git a/tests/fixtures/mock.toml b/tests/fixtures/mock.toml index 3738c144..4ca66e2f 100644 --- a/tests/fixtures/mock.toml +++ b/tests/fixtures/mock.toml @@ -2,9 +2,9 @@ project_name = "proj-name" [chipflow.steps] -silicon = "chipflow_lib.platform.silicon_step:SiliconStep" -sim = "chipflow_lib.platform.sim_step:SimStep" -software = "chipflow_lib.platform.software_step:SoftwareStep" +silicon = "chipflow.platform.silicon_step:SiliconStep" +sim = "chipflow.platform.sim_step:SimStep" +software = "chipflow.platform.software_step:SoftwareStep" [chipflow.silicon] process = "ihp_sg13g2" From 7751b8abd17af0b85348d79d2740185242137ed8 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 28 Oct 2025 17:43:46 +0000 Subject: [PATCH 3/7] Fix E402 lint errors in backward compatibility stubs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add noqa: E402 annotations to imports that intentionally come after deprecation warnings. The imports need to be after warnings.warn() so users see the deprecation message when they import these modules. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- chipflow_lib/__init__.py | 6 +++--- chipflow_lib/config.py | 4 ++-- chipflow_lib/platforms/__init__.py | 2 +- chipflow_lib/steps/board.py | 2 +- chipflow_lib/steps/sim.py | 2 +- chipflow_lib/steps/software.py | 2 +- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/chipflow_lib/__init__.py b/chipflow_lib/__init__.py index f185d753..10069dd9 100644 --- a/chipflow_lib/__init__.py +++ b/chipflow_lib/__init__.py @@ -22,11 +22,11 @@ # Re-export only the symbols actually used by chipflow-digital-ip and chipflow-examples # Top-level exports (used by chipflow-examples) -from chipflow import ChipFlowError # noqa: F401 -from chipflow import __version__ # noqa: F401 +from chipflow import ChipFlowError # noqa: F401, E402 +from chipflow import __version__ # noqa: F401, E402 # Internal API (used by tests and CLI) -from chipflow import _parse_config, _get_cls_by_reference, _ensure_chipflow_root, _get_src_loc # noqa: F401 +from chipflow import _parse_config, _get_cls_by_reference, _ensure_chipflow_root, _get_src_loc # noqa: F401, E402 # Note: Submodule imports (chipflow_lib.platforms, chipflow_lib.steps, chipflow_lib.config) # are handled by stub modules in their respective subdirectories diff --git a/chipflow_lib/config.py b/chipflow_lib/config.py index 24a4c4ce..f269b1c4 100644 --- a/chipflow_lib/config.py +++ b/chipflow_lib/config.py @@ -18,8 +18,8 @@ ) # Re-export the entire config module (used by chipflow-examples via 'import chipflow_lib.config') -from chipflow import config as _config -import sys +from chipflow import config as _config # noqa: E402 +import sys # noqa: E402 # Make this module act as a proxy for chipflow.config sys.modules[__name__] = _config diff --git a/chipflow_lib/platforms/__init__.py b/chipflow_lib/platforms/__init__.py index 26df4693..c3476956 100644 --- a/chipflow_lib/platforms/__init__.py +++ b/chipflow_lib/platforms/__init__.py @@ -18,7 +18,7 @@ ) # Re-export symbols used by chipflow-digital-ip and chipflow-examples -from chipflow.platforms import ( # noqa: F401 +from chipflow.platforms import ( # noqa: F401, E402 # Pin signatures (used by both repos) BidirIOSignature, GPIOSignature, diff --git a/chipflow_lib/steps/board.py b/chipflow_lib/steps/board.py index 64af43ff..8d0382c6 100644 --- a/chipflow_lib/steps/board.py +++ b/chipflow_lib/steps/board.py @@ -18,4 +18,4 @@ ) # Re-export BoardStep (used by chipflow-examples) -from chipflow.steps.board import BoardStep # noqa: F401 +from chipflow.steps.board import BoardStep # noqa: F401, E402 diff --git a/chipflow_lib/steps/sim.py b/chipflow_lib/steps/sim.py index 6526df8a..85a4fdec 100644 --- a/chipflow_lib/steps/sim.py +++ b/chipflow_lib/steps/sim.py @@ -18,4 +18,4 @@ ) # Re-export SimStep (used by chipflow-examples) -from chipflow.steps.sim import SimStep # noqa: F401 +from chipflow.steps.sim import SimStep # noqa: F401, E402 diff --git a/chipflow_lib/steps/software.py b/chipflow_lib/steps/software.py index a95f1df0..23f3fb58 100644 --- a/chipflow_lib/steps/software.py +++ b/chipflow_lib/steps/software.py @@ -18,4 +18,4 @@ ) # Re-export SoftwareStep (used by chipflow-examples) -from chipflow.steps.software import SoftwareStep # noqa: F401 +from chipflow.steps.software import SoftwareStep # noqa: F401, E402 From cb54a839287cff6ebb29833f53959c54fe1c82e9 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 28 Oct 2025 18:13:49 +0000 Subject: [PATCH 4/7] Add JTAGSignature to backward compatibility exports MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit JTAGSignature is used by chipflow-examples mcu_soc project but was missing from the backward compatibility stub exports. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- chipflow_lib/platforms/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/chipflow_lib/platforms/__init__.py b/chipflow_lib/platforms/__init__.py index c3476956..7f9630a5 100644 --- a/chipflow_lib/platforms/__init__.py +++ b/chipflow_lib/platforms/__init__.py @@ -24,6 +24,7 @@ GPIOSignature, I2CSignature, InputIOSignature, + JTAGSignature, OutputIOSignature, QSPIFlashSignature, SPISignature, From 97422b7334bc3c5a9dbf139de5d2ad3cd50946f3 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 11 Nov 2025 17:46:56 +0000 Subject: [PATCH 5/7] Add comprehensive tests for pinlock loading and fix error handling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add three new tests to verify pinlock file loading behavior: - test_load_pinlock_file: validates successful loading of valid lockfile - test_load_pinlock_missing_file: ensures proper error when file missing - test_load_pinlock_malformed_file: ensures proper error for invalid data Fix bug in load_pinlock() where only pydantic.ValidationError was caught, but Pydantic 2.x also raises PydanticUserError for incomplete models. Now catches both exception types. Fix test isolation by clearing ensure_chipflow_root() cache between tests to prevent environment pollution across test runs. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- chipflow/packaging/utils.py | 2 +- tests/test_pin_lock.py | 129 +++++++++++++++++++++++++++++++++++- 2 files changed, 129 insertions(+), 2 deletions(-) diff --git a/chipflow/packaging/utils.py b/chipflow/packaging/utils.py index 1fcc1904..8ac76156 100644 --- a/chipflow/packaging/utils.py +++ b/chipflow/packaging/utils.py @@ -36,7 +36,7 @@ def load_pinlock() -> LockFile: try: json = lockfile.read_text() return LockFile.model_validate_json(json) - except pydantic.ValidationError: + except (pydantic.ValidationError, pydantic.PydanticUserError): raise ChipFlowError( "Lockfile `pins.lock` is misformed. " "Please remove and rerun `chipflow pin lock`" diff --git a/tests/test_pin_lock.py b/tests/test_pin_lock.py index 165bb972..a070ef17 100644 --- a/tests/test_pin_lock.py +++ b/tests/test_pin_lock.py @@ -1,7 +1,14 @@ # SPDX-License-Identifier: BSD-2-Clause +import json +import os +import tempfile import unittest +from pathlib import Path from chipflow.platforms import PACKAGE_DEFINITIONS +from chipflow.packaging import load_pinlock +from chipflow.packaging.lockfile import LockFile +from chipflow import ChipFlowError class TestPinLock(unittest.TestCase): @@ -20,4 +27,124 @@ def test_package_definitions_structure(self): self.assertEqual(package_def.name.lower(), name.lower()) # Package definitions should have allocation methods self.assertTrue(hasattr(package_def, 'allocate_pins')) - self.assertTrue(callable(package_def.allocate_pins)) \ No newline at end of file + self.assertTrue(callable(package_def.allocate_pins)) + + def test_load_pinlock_file(self): + """Test loading a valid pins.lock file""" + # Create a temporary directory with a sample pins.lock file + with tempfile.TemporaryDirectory() as tmpdir: + # Set CHIPFLOW_ROOT to temporary directory + old_chipflow_root = os.environ.get('CHIPFLOW_ROOT') + os.environ['CHIPFLOW_ROOT'] = tmpdir + + # Clear the cache on ensure_chipflow_root + from chipflow.utils import ensure_chipflow_root + if hasattr(ensure_chipflow_root, 'root'): + delattr(ensure_chipflow_root, 'root') + + try: + # Create a minimal valid lockfile + lockfile_data = { + "process": "sky130", + "package": { + "package_type": { + "package_type": "QuadPackageDef", + "name": "test_package", + "width": 10, + "height": 10, + "_power": [] + } + }, + "port_map": { + "ports": {} + }, + "metadata": {} + } + + lockfile_path = Path(tmpdir) / 'pins.lock' + with open(lockfile_path, 'w') as f: + json.dump(lockfile_data, f, indent=2) + + # Test loading the lockfile + lockfile = load_pinlock() + + # Validate structure + self.assertIsInstance(lockfile, LockFile) + self.assertEqual(str(lockfile.process), "sky130") + self.assertIsNotNone(lockfile.package) + self.assertIsNotNone(lockfile.port_map) + self.assertIsInstance(lockfile.metadata, dict) + + finally: + # Restore original CHIPFLOW_ROOT + if old_chipflow_root is not None: + os.environ['CHIPFLOW_ROOT'] = old_chipflow_root + elif 'CHIPFLOW_ROOT' in os.environ: + del os.environ['CHIPFLOW_ROOT'] + + # Clear the cache again + if hasattr(ensure_chipflow_root, 'root'): + delattr(ensure_chipflow_root, 'root') + + def test_load_pinlock_missing_file(self): + """Test that loading fails gracefully when pins.lock doesn't exist""" + with tempfile.TemporaryDirectory() as tmpdir: + old_chipflow_root = os.environ.get('CHIPFLOW_ROOT') + os.environ['CHIPFLOW_ROOT'] = tmpdir + + # Clear the cache on ensure_chipflow_root + from chipflow.utils import ensure_chipflow_root + if hasattr(ensure_chipflow_root, 'root'): + delattr(ensure_chipflow_root, 'root') + + try: + # Should raise ChipFlowError when pins.lock doesn't exist + with self.assertRaises(ChipFlowError) as cm: + load_pinlock() + + self.assertIn("not found", str(cm.exception)) + self.assertIn("pins.lock", str(cm.exception)) + + finally: + if old_chipflow_root is not None: + os.environ['CHIPFLOW_ROOT'] = old_chipflow_root + elif 'CHIPFLOW_ROOT' in os.environ: + del os.environ['CHIPFLOW_ROOT'] + + # Clear the cache again + if hasattr(ensure_chipflow_root, 'root'): + delattr(ensure_chipflow_root, 'root') + + def test_load_pinlock_malformed_file(self): + """Test that loading fails gracefully with malformed pins.lock""" + with tempfile.TemporaryDirectory() as tmpdir: + old_chipflow_root = os.environ.get('CHIPFLOW_ROOT') + os.environ['CHIPFLOW_ROOT'] = tmpdir + + # Clear the cache on ensure_chipflow_root + from chipflow.utils import ensure_chipflow_root + if hasattr(ensure_chipflow_root, 'root'): + delattr(ensure_chipflow_root, 'root') + + try: + # Create a malformed lockfile + lockfile_path = Path(tmpdir) / 'pins.lock' + with open(lockfile_path, 'w') as f: + f.write('{"invalid": "json structure"}\n') + + # Should raise ChipFlowError when pins.lock is malformed + with self.assertRaises(ChipFlowError) as cm: + load_pinlock() + + self.assertIn("misformed", str(cm.exception)) + self.assertIn("pins.lock", str(cm.exception)) + + finally: + if old_chipflow_root is not None: + os.environ['CHIPFLOW_ROOT'] = old_chipflow_root + elif 'CHIPFLOW_ROOT' in os.environ: + del os.environ['CHIPFLOW_ROOT'] + + # Clear the cache again + if hasattr(ensure_chipflow_root, 'root'): + delattr(ensure_chipflow_root, 'root') \ No newline at end of file From 5fe9ea1c9493ffa721b231071459118fc0c09133 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 11 Nov 2025 19:01:33 +0000 Subject: [PATCH 6/7] Fix Pydantic model forward references and improve error messages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix issue where real-world pins.lock files were incorrectly reported as malformed due to unresolved forward references in Pydantic models. Changes: - Call model_rebuild() on Package and LockFile after importing all package types to resolve forward references - Chain validation errors using 'from e' to preserve detailed error information for debugging while showing user-friendly message The model_rebuild() calls are necessary because the lockfile models use forward references to package types (GAPackageDef, QuadPackageDef, etc.) that are only imported later in the __init__.py file. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- chipflow/packaging/__init__.py | 5 +++++ chipflow/packaging/utils.py | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/chipflow/packaging/__init__.py b/chipflow/packaging/__init__.py index b4837a86..d836f21f 100644 --- a/chipflow/packaging/__init__.py +++ b/chipflow/packaging/__init__.py @@ -81,6 +81,11 @@ PinCommand, ) +# Rebuild Pydantic models now that all package types are imported +# This resolves forward references in the lockfile models +Package.model_rebuild() +LockFile.model_rebuild() + # NOTE: This module is currently internal to the chipflow CLI. # The public API will be designed in a future PR after working through # real-world custom package examples. diff --git a/chipflow/packaging/utils.py b/chipflow/packaging/utils.py index 8ac76156..0630a1ad 100644 --- a/chipflow/packaging/utils.py +++ b/chipflow/packaging/utils.py @@ -36,11 +36,11 @@ def load_pinlock() -> LockFile: try: json = lockfile.read_text() return LockFile.model_validate_json(json) - except (pydantic.ValidationError, pydantic.PydanticUserError): + except (pydantic.ValidationError, pydantic.PydanticUserError) as e: raise ChipFlowError( "Lockfile `pins.lock` is misformed. " "Please remove and rerun `chipflow pin lock`" - ) + ) from e raise ChipFlowError("Lockfile `pins.lock` not found. Run `chipflow pin lock`") From 01bd3ae6808f88ed31b0aeccea2634b498e9b565 Mon Sep 17 00:00:00 2001 From: Rob Taylor Date: Tue, 11 Nov 2025 20:08:43 +0000 Subject: [PATCH 7/7] Keep top-level name as chipflow-lib --- chipflow/__init__.py | 2 +- pyproject.toml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/chipflow/__init__.py b/chipflow/__init__.py index 6756b2e4..968c4570 100644 --- a/chipflow/__init__.py +++ b/chipflow/__init__.py @@ -20,7 +20,7 @@ if TYPE_CHECKING: from .config import Config -__version__ = importlib.metadata.version("chipflow") +__version__ = importlib.metadata.version("chipflow-lib") # Maintain backward compatibility with underscore-prefixed names diff --git a/pyproject.toml b/pyproject.toml index d391ab3c..d54fc84f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ # Project metadata [project] -name = "chipflow" +name = "chipflow-lib" dynamic = ["version"] description = "ChipFlow common tools." authors = [