RISC-V Tools

🌐 Português · English

O riscv-tools é um pacote Python que compila, simula, executa e certifica programas de teste para RISC-V bare-metal. Cada projeto descreve o seu fluxo em um config.yaml, e o mesmo teste compilado roda de duas formas: no hardware real, pela porta JTAG, ou na simulação cocotb/GHDL.

Os resultados são conferidos contra referências (goldens), geradas pelo Spike ou versionadas no repositório do projeto.

O pacote tem um módulo por responsabilidade, cada um com o seu __config__.py de valores padrão. O config.yaml do projeto consumidor sobrescreve esses padrões, e a referência completa está em docs/configuration.md.

Ele foi projetado para rodar em uma workstation com todas as ferramentas instaladas, ou dentro das imagens Docker de CI do repositório Infra.

Módulos

Módulo	Responsabilidade	Doc
compiler	.c/.S -> .elf/.bin, leitura dos cabeçalhos (RV32_EXT/RV32_TEST_KIND/RV32_TIMEOUT_S)	docs/modules/compiler.md
bin_to_image	.bin -> .mif/.hex (formatos de imagem de memória, sem compilador)	docs/modules/bin_to_image.md
c_to_asm	.c -> assembly RISC-V legível (gcc -S), para inspecionar a geração de código	docs/modules/c_to_asm.md
boot_rom	Compila o bootloader fixo e compartilhado, uma vez, reutilizado em todos os testes	docs/modules/boot_rom.md
jtag	Detecção do cabo JTAG em tempo real, executor genérico de .tcl	docs/modules/jtag.md
mem_edit	Primitivas genéricas do In-System Memory Content Editor (ler/escrever palavra, escrita completa, dump)	docs/modules/mem_edit.md
rom_writer	Grava uma imagem de ROM via JTAG sem reprogramar	docs/modules/rom_writer.md
ram_zero	Zera a RAM inteira via JTAG sem reprogramar	docs/modules/ram_zero.md
ram_target	Onde fica a RAM (instância da FPGA ou porta de debug da SDRAM)	docs/modules/ram_target.md
sdram_debug	Lê, escreve e preenche a SDRAM pela porta de debug JTAG	docs/modules/sdram_debug.md
uart_console	Mostra a saída do programa pela UART JTAG enquanto ele roda	docs/modules/uart_console.md
ram_dump	Faz o dump da RAM inteira via JTAG para um .mif	docs/modules/ram_dump.md
mailbox	Leitura do mailbox PASS/FAIL e pulso da "go flag" de reinício	docs/modules/mailbox.md
quartus_program	Recompilação completa + quartus_pgm (o caminho lento, "base")	docs/modules/quartus_program.md
mem_validator	Compara um dump de RAM com um golden JSON	docs/modules/mem_validator.md
golden_generator	Gera um golden JSON dinamicamente rodando um ELF no Spike	docs/modules/golden_generator.md
spike_exec	Prepara e dispara execuções do Spike: preflight, símbolos do ELF, linha de comando (compartilhado por golden_generator e spike_run)	docs/modules/spike_exec.md
spike_run	Roda cada teste compilado até o fim no Spike e reporta PASS/FAIL pelo veredito HTIF, sem hardware	docs/modules/spike_run.md
orchestrator	Compõe os módulos acima numa rodada completa de testes em hardware real, ou num sweep de frequência de clock para achar a Fmax	docs/modules/orchestrator.md
sim_runner	Dirige a simulação cocotb/GHDL: a contraparte de simulação do orchestrator (precisa do extra sim)	docs/modules/sim_runner.md
certify	Compila e roda a suíte de certificação arquitetural ACT4 sob cocotb/GHDL	docs/modules/certify.md
vhdl_sort	Ordena topologicamente fontes VHDL por dependência de entidade/pacote, para o -a do GHDL	docs/modules/vhdl_sort.md
memory_map	Confere que todas as cópias escritas à mão do mapa de memória concordam com o YAML da plataforma	docs/modules/memory_map.md
path_check	Falha quando um caminho de arquivo listado na configuração do projeto não existe (antes e depois de mover arquivos)	docs/modules/path_check.md
profiles	Lista os perfis válidos de um core a partir das extensões e das regras entre elas (M e Zmmul não coexistem, Zicsr ou Zicclsm é obrigatório)	docs/modules/profiles.md
freq_sweep	Reescreve a frequência de clock e as defasagens de um fonte de PLL: o mecanismo com que o sweep de frequência do orchestrator edita	docs/modules/freq_sweep.md
run_log	Rotaciona e replica (tee) toda a saída de console de uma execução num histórico de logs persistente por tipo	docs/modules/run_log.md

