Quickstart#

pw_kernel: A Rust-based kernel for embedded systems

The easiest and fastest way to get started with pw_kernel is to copy our full-featured adventure example (pw_kernel/examples/adventure) and strip out whatever you don’t need. Although the code is in Upstream Pigweed the example is structured as an out-of-tree (i.e. self-contained) Bazel project, so you should be able to get it up and running within minutes.

Setup#

Clone the upstream Pigweed repo:

git clone https://pigweed.googlesource.com/pigweed/pigweed --depth 1

Move the pw_kernel/examples/adventure directory out of upstream Pigweed:
```
mv pigweed/pw_kernel/examples/adventure app
```
You can call it whatever you want but we’ll assume app throughtout this quickstart.
Make app your working dir:
```
cd app
```
Open //MODULE.bazel, uncomment the git_override invocation, and delete (or comment out) the local_path_override invocation.
```
 1bazel_dep(name = "pigweed")
 2
 3# Quickstart users should uncomment the `git_override` below and delete the
 4# `local_path_override` that follows it.
 5# git_override(
 6#       module_name = "pigweed",
 7#       commit = "603d02a539f7777187ff72bc39b48ee1000ca8b2",
 8#       remote = "https://pigweed.googlesource.com/pigweed/pigweed.git",
 9# )
10local_path_override(
11    module_name = "pigweed",
12    path = "../../..",
13)
```
Note

This step essentially sets up app to be a completely standalone project. Recall that this code example is hosted within the upstream Pigweed repository. In that context, it’s OK to assume that the pigweed dependency can be found at the local path ../../... When using app as the starting point for your own project, however, there’s no need to separately download the upstream Pigweed repo to a certain path. You can instead use git_override and let Bazel fetch the dependency over the network.

Build#

Build the app for RV32 QEMU:

$ bazelisk build //targets/riscv_qemu/simulated:adventure

See Install Bazel if you don’t have bazelisk installed.

Troubleshooting: `No MODULE.bazel, REPO.bazel, or WORKSPACE file found`#

If you see this error:

Starting local Bazel server (9.1.0) and connecting to it...
ERROR: fetching pigweed+: java.io.IOException: No MODULE.bazel, REPO.bazel,
or WORKSPACE file found in …/external/pigweed+
ERROR: Error computing the main repository mapping: error during computation
of main repo mapping: No MODULE.bazel, REPO.bazel, or WORKSPACE file found
in …/external/pigweed+

You need to modify MODULE.bazel as explained in Setup.

Simulate#

Simulate the app on RV32 QEMU:

$ bazelisk run @pigweed//pw_kernel/tooling:qemu_runner -- \
    --cpu rv32 \
    --machine virt \
    --semihosting \
    --image $(pwd)/bazel-bin/targets/riscv_qemu/simulated/adventure.elf

Next steps#

Check out Tour of pw_kernel for an in-depth explanation of the software architecture of the adventure example.