CHERI

CHERI-QEMU

CHERI-QEMU is an adaptation of the popular QEMU ISA emulator to implement the CHERI-MIPS and CHERI-RISC-V instruction sets. CHERI-QEMU boots CheriBSD and passes all of the CheriBSD MIPS/RISC-V and CheriABI tests. More information on QEMU itself can be found on the QEMU Wiki.

Obtaining CHERI-QEMU

The best way to get started with CHERI-QEMU is using our cheribuild tool, which will automatically download and build the necessary source. The compiled binaries will be installed to ~/cheri/output/sdk/bin by default.

Get started with CHERI-QEMU in one command line:

./cheribuild.py --include-dependencies qemu

The CHERI-QEMU source code can be found in the CHERI-QEMU GitHub repository. We also use a GitHub issue tracker to track bugs and feature requests.

CheriBSD Startup and Regression Testing

In practice, however, CHERI-QEMU is most useful if you also have an OS image. The following command line builds CheriBSD/RISC-V, CHERI-QEMU, and the complete toolchain including tools such as CHERI Clang/LLVM and CHERI GDB, and runs the resulting image in CHERI-QEMU:

./cheribuild.py --include-dependencies run-riscv64-purecap

This will boot CheriBSD to a multiuser prompt as follows:

$ ./cheribuild.py --include-dependencies run-riscv64-purecap
[...]
Copyright (c) 1992-2020 The FreeBSD Project.
Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
	The Regents of the University of California. All rights reserved.
FreeBSD is a registered trademark of The FreeBSD Foundation.
FreeBSD 13.0-CURRENT #0 ea692111dcc-c1(master)-dirty: Thu Dec  3 13:22:10 UTC 2020
    [Javascript required]:/home/jrtc4/cheri/build/cheribsd-riscv64-purecap-build/home/jrtc4/cheri/cheribsd/riscv.riscv64c/sys/CHERI-QEMU riscv
clang version 11.0.0 (https://github.com/CTSRD-CHERI/llvm-project.git ca275db7edb8f9ac26a926f750c0fc263da0ac27)
CHERI hybrid kernel.
[...]
FreeBSD/riscv (cheribsd-riscv64-purecap) (ttyu0)

login:

At this point you can login as the root user (no password) and run the CheriBSD regression tests:

login: root
[...]
root@:~ # cheribsdtest-hybrid -a
[...]
root@:~ # cheribsdtest-purecap -a
[...]
root@:~ #

Note that QEMU can be exited using the key sequence "Ctrl-a x" at any time.

Instruction, Register and Memory Tracing

CHERI-QEMU also has support for simple instruction, register and memory tracing. This is very useful for debugging and can be turned on (and off) by the command-line when QEMU is started or via the QEMU monitor. Note that turning on instruction tracing will add a lot of overhead to the QEMU emulation and can generate very large trace log files.

In addition to the disassembled instructions the trace includes changes to registers and memory. Here is a small sample of what the trace log looks like on CHERI-MIPS (e.g. start of an exception handler):

0xffffffff80000194:  csetdefault        c30
    Write C00|v:1 s:0 p:7fffffff b:0000000000000000 l:ffffffffffffffff
             |o:0000000000000000 t:0
[...]
0xffffffff8051d0ec:  sd a3,296(k1)
    Memory Write [c000000000143588] = 000000016004f5a0
0xffffffff8051d0f0:  cgetcause  k0
    Write k0 = 00000000000006ff
0xffffffff8051d0f4:  daddiu     t4,k1,608
    Write t4 = c0000000001436c0
0xffffffff8051d0f8:  csc        c28,t4,192(c30)
    Cap Memory Write [c0000000001436c0] = v:1 tps:00000000ffff00fa
    c:0000000000000000 b:0000000000000000 l:0000010000000000

Starting Instruction Tracing on Start Up

To start instruction tracing on start up add "-D <logfile> -d instr" to the QEMU command-line. For example (for CHERI-MIPS):

$ qemu-system-cheri128 -M malta -kernel ./kernel -nographic -hda ./disk.img -m 2048 -D /var/tmp/instr.log -d instr

Starting and Stopping Instruction Tracing via CheriBSD command

CheriBSD also has a tool /usr/bin/qtrace that can be used to toggle QEMU tracing. This will log the traces to the file specified using the -D flag on QEMU startup. For example:

$ qtrace -u exec /bin/true  # trace user-space instructions for cat
$ qtrace exec /bin/true     # trace all instructions for true
$ qtrace start              # turn on instruction tracing
$ qtrace stop               # turn off instruction tracing

Starting and Stopping Instruction Tracing via QEMU Monitor

Instruction tracing can also be started and stopped using the QEMU Monitor. To do this toggle into the QEMU Monitor using the "Ctrl-a c" key sequence. At the QEMU Monitor prompt, to start instruction tracing, do:

(qemu) logfile /var/tmp/instr.log
(qemu) log instr

Toggle back to the console with another "Ctrl-a c" key sequence.

To stop instruction tracing using the QEMU Monitor:

(qemu) log none

CHERI=QEMU can also create CHERI-MIPS instruction traces that are compatible with the libcheritrace format that is used by the tracedump utility and CheriVis. To generate libcheritrace instruction traces use '-d cvtrace' instead of '-d instr'. For example:

$ qemu-system-cheri128 -M malta -kernel ./kernel -nographic -hda ./disk.img -m 2048 -D /var/tmp/cvtrace.bin -d cvtrace
[...]
$ tracedump -t /var/tmp/cvtrace.bin
[...]