What is this?

This is Project Shodan, a project to research the fusion of novel hardware and software architectures to produce a low-power, ambient AI core. For more information, see our internal site at sites/cerebrahardware/shodan.

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://spacebeaker.googlesource.com/shodan/manifest -g default,internal
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

Install the prerequisites:

m prereqs

Install the RISCV toolchain:

m tools

Install the instruction set simulator:

m sim

Day-to-day Development Workflow

In general, working with repo is relatively simple:

1. Create a working topic branch to make changes on with repo start ${TOPICNAME}
2. Make your changes to the files. Add them with git add -A and commit with git commit.
3. Upload your changes with repo upload --re ${REVIEWER} --cc ${CC_LIST}
4. Go to the URL repo spits out to read and reply to comments.
5. Eventually your reviewer will give you a +2 LGTM on your change. To submit, click the “SUBMIT” button on the change in the web interface.
6. Run repo sync -j$(nproc) to update.
7. Run repo prune to remove your topic branch.

For more information on how to use repo and git effectively, take a look at the official documentation.

How to sync my local copy with latest?

repo sync -j$(nproc)

Then if you have any outstanding branches, a repo rebase will help.

How to send code for review?

To upload a branch to gerrit for review, do this:

repo upload --re reviewer1,reviewer2 --cc email@host.com,email2@host2.com

Reviewers can be specified as usernames or full email addresses, likewise for --cc.

Repo will then output a URL for you to visit that allows you to make comments and abandon and merge the changes into the repository. To make changes during the review process, make your changes to the files, then:

git add -A                                    # To add the files you've changed
git commit --amend                            # To update the previous change
repo upload -t --re ${REVIEWER} --cc ${CC_LIST} # To upload the change to Gerrit for review

Repository Layout

Our layout is pretty simple:

hw/

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

build/

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.

cache/

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

cicd/

Contains continuous integration scripts and tooling for Jenkins, our CI/CD tool.

docs/

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

manifest/

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

scripts/

Contains utility scripts to help automate a few things.

sim/

Contains tools and src for simulation of the shodan hw.

toolchain/

Contains the src to build the RISCV QEMU emulator, and IREE toolchain for ML models.

Start a simulation

The simulator used for Shodan is Renode. After building and installing the simulator it can be run by using the alias renode.

This alias is equivalent to the command:

mono cache/renode/Renode.exe

The configuration for the Shodan SoC is sim/config/shodan.repl, and an example of running zephyr on Shodan can be run as below:

include @sim/config/shodan_zephyr.resc
start

Build and test ML artifacts

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

To retrieve the IREE RISC-V toolchain and Renode emulator:

m tools

To build the IREE targets:

m iree

The IREE compiler sits in out/host/iree_compiler, while the runtime library/example sits in out/springbok_iree. To run the toy example (four-element vector element-wise multiplication) for testing:

sim_springbok out/springbok_iree/iree/iree/samples/simple_embedding/simple_embedding_embedded_sync

The output should be shown as:

(machine-0) 18:05:23.6463 [INFO] cpu2: simprint: "simple_embedding done", 0 (0x0)
18:05:23.6475 [INFO] cpu2: simprint: "main returned: ", 0 (0x0)

(Enter quit to exit the Renode simulation)

More Information

• Information on how to use repo