or1k_marocchino - OpenRISC processor IP core based on Tomasulo algorithm

The Basics

This repository contains an OpenRISC 1000 compliant processor IP core. The core:

1. Implements a variant of Tomasulo algorithm
2. Supports single and double precision floating point instructions
3. Has separate CPU and Wishbone clocks, assuming that the CPU clock is greater than or equals the Wishbone clock, but they must be aligned
4. Supports atomic instructions (load linked / store conditional)
5. Supports data bus snoop and shadow registers set for multicore systems

It is written in Verilog HDL.

This repository only contains the IP source code and some documentation. For a verification environment, please see other projects. See some details below.

License

This project is licensed under the Open Hardware Description License (OHDL). For details please see the LICENSE file or http://juliusbaxter.net/ohdl/

Style guide for contribution

1. TABs are forbidden, only SPACEs are allowed
2. Use 2 SPACEs as indent
3. Use Verilog 200x style for modules declarations
4. Use _i and _o suffixes in input/output names (inherited from mor1kx)
5. Do not include Emacs AUTO_TEMPLATEs
6. Use alignment for declarations (for inputs, outputs, wires, etc) as it done in original sources
7. Align position of = and <= in adjacently places equations as it done in original sources
8. Always use begin/end for always @() process, but they could be omitted for single equation in if branches.
9. Separate () from if, case, etc with one SPACE (inherited from mor1kx)
10. Don’t include files if you don’t use things from inclusions
11. Don’t use timescale (inherited from mor1kx)
12. In general: try to keep nice appearance of MAROCCHINO sources by following the format of already written code

Testing and Continuous Integration

A CPU core cannot be trusted without a full set of verification testing. The or1k_marocchino is constantly verified for correctness with the or1k Continuous Integration (CI) suite running in travis ci. This currently covers:

• source linting - a verilator --lint-only check is run on each commit to ensure there are no code quality issues.

• or1k-tests - the or1k-tests test suite is run against different configurations to check most major instructions, exception handling, caching, timers, interrupts and other features.

  Status:

The or1k Continuous Integration (CI) suite is running in a librecores-ci-openrisc docker container in Travis CI. Parallel execution of tests runs in librecores-ci-openrisc docker environment.

• librecores-ci-openrisc docker image is based on the standard librecores/librecores-ci docker image and it largely target the FuseSoC use cases.
• The base image includes installation of common EDA tools such as Icarus Verilog, Verilator and Yosys that is required by CI suite for testing. librecores/libreocres-ci-openrisc docker image gets the toolchain required, downloads and compiles the or1k-tests.

In the future we are working on bringing more tests including:

• softfloat, fpu verification (may not be feasable in CI due to long run times)
• Resource utilization regression with yosys synth_intel synth_xilinx
• Formal verification with yosys
• Verification that each revision can boot differnt OS's Linux, RTEMS
• Golden reference or1ksim trace comparisons vs verilog model using constrained random inputs.

Configuration

MAROCCHINO is complete re-write of mor1kx CAPPUCCINO. As a result MAROCCHINO had inherited most of configuration options. At the same time a lot of original options were made permanently defined to reduce complexity. The following tables explain how each parameter can be configured, what the configuration does and why you might want to use it.

Note 1: Permanently defined options have got default value but Values field is filled with n/a that indicates that they are not presence among MAROCCHINO parameters.

Note 2: The Comments field below also could indicates if a certain application (such as running Linux) requires a setting different than the default value.

Basic parameters

Parameter	Description	Default	Values	Comments
OPTION_OPERAND_WIDTH	Specify the CPU data and address widths	32	32	Do not specify value other than 32. Actually the parametrization is incomplete.
OPTION_RESET_PC	Specify the program counter upon reset	0x100	n

Caching parameters

