Skip to content
insper-riscvPublic

About

Núcleo RISC-V RV32 em VHDL-2008 com um pipeline de 5 estágios e extensões configuráveis.

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Core

🌐 Português · English

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.

1. Documentação

  • 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, prefixos i_/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, Zicsr e Zifencei.
  • 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 em tests/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 formal do CI.
  • ISA/E/description.md: a constante IS_E que escolhe o banco de 32 registradores (RV32I) ou de 16 (RV32E), a instrução ilegal com x16 a x31 e a ABI ilp32e.
  • 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, time e instret (Zicntr), com o que o manual exige, o bloco contador de 64 bits, a retirada de instruções, o divisor de tick e o mcountinhibit.
  • 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, mcause e mtval um ciclo depois do trap e a leitura do Zihpm em dois estágios.
  • ISA/M/instructions.md: instruções da extensão M conforme 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.eqz e czero.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.n e mop.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.s1 e ntl.all), codificação das dicas e execução como nop.
  • ISA/Zihintpause/instructions.md e ISA/Zihintpause/description.md: extensão Zihintpause (pause), codificação da dica e execução como nop.
  • 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.

2. Estrutura do Repositório

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)

3. Perfis da ISA

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_pkg

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

4. Verificação e Execução

4.1. Execução local

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)

4.2. Execução via Docker

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.

About

Núcleo RISC-V RV32 em VHDL-2008 com um pipeline de 5 estágios e extensões configuráveis.

Resources

Contributing

Stars

2 stars

Watchers

0 watching

Forks

Contributors

Languages