S3K Tutorial

Introduction to S3K

S3K is a capability-based separation kernel, intended to give user-level processes a high-level of control of their resources, and also provide a high-level of isolation between processes.

The target applications of S3K is resource-constrained embedded systems where we might not have virtual memory but require a flexible system that can dynamically reallocated limited resources while providing strong isolation guarantees.

Setting Up the Development Environment

We recommend that you use riscv-gnu-toolchain and qemu-system-riscv64.

Debian 12

# Installing qemu-system-riscv64
sudo apt install qemu-system-misc

# Installing the riscv-gnu-toolchain to $HOME/.local/opt/riscv
sudo apt-get install autoconf automake autotools-dev curl python3 python3-pip libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev ninja-build git cmake libglib2.0-dev libslirp-dev libncurses-dev
git clone https://github.com/riscv-collab/riscv-gnu-toolchain
cd riscv-gnu-toolchain
./configure --enable-multilib --prefix=~"$HOME/.local/opt/riscv" --with-cmodel=medany
make

# Modify PATH variable
export PATH=$HOME/.local/opt/riscv:$PATH
echo "export PATH=$HOME/.local/opt/riscv:$PATH" >> $HOME/.bashrc

Using Docker/Podman

We recommend using rootless docker/podman!

podman pull docker.io/hakarlsson/riscv-picolibc

To use the tools:

# At S3K root
podman run -it -v .:/workdir -w /workdir --net=host hakarlsson/riscv-picolibc bash

This mounts the local directory to /workdir within the container, allowing you to use riscv-gnu-toolchain and QEMU on those files.

Understanding the API

S3K's resource management model is based on capabilities. Capabilities are tokens give access to system resources. In S3K we have the following resources:

• Processes: An independent entities that carries out instructions of a programs. Their resources are determined by the capabilities they own.
• Memory Mapped Devices: Access to RAM, scratchpad, disks, and so on.
• Execution Time: Allows a process to execute on the CPU
• Inter-process communication: Allows a process to securely communicate with other processes.

Processes

A process in S3K consists of a process control block (PCB) and capability table (ctable). The PCB is the execution context of a process which includes:

• Process ID
• Process State defined by the following flags:
  • BUSY: The process is currently running or locked by another process.
  • WAITING: The process is waiting for an IPC call.
  • SUSPENDED: The process has been suspended.
• Timeout: When the process times out when waiting for IPC.
• General Purpose Registers from RISC-V
  • Program Counter (pc): Stores the memory address of the next instruction to be fetched and executed.
  • Return Address (ra): Holds the address of the instruction to return to after a function call.
  • Stack Pointer (sp): Points to the top of the stack, a data structure used for function calls, local variable storage, and other temporary data.
  • Global Pointer (gp): Points to a fixed location in memory where global variables are stored.
  • Thread Pointer (tp): Points to a thread-local storage area, used for thread-specific data.
  • Argument Registers (a0-a7): Used to pass arguments to functions.
  • Temporary Register (t0-t6): General-purpose registers used for temporary values during calculations.
  • Saved Register (s0-s11): Used to save the values across function calls.
• Virtual S3K Registers
  • Trap Program Counter (tpc): Stores the address of the trap handler.
  • Trap Stack Pointer (tsp): Stores the base stack pointer of the trap handler
  • Exception Program Counter (epc): Stores the address of the instruction that caused an exception.
  • Exception Stack Pointer (esp): Stores the value of the stack pointer when an exception occured.
  • Exception Cause (ecause): Indicates the reason for the exception, such as an illegal instruction or a memory access violation.
  • Exception Value (eval): Contains additional information about the exception, such as the address of the memory access that caused a memory access violation.
  • Servicing Time (servtime): Stores the minimal amount of execution time required by the server to access IPC calls.
• PMP registers, configured using PMP capabilities.
  • PMP configuration registers 0-7: Determines the RWX permissions of PMP regions.
  • PMP address registers 0-7: Determines the PMP regions.

The ctable is an array of capabilities protected by the kernel, describing the accessible system resources of a process. These resources includes memory, time, IPC, and other processes.

Memory Mapped Devices

Execution Time

Inter-process communication

Tutorial

In this tutorial, we introduce the concepts and API of S3K step-by-step. This tutorial is intended to be followed interactively using QEMU.

1. Init process

Learn how S3K's user-level processes start.

The first process to execute in S3K is the init process with process ID 0. The init process starts executing with pc = 0x80010000, so its program should be compiled and loaded to start at that address.

The init process, as the name suggest, is responsible for initializing the rest of the system. For this purpose, the init process is given the following capabilities:

• One memory slice capability per memory mapped resources, giving permission to manage RAM, UART, scratchpads, disks, and more.
• One time slice capabilities per hardware thread (harts), giving permission to access and manage execution time on said harts.
• A channel slice capability giving permission to manage every IPC channels.
• A monitor slice capability giving permission to manage every processes in the system.
• A PMP capability, giving the init process the right to execute the init code at 0x80010000. Without this, the init process will crash immediately.

These capabilities defines what the user-mode process will have access to during their life-time, and so the user-level system's accessible resources.

2. Trap Handling

Learn how processes handle their own exceptions.

3. UART communication

Learn how to set up UART communication.

4. Process creation

Learn how to set up initialize and start a new process.

5. Inter-Process Communication

Learn how to set up IPC.