Parameter	Description	Default	Values	Comments
FEATURE_DATACACHE	Enable memory access data caching	ENABLED	n/a	It presences permanently
OPTION_DCACHE_BLOCK_WIDTH	Specify the address width of a cache block	5	5, 4	see notes below
OPTION_DCACHE_SET_WIDTH	Specify the set address width	8	n	see notes below
OPTION_DCACHE_WAYS	Specify the number of blocks per set	2	n
OPTION_DCACHE_LIMIT_WIDTH	Specify the maximum address width	32	n	31 for Linux to allow uncached device access
OPTION_DCACHE_SNOOP	Enable bus snooping for cache coherency	NONE	ENABLED NONE	Linux SMP
OPTION_DCACHE_CLEAR_ON_INIT	Clean up DCACHE RAM blocks at simulation start	0	0, 1	see notes below
FEATURE_INSTRUCTIONCACHE	Enable memory access instruction caching	ENABLED	n/a	It presences permanently
OPTION_ICACHE_BLOCK_WIDTH	Specify the address width of a cache block	5	5, 4	see notes below
OPTION_ICACHE_SET_WIDTH	Specify the set address width	8	n	see notes below
OPTION_ICACHE_WAYS	Specify the number of blocks per set	2	n
OPTION_ICACHE_LIMIT_WIDTH	Specify the maximum address width	32	n
OPTION_ICACHE_CLEAR_ON_INIT	Clean up ICACHE RAM blocks at simulation start	0	0, 1	see notes below

Note 3: When OPTION_I(D)CACHE_BLOCK_WIDTH is 5, that means cache block is 32 bytes length, i.e. 8 of 32-bits words, i.e. bust length is 8. Analogue to that if OPTION_I(D)CACHE_BLOCK_WIDTH is 4, cache block is 16 bytes length, i.e. 4 of 32-bits words, i.e. bust length is 4. As Wishbone bridges are designed to support only 8/4 length bursts the only 5/4 values are suitable for OPTION_I(D)CACHE_BLOCK_WIDTH.

Note 4: MAROCCHINO caches are virtually indexed and physically tagged. If you plan to use Linux (or any other OS involving IMMUs for virtual addressing support) you must select such OPTION_I(D)CACHE_BLOCK_WIDTH and OPTION_I(D)CACHE_SET_WIDTH to achieve OPTION_I(D)CACHE_BLOCK_WIDTH + OPTION_I(D)CACHE_SET_WIDTH = 13. 13-bits is minimal page size for OpenRISC. Recommended OPTION_I(D)CACHE_BLOCK_WIDTH/OPTION_I(D)CACHE_SET_WIDTH pairs are 5/8 and 4/9.

Note 5: The OPTION_I(D)CACHE_CLEAR_ON_INIT could be used to force clean up all I(D)CACHE RAM block at simulation start if something goes wrong during simulations. At the same time if you have to involve such initialization that typically means that something wrong with your testing environment.

Memory Management Unit (MMU) parameters

Parameter	Description	Default	Values	Comments
FEATURE_DMMU	Enable the data bus MMU	ENABLED	n/a	It presences permanently
FEATURE_DMMU_HW_TLB_RELOAD	Enable hardware TLB reload	NONE	n/a	not implemented
OPTION_DMMU_SET_WIDTH	Specify the set address width	6	n
OPTION_DMMU_WAYS	Specify the number of ways per set	1	n
FEATURE_IMMU	Enable the instruction bus MMU	ENABLED	n/a	It presences permanently
FEATURE_IMMU_HW_TLB_RELOAD	Enable hardware TLB reload	NONE	n/a	not implemented
OPTION_IMMU_SET_WIDTH	Specify the set address width	6	n
OPTION_IMMU_WAYS	Specify the number of ways per set	1	n

System bus parameters

Parameter	Description	Default	Values	Comments
FEATURE_STORE_BUFFER	Enable store buffer	ENABLED	n/a	It presences permanently
OPTION_STORE_BUFFER_DEPTH_WIDTH	Specify num bits for store buffer depth width	4	1-n	16 taps by default
OPTION_STORE_BUFFER_CLEAR_ON_INIT	Clean up at simulation start	0	0, 1
BUS_IF_TYPE	Specify the bus interface type	WISHBONE32	n/a	Other buses are not supported. Width is hard-coded.
IBUS_WB_TYPE	Specify the Instruction bus interface type option	B3_READ_BURSTING	n/a
DBUS_WB_TYPE	Specify the Data bus interface type option	B3_READ_BURSTING	n/a

Hardware unit configuration parameters

