Development Infrastructure for L2IP (a RV32I processor)

Originally Developed By (2025.2): Ilana Finger, Leonardo Paloschi, Lucas Lima e Pedro Ventura.

Advisor: Rafael Corsi.

---

2026.1 Team: XXXX

Advisor: Rafael Corsi.

Why is This Necessary?

This organization — insper-riscv — was created through a partnership between Insper and CTI Renato Archer to collaboratively develop a RISC-V processor.

When working in a team and delivering a project to another institution, reproducibility is essential. The goal is to ensure that every experiment, synthesis, or simulation can be replicated exactly, whether by a team member, a new student or a professional from CTI Renato Archer

The idea behind maintaining a dedicated development infrastructure is to encapsulate all tools, libraries, packages, and configurations within a single, portable environment. This guarantees that anyone can obtain identical results on any machine, without worrying about dependency versions or setup steps.

When cloning the main project’s repository and opening it inside the provided Dev Container, no manual installations are required, all necessary tools are already included and ready to use directly from within the container.

Running the Environment and Understanding Concepts

To start using our DevContainer, you only need:

1. Install Docker

2. Install "Dev Containers" extension from VS Code

After having that, when cloning this repo and opening in VS code, a window will pop in the bottom right corner as shown here:

Alternitevely, you can click Ctrl+p or Cmd+p and search like follows, selecting this option:

What is a Dev Container?

A Dev Container is a feature of Visual Studio Code that lets you develop inside a pre-configured environment, isolated from your main system.

Instead of installing all tools, compilers, and libraries manually on your computer, a Dev Container uses a Docker image (like a lightweight virtual machine) that already includes everything you need.

In this project, that image is:

ghcr.io/pedropcventura/riscv-dev_tools:latest

When you open this repository in VS Code and select “Reopen in Container”, the following happens automatically:

1. VS Code checks for a file called .devcontainer/devcontainer.json.
2. That file tells VS Code which Docker image to use and what extensions to install.
3. VS Code connects to the container and opens your project inside it.

From your perspective, it feels like you’re coding normally in your computer but everything is running inside the container: the terminal, compilers, Python, Yosys, and any other tools defined by the image.

Every file you edit inside the Dev Container is still being edited locally on your computer. However, the terminal you use inside VS Code is not your local terminal: It belongs to the container

All this to ensure:

• Consistency: Everyone uses the same versions of every tool.
• No setup pain: Nothing to install manually on your system.
• Isolation: The container doesn’t affect your computer’s global environment.
• Portability: Works on macOS (ARM), Windows, and Linux the same way.

How to change it

If you ever need to:

• add a new VS Code extension,
• define environment variables,

you can edit the file .devcontainer/devcontainer.json

and then rebuild the container with

Ctrl + Shift + P -> Dev Containers: Rebuild and Reopen in Container

What is Docker?

Docker is a tool that lets you run applications inside containers — isolated environments that include everything the application needs to work: the operating system, libraries, and dependencies.

You can think of it as a lightweight virtual machine, but faster and easier to share.

Docker, Images, and Containers — What’s the Difference?

Concept	Description
Docker	The tool that builds, runs, and manages containers. It provides the engine that makes everything work.
Docker Image	A read-only template that defines what a container includes — such as the OS, tools, and configurations. Images can be shared and versioned (e.g., riscv-dev_tools:latest).
Docker Container	A running instance of an image. It’s a live environment created from that image, where you can execute commands, compile code, and run tests.

In short:

• A Docker image defines the environment.
• A container is the environment running (in your computer for example)
• Docker is the system that manages both.

Our Image:

• ghcr.io/pedropcventura/riscv-dev_tools:latest

This image contains all tools we used for our RISC-V development(GHDL, Yosys, Python, RISC-V GCC and more).

When you open this repository in VS Code, the Dev Container system automatically creates a container from this image and opens your workspace inside it.

This container running in your computer behaves like a clean, fully configured Linux environment

This Repository's Structure

.devcontainer/

Defines the development environment used by Visual Studio Code.
It tells VS Code which Docker image to use and what extensions should be installed automatically when opening the project.

Main file:
devcontainer.json

Example responsibilities:

• Specify the base image (ghcr.io/pedropcventura/riscv-dev_tools:latest)
• Configure environment variables and mount points
• Set the default user and workspace folder

If you want to add a new extension or environment variable, edit devcontainer.json and then rebuild the container:

Ctrl + Shift + P → Dev Containers: Rebuild and Reopen in Container

.vscode/

Contains local project settings and custom actions for VS Code.
These files define how developers interact with the environment — running scripts, formatting code, or triggering automation with one click.

Files inside:

• settings.json — defines default VS Code configurations (e.g., theme, formatters, shortcut buttons).
• tasks.json — defines reusable terminal commands as “tasks” (e.g., run t.py).

Example: The first custom button in VS Code runs the task defined in tasks.json:

{
  "label": "Run t.py",
  "type": "shell",
  "command": "python3 buttons_scripts/t.py"
}

This means when you press that button, the container executes t.py inside the buttons_scripts directory.

.github/workflows/

Contains automation pipelines (CI/CD). These workflows are executed by GitHub Actions every time someone pushes code or opens a pull request. No configuration needed: every new .yml you add inside here, will be executed at every commit.

Current workflow:

verify_image.yml

• checks that the main image (riscv-dev_tools:latest) is valid, healthy, and multi-architecture (AMD64 + ARM64).

This ensures the infrastructure remains reproducible for all contributors and compatible with both Intel and Apple Silicon machines.

buttons_scripts/

Stores custom scripts triggered from VS Code shortcut buttons. These scripts are meant to automate repetitive tasks (e.g., testing, building, or running examples).

Example:

• buttons_scripts/t.py — currently a test script used to confirm that the container is running correctly.

You can add new scripts here and link them to buttons by editing .vscode/tasks.json