Complete merge of agentic work

.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-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/infra-toolchain:latest
+      image: ghcr.io/insper-riscv/ci-elf:latest
     defaults:
       run:
         working-directory: Tests
@@ -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/uart-errors.
+        run: |
+          uv run riscv-tools --config tools/riscv_build/config.yaml sim \
+            --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

.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

.gitmodules

@@ -1,15 +1,24 @@
 [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
+[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

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).

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).

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

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
+-- ============================================================================
+-- <Título curto do pacote ou entidade>
+-- ============================================================================
+-- <Descrição clara em português da função do módulo, interfaces principais, invariantes de ciclo/latência ou parâmetros.>
+-- ============================================================================
+```
+
+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).