Docs

• AUTHORS.md: autores com commits no repositório, com nome e conta do GitHub.
• CONTRIBUTING.md: regras obrigatórias de contribuição e verificação antes de abrir Pull Request.
• CITATION.cff: metadados para citação do software.
• Referência de configuração
• Criando um teste em C
• Criando um teste em ASM
• Gerando um golden JSON pelo Spike
• Achando a Fmax (sweep de frequência de clock)
• Criando um workflow do GitHub Actions por tarefa

Uso

uv sync
uv run riscv-tools --config /path/to/project/config.yaml compile --emit mif
uv run riscv-tools --config /path/to/project/config.yaml compile --emit asm
uv run riscv-tools --config /path/to/project/config.yaml run
uv run riscv-tools --config /path/to/project/config.yaml run --exclude test-a,test-b
uv run riscv-tools --config /path/to/project/config.yaml generate-golden \
    build/real/some_test.elf --march rv32im --start 0x10 --end 0x20 --out golden/some_test.json

# Simulação (precisa do extra "sim": cocotb + cocotb-tools, e do GHDL no PATH)
uv sync --extra sim
uv run riscv-tools --config /path/to/project/config.yaml compile --emit hex
uv run riscv-tools --config /path/to/project/config.yaml sim
uv run riscv-tools --config /path/to/project/config.yaml sim --only test-a,test-b

Veja riscv-tools --help para a lista completa de subcomandos (write-rom, zero-ram, dump-ram, program, mailbox read|pulse, generate-header, generate-golden, spike-run, run, sim, vhdl-sort, check-memory-map, check-paths, freq-sweep).

# vhdl-sort não precisa de --config; é só análise do conteúdo dos arquivos,
# por exemplo ligado ao alvo de checagem de sintaxe VHDL de um Makefile:
uv run riscv-tools vhdl-sort src/**/*.vhd

# freq-sweep: acha a Fmax editando o PLL e fazendo uma recompilação +
# reprogramação + comparação da RAM completas a cada frequência candidata.
# Veja docs/pt-br/finding-fmax.md.
uv run riscv-tools --config /path/to/project/config.yaml freq-sweep \
    build/real/full.mif --golden golden/full.json --start 1 --stop 30 --step 2
uv run riscv-tools --config /path/to/project/config.yaml freq-sweep \
    build/real/full.mif --golden golden/full.json --binary --low 1 --high 50

Desenvolvimento

uv sync --group dev --extra sim
uv run pytest

Os testes que precisam do GHDL, do GCC RISC-V ou do Spike são pulados quando a ferramenta não existe. A doc de cada módulo lista seus pré-requisitos e os testes que o cobrem. Os testes verificam o tooling deste pacote; o processador é verificado pelas suítes do projeto consumidor.

tests/test_static_analysis.py roda ruff, pyright e deptry sobre o pacote inteiro, por isso não pertence a nenhum módulo em particular.

Rodando os testes no Docker

O Dockerfile parte da imagem ci-elf que o insper-riscv/Infra publica (ghcr.io/insper-riscv/ci-elf, veja o docs/pt-br/docker/ci-elf.md dele): GHDL, o GCC RISC-V com picolibc, o Spike com o módulo de debug longe do endereço 0 e o uv. Ele acrescenta as dependências deste projeto, de modo que nada é pulado e nada é compilado:

docker build -t riscv-tools-tests .
docker run --rm -v "$PWD:/workspace" riscv-tools-tests
docker run --rm -v "$PWD:/workspace" riscv-tools-tests tests/test_sim_runner.py -v

A imagem base é a latest da ci-elf. Para testar contra uma publicação específica, passe a tag sha- dela:

docker build --build-arg TOOLCHAIN_IMAGE=ghcr.io/insper-riscv/ci-elf:sha-<commit> \
    -t riscv-tools-tests .

O workflow tests monta esta imagem e roda a suíte inteira a cada push e pull request.

---

Copyright 2026 Insper. Licenciado sob a Apache License, Version 2.0.