Skip to content

Your first project

This walkthrough takes a small design from an idea to a bitstream. Each step happens on one page of the project, and the pages are listed in the sidebar in the order you use them: Plan, Design, Simulation, Synthesis, Implementation and Bitstream.

  • Sign in to Chipforge.
  • Check the Companion status in the top bar. When you point at it, it should say Connected. If your tools are on a Linux server, connect Chipforge to it first.
  • Install a simulator on the machine where your designs run. To build a bitstream you also need AMD Vivado or Intel Quartus Prime. See Toolchains and simulators.
  1. On the Projects page, select New Project. If you have no projects yet, the button is Create your first project.

  2. Enter a Name for the project.

  3. Under Project folder, select Choose… to pick or create a folder. If the project will be on a remote server, select Browse… instead, or type the folder’s path and select Validate.

    New file and folder names can use only the letters A–Z and a–z, digits, ., _ and -, because other characters break EDA tools.

  4. Select Create & start planning.

To start from sources you already have, select Import folder instead, choose the folder that holds them, and select Add & start planning. Chipforge doesn’t change your files. It adds a chipforge/ folder to the project for its own settings, chats and run results, and a hidden .chipforge/ folder with an index of your project’s files.

The project opens on the Plan page, where you agree what to build with the assistant before any code is written.

  1. Optionally, select Choose a target device to pick the FPGA you’re targeting. Once the chat has started, use Choose… under Target device beside the chat instead; if you don’t see it, widen the window. If you don’t choose a device, the assistant can recommend one once it knows the design.

  2. Tell the assistant what you want to build. A sentence is enough, for example “A UART transmitter for my board”.

  3. Answer the assistant’s questions. It asks about anything it can’t work out on its own, such as interfaces, clocks and resets, and how the design should be tested. Some questions come as a card with options to pick from.

  4. Review the proposal. When the plan is ready, a card headed Ready to build? lists the modules the assistant proposes and the file it saves the plan to.

  5. Choose how to continue:

    • Yes — build it (Auto): the assistant starts building, and edits files and runs lint and simulations without asking.
    • Yes — but ask before each edit (Manual): the assistant starts building, and asks you before each change.
    • No — keep planning: tell the assistant what should change, and select Send.

When you approve, Chipforge saves the plan to docs/PLAN.md in your project and opens it on the Design page. If the project already has chipforge/plan.md, or docs/PLAN.md is a file you wrote yourself, Chipforge leaves docs/PLAN.md alone and saves the plan to chipforge/plan.md instead.

On the Design page, the assistant writes the RTL for each module and lints it, then writes a self-checking testbench for each block and simulates it. Its chat shows each step as it happens.

When the assistant needs your approval, it shows a card with the change or command. Select Approve (Accept for a file change) to let it go ahead, or Reply instead to tell it what to do differently. The assistant tries to check with you before it moves on to the next stage, such as simulating the whole design. Synthesis needs your approval even in Auto mode. See The AI assistant for what each button does.

  1. Open the Simulation page.

  2. Choose a simulator from the simulator list. Chipforge remembers your choice for the project, and the assistant uses it too, unless you or the plan name a different one.

  3. Choose the testbench to run.

  4. Select Run Simulation. The simulator’s output streams into the page.

  5. When the run finishes, open the Waveform tab to see the signals. See Waveforms.

  1. Open the Synthesis page.

  2. Check the Project toolchain and the Target part. To change the part, select Choose part….

  3. Under Sources and Constraints, tick the files the run should use. Select a file’s name to open it in the editor.

  4. Choose the Top module.

  5. Select Run Synthesis. When the run finishes, the page shows its report and the files it produced.

  6. Open the Implementation page and select Run Implementation. Implementation works on the result of your last synthesis run.

Generate the bitstream and program your board

Section titled “Generate the bitstream and program your board”
  1. Open the Bitstream page. With Generate selected, select Run Bitstream.

    To run synthesis, implementation and bitstream generation in one go, turn on Run Full Flow (synth → impl → bitstream) and select Run Full Flow instead.

  2. Connect your board to the machine where the companion runs: your computer, or your remote server.

  3. Select Program device.

  4. Select Use this build to program the bitstream you just built, or Choose .bit… to pick another file.

  5. Choose your board from the list. If it isn’t there, select Rescan.

  6. Select Program.

Each run gets its own folder under chipforge/runs/ in your project, with its log, its reports and any bitstream it made. Chipforge keeps every run folder that holds a bitstream. Of the others, such as failed runs, synthesis and implementation runs, and simulations with their waveforms, it removes the oldest. For more about each stage, see FPGA flow.