diff --git a/.github/docs-review-prompt.md b/.github/docs-review-prompt.md new file mode 100644 index 0000000..a128676 --- /dev/null +++ b/.github/docs-review-prompt.md @@ -0,0 +1,78 @@ +# Documentation Review Prompt + +Review the ChipFlow documentation for quality, accuracy, and consistency. + +## Context + +ChipFlow is a platform for designing and building hardware systems (SoCs) using Python and Amaranth HDL. The documentation covers: + +- **chipflow-lib**: The main Python library and CLI tool +- **amaranth**: The hardware description language +- **amaranth-soc**: System-on-Chip design library +- **chipflow-examples**: Example designs (minimal SoC, MCU SoC) + +## Review Criteria + +### 1. Technical Accuracy + +- Do code examples actually work with the current API? +- Are command-line examples correct (`pdm chipflow ...`, etc.)? +- Are configuration file examples (`chipflow.toml`) valid? +- Do cross-references to other documentation sections resolve correctly? +- Are version numbers and URLs up to date? + +### 2. Consistency + +- Is terminology used consistently? (e.g., "SoC" vs "System-on-Chip", "pin" vs "port") +- Are code style conventions consistent across examples? +- Do similar concepts use similar explanations across different pages? +- Are file paths and directory structures described consistently? + +### 3. Flow and Organization + +- Does the getting-started guide provide a clear path for new users? +- Are prerequisites clearly stated before each section? +- Do topics build logically on each other? +- Are advanced topics appropriately separated from beginner content? +- Is the navigation structure (toctree) logical? + +### 4. Completeness + +- Are all major features documented? +- Are error messages and troubleshooting covered? +- Are environment variables and configuration options documented? +- Are there gaps in the examples that would confuse users? + +### 5. Links and References + +- Do internal cross-references (`:doc:`, `:ref:`, `:class:`) work? +- Are external URLs valid and pointing to the correct resources? +- Is the relationship between chipflow-lib, amaranth, and amaranth-soc clear? + +## Output Format + +Provide your findings in this structure: + +``` +## Summary +[Overall assessment of documentation quality - 1-2 sentences] + +## Issues Found + +### Critical +[Issues that would prevent users from following the documentation] + +### Major +[Significant inaccuracies or confusing sections] + +### Minor +[Small improvements or nitpicks] + +## Recommendations +[Top 3-5 actionable improvements] + +## Files Reviewed +[List of files examined] +``` + +If no issues are found in a category, note "None found" rather than omitting it. diff --git a/.github/workflows/docs-review.yml b/.github/workflows/docs-review.yml new file mode 100644 index 0000000..3fad9ef --- /dev/null +++ b/.github/workflows/docs-review.yml @@ -0,0 +1,175 @@ +name: Documentation Review + +on: + pull_request: + paths: + - 'docs/**' + - '*.md' + push: + branches: + - main + paths: + - 'docs/**' + - '*.md' + workflow_dispatch: + +jobs: + review-docs: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install PDM + run: pip install pdm + + - name: Install dependencies + run: pdm install + + - name: Build documentation + run: pdm run docs + continue-on-error: true + + - name: Set up Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Review documentation with Claude Code + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + # Create the review prompt + cat > /tmp/review-prompt.txt << 'PROMPT_EOF' + Review the ChipFlow documentation for quality, accuracy, and consistency. + + ## Context + ChipFlow is a platform for designing and building hardware systems (SoCs) using Python and Amaranth HDL. + + ## Review the following: + + 1. **Technical Accuracy** + - Do code examples work with the current API? + - Are command-line examples correct? + - Are configuration file examples valid? + + 2. **Consistency** + - Is terminology used consistently? + - Are code style conventions consistent? + + 3. **Flow and Organization** + - Does the getting-started guide provide a clear path? + - Do topics build logically on each other? + + 4. **Completeness** + - Are all major features documented? + - Are there gaps that would confuse users? + + ## Output Format + Provide findings as: + + ## Summary + [1-2 sentence assessment] + + ## Issues Found + + ### Critical + [Issues preventing users from following docs] + + ### Major + [Significant inaccuracies] + + ### Minor + [Small improvements] + + ## Recommendations + [Top 3-5 actionable improvements] + + Focus on docs/source/ and .md files. Report actual issues only. + PROMPT_EOF + + # Run Claude Code in print mode (non-interactive) + claude --print "$(cat /tmp/review-prompt.txt)" > review-results.txt 2>&1 || true + + # Show the results + cat review-results.txt + + - name: Process review results + id: process-review + run: | + if [ -f review-results.txt ] && [ -s review-results.txt ]; then + # Use heredoc to handle multiline output + { + echo 'review<> $GITHUB_OUTPUT + else + echo "review=Documentation review did not produce output" >> $GITHUB_OUTPUT + fi + + - name: Comment on PR + if: github.event_name == 'pull_request' + uses: actions/github-script@v7 + with: + script: | + const review = process.env.REVIEW_CONTENT; + + // Find existing comment from this workflow + const { data: comments } = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + }); + + const botComment = comments.find(comment => + comment.user.type === 'Bot' && + comment.body.includes('## 📚 Documentation Review') + ); + + const body = `## 📚 Documentation Review + + ${review} + + --- + *This review was automatically generated by Claude Code*`; + + if (botComment) { + await github.rest.issues.updateComment({ + owner: context.repo.owner, + repo: context.repo.repo, + comment_id: botComment.id, + body: body + }); + } else { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: body + }); + } + env: + REVIEW_CONTENT: ${{ steps.process-review.outputs.review }} + + - name: Upload review results + uses: actions/upload-artifact@v4 + if: always() + with: + name: docs-review-results + path: review-results.txt + retention-days: 30 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..569dbd6 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,54 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +ChipFlow is a platform for designing and building hardware systems, particularly System-on-Chips (SoCs), using Python. This repository contains documentation for the ChipFlow ecosystem, which includes: + +- Hardware description libraries (Amaranth HDL) +- Support for SoC design (amaranth-soc) +- ChipFlow-specific libraries and platforms +- Example designs (minimal SoC, MCU SoC) + +## Build Commands + +- **Install dependencies**: `pdm install` +- **Build documentation**: `pdm run docs` +- **Auto-rebuild documentation**: `pdm run autodocs` +- **View documentation**: Visit http://localhost:8000 when running autodocs + +## Testing + +- **Python tests**: `pytest` +- **Run specific test**: `pytest tests/test_file.py::test_function_name` + +## Code Style Guidelines + +- **Python**: PEP-8 style, Python 3.10+ +- **Linting**: `ruff check .` +- **Type checking**: `pyright` + +## Repository Structure + +- **docs/source/**: Documentation source files in reStructuredText format +- **vendor/**: Cloned repositories for documentation integration + - amaranth: Hardware description library + - amaranth-soc: SoC design library + - chipflow-lib: ChipFlow platform libraries +- **chipflow-examples/**: Example ChipFlow designs + - minimal/: Minimal SoC with RISC-V core + - mcu_soc/: MCU-style SoC with peripherals + +## Documentation Management + +The `copy-docs.sh` script clones and integrates documentation from: +- amaranth-lang/amaranth +- chipflow/amaranth-soc +- chipflow/chipflow-lib + +Documentation is built using Sphinx with extensions for: +- Multi-project documentation +- API documentation +- Custom styling +- Interactive elements \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index e9ceeb6..1c0670b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -7,7 +7,7 @@ top_path = Path('../../') sys.path.append(str((top_path / 'tools').absolute())) -from tools import copy_docs +from copy_docs import copy_docs # Repos we will be assembling repos = [ @@ -22,8 +22,29 @@ # add our repos to path for r in repo_list: + print(f"copy_docs: Adding {str(r)} to sys.path") sys.path.append(str(r)) +# Create platform-api.rst in docs/source/ (outside chipflow-lib to avoid copy_docs overwriting) +# This file points to the autoapi-generated index +Path('platform-api.rst').write_text("""Platform API Reference +====================== + +This section provides the API reference for the ChipFlow platform library. + +.. toctree:: + :maxdepth: 3 + + chipflow-lib/autoapi/chipflow/index +""") + +# Update chipflow-lib/index.rst to point to the platform-api.rst outside chipflow-lib/ +chipflow_lib_index = Path('chipflow-lib/index.rst') +if chipflow_lib_index.exists(): + content = chipflow_lib_index.read_text() + content = content.replace('platform-api', '/platform-api') + chipflow_lib_index.write_text(content) + # -- Project information project = 'ChipFlow' @@ -41,7 +62,7 @@ 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx_copybutton', - 'myst_parser', + # 'myst_parser', 'sphinx.ext.todo', 'sphinx.ext.napoleon', 'sphinx.ext.autodoc', @@ -50,6 +71,7 @@ 'sphinxcontrib.yowasp_wavedrom', 'sphinxext.rediraffe', 'autoapi.extension', + 'sphinx_design', ] rst_prolog = """ @@ -63,6 +85,11 @@ :language: python """ +rst_epilog = """ +.. |required| replace:: :bdg-primary-line:`Required` +.. |optional| replace:: :bdg-secondary-line:`Optional` +""" + html_theme = 'furo' html_logo = 'chipflow-lib/_assets/chipflow-logo.svg' html_title = "ChipFlow Platform Documentation" @@ -93,11 +120,17 @@ 'imported-members', ] autoapi_root = "chipflow-lib/autoapi" +autoapi_add_toctree_entry = False # We'll manually add to toctree in platform-api.rst +autoapi_ignore = [ + "*/chipflow_lib/*", # Backward compatibility shim +] # Exclude autoapi templates and in-progress stuff exclude_patterns = [ autoapi_template_dir, "chipflow-lib/unfinished", + "chipflow-lib/UNFINISHED_IDEAS.md", + "chipflow-lib/platform-api.rst", # We use /platform-api.rst at root instead "amaranth/cover.rst", "amaranth-soc/cover.rst", ] diff --git a/docs/source/examples/getting-started.rst b/docs/source/examples/getting-started.rst new file mode 100644 index 0000000..8314c77 --- /dev/null +++ b/docs/source/examples/getting-started.rst @@ -0,0 +1,131 @@ +Getting Started with ChipFlow Examples +====================================== + +This guide will walk you through setting up the ChipFlow examples repository and running your first chip build. + +Prerequisites +------------- + +Before you begin, ensure you have the following installed: + +- **Python 3.11+**: `Python Downloads `_ +- **Git**: `Git Downloads `_ +- **PDM**: `PDM Installation `_ + +We also recommend: + +- **VS Code**: `VS Code Downloads `_ +- **GitHub Desktop**: `GitHub Desktop Downloads `_ + +Clone the Repository +-------------------- + +Using Git command line: + +.. code-block:: bash + + git clone https://github.com/ChipFlow/chipflow-examples.git + cd chipflow-examples + +Or using GitHub Desktop: + +1. Go to the `chipflow-examples repository `_ +2. Click the green "Code" button +3. Select "Open with GitHub Desktop" +4. Follow the prompts to clone + +Install Dependencies +-------------------- + +Once you have the repository cloned, install the dependencies: + +.. code-block:: bash + + cd chipflow-examples + pdm lock -d + pdm install + +Set Up Your API Key +------------------- + +To submit designs to the ChipFlow cloud builder, you need an API key: + +1. Go to https://build.chipflow.com/user/detail +2. Click "Create/Refresh API Key" +3. Copy your new API key (you won't see it again!) + +Create a ``.env`` file in the ``chipflow-examples`` directory: + +.. code-block:: bash + + echo "CHIPFLOW_API_KEY=your_api_key_here" > .env + +Replace ``your_api_key_here`` with your actual API key. + +Running Your First Build +------------------------ + +Let's try the ``minimal`` example: + +.. code-block:: bash + + cd minimal + +First, lock the pin assignments: + +.. code-block:: bash + + pdm chipflow pin lock + +Run the simulation to test the design: + +.. code-block:: bash + + pdm sim-check + +You should see the simulation being built and run, with test output like: + +.. code-block:: text + + -- build_sim_cxxrtl + -- build_sim + pdm chipflow software + -- gather_dependencies + -- build_software_elf + -- build_software + cd build/sim && ./sim_soc + SoC type: CA7F100F + Flash ID: CA7CA7FF + Quad mode + Event logs are identical + +Submitting to ChipFlow +---------------------- + +Once your simulation passes, submit your design to be built: + +.. code-block:: bash + + pdm submit + +This returns a build URL where you can monitor progress: + +.. code-block:: text + + 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.chipflow.com/build/3f51a69c-b3e3-4fd3-88fd-52826ac5e5dd + +To stream build logs to your terminal: + +.. code-block:: bash + + pdm submit --wait + +Next Steps +---------- + +- Explore the :doc:`minimal` example to understand the basic structure +- Try the :doc:`mcu-soc` example for a more complete design +- Read the :doc:`../chipflow-lib/chipflow-toml-guide` to understand configuration options +- Check the :doc:`../chipflow-lib/simulation-guide` for simulation details diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst new file mode 100644 index 0000000..2eb6e14 --- /dev/null +++ b/docs/source/examples/index.rst @@ -0,0 +1,33 @@ +ChipFlow Examples +================= + +The `chipflow-examples `_ repository contains example designs demonstrating how to build chips using the ChipFlow platform. + +These examples show you how to: + +- Structure a ChipFlow project +- Configure your design with ``chipflow.toml`` +- Run simulations to test your design +- Submit your design to the ChipFlow cloud builder + +Available Examples +------------------ + +**Minimal SoC** (:doc:`minimal`) + A minimal System-on-Chip with a RISC-V core. This is the simplest starting point for understanding ChipFlow projects. + +**MCU SoC** (:doc:`mcu-soc`) + A more complete MCU-style SoC with additional peripherals. Demonstrates a more realistic design with GPIO, UART, and other interfaces. + +Getting Started +--------------- + +See :doc:`getting-started` for instructions on how to clone the examples repository and run your first chip build. + +.. toctree:: + :maxdepth: 2 + :hidden: + + getting-started + minimal + mcu-soc diff --git a/docs/source/examples/mcu-soc.rst b/docs/source/examples/mcu-soc.rst new file mode 100644 index 0000000..9d5f110 --- /dev/null +++ b/docs/source/examples/mcu-soc.rst @@ -0,0 +1,190 @@ +MCU SoC Example +=============== + +The ``mcu_soc`` example demonstrates a more complete microcontroller-style System-on-Chip with multiple peripherals, targeting the IHP SG13G2 process. + +Overview +-------- + +This example creates a full-featured MCU with: + +- **CV32E40P RISC-V CPU** - A 32-bit RISC-V processor with debug support +- **JTAG Debug Module** - Full debug capabilities via JTAG interface +- **QSPI Flash** - External flash memory for code storage +- **SRAM** - 2KB of on-chip RAM +- **Multiple GPIO Banks** - 2 banks of 8-bit GPIO (16 total) +- **Multiple UARTs** - 2 UART interfaces +- **SPI Controllers** - 3 user SPI interfaces +- **I2C Controllers** - 2 I2C bus interfaces +- **PWM Controllers** - 10 motor PWM outputs + +Project Structure +----------------- + +.. code-block:: text + + mcu_soc/ + ├── chipflow.toml # Project configuration + ├── design/ + │ ├── design.py # Main SoC design + │ ├── ips/ # Custom IP cores (PWM, etc.) + │ ├── openocd/ # OpenOCD debug configuration + │ ├── software/ # Firmware source code + │ ├── steps/ # Custom build steps + │ └── tests/ # Test reference data + └── README.md + +Configuration +------------- + +The ``chipflow.toml`` targets the IHP SG13G2 process with a PGA144 package: + +.. code-block:: toml + + [chipflow] + project_name = "chipflow-examples" + + [chipflow.top] + soc = "design.design:MySoC" + + [chipflow.steps] + board = "design.steps.board:MyBoardStep" + + [chipflow.silicon] + process = "ihp_sg13g2" + package = "pga144" + + [chipflow.test] + event_reference = "design/tests/events_reference.json" + +Peripheral Configuration +------------------------ + +The MCU SoC uses parameterized peripheral counts: + +.. code-block:: python + + self.user_spi_count = 3 # 3 SPI interfaces + self.i2c_count = 2 # 2 I2C interfaces + self.motor_count = 10 # 10 PWM channels + self.uart_count = 2 # 2 UART interfaces + self.gpio_banks = 2 # 2 GPIO banks + self.gpio_width = 8 # 8 bits per bank + +Interface Declaration +--------------------- + +The design dynamically creates interfaces based on peripheral counts: + +.. code-block:: python + + interfaces = { + "flash": Out(QSPIFlashSignature()), + "cpu_jtag": Out(JTAGSignature()) + } + + for i in range(self.user_spi_count): + interfaces[f"user_spi_{i}"] = Out(SPISignature()) + + for i in range(self.i2c_count): + interfaces[f"i2c_{i}"] = Out(I2CSignature()) + + for i in range(self.uart_count): + interfaces[f"uart_{i}"] = Out(UARTSignature()) + + for i in range(self.gpio_banks): + interfaces[f"gpio_{i}"] = Out(GPIOSignature(pin_count=self.gpio_width)) + +Memory Map +---------- + +.. list-table:: + :header-rows: 1 + + * - Region + - Base Address + - Description + * - SPI Flash + - ``0x00000000`` + - Code storage + * - SRAM + - ``0x10000000`` + - 2KB on-chip RAM + * - Debug + - ``0xa0000000`` + - Debug module + * - SPI Flash CSR + - ``0xb0000000`` + - Flash control registers + * - GPIO CSR + - ``0xb1000000`` + - GPIO registers (offset ``0x100000`` per bank) + * - UART CSR + - ``0xb2000000`` + - UART registers (offset ``0x100000`` per UART) + * - SoC ID CSR + - ``0xb4000000`` + - SoC identification + * - User SPI CSR + - ``0xb5000000`` + - SPI registers (offset ``0x100000`` per SPI) + * - I2C CSR + - ``0xb6000000`` + - I2C registers (offset ``0x100000`` per I2C) + * - Motor PWM CSR + - ``0xb7000000`` + - PWM registers (offset ``0x100`` per channel) + +Debug Support +------------- + +The MCU SoC includes full JTAG debug support via the CV32E40P debug module: + +.. code-block:: python + + debug = OBIDebugModule() + wb_arbiter.add(debug.initiator) + wb_decoder.add(debug.target, name="debug", addr=self.debug_base) + m.d.comb += cpu.debug_req.eq(debug.debug_req) + + m.d.comb += [ + debug.jtag_tck.eq(self.cpu_jtag.tck.i), + debug.jtag_tms.eq(self.cpu_jtag.tms.i), + debug.jtag_tdi.eq(self.cpu_jtag.tdi.i), + debug.jtag_trst.eq(self.cpu_jtag.trst.i), + self.cpu_jtag.tdo.o.eq(debug.jtag_tdo), + ] + +OpenOCD configuration files are provided in ``design/openocd/`` for hardware debugging. + +Custom IP: PWM Controller +------------------------- + +The example includes a custom PWM IP for motor control in ``design/ips/pwm.py``. This demonstrates how to create custom peripherals with their own IO signatures. + +Running the Example +------------------- + +.. code-block:: bash + + cd mcu_soc + pdm chipflow pin lock + pdm sim-check + pdm submit --wait + +Key Differences from Minimal +---------------------------- + +1. **Different CPU**: Uses CV32E40P instead of Minerva, with full debug support +2. **More Peripherals**: Multiple instances of each peripheral type +3. **JTAG Debug**: Full hardware debugging capability +4. **Custom IP**: Includes custom PWM peripheral +5. **Different Target**: IHP SG13G2 process instead of SKY130 + +Customization Ideas +------------------- + +- Adjust peripheral counts to match your requirements +- Add additional custom IP cores +- Modify memory sizes for your application +- Change the target process/package for different fabrication options diff --git a/docs/source/examples/minimal.rst b/docs/source/examples/minimal.rst new file mode 100644 index 0000000..45c68ae --- /dev/null +++ b/docs/source/examples/minimal.rst @@ -0,0 +1,132 @@ +Minimal SoC Example +=================== + +The ``minimal`` example demonstrates the simplest possible ChipFlow SoC design. It includes a RISC-V CPU core with basic peripherals. + +Overview +-------- + +This example creates a System-on-Chip with: + +- **Minerva RISC-V CPU** - A 32-bit RISC-V processor with multiply/divide support +- **QSPI Flash** - External flash memory for code storage +- **SRAM** - 1KB of on-chip RAM +- **GPIO** - 8-bit general purpose I/O +- **GPIO (Open Drain)** - 4-bit open-drain GPIO for I2C-style interfaces +- **UART** - Serial communication at 115200 baud + +Project Structure +----------------- + +.. code-block:: text + + minimal/ + ├── chipflow.toml # Project configuration + ├── design/ + │ ├── design.py # Main SoC design + │ ├── software/ # Firmware source code + │ ├── steps/ # Custom build steps + │ └── tests/ # Test reference data + └── README.md + +Configuration +------------- + +The ``chipflow.toml`` defines the project: + +.. code-block:: toml + + [chipflow] + project_name = "chipflow-examples-minimal" + + [chipflow.top] + soc = "design.design:MySoC" + + [chipflow.steps] + board = "design.steps.board:MyBoardStep" + + [chipflow.silicon] + process = "sky130" + package = "openframe" + + [chipflow.test] + event_reference = "design/tests/events_reference.json" + +Design Overview +--------------- + +The design is defined in ``design/design.py``. Here's the key structure: + +.. code-block:: python + + class MySoC(wiring.Component): + def __init__(self): + super().__init__({ + "flash": Out(QSPIFlashSignature()), + "uart_0": Out(UARTSignature()), + "gpio_0": Out(GPIOSignature(pin_count=8)), + "gpio_open_drain": Out(GPIOSignature( + pin_count=4, + sky130_drive_mode=Sky130DriveMode.OPEN_DRAIN_STRONG_UP + )) + }) + +The component declares its external interfaces using IO Signatures. These signatures tell ChipFlow how to map the design to physical pins. + +Memory Map +---------- + +The SoC uses the following memory map: + +.. list-table:: + :header-rows: 1 + + * - Region + - Base Address + - Description + * - SPI Flash + - ``0x00000000`` + - Code storage (boot address at 1MB offset) + * - SRAM + - ``0x10000000`` + - 1KB on-chip RAM + * - CSR Base + - ``0xb0000000`` + - Control/Status registers + * - GPIO CSR + - ``0xb1000000`` + - GPIO peripheral registers + * - UART CSR + - ``0xb2000000`` + - UART peripheral registers + * - SoC ID CSR + - ``0xb4000000`` + - SoC identification registers + +Running the Example +------------------- + +.. code-block:: bash + + cd minimal + pdm chipflow pin lock + pdm sim-check + pdm submit --wait + +Key Concepts Demonstrated +------------------------- + +1. **IO Signatures**: Using ``QSPIFlashSignature``, ``UARTSignature``, and ``GPIOSignature`` to define peripheral interfaces. + +2. **Wishbone Bus**: Connecting CPU, memory, and peripherals using Wishbone arbiters and decoders. + +3. **CSR Registers**: Using the CSR bus for low-speed peripheral configuration. + +4. **Software Builds**: Attaching firmware to the design with ``SoftwareBuild``. + +Next Steps +---------- + +- Modify the GPIO pin count or add more peripherals +- Change the target process in ``chipflow.toml`` +- Explore the :doc:`mcu-soc` example for a more complete design diff --git a/docs/source/index.rst b/docs/source/index.rst index 478fda7..402a4ae 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,11 +15,23 @@ Contents -------- .. toctree:: - :caption: User Guide + :caption: Getting Started :maxdepth: 2 Chip Configurator chipflow-lib/getting-started + tutorial-intro-chipflow-platform + +.. toctree:: + :caption: Examples + :maxdepth: 2 + + examples/index + +.. toctree:: + :caption: Reference + :maxdepth: 2 + chipflow-lib/index Digital IP Library Amaranth Language and Toolchain diff --git a/docs/source/tutorial-intro-chipflow-platform.rst b/docs/source/tutorial-intro-chipflow-platform.rst index f24bf71..221818a 100644 --- a/docs/source/tutorial-intro-chipflow-platform.rst +++ b/docs/source/tutorial-intro-chipflow-platform.rst @@ -38,7 +38,7 @@ Preparing your local environment sudo apt install git pipx -We use `PDM `_ to manage dependencies and ensure reproduable builds of your design. +We use `PDM `_ to manage dependencies and ensure reproducible builds of your design. First install PDM: :: @@ -70,12 +70,12 @@ Getting started First use `Git `_ to get the example sources. :: - git clone https://github.com/ChipFlow/example-socs + git clone https://github.com/ChipFlow/chipflow-examples Then set up your environment: :: - cd example-socs - make init + cd chipflow-examples + pdm install The example project @@ -211,22 +211,22 @@ with: .. code-block:: bash - make sim-build + pdm run chipflow sim build -After running this, we will have a simulation binary at ``build/sim/sim_soc``. +After running this, we will have a simulation binary at ``build/sim/sim_soc``. -We can't run it just yet, as it needs the software/BIOS too. To build the +We can't run it just yet, as it needs the software/BIOS too. To build the software we run: .. code-block:: bash - make software-build + pdm run chipflow software Now that we have our simulation binary, and a BIOS, we can run it: .. code-block:: bash - make sim-run + pdm run chipflow sim run You should see console output like this: @@ -252,23 +252,23 @@ First we need to build the design into a bitstream for the board: .. code-block:: bash - make board-build + pdm run chipflow board build -This will write a file ``build/top.bit``. As for the simulation, we need the -software/BIOS too. +This will write a file ``build/top.bit``. As for the simulation, we need the +software/BIOS too. If we haven't already, build the bios: .. code-block:: bash - make software-build + pdm run chipflow software Now, we load the software/BIOS and design onto board (program its bitstream): .. code-block:: bash - make board-load-software-ulx3s - make board-load-ulx3s + pdm run chipflow board load-software-ulx3s + pdm run chipflow board load-ulx3s Your board should now be running. For us to check that it's working, we can connect to it via its serial port: @@ -460,14 +460,14 @@ We can now take a look at our changes in simulation: .. code-block:: bash - # Rebuild our software - make software-build + # Rebuild our software + pdm run chipflow software # Rebuild our simulation - make sim-build + pdm run chipflow sim build # Run our simulation - make sim-run + pdm run chipflow sim run We should now see the output with button presses: @@ -492,17 +492,17 @@ software and design: .. code-block:: bash - # Rebuild our software - make software-build + # Rebuild our software + pdm run chipflow software # Rebuild our board - make board-build + pdm run chipflow board build # Load software onto board - make board-load-software-ulx3s + pdm run chipflow board load-software-ulx3s # Load design onto board - make board-load-ulx3s + pdm run chipflow board load-ulx3s Now, as in our first example, we need to connect to the board and see its output. @@ -527,11 +527,11 @@ When we press the physical buttons on the board, we should see it: Building for Silicon -------------------- -For this first Alpha, we aren't *quite* ready to start accepting designs on our API. This is coming very soon though! +To submit your design for silicon fabrication, see the :doc:`examples/getting-started` guide which covers the full submission workflow using the ChipFlow API. -`Sign up `_ to be notified when the next Alpha release is available. +`Sign up `_ to be notified when new releases are available. -If you are using this tutorial to test out new designs, reach out to us on `our Gitter channel `_. We would love to add your designs to our test sets! +If you are using this tutorial to test out new designs, reach out to us in our `GitHub Discussions forum `_. We would love to add your designs to our test sets! What's on the roadmap? @@ -544,10 +544,10 @@ We still have a lot of work to do - some things on our roadmap: * Improved simulation tooling. * Many more high-quality Amaranth Peripheral IP modules to include in your designs. -Join the beta -------------- +Join the Alpha Program +---------------------- -If you're interested in the platform, you can `join the beta `_ +If you're interested in the platform, you can `join the alpha program `_ and help us build the future of Python-powered chip design. @@ -556,5 +556,5 @@ Troubleshooting * Python version issues: If you choose to run ``pdm install`` within a venv, PDM will reuse that venv instead of creating a new one. - Ensure that you use a venv with Python 3.8 or greater. + Ensure that you use a venv with Python 3.11 or greater. diff --git a/tools/copy_docs.py b/tools/copy_docs.py index 903bdc2..01d0afb 100755 --- a/tools/copy_docs.py +++ b/tools/copy_docs.py @@ -10,6 +10,31 @@ from pathlib import Path from typing import List, Tuple + +def has_local_changes(repodir: Path) -> bool: + """Check if a git repository has uncommitted changes or is on a non-detached branch.""" + # Check for uncommitted changes + status_result = subprocess.run( + ['git', '-C', repodir, 'status', '--porcelain'], + capture_output=True, + text=True + ) + if status_result.stdout.strip(): + return True + + # Check if we're on a branch (not detached HEAD) + branch_result = subprocess.run( + ['git', '-C', repodir, 'symbolic-ref', '-q', 'HEAD'], + capture_output=True, + text=True + ) + if branch_result.returncode == 0: + # We're on a branch, check if it has commits ahead of origin + return True + + return False + + def copy_docs(repos: List[Tuple[str, str]]) -> List[Path]: """" Pull in docs from other repos. @@ -43,11 +68,14 @@ def copy_docs(repos: List[Tuple[str, str]]) -> List[Path]: # Check if repo already exists if repodir.exists(): - print(f"{repo_path} already there, updating") - # Git fetch - subprocess.run(['git', '-C', repodir, 'fetch'], check=True) - # Checkout ref - subprocess.run(['git', '-C', repodir, 'checkout', '-f', '--detach', ref], check=True) + if has_local_changes(repodir): + print(f"{repo_path} has local changes, skipping update") + else: + print(f"{repo_path} already there, updating") + # Git fetch + subprocess.run(['git', '-C', repodir, 'fetch'], check=True) + # Checkout ref + subprocess.run(['git', '-C', repodir, 'checkout', '-f', '--detach', ref], check=True) else: print(f"Cloning {repo_path} {ref} as {repodir}") # Clone the repository with gh