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.
Contents |
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 jrtc4@zeno.sec.cl.cam.ac.uk:/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 [...]