# mor1kx: a configurable OpenRISC 1000 processor core in Verilog

> mor1kx is an OpenRISC 1000 compliant processor IP core written in Verilog, built around a single central parameter table that lets you choose the pipeline, caches, MMUs, bus interface and debug features at elaboration time. The repository holds the RTL and documentation only, not a verification environment.

**openrisc/mor1kx** — mor1kx - an OpenRISC 1000 processor IP core

- Repository: https://github.com/openrisc/mor1kx
- Stars: 593 · Forks: 157
- Language: Verilog
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/openrisc-mor1kx

## An IP core, and only an IP core

The repository contains an OpenRISC 1000 compliant processor IP core written in Verilog HDL, and it is explicit about its boundaries. It only contains the IP source code and some documentation, and for a verification environment you are pointed at other projects. That matters for expectations, because a CPU core without a testbench, without a software image and without a board is a component rather than a product. The top level of the tree reflects the shape of the deliverable, with `rtl/` holding the design, `mor1kx.core` as the core file for the flow tools, `doc/` for the documentation, `bench/` for the benchmarks, and a `Jenkinsfile` for continuous integration. The project topics are openrisc and verilog, the primary language is Verilog, and the licence is the CERN Open Hardware Licence Version 2, Weakly Reciprocal, with the SPDX identifier CERN-OHL-W-2.0. That is a hardware licence rather than a software one, which is the norm for a core that other people instantiate in silicon.

## One parameter table decides the whole core

The README spends most of its length on configuration, and the organising idea is that the mor1kx CPU is very configurable so you can customise the core to your exact needs. The tables explain how each parameter can be configured, what the configuration does and why you might want to use it, and every table has the same shape: a parameter name, a description, a default, the allowed values, and a Usage field. The note on that last column says it indicates if a certain application, such as running Linux, requires a setting different from the default value. That single column is the most useful thing in the document, because it converts a generic parameter list into a set of decisions you have to make for your software, and it is why the tables are worth reading end to end rather than treating as reference.

## Pipeline, caches and the bus interface

The basic parameters set the shape of the machine. `OPTION_OPERAND_WIDTH` specifies the CPU data and address widths, defaulting to 32 with 32 and 64 among the values. `OPTION_CPU0` selects the CPU pipeline core, with the default `CAPPUCCINO` and `ESPRESSO` and `PRONTO_ESPRESSO` as the alternatives, and the Usage column marks `CAPPUCCINO` as the one for Linux. `OPTION_RESET_PC` sets the program counter at reset, defaulting to `0x100`. The caching parameters are the bulk of the tables, and they are symmetric: data and instruction caches are each controlled by a feature flag defaulting to `NONE`, with block width, set width, ways and limit width parameters, and the interesting entry is the data cache limit width, where the Usage column says 31 for Linux to allow uncached device access, while the default is 32. The system bus parameters cover the store buffer, which defaults to enabled with the note that it has a large footprint, the bus interface type defaulting to `WISHBONE32`, and separate instruction and data bus types where the instruction bus defaults to `B3_READ_BURSTING` and the data bus defaults to `CLASSIC`.

## MMUs, debug and the hardware units

The memory management unit parameters are again symmetric between the data bus and the instruction bus, and again the Usage column is the interesting part. Both the data MMU and the instruction MMU default to `NONE` and the Usage column says Linux expects `ENABLED` for both. The hardware TLB reload feature defaults to `NONE` and the Usage column says Linux expects `NONE`, which is the kind of detail that only matters once something misbehaves. The hardware unit parameters cover the traceport interface, which is marked for Verilator, the debug unit for hardware breakpoints and the advanced debug unit interface, which is marked for OpenOCD, the performance counters with a configurable number, the internal OpenRISC timer, which defaults to enabled, and the internal OpenRISC PIC with a trigger mode that can be level, edge or latched level. The Usage column ties the traceport to Verilator and the debug unit to OpenOCD, which tells you what those two features are actually for.

## Multicore, the FPU and the ALU

