diff --git a/.gitattributes b/.gitattributes index 2994eba3..38934302 100644 --- a/.gitattributes +++ b/.gitattributes @@ -16,4 +16,3 @@ # Jupyter notebook *.ipynb text eol=lf - diff --git a/.gitignore b/.gitignore index 91d627a1..2376557b 100644 --- a/.gitignore +++ b/.gitignore @@ -19,4 +19,3 @@ __pycache__/ docs/_build .cache - diff --git a/chipflow_lib/software/drivers/spi.c b/chipflow_lib/software/drivers/spi.c index 32667b2e..951bcc0f 100644 --- a/chipflow_lib/software/drivers/spi.c +++ b/chipflow_lib/software/drivers/spi.c @@ -2,7 +2,7 @@ #include "spi.h" void spi_init(volatile spi_regs_t *spi, uint32_t divider) { - spi->divider = divider; + spi->divider = divider; spi->config = 0x02; // CS=0, SCK_EDGE=1, SCK_IDLE=0 } @@ -11,8 +11,8 @@ uint32_t spi_xfer(volatile spi_regs_t *spi, uint32_t data, uint32_t width, bool spi->send_data = data << (32U - width); while (!(spi->status & 0x1)) // wait for rx full ; - if (deselect) { - spi->config = ((width - 1) << 3) | 0x02; // CS=0, SCK_EDGE=1, SCK_IDLE=0 + if (deselect) { + spi->config = ((width - 1) << 3) | 0x02; // CS=0, SCK_EDGE=1, SCK_IDLE=0 } return spi->receive_data; } diff --git a/chipflow_lib/software/drivers/spiflash.S b/chipflow_lib/software/drivers/spiflash.S index 9e007531..4026be67 100644 --- a/chipflow_lib/software/drivers/spiflash.S +++ b/chipflow_lib/software/drivers/spiflash.S @@ -14,7 +14,7 @@ mv t3, ra # address of SPI ctrl reg li a0, 0xb0000000 # enter bypass mode -lbu t1, 0(a0) +lbu t1, 0(a0) ori t1, t1, 0x1 sb t1, 0(a0) call flashio_wait_bypass_ready @@ -40,7 +40,7 @@ j flashio_xfer flashio_done: # exit bypass mode -lbu t1, 0(a0) +lbu t1, 0(a0) andi t1, t1, 0xFE sb t1, 0(a0) diff --git a/chipflow_lib/software/drivers/spiflash.c b/chipflow_lib/software/drivers/spiflash.c index 42d20376..fbf7b101 100644 --- a/chipflow_lib/software/drivers/spiflash.c +++ b/chipflow_lib/software/drivers/spiflash.c @@ -39,7 +39,7 @@ bool spiflash_is_winbond(volatile spiflash_regs_t *flash) { if ((id & 0x00ff0000) == WINBOND_ID<<16) return true; else return false; } - + void spiflash_set_qspi_flag(volatile spiflash_regs_t *flash) { uint8_t buffer[8]; diff --git a/chipflow_lib/steps/__init__.py b/chipflow_lib/steps/__init__.py index e69de29b..82d44f47 100644 --- a/chipflow_lib/steps/__init__.py +++ b/chipflow_lib/steps/__init__.py @@ -0,0 +1,17 @@ +""" +Steps provide an extensible way to modify the `chipflow` command behavior for a given design +""" + +from abc import ABC + +class StepBase(ABC): + def __init__(self, config={}): + ... + + def build_cli_parser(self, parser): + "Build the cli parser for this step" + ... + + def run_cli(self, args): + "Called when this step's is used from `chipflow` command" + self.build() diff --git a/chipflow_lib/steps/board.py b/chipflow_lib/steps/board.py index adb59900..439b5800 100644 --- a/chipflow_lib/steps/board.py +++ b/chipflow_lib/steps/board.py @@ -1,6 +1,7 @@ # SPDX-License-Identifier: BSD-2-Clause +from . import StepBase -class BoardStep: +class BoardStep(StepBase): """Build the design for a board.""" def __init__(self, config, platform): @@ -13,4 +14,5 @@ def run_cli(self, args): self.build() def build(self): + "Build for the given platform" self.platform.build() diff --git a/chipflow_lib/steps/silicon.py b/chipflow_lib/steps/silicon.py index beb81f53..e89306bb 100644 --- a/chipflow_lib/steps/silicon.py +++ b/chipflow_lib/steps/silicon.py @@ -13,6 +13,7 @@ import dotenv from amaranth import * +from . import StepBase from .. import ChipFlowError from ..platforms import SiliconPlatform, top_interfaces, load_pinlock @@ -20,7 +21,7 @@ logger = logging.getLogger(__name__) -class SiliconTop(Elaboratable): +class SiliconTop(StepBase, Elaboratable): def __init__(self, config={}): self._config = config @@ -53,7 +54,7 @@ def elaborate(self, platform: SiliconPlatform): class SiliconStep: - """Prepare and submit the design for an ASIC.""" + """Step to Prepare and submit the design for an ASIC.""" def __init__(self, config): self.config = config diff --git a/chipflow_lib/steps/sim.py b/chipflow_lib/steps/sim.py index fbb16cb7..fdb6d875 100644 --- a/chipflow_lib/steps/sim.py +++ b/chipflow_lib/steps/sim.py @@ -3,8 +3,9 @@ from doit.cmd_base import ModuleTaskLoader from doit.doit_cmd import DoitMain +from . import StepBase -class SimStep: +class SimStep(StepBase): """Simulate the design.""" doit_build_module = None diff --git a/chipflow_lib/steps/software.py b/chipflow_lib/steps/software.py index b8bc45cb..957d2d82 100644 --- a/chipflow_lib/steps/software.py +++ b/chipflow_lib/steps/software.py @@ -3,9 +3,10 @@ from doit.cmd_base import ModuleTaskLoader from doit.doit_cmd import DoitMain +from . import StepBase -class SoftwareStep: - """Build the software.""" +class SoftwareStep(StepBase): + """Base step to build the software.""" doit_build_module = None @@ -19,7 +20,9 @@ def run_cli(self, args): self.build() def doit_build(self): + "Run the overridden doit_build_module" DoitMain(ModuleTaskLoader(self.doit_build_module)).run(["build_software"]) def build(self): + "Build the software for your design" self.doit_build() diff --git a/docs/_assets/api-key.png b/docs/_assets/api-key.png new file mode 100644 index 00000000..d57e8525 Binary files /dev/null and b/docs/_assets/api-key.png differ diff --git a/docs/_static/chipflow-logo.png b/docs/_assets/chipflow-logo.png similarity index 100% rename from docs/_static/chipflow-logo.png rename to docs/_assets/chipflow-logo.png diff --git a/docs/_static/chipflow-logo.svg b/docs/_assets/chipflow-logo.svg similarity index 100% rename from docs/_static/chipflow-logo.svg rename to docs/_assets/chipflow-logo.svg diff --git a/docs/_assets/github-desktop-open.png b/docs/_assets/github-desktop-open.png new file mode 100644 index 00000000..6557bf38 Binary files /dev/null and b/docs/_assets/github-desktop-open.png differ diff --git a/docs/_assets/open-github-desktop.png b/docs/_assets/open-github-desktop.png new file mode 100644 index 00000000..13a025a6 Binary files /dev/null and b/docs/_assets/open-github-desktop.png differ diff --git a/docs/_templates/autoapi/class.rst b/docs/_templates/autoapi/class.rst new file mode 100644 index 00000000..22d88d6e --- /dev/null +++ b/docs/_templates/autoapi/class.rst @@ -0,0 +1,23 @@ +{% if visible_methods or visible_attributes %} +.. rubric:: Overview + +{% set summary_methods = visible_methods|rejectattr("properties", "contains", "property")|list %} +{% set summary_attributes = visible_attributes + visible_methods|selectattr("properties", "contains", "property")|list %} + +{% if summary_attributes %} +{{ macros.auto_summary(summary_attributes, title="Attributes")|indent(3) }} +{% endif %} + +{% if summary_methods %} +{{ macros.auto_summary(summary_methods, title="Methods")|indent(3) }} +{% endif %} + +.. rubric:: Members + +{% for attribute in visible_attributes %} +{{ attribute.render()|indent(3) }} +{% endfor %} +{% for method in visible_methods %} +{{ method.render()|indent(3) }} +{% endfor %} +{% endif %} diff --git a/docs/_templates/autoapi/macros.rst b/docs/_templates/autoapi/macros.rst new file mode 100644 index 00000000..eec45866 --- /dev/null +++ b/docs/_templates/autoapi/macros.rst @@ -0,0 +1,43 @@ +{% macro _render_item_name(obj, sig=False) -%} +:py:obj:`{{ obj.name }} <{{ obj.id }}>` +{%- if sig -%} +\ ( +{%- for arg in obj.obj.args -%} +{%- if arg[0] %}{{ arg[0]|replace('*', '\*') }}{% endif -%}{{ arg[1] -}} +{%- if not loop.last %}, {% endif -%} +{%- endfor -%} +){%- endif -%} +{%- endmacro %} + +{% macro _item(obj, sig=False, label='') %} + * - {{ _render_item_name(obj, sig) }} + - {% if label %}:summarylabel:`{{ label }}` {% endif %}{% if obj.summary %}{{ obj.summary }}{% else %}\-{% endif +%} + +{% endmacro %} + +{% macro auto_summary(objs, title='') -%} +.. list-table:: {{ title }} + + :header-rows: 0 + :widths: auto + :class: summarytable + + {% for obj in objs -%} + {%- set sig = (obj.type in ['method', 'function'] and not 'property' in obj.properties) -%} + + {%- if 'property' in obj.properties -%} + {%- set label = 'prop' -%} + {%- elif 'classmethod' in obj.properties -%} + {%- set label = 'class' -%} + {%- elif 'abstractmethod' in obj.properties -%} + {%- set label = 'abc' -%} + {%- elif 'staticmethod' in obj.properties -%} + {%- set label = 'static' -%} + {%- else -%} + {%- set label = '' -%} + {%- endif -%} + + {{- _item(obj, sig=sig, label=label) -}} + {%- endfor -%} + +{% endmacro %} diff --git a/docs/_templates/autoapi/module.rst b/docs/_templates/autoapi/module.rst new file mode 100644 index 00000000..802a648b --- /dev/null +++ b/docs/_templates/autoapi/module.rst @@ -0,0 +1,19 @@ +{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %} +{% block classes scoped %} +{% if visible_classes %} +{{ macros.auto_summary(visible_classes, title="Classes") }} +{% endif %} +{% endblock %} + +{% block functions scoped %} +{% if visible_functions %} +{{ macros.auto_summary(visible_functions, title="Functions") }} +{% endif %} +{% endblock %} + +{% block attributes scoped %} +{% if visible_attributes %} +{{ macros.auto_summary(visible_attributes, title="Attributes") }} +{% endif %} +{% endblock %} +{% endif %} diff --git a/docs/chipflow-commands.rst b/docs/chipflow-commands.rst index c502d5a1..d5760491 100644 --- a/docs/chipflow-commands.rst +++ b/docs/chipflow-commands.rst @@ -41,4 +41,3 @@ A default simulation driver (the C++ code that runs the simulation) is included --------------------- If the design contains a CPU, the ``chipflow software build`` command is used to build test firmware for the target CPU. Which C source files to include, and any build options (like the target architecture or enabled RISC-V extensions) can be customised in the ``software/doit_build.py`` doit build script inside the user project. - diff --git a/docs/chipflow-toml-guide.rst b/docs/chipflow-toml-guide.rst index c46c3793..2e71e9ec 100644 --- a/docs/chipflow-toml-guide.rst +++ b/docs/chipflow-toml-guide.rst @@ -11,7 +11,7 @@ Let's start with a typical example: .. testcode:: :hide: - # Assert that example-chipflow.toml matches the current config schema. If + # 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 import _parse_config_file @@ -178,5 +178,3 @@ Note that in this context, the :term:type parameter can only be ``ground`` or `` This is a work in progress, and currently you can use the defaults provided by customer support. .. _Caravel Harness: https://caravel-harness.readthedocs.io/en/latest/ - - diff --git a/docs/conf.py b/docs/conf.py index b819d8c2..5ae5aa3c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,8 +37,18 @@ ] html_theme = 'furo' -html_logo = '_static/chipflow-logo.svg' +html_logo = '_assets/chipflow-logo.svg' html_title = "ChipFlow Platform Documentation" +html_static_path = ['_assets'] + +html_theme_options = { + "dark_css_variables": { + "admonition-font-size": "0.9 rem", + }, + "light_css_variables": { + "admonition-font-size": "0.9 rem", + }, +} autodoc_typehints = 'description' @@ -57,8 +67,11 @@ 'imported-members', ] -# Exclude autoapi templates -exclude_patterns = [autoapi_template_dir] +# Exclude autoapi templates and in-progress stuff +exclude_patterns = [ + autoapi_template_dir, + "unfinished", +] intersphinx_mapping = { 'py': ('https://docs.python.org/3/', None), diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 00000000..331c0be0 --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,183 @@ +Getting Started with ChipFlow +============================= + +Welcome to ChipFlow! This guide will help you get started with the ChipFlow IC design platform, which simplifies the process of designing, testing, and manufacturing custom silicon. + +What is ChipFlow? +----------------- + +ChipFlow is an integrated circuit design platform that combines modern hardware design tools with cloud-based manufacturing services. It enables you to: + +- Design custom silicon using `Python `__ and `Amaranth HDL `__ +- Simulate and verify your designs +- Prepare and submit your designs for manufacturing +- Manage the entire IC design workflow from a single platform + + +Prerequisites +------------- + +Before you begin: + +- Install the latest version of `Python `__. +- Ensure you have `Git command line tools `__ installed +- We recommend `Visual Studio Code `__ as a development environment +- `GitHub Desktop `__ is a great tool for workingh with Git repos + +Clone chipflow-examples +----------------------- + +.. note:: + If you’re familiar with the `Git `__ command line + then go clone [ChipFlow/chipflow-examples](https://github.com/ChipFlow/chipflow-examples) + and jump ahead to `Install the Dependencies`_ + + +If the git world is new to you, start up `GitHub +Desktop `__. The first time you launch +it you will be asked to sign in or create an account - we recommend you +take this moment to create a GitHub account if you don’t already have +one! + +Navigate to `the chipflow-examples repository `__ +and click the green ‘Code’ button at the top. Select ‘Open with GitHub Desktop’ and +then follow the prompts (N.B. your web browser may have a pop-up to +authorise opening an external app) + +|Image showing the link to click| + + +Once GitHub Desktop has cloned your repo you can click the button to +open it in VS Code: + +|Image showing where to click in GitHub Desktop to +open in VSCode| + + +Install the dependencies +------------------------ + +.. note:: + In VS Code, open up a terminal by pressing :kbd:`Command-p`: (Mac) or :kbd:`C-p` (Windows/Linux). + +We use `PDM `__ to manage our dependencies, so +this will need to be installed. Follow the `PDM install +instructions `__ for your OS. + +Once PDM is installed, make sure you are in the ``chipflow-examples`` +directory and then run: + +:: + + pdm lock -d + pdm install + +Set up the environment +---------------------- + +Generate your API key by going to https://build.chipflow.org/ and logging in with your GitHub account. + +Click on the 'User' menu, then on ‘Create/Refresh API Key’ Your new API key will appear at the +top. + +.. figure:: _assets/api-key.png + :alt: Image showing a newly generated API Key + + Image showing a newly generated API Key + +.. warning: + Copy it now, as you will not see it again! + +Next, create a file called ``.env`` at the top level in the +``chipflow-examples`` directory, containing the line below, substituting +your key from the page above: + +:: + + CHIPFLOW_API_KEY= + +Running a chip build +-------------------- + +First choose a design to test. Here we will use the ``minimal`` design. + +Change into the ``minimal`` directory in ``chipflow-examples`` to use +this design. Now we need to ‘lock’ our pins - the ChipFlow tooling will +then automatically allocate inputs and outputs from your design to pins +on the chip. + +:: + + pdm run chipflow pin lock + +We can now simulate and test the design by running: + +:: + + make sim-check + +You should see the simulation model being built and run - and a small +test firmware running on the simulated System-on-a-Chip (aided by our +local friendly cat!) + +:: + + pdm run chipflow sim + -- build_sim_cxxrtl + -- build_sim + pdm run chipflow software + -- gather_depencencies + -- build_software_elf + -- build_software + cd build/sim && ./sim_soc + 🐱: nyaa~! + SoC type: CA7F100F + Flash ID: CA7CA7FF + Quad mode + pdm run json-compare design/tests/events_reference.json build/sim/events.json + Event logs are identical + +Now you are ready to try building this design into a chip! To submit +your design to ChipFlow Platform where it will be built into GDS, run: + +:: + + pdm run chipflow silicon submit + +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'} + 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 +available at build URL that is returned, once it is complete. + +If you would like to get the build logs streamed to your command-line, +you can instead call: + +:: + + pdm run chipflow silicon submit --wait + +.. |Image showing the link to click| image:: _assets/open-github-desktop.png +.. |Image showing where to click in GitHub Desktop to open in VSCode| image:: _assets/github-desktop-open.png + + +Installation +------------ + +1. Clone the ChipFlow repository: + + .. code-block:: bash + + git clone https://github.com/ChipFlow/chipflow-lib.git + cd chipflow-lib + +2. Install dependencies using PDM: + + .. code-block:: bash + + pdm install diff --git a/docs/index.rst b/docs/index.rst index c82e0635..e24a57df 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,19 +1,23 @@ ChipFlow Library Documentation ------------------------------- +============================== -.. image: _static/chipflow-logo.svg +.. image:: _assets/chipflow-logo.svg :width: 200px :class: sd-m-auto :name: landing-page-logo -.. rubric: ChipFlow IC Design Platform +ChipFlow IC Design Platform +--------------------------- +ChipFlow is an open-source platform for designing, testing, and manufacturing custom silicon. +It provides a streamlined workflow from design to fabrication using Python and the Amaranth HDL. .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: User Guide + getting-started chipflow-toml-guide chipflow-commands - autoapi/index + API Reference diff --git a/docs/unfinished/advanced-configuration.rst b/docs/unfinished/advanced-configuration.rst new file mode 100644 index 00000000..08548c08 --- /dev/null +++ b/docs/unfinished/advanced-configuration.rst @@ -0,0 +1,279 @@ +Advanced Configuration +====================== + +This guide covers advanced configuration options for ChipFlow projects, including customizing clock domains, debugging features, and platform-specific settings. + +Advanced TOML Configuration +---------------------------- + +The ``chipflow.toml`` file supports many advanced configuration options beyond the basics covered in the getting started guide. + +Clock Domains +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ChipFlow supports multiple clock domains in your design: + +.. code-block:: toml + + [chipflow.clocks] + # Default clock for the design + default = "sys_clk" + + # Additional clock domains + pll = "pll_clk" + fast = "fast_clk" + +Each named clock must have a corresponding pad defined in the pads section: + +.. code-block:: toml + + [chipflow.silicon.pads] + sys_clk = { type = "clock", loc = "N1" } + pll_clk = { type = "clock", loc = "N2" } + fast_clk = { type = "clock", loc = "N3" } + +Debugging Features +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +ChipFlow provides debugging options for silicon designs: + +.. code-block:: toml + + [chipflow.silicon.debug] + # Heartbeat LED to verify clock/reset functionality + heartbeat = true + + # Internal logic analyzer + logic_analyzer = true + logic_analyzer_depth = 1024 + + # JTAG debug access + jtag = true + +Pin Locking +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To prevent pin assignments from changing accidentally, ChipFlow supports a pin locking mechanism: + +.. code-block:: toml + + [chipflow.pin_lock] + # Enable pin locking + enabled = true + + # Lock file path (relative to project root) + file = "pins.lock" + +Once locked, pin assignments can only be changed by explicitly updating the lock file. + +Resource Constraints +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For silicon designs, you can specify resource constraints: + +.. code-block:: toml + + [chipflow.silicon.constraints] + # Maximum die area in mm² + max_area = 1.0 + + # Maximum power budget in mW + max_power = 100 + + # Target clock frequency in MHz + target_frequency = 100 + +Custom Top-Level Components +--------------------------- + +You can specify custom top-level components for your design: + +.. code-block:: toml + + [chipflow.top] + # Main SoC component + soc = "my_design.components:MySoC" + + # Additional top-level components + uart = "my_design.peripherals:UART" + spi = "my_design.peripherals:SPI" + +Each component should be a fully qualified Python path to a class that implements the Amaranth Component interface. + +Platform-Specific Configuration +------------------------------- + +Different target platforms may require specific configuration options: + +FPGA Board Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: toml + + [chipflow.board] + # Target FPGA board + target = "ulx3s" + + # Board-specific options + [chipflow.board.options] + size = "85k" # FPGA size + spi_flash = true + sdram = true + +Silicon Process Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: toml + + [chipflow.silicon] + # Target manufacturing process + process = "gf130bcd" + + # Process-specific options + [chipflow.silicon.options] + metal_stack = "6LM" + io_voltage = 3.3 + core_voltage = 1.2 + +External Dependencies +--------------------- + +ChipFlow can integrate with external dependencies: + +.. code-block:: toml + + [chipflow.deps] + # External IP cores + cores = [ + "github.com/chipflow/uart-core@v1.0.0", + "github.com/chipflow/spi-core@v2.1.0" + ] + + # External library paths + [chipflow.deps.libs] + amaranth_cores = "amaranth_cores" + chisel_cores = "chisel_cores" + +Testing Configuration +--------------------- + +For more complex testing setups: + +.. code-block:: toml + + [chipflow.sim] + # Testbench implementation + testbench = "my_design.tb:TestBench" + + # Custom simulation flags + [chipflow.sim.options] + trace_all = true + cycles = 10000 + seed = 12345 + + # Test vectors + [chipflow.sim.test_vectors] + path = "test_vectors.json" + format = "json" + +Documentation Configuration +--------------------------- + +To generate custom documentation for your design: + +.. code-block:: toml + + [chipflow.docs] + # Documentation output directory + output = "docs/build" + + # Block diagram generation + block_diagram = true + + # Custom templates + template_dir = "docs/templates" + + # Additional documentation files + extra_files = [ + "docs/architecture.md", + "docs/api.md" + ] + +Environment Variables +--------------------- + +Several environment variables can be used to customize ChipFlow's behavior: + +- ``CHIPFLOW_ROOT``: Root directory of your project, which must contain `chipflow.toml` +- ``CHIPFLOW_API_KEY``: API key secret for ChipFlow services +- ``CHIPFLOW_API_ENDPOINT``: Custom API endpoint (defaults to production - https://build.chipflow.org) +- ``CHIPFLOW_DEBUG``: Enable debug logging (set to "1") + +Using Custom Steps +------------------ + +To implement a custom step implementation: + +1. Create a new class that inherits from the base step: + + .. code-block:: python + + from chipflow_lib.steps.silicon import SiliconStep + + class CustomSiliconStep(SiliconStep): + def prepare(self): + # Custom preparation logic + result = super().prepare() + # Additional processing + return result + + def submit(self, rtlil_path, *, dry_run=False): + # Custom submission logic + if dry_run: + # Custom dry run behavior + return + + # Custom submission implementation + # ... + +2. Reference your custom step in chipflow.toml: + + .. code-block:: toml + + [chipflow.steps] + silicon = "my_design.custom_steps:CustomSiliconStep" + +3. Your custom step will be used when invoking the corresponding command. + +Advanced Pin Configurations +--------------------------- + +For complex pin requirements: + +.. code-block:: toml + + [chipflow.silicon.pads] + # Differential pair + lvds_in_p = { type = "i", loc = "N4", diff_pair = "positive" } + lvds_in_n = { type = "i", loc = "N5", diff_pair = "negative" } + + # Multiple bits of a bus + data[0] = { type = "io", loc = "S1" } + data[1] = { type = "io", loc = "S2" } + data[2] = { type = "io", loc = "S3" } + data[3] = { type = "io", loc = "S4" } + + # Special I/O modes + spi_clk = { type = "o", loc = "E1", drive = "8mA", slew = "fast" } + i2c_sda = { type = "io", loc = "W1", pull = "up", schmitt = true } + +Integration with Version Control +-------------------------------- + +ChipFlow integrates with Git for version tracking: + +1. Design submissions include Git commit hash for tracking +2. ChipFlow warns if submitting from a dirty Git tree +3. Version information is embedded in the manufacturing metadata + +For CI/CD integration, call the `chipflow` command as usual, and make sure to set your `CHIPFLOW_API_KEY` using your CI providers' secret handling. diff --git a/docs/unfinished/create-project.rst b/docs/unfinished/create-project.rst new file mode 100644 index 00000000..534df6f7 --- /dev/null +++ b/docs/unfinished/create-project.rst @@ -0,0 +1,122 @@ +Creating Your First Project +--------------------------- + +1. Create a new directory for your project: + + .. code-block:: bash + + mkdir my-chipflow-project + cd my-chipflow-project + +2. Initialize your project: + + .. code-block:: bash + + pdm init + pdm add chipflow-lib + +3. Create a basic `chipflow.toml` configuration file: + + .. code-block:: toml + + [chipflow] + project_name = "my-first-chip" + + [chipflow.clocks] + default = "sys_clk" + + [chipflow.resets] + default = "sys_rst_n" + + [chipflow.silicon] + process = "gf130bcd" + package = "pga144" + + [chipflow.silicon.debug] + heartbeat = true + + [chipflow.silicon.pads] + sys_clk = { type = "clock", loc = "N1" } + sys_rst_n = { type = "reset", loc = "N2" } + +4. Create a simple design: + + Create a file called `design.py` with your hardware design. Here's a simple example: + + .. code-block:: python + + from amaranth import * + from amaranth.lib.wiring import Component, In, Out + + class Blinky(Component): + """A simple LED blinker""" + + def __init__(self): + super().__init__() + self.led = Out(1) + + def elaborate(self, platform): + m = Module() + + # 24-bit counter (approx 1Hz with 16MHz clock) + counter = Signal(24) + m.d.sync += counter.eq(counter + 1) + + # Connect the counter's most significant bit to the LED + m.d.comb += self.led.eq(counter[-1]) + + return m + + class MyTop(Component): + """Top-level design""" + + def __init__(self): + super().__init__() + self.blinky = Blinky() + + def elaborate(self, platform): + m = Module() + + m.submodules.blinky = self.blinky + + # Wire up the blinky LED to an output pin + led_out = platform.request("led") + m.d.comb += led_out.eq(self.blinky.led) + + return m + +Workflow Steps +-------------- + +ChipFlow organizes the design process into distinct steps: + +1. **Simulation**: Test your design in a virtual environment +2. **Board**: Prepare your design for FPGA prototyping +3. **Silicon**: Prepare and submit your design for manufacturing + +Each step is configured and executed through the ChipFlow CLI: + +.. code-block:: bash + + # Simulate your design + pdm chipflow sim prepare + + # Build for FPGA + pdm chipflow board prepare + + # Prepare for silicon manufacturing + pdm chipflow silicon prepare + + # Submit for manufacturing + pdm chipflow silicon submit + +Next Steps +---------- + +Now that you've created your first ChipFlow project, you can: + +- Read the :doc:`workflows` guide to understand the detailed workflow +- Learn about the :doc:`chipflow-toml-guide` for configuring your project +- Explore :doc:`advanced-configuration` options + +For more examples and detailed documentation, visit the `ChipFlow GitHub repository `_. diff --git a/docs/unfinished/workflows.rst b/docs/unfinished/workflows.rst new file mode 100644 index 00000000..1d75a569 --- /dev/null +++ b/docs/unfinished/workflows.rst @@ -0,0 +1,220 @@ +ChipFlow Workflows +================== + +This guide details the different workflows available in the ChipFlow platform, from simulation to silicon manufacturing. + +Overview +-------- + +ChipFlow organizes the IC design process into several logical steps, each addressing a different phase of development: + +1. **Simulation**: Virtual testing of your design +2. **Board**: FPGA prototyping +3. **Silicon**: Manufacturing preparation and submission + +Each workflow is implemented as a "step" in the ChipFlow library and can be accessed through the CLI tool. + +Simulation Workflow +-------------------- + +The simulation workflow allows you to test your design in a virtual environment before committing to hardware. + +**Commands:** + +.. code-block:: bash + + # Prepare the simulation environment + pdm chipflow sim prepare + + # Run the simulation tests + pdm chipflow sim run + +**Key Configuration:** + +In your chipflow.toml file, you can specify simulation-specific settings: + +.. code-block:: toml + + [chipflow.sim] + # Test-bench top module + testbench = "my_design.tb:TestBench" + + # Simulation duration in clock cycles + cycles = 10000 + + # Optional VCD waveform dump file + vcd = "sim.vcd" + +**Building a Test Bench:** + +Create a test bench file (e.g., `tb.py`) with a class that implements the simulation logic: + +.. code-block:: python + + from amaranth import * + from amaranth.sim import Simulator + from my_design import MyDesign + + class TestBench: + def __init__(self): + self.dut = MyDesign() + + def elaborate(self, platform): + m = Module() + m.submodules.dut = self.dut + + # Add stimulus logic here + + return m + + def sim_traces(self): + # Return signals to trace in simulation + return [self.dut.clk, self.dut.reset, self.dut.output] + + def sim_test(self, sim): + # Stimulus generation + def process(): + # Reset the design + yield self.dut.reset.eq(1) + yield Tick() + yield self.dut.reset.eq(0) + + # Run test vectors + for i in range(100): + yield self.dut.input.eq(i) + yield Tick() + output = yield self.dut.output + print(f"Input: {i}, Output: {output}") + + sim.add_process(process) + +Board Workflow +---------------- + +The board workflow prepares your design for FPGA deployment, which is useful for prototyping before committing to silicon. + +**Commands:** + +.. code-block:: bash + + # Prepare the design for FPGA deployment + pdm chipflow board prepare + + # Deploy to FPGA + pdm chipflow board deploy + +**Key Configuration:** + +.. code-block:: toml + + [chipflow.board] + # Target FPGA board + target = "tangnano9k" # or "icebreaker", "ulx3s", etc. + + # Pin mappings for your design + [chipflow.board.pins] + clk = "CLK" + reset = "BTN1" + leds[0] = "LED1" + leds[1] = "LED2" + +Silicon Workflow +----------------- + +The silicon workflow is the path to producing actual ASICs through ChipFlow's manufacturing services. + +**Commands:** + +.. code-block:: bash + + # Prepare design for manufacturing + pdm chipflow silicon prepare + + # Validate the design against manufacturing rules + pdm chipflow silicon validate + + # Submit the design for manufacturing + pdm chipflow silicon submit + + # Check the status of a submitted design + pdm chipflow silicon status + +**Key Configuration:** + +The silicon workflow requires detailed configuration in your chipflow.toml file: + +.. code-block:: toml + + [chipflow.silicon] + # Target manufacturing process + process = "gf130bcd" + + # Physical package for the chip + package = "cf20" + + # Optional debugging features + [chipflow.silicon.debug] + heartbeat = true + + # Pin assignments + [chipflow.silicon.pads] + sys_clk = { type = "clock", loc = "N1" } + sys_rst_n = { type = "reset", loc = "N2" } + led = { type = "o", loc = "N3" } + + # Power connections + [chipflow.silicon.power] + vdd = { type = "power", loc = "E1" } + vss = { type = "ground", loc = "E2" } + +**Submission Process:** + +When submitting a design for manufacturing: + +1. ChipFlow validates your design against process design rules +2. The design is converted to the necessary formats for manufacturing +3. You receive a quote and timeline for production +4. Once approved, the design enters the manufacturing queue +5. You receive updates on the progress of your chip + +Authentication for Submission +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To submit a design, you'll need to set up authentication: + +1. Create a `.env` file in your project directory with your API keys: + + .. code-block:: bash + + CHIPFLOW_API_KEY=your_key_secret + +2. Alternatively, set these as environment variables before submission: + + .. code-block:: bash + + export CHIPFLOW_API_KEY_ID=your_key_id + export CHIPFLOW_API_KEY_SECRET=your_key_secret + pdm chipflow silicon submit + +Customizing Workflows +--------------------- + +You can customize any workflow by creating your own implementation of the standard steps: + +.. code-block:: toml + + [chipflow.steps] + # Custom implementation of the silicon step + silicon = "my_design.steps.silicon:MySiliconStep" + + # Custom implementation of the simulation step + sim = "my_design.steps.sim:MySimStep" + +Your custom step class should inherit from the corresponding base class in `chipflow_lib.steps` and override the necessary methods. + +Next Steps +---------- + +- Learn about :doc:`advanced-configuration` options +- Explore the :doc:`chipflow-toml-guide` for detailed configuration options +- See API documentation for :doc:`autoapi/steps/index` to create custom workflow steps diff --git a/pyproject.toml b/pyproject.toml index b7c4a4e8..233b1f39 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -72,7 +72,7 @@ test-docs.cmd = "sphinx-build -b doctest docs/ docs/_build" lint.cmd = "ruff check" docs.cmd = "sphinx-build docs/ docs/_build/ -W --keep-going" test-silicon.cmd = "pytest tests/test_silicon_platform.py tests/test_silicon_platform_additional.py tests/test_silicon_platform_amaranth.py tests/test_silicon_platform_build.py tests/test_silicon_platform_port.py --cov=chipflow_lib.platforms.silicon --cov-report=term" - +chipflow.cmd = "chipflow" [dependency-groups] lint = [ diff --git a/tests/test_utils.py b/tests/test_utils.py index e0f77280..2aab4578 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -1,7 +1,7 @@ # SPDX-License-Identifier: BSD-2-Clause import itertools import logging -import pytest #noqa +import pytest #noqa from pprint import pformat @@ -102,4 +102,4 @@ def test_pin_annotation_as_json(): print(f"json_output: {json_output}") # Debug print using print() assert isinstance(json_output, dict) assert json_output["direction"] == "io" - assert json_output["width"] == 8 \ No newline at end of file + assert json_output["width"] == 8