Parameter	Description	Default	Values	Comments
FEATURE_TRACEPORT_EXEC	Enable the traceport hardware interface	NONE	ENABLED NONE	Verilator
FEATURE_DEBUGUNIT	Enable hardware breakpoints and advanced debug unit interface	NONE	ENABLED NONE	OpenOCD
FEATURE_PERFCOUNTERS	Enable the performance counters unit	NONE	n/a	not implemented
OPTION_PERFCOUNTERS_NUM	Specify the number of performance counters to generate	0	n/a	not implemented
FEATURE_TIMER	Enable the internal OpenRISC timer	ENABLED	n/a	It presences permanently
FEATURE_PIC	Enable the internal OpenRISC PIC	ENABLED	n/a	It presences permanently
OPTION_PIC_TRIGGER	Specify the PIC trigger mode	LEVEL	LEVEL EDGE LATCHED_LEVEL
OPTION_PIC_NMI_WIDTH	Specify non maskable interrupts width, starting at 0, these interrupts will not be reset or maskable	0	0-32
OPTION_RF_CLEAR_ON_INIT	Enable clearing all registers on initialization	0	0, 1
OPTION_RF_NUM_SHADOW_GPR	Specify the number of shadow register files	0	0-16	Set >=1 for Linux SMP
OPTION_RF_ADDR_WIDTH	Specify the address width of the register file	5	5
OPTION_RF_WORDS	Specify the number of registers in the register file	32	32
FEATURE_FASTCONTEXTS	Enable fast context switching of register sets	NONE	n/a	not implemented
FEATURE_MULTICORE	Enable the coreid and numcores SPR registers	NONE	ENABLED NONE	Linux SMP
FEATURE_FPU	Enable the FPU	ENABLED	n/a	It presences permanently
FEATURE_BRANCH_PREDICTOR	Select the branch predictor implementation	GSHARE	n/a	It presences permanently

Exception handling options

Parameter	Description	Default	Values	Comments
FEATURE_DSX	Enable setting the SR[DSX] flag when raising exceptions in a delay slot	ENABLED	n/a	permanently
FEATURE_RANGE	Enable checking and raising range exceptions	ENABLED	n/a	implemented
FEATURE_OVERFLOW	Enable checking and raising overflow exceptions	ENABLED	n/a	implemented

ALU configuration options

Parameter	Description	Default	Values	Comments
FEATURE_MULTIPLIER	Specify the multiplier implementation	PIPELINED	n/a	It presences permanently
FEATURE_DIVIDER	Specify the divider implementation	SERIAL	n/a	It presences permanently
OPTION_SHIFTER	Specify the shifter implementation	BARREL	n/a	It presences permanently
FEATURE_CARRY_FLAG	Enable checking and setting the carry flag	ENABLED	n/a	It presences permanently

Instruction enabling options

Parameter	Description	Default	Values	Comments
FEATURE_MAC	Enable the l.mac* multiply accumulate instructions	NONE	n/a	not implemented
FEATURE_SYSCALL	Enable the l.sys OS syscall instruction	ENABLED	n/a	permanently
FEATURE_TRAP	Enable the l.trap instruction	ENABLED	n/a	GDB
FEATURE_ADDC	Enable the l.addc add with carry flag instruction	ENABLED	n/a	permanently
FEATURE_SRA	Enable the l.sra shirt right arithmetic instruction	ENABLED	n/a	permanently
FEATURE_ROR	Enable the l.ror* rotate right instructions	ENABLED	n/a	permanently
FEATURE_EXT	Enable the l.ext* sign extend instructions	ENABLED	n/a	permanently
FEATURE_CMOV	Enable the l.cmov conditional move instruction	ENABLED	n/a	permanently
FEATURE_FFL1	Enable the l.f[fl]1 find first/last set bit instructions	ENABLED	n/a	Linux
FEATURE_ATOMIC	Enable the l.lwa and l.swa atomic instructions	ENABLED	n/a	Linux SMP
FEATURE_CUST1	Enable the l.cust* custom instruction	NONE	n/a	not implemented
FEATURE_CUST2	Enable the l.cust* custom instruction	NONE	n/a	not implemented
FEATURE_CUST3	Enable the l.cust* custom instruction	NONE	n/a	not implemented
FEATURE_CUST4	Enable the l.cust* custom instruction	NONE	n/a	not implemented
FEATURE_CUST5	Enable the l.cust* custom instruction	NONE	n/a	not implemented
FEATURE_CUST6	Enable the l.cust* custom instruction	NONE	n/a	not implemented
FEATURE_CUST7	Enable the l.cust* custom instruction	NONE	n/a	not implemented
FEATURE_CUST8	Enable the l.cust* custom instruction	NONE	n/a	reserved for internal use