-
Notifications
You must be signed in to change notification settings - Fork 1
FAQ: Standing Up Your Copy
Cheribuild is a nontrivial feat of engineering in its own right and it’ll be your best friend for getting started. The documentation is excellent and kept up to date. Alex works very hard on it and it shows. The overall set up is to install some requirements, set up the directory structure, clone a repo, and let Cheribuild work perhaps while you do some light CHERIreading. Remember that -f is your friend if you tend to wander away from your terminal during installations.
My systems are Ubuntu, I understand this works on FreeBSD and OSX, however I have not tried it and cannot speak to the installation process.
Be aware that when you re-start Qemu and rebuild, it will prompt you, but likely overwrite the CheriBSD disk image and all the changes you might have made to it. That’s intentional, but may not suit your development style. Pay careful attention to the Cheribuild documentation!
I did not know about it when I was setting up, but there is a --force option to automatically suppress the y/n prompts. I recommend you try it out for installation. If you run into issues, please file a bug. We’d appreciate it.
Output from my terminal:
$ sudo apt-get install libtool pkg-config clang bison cmake ninja-build samba flex texinfo libarchive-dev libglib2.0-dev libpixman-1-dev libbz2-dev libarchive-tools libexpat1-dev
$ mkdir ~/cheri
$ git clone https://github.com/CTSRD-CHERI/cheribuild ~/cheri/cheribuild
Well, no not really. Your best bet is to run the Qemu setup in a VM.
Cheribuild can successfully build and run the riscv64-purecap and fvp-morello-purecap targets on Ubuntu 20.04 running on WSL2 (tested with Windows 10 Pro build 19042.985 and the provided Linux 5.4 kernel in May 2021). For the most part, getting started works as it would on any other Ubuntu 20.04 system. However, you may encounter some issues as you learn and experiment. For example, some tests for the modified qemu may not run properly because WSL2 does not yet fully support nested virtualization out of the box.
It's possible Cygwin or WSL1 might work too, maybe, but no one has tried it. This could be an interesting area to contribute if you have experience with those tools!
CHERI-RISC-V (what you should use):
$ ~/cheri/cheribuild/cheribuild.py qemu llvm cheribsd-riscv64-purecap disk-image-riscv64-purecap run-riscv64-purecap
CHERI-MIPS (what I used):
$ ~/cheri/cheribuild/cheribuild.py qemu llvm cheribsd-mips64-purecap disk-image-mips64-purecap run-mips64-purecap
(Assuming you have installed Cheribuild from the above section, this will build the development environment and then start the MIPS version, not the RISC-V one)
Default account is root with no password. I’m told this is a tradition from the FreeBSD live boot CD, although I’ve never seen one of these mythical things in person. 😀 I generally run uname -mrs after starting CheriBSD for a sanity check, though that’s just me.
By the way, the cleanest way to exit the whole thing is to run ‘shutdown -p now’ at the CheriBSD terminal prompt. Be advised that it may take a surprisingly long amount of time to shutdown and exit. That’s normal.
If you don’t care about ruining the disk image or keeping your install stable, i.e. you’re going to rebuild it anyway, “Ctrl-A x” will kill QEMU. I generally don’t do this, however most of the team does.
Yay! Congratulations! Do a happy dance, then poke around a bit and explore!
Cheribuild to the rescue! There’s a --test argument to run the existing tests. It’s not as extensive as it could be, but it does exist. For new work, there is still a lot of manual testing by the developer and the reviewer. At this time, there is no formal QA verification, although Alex has been working hard to improve the CI (Continuous Integration) and run Jenkins on master.
For CHERI-RISC-V, use:
$ ~/cheri/cheribuild/cheribuild.py qemu llvm cheribsd-riscv64-purecap disk-image-riscv64-purecap run-riscv64-purecap --test
For CHERI-MIPS, use:
$ ~/cheri/cheribuild/cheribuild.py qemu llvm cheribsd-mips64-purecap disk-image-mips64-purecap run-mips64-purecap --test
New stuff lands very frequently, so you may find a clean master breaks. Don’t panic. We’re getting better, and most of the main repositories stage changes through a dev branch, though it still happens. If you run into issues with new changes, Speak up! Please!
Related to testing, Alfredo has syzkaller, a kernel fuzzer, running regularly. The ISA (Instruction Set Architecture) and other parts have testing and verification procedures of their own, however my focus is primarily on CheriBSD.
There are 3 flavors of GDB to consider, based on whether the debuggee and debugger are running inside the CHERI stack or outside it (on the host or another computer altogether):
| Debuggee | Debugger | Purpose |
|---|---|---|
| inside | inside | cross-compiled, capability-aware gdb running under CheriBSD to debug a CHERI userspace program |
| inside | outside | Host-compiled, capability-aware gdb running on the host; especially useful for debugging the CheriBSD kernel using the debug server provided by QEMU |
| outside | outside | The standard debugging case; useful for debugging, e.g., CHERI Qemu itself. |
The outside-outside case is the least used and most likely not one you’ll reach for often. For the CHERI cases, you’ll want to check out the latest debugging over at Building GDB.
For working in the CheriBSD kernel, remote gdb debugging is the way to go. You’ll be looking for the extra flag --wait-for-debugger, wait on cheribuild, then follow the directions it prints for the type of debugging you’d like to do. --wait-for-debugger is most useful for kernel debugging rather than userland debugging.
For me, this tends to be fragile, and you’ll need to be very close attention to the directions that cheribuild spits out for attaching the debugger to the kernel or userland. Very, very close attention. I personally use two terminals side by side when setting it up.
For working on CheriBSD, in userspace, gdb is present and built by default with python cheribuild.py -d run-<architecture> (at least for MIPS and RISC-V). Check the Cheribuild documentation for the latest details. Ultimately, you’ll be interested in running gdb-run.sh, which will start a program in GDB and print a backtrace once it stops, which can save a lot of your sanity.
The CHERI-RISC-V kernel debugger invocation is:
$ ./cheri/cheribuild/cheribuild.py -d gdb-native disk-image-riscv64-purecap run-riscv64-purecap --wait-for-debugger
The CHERI-MIPS (kernel) debugger invocation is:
$ ./cheri/cheribuild/cheribuild.py -d gdb-native disk-image-mips64-purecap run-mips64-purecap --wait-for-debugger
The first version of this appeared on Allison Naaktgeboren's page.