Memórias do SoC RISC-V RV32: os blocos de memória que o núcleo lê e escreve. O núcleo, os periféricos, os topos que os conectam e os programas de teste ficam em outros repositórios da organização insper-riscv.
- AUTHORS.md: autores com commits no repositório, com nome e conta do GitHub.
- CONTRIBUTING.md: regras obrigatórias de contribuição, norma VHDL-2008, nomenclatura, cabeçalhos, normas Python e verificação antes de abrir Pull Request.
- CITATION.cff: metadados para citação do software.
- contracts/02-barramento-e-memoria.md: protocolo de barramento e de memória compartilhado por todas as famílias.
- contrato-de-memoria.md: contrato de uma memória (pinos, tempo, clock e palavra de largura diferente da do core).
- Documentação por componente, uma por bloco, em português (
docs/pt-br/) e em inglês (docs/en/), agrupada por tipo.docs/pt-br/cache/(caches e roteamento de região): dcache, icache, ifetch_bridge, mem_region_router, flash_arbiter.docs/pt-br/block_ram/(memória em bloco da FPGA): block_ram.docs/pt-br/ram/(SDRAM, RAM externa e RAM interna): sdram_ctrl, sdram_arbiter, sdram_cpu_bridge, sdram_pkg, sdram_model, sdram_bist, sdram_dbg_master, sdram_jtag_core, ram_chip, ram, ram_simulation, onchip_ram_port.docs/pt-br/rom/(FLASH, BOOT_MEMORY e modelo da ROM): flash_chip, flash_cmd_port, boot_memory, flash, flash_loader, flash_jtag_core, flash_simulation, flash_store, rom_simulation, max10_flash, epcs_ctrl, epcs_xip, max10_xip.docs/pt-br/latency/(contagem de latência dos modelos emulados): latency_counter.docs/pt-br/barramento/(pontes AXI4): axi_master_bridge, axi_slave_word_bridge.
- Documentos de projeto (decisões, protocolo, verificação e defeitos corrigidos) em
docs/pt-br/barramento/(dcache_axi, dcache_axi_decisions), emdocs/pt-br/ram/(sdram_debug, sdram_line, sdram_subword_read, sdram_timings, sdram_clock_crossing), emdocs/pt-br/formal/(formal, blocks) e emdocs/pt-br/bugs/(um documento por defeito). Os documentos por componente linkam para eles. O interconector externo e a UART sobre JTAG ficam documentados no Insper-RISC-V e no Peripherals.
| Caminho | Conteúdo |
|---|---|
src/common/ |
Submódulo Common-Components, editado só na origem |
src/cache/SoC/ |
Cache de instruções, ponte de busca de instrução sem cache e cache de dados da SDRAM, roteador por região, árbitro da FLASH, modelo do chip de FLASH e a porta de comandos dele (flash_cmd_port, que apaga, grava e protege), mais o pacote cache_pkg (pertinência a uma região e largura do índice de linha); sim/ guarda os sistemas de teste das caches |
src/RAM/SoC/ |
Controlador da SDRAM da placa (32M x 16, 64 MB), ponte entre o clock do núcleo e o do controlador, árbitro que divide a SDRAM entre o núcleo e o mestre de depuração (docs/pt-br/ram/sdram_debug.md) e um pacote com os tempos do chip. O pacote ram_pkg traduz o endereço de byte no deslocamento dentro da janela do chip. src/RAM/SoC/sim/ guarda o modelo do chip, que reprova a simulação quando o controlador quebra uma regra dele, e os topos que o ligam ao controlador. O onchip_ram_port põe o bloco de RAM interna da FPGA atrás do mesmo contrato de linha da memória externa, para uma RAM interna poder ficar atrás de cache (docs/pt-br/ram/onchip_ram_port.md) |
src/block_ram/altera/ |
block_ram, a única instância do altsyncram da Intel, de uma ou duas portas, só para a placa |
src/sim/SoC/ |
Pacote sim_util_pkg (tempo em ns, padrão de dados e registro de violação) dos modelos de chip e dos sistemas de teste, só para simulação |
src/latency/SoC/ |
Máquina de contagem de latência (latency_counter) que o modelo do chip de FLASH, o modelo da RAM externa e o adaptador da RAM interna compartilham |
src/RAM/FPGA/Cyclone-V/ |
IP Quartus RAM, só para a placa |
src/RAM/FPGA/debug/sdram/ |
Núcleo Virtual JTAG (sdram_jtag_core) e mestre de depuração (sdram_dbg_master) que deixam um hospedeiro ler e escrever a SDRAM pela JTAG, só para a placa |
src/ROM/SoC/ |
Modelo de simulação da ROM em VHDL puro com array que o cocotb consegue ler (rom_simulation), modelo da FLASH de duas portas (flash_simulation), carregador da FLASH pela JTAG (flash_loader, com a porta JTAG flash_jtag_core) o controlador de barramento da flash interna do MAX 10 (max10_flash), o acesso de usuário à flash serial EPCS (epcs_cmd, epcs_spi e o topo epcs_ctrl), os adaptadores de leitura direta dessas duas flashes (epcs_xip e max10_xip) e, em sim/, o topo que os liga (flash_system), os modelos da megafunção do MAX 10 e da EPCS e seus bancos de teste |
src/ROM/Cyclone-V/ |
IPs Quartus da ROM, instâncias da block_ram: BOOT_MEMORY (gravada uma vez), FLASH (a única cópia da FLASH interna, de duas portas, reescrita pelo carregador JTAG a cada teste) e FLASH_STORE, mais a casca Virtual JTAG do carregador (flash_jtag_shell, só para a placa). Também simulam no GHDL pelos modelos altera_mf da Intel |
src/ROM/MAX-10/ |
Invólucro fino do IP de flash on-chip da DE10-Lite (max10_flash_ip) e o script que o gera no Platform Designer (max10_flash_core.tcl); só o Quartus o compila |
src/ROM/Cyclone-IV-E/ |
Invólucro fino do bloco ASMI da Cyclone IV E (epcs_asmi_cyclone_iv_e), que leva os pinos SPI do epcs_ctrl aos pinos de configuração da DE0-Nano e da DE2-115; só o Quartus o compila (o da Cyclone V fica em Cyclone-V/) |
src/barramento/SoC/ |
As duas pontes AXI4 genéricas, que só dependem do contrato de memória do core: o mestre (axi_master_bridge, do core para um escravo AXI4) e o escravo de palavra (axi_slave_word_bridge, AXI4 na frente de uma memória), com o sistema de teste em sim/. O interconector externo, o roteador AXI4 e o banco de periféricos decodificam o mapa da plataforma e conhecem os periféricos, então ficam no Insper-RISC-V, em src/interconnect/ |
src/tests/ |
Autoteste da SDRAM (sdram_bist), que dirige o controlador sozinho em modos rápido, padrões, varredura do chip inteiro e aleatório, e o sistema que o liga ao modelo do chip (sdram_bist_system) |
tests/python/ |
Testes por entidade em cocotb, em unittests/{cache,ram,rom,barramento}, e o catálogo (tests.json) que os conduz |
tests/vhdl/ |
Bancos de teste do controlador da SDRAM (sdram_ctrl_tb) e dos pacotes (cache_pkg_tb, ram_pkg_tb e sim_util_pkg_tb) |
formal/ |
Propriedades em SystemVerilog e scripts das provas, uma pasta por bloco, e o agregador dos engines (documentação) |
docs/pt-br/, docs/en/ |
Um documento por componente, agrupado em cache, ram, rom, sim e barramento, mais contracts, formal e bugs |
Há três famílias que compartilham uma única interface de escravo: modelos de simulação, IPs internos da FPGA e memória externa (RAM fora da FPGA, com controladores de vários ciclos), esta última em src/RAM/SoC/, onde a SDRAM é a primeira. Toda memória interna responde em um ciclo; o sinal ready só integra a interface com a memória externa. Os tempos do chip em src/RAM/SoC/sdram/sdram_pkg.vhd são os da folha de dados do chip, listados em docs/pt-br/ram/sdram_timings.md.
Os tamanhos dos IPs devem coincidir com o mapa de memória da plataforma (src/simulation/internal-mem/platform.yaml do Insper-RISC-V), verificado ali por make memory-map.
git clone --recurse-submodules https://github.com/insper-riscv/Memory.git
cd Memory
uv sync
make check # Verificação de sintaxe VHDL dos modelos e das memórias (GHDL)
make test # Testes por entidade em cocotb (make test TEST=RAM para um alvo)
make paths # Caminhos do paths.yaml e árvore do repositório (riscv-tools check-tree)
make formal # Provas formais (SymbiYosys) com o engine de FORMAL_ENGINE (bitwuzla por padrão)Os IPs de Cyclone-V/ não são analisados no make check, pois exigem a biblioteca altera_mf da Intel, ausente da imagem; a simulação do topo de hardware no Insper-RISC-V os cobre.
A imagem ghcr.io/insper-riscv/ci-vhdl:latest publicada pelo repositório insper-riscv/Infra já traz o GHDL (backend LLVM), Yosys, SymbiYosys, os solvers Yices e Bitwuzla, uv, Python 3.14 e cocotb pré-instalados:
docker run --rm -v "$PWD:/workspace" -w /workspace ghcr.io/insper-riscv/ci-vhdl:latest \
bash -c "uv sync && make check && make test && make paths && make formal"Copyright 2026 Insper. Licenciado sob a Apache License, Version 2.0.