sentinel-cpu 0.1.0b2

Embedded RISC-V implementation written in Amaranth

Logo by Tokino Kei.

sentinel

Sentinel is a small RISC-V CPU (RV32I_Zicsr) written in Amaranth. It implements the Machine Mode privileged spec, and is designed to fit into ~1000 4-input LUTs or less on an FPGA. It is a good candidate for control tasks where a programmable state machine or custom size-tailored core would otherwise be used.

Unlike most RISC-V implementations, Sentinel is microcoded, not pipelined. Instructions require multiple clock cycles to execute. Sentinel is therefore not necessarily a good fit for applications where high throughput/ IPC is required. Short version: minimum of 4 CPI for basic arithmetic, maximum of 69 for a 31-bit shift (yes, shift instructions need work).

Sentinel has been tested against RISC-V Formal and the RISCOF frameworks, and passes both. Once I have added a few extra tests, the core can be considered correct with respect to the RISC-V Formal model. The core is also probably correct with respect to the SAIL golden model.

Why The Name sentinel?

I've like the way the word "sentinel" sounds ever since I first learned of the word, either from the title of a book on NJ lighthouses, or on an enemy from an old Sega Genesis RPG. The term has always stuck with me since then, albeit in a much more positive light than "the soldier golems of the forces of Darkness" :). Since "sentinel" means "one who stands watch", I think it's an apt name for a CPU intended to watch over the rest of your silicon, but otherwise stay out of the way. Also, since lighthouses are indeed "Sentinels Of The Shore", I wanted to shoehorn a lighthouse into the logo :).

Quick Quick Start

Verilog Programmers

If you're primarily a Verilog/VHDL programmer, each Sentinel release includes ready-to-use, standalone Verilog as an asset. If you wish to use Verilog generated from an arbitrary commit without getting involved with the source, see Pre-Generated Verilog section of the Quick Start docs.

Amaranth Programmers

For Amaranth programmers wishing to use Sentinel without playing with the source, you can install sentinel-cpu using pip or pdm. When a PyPI package is available, you will probably want one of the following:

• pip install sentinel-cpu
• pdm add sentinel-cpu

However, since there's no PyPI package right now, I recommend substituting the sentinel-cpu Name-Based Lookup with the git+https://codeberg.org/cr1901/sentinel@main URL-based lookup. See the As A Dependency section of the Installation docs for other useful command-lines.

Source Code Demos

For those who want to play with the source, the absolute fastest way to get started is to check out the source code, install pdm, use pdm to create a virtual environment with appropriate tools, and generate an .env.toolchain file that pdm uses to set some environment variables for Amaranth:

pipx install pdm
git clone https://codeberg.org/cr1901/sentinel.git
cd sentinel
pdm venv create -n quick-quickstart
pdm install --venv quick-quickstart -G examples -G yowasp
pdm run use-yowasp

Use pip or pipx to install pdm depending on your Python install's recommendation.

Then, to generate Verilog core with a Wishbone Classic bus, and clk, rst, and irq input pins, run:

pdm run --venv quick-quickstart gen

To create a demo bitstream that counts primes and sets LEDs accordingly (for the iCE40-HX8K Breakout Board), run:

pdm run --venv quick-quickstart demo -i csr -p ice40_hx8k_b_evn

The output will be available in build/ at the source code root.

If you have Rust installed with the riscv32i-unknown-none-elf target, you can create a Rule 110 demo that prints neat patterns to the serial port:

pdm run --venv quick-quickstart demo-rust -i csr -p ice40_hx8k_b_evn

The output will be available in build-rust/ at the source code root.

Run pdm run --venv quick-quickstart gen -h and pdm run --venv quick-quickstart demo -h for help, and experiment!

When you're done, unset the environment variables and optionally destroy the virtual environment, as we will not be using it again:

pdm run use-local
pdm venv remove quick-quickstart

Note that extra dependencies are required for development. See the next section.

Quick Doc Links

• To get started with an environment suitable for development, consult the Installation doc page.
• For information on the source code development environment, click here.
  • Source code guidelines are found on the Development Guidelines page.
• For other use cases, consult the Quick Start page. Note that they are a little less quick than the Quick Quick Start :).
• Sentinel has multiple test suites. External submodules have their own README.mds for context and quick instructions. The Testing page and subpages give further instructions and information.
• The Public API has its own page.
  • Internal Amaranth Components are documented on the Internals page.
• A copy of the below block diagram, detailed instruction cycle counts, and implemented CSRs are also on the Internals page.
• Microcode information has its own page.

Block Diagram