diff --git a/docs/chipflow-commands.rst b/docs/chipflow-commands.rst new file mode 100644 index 00000000..c502d5a1 --- /dev/null +++ b/docs/chipflow-commands.rst @@ -0,0 +1,44 @@ +The ``chipflow`` command +========================== + +The ``chipflow`` tool enables you to simulate your design or submit it to the ChipFlow cloud build service. +It implements several subcommands, which can be customised or added to in the ``steps`` section of :ref:`chipflow.toml`. + +.. _chipflow_toml: chipflow-toml-guide.rst + +``chipflow pin lock`` +--------------------- + +The ``chipflow pin lock`` command performs pin locking for the current design. +For every new top level interface with containing external pins with a ``PinSignature`` that is discovered, the necessary number of package pins is allocated and the mapping saved in the ``pins.lock`` file. +This means that, unless the ``pins.lock`` file is deleted or manually modified, the pin assignments of all existing pins will always remain the same. + +``chipflow silicon`` +-------------------- + +The ``chipflow silicon`` subcommand is used to send the design to the cloud builder for build and tapeout. In general, it would be run inside GitHub Actions as part of a CI job. + + - ``chipflow silicon prepare`` links the design, including all Amaranth modules and any external Verilog components, into a single RTLIL file that is ready to be sent to the cloud builder. + - ``chipflow silicon submit`` sends the linked design along with the ``pins.lock`` file containing pinout information to the ChipFlow cloud service for the build. With the ``--dry-run`` argument, it can be used for a local test that the design is ready to be submitted. + +Submitting the design to the cloud requires the ``CHIPFLOW_API_KEY`` environment variable to be set with a valid API key obtained from the cloud interface. + +``chipflow sim`` +---------------- + +The ``chipflow sim build`` command is used to build a CXXRTL simulation of the design; converting the design to a fast compiled C++ format along with C++ models of any peripherals. + +Extra C++ model files for the simulation, and any custom build steps required, can be added to the ``sim/doit_build.py`` `doit `_ build script inside the user project. + +A default simulation driver (the C++ code that runs the simulation) is included as `main.cc `_ in the example projects. This code: + + - Instantiates the user design; and the simulation models for the peripherals (SPI flash, UART and GPIO) + - Initialises the CXXRTL debug agent, which is required to perform debugging with the `RTL Debugger `_ VS Code extension + - Configures input and output JSON files for stimuli and results respectively (for automated integration testing) + - Runs the design for 3,000,000 clock cycles + +``chipflow software`` +--------------------- + +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 15534832..c46c3793 100644 --- a/docs/chipflow-toml-guide.rst +++ b/docs/chipflow-toml-guide.rst @@ -48,6 +48,8 @@ The instance name is the name the python object will be given in your design, an The module class path offers a way to locate Python objects as entry points. It consists of a module's :term:`qualified name` followed by a colon (:) and then the :term:`qualified name` of the class within that module. +.. _chipflow-toml-steps: + ``[chipflow.steps]`` -------------------- diff --git a/docs/index.rst b/docs/index.rst index bfe16a3e..c82e0635 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,4 +15,5 @@ ChipFlow Library Documentation :caption: Contents: chipflow-toml-guide + chipflow-commands autoapi/index