{"id":13408518,"url":"https://github.com/YosysHQ/picorv32","last_synced_at":"2025-03-14T13:31:29.714Z","repository":{"id":33333574,"uuid":"36978369","full_name":"YosysHQ/picorv32","owner":"YosysHQ","description":"PicoRV32 - A Size-Optimized RISC-V CPU","archived":false,"fork":false,"pushed_at":"2024-06-27T08:36:08.000Z","size":913,"stargazers_count":2983,"open_issues_count":69,"forks_count":742,"subscribers_count":166,"default_branch":"main","last_synced_at":"2024-08-05T18:22:26.426Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Verilog","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YosysHQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-06T11:52:27.000Z","updated_at":"2024-08-05T18:22:36.491Z","dependencies_parsed_at":"2023-02-16T08:35:18.154Z","dependency_job_id":"1a718058-6d25-49a4-a26d-71a3301bb9ff","html_url":"https://github.com/YosysHQ/picorv32","commit_stats":null,"previous_names":["cliffordwolf/picorv32"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YosysHQ%2Fpicorv32","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YosysHQ%2Fpicorv32/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YosysHQ%2Fpicorv32/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YosysHQ%2Fpicorv32/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YosysHQ","download_url":"https://codeload.github.com/YosysHQ/picorv32/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243584287,"owners_count":20314725,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T20:00:53.396Z","updated_at":"2025-03-14T13:31:29.217Z","avatar_url":"https://github.com/YosysHQ.png","language":"Verilog","funding_links":[],"categories":["Projects and IPs","CPU cores","Verilog","CPUs","CPU RISC-V","Open Source Core Implementations"],"sub_categories":["Information Technology","网络服务_其他"],"readme":"[![.github/workflows/ci.yml](https://github.com/YosysHQ/picorv32/actions/workflows/ci.yml/badge.svg)](https://github.com/YosysHQ/picorv32/actions/workflows/ci.yml)\n\nPicoRV32 - A Size-Optimized RISC-V CPU\n======================================\n\nPicoRV32 is a CPU core that implements the [RISC-V RV32IMC Instruction Set](http://riscv.org/).\nIt can be configured as RV32E, RV32I, RV32IC, RV32IM, or RV32IMC core, and optionally\ncontains a built-in interrupt controller.\n\nTools (gcc, binutils, etc..) can be obtained via the [RISC-V Website](https://riscv.org/software-status/).\nThe examples bundled with PicoRV32 expect various RV32 toolchains to be installed in `/opt/riscv32i[m][c]`. See\nthe [build instructions below](#building-a-pure-rv32i-toolchain) for details.\nMany Linux distributions now include the tools for RISC-V (for example\nUbuntu 20.04 has `gcc-riscv64-unknown-elf`). To compile using those set\n`TOOLCHAIN_PREFIX` accordingly (eg. `make TOOLCHAIN_PREFIX=riscv64-unknown-elf-`).\n\nPicoRV32 is free and open hardware licensed under the [ISC license](http://en.wikipedia.org/wiki/ISC_license)\n(a license that is similar in terms to the MIT license or the 2-clause BSD license).\n\n#### Table of Contents\n\n- [Features and Typical Applications](#features-and-typical-applications)\n- [Files in this Repository](#files-in-this-repository)\n- [Verilog Module Parameters](#verilog-module-parameters)\n- [Cycles per Instruction Performance](#cycles-per-instruction-performance)\n- [PicoRV32 Native Memory Interface](#picorv32-native-memory-interface)\n- [Pico Co-Processor Interface (PCPI)](#pico-co-processor-interface-pcpi)\n- [Custom Instructions for IRQ Handling](#custom-instructions-for-irq-handling)\n- [Building a pure RV32I Toolchain](#building-a-pure-rv32i-toolchain)\n- [Linking binaries with newlib for PicoRV32](#linking-binaries-with-newlib-for-picorv32)\n- [Evaluation: Timing and Utilization on Xilinx 7-Series FPGAs](#evaluation-timing-and-utilization-on-xilinx-7-series-fpgas)\n\n\nFeatures and Typical Applications\n---------------------------------\n\n- Small (750-2000 LUTs in 7-Series Xilinx Architecture)\n- High f\u003csub\u003emax\u003c/sub\u003e (250-450 MHz on 7-Series Xilinx FPGAs)\n- Selectable native memory interface or AXI4-Lite master\n- Optional IRQ support (using a simple custom ISA)\n- Optional Co-Processor Interface\n\nThis CPU is meant to be used as auxiliary processor in FPGA designs and ASICs. Due\nto its high f\u003csub\u003emax\u003c/sub\u003e it can be integrated in most existing designs without crossing\nclock domains. When operated on a lower frequency, it will have a lot of timing\nslack and thus can be added to a design without compromising timing closure.\n\nFor even smaller size it is possible disable support for registers `x16`..`x31` as\nwell as `RDCYCLE[H]`, `RDTIME[H]`, and `RDINSTRET[H]` instructions, turning the\nprocessor into an RV32E core.\n\nFurthermore it is possible to choose between a dual-port and a single-port\nregister file implementation. The former provides better performance while\nthe latter results in a smaller core.\n\n*Note: In architectures that implement the register file in dedicated memory\nresources, such as many FPGAs, disabling the 16 upper registers and/or\ndisabling the dual-port register file may not further reduce the core size.*\n\nThe core exists in three variations: `picorv32`, `picorv32_axi` and `picorv32_wb`.\nThe first provides a simple native memory interface, that is easy to use in simple\nenvironments. `picorv32_axi` provides an AXI-4 Lite Master interface that can\neasily be integrated with existing systems that are already using the AXI\nstandard. `picorv32_wb` provides a Wishbone master interface.\n\nA separate core `picorv32_axi_adapter` is provided to bridge between the native\nmemory interface and AXI4. This core can be used to create custom cores that\ninclude one or more PicoRV32 cores together with local RAM, ROM, and\nmemory-mapped peripherals, communicating with each other using the native\ninterface, and communicating with the outside world via AXI4.\n\nThe optional IRQ feature can be used to react to events from the outside, implement\nfault handlers, or catch instructions from a larger ISA and emulate them in\nsoftware.\n\nThe optional Pico Co-Processor Interface (PCPI) can be used to implement\nnon-branching instructions in an external coprocessor. Implementations\nof PCPI cores that implement the M Standard Extension instructions\n`MUL[H[SU|U]]` and `DIV[U]/REM[U]` are included in this package.\n\n\nFiles in this Repository\n------------------------\n\n#### README.md\n\nYou are reading it right now.\n\n#### picorv32.v\n\nThis Verilog file contains the following Verilog modules:\n\n| Module                   | Description                                                           |\n| ------------------------ | --------------------------------------------------------------------- |\n| `picorv32`               | The PicoRV32 CPU                                                      |\n| `picorv32_axi`           | The version of the CPU with AXI4-Lite interface                       |\n| `picorv32_axi_adapter`   | Adapter from PicoRV32 Memory Interface to AXI4-Lite                   |\n| `picorv32_wb`            | The version of the CPU with Wishbone Master interface                 |\n| `picorv32_pcpi_mul`      | A PCPI core that implements the `MUL[H[SU\\|U]]` instructions          |\n| `picorv32_pcpi_fast_mul` | A version of `picorv32_pcpi_fast_mul` using a single cycle multiplier |\n| `picorv32_pcpi_div`      | A PCPI core that implements the `DIV[U]/REM[U]` instructions          |\n\nSimply copy this file into your project.\n\n#### Makefile and testbenches\n\nA basic test environment. Run `make test` to run the standard test bench (`testbench.v`)\nin the standard configurations. There are other test benches and configurations. See\nthe `test_*` make target in the Makefile for details.\n\nRun `make test_ez` to run `testbench_ez.v`, a very simple test bench that does\nnot require an external firmware .hex file. This can be useful in environments\nwhere the RISC-V compiler toolchain is not available.\n\n*Note: The test bench is using Icarus Verilog. However, Icarus Verilog 0.9.7\n(the latest release at the time of writing) has a few bugs that prevent the\ntest bench from running. Upgrade to the latest github master of Icarus Verilog\nto run the test bench.*\n\n#### firmware/\n\nA simple test firmware. This runs the basic tests from `tests/`, some C code, tests IRQ\nhandling and the multiply PCPI core.\n\nAll the code in `firmware/` is in the public domain. Simply copy whatever you can use.\n\n#### tests/\n\nSimple instruction-level tests from [riscv-tests](https://github.com/riscv/riscv-tests).\n\n#### dhrystone/\n\nAnother simple test firmware that runs the Dhrystone benchmark.\n\n#### picosoc/\n\nA simple example SoC using PicoRV32 that can execute code directly from a\nmemory mapped SPI flash.\n\n#### scripts/\n\nVarious scripts and examples for different (synthesis) tools and hardware architectures.\n\n\nVerilog Module Parameters\n-------------------------\n\nThe following Verilog module parameters can be used to configure the PicoRV32\ncore.\n\n#### ENABLE_COUNTERS (default = 1)\n\nThis parameter enables support for the `RDCYCLE[H]`, `RDTIME[H]`, and\n`RDINSTRET[H]` instructions. This instructions will cause a hardware\ntrap (like any other unsupported instruction) if `ENABLE_COUNTERS` is set to zero.\n\n*Note: Strictly speaking the `RDCYCLE[H]`, `RDTIME[H]`, and `RDINSTRET[H]`\ninstructions are not optional for an RV32I core. But chances are they are not\ngoing to be missed after the application code has been debugged and profiled.\nThis instructions are optional for an RV32E core.*\n\n#### ENABLE_COUNTERS64 (default = 1)\n\nThis parameter enables support for the `RDCYCLEH`, `RDTIMEH`, and `RDINSTRETH`\ninstructions. If this parameter is set to 0, and `ENABLE_COUNTERS` is set to 1,\nthen only the `RDCYCLE`, `RDTIME`, and `RDINSTRET` instructions are available.\n\n#### ENABLE_REGS_16_31 (default = 1)\n\nThis parameter enables support for registers the `x16`..`x31`. The RV32E ISA\nexcludes this registers. However, the RV32E ISA spec requires a hardware trap\nfor when code tries to access this registers. This is not implemented in PicoRV32.\n\n#### ENABLE_REGS_DUALPORT (default = 1)\n\nThe register file can be implemented with two or one read ports. A dual ported\nregister file improves performance a bit, but can also increase the size of\nthe core.\n\n#### LATCHED_MEM_RDATA (default = 0)\n\nSet this to 1 if the `mem_rdata` is kept stable by the external circuit after a\ntransaction. In the default configuration the PicoRV32 core only expects the\n`mem_rdata` input to be valid in the cycle with `mem_valid \u0026\u0026 mem_ready` and\nlatches the value internally.\n\nThis parameter is only available for the `picorv32` core. In the\n`picorv32_axi` and `picorv32_wb` core this is implicitly set to 0.\n\n#### TWO_STAGE_SHIFT (default = 1)\n\nBy default shift operations are performed in two stages: first shifts in units\nof 4 bits and then shifts in units of 1 bit. This speeds up shift operations,\nbut adds additional hardware. Set this parameter to 0 to disable the two-stage\nshift to further reduce the size of the core.\n\n#### BARREL_SHIFTER (default = 0)\n\nBy default shift operations are performed by successively shifting by a\nsmall amount (see `TWO_STAGE_SHIFT` above). With this option set, a barrel\nshifter is used instead.\n\n#### TWO_CYCLE_COMPARE (default = 0)\n\nThis relaxes the longest data path a bit by adding an additional FF stage\nat the cost of adding an additional clock cycle delay to the conditional\nbranch instructions.\n\n*Note: Enabling this parameter will be most effective when retiming (aka\n\"register balancing\") is enabled in the synthesis flow.*\n\n#### TWO_CYCLE_ALU (default = 0)\n\nThis adds an additional FF stage in the ALU data path, improving timing\nat the cost of an additional clock cycle for all instructions that use\nthe ALU.\n\n*Note: Enabling this parameter will be most effective when retiming (aka\n\"register balancing\") is enabled in the synthesis flow.*\n\n#### COMPRESSED_ISA (default = 0)\n\nThis enables support for the RISC-V Compressed Instruction Set.\n\n#### CATCH_MISALIGN (default = 1)\n\nSet this to 0 to disable the circuitry for catching misaligned memory\naccesses.\n\n#### CATCH_ILLINSN (default = 1)\n\nSet this to 0 to disable the circuitry for catching illegal instructions.\n\nThe core will still trap on `EBREAK` instructions with this option\nset to 0. With IRQs enabled, an `EBREAK` normally triggers an IRQ 1. With\nthis option set to 0, an `EBREAK` will trap the processor without\ntriggering an interrupt.\n\n#### ENABLE_PCPI (default = 0)\n\nSet this to 1 to enable the _external_ Pico Co-Processor Interface (PCPI).\nThe external interface is not required for the internal PCPI cores, such as\n`picorv32_pcpi_mul`.\n\n#### ENABLE_MUL (default = 0)\n\nThis parameter internally enables PCPI and instantiates the `picorv32_pcpi_mul`\ncore that implements the `MUL[H[SU|U]]` instructions. The external PCPI\ninterface only becomes functional when ENABLE_PCPI is set as well.\n\n#### ENABLE_FAST_MUL (default = 0)\n\nThis parameter internally enables PCPI and instantiates the `picorv32_pcpi_fast_mul`\ncore that implements the `MUL[H[SU|U]]` instructions. The external PCPI\ninterface only becomes functional when ENABLE_PCPI is set as well.\n\nIf both ENABLE_MUL and ENABLE_FAST_MUL are set then the ENABLE_MUL setting\nwill be ignored and the fast multiplier core will be instantiated.\n\n#### ENABLE_DIV (default = 0)\n\nThis parameter internally enables PCPI and instantiates the `picorv32_pcpi_div`\ncore that implements the `DIV[U]/REM[U]` instructions. The external PCPI\ninterface only becomes functional when ENABLE_PCPI is set as well.\n\n#### ENABLE_IRQ (default = 0)\n\nSet this to 1 to enable IRQs. (see \"Custom Instructions for IRQ Handling\" below\nfor a discussion of IRQs)\n\n#### ENABLE_IRQ_QREGS (default = 1)\n\nSet this to 0 to disable support for the `getq` and `setq` instructions. Without\nthe q-registers, the irq return address will be stored in x3 (gp) and the IRQ\nbitmask in x4 (tp), the global pointer and thread pointer registers according\nto the RISC-V ABI.  Code generated from ordinary C code will not interact with\nthose registers.\n\nSupport for q-registers is always disabled when ENABLE_IRQ is set to 0.\n\n#### ENABLE_IRQ_TIMER (default = 1)\n\nSet this to 0 to disable support for the `timer` instruction.\n\nSupport for the timer is always disabled when ENABLE_IRQ is set to 0.\n\n#### ENABLE_TRACE (default = 0)\n\nProduce an execution trace using the `trace_valid` and `trace_data` output ports.\nFor a demonstration of this feature run `make test_vcd` to create a trace file\nand then run `python3 showtrace.py testbench.trace firmware/firmware.elf` to decode\nit.\n\n#### REGS_INIT_ZERO (default = 0)\n\nSet this to 1 to initialize all registers to zero (using a Verilog `initial` block).\nThis can be useful for simulation or formal verification.\n\n#### MASKED_IRQ (default = 32'h 0000_0000)\n\nA 1 bit in this bitmask corresponds to a permanently disabled IRQ.\n\n#### LATCHED_IRQ (default = 32'h ffff_ffff)\n\nA 1 bit in this bitmask indicates that the corresponding IRQ is \"latched\", i.e.\nwhen the IRQ line is high for only one cycle, the interrupt will be marked as\npending and stay pending until the interrupt handler is called (aka \"pulse\ninterrupts\" or \"edge-triggered interrupts\").\n\nSet a bit in this bitmask to 0 to convert an interrupt line to operate\nas \"level sensitive\" interrupt.\n\n#### PROGADDR_RESET (default = 32'h 0000_0000)\n\nThe start address of the program.\n\n#### PROGADDR_IRQ (default = 32'h 0000_0010)\n\nThe start address of the interrupt handler.\n\n#### STACKADDR (default = 32'h ffff_ffff)\n\nWhen this parameter has a value different from 0xffffffff, then register `x2` (the\nstack pointer) is initialized to this value on reset. (All other registers remain\nuninitialized.) Note that the RISC-V calling convention requires the stack pointer\nto be aligned on 16 bytes boundaries (4 bytes for the RV32I soft float calling\nconvention).\n\n\nCycles per Instruction Performance\n----------------------------------\n\n*A short reminder: This core is optimized for size and f\u003csub\u003emax\u003c/sub\u003e, not performance.*\n\nUnless stated otherwise, the following numbers apply to a PicoRV32 with\nENABLE_REGS_DUALPORT active and connected to a memory that can accommodate\nrequests within one clock cycle.\n\nThe average Cycles per Instruction (CPI) is approximately 4, depending on the mix of\ninstructions in the code. The CPI numbers for the individual instructions can\nbe found in the table below. The column \"CPI (SP)\" contains the CPI numbers for\na core built without ENABLE_REGS_DUALPORT.\n\n| Instruction          |  CPI | CPI (SP) |\n| ---------------------| ----:| --------:|\n| direct jump (jal)    |    3 |        3 |\n| ALU reg + immediate  |    3 |        3 |\n| ALU reg + reg        |    3 |        4 |\n| branch (not taken)   |    3 |        4 |\n| memory load          |    5 |        5 |\n| memory store         |    5 |        6 |\n| branch (taken)       |    5 |        6 |\n| indirect jump (jalr) |    6 |        6 |\n| shift operations     | 4-14 |     4-15 |\n\nWhen `ENABLE_MUL` is activated, then a `MUL` instruction will execute\nin 40 cycles and a `MULH[SU|U]` instruction will execute in 72 cycles.\n\nWhen `ENABLE_DIV` is activated, then a `DIV[U]/REM[U]` instruction will\nexecute in 40 cycles.\n\nWhen `BARREL_SHIFTER` is activated, a shift operation takes as long as\nany other ALU operation.\n\nThe following dhrystone benchmark results are for a core with enabled\n`ENABLE_FAST_MUL`, `ENABLE_DIV`, and `BARREL_SHIFTER` options.\n\nDhrystone benchmark results: 0.516 DMIPS/MHz (908 Dhrystones/Second/MHz)\n\nFor the Dhrystone benchmark the average CPI is 4.100.\n\nWithout using the look-ahead memory interface (usually required for max\nclock speed), this results drop to 0.305 DMIPS/MHz and 5.232 CPI.\n\n\nPicoRV32 Native Memory Interface\n--------------------------------\n\nThe native memory interface of PicoRV32 is a simple valid-ready interface\nthat can run one memory transfer at a time:\n\n    output        mem_valid\n    output        mem_instr\n    input         mem_ready\n\n    output [31:0] mem_addr\n    output [31:0] mem_wdata\n    output [ 3:0] mem_wstrb\n    input  [31:0] mem_rdata\n\nThe core initiates a memory transfer by asserting `mem_valid`. The valid\nsignal stays high until the peer asserts `mem_ready`. All core outputs\nare stable over the `mem_valid` period. If the memory transfer is an\ninstruction fetch, the core asserts `mem_instr`.\n\n#### Read Transfer\n\nIn a read transfer `mem_wstrb` has the value 0 and `mem_wdata` is unused.\n\nThe memory reads the address `mem_addr` and makes the read value available on\n`mem_rdata` in the cycle `mem_ready` is high.\n\nThere is no need for an external wait cycle. The memory read can be implemented\nasynchronously with `mem_ready` going high in the same cycle as `mem_valid`, or\n`mem_ready` being tied to constant 1.\n\n#### Write Transfer\n\nIn a write transfer `mem_wstrb` is not 0 and `mem_rdata` is unused. The memory\nwrite the data at `mem_wdata` to the address `mem_addr` and acknowledges the\ntransfer by asserting `mem_ready`.\n\nThe 4 bits of `mem_wstrb` are write enables for the four bytes in the addressed\nword. Only the 8 values `0000`, `1111`, `1100`, `0011`, `1000`, `0100`, `0010`,\nand `0001` are possible, i.e. no write, write 32 bits, write upper 16 bits,\nwrite lower 16, or write a single byte respectively.\n\nThere is no need for an external wait cycle. The memory can acknowledge the\nwrite immediately  with `mem_ready` going high in the same cycle as\n`mem_valid`, or `mem_ready` being tied to constant 1.\n\n#### Look-Ahead Interface\n\nThe PicoRV32 core also provides a \"Look-Ahead Memory Interface\" that provides\nall information about the next memory transfer one clock cycle earlier than the\nnormal interface.\n\n    output        mem_la_read\n    output        mem_la_write\n    output [31:0] mem_la_addr\n    output [31:0] mem_la_wdata\n    output [ 3:0] mem_la_wstrb\n\nIn the clock cycle before `mem_valid` goes high, this interface will output a\npulse on `mem_la_read` or `mem_la_write` to indicate the start of a read or\nwrite transaction in the next clock cycle.\n\n*Note: The signals `mem_la_read`, `mem_la_write`, and `mem_la_addr` are driven\nby combinatorial circuits within the PicoRV32 core. It might be harder to\nachieve timing closure with the look-ahead interface than with the normal\nmemory interface described above.*\n\n\nPico Co-Processor Interface (PCPI)\n----------------------------------\n\nThe Pico Co-Processor Interface (PCPI) can be used to implement non-branching\ninstructions in external cores:\n\n    output        pcpi_valid\n    output [31:0] pcpi_insn\n    output [31:0] pcpi_rs1\n    output [31:0] pcpi_rs2\n    input         pcpi_wr\n    input  [31:0] pcpi_rd\n    input         pcpi_wait\n    input         pcpi_ready\n\nWhen an unsupported instruction is encountered and the PCPI feature is\nactivated (see ENABLE_PCPI above), then `pcpi_valid` is asserted, the\ninstruction word itself is output on `pcpi_insn`, the `rs1` and `rs2`\nfields are decoded and the values in those registers are output\non `pcpi_rs1` and `pcpi_rs2`.\n\nAn external PCPI core can then decode the instruction, execute it, and assert\n`pcpi_ready` when execution of the instruction is finished. Optionally a\nresult value can be written to `pcpi_rd` and `pcpi_wr` asserted. The\nPicoRV32 core will then decode the `rd` field of the instruction and\nwrite the value from `pcpi_rd` to the respective register.\n\nWhen no external PCPI core acknowledges the instruction within 16 clock\ncycles, then an illegal instruction exception is raised and the respective\ninterrupt handler is called. A PCPI core that needs more than a couple of\ncycles to execute an instruction, should assert `pcpi_wait` as soon as\nthe instruction has been decoded successfully and keep it asserted until\nit asserts `pcpi_ready`. This will prevent the PicoRV32 core from raising\nan illegal instruction exception.\n\n\nCustom Instructions for IRQ Handling\n------------------------------------\n\n*Note: The IRQ handling features in PicoRV32 do not follow the RISC-V\nPrivileged ISA specification. Instead a small set of very simple custom\ninstructions is used to implement IRQ handling with minimal hardware\noverhead.*\n\nThe following custom instructions are only supported when IRQs are enabled\nvia the `ENABLE_IRQ` parameter (see above).\n\nThe PicoRV32 core has a built-in interrupt controller with 32 interrupt inputs. An\ninterrupt can be triggered by asserting the corresponding bit in the `irq`\ninput of the core.\n\nWhen the interrupt handler is started, the `eoi` End Of Interrupt (EOI) signals\nfor the handled interrupts go high. The `eoi` signals go low again when the\ninterrupt handler returns.\n\nThe IRQs 0-2 can be triggered internally by the following built-in interrupt sources:\n\n| IRQ | Interrupt Source                    |\n| ---:| ------------------------------------|\n|   0 | Timer Interrupt                     |\n|   1 | EBREAK/ECALL or Illegal Instruction |\n|   2 | BUS Error (Unalign Memory Access)   |\n\nThis interrupts can also be triggered by external sources, such as co-processors\nconnected via PCPI.\n\nThe core has 4 additional 32-bit registers `q0 .. q3` that are used for IRQ\nhandling. When the IRQ handler is called, the register `q0` contains the return\naddress and `q1` contains a bitmask of all IRQs to be handled. This means one\ncall to the interrupt handler needs to service more than one IRQ when more than\none bit is set in `q1`.\n\nWhen support for compressed instructions is enabled, then the LSB of q0 is set\nwhen the interrupted instruction is a compressed instruction. This can be used if\nthe IRQ handler wants to decode the interrupted instruction.\n\nRegisters `q2` and `q3` are uninitialized and can be used as temporary storage\nwhen saving/restoring register values in the IRQ handler.\n\nAll of the following instructions are encoded under the `custom0` opcode. The f3\nand rs2 fields are ignored in all this instructions.\n\nSee [firmware/custom_ops.S](firmware/custom_ops.S) for GNU assembler macros that\nimplement mnemonics for this instructions.\n\nSee [firmware/start.S](firmware/start.S) for an example implementation of an\ninterrupt handler assembler wrapper, and [firmware/irq.c](firmware/irq.c) for\nthe actual interrupt handler.\n\n#### getq rd, qs\n\nThis instruction copies the value from a q-register to a general-purpose\nregister.\n\n    0000000 ----- 000XX --- XXXXX 0001011\n    f7      rs2   qs    f3  rd    opcode\n\nExample:\n\n    getq x5, q2\n\n#### setq qd, rs\n\nThis instruction copies the value from a general-purpose register to a\nq-register.\n\n    0000001 ----- XXXXX --- 000XX 0001011\n    f7      rs2   rs    f3  qd    opcode\n\nExample:\n\n    setq q2, x5\n\n#### retirq\n\nReturn from interrupt. This instruction copies the value from `q0`\nto the program counter and re-enables interrupts.\n\n    0000010 ----- 00000 --- 00000 0001011\n    f7      rs2   rs    f3  rd    opcode\n\nExample:\n\n    retirq\n\n#### maskirq\n\nThe \"IRQ Mask\" register contains a bitmask of masked (disabled) interrupts.\nThis instruction writes a new value to the irq mask register and reads the old\nvalue.\n\n    0000011 ----- XXXXX --- XXXXX 0001011\n    f7      rs2   rs    f3  rd    opcode\n\nExample:\n\n    maskirq x1, x2\n\nThe processor starts with all interrupts disabled.\n\nAn illegal instruction or bus error while the illegal instruction or bus error\ninterrupt is disabled will cause the processor to halt.\n\n#### waitirq\n\nPause execution until an interrupt becomes pending. The bitmask of pending IRQs\nis written to `rd`.\n\n    0000100 ----- 00000 --- XXXXX 0001011\n    f7      rs2   rs    f3  rd    opcode\n\nExample:\n\n    waitirq x1\n\n#### timer\n\nReset the timer counter to a new value. The counter counts down clock cycles and\ntriggers the timer interrupt when transitioning from 1 to 0. Setting the\ncounter to zero disables the timer. The old value of the counter is written to\n`rd`.\n\n    0000101 ----- XXXXX --- XXXXX 0001011\n    f7      rs2   rs    f3  rd    opcode\n\nExample:\n\n    timer x1, x2\n\n\nBuilding a pure RV32I Toolchain\n-------------------------------\n\nTL;DR: Run the following commands to build the complete toolchain:\n\n    make download-tools\n    make -j$(nproc) build-tools\n\nThe default settings in the [riscv-tools](https://github.com/riscv/riscv-tools) build\nscripts will build a compiler, assembler and linker that can target any RISC-V ISA,\nbut the libraries are built for RV32G and RV64G targets. Follow the instructions\nbelow to build a complete toolchain (including libraries) that target a pure RV32I\nCPU.\n\nThe following commands will build the RISC-V GNU toolchain and libraries for a\npure RV32I target, and install it in `/opt/riscv32i`:\n\n    # Ubuntu packages needed:\n    sudo apt-get install autoconf automake autotools-dev curl libmpc-dev \\\n            libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo \\\n\t    gperf libtool patchutils bc zlib1g-dev git libexpat1-dev\n\n    sudo mkdir /opt/riscv32i\n    sudo chown $USER /opt/riscv32i\n\n    git clone https://github.com/riscv/riscv-gnu-toolchain riscv-gnu-toolchain-rv32i\n    cd riscv-gnu-toolchain-rv32i\n    git checkout 411d134\n    git submodule update --init --recursive\n\n    mkdir build; cd build\n    ../configure --with-arch=rv32i --prefix=/opt/riscv32i\n    make -j$(nproc)\n\nThe commands will all be named using the prefix `riscv32-unknown-elf-`, which\nmakes it easy to install them side-by-side with the regular riscv-tools (those\nare using the name prefix `riscv64-unknown-elf-` by default).\n\nAlternatively you can simply use one of the following make targets from PicoRV32's\nMakefile to build a `RV32I[M][C]` toolchain. You still need to install all\nprerequisites, as described above. Then run any of the following commands in the\nPicoRV32 source directory:\n\n| Command                                  | Install Directory  | ISA       |\n|:---------------------------------------- |:------------------ |:--------  |\n| `make -j$(nproc) build-riscv32i-tools`   | `/opt/riscv32i/`   | `RV32I`   |\n| `make -j$(nproc) build-riscv32ic-tools`  | `/opt/riscv32ic/`  | `RV32IC`  |\n| `make -j$(nproc) build-riscv32im-tools`  | `/opt/riscv32im/`  | `RV32IM`  |\n| `make -j$(nproc) build-riscv32imc-tools` | `/opt/riscv32imc/` | `RV32IMC` |\n\nOr simply run `make -j$(nproc) build-tools` to build and install all four tool chains.\n\nBy default calling any of those make targets will (re-)download the toolchain\nsources. Run `make download-tools` to download the sources to `/var/cache/distfiles/`\nonce in advance.\n\n*Note: These instructions are for git rev 411d134 (2018-02-14) of riscv-gnu-toolchain.*\n\n\nLinking binaries with newlib for PicoRV32\n-----------------------------------------\n\nThe tool chains (see last section for install instructions) come with a version of\nthe newlib C standard library.\n\nUse the linker script [firmware/riscv.ld](firmware/riscv.ld) for linking binaries\nagainst the newlib library. Using this linker script will create a binary that\nhas its entry point at 0x10000. (The default linker script does not have a static\nentry point, thus a proper ELF loader would be needed that can determine the\nentry point at runtime while loading the program.)\n\nNewlib comes with a few syscall stubs. You need to provide your own implementation\nof those syscalls and link your program with this implementation, overwriting the\ndefault stubs from newlib. See `syscalls.c` in [scripts/cxxdemo/](scripts/cxxdemo/)\nfor an example of how to do that.\n\n\nEvaluation: Timing and Utilization on Xilinx 7-Series FPGAs\n-----------------------------------------------------------\n\nThe following evaluations have been performed with Vivado 2017.3.\n\n#### Timing on Xilinx 7-Series FPGAs\n\nThe `picorv32_axi` module with enabled `TWO_CYCLE_ALU` has been placed and\nrouted for Xilinx Artix-7T, Kintex-7T, Virtex-7T, Kintex UltraScale, and Virtex\nUltraScale devices in all speed grades. A binary search is used to find the\nshortest clock period for which the design meets timing.\n\nSee `make table.txt` in [scripts/vivado/](scripts/vivado/).\n\n| Device                    | Device               | Speedgrade | Clock Period (Freq.) |\n|:------------------------- |:---------------------|:----------:| --------------------:|\n| Xilinx Kintex-7T          | xc7k70t-fbg676-2     | -2         |     2.4 ns (416 MHz) |\n| Xilinx Kintex-7T          | xc7k70t-fbg676-3     | -3         |     2.2 ns (454 MHz) |\n| Xilinx Virtex-7T          | xc7v585t-ffg1761-2   | -2         |     2.3 ns (434 MHz) |\n| Xilinx Virtex-7T          | xc7v585t-ffg1761-3   | -3         |     2.2 ns (454 MHz) |\n| Xilinx Kintex UltraScale  | xcku035-fbva676-2-e  | -2         |     2.0 ns (500 MHz) |\n| Xilinx Kintex UltraScale  | xcku035-fbva676-3-e  | -3         |     1.8 ns (555 MHz) |\n| Xilinx Virtex UltraScale  | xcvu065-ffvc1517-2-e | -2         |     2.1 ns (476 MHz) |\n| Xilinx Virtex UltraScale  | xcvu065-ffvc1517-3-e | -3         |     2.0 ns (500 MHz) |\n| Xilinx Kintex UltraScale+ | xcku3p-ffva676-2-e   | -2         |     1.4 ns (714 MHz) |\n| Xilinx Kintex UltraScale+ | xcku3p-ffva676-3-e   | -3         |     1.3 ns (769 MHz) |\n| Xilinx Virtex UltraScale+ | xcvu3p-ffvc1517-2-e  | -2         |     1.5 ns (666 MHz) |\n| Xilinx Virtex UltraScale+ | xcvu3p-ffvc1517-3-e  | -3         |     1.4 ns (714 MHz) |\n\n#### Utilization on Xilinx 7-Series FPGAs\n\nThe following table lists the resource utilization in area-optimized synthesis\nfor the following three cores:\n\n- **PicoRV32 (small):** The `picorv32` module without counter instructions,\n  without two-stage shifts, with externally latched `mem_rdata`, and without\n  catching of misaligned memory accesses and illegal instructions.\n\n- **PicoRV32 (regular):** The `picorv32` module in its default configuration.\n\n- **PicoRV32 (large):** The `picorv32` module with enabled PCPI, IRQ, MUL,\n  DIV, BARREL_SHIFTER, and COMPRESSED_ISA features.\n\nSee `make area` in [scripts/vivado/](scripts/vivado/).\n\n| Core Variant       | Slice LUTs | LUTs as Memory | Slice Registers |\n|:------------------ | ----------:| --------------:| ---------------:|\n| PicoRV32 (small)   |        761 |             48 |             442 |\n| PicoRV32 (regular) |        917 |             48 |             583 |\n| PicoRV32 (large)   |       2019 |             88 |            1085 |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYosysHQ%2Fpicorv32","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYosysHQ%2Fpicorv32","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYosysHQ%2Fpicorv32/lists"}