From 1cb7f1007429856c153712a9980b429c4adf72f2 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Mon, 5 Oct 2026 09:48:00 -0300 Subject: [PATCH 01/27] make board-build / board: build in the toolchain image, run on the board scripts/toolchain.sh runs a command in the infra-toolchain image as the calling user. board-build generates the headers, the MIFs and the goldens in it, so no local GCC is needed; board runs riscv-tools on the host, where Quartus and the JTAG cable are. Co-Authored-By: Claude Sonnet 5.5 --- Makefile | 18 +++++++++++++++++- scripts/toolchain.sh | 20 ++++++++++++++++++++ 2 files changed, 37 insertions(+), 1 deletion(-) create mode 100755 scripts/toolchain.sh diff --git a/Makefile b/Makefile index d31d77a..21e4e3c 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ GHDL := ghdl STD := --std=08 WDIR := build/ghdl -.PHONY: all sync check subrepos sim paths clean +.PHONY: all sync check subrepos sim paths board-build board clean all: paths check subrepos sim @@ -57,6 +57,22 @@ sim: sync && uv run riscv-tools --config tools/riscv_build/config.yaml compile --emit hex \ && uv run riscv-tools --config tools/riscv_build/config.yaml sim +# --------------------------------------------------------------- +# The real board. The programs and their goldens are built in the toolchain image +# (scripts/toolchain.sh), never with a local GCC; only Quartus and the JTAG cable +# run on the host. `make board-build` first, then `make board` +# (BOARD_ARGS='--only add' runs one program). +# --------------------------------------------------------------- +BOARD_CFG := tools/riscv_build/config.yaml + +board-build: + cd Tests && ../scripts/toolchain.sh bash -c 'uv run riscv-tools --config $(BOARD_CFG) generate-header \ + && uv run riscv-tools --config $(BOARD_CFG) compile --emit mif' + +# riscv-tools' run_log writes the whole run to Tests/logs/real/latest.log and archives the previous one. +board: + cd Tests && uv run riscv-tools --config $(BOARD_CFG) run $(BOARD_ARGS) + # Every file path the configuration lists exists (paths.yaml). paths: sync cd Tests && uv run riscv-tools --root .. check-paths --manifest paths.yaml diff --git a/scripts/toolchain.sh b/scripts/toolchain.sh new file mode 100755 index 0000000..a9443dc --- /dev/null +++ b/scripts/toolchain.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +# Runs a command inside the infra-toolchain image (GCC with picolibc, Spike, GHDL, +# uv) with this repository mounted at /workspace, as the calling user so the files +# it writes are not owned by root; its virtualenv lives in the container (/tmp/venv), +# so it never clobbers the host's .venv. The working directory carries over: run from +# Tests/ and the command runs in /workspace/Tests. +# +# scripts/toolchain.sh uv run riscv-tools --config tools/riscv_build/config.yaml compile --emit mif +set -euo pipefail + +IMAGE="${TOOLCHAIN_IMAGE:-ghcr.io/insper-riscv/infra-toolchain:latest}" +ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +REL="$(realpath --relative-to="$ROOT" "$PWD")" + +exec docker run --rm \ + --user "$(id -u):$(id -g)" \ + -e HOME=/tmp -e UV_LINK_MODE=copy -e UV_PROJECT_ENVIRONMENT=/tmp/venv \ + -v "$ROOT:/workspace" \ + -w "/workspace/$REL" \ + "$IMAGE" "$@" From 0dd8cf6b196afd21293b01697efbca0f16033915 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Mon, 12 Oct 2026 15:29:54 -0300 Subject: [PATCH 02/27] Benchmark the SDRAM platform and pin the submodules it was measured on Adds docs/BENCHMARK_SDRAM.md: the 89 existing programs on the sdram platform against internal-mem, in simulation inside the Infra toolchain image (median ratio 2.27, range 1.33 to 2.75), plus the six SDRAM-only programs. Core, Memory, TopLevel and Tests point at the tips of their open SDRAM pull requests (feat/sdram-ready, feat/sdram-bist, feat/sdram-platform, feat/sdram-tests), the commits the numbers come from. Peripherals is unchanged. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01288qnYGXPmNxMvNWBhu3QE --- Core | 2 +- Memory | 2 +- Tests | 2 +- TopLevel | 2 +- docs/BENCHMARK_SDRAM.md | 207 ++++++++++++++++++++++++++++++++++++++++ 5 files changed, 211 insertions(+), 4 deletions(-) create mode 100644 docs/BENCHMARK_SDRAM.md diff --git a/Core b/Core index fb18458..8e15a8e 160000 --- a/Core +++ b/Core @@ -1 +1 @@ -Subproject commit fb184580a8e9e548ade0d49fa7b686f11de8cbc2 +Subproject commit 8e15a8e68350e1ef01f1426baf07527e902d815e diff --git a/Memory b/Memory index 7d5d6d8..4e339b5 160000 --- a/Memory +++ b/Memory @@ -1 +1 @@ -Subproject commit 7d5d6d82697a8252af880092b1c16f51980d7b77 +Subproject commit 4e339b595dbfcd9d51d71e2b6c3b3b769835c779 diff --git a/Tests b/Tests index 4ff7260..b71df35 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit 4ff7260205e689bd08fb73967600a751d14f6d0d +Subproject commit b71df35a991abc2f4da32c19d34639b3af3e26ab diff --git a/TopLevel b/TopLevel index 7e190e1..4f2601f 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit 7e190e16429fc30a0ea6e58776ad945639103377 +Subproject commit 4f2601fcba528b4724323afc9c9cb25a7d9aad06 diff --git a/docs/BENCHMARK_SDRAM.md b/docs/BENCHMARK_SDRAM.md new file mode 100644 index 0000000..cd3ed7e --- /dev/null +++ b/docs/BENCHMARK_SDRAM.md @@ -0,0 +1,207 @@ +# Benchmark da plataforma SDRAM em simulação + +Este documento mede quanto custa, em ciclos, usar a SDRAM de 64 MB da DE0-CV como única RAM do core, em comparação com a RAM interna do FPGA. O número serve para dimensionar uma cache L1 de dado entre o core e a SDRAM. + +## 1. O que foi medido + +Cada programa da suíte de testes roda duas vezes no mesmo testbench cocotb, uma em cada plataforma: + +| Plataforma | Onde ficam `.data`, `.bss`, heap e pilha | +| :--- | :--- | +| `internal-mem` | RAM interna do FPGA, resposta em 1 ciclo | +| `sdram` | SDRAM externa, resposta em vários ciclos, com o core parando o pipeline até a resposta chegar | + +A métrica é o tempo do programa em ticks do clock base de simulação, que valem três por ciclo do core. Na plataforma `sdram`, a espera de inicialização do chip (20 000 ticks) é descontada, porque ela não depende do programa. A razão de cada programa é: + +$$ +r = \frac{T_{\text{sdram}} - 20\,000}{T_{\text{internal-mem}}} +$$ + +O modelo de chip da simulação aborta o teste em qualquer violação de timing, de ordem de comandos ou de intervalo de refresh, então um programa que passa também respeitou o protocolo da SDRAM. + +## 2. Ambiente + +A compilação e a simulação rodaram dentro da imagem `ghcr.io/insper-riscv/infra-toolchain:latest`, com o GHDL 6.0.0, o GCC RISC-V 16.1.0 com picolibc e o Spike da própria imagem. Nada do host foi usado. + +Os repositórios foram testados nos commits abaixo, que são as pontas dos pull requests de SDRAM abertos: + +| Repositório | Branch | Commit | +| :--- | :--- | :--- | +| Core | `feat/sdram-ready` | `8e15a8e` | +| Memory | `feat/sdram-bist` | `4e339b5` | +| TopLevel | `feat/sdram-platform` | `4f2601f` | +| Testes | `feat/sdram-tests` | `b71df35` | +| Tools | `feat/sdram-debug-backend` | `91e3681` | + +Comandos, a partir do projeto de testes e com a configuração de cada plataforma (`config.sdram-regression.yaml` e `config.yaml`): + +1. `riscv-tools --config generate-header` +2. `riscv-tools --config compile --emit hex` +3. `riscv-tools --config sim` + +## 3. Resultado + +Os 89 programas existentes passam nas duas plataformas (178 execuções, 0 falhas). + +| Estatística da razão $r$ | Valor | +| :--- | ---: | +| menor | 1,33 | +| mediana | 2,27 | +| média | 2,18 | +| maior | 2,75 | + +Distribuição dos 89 programas: + +| Faixa de $r$ | Programas | +| :--- | ---: | +| abaixo de 1,5 | 2 | +| de 1,5 a 2,0 | 10 | +| de 2,0 a 2,5 | 76 | +| 2,5 ou mais | 1 | + +A SDRAM custa cerca de 2,3 vezes a RAM interna na mediana, e não uma ordem de grandeza a mais: boa parte do tempo de um programa vai para instruções que não acessam a RAM. + +### 3.1. Extremos + +| Programa | `internal-mem` | `sdram` | $r$ | +| :--- | ---: | ---: | ---: | +| `stdout-printf-int` | 16 994 | 22 685 | 1,33 | +| `div-rem-back-to-back` | 1 049 | 1 553 | 1,48 | +| `mul` | 1 064 | 1 598 | 1,50 | +| `store-word-roundtrip` | 362 | 851 | 2,35 | +| `rodata-lookup-table` | 569 | 1 358 | 2,39 | +| `stdout-truncate` | 188 627 | 518 597 | 2,75 | + +Os programas aritméticos longos ficam perto de 1,5 provavelmente porque passam boa parte do tempo na unidade de multiplicação e divisão, que não depende da RAM (não verificado). Os que fazem um load ou um store logo depois de outro ficam perto de 2,35, o que dá o custo de um acesso isolado à SDRAM. + +### 3.2. Diferença para os valores publicados no PR + +A descrição do PR do Core informa menor 1,31, mediana 2,27, média 2,17 e maior 2,47. Esta medição reproduz a mediana e quase reproduz a média; o máximo é maior. + +| Programa | $T_{\text{sdram}}$ no PR | $T_{\text{sdram}}$ aqui | +| :--- | ---: | ---: | +| `add` | 1 175 | 1 175 | +| `mul` | 1 598 | 1 598 | +| `stdout-printf-int` | 22 220 | 22 685 | +| `stdout-truncate` | 465 992 | 518 597 | + +Os programas sem saída de texto coincidem exatamente. Só os que usam `stdout` ficam mais lentos aqui. A explicação provável é que, nos branches testados, a saída de texto também envia cada byte à UART JTAG, o que acrescenta acessos a cada caractere. Esta hipótese não foi verificada com uma execução sem a UART. + +## 4. Programas específicos da SDRAM + +Seis programas exercitam a SDRAM diretamente e só existem na plataforma `sdram`, então não têm baseline. Todos passam. Os ticks abaixo já descontam a inicialização. + +| Programa | Ticks | +| :--- | ---: | +| `sdram-bytes` | 10 124 | +| `sdram-loop` | 81 335 | +| `sdram-muldiv` | 119 858 | +| `sdram-refresh` | 128 975 | +| `sdram-copy` | 267 029 | +| `sdram-memtest` | 518 462 | + +## 5. Limites desta medição + +1. É simulação. O clock do controlador (7 ns) não tem relação fixa com o do core, mas a simulação não modela atraso de pino nem fase de clock, que só a placa mostra. +2. Os tempos do chip no controlador são provisórios, valores usuais de uma peça SDR de 143 MHz que ainda não foram conferidos no datasheet. +3. Não houve execução na placa nem compilação no Quartus nesta rodada. + +## 6. Uso como linha de base para a cache + +Uma cache L1 de dado deve ser medida com o mesmo procedimento das seções 1 e 2 e comparada com a coluna `sdram` da tabela da seção 7. O teto do ganho é o custo medido aqui: uma cache ideal levaria a razão mediana de 2,27 para 1,0. + +## 7. Tabela completa + +Ticks por programa, ordenados pela razão. A coluna `sdram` já desconta a inicialização. + +| Programa | `internal-mem` | `sdram` | $r$ | +| :--- | ---: | ---: | ---: | +| `stdout-printf-int` | 16994 | 22685 | 1,33 | +| `div-rem-back-to-back` | 1049 | 1553 | 1,48 | +| `mul` | 1064 | 1598 | 1,50 | +| `mulh` | 1064 | 1598 | 1,50 | +| `div` | 1025 | 1568 | 1,53 | +| `rem` | 899 | 1430 | 1,59 | +| `mulhsu` | 821 | 1325 | 1,61 | +| `mulhu` | 821 | 1325 | 1,61 | +| `divu` | 746 | 1241 | 1,66 | +| `remu` | 746 | 1241 | 1,66 | +| `data-init-word-array` | 764 | 1448 | 1,90 | +| `hazard-forwarding-mul` | 461 | 908 | 1,97 | +| `loop` | 803 | 1643 | 2,05 | +| `divide-signed` | 614 | 1265 | 2,06 | +| `divide-unsigned` | 614 | 1265 | 2,06 | +| `remainder-signed` | 614 | 1265 | 2,06 | +| `remainder-unsigned` | 614 | 1265 | 2,06 | +| `example-add` | 608 | 1262 | 2,08 | +| `multiply` | 608 | 1262 | 2,08 | +| `data-initialization` | 497 | 1070 | 2,15 | +| `data-init-word` | 497 | 1070 | 2,15 | +| `jump-jal` | 380 | 824 | 2,17 | +| `jump-jalr` | 380 | 824 | 2,17 | +| `data-init-halfword` | 482 | 1055 | 2,19 | +| `stdout-printf` | 6458 | 14165 | 2,19 | +| `example-integration-mem` | 647 | 1430 | 2,21 | +| `bss-zero` | 476 | 1055 | 2,22 | +| `data-init-byte` | 473 | 1049 | 2,22 | +| `branch-beq` | 362 | 809 | 2,23 | +| `branch-bge` | 362 | 809 | 2,23 | +| `branch-bgeu` | 362 | 809 | 2,23 | +| `branch-blt` | 362 | 809 | 2,23 | +| `branch-bltu` | 362 | 809 | 2,23 | +| `branch-bne` | 362 | 809 | 2,23 | +| `load-store-word` | 488 | 1091 | 2,24 | +| `load-store-byte` | 485 | 1085 | 2,24 | +| `load-store-halfword` | 485 | 1085 | 2,24 | +| `logical-and` | 356 | 803 | 2,26 | +| `logical-or` | 356 | 803 | 2,26 | +| `logical-xor` | 356 | 803 | 2,26 | +| `add-upper-immediate-to-pc` | 353 | 803 | 2,27 | +| `arithmetic-add` | 353 | 803 | 2,27 | +| `arithmetic-sub` | 353 | 803 | 2,27 | +| `compare-slt` | 353 | 803 | 2,27 | +| `compare-sltu` | 353 | 803 | 2,27 | +| `hazard-forwarding-chain` | 353 | 803 | 2,27 | +| `hazard-forwarding-raw` | 353 | 803 | 2,27 | +| `logical-andi` | 353 | 803 | 2,27 | +| `logical-ori` | 353 | 803 | 2,27 | +| `logical-xori` | 353 | 803 | 2,27 | +| `shift-left-logical` | 353 | 803 | 2,27 | +| `shift-right-arithmetic-reg` | 353 | 803 | 2,27 | +| `shift-right-logical-reg` | 353 | 803 | 2,27 | +| `compare-slti` | 350 | 797 | 2,28 | +| `compare-sltiu` | 350 | 797 | 2,28 | +| `shift-left-logical-imm` | 350 | 797 | 2,28 | +| `shift-right-arithmetic-imm` | 350 | 797 | 2,28 | +| `shift-right-logical-imm` | 350 | 797 | 2,28 | +| `not` | 497 | 1133 | 2,28 | +| `x0-readonly` | 350 | 800 | 2,29 | +| `arithmetic-addi-negative` | 347 | 797 | 2,30 | +| `load-upper-immediate` | 347 | 797 | 2,30 | +| `struct-init-heap` | 344 | 791 | 2,30 | +| `struct-init-stack` | 344 | 791 | 2,30 | +| `load-halfword-signed` | 368 | 851 | 2,31 | +| `load-halfword-unsigned` | 368 | 851 | 2,31 | +| `and` | 509 | 1181 | 2,32 | +| `or` | 509 | 1181 | 2,32 | +| `xor` | 509 | 1181 | 2,32 | +| `branch-not-equal` | 506 | 1178 | 2,33 | +| `load-word` | 365 | 851 | 2,33 | +| `store-halfword-roundtrip` | 365 | 851 | 2,33 | +| `shift-left` | 506 | 1181 | 2,33 | +| `add` | 503 | 1175 | 2,34 | +| `branch-equal` | 503 | 1175 | 2,34 | +| `compare-signed` | 503 | 1175 | 2,34 | +| `compare-unsigned` | 503 | 1175 | 2,34 | +| `shift-right-arithmetic` | 503 | 1175 | 2,34 | +| `shift-right-logical` | 503 | 1175 | 2,34 | +| `sub` | 503 | 1175 | 2,34 | +| `hazard-load-use` | 365 | 854 | 2,34 | +| `section6-loadstore` | 359 | 842 | 2,35 | +| `struct-alignment` | 389 | 914 | 2,35 | +| `load-byte-signed` | 362 | 851 | 2,35 | +| `load-byte-unsigned` | 362 | 851 | 2,35 | +| `store-byte-roundtrip` | 362 | 851 | 2,35 | +| `store-word-roundtrip` | 362 | 851 | 2,35 | +| `rodata-lookup-table` | 569 | 1358 | 2,39 | +| `stdout-truncate` | 188627 | 518597 | 2,75 | From 5ca6335ca00c3cca772e14cd6dfe113be6a7cc8f Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Mon, 12 Oct 2026 15:34:55 -0300 Subject: [PATCH 03/27] Add the board benchmark of the SDRAM self test Four BIST modes on the DE0-CV with the sdram-bringup project (TopLevel e37c149, Memory 4e339b5): 0 wrong words in all of them, whole-chip sweep in about 6 s. Also the Quartus slack of the programmed design. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01288qnYGXPmNxMvNWBhu3QE --- docs/BENCHMARK_SDRAM_PLACA.md | 65 +++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/BENCHMARK_SDRAM_PLACA.md diff --git a/docs/BENCHMARK_SDRAM_PLACA.md b/docs/BENCHMARK_SDRAM_PLACA.md new file mode 100644 index 0000000..b1b3fc2 --- /dev/null +++ b/docs/BENCHMARK_SDRAM_PLACA.md @@ -0,0 +1,65 @@ +# Benchmark da SDRAM na placa + +Este documento registra a execução do autoteste (BIST) da SDRAM de 64 MB na DE0-CV, sem o core, e as margens de timing do projeto que foi gravado. Ele complementa o benchmark de simulação em `BENCHMARK_SDRAM.md`, que mede o custo em ciclos de usar a SDRAM como RAM. + +## 1. Ambiente + +| Item | Valor | +| :--- | :--- | +| Placa | DE0-CV, FPGA Cyclone V `5CEBA4F23` (JTAG `0x02B050DD`) | +| Cabo | USB-Blaster `[3-5]` | +| Memória | SDRAM SDR 32M x 16, 143 MHz | +| Ferramenta | Quartus Prime Lite 25.1std.0, no host | +| Projeto | `sdram-bringup` do TopLevel, branch `feat/sdram-bringup`, commit `e37c149` | +| Controlador e autoteste | Memory, branch `feat/sdram-bist`, commit `4e339b5` | + +O projeto liga a SDRAM a um controlador e ao autoteste, sem o core. O PLL gera 142,857 MHz para o controlador e para o pino `DRAM_CLK`, este deslocado em 2750 ps, e 50 MHz para o lado do core, que o autoteste não usa. + +## 2. Procedimento + +1. Compilar: `quartus_sh --flow compile sdram_bringup`, em `platforms/sdram-bringup/quartus`. +2. Gravar o bitstream na SRAM do FPGA: `quartus_pgm -c "USB-Blaster [3-5]" -m JTAG -o "p;output_files/sdram_bringup.sof"`. +3. Rodar cada modo do autoteste pelo JTAG: `quartus_stp -t jtag/sdram_bist.tcl 120`, de dentro de `platforms/sdram-bringup`. + +A compilação levou 45 s. A gravação é volátil: ao desligar a placa, o FPGA perde a configuração. + +## 3. Resultado do autoteste + +Cada modo foi executado uma vez, em sequência, depois da gravação. Todos passaram, sem palavra errada e sem estouro do controlador. + +| Modo | Teste | Palavras movidas | Palavras erradas | Resultado | +| :--- | :--- | ---: | ---: | :--- | +| 0 | rápido, com máscaras de byte | 458 752 | 0 | PASS | +| 1 | padrões (zeros, uns, `0xAAAAAAAA`, `0x55555555`, bit andando, endereço e complemento) | 1 048 576 | 0 | PASS | +| 2 | varredura do chip inteiro, $2^{24}$ palavras | 67 108 864 | 0 | PASS | +| 3 | endereços pseudo-aleatórios, $2^{20}$ palavras escritas e relidas | 2 097 152 | 0 | PASS | + +A varredura completa levou cerca de 6 s; o relógio do script tem resolução de 1 s, então o tempo vale como ordem de grandeza. Ela move $4 \cdot 2^{24}$ palavras (escrita e leitura, com o dado do endereço e com seu complemento), o que dá algo em torno de 11 milhões de palavras por segundo. + +O controlador gasta 10 ciclos de 7 ns por acesso de uma palavra (ativar a linha, ler ou escrever em dois ciclos de 16 bits e pré-carregar), ou seja, no máximo + +$$ +\frac{1}{10 \cdot 7\ \text{ns}} \approx 14{,}3 \text{ milhões de palavras por segundo} +$$ + +com os tempos provisórios do chip. A taxa medida fica abaixo desse teto, como se espera. + +## 4. Timing do projeto gravado + +Margens (slack) do Quartus com as restrições de entrada e saída do chip. Valores negativos indicam que o caminho não fecha naquele modelo. + +| Verificação | Modelo lento 85 C | Modelo lento 0 C | +| :--- | ---: | ---: | +| Leitura de dado, setup (domínio do controlador) | -0,201 ns | +0,057 ns | +| Comandos e dado de escrita, setup (`DRAM_CLK`) | -0,051 ns | -0,029 ns | +| Comandos e dado de escrita, hold | +2,974 ns | +3,068 ns | +| Hold no domínio do controlador | +0,337 ns | +0,314 ns | + +Recursos: 521 ALMs de 18 480 (3 %), 923 registradores, 65 pinos de 224 e nenhum bit de memória em bloco. + +## 5. Limites desta medição + +1. Os tempos do chip nas restrições (setup de entrada 1,5 ns, hold de entrada 0,8 ns, acesso 5,4 ns, hold de saída 2,5 ns) são valores usuais de uma SDR de 143 MHz, ainda não conferidos com o datasheet da peça. As margens negativas dos modelos lentos dependem deles. +2. O autoteste passou na placa mesmo com margem negativa no modelo lento, o que indica que o modelo é conservador; ele não prova folga em outra temperatura, outra placa ou outro lote. +3. Foi uma execução de cada modo. Não houve repetição para medir variação nem varredura da fase do clock. +4. Este benchmark não inclui o core. O custo em ciclos de rodar programas com a SDRAM como RAM, na placa, depende da plataforma `sdram` completa e não foi medido aqui. From d857ef58e94496b2a601aa4354beb6a83c916d6b Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Mon, 12 Oct 2026 16:00:42 -0300 Subject: [PATCH 04/27] Add the full-platform board run to the SDRAM board benchmark The sdram platform (core and SDRAM) on the DE0-CV: the 89 existing programs and the 6 SDRAM programs pass, 82 goldens match. Run inside the Infra toolchain image (Ubuntu 26.04) with the host Quartus mounted. Also the Quartus slack and resources of core_fpga_sdram. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01288qnYGXPmNxMvNWBhu3QE --- docs/BENCHMARK_SDRAM_PLACA.md | 40 +++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/docs/BENCHMARK_SDRAM_PLACA.md b/docs/BENCHMARK_SDRAM_PLACA.md index b1b3fc2..b6337fc 100644 --- a/docs/BENCHMARK_SDRAM_PLACA.md +++ b/docs/BENCHMARK_SDRAM_PLACA.md @@ -57,9 +57,41 @@ Margens (slack) do Quartus com as restrições de entrada e saída do chip. Valo Recursos: 521 ALMs de 18 480 (3 %), 923 registradores, 65 pinos de 224 e nenhum bit de memória em bloco. -## 5. Limites desta medição +## 5. Plataforma completa na placa (core e SDRAM) + +A plataforma `sdram` do TopLevel (branch `feat/sdram-platform`, commit `4f2601f`) liga o core a 50 MHz à SDRAM, que é a única RAM, com o controlador a 142,857 MHz. A suíte rodou na placa com o `riscv-tools` dentro da imagem `ghcr.io/insper-riscv/infra-toolchain:latest` (Ubuntu 26.04.1, GHDL 6.0.0, GCC RISC-V 16.1.0 com picolibc). O Quartus 25.1std do host foi montado em modo leitura nessa imagem, com o servidor JTAG do host acessado pela rede do host. A imagem recebeu uma única camada local com a biblioteca `libglib2.0-0t64`, que as ferramentas do Quartus exigem e a imagem não trazia. + +Passos, cada um dentro do container: + +1. `generate-header` e `compile --emit mif` para as duas configurações (os 89 programas existentes e os 6 da SDRAM); o golden de cada programa C sai do Spike da imagem. +2. `run` da configuração `config.sdram-regression.yaml`: compila o projeto `core_fpga_sdram`, grava a placa e executa cada programa carregando-o pela porta de debug JTAG e lendo o resultado de volta. +3. `run --skip-reconfigure` da configuração `config.sdram.yaml`: os 6 programas que usam a SDRAM, sem regravar a placa. + +### 5.1. Resultado + +| Verificação | Resultado | +| :--- | :--- | +| Programas existentes | 89 passam, 0 falham | +| Goldens conferidos contra a memória da placa | 82 | +| Programas específicos da SDRAM | 6 passam, 0 falham | +| Compilação do Quartus (dentro do container) | concluída, 0 erros | + +Cada programa leva de 2,4 s a 3,0 s na placa. Esse tempo é dominado pelo carregamento e pela leitura pelo JTAG, e não pelo número de ciclos do programa, então ele não serve para calcular a razão contra a RAM interna; essa razão está medida em simulação em `BENCHMARK_SDRAM.md`. + +### 5.2. Timing e recursos do projeto gravado + +| Verificação | Modelo lento 85 C | Modelo lento 0 C | +| :--- | ---: | ---: | +| Leitura de dado, setup (domínio do controlador) | -0,204 ns | +0,053 ns | +| Comandos e dado de escrita, setup (`DRAM_CLK`) | -0,047 ns | -0,025 ns | +| Domínio do core a 50 MHz, setup | +4,690 ns | +5,152 ns | +| Hold no pino `DRAM_CLK` | +2,971 ns | | + +Recursos: 3 216 ALMs de 18 480 (17 %), 4 058 registradores, 51 pinos de 224 e 508 416 bits de memória em bloco (16 %). A compilação completa levou cerca de 2 minutos no total de passos do Quartus. + +## 6. Limites desta medição 1. Os tempos do chip nas restrições (setup de entrada 1,5 ns, hold de entrada 0,8 ns, acesso 5,4 ns, hold de saída 2,5 ns) são valores usuais de uma SDR de 143 MHz, ainda não conferidos com o datasheet da peça. As margens negativas dos modelos lentos dependem deles. -2. O autoteste passou na placa mesmo com margem negativa no modelo lento, o que indica que o modelo é conservador; ele não prova folga em outra temperatura, outra placa ou outro lote. -3. Foi uma execução de cada modo. Não houve repetição para medir variação nem varredura da fase do clock. -4. Este benchmark não inclui o core. O custo em ciclos de rodar programas com a SDRAM como RAM, na placa, depende da plataforma `sdram` completa e não foi medido aqui. +2. O autoteste e a suíte passaram na placa mesmo com margem negativa no modelo lento, o que indica que o modelo é conservador; isso não prova folga em outra temperatura, outra placa ou outro lote. +3. Foi uma execução de cada modo e uma da suíte. Não houve repetição para medir variação nem varredura da fase do clock. +4. A suíte na placa mede correção, não ciclos. O custo em ciclos vem da simulação. From 84be77252e355d443298364930fcedbed0f41e30 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Mon, 12 Oct 2026 16:00:56 -0300 Subject: [PATCH 05/27] Fix the core-domain slack and drop the compile time in the board benchmark Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01288qnYGXPmNxMvNWBhu3QE --- docs/BENCHMARK_SDRAM_PLACA.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/BENCHMARK_SDRAM_PLACA.md b/docs/BENCHMARK_SDRAM_PLACA.md index b6337fc..463a1fa 100644 --- a/docs/BENCHMARK_SDRAM_PLACA.md +++ b/docs/BENCHMARK_SDRAM_PLACA.md @@ -84,10 +84,9 @@ Cada programa leva de 2,4 s a 3,0 s na placa. Esse tempo é dominado pelo carreg | :--- | ---: | ---: | | Leitura de dado, setup (domínio do controlador) | -0,204 ns | +0,053 ns | | Comandos e dado de escrita, setup (`DRAM_CLK`) | -0,047 ns | -0,025 ns | -| Domínio do core a 50 MHz, setup | +4,690 ns | +5,152 ns | -| Hold no pino `DRAM_CLK` | +2,971 ns | | +| Domínio do core a 50 MHz, setup | +2,029 ns | +2,026 ns | -Recursos: 3 216 ALMs de 18 480 (17 %), 4 058 registradores, 51 pinos de 224 e 508 416 bits de memória em bloco (16 %). A compilação completa levou cerca de 2 minutos no total de passos do Quartus. +Recursos: 3 216 ALMs de 18 480 (17 %), 4 058 registradores, 51 pinos de 224 e 508 416 bits de memória em bloco (16 %). ## 6. Limites desta medição From 7d99c57d90ef246c1b805a752948d10deeec8b4b Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Mon, 12 Oct 2026 17:43:54 -0300 Subject: [PATCH 06/27] Board benchmark: the run on the published toolchain image The full-platform run was repeated on ghcr.io/insper-riscv/infra-toolchain:latest with no extra layer (libglib2.0-0t64 is now in the image, uv 0.13.0): the same 89 + 6 programs pass and 82 goldens match. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01288qnYGXPmNxMvNWBhu3QE --- docs/BENCHMARK_SDRAM_PLACA.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/BENCHMARK_SDRAM_PLACA.md b/docs/BENCHMARK_SDRAM_PLACA.md index 463a1fa..b94d2af 100644 --- a/docs/BENCHMARK_SDRAM_PLACA.md +++ b/docs/BENCHMARK_SDRAM_PLACA.md @@ -59,7 +59,7 @@ Recursos: 521 ALMs de 18 480 (3 %), 923 registradores, 65 pinos de 224 e nenhum ## 5. Plataforma completa na placa (core e SDRAM) -A plataforma `sdram` do TopLevel (branch `feat/sdram-platform`, commit `4f2601f`) liga o core a 50 MHz à SDRAM, que é a única RAM, com o controlador a 142,857 MHz. A suíte rodou na placa com o `riscv-tools` dentro da imagem `ghcr.io/insper-riscv/infra-toolchain:latest` (Ubuntu 26.04.1, GHDL 6.0.0, GCC RISC-V 16.1.0 com picolibc). O Quartus 25.1std do host foi montado em modo leitura nessa imagem, com o servidor JTAG do host acessado pela rede do host. A imagem recebeu uma única camada local com a biblioteca `libglib2.0-0t64`, que as ferramentas do Quartus exigem e a imagem não trazia. +A plataforma `sdram` do TopLevel (branch `feat/sdram-platform`, commit `4f2601f`) liga o core a 50 MHz à SDRAM, que é a única RAM, com o controlador a 142,857 MHz. A suíte rodou na placa com o `riscv-tools` dentro da imagem publicada `ghcr.io/insper-riscv/infra-toolchain:latest` (Ubuntu 26.04.1, GHDL 6.0.0, GCC RISC-V 16.1.0 com picolibc, uv 0.13.0, Python 3.14.8), sem nenhuma camada adicional. O Quartus 25.1std do host foi montado em modo leitura nessa imagem, com o servidor JTAG do host acessado pela rede do host; a biblioteca `libglib2.0-0t64`, que as ferramentas do Quartus exigem, já faz parte da imagem. O resultado da seção 5.1 vale para essa execução, e uma execução anterior, com uma camada local que só acrescentava essa biblioteca, deu o mesmo resultado. Passos, cada um dentro do container: From 2345bb90bec32031a3a2683be8bd0d50458f70ed Mon Sep 17 00:00:00 2001 From: brnoschsaloli Date: Thu, 15 Oct 2026 15:36:33 -0300 Subject: [PATCH 07/27] add UART implementation plan --- docs/UART_IMPLEMENTATION_PLAN.md | 295 +++++++++++++++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 docs/UART_IMPLEMENTATION_PLAN.md diff --git a/docs/UART_IMPLEMENTATION_PLAN.md b/docs/UART_IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..67cf735 --- /dev/null +++ b/docs/UART_IMPLEMENTATION_PLAN.md @@ -0,0 +1,295 @@ +# Plano de implementação da UART + +## Estado + +- Atualizado em: 2026-10-15. +- Branch de trabalho no repositório-pai: `UART`. +- IP OpenCores baixado em `../uartCheck/uart2bus/trunk`. +- Validação standalone na DE0-CV: **concluída em hardware**. +- `UART.vhd` e seus testes unitários isolados: **concluídos (8/8 testes)**. +- Próxima etapa: integrar o periférico ao top-level do SoC em simulação. + +## Decisão de arquitetura + +A UART será um **periférico controlado pelo processador RV32IM**, e não uma +ponte externa que atua como mestre do barramento. + +O processador acessará registradores da UART em `0xC0000000`. O software +escreverá bytes para transmissão, consultará o estado do transmissor e lerá +bytes recebidos. Na primeira versão, o software usará polling; não será +necessário acrescentar `ready` ao barramento nem alterar o pipeline do core. + +A Raspberry Pi Pico/Debug Probe continua sendo a ponte elétrica USB-UART entre +o computador e a FPGA, mas não interpreta comandos nem acessa diretamente o +barramento do SoC: + +Assim, os comandos texto/binário do `uart2bus` (`r`, `w`, NOP, ACK `0x5A` +etc.) pertencem apenas ao teste standalone. No SoC integrado, o terminal recebe +e transmite os bytes produzidos/consumidos pelo programa executado no RV32IM. + +## O que foi validado no standalone + +O projeto standalone está em `../uartCheck/standalone` e usa o clock de 50 MHz +da DE0-CV com UART em 115200 baud, 8N1. O arquivo programado no Cyclone V foi +gerado e carregado com sucesso pelo Quartus/USB-Blaster. + +Ligação usada: + +| Sinal | Pico/Debug Probe | DE0-CV | Pino FPGA | +| :--- | :--- | :--- | :--- | +| TX do adaptador -> RX da FPGA | laranja | GPIO_0 pino físico 3 | `PIN_M16` | +| RX do adaptador <- TX da FPGA | amarelo | GPIO_0 pino físico 4 | `PIN_C16` | +| GND comum | preto | GPIO_0 pino físico 30 | GND | + +O script `../uartCheck/standalone/tools/test_uart2bus.py` passou em hardware nos +seguintes grupos: + +- protocolos texto e binário; +- leituras, escritas e recuperação do parser; +- comandos consecutivos e quadro enviado com pausa; +- acessos de 1, 4 e 256 bytes; +- incremento automático ligado e desligado; +- escrita sem ACK; +- wrap de endereço de `0xFFFF` para `0x0000`. + +Foram registradas duas divergências do RTL original em relação à +especificação: + +1. um caractere não hexadecimal no endereço textual pode disparar uma leitura + em vez de invalidar o comando; +2. o NOP binário devolve `0x5A` mesmo quando o bit de solicitação de ACK está + desabilitado. + +Essas divergências não afetam o periférico final, pois o parser `uart2bus` não +será integrado ao SoC. + +## Partes do OpenCores que serão reutilizadas + +Reutilizar a implementação VHDL da camada UART física: + +- `baudGen.vhd`: gera o clock-enable de 16 vezes o baud rate; +- `uartRx.vhd`: recebe quadros seriais e entrega um byte com `newRxData`; +- `uartTx.vhd`: transmite um byte e informa `txBusy`; +- `uartTop.vhd`: agrega os três blocos anteriores. + +Não integrar: + +- `uartParser.vhd`; +- `uart2BusTop.vhd` e sua interface de mestre de barramento; +- protocolos de comando texto e binário do `uart2bus`. + +Os fontes necessários serão copiados para a área do periférico com a licença +e a atribuição originais preservadas. O pacote baixado permanecerá intacto; +correções de compatibilidade e a interface com o SoC ficarão em uma cópia +vendorizada ou em wrappers do projeto. + +## Clock, reset e serial + +- Clock do periférico: `pll_clk_idexmem`, no mesmo domínio de 50 MHz do + estágio MEM e da RAM. +- Configuração inicial: 115200 baud, 8 bits, sem paridade e 1 stop bit. +- Constantes para 50 MHz/115200: `baudFreq = 0x240` e + `baudLimit = 0x3AC9`. +- Reset: `core_reset`, assíncrono e ativo em nível alto na interface do IP. +- Entrada serial: `UART_RX`; saída serial: `UART_TX`. + +Os pinos `PIN_M16` e `PIN_C16` estão reservados em comentários do projeto +principal para uma possível SPI flash futura. Eles podem ser usados nesta etapa, +mas o conflito deve ser revisto se a SPI flash externa for implementada. + +## Interface proposta de `UART.vhd` + +`UART.vhd` será o escravo memory-mapped que envolve `uartTop`. Sua interface +seguirá o padrão já usado por GPIO e TIMER: + +```vhdl +generic ( + DATA_WIDTH : natural := 32; + BAUD_FREQ : natural := 16#240#; + BAUD_LIMIT : natural := 16#3AC9# +); +port ( + clock : in std_logic; + clear : in std_logic; + data_in : in std_logic_vector(DATA_WIDTH - 1 downto 0); + address : in std_logic_vector(1 downto 0); + write : in std_logic; + read : in std_logic; + data_out : out std_logic_vector(DATA_WIDTH - 1 downto 0); + irq : out std_logic; + uart_rx : in std_logic; + uart_tx : out std_logic +); +``` + +O endereço local é um índice de palavra (`ram_addr(3 downto 2)`). A primeira +versão de software usará somente acessos alinhados de 32 bits, embora o dado +UART ocupe apenas os oito bits menos significativos. + +## Mapa de registradores + +Base da UART: `0xC0000000` (id de periférico `4`, conforme o contrato do +barramento). + +| Endereço | Nome | Acesso | Semântica | +| :--- | :--- | :--- | :--- | +| `0xC0000000` | `DATA` | R/W | Escrita em bits `[7:0]` inicia TX se livre. Leitura devolve o byte RX em `[7:0]` e consome `RX_VALID`. | +| `0xC0000004` | `STATUS` | R/W1C | Estado e erros sticky descritos abaixo. | +| `0xC0000008` | `CONTROL` | R/W | Bit 0 habilita a solicitação de interrupção de RX. | +| `0xC000000C` | reservado | - | Leitura zero; escrita sem efeito. | + +Bits de `STATUS`: + +| Bit | Nome | Significado | +| :--- | :--- | :--- | +| 0 | `RX_VALID` | Existe um byte recebido ainda não consumido. | +| 1 | `TX_READY` | O transmissor aceita um novo byte (`not txBusy`). | +| 2 | `RX_OVERRUN` | Chegou outro byte antes do anterior ser consumido. Sticky, limpo escrevendo 1 neste bit. | +| 3 | `TX_DROPPED` | Houve escrita em `DATA` enquanto TX estava ocupado. Sticky, limpo escrevendo 1 neste bit. | + +Comportamento definido para os casos de borda: + +- se outro byte chegar enquanto `RX_VALID = 1`, o byte mais recente substitui + o anterior e `RX_OVERRUN` é ativado; +- se a leitura de `DATA` e a chegada de um byte acontecerem no mesmo ciclo, a + leitura consome o byte anterior e o novo permanece armazenado com + `RX_VALID = 1`; +- escrever em `DATA` com `TX_READY = 0` não interrompe o quadro em andamento; + o novo byte é descartado e `TX_DROPPED` é ativado; +- `irq = RX_VALID and RX_IRQ_ENABLE`, mas a saída ficará desconectada na + primeira integração, pois o caminho de interrupção/CSR ainda não existe. + +## Integração no top-level + +A primeira integração será local ao top-level +`TopLevel/platforms/internal-mem/quartus/core_fpga_test.vhd`, sem antecipar a +refatoração completa do interconnect: + +1. Decodificar UART quando `ram_addr(31) = '1'` e + `ram_addr(30 downto 28) = "100"`. +2. Gerar `uart_write` e `uart_read` a partir de `ram_wren`/`ram_rden` e da + seleção da UART. +3. Entregar `ram_addr(3 downto 2)` como endereço local de registrador. +4. Bloquear `rden` e `wren` da RAM física durante acessos à UART. Isso evita que + endereços `0xC...`, que hoje chegariam truncados à RAM, causem alias. +5. Separar a saída da RAM do sinal `ram_rdata` do core e inserir o mux de + leitura RAM/UART. +6. Registrar a seleção e o dado lido do periférico para preservar a latência de + exatamente um ciclo esperada pelo estágio WB. +7. Adicionar `UART_RX` e `UART_TX` à entidade de topo e reativar as atribuições + de `PIN_M16`/`PIN_C16` no `.qsf` com I/O de 3,3 V. + +O barramento atual não possui `ready`. Isso é suficiente para esta versão: +acessos aos registradores completam em um ciclo, enquanto a latência da linha +serial é tratada pelo software através de `TX_READY` e `RX_VALID`. + +## Software inicial + +O suporte mínimo pode começar com acesso direto por ponteiros `volatile`: + +```c +#define UART_BASE 0xC0000000u +#define UART_DATA (*(volatile unsigned int *)(UART_BASE + 0x00u)) +#define UART_STATUS (*(volatile unsigned int *)(UART_BASE + 0x04u)) + +#define UART_RX_VALID (1u << 0) +#define UART_TX_READY (1u << 1) + +static void uart_putc(unsigned char value) +{ + while ((UART_STATUS & UART_TX_READY) == 0u) { + } + UART_DATA = value; +} + +static unsigned char uart_getc(void) +{ + while ((UART_STATUS & UART_RX_VALID) == 0u) { + } + return (unsigned char)UART_DATA; +} +``` + +Depois da validação, esses endereços devem ir para o YAML da plataforma e para +um cabeçalho/driver comum, em vez de permanecer duplicados nos programas de +teste. + +## Roteiro de implementação + +### Fase 1 - importar e compilar a camada física (concluída) + +1. Registrar a origem, revisão e licença do OpenCores junto aos fontes + vendorizados. +2. Copiar somente `baudGen`, `uartRx`, `uartTx`, `uartTop` e as declarações + estritamente necessárias. +3. Auditar os fontes VHDL antigos para compilação estrita com `numeric_std` e + com as ferramentas atuais (GHDL e Quartus). +4. Confirmar em simulação que as constantes escolhidas produzem 115200 baud + com clock de 50 MHz. + +### Fase 2 - implementar e testar `UART.vhd` (concluída) + +1. Implementar o banco de registradores e instanciar `uartTop`, sem parser. +2. Criar teste unitário cobrindo: + - estado depois do reset (`TX_READY = 1`, demais bits em zero); + - recepção, leitura de `DATA` e limpeza de `RX_VALID`; + - transmissão e formato serial 8N1; + - overrun de RX e descarte durante TX ocupado; + - limpeza W1C dos erros; + - leitura e chegada simultâneas; + - `CONTROL` e geração de `irq`. + +Resultado em 2026-10-15: os oito testes Cocotb de `UART` passaram com GHDL. +Sete testes usam `BAUD_FREQ = 1` e `BAUD_LIMIT = 0`, preservando os 16 pulsos +por bit do datapath real, mas acelerando a simulação. Um teste adicional usa os +valores padrão e um clock de 50 MHz para medir 115200 baud. Também foi executada +a análise VHDL conjunta de todos os periféricos sem erros. + +### Fase 3 - integrar ao SoC em simulação + +1. Instanciar o periférico e a decodificação no top-level. +2. Atualizar a lista e a ordem de fontes de simulação e do Quartus. +3. Adicionar a UART ao mapa da plataforma com base `0xC0000000`. +4. Executar toda a regressão existente para comprovar que RAM, FLASH, boot e + mailbox continuam funcionando. +5. Executar um programa RV32 que transmita uma mensagem e outro que receba e + devolva caracteres, verificando a linha serial no testbench. + +### Fase 4 - validar no hardware integrado + +1. Compilar e programar o novo `.sof`. +2. Manter a mesma ligação de três fios já validada no standalone. +3. Abrir `/dev/ttyACM0` em 115200 8N1 com `picocom`. +4. Confirmar uma mensagem de inicialização enviada pelo processador. +5. Executar um firmware de echo e testar bytes comuns, `CR`, `LF`, rajadas e + recuperação após overrun. +6. Automatizar o teste de hardware com Python, agora enviando dados crus ao + firmware em vez dos comandos do parser `uart2bus`. + +## Critérios de aceite + +A primeira versão da UART estará concluída quando: + +- o wrapper e a camada física passarem nos testes unitários; +- toda a regressão existente do RV32 continuar passando; +- Quartus compilar sem erro e o pinout corresponder à fiação validada; +- um programa executado pelo RV32 transmitir e receber bytes pela Pico; +- o teste automatizado de hardware validar TX, RX, polling e flags de erro; +- nenhum acesso à UART escrever ou ler acidentalmente a RAM por alias. + +## Evoluções adiadas + +Ficam explicitamente fora da primeira entrega: + +- integrar `irq` ao core e implementar o suporte CSR/interrupções; +- adicionar FIFOs de RX/TX; +- baud rate configurável por registrador; +- controle de paridade, tamanho de palavra ou quantidade de stop bits; +- sinal `ready` e periféricos de latência variável; +- refatoração completa do interconnect e da decodificação atualmente feita + dentro do core; +- coexistência com uma SPI flash externa nos mesmos pinos. + +Esses itens podem ser adicionados depois que o caminho mínimo +CPU -> registradores UART -> pinos seriais estiver comprovado em simulação e +na placa. From 3d230d723c47dab33a4c485bc04d8adaab02b5a9 Mon Sep 17 00:00:00 2001 From: brnoschsaloli Date: Thu, 15 Oct 2026 15:38:13 -0300 Subject: [PATCH 08/27] update peripherals w UART implementation --- Peripherals | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Peripherals b/Peripherals index 1b9d60e..9a74e1d 160000 --- a/Peripherals +++ b/Peripherals @@ -1 +1 @@ -Subproject commit 1b9d60ec5b8225728b5c3d1bc3b0b63cce1cb1ae +Subproject commit 9a74e1d9a13a284dd95318c7b06ed03440022a65 From 05baf1e61046111ce65aba2f5a55500e0766ad04 Mon Sep 17 00:00:00 2001 From: brnoschsaloli Date: Thu, 15 Oct 2026 18:50:10 -0300 Subject: [PATCH 09/27] atualizando integracao da UART no projeto --- Tests | 2 +- TopLevel | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Tests b/Tests index 4ff7260..55f8cff 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit 4ff7260205e689bd08fb73967600a751d14f6d0d +Subproject commit 55f8cffd14eff2b1d70039e36ef98efda90c5762 diff --git a/TopLevel b/TopLevel index 7e190e1..8fb7cc8 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit 7e190e16429fc30a0ea6e58776ad945639103377 +Subproject commit 8fb7cc846afd2080aa6ba125f6ec5a8abf8792ba From 7426833cea71dc98bd2840acdd5bfeed1301ffaf Mon Sep 17 00:00:00 2001 From: brnoschsaloli Date: Mon, 26 Oct 2026 09:20:30 -0300 Subject: [PATCH 10/27] feat: validate UART with separate TX and RX registers --- .github/workflows/sim.yml | 8 +++- Makefile | 11 ++++-- Peripherals | 2 +- README.md | 13 +++--- Tests | 2 +- TopLevel | 2 +- docs/UART_IMPLEMENTATION_PLAN.md | 68 +++++++++++++++++++++----------- 7 files changed, 70 insertions(+), 36 deletions(-) diff --git a/.github/workflows/sim.yml b/.github/workflows/sim.yml index 76a12c2..c11f317 100644 --- a/.github/workflows/sim.yml +++ b/.github/workflows/sim.yml @@ -28,6 +28,8 @@ jobs: path: . - name: Install Python dependencies run: uv sync + - name: Run host-side UART harness tests + run: uv run python -m unittest discover -s tests/host -v - name: Generate rv32_test.h run: uv run riscv-tools --config tools/riscv_build/config.yaml generate-header - name: Check the memory map against every copy @@ -42,7 +44,11 @@ jobs: - name: Build sim test ROM images run: uv run riscv-tools --config tools/riscv_build/config.yaml compile --emit hex - name: Run sim tests - run: uv run riscv-tools --config tools/riscv_build/config.yaml sim + # The generic simulation top has no UART pins; Tests' sim-fpga and + # physical harness own uart-echo/uart-tx. + run: | + uv run riscv-tools --config tools/riscv_build/config.yaml sim \ + --exclude uart-echo,uart-tx - name: Run per-entity VHDL unit tests run: uv run python tests/python/runner.py - name: Each repository's own checks and tests, at the pinned versions diff --git a/Makefile b/Makefile index d31d77a..cc81ebf 100644 --- a/Makefile +++ b/Makefile @@ -22,7 +22,7 @@ sync: # --------------------------------------------------------------- # 1) All .vhd/.vhdl of the repositories that hold VHDL. The Quartus IPs (Memory/ips) # and the PLL need Intel libraries and are left out. -CHECK_SRCS := $(shell find TopLevel/platforms/internal-mem/rtl Memory/sim Peripherals/common Peripherals/GPIO Peripherals/TIMER Core/common Core/I Core/M Core/cores -type f \( -name '*.vhd' -o -name '*.vhdl' \) | sort) +CHECK_SRCS := $(shell find TopLevel/platforms/internal-mem/rtl Memory/sim Peripherals/common Peripherals/GPIO Peripherals/TIMER Peripherals/UART Core/common Core/I Core/M Core/cores -type f \( -name '*.vhd' -o -name '*.vhdl' \) | sort) # 2) Dependency order (topological sort, riscv-tools vhdl-sort) ORDERED_SRCS := $(shell uv run --project Tests riscv-tools vhdl-sort $(CHECK_SRCS)) @@ -50,12 +50,15 @@ subrepos: sync $(MAKE) -C TopLevel all # --------------------------------------------------------------- -# The Tests project's simulation suite (the 89 programs on the core) +# The Tests project's generic simulation suite. The UART programs require the +# physical/hardware top and run in Tests' dedicated UART and sim-fpga flows. # --------------------------------------------------------------- sim: sync - cd Tests && uv run riscv-tools --config tools/riscv_build/config.yaml generate-header \ + cd Tests && uv run python -m unittest discover -s tests/host -v \ + && uv run riscv-tools --config tools/riscv_build/config.yaml generate-header \ && uv run riscv-tools --config tools/riscv_build/config.yaml compile --emit hex \ - && uv run riscv-tools --config tools/riscv_build/config.yaml sim + && uv run riscv-tools --config tools/riscv_build/config.yaml sim \ + --exclude uart-echo,uart-tx # Every file path the configuration lists exists (paths.yaml). paths: sync diff --git a/Peripherals b/Peripherals index 9a74e1d..d8b52ad 160000 --- a/Peripherals +++ b/Peripherals @@ -1 +1 @@ -Subproject commit 9a74e1d9a13a284dd95318c7b06ed03440022a65 +Subproject commit d8b52ad7d886f2547d23e5cb0b89d0b4f36699e3 diff --git a/README.md b/README.md index ba6f099..9addc61 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ submodule, holds the KPI reports and the integration CI, and nothing else. | [Tools](https://github.com/insper-riscv/Tools) | `riscv-tools`: compile, simulate, run on the board, certify, verify | Infra (when running) | | [Core](https://github.com/insper-riscv/Core) | the processor in VHDL, by ISA extension (`common/`, `I/`, `M/`), profiles `rv32i` and `rv32im`, entity tests | nothing | | [Memory](https://github.com/insper-riscv/Memory) | simulation models and the board's Quartus IPs | Core (the memory interface) | -| [Peripherals](https://github.com/insper-riscv/Peripherals) | GPIO and TIMER (UART later), entity tests | Core | +| [Peripherals](https://github.com/insper-riscv/Peripherals) | GPIO, TIMER and UART, with entity tests | Core | | [TopLevel](https://github.com/insper-riscv/TopLevel) | the platforms: Quartus project, PLL, simulation top, runtime, memory map, testbench | Core, Memory, Peripherals, Tools | | [Tests](https://github.com/insper-riscv/Tests) | the test programs (`asm/`, `c/`), goldens, and the flows that run them | TopLevel, Tools | | [Certification](https://github.com/insper-riscv/Certification) | the official ACT4 (riscv-arch-test) suite | Core, Memory, TopLevel, Tools | @@ -41,7 +41,7 @@ brings `Tools` along); `Infra` and `Certification` are used on their own. ```bash git clone --recurse-submodules https://github.com/insper-riscv/RV32.git cd RV32 -make all # paths, VHDL check, every repository's own checks, the 89-program suite +make all # paths, VHDL check, repository checks, generic program suite ``` The tools come from the `infra-toolchain` image of Infra (`ghcr.io/insper-riscv/infra-toolchain`); @@ -52,17 +52,18 @@ the CI runs in it. | `make paths` | every file path the configuration lists exists (`paths.yaml`, `riscv-tools check-paths`) | | `make check` | GHDL analyzes every VHDL source of the tree in one library | | `make subrepos` | `Core`, `Memory`, `Peripherals` and `TopLevel`: their own paths, syntax checks, profiles, entity tests and memory-map check | -| `make sim` | the simulation suite of `Tests`: 89 programs on the pipeline | +| `make sim` | the generic simulation suite of `Tests` plus UART-harness host tests; UART programs use the hardware-top/physical flows | The submodules sit side by side because they find each other as siblings (`../Core`, -`../Memory`, `../TopLevel`): the same layout when each is cloned on its own next to the -others, as their CI does. +`../Memory`, `../Peripherals`, `../TopLevel`): the same layout when each is cloned on +its own next to the others, as their CI does. ## Board The Quartus project is `TopLevel/platforms/internal-mem/quartus/core_fpga_test.qpf` (Cyclone V 5CEBA4F23: BOOT_ROM, FLASH and RAM inside the FPGA). Programming it and running tests on it -is `riscv-tools run` from `Tests`; see +uses the mailbox-only `riscv-tools run` suite plus the dedicated physical UART +harness from `Tests`; see [TopLevel's docs/HARDWARE_PROGRAMMING.md](https://github.com/insper-riscv/TopLevel/blob/main/docs/HARDWARE_PROGRAMMING.md). ## KPIs diff --git a/Tests b/Tests index 55f8cff..67a2382 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit 55f8cffd14eff2b1d70039e36ef98efda90c5762 +Subproject commit 67a2382902d03383c469956b01d5ae144001854e diff --git a/TopLevel b/TopLevel index 8fb7cc8..72283dd 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit 8fb7cc846afd2080aa6ba125f6ec5a8abf8792ba +Subproject commit 72283dd59b4074dd45cb76169b9d44165b69fd54 diff --git a/docs/UART_IMPLEMENTATION_PLAN.md b/docs/UART_IMPLEMENTATION_PLAN.md index 67cf735..99a5cb0 100644 --- a/docs/UART_IMPLEMENTATION_PLAN.md +++ b/docs/UART_IMPLEMENTATION_PLAN.md @@ -2,12 +2,15 @@ ## Estado -- Atualizado em: 2026-10-15. +- Atualizado em: 2026-10-26. - Branch de trabalho no repositório-pai: `UART`. - IP OpenCores baixado em `../uartCheck/uart2bus/trunk`. - Validação standalone na DE0-CV: **concluída em hardware**. -- `UART.vhd` e seus testes unitários isolados: **concluídos (8/8 testes)**. -- Próxima etapa: integrar o periférico ao top-level do SoC em simulação. +- `UART.vhd` e seus testes unitários isolados: **concluídos (9/9 testes)**. +- Novo mapa com endereços separados de TX e RX: **simulação integrada e + validação física básica concluídas**. +- Próxima etapa: ampliar a validação física para rajadas, overrun e flags de + erro. ## Decisão de arquitetura @@ -126,6 +129,9 @@ O endereço local é um índice de palavra (`ram_addr(3 downto 2)`). A primeira versão de software usará somente acessos alinhados de 32 bits, embora o dado UART ocupe apenas os oito bits menos significativos. +Não há FIFO nesta versão. RX mantém somente o byte pendente mais recente e TX +aceita um novo byte apenas quando `TX_READY = 1`. + ## Mapa de registradores Base da UART: `0xC0000000` (id de periférico `4`, conforme o contrato do @@ -133,10 +139,10 @@ barramento). | Endereço | Nome | Acesso | Semântica | | :--- | :--- | :--- | :--- | -| `0xC0000000` | `DATA` | R/W | Escrita em bits `[7:0]` inicia TX se livre. Leitura devolve o byte RX em `[7:0]` e consome `RX_VALID`. | -| `0xC0000004` | `STATUS` | R/W1C | Estado e erros sticky descritos abaixo. | -| `0xC0000008` | `CONTROL` | R/W | Bit 0 habilita a solicitação de interrupção de RX. | -| `0xC000000C` | reservado | - | Leitura zero; escrita sem efeito. | +| `0xC0000000` | `TX_DATA` | W | Escrita em bits `[7:0]` inicia TX se livre. Leitura devolve zero. | +| `0xC0000004` | `RX_DATA` | R | Leitura devolve o byte RX em `[7:0]` e consome `RX_VALID`. Escrita não tem efeito. | +| `0xC0000008` | `STATUS` | R/W1C | Estado e erros sticky descritos abaixo. | +| `0xC000000C` | `CONTROL` | R/W | Bit 0 habilita a solicitação de interrupção de RX. | Bits de `STATUS`: @@ -145,16 +151,16 @@ Bits de `STATUS`: | 0 | `RX_VALID` | Existe um byte recebido ainda não consumido. | | 1 | `TX_READY` | O transmissor aceita um novo byte (`not txBusy`). | | 2 | `RX_OVERRUN` | Chegou outro byte antes do anterior ser consumido. Sticky, limpo escrevendo 1 neste bit. | -| 3 | `TX_DROPPED` | Houve escrita em `DATA` enquanto TX estava ocupado. Sticky, limpo escrevendo 1 neste bit. | +| 3 | `TX_DROPPED` | Houve escrita em `TX_DATA` enquanto TX estava ocupado. Sticky, limpo escrevendo 1 neste bit. | Comportamento definido para os casos de borda: - se outro byte chegar enquanto `RX_VALID = 1`, o byte mais recente substitui o anterior e `RX_OVERRUN` é ativado; -- se a leitura de `DATA` e a chegada de um byte acontecerem no mesmo ciclo, a +- se a leitura de `RX_DATA` e a chegada de um byte acontecerem no mesmo ciclo, a leitura consome o byte anterior e o novo permanece armazenado com `RX_VALID = 1`; -- escrever em `DATA` com `TX_READY = 0` não interrompe o quadro em andamento; +- escrever em `TX_DATA` com `TX_READY = 0` não interrompe o quadro em andamento; o novo byte é descartado e `TX_DROPPED` é ativado; - `irq = RX_VALID and RX_IRQ_ENABLE`, mas a saída ficará desconectada na primeira integração, pois o caminho de interrupção/CSR ainda não existe. @@ -189,8 +195,9 @@ O suporte mínimo pode começar com acesso direto por ponteiros `volatile`: ```c #define UART_BASE 0xC0000000u -#define UART_DATA (*(volatile unsigned int *)(UART_BASE + 0x00u)) -#define UART_STATUS (*(volatile unsigned int *)(UART_BASE + 0x04u)) +#define UART_TX_DATA (*(volatile unsigned int *)(UART_BASE + 0x00u)) +#define UART_RX_DATA (*(volatile unsigned int *)(UART_BASE + 0x04u)) +#define UART_STATUS (*(volatile unsigned int *)(UART_BASE + 0x08u)) #define UART_RX_VALID (1u << 0) #define UART_TX_READY (1u << 1) @@ -199,14 +206,14 @@ static void uart_putc(unsigned char value) { while ((UART_STATUS & UART_TX_READY) == 0u) { } - UART_DATA = value; + UART_TX_DATA = value; } static unsigned char uart_getc(void) { while ((UART_STATUS & UART_RX_VALID) == 0u) { } - return (unsigned char)UART_DATA; + return (unsigned char)UART_RX_DATA; } ``` @@ -232,20 +239,22 @@ teste. 1. Implementar o banco de registradores e instanciar `uartTop`, sem parser. 2. Criar teste unitário cobrindo: - estado depois do reset (`TX_READY = 1`, demais bits em zero); - - recepção, leitura de `DATA` e limpeza de `RX_VALID`; + - recepção, leitura de `RX_DATA` e limpeza de `RX_VALID`; - transmissão e formato serial 8N1; - overrun de RX e descarte durante TX ocupado; - limpeza W1C dos erros; - leitura e chegada simultâneas; + - separação e ausência de efeitos colaterais entre `TX_DATA` e `RX_DATA`; - `CONTROL` e geração de `irq`. -Resultado em 2026-10-15: os oito testes Cocotb de `UART` passaram com GHDL. -Sete testes usam `BAUD_FREQ = 1` e `BAUD_LIMIT = 0`, preservando os 16 pulsos -por bit do datapath real, mas acelerando a simulação. Um teste adicional usa os -valores padrão e um clock de 50 MHz para medir 115200 baud. Também foi executada -a análise VHDL conjunta de todos os periféricos sem erros. +Atualização em 2026-10-26: os nove testes Cocotb de `UART` passaram com GHDL. +Oito testes usam `BAUD_FREQ = 1` e `BAUD_LIMIT = 0`, preservando os 16 pulsos +por bit do datapath real, mas acelerando a simulação. Eles incluem a verificação +de que uma leitura de `TX_DATA` e uma escrita em `RX_DATA` não produzem efeitos +colaterais. Um teste adicional usa os valores padrão e um clock de 50 MHz para +medir 115200 baud. A análise VHDL conjunta de todos os periféricos também passou. -### Fase 3 - integrar ao SoC em simulação +### Fase 3 - integrar ao SoC em simulação (concluída) 1. Instanciar o periférico e a decodificação no top-level. 2. Atualizar a lista e a ordem de fontes de simulação e do Quartus. @@ -255,7 +264,10 @@ a análise VHDL conjunta de todos os periféricos sem erros. 5. Executar um programa RV32 que transmita uma mensagem e outro que receba e devolva caracteres, verificando a linha serial no testbench. -### Fase 4 - validar no hardware integrado +Resultado em 2026-10-26: `uart-tx` e `uart-echo` passaram no top de FPGA +simulado usando, respectivamente, `TX_DATA` e `RX_DATA` em endereços separados. + +### Fase 4 - validar no hardware integrado (mapa separado validado) 1. Compilar e programar o novo `.sof`. 2. Manter a mesma ligação de três fios já validada no standalone. @@ -266,6 +278,18 @@ a análise VHDL conjunta de todos os periféricos sem erros. 6. Automatizar o teste de hardware com Python, agora enviando dados crus ao firmware em vez dos comandos do parser `uart2bus`. +Resultado em 2026-10-26: com o `.sof` do novo mapa previamente carregado, o +harness `uart_hardware_test.py --skip-program` passou nos dois firmwares. O +`uart-echo` devolveu exatamente `RX test\r\n`; em seguida, o harness carregou +`uart-tx` pela memória JTAG e recebeu exatamente `UART OK\r\n`. Ambos os +firmwares finalizaram com `MAILBOX=1`, produzindo o resultado final +`INTEGRATED UART HARDWARE TEST: PASS (uart-echo, uart-tx)`. Isso valida na placa +o caminho CPU -> registradores separados `TX_DATA`/`RX_DATA` -> pinos seriais, +incluindo o polling de `STATUS`. + +Ainda permanecem pendentes os casos de estresse desta fase: rajadas, recuperação +após overrun e observação das flags de erro no teste físico automatizado. + ## Critérios de aceite A primeira versão da UART estará concluída quando: From d4e5a889a481f2f86b711a7554481636532a81dc Mon Sep 17 00:00:00 2001 From: brnoschsaloli Date: Mon, 26 Oct 2026 10:16:07 -0300 Subject: [PATCH 11/27] test: integrate UART error and burst validation --- .github/workflows/sim.yml | 4 ++-- Makefile | 2 +- Tests | 2 +- TopLevel | 2 +- docs/UART_IMPLEMENTATION_PLAN.md | 23 +++++++++++++++++------ 5 files changed, 22 insertions(+), 11 deletions(-) diff --git a/.github/workflows/sim.yml b/.github/workflows/sim.yml index c11f317..56177e7 100644 --- a/.github/workflows/sim.yml +++ b/.github/workflows/sim.yml @@ -45,10 +45,10 @@ jobs: run: uv run riscv-tools --config tools/riscv_build/config.yaml compile --emit hex - name: Run sim tests # The generic simulation top has no UART pins; Tests' sim-fpga and - # physical harness own uart-echo/uart-tx. + # physical harness own uart-echo/uart-tx/uart-errors. run: | uv run riscv-tools --config tools/riscv_build/config.yaml sim \ - --exclude uart-echo,uart-tx + --exclude uart-echo,uart-tx,uart-errors - name: Run per-entity VHDL unit tests run: uv run python tests/python/runner.py - name: Each repository's own checks and tests, at the pinned versions diff --git a/Makefile b/Makefile index cc81ebf..be3c236 100644 --- a/Makefile +++ b/Makefile @@ -58,7 +58,7 @@ sim: sync && uv run riscv-tools --config tools/riscv_build/config.yaml generate-header \ && uv run riscv-tools --config tools/riscv_build/config.yaml compile --emit hex \ && uv run riscv-tools --config tools/riscv_build/config.yaml sim \ - --exclude uart-echo,uart-tx + --exclude uart-echo,uart-tx,uart-errors # Every file path the configuration lists exists (paths.yaml). paths: sync diff --git a/Tests b/Tests index 67a2382..96f834b 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit 67a2382902d03383c469956b01d5ae144001854e +Subproject commit 96f834bc516739f86803794a7e55d92fa8006c52 diff --git a/TopLevel b/TopLevel index 72283dd..8827e83 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit 72283dd59b4074dd45cb76169b9d44165b69fd54 +Subproject commit 8827e834ef5c83ee3ff940a6f0dec5a9d9f08960 diff --git a/docs/UART_IMPLEMENTATION_PLAN.md b/docs/UART_IMPLEMENTATION_PLAN.md index 99a5cb0..112c124 100644 --- a/docs/UART_IMPLEMENTATION_PLAN.md +++ b/docs/UART_IMPLEMENTATION_PLAN.md @@ -8,9 +8,9 @@ - Validação standalone na DE0-CV: **concluída em hardware**. - `UART.vhd` e seus testes unitários isolados: **concluídos (9/9 testes)**. - Novo mapa com endereços separados de TX e RX: **simulação integrada e - validação física básica concluídas**. -- Próxima etapa: ampliar a validação física para rajadas, overrun e flags de - erro. + validação física concluídas**. +- Rajadas, `RX_OVERRUN`, `TX_DROPPED` e limpeza W1C: **validados em simulação + e na placa**. ## Decisão de arquitetura @@ -267,7 +267,7 @@ medir 115200 baud. A análise VHDL conjunta de todos os periféricos também pas Resultado em 2026-10-26: `uart-tx` e `uart-echo` passaram no top de FPGA simulado usando, respectivamente, `TX_DATA` e `RX_DATA` em endereços separados. -### Fase 4 - validar no hardware integrado (mapa separado validado) +### Fase 4 - validar no hardware integrado (concluída) 1. Compilar e programar o novo `.sof`. 2. Manter a mesma ligação de três fios já validada no standalone. @@ -287,8 +287,19 @@ firmwares finalizaram com `MAILBOX=1`, produzindo o resultado final o caminho CPU -> registradores separados `TX_DATA`/`RX_DATA` -> pinos seriais, incluindo o polling de `STATUS`. -Ainda permanecem pendentes os casos de estresse desta fase: rajadas, recuperação -após overrun e observação das flags de erro no teste físico automatizado. +Atualização em 2026-10-26: o firmware `uart-errors` e o harness coordenado +passaram tanto no top FPGA simulado quanto na placa. O teste provocou uma +escrita durante TX ocupado e recebeu `ATR`, confirmando `TX_DROPPED`, o descarte +do segundo byte e sua limpeza W1C. Em seguida, enviou `0x12 0x34` sem consumir o +primeiro byte e recebeu `OB`, confirmando `RX_OVERRUN`, retenção do byte mais +recente e sua limpeza W1C. Por fim, o firmware devolveu exatamente a rajada crua +de 32 bytes `0x00` a `0x1f`, seguida por `P`, sem novas flags de erro. O teste +terminou com `MAILBOX=1` e +`INTEGRATED UART HARDWARE TEST: PASS (uart-echo, uart-errors)`. + +Com esse resultado, os critérios da primeira versão da UART foram atendidos em +simulação e em hardware, incluindo TX, RX, polling, endereços separados, +comportamento de sobrecarga e flags sticky com limpeza W1C. ## Critérios de aceite From 1d6f3e9f28ade945d14d153ff9cf24a876c5ef46 Mon Sep 17 00:00:00 2001 From: "peng1104-agent[bot]" <343739453+peng1104-agent[bot]@users.noreply.github.com> Date: Mon, 26 Oct 2026 13:24:07 +0000 Subject: [PATCH 12/27] =?UTF-8?q?Docs:=20autores=202026.1,=20norma=20C23?= =?UTF-8?q?=20e=20guias=20bil=C3=ADngues?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AUTHORS.en.md | 29 ++++++++ AUTHORS.md | 29 ++++++++ CITATION.cff | 52 ++++++++++++++ CONTRIBUTING.en.md | 176 +++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 176 +++++++++++++++++++++++++++++++++++++++++++++ README.en.md | 61 ++++++++++++++++ README.md | 110 ++++++++++------------------ 7 files changed, 561 insertions(+), 72 deletions(-) create mode 100644 AUTHORS.en.md create mode 100644 AUTHORS.md create mode 100644 CITATION.cff create mode 100644 CONTRIBUTING.en.md create mode 100644 CONTRIBUTING.md create mode 100644 README.en.md diff --git a/AUTHORS.en.md b/AUTHORS.en.md new file mode 100644 index 0000000..33d5fcd --- /dev/null +++ b/AUTHORS.en.md @@ -0,0 +1,29 @@ +# Authors + +🌐 [Português](AUTHORS.md) · [English](AUTHORS.en.md) + +This repository is part of the Computer Engineering and Computer Science Capstone at [Insper](https://www.insper.edu.br), led by Professor **Rafael Corsi Ferrão** ([@rafaelcorsi](https://github.com/rafaelcorsi)) and funded by [CTI Renato Archer](https://www.gov.br/cti/pt-br). The list below gathers the people who took part in the development of `RV32IM`. + +## 1. Authors of this Module + +| Period | Name | GitHub account | +| :--- | :--- | :--- | +| 2026.2 | Lucas Hix | [@Peng1104](https://github.com/Peng1104) | +| 2026.2 | Breno Schneider Salles de Oliveira | [@brnoschsaloli](https://github.com/brnoschsaloli) | +| 2026.2 | Artur Cruz | [@arturacruz](https://github.com/arturacruz) | +| 2026.1 | Henrique Rocha Bomfim | [@HenriqueRBomfim](https://github.com/HenriqueRBomfim) | +| 2026.1 | Pedro Carvalho Ribeiro Neto | [@Ribs2004](https://github.com/Ribs2004) | +| 2026.1 | Luiz Felipe Borelli Durand | [@LuizDurand](https://github.com/LuizDurand) | +| 2026.1 | Luka Siqueira Ferreira de Figueiredo | [@lukafig](https://github.com/lukafig) | +| 2025.2 | Ilana Chaia Finger | [@ilacftemp](https://github.com/ilacftemp) | +| 2025.2 | Leonardo Merlin Paloschi | [@leonardopaloschi](https://github.com/leonardopaloschi) | +| 2025.2 | Lucas Fernando De Souza Lima | [@lucasouzamil](https://github.com/lucasouzamil) | +| 2025.2 | Pedro Pereira Cecilio Ventura | [@pedropcventura](https://github.com/pedropcventura) | + +## 2. Project History + +Each Capstone group continued the work of the previous one. The complete list of groups, including those who made no commits in this repository, is in the [organization README](https://github.com/insper-riscv/.github/blob/main/profile/README.en.md). + +--- + +Copyright 2026 Insper. Licensed under the [Apache License, Version 2.0](LICENSE). diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 0000000..57a1307 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,29 @@ +# Autores + +🌐 [Português](AUTHORS.md) · [English](AUTHORS.en.md) + +Este repositório faz parte do Capstone de Engenharia de Computação e Ciência da Computação do [Insper](https://www.insper.edu.br), liderado pelo professor **Rafael Corsi Ferrão** ([@rafaelcorsi](https://github.com/rafaelcorsi)) e financiado pelo [CTI Renato Archer](https://www.gov.br/cti/pt-br). A lista abaixo reúne as pessoas que participaram na elaboração do `RV32`. + +## 1. Autores deste Módulo + +| Período | Nome | Conta no GitHub | +| :--- | :--- | :--- | +| 2026.2 | Lucas Hix | [@Peng1104](https://github.com/Peng1104) | +| 2026.2 | Breno Schneider Salles de Oliveira | [@brnoschsaloli](https://github.com/brnoschsaloli) | +| 2026.2 | Artur Cruz | [@arturacruz](https://github.com/arturacruz) | +| 2026.1 | Henrique Rocha Bomfim | [@HenriqueRBomfim](https://github.com/HenriqueRBomfim) | +| 2026.1 | Pedro Carvalho Ribeiro Neto | [@Ribs2004](https://github.com/Ribs2004) | +| 2026.1 | Luiz Felipe Borelli Durand | [@LuizDurand](https://github.com/LuizDurand) | +| 2026.1 | Luka Siqueira Ferreira de Figueiredo | [@lukafig](https://github.com/lukafig) | +| 2025.2 | Ilana Chaia Finger | [@ilacftemp](https://github.com/ilacftemp) | +| 2025.2 | Leonardo Merlin Paloschi | [@leonardopaloschi](https://github.com/leonardopaloschi) | +| 2025.2 | Lucas Fernando De Souza Lima | [@lucasouzamil](https://github.com/lucasouzamil) | +| 2025.2 | Pedro Pereira Cecilio Ventura | [@pedropcventura](https://github.com/pedropcventura) | + +## 2. Histórico do Projeto + +Cada grupo do Capstone continuou o trabalho do anterior. A lista completa dos grupos, incluindo quem não fez commits neste repositório, está no [README da organização](https://github.com/insper-riscv/.github/blob/main/profile/README.md). + +--- + +Copyright 2026 Insper. Licenciado sob a [Apache License, Version 2.0](LICENSE). diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..f85a2ec --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,52 @@ +cff-version: 1.2.0 +message: "Se você usar este software, cite-o com os metadados abaixo. / If you use this software, please cite it using the metadata below." +type: software +title: "RV32IM: SoC RISC-V em VHDL (repositório agregador)" +abstract: >- + Repositório agregador do SoC RISC-V RV32IM em VHDL-2008: fixa por submódulo + as versões de Core, Memory, Peripherals, TopLevel e Testes e executa a + integração contínua conjunta. Desenvolvido no Capstone do Insper, financiado + pelo CTI Renato Archer. +authors: + - family-names: Hix + given-names: Lucas + alias: Peng1104 + - family-names: Oliveira + given-names: Breno Schneider Salles de + alias: brnoschsaloli + - family-names: Cruz + given-names: Artur + alias: arturacruz + - family-names: Bomfim + given-names: Henrique Rocha + alias: HenriqueRBomfim + - family-names: Neto + given-names: Pedro Carvalho Ribeiro + alias: Ribs2004 + - family-names: Durand + given-names: Luiz Felipe Borelli + alias: LuizDurand + - family-names: Figueiredo + given-names: Luka Siqueira Ferreira de + alias: lukafig + - family-names: Finger + given-names: Ilana Chaia + alias: ilacftemp + - family-names: Paloschi + given-names: Leonardo Merlin + alias: leonardopaloschi + - family-names: Lima + given-names: Lucas Fernando De Souza + alias: lucasouzamil + - family-names: Ventura + given-names: Pedro Pereira Cecilio + alias: pedropcventura +repository-code: "https://github.com/insper-riscv/RV32IM" +url: "https://github.com/insper-riscv/RV32IM" +license: Apache-2.0 +keywords: + - RISC-V + - RV32IM + - VHDL + - SoC + - FPGA diff --git a/CONTRIBUTING.en.md b/CONTRIBUTING.en.md new file mode 100644 index 0000000..4d43734 --- /dev/null +++ b/CONTRIBUTING.en.md @@ -0,0 +1,176 @@ +# Contribution Guide + +🌐 [Português](CONTRIBUTING.md) · [English](CONTRIBUTING.en.md) + +This document defines the mandatory coding, structural organization, documentation, and verification rules for any contribution to the `RV32IM` repository. + +## 1. VHDL Standards and Synthesis Compatibility + +All hardware code in the project is written and validated under the **IEEE 1076-2008 (VHDL-2008)** standard, compiled in GHDL with the `--std=08` flag, and synthesized in Quartus Prime. + +| Rule | Specification | +| :--- | :--- | +| Language standard | VHDL-2008 (`--std=08`) across all `.vhd` files | +| Permitted IEEE packages | Only `ieee.std_logic_1164.all` and `ieee.numeric_std.all` | +| Prohibited packages | `std_logic_arith`, `std_logic_unsigned`, and `std_logic_signed` must never be used | +| Module instantiation | Use direct entity instantiation (`u_name : entity work.entity_name`), without redundant `component` declarations | +| Port mapping (`port map`) | Always associate by name (`i_port => signal`) and use intermediate signals for logical expressions or dynamic slices, because GHDL requires globally static expressions in port map actuals | +| Latch prevention | Every signal assigned in a combinational process or conditional assignment must receive an explicit default value across all branches (`else` / `when others =>`) | + +The reference standard is [IEEE Std 1076-2008, IEEE Standard VHDL Language Reference Manual](https://standards.ieee.org/ieee/1076/3666/). In academic work, cite it with the BibTeX entry below: + +```bibtex +@misc{ieee1076, + title = {IEEE Standard VHDL Language Reference Manual}, + author = {{IEEE}}, + year = {2008}, + note = {IEEE Std 1076-2008}, + howpublished = {\url{https://standards.ieee.org/ieee/1076/3666/}} +} +``` + +The organization into reusable blocks with explicit interfaces and parameters follows [IEEE Std 1685, IEEE Standard for IP-XACT](https://standards.ieee.org/ieee/1685/10583/), whose BibTeX entry is: + +```bibtex +@misc{ieee1685, + title = {IEEE Standard for IP-XACT, Standard Structure for Packaging, Integrating, and Reusing IP within Tool Flows}, + author = {{IEEE}}, + year = {2022}, + note = {IEEE Std 1685-2022}, + howpublished = {\url{https://standards.ieee.org/ieee/1685/10583/}} +} +``` + +The design-for-reuse methodology for hardware blocks follows the book *Reuse Methodology Manual for System-on-a-Chip Designs* (3rd edition, Springer, 2002) by Keating and Bricaud, a copyrighted work available only by purchase or through an institutional library: + +```bibtex +@book{keating2002rmm, + title = {Reuse Methodology Manual for System-on-a-Chip Designs}, + author = {Keating, Michael and Bricaud, Pierre}, + edition = {3}, + year = {2002}, + publisher = {Springer}, + isbn = {978-1402071416} +} +``` + +## 2. C Standard and Test Programs + +All C code in the project (test programs in `Tests/c/`, runtime and platform startup code) is written under the **ISO/IEC 9899:2024 (C23)** standard, compiled with the `-std=c23` flag. C is the language of the programs that exercise the processor, and it is through them that the other modules are verified: Core, Memory, Peripherals and TopLevel run these programs in simulation and on the board, and the result of each one is compared against its expected golden. + +| Rule | Specification | +| :--- | :--- | +| Language standard | C23 (`-std=c23`) across all `.c` and `.h` files | +| Compiler extensions | Do not use GNU extensions when the standard has an equivalent | +| Standard library | picolibc, as provided by the Infra toolchain image | + +The reference standard is [ISO/IEC 9899:2024, Programming languages: C](https://www.iso.org/standard/82075.html). In academic work, cite it with the BibTeX entry below: + +```bibtex +@misc{iso9899, + title = {Programming languages --- C}, + author = {{ISO/IEC}}, + year = {2024}, + note = {ISO/IEC 9899:2024}, + howpublished = {\url{https://www.iso.org/standard/82075.html}} +} +``` + +## 3. Mandatory VHDL Naming and Port Prefixes + +All code identifiers must be written in **English**, whereas all comments and file headers must be written in **Portuguese**. + +| VHDL Element | Convention | Examples | +| :--- | :--- | :--- | +| Entities, architectures, and packages | `snake_case` | `mux_2x1`, `generic_register`, `alu_consts`, `rtl` | +| Input ports (`in`) | Mandatory `i_` prefix + `snake_case` | `i_clk`, `i_rst`, `i_data`, `i_addr` | +| Output ports (`out`) | Mandatory `o_` prefix + `snake_case` | `o_data`, `o_irq`, `o_ready` | +| Generics | Descriptive `snake_case` | `data_width`, `addr_width` | +| Constants (`constant`) | `UPPER_SNAKE_CASE` | `WORD_WIDTH`, `REG_ZERO` | +| Types and subtypes (`type`, `subtype`) | `snake_case` with `_t` suffix | `word_t`, `reg_idx_t` | +| Internal signals and variables | `snake_case` | `rd_data`, `wr_en` | +| Instance labels | `u_` prefix + `snake_case` | `u_reg_file`, `u_mux` | + +## 4. VHDL File Headers and Docstrings + +### 4.1. Mandatory File Header + +Every `.vhd` file must begin with a 72-column header block (`-- ====...====`) in Portuguese describing the architectural responsibility of the package or entity: + +```vhdl +-- ============================================================================ +-- +-- ============================================================================ +-- +-- ============================================================================ +``` + +Internal sections within an architecture must use 72-column single-hyphen dividers (`-- ----...----`). + +### 4.2. Individual Docstring Above Every Declaration + +Every individual `generic`, `port`, `constant`, `subtype`, `type`, `signal`, `alias`, and `variable` declaration must have its own descriptive comment in Portuguese on the line immediately above it. End-of-line inline comments do not replace the docstring above the declaration: + +```vhdl +entity mux_2x1 is + generic( + -- Largura em bits dos barramentos de entrada e saída + data_width : natural := 32 + ); + port( + -- Entrada selecionada quando i_sel vale '0' + i_d0 : in std_logic_vector(data_width - 1 downto 0); + -- Entrada selecionada quando i_sel vale '1' + i_d1 : in std_logic_vector(data_width - 1 downto 0); + -- Bit seletor entre i_d0 ('0') e i_d1 ('1') + i_sel : in std_logic; + -- Saída multiplexada resultante + o_out : out std_logic_vector(data_width - 1 downto 0) + ); +end entity mux_2x1; +``` + +## 5. Design for Reuse and Zero Duplication + +The project follows the *Design for Reuse* practice described in the *Reuse Methodology Manual* (Keating and Bricaud). Each rule below translates into a criterion that can be checked in review: + +| # | Rule | Review criterion | +| :--- | :--- | :--- | +| 1 | **Single-purpose blocks:** separate control, datapath, and protocol interface into distinct entities | An entity with more than one job must be split; a structural top level only connects instances | +| 2 | **Parameterization through `generic` and package constants:** no width, depth, or feature fixed inside the architecture | No magic literal in logic; codes, addresses, and selectors live in constant packages | +| 3 | **Standardized, interchangeable interfaces:** entities with the same port signature can be swapped without changing whoever instantiates them | Changing a block's architecture must not change its ports or its externally observable behavior | +| 4 | **Lean ports:** the entity exposes only the ports and generics it uses | Signals or generics "for future use" do not belong in an entity | +| 5 | **Dependence on ports only:** the upper level knows the entity declaration, never the internals of its architecture | The top level never carries fine-grained implementation logic | +| 6 | **Composition with already verified leaf blocks:** reuse existing primitives | Do not reimplement with ad-hoc processes or operators what a primitive or an already computed signal provides | + +## 6. Markdown Documentation Rules + +Every `README`, `CONTRIBUTING`, and `AUTHORS` maintains mirrored versions in Portuguese (`*.md`) and English (`*.en.md`), following these rules: + +1. **Language switcher and license footer:** every `README.md` and `README.en.md` includes the `🌐 [Português](...) · [English](...)` switcher at the top, and every `.md` file ends with the copyright footer linking to `LICENSE`. +2. **Numbered progressive sections:** all sections starting at `##` must be numbered (`## 1.`, `### 1.1.`, `## 2.`) in a logical reading order. +3. **Direct punctuation:** + - **Em-dashes are prohibited** in prose and tables; use commas, parentheses, semicolons, or colons according to the actual syntactic relationship. + - **Chained colons are prohibited** (more than one `:` in the same sentence or table cell). +4. **Behavior explanation:** never cite an internal file, module, or signal name as if the name itself explained what the system does; always describe the operation performed. +5. **Non-redundant tables and LaTeX:** structured data belongs in Markdown tables and mathematical/boolean equations in LaTeX blocks (`$$ ... $$` or `$ ... $`), without repeating in prose what the table or equation already states. +6. **No changelog or open TODOs in technical docs:** architecture and contract documents describe exclusively the current state, without internal changelogs or lists of future tasks. +7. **Usage guides only instruct:** installation and run instructions say how to do it, without justifying the choice of method. + +## 7. Mandatory Verification Before Opening a Pull Request + +Any change to code, configuration, or documentation must pass all commands below without errors before submission: + +```bash +git submodule update --init --recursive # Initializes every submodule at its pinned version +make all # Runs paths, the VHDL check, every repository's own checks, and the simulation suite +``` + +When adding, renaming, or removing any versioned file, immediately update: +- `paths.yaml` +- the submodule pointers +- `README.md`, `README.en.md`, and the affected documentation + +--- + +Copyright 2026 Insper. Licensed under the [Apache License, Version 2.0](LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..611c617 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,176 @@ +# Guia de Contribuição + +🌐 [Português](CONTRIBUTING.md) · [English](CONTRIBUTING.en.md) + +Este documento define as regras obrigatórias de codificação, organização estrutural, documentação e verificação para qualquer contribuição ao repositório `RV32IM`. + +## 1. Normas VHDL e Compatibilidade de Síntese + +Todo código de hardware do projeto é escrito e validado sob a norma **IEEE 1076-2008 (VHDL-2008)**, compilado no GHDL com a flag `--std=08` e sintetizado no Quartus Prime. + +| Regra | Especificação | +| :--- | :--- | +| Norma da linguagem | VHDL-2008 (`--std=08`) em todos os arquivos `.vhd` | +| Pacotes IEEE permitidos | Apenas `ieee.std_logic_1164.all` e `ieee.numeric_std.all` | +| Pacotes proibidos | `std_logic_arith`, `std_logic_unsigned` e `std_logic_signed` nunca devem ser utilizados | +| Instanciação de módulos | Usar instanciação direta de entidade (`u_nome : entity work.nome_da_entidade`), sem declarações `component` redundantes | +| Mapeamento de portas (`port map`) | Associar sempre por nome (`i_porta => sinal`) e utilizar sinais intermediários para expressões lógicas ou fatias dinâmicas, pois o GHDL exige expressões globalmente estáticas nos formais/atuais de porta | +| Inferência de latches | Todo sinal atribuído em processo combinacional ou atribuição condicional deve receber valor padrão explícito em todos os ramos (`else` / `when others =>`) | + +A norma de referência é a [IEEE Std 1076-2008, IEEE Standard VHDL Language Reference Manual](https://standards.ieee.org/ieee/1076/3666/). Em trabalhos acadêmicos, cite-a com a entrada BibTeX abaixo: + +```bibtex +@misc{ieee1076, + title = {IEEE Standard VHDL Language Reference Manual}, + author = {{IEEE}}, + year = {2008}, + note = {IEEE Std 1076-2008}, + howpublished = {\url{https://standards.ieee.org/ieee/1076/3666/}} +} +``` + +A organização em blocos reutilizáveis com interfaces e parâmetros explícitos segue a [IEEE Std 1685, IEEE Standard for IP-XACT](https://standards.ieee.org/ieee/1685/10583/), cuja entrada BibTeX é: + +```bibtex +@misc{ieee1685, + title = {IEEE Standard for IP-XACT, Standard Structure for Packaging, Integrating, and Reusing IP within Tool Flows}, + author = {{IEEE}}, + year = {2022}, + note = {IEEE Std 1685-2022}, + howpublished = {\url{https://standards.ieee.org/ieee/1685/10583/}} +} +``` + +A metodologia de projeto para reuso de blocos de hardware segue o livro *Reuse Methodology Manual for System-on-a-Chip Designs* (3ª edição, Springer, 2002), de Keating e Bricaud, obra com direitos autorais cujo acesso depende de compra ou de biblioteca institucional: + +```bibtex +@book{keating2002rmm, + title = {Reuse Methodology Manual for System-on-a-Chip Designs}, + author = {Keating, Michael and Bricaud, Pierre}, + edition = {3}, + year = {2002}, + publisher = {Springer}, + isbn = {978-1402071416} +} +``` + +## 2. Norma C e Programas de Teste + +Todo código em C do projeto (programas de teste em `Tests/c/`, runtime e código de inicialização da plataforma) é escrito sob a norma **ISO/IEC 9899:2024 (C23)**, compilado com a flag `-std=c23`. O C é a linguagem dos programas que exercitam o processador, e é por meio deles que os demais módulos são verificados: o Core, a Memory, os Peripherals e o TopLevel executam esses programas na simulação e na placa, e o resultado de cada um é comparado com o golden esperado. + +| Regra | Especificação | +| :--- | :--- | +| Norma da linguagem | C23 (`-std=c23`) em todos os arquivos `.c` e `.h` | +| Extensões do compilador | Não utilizar extensões GNU quando houver equivalente na norma | +| Biblioteca padrão | picolibc, conforme a imagem de toolchain do Infra | + +A norma de referência é a [ISO/IEC 9899:2024, Programming languages: C](https://www.iso.org/standard/82075.html). Em trabalhos acadêmicos, cite-a com a entrada BibTeX abaixo: + +```bibtex +@misc{iso9899, + title = {Programming languages --- C}, + author = {{ISO/IEC}}, + year = {2024}, + note = {ISO/IEC 9899:2024}, + howpublished = {\url{https://www.iso.org/standard/82075.html}} +} +``` + +## 3. Nomenclatura e Prefixos Obrigatórios em VHDL + +Todos os identificadores de código devem ser escritos em **inglês**, enquanto todos os comentários e cabeçalhos devem ser escritos em **português**. + +| Elemento VHDL | Convenção | Exemplos | +| :--- | :--- | :--- | +| Entidades, arquiteturas e pacotes | `snake_case` | `mux_2x1`, `generic_register`, `alu_consts`, `rtl` | +| Portas de entrada (`in`) | Prefixo obrigatório `i_` + `snake_case` | `i_clk`, `i_rst`, `i_data`, `i_addr` | +| Portas de saída (`out`) | Prefixo obrigatório `o_` + `snake_case` | `o_data`, `o_irq`, `o_ready` | +| Generics | `snake_case` descritivo | `data_width`, `addr_width` | +| Constantes (`constant`) | `UPPER_SNAKE_CASE` | `WORD_WIDTH`, `REG_ZERO` | +| Tipos e subtipos (`type`, `subtype`) | `snake_case` com sufixo `_t` | `word_t`, `reg_idx_t` | +| Sinais e variáveis internas | `snake_case` | `rd_data`, `wr_en` | +| Rótulos de instância | Prefixo `u_` + `snake_case` | `u_reg_file`, `u_mux` | + +## 4. Cabeçalhos (Headers) e Docstrings em VHDL + +### 4.1. Cabeçalho Obrigatório de Arquivo + +Todo arquivo `.vhd` deve iniciar com um bloco de cabeçalho de 72 colunas (`-- ====...====`) em português descrevendo a responsabilidade arquitetural do pacote ou da entidade: + +```vhdl +-- ============================================================================ +-- +-- ============================================================================ +-- +-- ============================================================================ +``` + +Seções internas de uma arquitetura devem utilizar separadores de 72 colunas com hífens simples (`-- ----...----`). + +### 4.2. Docstring Individual Acima de Cada Declaração + +Cada declaração individual de `generic`, `port`, `constant`, `subtype`, `type`, `signal`, `alias` e `variable` deve possuir seu próprio comentário descritivo em português imediatamente na linha acima. Comentários na mesma linha (inline ao final da linha) não substituem a docstring acima da declaração: + +```vhdl +entity mux_2x1 is + generic( + -- Largura em bits dos barramentos de entrada e saída + data_width : natural := 32 + ); + port( + -- Entrada selecionada quando i_sel vale '0' + i_d0 : in std_logic_vector(data_width - 1 downto 0); + -- Entrada selecionada quando i_sel vale '1' + i_d1 : in std_logic_vector(data_width - 1 downto 0); + -- Bit seletor entre i_d0 ('0') e i_d1 ('1') + i_sel : in std_logic; + -- Saída multiplexada resultante + o_out : out std_logic_vector(data_width - 1 downto 0) + ); +end entity mux_2x1; +``` + +## 5. Projeto para Reuso e Proibição de Duplicação + +O projeto segue a prática de *Design for Reuse* descrita no *Reuse Methodology Manual* (Keating e Bricaud). Cada regra abaixo se traduz em um critério verificável em revisão: + +| # | Regra | Critério de revisão | +| :--- | :--- | :--- | +| 1 | **Blocos de propósito único:** separar controle, caminho de dados e interface de protocolo em entidades distintas | Uma entidade com mais de uma função deve ser dividida; um topo estrutural apenas conecta instâncias | +| 2 | **Parametrização por `generic` e constantes de pacote:** nenhuma largura, profundidade ou recurso fixado dentro da arquitetura | Nenhum literal mágico na lógica; códigos, endereços e seletores residem em pacotes de constantes | +| 3 | **Interfaces padronizadas e intercambiáveis:** entidades com a mesma assinatura de portas podem ser trocadas sem alterar quem as instancia | Trocar a arquitetura de um bloco não pode mudar suas portas nem seu comportamento observável de fora | +| 4 | **Portas enxutas:** a entidade expõe somente as portas e os generics que usa | Sinais ou generics "para uso futuro" não entram em uma entidade | +| 5 | **Dependência apenas das portas:** o nível superior conhece a declaração da entidade, nunca detalhes internos de sua arquitetura | O topo nunca carrega lógica fina de implementação | +| 6 | **Composição com blocos-folha já verificados:** reaproveitar primitivos existentes | Não reimplementar com processos ou operadores redundantes o que um primitivo ou um sinal já calculado fornece | + +## 6. Regras de Documentação Markdown + +Todo `README` e todo `CONTRIBUTING` e `AUTHORS` mantêm versões espelhadas em português (`*.md`) e em inglês (`*.en.md`), obedecendo às seguintes regras: + +1. **Seletor de idioma e rodapé de licença:** todo `README.md` e `README.en.md` traz no topo o seletor `🌐 [Português](...) · [English](...)`, e todo arquivo `.md` encerra com o rodapé de copyright e link para `LICENSE`. +2. **Seções numeradas e progressivas:** todas as seções a partir de `##` devem ser numeradas (`## 1.`, `### 1.1.`, `## 2.`) em ordem lógica de leitura. +3. **Pontuação direta:** + - **Proibido o uso de travessão** em prosa ou tabelas; utilize vírgula, parênteses, ponto e vírgula ou dois-pontos conforme a relação sintática real. + - **Proibidos dois-pontos encadeados** (mais de um `:` na mesma frase ou célula de tabela). +4. **Explicação de comportamento:** nunca cite o nome de um arquivo, módulo ou sinal interno como se o próprio nome explicasse o que o sistema faz; descreva sempre a operação realizada. +5. **Tabelas e LaTeX sem redundância:** dados estruturados devem estar em tabelas Markdown e expressões matemáticas/lógicas em blocos LaTeX (`$$ ... $$` ou `$ ... $`), sem repetir em prosa o que a tabela ou equação já enuncia. +6. **Sem histórico ou pendências na documentação técnica:** documentos de arquitetura e contratos descrevem exclusivamente o estado atual, sem changelogs internos nem listas de tarefas futuras. +7. **Guias de uso apenas instruem:** instruções de instalação e execução dizem como fazer, sem justificar a escolha do método. + +## 7. Verificação Obrigatória Antes de Abrir Pull Request + +Qualquer alteração em código, configuração ou documentação deve passar sem erros pelos comandos abaixo antes do envio: + +```bash +git submodule update --init --recursive # Inicializa todos os submódulos nas versões fixadas +make all # Executa paths, verificação VHDL, verificações de cada repositório e a suíte de simulação +``` + +Ao adicionar, renomear ou remover qualquer arquivo versionado, atualize imediatamente: +- `paths.yaml` +- os ponteiros dos submódulos +- `README.md`, `README.en.md` e a documentação afetada + +--- + +Copyright 2026 Insper. Licenciado sob a [Apache License, Version 2.0](LICENSE). diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..af72ce5 --- /dev/null +++ b/README.en.md @@ -0,0 +1,61 @@ +# RV32IM + +🌐 [Português](README.md) · [English](README.en.md) + +![Pipeline diagram](Core/docs/img/multi-stage-rv32m_pipeline_final-Pipeline.jpg) + +32-bit RISC-V SoC (RV32I + M) in VHDL, with an in-order 5-stage pipeline, its memories, peripherals, and board platform, plus the tools and tests around them. The work is split across repositories of the [insper-riscv](https://github.com/insper-riscv) organization, one responsibility each. This repository is the aggregator: it pins a version of each one as a git submodule and holds the KPI reports and the joint continuous integration. + +## 1. Documentation + +- [AUTHORS.en.md](AUTHORS.en.md): authors with commits in the repository, with name and GitHub account. +- [CONTRIBUTING.en.md](CONTRIBUTING.en.md): mandatory contribution rules, VHDL-2008 standard, C23 standard (ISO/IEC 9899:2024), documentation rules, and verification before opening a Pull Request. +- [CITATION.cff](CITATION.cff): software citation metadata. +- [docs/README_kpis.md](docs/README_kpis.md): KPI scripts (clock, resources, CPI, and tests) from a Quartus run. +- [docs/BENCHMARK_SDRAM.md](docs/BENCHMARK_SDRAM.md) and [docs/BENCHMARK_SDRAM_PLACA.md](docs/BENCHMARK_SDRAM_PLACA.md): SDRAM benchmark. + +## 2. Repositories + +| Repository | Responsibility | Depends on | +| :--- | :--- | :--- | +| [Infra](https://github.com/insper-riscv/Infra) | The machine: the toolchain image (GCC with picolibc, Spike, GHDL, uv) in which continuous integration runs | Nothing | +| [Tools](https://github.com/insper-riscv/Tools) | `riscv-tools`: compile, simulate, run on the board, certify, and verify | Infra (at run time) | +| [Core](https://github.com/insper-riscv/Core) | The processor in VHDL, by ISA extension, profiles, and per-entity tests | Nothing | +| [Memory](https://github.com/insper-riscv/Memory) | Simulation models and the board Quartus IPs | Core (memory interface) | +| [Peripherals](https://github.com/insper-riscv/Peripherals) | GPIO and TIMER, with per-entity tests | Core | +| [TopLevel](https://github.com/insper-riscv/TopLevel) | The platforms: Quartus project, PLL, simulation top, runtime, memory map, and testbench | Core, Memory, Peripherals, Tools | +| [Tests](https://github.com/insper-riscv/Tests) | The test programs (`asm/`, `c/`), goldens, and the flows that run them | TopLevel, Tools | +| [Certification](https://github.com/insper-riscv/Certification) | The official ACT4 suite (riscv-arch-test) | Core, Memory, TopLevel, Tools | + +`Core`, `Memory`, `Peripherals`, `TopLevel`, and `Tests` are submodules of this repository (`Tests` brings `Tools` along); `Infra` and `Certification` are used on their own. + +## 3. Cloning and Running + +```bash +git clone --recurse-submodules https://github.com/insper-riscv/RV32IM.git +cd RV32IM +make all # paths, VHDL check, every repository's own checks, and the 89-program suite +``` + +The tools come from the `infra-toolchain` image (`ghcr.io/insper-riscv/infra-toolchain`), in which continuous integration runs. + +| Target | What it runs | +| :--- | :--- | +| `make paths` | Existence of every path listed in the configuration (`paths.yaml`, `riscv-tools check-paths`) | +| `make check` | GHDL analysis of every VHDL source of the tree in a single library | +| `make subrepos` | Paths, syntax checks, profiles, per-entity tests, and memory map of `Core`, `Memory`, `Peripherals`, and `TopLevel` | +| `make sim` | Simulation suite of `Tests`: 89 programs on the pipeline | + +The submodules sit side by side because they find each other as siblings (`../Core`, `../Memory`, `../TopLevel`), the same layout as when each is cloned next to the others by continuous integration. + +## 4. Board + +The Quartus project is `TopLevel/platforms/internal-mem/quartus/core_fpga_test.qpf` (Cyclone V 5CEBA4F23, with BOOT_ROM, FLASH, and RAM inside the FPGA). Programming it and running tests on it is done with `riscv-tools run` from `Tests`, as described in [TopLevel's docs/HARDWARE_PROGRAMMING.md](https://github.com/insper-riscv/TopLevel/blob/main/docs/HARDWARE_PROGRAMMING.md). + +## 5. KPIs + +`scripts/kpi_report.py` and `scripts/compare_kpis.py` build the KPI reports (clock, resources, CPI, and tests) from a Quartus run, as described in [docs/README_kpis.md](docs/README_kpis.md). + +--- + +Copyright 2026 Insper. Licensed under the [Apache License, Version 2.0](LICENSE). diff --git a/README.md b/README.md index ba6f099..b4f6318 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,61 @@ -# RV32IM: a RISC-V SoC in VHDL +# RV32IM -![Pipeline Diagram](Core/docs/img/multi-stage-rv32m_pipeline_final-Pipeline.jpg) +🌐 [Português](README.md) · [English](README.en.md) -**Team:** -| Name | Role | -|------|------| -| Henrique Rocha Bomfim | Pipeline: design & implementation | -| Pedro Carvalho Ribeiro Neto | Pipeline: design & implementation | -| Luiz Felipe Borelli Durand | Multdiv, KPIs & Tests | -| Luka Siqueira Ferreira de Figueiredo | Tests, KPIs & multdiv | +![Diagrama do pipeline](Core/docs/img/multi-stage-rv32m_pipeline_final-Pipeline.jpg) -**Advisor:** [Rafael Corsi](https://github.com/rafaelcorsi) +SoC RISC-V de 32 bits (RV32I + M) em VHDL, com pipeline em ordem de 5 estágios, suas memórias, periféricos e plataforma de placa, e as ferramentas e testes ao redor. O trabalho é dividido em repositórios da organização [insper-riscv](https://github.com/insper-riscv), um por responsabilidade. Este repositório é o agregador: fixa uma versão de cada um como submódulo git, guarda os relatórios de KPI e a integração contínua conjunta. ---- +## 1. Documentação -## What this repository is +- [AUTHORS.md](AUTHORS.md): autores com commits no repositório, com nome e conta do GitHub. +- [CONTRIBUTING.md](CONTRIBUTING.md): regras obrigatórias de contribuição, norma VHDL-2008, norma C23 (ISO/IEC 9899:2024), regras de documentação e verificação antes de abrir Pull Request. +- [CITATION.cff](CITATION.cff): metadados para citação do software. +- [docs/README_kpis.md](docs/README_kpis.md): scripts de KPI (frequência, recursos, CPI e testes) a partir de uma execução do Quartus. +- [docs/BENCHMARK_SDRAM.md](docs/BENCHMARK_SDRAM.md) e [docs/BENCHMARK_SDRAM_PLACA.md](docs/BENCHMARK_SDRAM_PLACA.md): benchmark com SDRAM. -A 32-bit RISC-V (RV32I + M) processor with a 5-stage in-order pipeline, its memories, -peripherals and board platform, and the tools and tests around them. The work is split -in repositories of [insper-riscv](https://github.com/insper-riscv), one responsibility -each; **this repository is the parent**: it pins a version of every one of them as a git -submodule, holds the KPI reports and the integration CI, and nothing else. +## 2. Repositórios -| Repository | Responsibility | Depends on | +| Repositório | Responsabilidade | Depende de | | :--- | :--- | :--- | -| [Infra](https://github.com/insper-riscv/Infra) | the machine: the toolchain image (GCC with picolibc, Spike, GHDL, uv) the CI runs in | nothing | -| [Tools](https://github.com/insper-riscv/Tools) | `riscv-tools`: compile, simulate, run on the board, certify, verify | Infra (when running) | -| [Core](https://github.com/insper-riscv/Core) | the processor in VHDL, by ISA extension (`common/`, `I/`, `M/`), profiles `rv32i` and `rv32im`, entity tests | nothing | -| [Memory](https://github.com/insper-riscv/Memory) | simulation models and the board's Quartus IPs | Core (the memory interface) | -| [Peripherals](https://github.com/insper-riscv/Peripherals) | GPIO and TIMER (UART later), entity tests | Core | -| [TopLevel](https://github.com/insper-riscv/TopLevel) | the platforms: Quartus project, PLL, simulation top, runtime, memory map, testbench | Core, Memory, Peripherals, Tools | -| [Tests](https://github.com/insper-riscv/Tests) | the test programs (`asm/`, `c/`), goldens, and the flows that run them | TopLevel, Tools | -| [Certification](https://github.com/insper-riscv/Certification) | the official ACT4 (riscv-arch-test) suite | Core, Memory, TopLevel, Tools | +| [Infra](https://github.com/insper-riscv/Infra) | A máquina: a imagem de toolchain (GCC com picolibc, Spike, GHDL, uv) em que a integração contínua executa | Nada | +| [Tools](https://github.com/insper-riscv/Tools) | `riscv-tools`: compilar, simular, executar na placa, certificar e verificar | Infra (na execução) | +| [Core](https://github.com/insper-riscv/Core) | O processador em VHDL, por extensão da ISA, perfis e testes por entidade | Nada | +| [Memory](https://github.com/insper-riscv/Memory) | Modelos de simulação e IPs Quartus da placa | Core (interface de memória) | +| [Peripherals](https://github.com/insper-riscv/Peripherals) | GPIO e TIMER, com testes por entidade | Core | +| [TopLevel](https://github.com/insper-riscv/TopLevel) | As plataformas: projeto Quartus, PLL, topo de simulação, runtime, mapa de memória e testbench | Core, Memory, Peripherals, Tools | +| [Tests](https://github.com/insper-riscv/Tests) | Os programas de teste (`asm/`, `c/`), goldens e os fluxos que os executam | TopLevel, Tools | +| [Certification](https://github.com/insper-riscv/Certification) | A suíte oficial ACT4 (riscv-arch-test) | Core, Memory, TopLevel, Tools | -`Core`, `Memory`, `Peripherals`, `TopLevel` and `Tests` are submodules here (`Tests` -brings `Tools` along); `Infra` and `Certification` are used on their own. +`Core`, `Memory`, `Peripherals`, `TopLevel` e `Tests` são submódulos deste repositório (`Tests` traz o `Tools` junto); `Infra` e `Certification` são usados isoladamente. -## Clone and run +## 3. Clonagem e Execução ```bash -git clone --recurse-submodules https://github.com/insper-riscv/RV32.git -cd RV32 -make all # paths, VHDL check, every repository's own checks, the 89-program suite +git clone --recurse-submodules https://github.com/insper-riscv/RV32IM.git +cd RV32IM +make all # paths, verificação VHDL, verificações de cada repositório e a suíte de 89 programas ``` -The tools come from the `infra-toolchain` image of Infra (`ghcr.io/insper-riscv/infra-toolchain`); -the CI runs in it. +As ferramentas vêm da imagem `infra-toolchain` (`ghcr.io/insper-riscv/infra-toolchain`), em que a integração contínua executa. -| Target | What it runs | +| Alvo | O que executa | | :--- | :--- | -| `make paths` | every file path the configuration lists exists (`paths.yaml`, `riscv-tools check-paths`) | -| `make check` | GHDL analyzes every VHDL source of the tree in one library | -| `make subrepos` | `Core`, `Memory`, `Peripherals` and `TopLevel`: their own paths, syntax checks, profiles, entity tests and memory-map check | -| `make sim` | the simulation suite of `Tests`: 89 programs on the pipeline | - -The submodules sit side by side because they find each other as siblings (`../Core`, -`../Memory`, `../TopLevel`): the same layout when each is cloned on its own next to the -others, as their CI does. +| `make paths` | Existência de todos os caminhos listados na configuração (`paths.yaml`, `riscv-tools check-paths`) | +| `make check` | Análise de todos os fontes VHDL da árvore em uma única biblioteca do GHDL | +| `make subrepos` | Caminhos, verificações de sintaxe, perfis, testes por entidade e mapa de memória de `Core`, `Memory`, `Peripherals` e `TopLevel` | +| `make sim` | Suíte de simulação do `Tests`: 89 programas sobre o pipeline | -## Board +Os submódulos ficam lado a lado porque se encontram como irmãos (`../Core`, `../Memory`, `../TopLevel`), o mesmo arranjo de quando cada um é clonado ao lado dos demais pela integração contínua. -The Quartus project is `TopLevel/platforms/internal-mem/quartus/core_fpga_test.qpf` (Cyclone V -5CEBA4F23: BOOT_ROM, FLASH and RAM inside the FPGA). Programming it and running tests on it -is `riscv-tools run` from `Tests`; see -[TopLevel's docs/HARDWARE_PROGRAMMING.md](https://github.com/insper-riscv/TopLevel/blob/main/docs/HARDWARE_PROGRAMMING.md). +## 4. Placa -## KPIs +O projeto Quartus é `TopLevel/platforms/internal-mem/quartus/core_fpga_test.qpf` (Cyclone V 5CEBA4F23, com BOOT_ROM, FLASH e RAM dentro da FPGA). A programação e a execução de testes nela são feitas por `riscv-tools run` a partir do `Tests`, conforme [docs/HARDWARE_PROGRAMMING.md do TopLevel](https://github.com/insper-riscv/TopLevel/blob/main/docs/HARDWARE_PROGRAMMING.md). -`scripts/kpi_report.py` and `scripts/compare_kpis.py` build the KPI reports (clock, resources, -CPI, tests) from a Quartus run; see [docs/README_kpis.md](docs/README_kpis.md). +## 5. KPIs -## History +`scripts/kpi_report.py` e `scripts/compare_kpis.py` geram os relatórios de KPI (clock, recursos, CPI e testes) a partir de uma execução do Quartus, conforme [docs/README_kpis.md](docs/README_kpis.md). -The processor used to live in this repository alone (`src/`, `tests/`, `Tests/` as a -submodule). It was split in 2026; every moved file kept its history and authorship -(`git filter-repo`). Recover any earlier state with git: - -| Tag | What it holds | -| :--- | :--- | -| `pre-refactor` | the repositories as they were before the split (also in Infra, Tools, Tests, Certification) | -| `archive/l2ip` | `L2IP/`, the deprecated SoC top with GPIO and LEDs, the reference for the bus design | -| `archive/3stage-core` | `rv32i3stage_core.vhd`, the 3-stage core | -| `archive/ram1port-quartus-build` | `tests/FPGA/RAM1PORT`, a committed Quartus build (56 MB) | -| `archive/stale-memory-ips` | the outdated `src/RAM1PORT`, `ROM1PORT`, `ROM_IP` | -| `archive/legacy-src` | `AndGate`, `RV32M`, `conversorHex7Seg`, `mhu`, `edgeDetector`, old tops and Quartus projects | -| `archive/gpio-rom-simulation` | the stale `ROM_simulation` copy of `src/GPIO` | -| `archive/fpga-core-legacy` | the old JTAG `.tcl` helpers, `output_mifs`, generated Questa output, `clk.sdc`, `qar_info.json` | -| `archive/legacy-env` | `.vscode`, `.devcontainer`, `Dockerfile.quick`, `requirements.txt` (a third-party image, the old cocotb environment) | - -`git checkout -- ` brings a path back. - -## License +--- -Apache License 2.0, see [LICENSE](LICENSE). +Copyright 2026 Insper. Licenciado sob a [Apache License, Version 2.0](LICENSE). From 235a4d1ab437057f993bf1f3fdf607b076cb9282 Mon Sep 17 00:00:00 2001 From: brnoschsaloli Date: Mon, 26 Oct 2026 11:34:08 -0300 Subject: [PATCH 13/27] ci: update TopLevel UART workflow --- TopLevel | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TopLevel b/TopLevel index 8827e83..9fa606d 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit 8827e834ef5c83ee3ff940a6f0dec5a9d9f08960 +Subproject commit 9fa606d76cf8251a247780bc2137a1a0d84bf17f From d895f625ce41f6a87bf13b00ceb4f2be7c79e11a Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 14:32:11 -0300 Subject: [PATCH 14/27] Register the Infra submodule and use SSH URLs for the submodules Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- .gitmodules | 13 ++++++++----- Infra | 1 + 2 files changed, 9 insertions(+), 5 deletions(-) create mode 160000 Infra diff --git a/.gitmodules b/.gitmodules index 1d1042d..ac0e87e 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,15 +1,18 @@ [submodule "Tests"] path = Tests - url = https://github.com/insper-riscv/Tests.git + url = git@github.com:insper-riscv/Tests.git [submodule "Core"] path = Core - url = https://github.com/insper-riscv/Core.git + url = git@github.com:insper-riscv/Core.git [submodule "Memory"] path = Memory - url = https://github.com/insper-riscv/Memory.git + url = git@github.com:insper-riscv/Memory.git [submodule "Peripherals"] path = Peripherals - url = https://github.com/insper-riscv/Peripherals.git + url = git@github.com:insper-riscv/Peripherals.git [submodule "TopLevel"] path = TopLevel - url = https://github.com/insper-riscv/TopLevel.git + url = git@github.com:insper-riscv/TopLevel.git +[submodule "Infra"] + path = Infra + url = git@github.com:insper-riscv/Infra.git diff --git a/Infra b/Infra new file mode 160000 index 0000000..79b11b0 --- /dev/null +++ b/Infra @@ -0,0 +1 @@ +Subproject commit 79b11b0dc851f6bdb88c1ad25c3aca9b3509790b From 13c575e155b9ec0be75a8e616d809e9f338e6fe3 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 14:33:19 -0300 Subject: [PATCH 15/27] Point every submodule at its final branch and add the Certification submodule Core, Memory, Peripherals, TopLevel, Tests, Infra and Certification now point at their final branches, which carry the open pull requests merged and the pipeline, Zicsr, Zifencei, Zmmul and Zicclsm work. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- .gitmodules | 3 +++ Certification | 1 + Core | 2 +- Infra | 2 +- Memory | 2 +- Peripherals | 2 +- 6 files changed, 8 insertions(+), 4 deletions(-) create mode 160000 Certification diff --git a/.gitmodules b/.gitmodules index ac0e87e..e2252dd 100644 --- a/.gitmodules +++ b/.gitmodules @@ -16,3 +16,6 @@ [submodule "Infra"] path = Infra url = git@github.com:insper-riscv/Infra.git +[submodule "Certification"] + path = Certification + url = git@github.com:insper-riscv/Certification.git diff --git a/Certification b/Certification new file mode 160000 index 0000000..8a4be42 --- /dev/null +++ b/Certification @@ -0,0 +1 @@ +Subproject commit 8a4be42480ccf65cdd3c75da3b018266d680d53b diff --git a/Core b/Core index 8e15a8e..07a08cb 160000 --- a/Core +++ b/Core @@ -1 +1 @@ -Subproject commit 8e15a8e68350e1ef01f1426baf07527e902d815e +Subproject commit 07a08cb04723778e5024d9510090dc775db54b36 diff --git a/Infra b/Infra index 79b11b0..ed5ee83 160000 --- a/Infra +++ b/Infra @@ -1 +1 @@ -Subproject commit 79b11b0dc851f6bdb88c1ad25c3aca9b3509790b +Subproject commit ed5ee8392ffea937bdc10137a7dad6d1bf67cb53 diff --git a/Memory b/Memory index 4e339b5..18dd839 160000 --- a/Memory +++ b/Memory @@ -1 +1 @@ -Subproject commit 4e339b595dbfcd9d51d71e2b6c3b3b769835c779 +Subproject commit 18dd839a70ed5a4e1984d777a9dbe983318bf8f4 diff --git a/Peripherals b/Peripherals index d8b52ad..3ec2ade 160000 --- a/Peripherals +++ b/Peripherals @@ -1 +1 @@ -Subproject commit d8b52ad7d886f2547d23e5cb0b89d0b4f36699e3 +Subproject commit 3ec2adecb2827941a0614f30aef85ff921809175 From 706b081acd0b72e66ad103c2e2e3855be8a0e11b Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 14:53:10 -0300 Subject: [PATCH 16/27] Add the Common-Components submodule and point every submodule at its final branch The generic blocks live in Common-Components and Core, Memory and Peripherals import them as a sibling. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- .gitmodules | 3 +++ Certification | 2 +- Common-Components | 1 + Core | 2 +- Makefile | 5 +++-- Memory | 2 +- Peripherals | 2 +- README.en.md | 7 ++++--- README.md | 7 ++++--- Tests | 2 +- TopLevel | 2 +- 11 files changed, 21 insertions(+), 14 deletions(-) create mode 160000 Common-Components diff --git a/.gitmodules b/.gitmodules index e2252dd..e60b81a 100644 --- a/.gitmodules +++ b/.gitmodules @@ -19,3 +19,6 @@ [submodule "Certification"] path = Certification url = git@github.com:insper-riscv/Certification.git +[submodule "Common-Components"] + path = Common-Components + url = git@github.com:insper-riscv/Common-Components.git diff --git a/Certification b/Certification index 8a4be42..652251f 160000 --- a/Certification +++ b/Certification @@ -1 +1 @@ -Subproject commit 8a4be42480ccf65cdd3c75da3b018266d680d53b +Subproject commit 652251f91507b7d6f0c06b5bf175f861f30468cf diff --git a/Common-Components b/Common-Components new file mode 160000 index 0000000..44a5429 --- /dev/null +++ b/Common-Components @@ -0,0 +1 @@ +Subproject commit 44a542922e7e34360ac2337833ec5e0275b8239f diff --git a/Core b/Core index 07a08cb..e2ee2b5 160000 --- a/Core +++ b/Core @@ -1 +1 @@ -Subproject commit 07a08cb04723778e5024d9510090dc775db54b36 +Subproject commit e2ee2b5f0c69dc28c638b0685da77dc259ece961 diff --git a/Makefile b/Makefile index 7bb0a81..3ab29ec 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -# The parent repository: it pins Core, Memory, Peripherals, TopLevel and Tests, and +# The parent repository: it pins Core, Memory, Peripherals, TopLevel, Tests, Infra and Certification, and # this Makefile runs them together. Each of them has its own Makefile and uv project; # `git submodule update --init --recursive` first. SHELL := /bin/bash @@ -22,7 +22,7 @@ sync: # --------------------------------------------------------------- # 1) All .vhd/.vhdl of the repositories that hold VHDL. The Quartus IPs (Memory/ips) # and the PLL need Intel libraries and are left out. -CHECK_SRCS := $(shell find TopLevel/platforms/internal-mem/rtl Memory/sim Peripherals/common Peripherals/GPIO Peripherals/TIMER Peripherals/UART Core/common Core/I Core/M Core/cores -type f \( -name '*.vhd' -o -name '*.vhdl' \) | sort) +CHECK_SRCS := $(shell find TopLevel/platforms/internal-mem/rtl Memory/sim Common-Components Peripherals/GPIO Peripherals/TIMER Peripherals/UART Core/common Core/I Core/M Core/Zicsr Core/Zifencei Core/core -type f \( -name '*.vhd' -o -name '*.vhdl' \) | sort) # 2) Dependency order (topological sort, riscv-tools vhdl-sort) ORDERED_SRCS := $(shell uv run --project Tests riscv-tools vhdl-sort $(CHECK_SRCS)) @@ -44,6 +44,7 @@ check: # other as siblings (../Core, ../Memory, ...), which is how the submodules sit. # --------------------------------------------------------------- subrepos: sync + $(MAKE) -C Common-Components check $(MAKE) -C Core paths check profiles test $(MAKE) -C Memory paths check test $(MAKE) -C Peripherals paths check test diff --git a/Memory b/Memory index 18dd839..3074120 160000 --- a/Memory +++ b/Memory @@ -1 +1 @@ -Subproject commit 18dd839a70ed5a4e1984d777a9dbe983318bf8f4 +Subproject commit 3074120cf7e045e46a2aa0f896a73357584c1d63 diff --git a/Peripherals b/Peripherals index 3ec2ade..ffb72a0 160000 --- a/Peripherals +++ b/Peripherals @@ -1 +1 @@ -Subproject commit 3ec2adecb2827941a0614f30aef85ff921809175 +Subproject commit ffb72a0766ac8773457fc7428d31e5f756e43a3e diff --git a/README.en.md b/README.en.md index be872b9..19aa3fd 100644 --- a/README.en.md +++ b/README.en.md @@ -20,14 +20,15 @@ | :--- | :--- | :--- | | [Infra](https://github.com/insper-riscv/Infra) | The machine: the toolchain image (GCC with picolibc, Spike, GHDL, uv) in which continuous integration runs | Nothing | | [Tools](https://github.com/insper-riscv/Tools) | `riscv-tools`: compile, simulate, run on the board, certify, and verify | Infra (at run time) | -| [Core](https://github.com/insper-riscv/Core) | The processor in VHDL, by ISA extension, profiles, and per-entity tests | Nothing | +| [Common-Components](https://github.com/insper-riscv/Common-Components) | The generic VHDL blocks (adder, flip-flop, registers, multiplexers, one-hot decoder, and tri-state buffer) that Core, Memory, and Peripherals import | Nothing | +| [Core](https://github.com/insper-riscv/Core) | The processor in VHDL, by ISA extension, profiles, and per-entity tests | Common-Components | | [Memory](https://github.com/insper-riscv/Memory) | Simulation models and the board Quartus IPs | Core (memory interface) | -| [Peripherals](https://github.com/insper-riscv/Peripherals) | GPIO, TIMER, and UART, with per-entity tests | Core | +| [Peripherals](https://github.com/insper-riscv/Peripherals) | GPIO, TIMER, and UART, with per-entity tests | Common-Components | | [TopLevel](https://github.com/insper-riscv/TopLevel) | The platforms: Quartus project, PLL, simulation top, runtime, memory map, and testbench | Core, Memory, Peripherals, Tools | | [Tests](https://github.com/insper-riscv/Tests) | The test programs (`asm/`, `c/`), goldens, and the flows that run them | TopLevel, Tools | | [Certification](https://github.com/insper-riscv/Certification) | The official ACT4 suite (riscv-arch-test) | Core, Memory, TopLevel, Tools | -`Core`, `Memory`, `Peripherals`, `TopLevel`, `Tests`, `Infra`, and `Certification` are submodules of this repository (`Tests` and `Certification` bring `Tools` along). +`Common-Components`, `Core`, `Memory`, `Peripherals`, `TopLevel`, `Tests`, `Infra`, and `Certification` are submodules of this repository (`Tests` and `Certification` bring `Tools` along). ## 3. Cloning and Running diff --git a/README.md b/README.md index 6c87dec..0444f27 100644 --- a/README.md +++ b/README.md @@ -20,14 +20,15 @@ SoC RISC-V de 32 bits (RV32I + M) em VHDL, com pipeline em ordem de 5 estágios, | :--- | :--- | :--- | | [Infra](https://github.com/insper-riscv/Infra) | A máquina: a imagem de toolchain (GCC com picolibc, Spike, GHDL, uv) em que a integração contínua executa | Nada | | [Tools](https://github.com/insper-riscv/Tools) | `riscv-tools`: compilar, simular, executar na placa, certificar e verificar | Infra (na execução) | -| [Core](https://github.com/insper-riscv/Core) | O processador em VHDL, por extensão da ISA, perfis e testes por entidade | Nada | +| [Common-Components](https://github.com/insper-riscv/Common-Components) | Os blocos genéricos de VHDL (somador, flip-flop, registradores, multiplexadores, decodificador one-hot e buffer de três estados) que Core, Memory e Peripherals importam | Nada | +| [Core](https://github.com/insper-riscv/Core) | O processador em VHDL, por extensão da ISA, perfis e testes por entidade | Common-Components | | [Memory](https://github.com/insper-riscv/Memory) | Modelos de simulação e IPs Quartus da placa | Core (interface de memória) | -| [Peripherals](https://github.com/insper-riscv/Peripherals) | GPIO, TIMER e UART, com testes por entidade | Core | +| [Peripherals](https://github.com/insper-riscv/Peripherals) | GPIO, TIMER e UART, com testes por entidade | Common-Components | | [TopLevel](https://github.com/insper-riscv/TopLevel) | As plataformas: projeto Quartus, PLL, topo de simulação, runtime, mapa de memória e testbench | Core, Memory, Peripherals, Tools | | [Tests](https://github.com/insper-riscv/Tests) | Os programas de teste (`asm/`, `c/`), goldens e os fluxos que os executam | TopLevel, Tools | | [Certification](https://github.com/insper-riscv/Certification) | A suíte oficial ACT4 (riscv-arch-test) | Core, Memory, TopLevel, Tools | -`Core`, `Memory`, `Peripherals`, `TopLevel`, `Tests`, `Infra` e `Certification` são submódulos deste repositório (`Tests` e `Certification` trazem o `Tools` junto). +`Common-Components`, `Core`, `Memory`, `Peripherals`, `TopLevel`, `Tests`, `Infra` e `Certification` são submódulos deste repositório (`Tests` e `Certification` trazem o `Tools` junto). ## 3. Clonagem e Execução diff --git a/Tests b/Tests index 1c94848..99ef113 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit 1c94848fda3855a52c974f2e931e67a986e3db03 +Subproject commit 99ef113d8b1b3621cb01a88105e7de523f6c5b7e diff --git a/TopLevel b/TopLevel index cada13f..909a907 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit cada13f338bfc0b6f9e67ecf5d6af88fc10e95a6 +Subproject commit 909a90707ab95e36eaf8394614c27e81ba85be6c From f3dbf08032841db20a0f2948bcd812d48bbcc520 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 15:03:37 -0300 Subject: [PATCH 17/27] Run the workflows on the ci-* images and take the final submodules Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- .github/workflows/sim.yml | 4 ++-- .github/workflows/vhdl_syntax_check.yml | 4 ++-- Certification | 2 +- Core | 2 +- Memory | 2 +- Peripherals | 2 +- README.en.md | 2 +- README.md | 2 +- Tests | 2 +- TopLevel | 2 +- docs/BENCHMARK_SDRAM.md | 2 +- docs/BENCHMARK_SDRAM_PLACA.md | 2 +- scripts/toolchain.sh | 5 ++--- 13 files changed, 16 insertions(+), 17 deletions(-) diff --git a/.github/workflows/sim.yml b/.github/workflows/sim.yml index 56177e7..b8932b4 100644 --- a/.github/workflows/sim.yml +++ b/.github/workflows/sim.yml @@ -13,10 +13,10 @@ concurrency: jobs: cocotb-ghdl: runs-on: ubuntu-26.04 - # insper-riscv/Infra's toolchain image: GHDL, the RISC-V GCC with picolibc, + # the ci-asm image of insper-riscv/Infra: GHDL, the RISC-V GCC with picolibc, # Spike and uv already on PATH. container: - image: ghcr.io/insper-riscv/infra-toolchain:latest + image: ghcr.io/insper-riscv/ci-asm:latest defaults: run: working-directory: Tests diff --git a/.github/workflows/vhdl_syntax_check.yml b/.github/workflows/vhdl_syntax_check.yml index 87b6d45..f9ed1bd 100644 --- a/.github/workflows/vhdl_syntax_check.yml +++ b/.github/workflows/vhdl_syntax_check.yml @@ -22,9 +22,9 @@ jobs: ghdl-check: name: GHDL syntax check runs-on: ubuntu-26.04 - # insper-riscv/Infra's toolchain image: GHDL and uv on PATH. + # the ci-vhdl image of insper-riscv/Infra: GHDL and uv on PATH. container: - image: ghcr.io/insper-riscv/infra-toolchain:latest + image: ghcr.io/insper-riscv/ci-vhdl:latest steps: - name: Checkout diff --git a/Certification b/Certification index 652251f..d1213e7 160000 --- a/Certification +++ b/Certification @@ -1 +1 @@ -Subproject commit 652251f91507b7d6f0c06b5bf175f861f30468cf +Subproject commit d1213e762be1b24a9029a4c6f27371d2d7880d1e diff --git a/Core b/Core index e2ee2b5..05d4fef 160000 --- a/Core +++ b/Core @@ -1 +1 @@ -Subproject commit e2ee2b5f0c69dc28c638b0685da77dc259ece961 +Subproject commit 05d4fef8f1fc4b95779615962ea371cba1a2880a diff --git a/Memory b/Memory index 3074120..600a4e4 160000 --- a/Memory +++ b/Memory @@ -1 +1 @@ -Subproject commit 3074120cf7e045e46a2aa0f896a73357584c1d63 +Subproject commit 600a4e41a4fc198207321cd66dd0c1edcf4e4ac5 diff --git a/Peripherals b/Peripherals index ffb72a0..e3f1c59 160000 --- a/Peripherals +++ b/Peripherals @@ -1 +1 @@ -Subproject commit ffb72a0766ac8773457fc7428d31e5f756e43a3e +Subproject commit e3f1c598fa990c1d0f9f6bc22ad3332d9768aedf diff --git a/README.en.md b/README.en.md index 19aa3fd..370764c 100644 --- a/README.en.md +++ b/README.en.md @@ -38,7 +38,7 @@ cd RV32 make all # paths, VHDL check, every repository's own checks, and the 89-program suite ``` -The tools come from the `infra-toolchain` image (`ghcr.io/insper-riscv/infra-toolchain`), in which continuous integration runs. +The tools come from the `ci-asm` image (`ghcr.io/insper-riscv/ci-asm`), in which continuous integration runs. | Target | What it runs | | :--- | :--- | diff --git a/README.md b/README.md index 0444f27..2633e12 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ cd RV32 make all # paths, verificação VHDL, verificações de cada repositório e a suíte de 89 programas ``` -As ferramentas vêm da imagem `infra-toolchain` (`ghcr.io/insper-riscv/infra-toolchain`), em que a integração contínua executa. +As ferramentas vêm da imagem `ci-asm` (`ghcr.io/insper-riscv/ci-asm`), em que a integração contínua executa. | Alvo | O que executa | | :--- | :--- | diff --git a/Tests b/Tests index 99ef113..9d0fb3e 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit 99ef113d8b1b3621cb01a88105e7de523f6c5b7e +Subproject commit 9d0fb3ec3fab74059356fd7d967796d3700f750c diff --git a/TopLevel b/TopLevel index 909a907..1e8c32c 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit 909a90707ab95e36eaf8394614c27e81ba85be6c +Subproject commit 1e8c32c841ec87e0386b04740a47beb4e08bd2a1 diff --git a/docs/BENCHMARK_SDRAM.md b/docs/BENCHMARK_SDRAM.md index cd3ed7e..f572558 100644 --- a/docs/BENCHMARK_SDRAM.md +++ b/docs/BENCHMARK_SDRAM.md @@ -21,7 +21,7 @@ O modelo de chip da simulação aborta o teste em qualquer violação de timing, ## 2. Ambiente -A compilação e a simulação rodaram dentro da imagem `ghcr.io/insper-riscv/infra-toolchain:latest`, com o GHDL 6.0.0, o GCC RISC-V 16.1.0 com picolibc e o Spike da própria imagem. Nada do host foi usado. +A compilação e a simulação rodaram dentro da imagem `ghcr.io/insper-riscv/ci-asm:latest`, com o GHDL 6.0.0, o GCC RISC-V 16.1.0 com picolibc e o Spike da própria imagem. Nada do host foi usado. Os repositórios foram testados nos commits abaixo, que são as pontas dos pull requests de SDRAM abertos: diff --git a/docs/BENCHMARK_SDRAM_PLACA.md b/docs/BENCHMARK_SDRAM_PLACA.md index b94d2af..c0c3ab1 100644 --- a/docs/BENCHMARK_SDRAM_PLACA.md +++ b/docs/BENCHMARK_SDRAM_PLACA.md @@ -59,7 +59,7 @@ Recursos: 521 ALMs de 18 480 (3 %), 923 registradores, 65 pinos de 224 e nenhum ## 5. Plataforma completa na placa (core e SDRAM) -A plataforma `sdram` do TopLevel (branch `feat/sdram-platform`, commit `4f2601f`) liga o core a 50 MHz à SDRAM, que é a única RAM, com o controlador a 142,857 MHz. A suíte rodou na placa com o `riscv-tools` dentro da imagem publicada `ghcr.io/insper-riscv/infra-toolchain:latest` (Ubuntu 26.04.1, GHDL 6.0.0, GCC RISC-V 16.1.0 com picolibc, uv 0.13.0, Python 3.14.8), sem nenhuma camada adicional. O Quartus 25.1std do host foi montado em modo leitura nessa imagem, com o servidor JTAG do host acessado pela rede do host; a biblioteca `libglib2.0-0t64`, que as ferramentas do Quartus exigem, já faz parte da imagem. O resultado da seção 5.1 vale para essa execução, e uma execução anterior, com uma camada local que só acrescentava essa biblioteca, deu o mesmo resultado. +A plataforma `sdram` do TopLevel (branch `feat/sdram-platform`, commit `4f2601f`) liga o core a 50 MHz à SDRAM, que é a única RAM, com o controlador a 142,857 MHz. A suíte rodou na placa com o `riscv-tools` dentro da imagem publicada `ghcr.io/insper-riscv/ci-asm:latest` (Ubuntu 26.04.1, GHDL 6.0.0, GCC RISC-V 16.1.0 com picolibc, uv 0.13.0, Python 3.14.8), sem nenhuma camada adicional. O Quartus 25.1std do host foi montado em modo leitura nessa imagem, com o servidor JTAG do host acessado pela rede do host; a biblioteca `libglib2.0-0t64`, que as ferramentas do Quartus exigem, já faz parte da imagem. O resultado da seção 5.1 vale para essa execução, e uma execução anterior, com uma camada local que só acrescentava essa biblioteca, deu o mesmo resultado. Passos, cada um dentro do container: diff --git a/scripts/toolchain.sh b/scripts/toolchain.sh index a9443dc..b59e312 100755 --- a/scripts/toolchain.sh +++ b/scripts/toolchain.sh @@ -1,6 +1,5 @@ #!/usr/bin/env bash -# Runs a command inside the infra-toolchain image (GCC with picolibc, Spike, GHDL, -# uv) with this repository mounted at /workspace, as the calling user so the files +# Runs a command inside the ci-asm image (GCC with picolibc, Spike, GHDL, uv) with this repository mounted at /workspace, as the calling user so the files # it writes are not owned by root; its virtualenv lives in the container (/tmp/venv), # so it never clobbers the host's .venv. The working directory carries over: run from # Tests/ and the command runs in /workspace/Tests. @@ -8,7 +7,7 @@ # scripts/toolchain.sh uv run riscv-tools --config tools/riscv_build/config.yaml compile --emit mif set -euo pipefail -IMAGE="${TOOLCHAIN_IMAGE:-ghcr.io/insper-riscv/infra-toolchain:latest}" +IMAGE="${TOOLCHAIN_IMAGE:-ghcr.io/insper-riscv/ci-asm:latest}" ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" REL="$(realpath --relative-to="$ROOT" "$PWD")" From 09f80fe6fc3817153aaaed66181a2f6c63ffad0a Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 15:07:05 -0300 Subject: [PATCH 18/27] Update Common-Components (authors and citation) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- Common-Components | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Common-Components b/Common-Components index 44a5429..3a5f361 160000 --- a/Common-Components +++ b/Common-Components @@ -1 +1 @@ -Subproject commit 44a542922e7e34360ac2337833ec5e0275b8239f +Subproject commit 3a5f361fd8ec7ae69bfa2e195fb27047ecfaa092 From d08b0ecf2831c50569098f23560bbc0b7e957f59 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 15:09:28 -0300 Subject: [PATCH 19/27] Update Core (README) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- Core | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Core b/Core index 05d4fef..68086f6 160000 --- a/Core +++ b/Core @@ -1 +1 @@ -Subproject commit 05d4fef8f1fc4b95779615962ea371cba1a2880a +Subproject commit 68086f63bdc3008d7fe4a68cfe23a7a17ebf2be0 From a14ad4ccbf0ae399ce47c2e7f2104bebfd35e21e Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 16:58:58 -0300 Subject: [PATCH 20/27] Update Tests (misaligned trap test) Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- Tests | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Tests b/Tests index 9d0fb3e..d0dc11c 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit 9d0fb3ec3fab74059356fd7d967796d3700f750c +Subproject commit d0dc11c8b1e7a20a0ffe1169474ce16619acdffa From 81ff3fb7b5d0254ee0379725e98a445b5a4e6581 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 17:20:58 -0300 Subject: [PATCH 21/27] Take the Common-Components sources in src/ and the new tests Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- Certification | 2 +- Common-Components | 2 +- Core | 2 +- Makefile | 2 +- Memory | 2 +- Peripherals | 2 +- Tests | 2 +- TopLevel | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/Certification b/Certification index d1213e7..505fa54 160000 --- a/Certification +++ b/Certification @@ -1 +1 @@ -Subproject commit d1213e762be1b24a9029a4c6f27371d2d7880d1e +Subproject commit 505fa54e4fe5071c0ab64f894c2dd0c07c58c87a diff --git a/Common-Components b/Common-Components index 3a5f361..6012c47 160000 --- a/Common-Components +++ b/Common-Components @@ -1 +1 @@ -Subproject commit 3a5f361fd8ec7ae69bfa2e195fb27047ecfaa092 +Subproject commit 6012c479316ce4cc2426b421eaff33252001c1a1 diff --git a/Core b/Core index 68086f6..5919111 160000 --- a/Core +++ b/Core @@ -1 +1 @@ -Subproject commit 68086f63bdc3008d7fe4a68cfe23a7a17ebf2be0 +Subproject commit 5919111fee961aa8612aa85c834125fb728430e8 diff --git a/Makefile b/Makefile index 3ab29ec..0988187 100644 --- a/Makefile +++ b/Makefile @@ -22,7 +22,7 @@ sync: # --------------------------------------------------------------- # 1) All .vhd/.vhdl of the repositories that hold VHDL. The Quartus IPs (Memory/ips) # and the PLL need Intel libraries and are left out. -CHECK_SRCS := $(shell find TopLevel/platforms/internal-mem/rtl Memory/sim Common-Components Peripherals/GPIO Peripherals/TIMER Peripherals/UART Core/common Core/I Core/M Core/Zicsr Core/Zifencei Core/core -type f \( -name '*.vhd' -o -name '*.vhdl' \) | sort) +CHECK_SRCS := $(shell find TopLevel/platforms/internal-mem/rtl Memory/sim Common-Components/src Peripherals/GPIO Peripherals/TIMER Peripherals/UART Core/common Core/I Core/M Core/Zicsr Core/Zifencei Core/core -type f \( -name '*.vhd' -o -name '*.vhdl' \) | sort) # 2) Dependency order (topological sort, riscv-tools vhdl-sort) ORDERED_SRCS := $(shell uv run --project Tests riscv-tools vhdl-sort $(CHECK_SRCS)) diff --git a/Memory b/Memory index 600a4e4..c52a8e5 160000 --- a/Memory +++ b/Memory @@ -1 +1 @@ -Subproject commit 600a4e41a4fc198207321cd66dd0c1edcf4e4ac5 +Subproject commit c52a8e5a0e6117a49e4b2c8b18131092ffc2f3fc diff --git a/Peripherals b/Peripherals index e3f1c59..fe1d023 160000 --- a/Peripherals +++ b/Peripherals @@ -1 +1 @@ -Subproject commit e3f1c598fa990c1d0f9f6bc22ad3332d9768aedf +Subproject commit fe1d0232f30d043153d8d8e2acc7c60a287d1e9d diff --git a/Tests b/Tests index d0dc11c..40a4385 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit d0dc11c8b1e7a20a0ffe1169474ce16619acdffa +Subproject commit 40a438539067b561b4a5ef41df8f47d8b6004b72 diff --git a/TopLevel b/TopLevel index 1e8c32c..132fdbe 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit 1e8c32c841ec87e0386b04740a47beb4e08bd2a1 +Subproject commit 132fdbe64766c06056372cdf63375a1addfb1273 From c61c064b1a5a7e913ccb4141e2150e156abdd034 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 17:27:10 -0300 Subject: [PATCH 22/27] Point the submodules at the Common-Components tests, authors and CONTRIBUTING updates Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- Common-Components | 2 +- Core | 2 +- Memory | 2 +- Peripherals | 2 +- TopLevel | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Common-Components b/Common-Components index 6012c47..23d0af4 160000 --- a/Common-Components +++ b/Common-Components @@ -1 +1 @@ -Subproject commit 6012c479316ce4cc2426b421eaff33252001c1a1 +Subproject commit 23d0af4d5396af78be67b2483fe522996aa8abee diff --git a/Core b/Core index 5919111..90b489d 160000 --- a/Core +++ b/Core @@ -1 +1 @@ -Subproject commit 5919111fee961aa8612aa85c834125fb728430e8 +Subproject commit 90b489d04355a691894f06e803b02e59cb5ebb7d diff --git a/Memory b/Memory index c52a8e5..6da36ac 160000 --- a/Memory +++ b/Memory @@ -1 +1 @@ -Subproject commit c52a8e5a0e6117a49e4b2c8b18131092ffc2f3fc +Subproject commit 6da36ac5c90b583a69c38ee89a84818868d47d05 diff --git a/Peripherals b/Peripherals index fe1d023..70dc44d 160000 --- a/Peripherals +++ b/Peripherals @@ -1 +1 @@ -Subproject commit fe1d0232f30d043153d8d8e2acc7c60a287d1e9d +Subproject commit 70dc44ddf93fc72025327c3ecc23112da3810202 diff --git a/TopLevel b/TopLevel index 132fdbe..a9709d6 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit 132fdbe64766c06056372cdf63375a1addfb1273 +Subproject commit a9709d6762f100766939a73a15194c9031880d68 From c1640951ca96468bd427627cff61f5422c5fbe6f Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 17:30:37 -0300 Subject: [PATCH 23/27] Point Common-Components at the corrected contribution guide Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- Common-Components | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Common-Components b/Common-Components index 23d0af4..0762199 160000 --- a/Common-Components +++ b/Common-Components @@ -1 +1 @@ -Subproject commit 23d0af4d5396af78be67b2483fe522996aa8abee +Subproject commit 0762199a502303c13073cdf85f4d60c36ec478cf From cd05863b03733fb583df915516bfc0704e71e032 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 17:33:21 -0300 Subject: [PATCH 24/27] Point Common-Components at its main Pull request 1 of Common-Components is merged. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- Common-Components | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Common-Components b/Common-Components index 0762199..27c1845 160000 --- a/Common-Components +++ b/Common-Components @@ -1 +1 @@ -Subproject commit 0762199a502303c13073cdf85f4d60c36ec478cf +Subproject commit 27c1845c0beabee4d2026dbc79203997b35a73c4 From 558cf96b728b074440ff911a1b98d4b70be59e3d Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 17:46:39 -0300 Subject: [PATCH 25/27] Point the submodules at the Tools whose tests pass pyright strict Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- Certification | 2 +- Core | 2 +- Memory | 2 +- Peripherals | 2 +- Tests | 2 +- TopLevel | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Certification b/Certification index 505fa54..d4b2f42 160000 --- a/Certification +++ b/Certification @@ -1 +1 @@ -Subproject commit 505fa54e4fe5071c0ab64f894c2dd0c07c58c87a +Subproject commit d4b2f425535c684db16bb25198a32cea3990f76b diff --git a/Core b/Core index 90b489d..743d137 160000 --- a/Core +++ b/Core @@ -1 +1 @@ -Subproject commit 90b489d04355a691894f06e803b02e59cb5ebb7d +Subproject commit 743d1370e178788583322dcb84861d85ff547c2d diff --git a/Memory b/Memory index 6da36ac..a84064e 160000 --- a/Memory +++ b/Memory @@ -1 +1 @@ -Subproject commit 6da36ac5c90b583a69c38ee89a84818868d47d05 +Subproject commit a84064edca65141e2ce1105c84389d528e7782f2 diff --git a/Peripherals b/Peripherals index 70dc44d..96c1a32 160000 --- a/Peripherals +++ b/Peripherals @@ -1 +1 @@ -Subproject commit 70dc44ddf93fc72025327c3ecc23112da3810202 +Subproject commit 96c1a32f6e927e032c6ad97b0522bcd238acb8f6 diff --git a/Tests b/Tests index 40a4385..1b63c57 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit 40a438539067b561b4a5ef41df8f47d8b6004b72 +Subproject commit 1b63c57e2170619e4b2b7fab5c9e64c8e99f4a9d diff --git a/TopLevel b/TopLevel index a9709d6..e7d729d 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit a9709d6762f100766939a73a15194c9031880d68 +Subproject commit e7d729dd1272166cf879b010059bbf3ad11e406b From e72ce322d530c017afc8c76287ce4f9bab6ff6f3 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 18:13:48 -0300 Subject: [PATCH 26/27] Follow the Infra rename: ci-asm is now ci-elf and ci-elf is now ci-act4 Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- .github/workflows/sim.yml | 4 ++-- README.en.md | 2 +- README.md | 2 +- docs/BENCHMARK_SDRAM.md | 2 +- docs/BENCHMARK_SDRAM_PLACA.md | 2 +- scripts/toolchain.sh | 4 ++-- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/sim.yml b/.github/workflows/sim.yml index b8932b4..0157fb8 100644 --- a/.github/workflows/sim.yml +++ b/.github/workflows/sim.yml @@ -13,10 +13,10 @@ concurrency: jobs: cocotb-ghdl: runs-on: ubuntu-26.04 - # the ci-asm image of insper-riscv/Infra: GHDL, the RISC-V GCC with picolibc, + # the ci-elf image of insper-riscv/Infra: GHDL, the RISC-V GCC with picolibc, # Spike and uv already on PATH. container: - image: ghcr.io/insper-riscv/ci-asm:latest + image: ghcr.io/insper-riscv/ci-elf:latest defaults: run: working-directory: Tests diff --git a/README.en.md b/README.en.md index 370764c..942b590 100644 --- a/README.en.md +++ b/README.en.md @@ -38,7 +38,7 @@ cd RV32 make all # paths, VHDL check, every repository's own checks, and the 89-program suite ``` -The tools come from the `ci-asm` image (`ghcr.io/insper-riscv/ci-asm`), in which continuous integration runs. +The tools come from the `ci-elf` image (`ghcr.io/insper-riscv/ci-elf`), in which continuous integration runs. | Target | What it runs | | :--- | :--- | diff --git a/README.md b/README.md index 2633e12..60b957f 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ cd RV32 make all # paths, verificação VHDL, verificações de cada repositório e a suíte de 89 programas ``` -As ferramentas vêm da imagem `ci-asm` (`ghcr.io/insper-riscv/ci-asm`), em que a integração contínua executa. +As ferramentas vêm da imagem `ci-elf` (`ghcr.io/insper-riscv/ci-elf`), em que a integração contínua executa. | Alvo | O que executa | | :--- | :--- | diff --git a/docs/BENCHMARK_SDRAM.md b/docs/BENCHMARK_SDRAM.md index f572558..085f4c9 100644 --- a/docs/BENCHMARK_SDRAM.md +++ b/docs/BENCHMARK_SDRAM.md @@ -21,7 +21,7 @@ O modelo de chip da simulação aborta o teste em qualquer violação de timing, ## 2. Ambiente -A compilação e a simulação rodaram dentro da imagem `ghcr.io/insper-riscv/ci-asm:latest`, com o GHDL 6.0.0, o GCC RISC-V 16.1.0 com picolibc e o Spike da própria imagem. Nada do host foi usado. +A compilação e a simulação rodaram dentro da imagem `ghcr.io/insper-riscv/ci-elf:latest`, com o GHDL 6.0.0, o GCC RISC-V 16.1.0 com picolibc e o Spike da própria imagem. Nada do host foi usado. Os repositórios foram testados nos commits abaixo, que são as pontas dos pull requests de SDRAM abertos: diff --git a/docs/BENCHMARK_SDRAM_PLACA.md b/docs/BENCHMARK_SDRAM_PLACA.md index c0c3ab1..e99ed55 100644 --- a/docs/BENCHMARK_SDRAM_PLACA.md +++ b/docs/BENCHMARK_SDRAM_PLACA.md @@ -59,7 +59,7 @@ Recursos: 521 ALMs de 18 480 (3 %), 923 registradores, 65 pinos de 224 e nenhum ## 5. Plataforma completa na placa (core e SDRAM) -A plataforma `sdram` do TopLevel (branch `feat/sdram-platform`, commit `4f2601f`) liga o core a 50 MHz à SDRAM, que é a única RAM, com o controlador a 142,857 MHz. A suíte rodou na placa com o `riscv-tools` dentro da imagem publicada `ghcr.io/insper-riscv/ci-asm:latest` (Ubuntu 26.04.1, GHDL 6.0.0, GCC RISC-V 16.1.0 com picolibc, uv 0.13.0, Python 3.14.8), sem nenhuma camada adicional. O Quartus 25.1std do host foi montado em modo leitura nessa imagem, com o servidor JTAG do host acessado pela rede do host; a biblioteca `libglib2.0-0t64`, que as ferramentas do Quartus exigem, já faz parte da imagem. O resultado da seção 5.1 vale para essa execução, e uma execução anterior, com uma camada local que só acrescentava essa biblioteca, deu o mesmo resultado. +A plataforma `sdram` do TopLevel (branch `feat/sdram-platform`, commit `4f2601f`) liga o core a 50 MHz à SDRAM, que é a única RAM, com o controlador a 142,857 MHz. A suíte rodou na placa com o `riscv-tools` dentro da imagem publicada `ghcr.io/insper-riscv/ci-elf:latest` (Ubuntu 26.04.1, GHDL 6.0.0, GCC RISC-V 16.1.0 com picolibc, uv 0.13.0, Python 3.14.8), sem nenhuma camada adicional. O Quartus 25.1std do host foi montado em modo leitura nessa imagem, com o servidor JTAG do host acessado pela rede do host; a biblioteca `libglib2.0-0t64`, que as ferramentas do Quartus exigem, já faz parte da imagem. O resultado da seção 5.1 vale para essa execução, e uma execução anterior, com uma camada local que só acrescentava essa biblioteca, deu o mesmo resultado. Passos, cada um dentro do container: diff --git a/scripts/toolchain.sh b/scripts/toolchain.sh index b59e312..33fc4cb 100755 --- a/scripts/toolchain.sh +++ b/scripts/toolchain.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Runs a command inside the ci-asm image (GCC with picolibc, Spike, GHDL, uv) with this repository mounted at /workspace, as the calling user so the files +# Runs a command inside the ci-elf image (GCC with picolibc, Spike, GHDL, uv) with this repository mounted at /workspace, as the calling user so the files # it writes are not owned by root; its virtualenv lives in the container (/tmp/venv), # so it never clobbers the host's .venv. The working directory carries over: run from # Tests/ and the command runs in /workspace/Tests. @@ -7,7 +7,7 @@ # scripts/toolchain.sh uv run riscv-tools --config tools/riscv_build/config.yaml compile --emit mif set -euo pipefail -IMAGE="${TOOLCHAIN_IMAGE:-ghcr.io/insper-riscv/ci-asm:latest}" +IMAGE="${TOOLCHAIN_IMAGE:-ghcr.io/insper-riscv/ci-elf:latest}" ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" REL="$(realpath --relative-to="$ROOT" "$PWD")" From f626a691dd94ff7067901e62b7e778900e382026 Mon Sep 17 00:00:00 2001 From: Lucas Hix Date: Tue, 27 Oct 2026 18:19:41 -0300 Subject: [PATCH 27/27] Point the submodules at the Infra rename Infra at the branch that renames ci-asm to ci-elf and ci-elf to ci-act4, and the modules that name those images. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Yb7Y6Pa4P79YEybMvTwrXe --- Certification | 2 +- Infra | 2 +- Tests | 2 +- TopLevel | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Certification b/Certification index d4b2f42..34b42eb 160000 --- a/Certification +++ b/Certification @@ -1 +1 @@ -Subproject commit d4b2f425535c684db16bb25198a32cea3990f76b +Subproject commit 34b42eba0411d75ee000f4f878e9c75c2aca7063 diff --git a/Infra b/Infra index ed5ee83..975ce40 160000 --- a/Infra +++ b/Infra @@ -1 +1 @@ -Subproject commit ed5ee8392ffea937bdc10137a7dad6d1bf67cb53 +Subproject commit 975ce404ccfddbef7857b889e2e9dacc976b329e diff --git a/Tests b/Tests index 1b63c57..3a0e38f 160000 --- a/Tests +++ b/Tests @@ -1 +1 @@ -Subproject commit 1b63c57e2170619e4b2b7fab5c9e64c8e99f4a9d +Subproject commit 3a0e38f08890b26d965fd19174e6def1dc7d1628 diff --git a/TopLevel b/TopLevel index e7d729d..6d6c5bd 160000 --- a/TopLevel +++ b/TopLevel @@ -1 +1 @@ -Subproject commit e7d729dd1272166cf879b010059bbf3ad11e406b +Subproject commit 6d6c5bd06cd8f63d51a1f2fcbcf467e0bb3f3f3a