Skip to content

Development Workflow

To maintain a high-quality codebase and ensure that our SoC remains "competition-ready," all team members must follow this workflow. Consistency is key to avoiding integration hell.

Git Branching Strategy

We use a feature-branching model. Direct pushes to the main branch are strictly prohibited.

  • main: The "Gold Standard." Only contains stable, verified, and synthesized code.
  • develop: The integration branch where all new features are merged first.
  • feat/<feature-name>: Used for new hardware modules or software drivers.
  • fix/<issue-name>: Used for bug fixes or RTL timing corrections.
  • docs/<topic>: Used for updating MkDocs or README files.

Branch Naming

Always use lowercase and hyphens for branch names.

  • Good: feat/ai-accel-mvm-unit
  • Bad: New_AI_Accelerator_v2

Commit Message Convention

We follow Conventional Commits. This makes the project history readable and allows for automated changelog generation.

Format: <type>: <description>

Type Description
rtl Changes to SystemVerilog source files.
sw Changes to C/Assembly code or drivers.
feat A new feature for the SoC or toolchain.
fix A bug fix in hardware or software.
docs Documentation changes only.
refactor Code changes that neither fix a bug nor add a feature.
ci Changes to our CI/CD scripts or Dockerfile.

Example

rtl: add OBI-to-AXI bridge for memory subsystem sw: implement basic UART baud rate configuration

The RTL Development Cycle

When working on a hardware module (e.g., a new peripheral), follow these steps:

  1. Code: Write your SystemVerilog code in rtl/.
  2. Lint: Run ./ci/lint.sh to catch syntax errors or non-synthesizable constructs.
  3. Simulate: Use ./scripts/sim_unit.sh or the main ./scripts/sim.sh.
  4. Verify: Open the waveforms in GTKWave to ensure the logic matches the design.
  5. Clean: Ensure your code follows the Coding Standards.

Broken CI

Never merge a Pull Request if ./ci/run_all.sh fails. The integration branch must always be in a "passing" state.

Software & Drivers Cycle

Since we are working bare-metal, software and hardware are tightly coupled:

  1. Map: Define your register addresses in sw/mcal/drivers.h.
  2. Write: Develop the driver or application in sw/.
  3. Compile: Use the provided Makefile to cross-compile for RISC-V.
  4. Test: Run the simulation to see if the hardware responds correctly to your software commands.

Pull Request (PR) Process

  1. Push your branch to GitHub.
  2. Open a Pull Request against the develop branch.
  3. Self-Review: Look at your own diff. Did you leave any display statements or debug flags?
  4. Peer Review: At least one other team member must approve the RTL changes.
  5. Merge: Once CI passes and approval is given, merge using Squash and Merge.

🔵 Tooling & Editor Support

To ensure a consistent development experience, we recommend VS Code integrated with our custom Dev Container. This setup automatically configures your compiler paths, linters, and RISC-V extensions.

1. Mandatory Host Extensions

Before opening the project, you must install these extensions on your local VS Code (Host):

  • Dev Containers: Allows VS Code to use a Docker container as a full-featured development environment.
  • Docker: To manage the lifecycle of your containers.
  • Path Intellisense: For autocompletion of file paths in scripts and includes.

2. The Dev Container Environment

Once you open the project folder, VS Code will prompt you to "Reopen in Container." Doing so will automatically activate the following internal extensions:

Category Extension Purpose
C/C++ ms-vscode.cpptools IntelliSense for TB and drivers.
Hardware eirikpre.systemverilog SystemVerilog syntax & navigation.
Linting CHIPSAlliance.verible Language Server using verible-verilog-ls.
RISC-V sunshaoce.RISC-V Support for RISC-V assembly and ISA.
Utilities ZixuanWang.linkerscript Syntax highlighting for .ld files.

Verilog Language Server (LSP)

Our environment uses verible-verilog-ls. It is configured to use ${workspaceFolder}/files.f as the source of truth for file indexing. If you add a new .sv file, make sure to add it to files.f to keep IntelliSense working.

3. C++ Configuration & IntelliSense

Our .vscode/c_cpp_properties.json (managed via devcontainer.json) is configured to include:

  • Verilator Headers: /usr/share/verilator/include for cycle-accurate simulation code.
  • Project MCAL: ${workspaceFolder}/sw/mcal/** for bare-metal driver development.
  • Standard: C++17 for modern testbench features.

Format on Save

editor.formatOnSave is enabled. RTL files will be formatted using verible-verilog-format to ensure a clean git history. Please do not disable this.

4. Alternative Editors

If you prefer Helix or Neovim, ensure your languages.toml or LSP configuration points to:

  • Verible: For SystemVerilog.
  • Clangd: For C/C++ (make sure to generate a compile_commands.json if possible).