The remaining hardware parameters cover the things that decide what the core can run. The number of shadow register files is settable from 0 to 16 with the Usage column saying to set it to at least 1 for Linux SMP, and there is a companion feature for fast context switching of register sets. The multicore feature enables the `coreid` and `numcores` special purpose registers and is also marked for Linux SMP, so SMP support comes as a pair of switches. The FPU is available for the cappuccino pipeline only, which is a constraint worth knowing if you are tempted to pick the espresso core. The branch predictor has three implementations to choose from, `SIMPLE`, `GSHARE` and `SAT_COUNTER`. The ALU options cover the multiplier, with five implementations including a simulation variant, the divider, the shifter and the carry flag. The exception handling options cover the delay slot flag, range checking and overflow checking, all enabled by default.

## Building the documentation, and the floating point caveat

The documentation lives in the doc directory, in asciidoc format, with a makefile that builds HTML or PDF, and the README gives the command to run in that directory:

```bash
  $ make html
```

There is also a note about floating point behaviour that is the kind of thing that belongs in a core's documentation rather than in a wiki. C and C++ float to integer conversion assumes truncation, rounding toward zero, and the `lf.ftoi.s` instruction performs such a rounding regardless of the rounding mode bits of the floating point control and status register, while all other floating point instructions always perform rounding according to those rounding mode bits. For a core targeting Linux with a compiler that follows the C rules, that is a genuine difference between what the hardware does and what the language standard expects, and it is exactly the sort of detail that has to be in the core's own documentation.

## Where this is the wrong choice

The limits are clear from the framing of the project. First, it is a 32 bit general purpose core, with the operand width parameter offering 64 as a value but the rest of the documentation describing a classic small embedded processor, and there is no mention of a superscalar or out of order design, so anyone wanting server class performance is looking in the wrong place. Second, there is no verification environment here, and the README says so directly, which means the cost of adopting this core includes assembling a testbench, a software image and somewhere to run it, and that work is not small for a CPU. Third, the configuration surface is a double-edged feature. The parameter tables are excellent, but every non-default choice is a place where you can build something that passes a smoke test and fails on real software, and the Usage column only records the cases the author knew about. Fourth, the maintenance picture is thin. The tags are v5.1.1 and v5.1, both from 2022, while the last push was on 2026-06-06, so the tree has moved on from the last release without a new one, and for a core that people instantiate in their own designs, an unpinned revision is a risk. And fifth, the licence, while appropriate for hardware, is worth understanding before you mix this core with code you intend to keep closed, since the Weakly Reciprocal variant of the CERN Open Hardware Licence has its own conditions for derived designs.

## Conclusion

mor1kx fits an FPGA or ASIC project that needs a small 32 bit processor core with a build-time configurable feature set, since the parameter table lets you include or drop the caches, MMUs, FPU, debug unit and performance counters according to the target rather than paying for them in area. It is the wrong choice if you want a verification environment or a board ready build, since the repository explicitly says it contains only the IP source and some documentation, and the wrong choice if you need something more than a 32 bit general purpose core. Before you start, work through the Usage column in the configuration tables, because the differences marked there, such as the data cache limit width of 31 for Linux to allow uncached device access, are the ones that decide whether a board boots. The last push was on 2026-06-06, the newest tags are v5.1.1 and v5.1 from 2022, and the licence is CERN-OHL-W-2.0.

## FAQ

### What is mor1kx and what does it include?

It is an OpenRISC 1000 compliant processor IP core written in Verilog HDL. The repository contains only the IP source code and some documentation, and the README points at other projects for a verification environment.

### Which mor1kx parameters matter when running Linux?

The configuration tables have a Usage column for this. It marks `CAPPUCCINO` as the CPU pipeline core for Linux, 31 as the data cache limit width to allow uncached device access, `ENABLED` for both the data and instruction MMU, `NONE` for hardware TLB reload, at least one shadow register file and the multicore feature for SMP, and the FPU is available for the cappuccino pipeline only.

### How is the mor1kx documentation built?

The documentation is in the doc directory in asciidoc format, with a makefile that builds HTML or PDF. To build the HTML version you run `make html` in that directory.

## Sources

- [Issues](https://github.com/openrisc/mor1kx/issues)
- [openrisc/mor1kx on GitHub](https://github.com/openrisc/mor1kx)
- [README](https://github.com/openrisc/mor1kx/blob/master/README.md)
- [Releases](https://github.com/openrisc/mor1kx/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openrisc-mor1kx