Núcleo do processador RISC-V RV32 em VHDL-2008 organizado com uma pipeline de 5 estágios (IF, ID, EX, MEM e WB), modularizado por extensão da ISA (base I ou E, e as extensões M, Zmmul, Zicsr, Zicntr, Zihpm, Zifencei, Zicclsm, Zicond, Zimop, Zihintntl e Zihintpause) sob a entidade de topo (core), acompanhado de testes unitários por entidade via cocotb/GHDL e de verificação formal via SymbiYosys.
- 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 (
--std=08), convenção de nomenclatura, prefixosi_/o_, cabeçalhos, docstrings e regras de documentação. -
ISA/I/instructions.md: requisitos do manual do RISC-V para a base RV32I (estado do programador, formatos, as 37 instruções com codificação e semântica,
FENCE,ECALL,EBREAK) e o comportamento do Core em cada caso. - ISA/I/description.md: implementação da base RV32I no Core, com estágios, decodificador de controle, ULA, extensores de imediato e de leitura, gerenciador de stores, adiantamento e hazards.
- ISA/I/construcao-incremental.md: formatos das instruções de 32 bits do RISC-V e progressão incremental do caminho de dados para as 37 instruções da base RV32I.
- ISA/I/ULA.md: código de operação, somador-subtrator compartilhado, desvios, deslocadores e seleção do resultado da ULA.
-
ARCHITECTURE.md: microarquitetura do pipeline de 5 estágios, responsabilidades por estágio, caminhos de forwarding, detecção de hazard load-use, stall, flush e suporte às extensões
M,ZicsreZifencei. -
PIPELINE_ARCHITECTURE_GUIDE.md: referência detalhada dos sinais de interconexão entre os estágios, barreiras síncronas (
IF/ID,ID/EX,EX/MEM,MEM/WB), equações de stall e flush e resolução de desvios. -
ISA/I/DECODER.md: tabela de decodificação da unidade de controle base, com os sinais de controle das 37 instruções da base RV32I e o comportamento de qualquer outra instrução como
NOP. -
contracts/01-contrato-de-extensao.md: contrato de diretórios por extensão, manifestos de perfil (
profiles/*.yaml) e ponto único de integração de novas extensões na entidade de topo. - contracts/02-barramento-e-memoria.md: protocolo de barramento de instruções e de dados (mapa de memória por região, endereçamento em byte, habilitação por byte, handshake de espera por memória lenta, resposta de erro da porta externa e cache de instruções).
-
contracts/03-relogios-e-reset.md: contrato K7, os papéis de relógio (
core,fetch,mem,mem_pin,rst), a origem do valor de cada um e a latência do reset. -
contracts/04-contrato-de-boot.md: fragmentos de boot por extensão (
src/<Extensão>/boot.inc), a ordem de inclusão, o estado que cada um deixa e a verificação emtests/boot. - ISA/Zicclsm/instructions.md e ISA/Zicclsm/description.md: o que a especificação de perfis exige da Zicclsm e a execução em hardware dos loads e stores desalinhados, classificação dos acessos, regiões cobertas em cada mapa de memória e o acesso em duas etapas que cruza a palavra.
-
FORMAL.md: provas formais, engines de solver, arquivo de resultado por engine e a regra do agregador que decide o check
formaldo CI. -
ISA/E/description.md: a constante
IS_Eque escolhe o banco de 32 registradores (RV32I) ou de 16 (RV32E), a instrução ilegal comx16ax31e a ABIilp32e. -
ISA/Zicsr/instructions.md e ISA/Zicsr/description.md: extensão Zicsr, com as instruções, a codificação e as regras de leitura e escrita exigidas pelo manual, e a implementação no Core (banco de CSRs, exceções síncronas,
MRET, redirecionamento e comportamento sem Zicsr). -
ISA/Zicntr: contadores básicos
cycle,timeeinstret(Zicntr), com o que o manual exige, o bloco contador de 64 bits, a retirada de instruções, o divisor de tick e omcountinhibit. -
ISA/Zihpm: contadores de desempenho
hpmcounter(Zihpm), com o que o manual exige, a organização dos contadores de eventos, a regra de contagem e a tabela de eventos. - ISA/Zihpm/conformance.md: cada exigência do Zihpm confrontada com o comportamento do Core, com a evidência de cada linha.
-
profile/description.md: os arquivos que definem os perfis, as regras que geram a matriz completa e os perfis de referência de
profiles/. - timing/STALL_REGISTRADO_DO_MULTDIV.md: a parada do multiplicador e do divisor vinda de um flip-flop, e o efeito no caminho crítico.
- timing/P7_FLUSH_SO_NOS_BITS_DE_CONTROLE.md: os registradores de barreira limpam só os bits de controle no descarte.
- timing/P8_ADIANTAMENTO_RESOLVIDO_EM_ID.md: a seleção do adiantamento resolvida em ID, registrada e replicada.
-
timing/P9_SEGUNDO_PATAMAR_DO_PERFIL_COMPLETO.md: o cruzamento de palavra registrado, a escrita de
mepc,mcauseemtvalum ciclo depois do trap e a leitura do Zihpm em dois estágios. -
ISA/M/instructions.md: instruções da extensão
Mconforme o manual do RISC-V (capítulo 11): codificação, divisão, divisão por zero e estouro. -
ISA/M/description.md: como o Core executa a
M: decodificador, divisor não-restaurador, parada do pipeline, fusão de pares e verificação formal. -
ISA/Zmmul/instructions.md: instruções da extensão
Zmmul(só multiplicação, seção 11.1.3 do manual): codificação e semântica. -
ISA/Zmmul/description.md: como o Core executa a
Zmmul: configuração, decodificação sem divisão e multiplicador de Booth. -
ISA/Zicond/instructions.md e ISA/Zicond/description.md: extensão Zicond (
czero.eqzeczero.nez, capítulo 10 do manual), codificação, semântica e a execução no Core. -
ISA/Zifencei/instructions.md e ISA/Zifencei/description.md: extensão Zifencei (
FENCE.I), exigências do manual, regiões que passam pela cache de instruções, execução com e sem cache de dados write-back, efeito no pipeline e nas caches e custo. -
ISA/Zimop/instructions.md e ISA/Zimop/description.md: extensão Zimop (
mop.r.nemop.rr.n), exigências do manual, codificação das 40 instruções, decodificação no estágio ID e verificação. -
ISA/Zihintntl/instructions.md e ISA/Zihintntl/description.md: extensão Zihintntl (
ntl.p1,ntl.pall,ntl.s1entl.all), codificação das dicas e execução comonop. -
ISA/Zihintpause/instructions.md e ISA/Zihintpause/description.md: extensão Zihintpause (
pause), codificação da dica e execução comonop. - MEMORY_WIDTH.md: regras do adaptador entre a palavra de 32 bits do Core e uma memória mais estreita ou mais larga, com endereço, máscara de bytes, leitura, sinal de pronto e interação com o acesso desalinhado.
-
bugs/DIVISOR_SEM_SINAL_ACIMA_DE_2_31.md: análise matemática da faixa do resto parcial na divisão não-restauradora e do uso de 34 bits internos para divisores sem sinal acima de
$2^{31}$ . - bugs/FLUSH_COM_PIPELINE_PARADO.md: análise da interação entre redirecionamento de desvio em EX e parada global do pipeline por espera de memória em MEM.
- bugs/LOAD_EM_WB_DURANTE_STALL.md: análise do load segurado em WB que era sobrescrito pelo load seguinte enquanto a unidade M para o pipeline.
| Caminho | Conteúdo |
|---|---|
src/common/ |
Submódulo Common-Components: os blocos genéricos (somador, flip-flop, registradores, multiplexadores e decodificador one-hot) que o Core importa |
src/shared/ |
Peças do Core usadas por todos os perfis: pacotes de tipos e constantes, registradores de barreira entre estágios, unidade de controle base, banco de registradores, unidades de forwarding e hazard e gerador de PC |
src/I-E/ |
Blocos comuns às bases RV32I e RV32E (a RV32E só reduz o banco a 16 registradores), compostos pela ULA, extensor de imediatos, extensor de leitura de memória e gerenciador de alinhamento de stores |
src/M/ |
Extensão de multiplicação e divisão inteira RV32M, contendo decodificador dedicado, multiplicador sequencial de Booth radix-2, divisor não-restaurador de 34 bits e unidade integradora |
src/Zicsr/ |
Extensão de registradores de controle e estado (CSRs) do modo máquina e unidade de detecção de exceções síncronas e retorno de trap (MRET) |
src/Zihpm/ |
Extensão dos contadores de eventos hpmcounter3 a hpmcounter31, com o banco de contadores e a tabela de eventos do núcleo |
src/Zicntr/ |
Extensão de contadores: mcycle, minstret, time e os espelhos cycle, instret, time, com o contador de 64 bits e o divisor do tempo |
src/Zicclsm/ |
Unidade de acesso desalinhado à memória principal (misaligned_unit), que divide em duas etapas o acesso que cruza a palavra |
src/Zifencei/ |
Extensão de sincronização da memória de instruções (FENCE.I), com suporte opcional a handshake de flush de cache de dados write-back |
src/Zicond/ |
Extensão de condicionais zero (czero.eqz e czero.nez), com decodificador no estágio ID e unidade de execução no estágio EX |
src/Zimop/ |
Extensão de operações possivelmente definidas (mop.r.n e mop.rr.n), que escrevem zero em rd |
src/Zihintntl/ |
Extensão de dicas de localidade não temporal (ntl.p1, ntl.pall, ntl.s1 e ntl.all), que executam como nop |
src/Zihintpause/ |
Extensão da dica pause, que executa como nop |
src/core/ |
Entidades dos 5 estágios do pipeline (stage_if, stage_id, stage_ex, stage_mem, stage_wb) e topo estrutural do processador (core) |
profiles/ |
A especificação dos perfis (matrix.yaml) e os manifestos de fontes dos perfis que provam a compilação sem os diretórios opcionais (rv32i.yaml, rv32i_zmmul.yaml, rv32im.yaml, rv32im_zicsr.yaml, rv32im_zicsr_irq.yaml, rv32im_zicond.yaml, rv32im_zicsr_zifencei.yaml, rv32im_zicclsm_zicntr_zifencei.yaml, rv32im_zicclsm_zicntr_zihpm_zifencei.yaml, rv32im_zicclsm_zicntr_zihpm_zifencei_reduced.yaml) em ordem de dependência |
formal/ |
Propriedades em SystemVerilog (csr_file_props.sv, trap_unit_props.sv), configurações .sby, script de verificação formal via GHDL + Yosys + SymbiYosys e o agregador dos engines (documentação) |
tests/python/ |
Testes unitários por entidade e de integração do topo em cocotb/GHDL (documentação) |
tests/boot/ |
Verificação dos fragmentos de boot: montagem de todas as combinações de macros e execução no Spike (contrato) |
O topo estrutural core lê uma constante booleana por extensão do config_pkg (Common-Components), que habilita ou desabilita a extensão em tempo de elaboração. O topo de uma plataforma compila o config_pkg gerado do platform.yaml no lugar do pacote padrão (RV32IM com Zicclsm), e os testes e as provas formais trocam o arquivo por uma variante de formal/configs.yaml:
| Extensão | Constante | Padrão | Com a constante falsa |
|---|---|---|---|
| M | HAS_M |
true |
As instruções M são ilegais (causa 2 com Zicsr, o_trap sem Zicsr) |
| Zmmul | HAS_ZMMUL |
false |
As instruções de multiplicação são ilegais (causa 2 com Zicsr, o_trap sem Zicsr) |
| Zicsr | HAS_ZICSR |
false |
Sem CSRs nem traps; o core sinaliza a exceção em o_trap |
| Zicntr | HAS_ZICNTR |
false |
Sem os contadores cycle, time e instret; exige Zicsr |
| Zihpm | HAS_ZIHPM |
false |
Sem os contadores de eventos hpmcounter3 a hpmcounter31; exige Zicsr, e hpm_counters e hpm_width dimensionam o banco |
| Zifencei | HAS_ZIFENCEI |
false |
FENCE.I é ilegal (causa 2 com Zicsr, o_trap sem Zicsr) |
| Zimop | HAS_ZIMOP |
false |
As 40 codificações de mop.r.n e mop.rr.n são ilegais (causa 2 com Zicsr, o_trap sem Zicsr) |
| Zihintntl | HAS_ZIHINTNTL |
false |
As quatro dicas ntl.* seguem como ADD em x0, que também é um nop |
| Zihintpause | HAS_ZIHINTPAUSE |
false |
pause segue como FENCE, que também é um nop |
| Zicclsm | HAS_ZICCLSM |
true |
Todo acesso desalinhado gera trap |
| Zicond | HAS_ZICOND |
false |
czero.eqz e czero.nez são ilegais (causa 2 com Zicsr, o_trap sem Zicsr) |
Um perfil é uma combinação dessas extensões, e duas regras definem as combinações válidas: M e Zmmul nunca coexistem, porque M já inclui a multiplicação do Zmmul, e Zicntr e Zihpm implicam Zicsr, porque os contadores são CSRs. Um core sem Zicsr e sem Zicclsm também é válido: o acesso desalinhado só é sinalizado em o_trap. A base é o RV32I (IS_E falso) ou o RV32E (IS_E verdadeiro, ver ISA/E/description.md), e cada base aceita todas as 240 combinações de extensões, o que dá 480 perfis. A lista de perfis vem de profiles/matrix.yaml, que expande a Zimop e a Zicond como as demais; os perfis de referência rv32im_zicond e rv32im_zimop ligam cada uma sozinha na compilação do GHDL:
riscv-tools profiles --spec profiles/matrix.yaml # um nome por linha
riscv-tools profiles --spec profiles/matrix.yaml --format generics # nome e constantes (-ghas_x=valor, que o Makefile traduz em HAS_X)
make profile-matrix # elabora cada perfil com o seu config_pkgQuando uma extensão está desabilitada pela sua constante, as instruções correspondentes são ilegais: com Zicsr geram a causa 2 do mcause, e sem Zicsr geram um pulso em o_trap, e em qualquer dos dois casos não escrevem registrador nem acessam a memória.
git clone --recurse-submodules https://github.com/insper-riscv/Core.git
cd Core
uv sync
make check # Verificação de sintaxe VHDL de todos os fontes em ordem topológica
make profiles # Compilação e elaboração independente de cada perfil em profiles/*.yaml
make test # Execução da suíte completa de testes cocotb (ou make test TEST=ALU para um alvo)
make paths # Validação de existência de todos os caminhos listados nos manifestos
make formal # Execução das provas formais (SymbiYosys) com o engine de FORMAL_ENGINE (bitwuzla por padrão)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 2.1.0 pré-instalados:
docker run --rm -v "$PWD:/workspace" -w /workspace ghcr.io/insper-riscv/ci-vhdl:latest \
bash -c "uv sync && make check && make profiles && make test && make formal"Copyright 2026 Insper. Licenciado sob a Apache License, Version 2.0.