What is this?

This is Project Open Se Cura, a project to research the fusion of novel hardware and software architectures to produce a low-power, ambient AI core.

Developing in this Codebase

We've stored our code in Gerrit, and like the Android developers before us, we use repo to manage the projects in our Gerrit repositories.

To get started, first make sure you have a Git login for all our projects by going to googlesource.com/new-password and pasting the provided script into a terminal.

Now you need to pull down a copy of the repo tool from our public facing sites and add it to your path:

mkdir -p bin
export PATH=$PATH:$HOME/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

Make sure you've initialized git with your name and email address, and have configured it properly for fetching the sources:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Once you‘ve done this, you’re actually ready to check out the sources. Make a new directory where you'd like it to live, and initialize repo with the current release branch.

repo init -u https://opensecura.googlesource.com/manifest
repo sync -j$(nproc)

System Setup for Development

Development for shodan requires that the necessary tools and prerequisites be installed.

To setup the build system:

source build/setup.sh

Add the bazel apt repository to your machines sources. Instructions @ https://bazel.build/install/ubuntu#add-dis-uri

Install the prerequisites:

m prereqs

Install the tools used for development:

m tools -j$(nproc)

Repository Layout

Our layout is pretty simple:


Contains build scripts for the whole tree. This is effectively just an orchestration layer to make building the whole shebang easier. Each subtree may have its own build systems and have their own ways of building.


The cached cross-compilation toolchain, including rust and RISC-V GCC/LLVM toolchain.


Lots of extra documentation (we hope) about how the repo is laid out, how the build system works, code reviews, licensing, etc.


Contains all of the source code and RTL required to build the Shodan hardware, as well as simulate it in Verilator.


External contributor's HW IPs.


RTL of the ML core for ML acceleration.


Top-Level integrated HW platform of the multi-core system.


Opentitan repository as a library to leverage its IP for the security core and peripheral IP design.


Operating system software for the SMC; including seL4 kernel & CAmkES framework, and custom CAmkES components that support Shodan (or maybe CantripOS) applications.


The repo manifest used to glue all the git repositories together.


Contains utility scripts to help automate a few things.


Contains tools and src for simulators (Kelvin, Renode, and Verilator) of the shodan system.


Contains the source code of applications running in all shodan cores.


Kelvin ML core BSP, the TFLM optimized kernel, and the instruction functional tests.


TockOS library


The platform and application SW running on the security core.


pigweed frameworks. Currently it is used for springbok core functional tests.


TensorFlow Lite for Microcontroller framework for ML deployment. A fork for the upstream project to support Kelvin vector instructions.


The operating system running on the Security Core.


Springbok (RVV) ML core BSP, as well as the RVV instruction functional tests.


ML core IREE application. It builds IREE runtime applications for ML models using IREE libraries and ML Core BSP.


ContainsIREE toolchain for ML models.

Build and Test ML Artifacts

The ML executable is built with IREE workflow, targeted to RISCV 32-bit bare-metal config.

To build the IREE targets:

set-platform nexus
m iree

The IREE compiler sits in out/host/iree_compiler, while the runtime library/example sits in out/<ml core>_iree. To run the toy example (four-element vector element-wise multiplication) on kelvin for testing:

sim_kelvin out/kelvin_iree/sparrow_iree/samples/simple_vec_mul/simple_int_vec_mul_bytecode_static

The output should be shown as:

Starting simulation
INFO |simple_int_vec_mul finished successfully
Program exits properly
Total cycles: 237101
Simulation done: 0.070 sec

Running The Full Shodan System Simulation

The simulator used for Shodan is Renode. The configuration for the Shodan system is sim/config/platforms/shodan.repl, while and starting script is in sim/config/shodan.resc

To run the full system simulation, build the default target:

set-platform shodan

After all the artifacts are bulit, the Renode simulation session automatically starts, and you should see the secured core and SMC booted

10:11:43.1993 [INFO] uart5: [output] init_kernel()
10:11:43.2012 [INFO] uart5: [output] Init local IRQ
10:11:43.2018 [INFO] uart5: [output] Bootstrapping kernel
10:11:43.2053 [INFO] uart5: [output] Initialing PLIC...
10:11:43.2830 [INFO] uart5: [output] Booting all finished, dropped to user space
10:11:43.2978 [INFO] uart5: [output] cantrip_os_rootserver::Bootinfo: (485, 131072) empty slots 1 nodes (15, 81) untyped 131072 cnode slots
10:11:43.3008 [INFO] uart5: [output] cantrip_os_rootserver::Model: 1011 objects 32 irqs 0 untypeds 2 asids
10:11:43.3123 [INFO] uart5: [output] cantrip_os_rootserver::capDL spec: 0.10 Mbytes
10:11:43.3142 [INFO] uart5: [output] cantrip_os_rootserver::CAmkES components: 1.08 Mbytes
10:11:43.3191 [INFO] uart5: [output] cantrip_os_rootserver::Rootserver executable: 0.39 Mbytes

At this point, you should be able to connect to the SMC debug console.

Setting Up Debug Console Communication

Install socat to your machine

sudo apt install socat

In a new shell session, launch the debug console with


You will see the CantripOS prompt showing up when you hit enter. Use ctrl-c to leave the console.

Connecting to Renode Console

Renode has its own console to control the emulation environment. You can connect to it by

telnet localhost 1234

For example, you can check the core status

(matcha) cpu1 IsHalted

or stop the whole emulation with

(matcha) quit

Launch ML Job on the ML Core

You can launch the ML workload execution by communicating through the debug console

Check existing builtin applications

CANTRIP> builtins

Start the embedded ML model app; for example,

CANTRIP> start mltest

with the Renode console log printed as

15:17:59.9864 [INFO] uart5: [output] cantrip_ml_coordinator::Load successful.
15:18:02.6868 [INFO] uart5: [output] [mltest]::Model completed: mask 0b0001 ms 0
18:18:45.7710 [INFO] uart5: [output] [mltest]::DONE!

More Information

For more available Shodan build targets, please use the in-project command of hmm and hmm <target name>.

Also, Information on how to use repo