Installation

Prerequisites

Sentinel requires Python 3.11 or newer. It additionally uses PDM as its package/dependency manager, and to orchestrate all things you can do with its source code. I highly recommend installing pdm version 2.20 or newer, at least until I work out the details of using Sentinel without pdm. Use either pip or pipx, depending on your Python installation’s recommendation:

pipx install pdm

If you don’t have Python 3.11 or later installed, and cannot install it locally, pdm can install one for you for any project using Sentinel as a dependency. See pdm python for details.

Yosys And FOSS Toolchains

Amaranth, and by extension Sentinel, requires yosys, which is not a Python package. Amaranth itself provides a yosys subset as part of its builtin-yosys feature. Additionally, for creating demo bitstreams, nextpnr is required. the YoWASP project provides a full yosys binary as a PyPI package.

While developing Sentinel, I personally use the Windows/Linux/etc versions of yosys and other tools, for several reasons:

  • It’s what I am/was used to.

  • Sometimes I need to modify the tools to test bug fixes. Rebuilding native tools is easier for me than rebuilding WASM tools.

  • Tests would not work anyway; there’s no SAIL nor riscv64-unknown-elf-gcc WASM binaries yet (AFAIK).

However, for Verilog and Demo generation (e.g. everything inside the Quick Start, I support using builtin-yosys/YoWASP or local tools. By default, local tools are used. You can install Amaranth with the builtin-yosys feature and YoWASP by running:

pdm install -G yowasp

To swap from a local toolchain to YoWASP, use:

pdm use-yowasp

This installs a set of envrionment variables into .env.toolchain at the source root. All commands run via pdm get these variables, which in turn Amaranth uses to run Amaranth’s builtin-yosys functionality and alternate YoWASP versions of external tools.

To swap from YoWASP to a local toolchain, use:

pdm use-local

This removes the .env.toolchain file if present; pdm happily runs without one.

Todo

Can .env.toolchain somehow be used per virtual environment (to allow per-virtualenv toolchains)?

Note

I may eventually add example support for targets without a FOSS toolchain, such as Vivado.

I don’t anticipate WASM binaries for any of these toolchains anytime soon, so even if you opt to use the YoWASP flow, you will have to provide proprietary toolchain binaries (or remote access to them) yourself.

If you want to hack on tests, where YoWASP doesn’t currently work, and/or don’t feel like building yosys, binaries are available from OSS CAD Suite. Ensure LD_PRELOAD is not set if using OSS CAD Suite. And of course, make sure yosys is on your PATH :).

As A Dependency

You can install Sentinel from PyPI:

pip install sentinel-cpu

The main branch, which infrequently changes except during releases, may contain bug fixes from the development branch. You can install the main branch via:

pip install git+https://codeberg.org/cr1901/sentinel@main

If you wish to be adventerous and follow the development branch, use this command instead:

pip install git+https://codeberg.org/cr1901/sentinel@next

Todo

I am still working out the details on using Sentinel outside of PDM. There are use cases, such as LiteX, but I’ve decided to wait to implement this until another release.

In A PDM Project

One intended workflow of Sentinel is in a mixed-language (Verilog, VHDL, Amaranth, Chisel, etc) environment, where PDM manages the Python code or even the entire project. In this case, dependencies should be managed by PDM.

When the PyPI package is available, run:

pdm add sentinel-cpu

at the root of your project. Otherwise, run:

pdm add sentinel-cpu@git+https://codeberg.org/cr1901/sentinel@main

to bring in the main branch, or

pdm add sentinel-cpu@git+https://codeberg.org/cr1901/sentinel@next

to bring in the development branch.

Warning

When advantageous, the next branch tracks upstream git packages without pinning to a branch or commit (that’s what pdm.lock is for). These include:

Additionally, some Amaranth packages/dependencies are still in flux and don’t have a stable release to track on PyPI. Until they do, the main branch may also depend on git dependencies without pinning.

However, if installing/using either branch breaks due to immediate dependencies changing, I will make a release on main, and commit on next to correct the breakage (and possibly add more tests to CI). See here for rationale.

Development Environment

Sentinel’s source code is also managed by PDM. To get started, check out a copy of the source code and then run pdm install:

git clone https://codeberg.org/cr1901/sentinel
cd sentinel
git submodule update --init --recursive
pdm install -G dev -G lint -G examples

The commands above will initialize a virtual environment consisting of:

  • Amaranth, a Python embedded DSL for creating digital circuits.

  • m5meta microcode assembler, without which Sentinel would optimize down to ~0 LUTs :).

  • pytest for basic/regression testing.

  • DoIt as a lower-level dependency-graph aware task orchestrator (called from pdm).

  • riscv-tests, an older set of unit tests for RISC-V processors. Running these is done via pytest.

  • RISC-V Formal to verify that desirable properties of Sentinel (such as “instructions write the correct destination”) hold for all possible inputs over a bounded number of clock cycles after reset.

  • RISCOF, the unit test framework that is maintained by RISC-V International themselves. This appears to have originally been derived from the riscv-tests, but is much more comprehensive.

Additionally, make sure the following are installed:

  • yosys and nextpnr-ice40, as described above.

  • boolector SMT solver.

    Note

    Boolector is no longer maintained. Eventually I will update to Bitwuzla.

  • SymbiYosys verification driver.

  • riscv64-unknown-elf-gcc C/C++ compiler and assembler.

    The binary name is hardcoded by scripts. In principle, the actual toolchain binary doesn’t matter, but the scripts haven’t been updated yet.

  • rustc/rustup with the riscv32i-unknown-none-elf target.

    Rust is currently only required for certain example designs.

  • The RISCOF tests also requires the SAIL RISC-V emulator. This is a pain to compile, so I provide a Linux binary (and eventually Windows if I can get OCaml to behave long enough. I used to be able to install it just fine :’D!).

Where To Find Dependencies

If you are having trouble finding binaries via package manager, yosys, nextpnr-ice40, boolector and SymbiYosys are provided by OSS CAD Suite, and SiFive still provides downloads to usable GCC versions in an archived repo.

Rather than using your distro’s package manager, I suggest installing Rust using the directions here and then run rustup target add riscv32i-unknown-none-elf to add the RISC-V specific libstd/libcore. I think the package manager Rust and the rustup-installed Rust can coexist.

Next, head over to the Overview page for how to hack on Sentinel :).