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

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://github.com/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 Quickstart 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