Quick Start

Note

The Quick Start assumes you have Python installed and want to explore the source code. If neither of those apply, you can:

  • import Sentinel as a Python package in your own Amaranth code.

  • Download the Verilog of the lastest release of Sentinel here.

See Pre-Generated Verilog and Use In Amaranth Code for more information.

Using The Source

From a checkout of Sentinel’s source, you have a few options to try out Sentinel risk free! The below commands assume you and are running commands at the source code root, and that you’ve installed pdm, yosys, and possibly nextpnr-ice40:

pipx install pdm
git clone https://codeberg.org/cr1901/sentinel_cpu.git
cd sentinel
pdm install -G examples

If you don’t have an external yosys or nextpnr-ice40, and don’t wish to install them, you can use the YoWASP flow for this section instead:

pipx install pdm
git clone https://codeberg.org/cr1901/sentinel_cpu.git
cd sentinel
pdm install -G examples -G yowasp
pdm run use-yowasp

Note

An alternate take on the Quick Start using YoWASP (which will probably be seen by more people) is detailed in the “Quick Quick Start” section of the README.md at the repo root. The README.md demonstrates creating and destroying a separate virtual environment for using the YoWASP flow. Both sets of commands should have the same results; I omit venv handling here to keep the docs simpler.

Generate A Verilog Core

To generate Verilog for a Sentinel CPU with a Wishbone classic bus and an IRQ line, run:

pdm gen -o sentinel_cpu.v

Verilog generation only generates a CPU, not a full SoC or design. You must integrate the Sentinel source file into an larger external HDL project (Amaranth, Verilog, or otherwise).

A Full Example SoC In Amaranth

The examples.attosoc module shows one way to create a simple Sentinel SoC with a UART, timer, and GPIO. Examples should not be taken as a canonical way to create Amaranth SoCs. They are subject to change as Amaranth matures (and are also a good way for me to experiment :)).

The AttoSoC class constructs the SoC from various peripheral classes contained within attosoc. Peripherals come with either a Wishbone bus interface or a CSR bus interface from amaranth-soc (bridged to Wishbone). The main() function provides an argparse command-line entry point, and demo() actually builds the SoC.

Right now, attosoc uses Amaranth to build a SoC bitstream for several platforms:

The pdm scripts demo and demo-rust are thin wrappers over main() Extra arguments can be sent by using pdm demo [more] [args] [here...]; be careful of overriding args hardcoded to be sent by the pdm script!

Rust Demo

If you have a Rust compiler installed, you can create a demo that prints a Rule 110 pattern to a serial console:

pdm demo-rust [args ...]

This script compiles a Rule 110 example in the sentinel-rt crate and sends the resulting ELF file off to the demo function. The output bitstream will be available under the build-rust directory.

Assembly Demo

If you don’t wish to or can’t install a Rust compiler, I provide a fallback firmware written in assembly that requires no external dependencies.

pdm demo [args ...]

This firmware calculate primes up to 255, and lights up LEDs for each prime found. The output will be available under the build directory.

Todo

demo parameters are only really documented in passing/prose right now, and not even all of them at that:

  • Punt the remaining params to development sections?

  • Prose might be enough?

For help on all tweakable parameters, use the -h command-line option:

pdm gen -h
pdm demo[-rust] -h

For use outside of the source tree, see the Reference page.