Add further detail about kernel configurations and how to select a ke…

…rnel.

src/features/kernel.md

@@ -8,3 +8,131 @@ The CheriBSD kernel can be compiled either as hybrid or pure-capability code:
   memory protection internally in the kernel, protecting against memory-safety
   vulnerabilities in components such as the network stack and system-call
   layer.
+
+A number of precompiled kernels are provided in the CheriBSD release, enabling
+or disabling debugging and revocation in combination with hybrid or
+pure-capability compilations.
+In general, we recommend that performance benchmarking be done only with
+`NODEBUG` kernels; see [Benchmarking guidance](../benchmarking/README.md) for
+further details.
+
+## Precompiled kernels in CheriBSD 23.11
+
+CheriBSD 23.11 ships with a number of precompiled kernels that enable and
+disable various relevant kernel configuration options.
+Kernel configuration files themselves may be found in `sys/amd64/conf` in the
+CheriBSD source tree, and will have names such as `GENERIC-MORELLO`.
+The following kernel features may be selected from amongst the precompiled
+kernels:
+
+| Option name   | Description |
+|---------------|-------------|
+| `PURECAP`     | Compiled with internal memory safety |
+| `NODEBUG`     | Compiled without kernel debugging features |
+| `NOCAPREVOKE` | Compiled without userspace heap temporal safety |
+
+Kernel directory names are in the form `/boot/kernel*`; the default kernel is
+named `/boot/kernel`.
+
+```
+# cd /boot
+# ls -d kernel*
+kernel
+kernel.GENERIC-MORELLO-NOCAPREVOKE
+kernel.GENERIC-MORELLO-NOCAPREVOKE-NODEBUG
+kernel.GENERIC-MORELLO-NODEBUG
+kernel.GENERIC-MORELLO-PURECAP
+kernel.GENERIC-MORELLO-PURECAP-NOCAPREVOKE
+kernel.GENERIC-MORELLO-PURECAP-NOCAPREVOKE-NODEBUG
+kernel.GENERIC-MORELLO-PURECAP-NODEBUG
+```
+
+In CheriBSD 23.11, the default kernel uses the `GENERIC-MORELLO` kernel
+configuration, and is a hybrid kernel with debugging and userspace heap
+temporal safety enabled.
+This is expected to change to a pure-capability kernel in future CheriBSD
+releases.
+
+## Identifying the currently booted kernel
+
+The `uname(1)` command prints information on the kernel configuration.
+The following command-line options may be of use:
+
+| Option name | Description                         |
+|-------------|-------------------------------------|
+| `-a`        | Print numerous details              |
+| `-i`        | Print the kernel configuration name |
+
+In CheriBSD 23.11, the default kernel is `GENERIC-MORELLO`, a hybrid kernel
+that includes a number of debugging features, and is unsuitable for
+benchmarking.
+
+```
+# uname -i
+GENERIC-MORELLO
+```
+
+## Selecting another kernel using loader.conf
+
+You can set the kernel to boot via `/boot/loader.conf` using the variable
+`kernel`.
+This is set to the name of the kernel directory under `/boot`; for example,
+the default is:
+
+```
+kernel="kernel"
+```
+
+You can persistently set the system to boot with a pure-capability kernel by
+setting `kernel` as follows in `/boot/loader.conf`:
+
+```
+kernel="kernel.GENERIC-MORELLO-PURECAP"
+```
+
+After a reboot, `uname(1)` should then report that this is the kernel in use:
+
+```
+# uname -i
+GENERIC-MORELLO-PURECAP
+```
+
+## Selecting another kernel from the boot loader
+
+It is also possible to interactively select a different kernel from the boot
+loader on the video or serial console:
+
+```
+    _____ _               _ ____   _____ _____
+   / ____| |             (_)  _ \ / ____|  __ \
+  | |    | |__   ___ _ __ _| |_) | (___ | |  | |
+  | |    | '_ \ / _ \ '__| |  _ < \___ \| |  | |
+  | |____| | | |  __/ |  | | |_) |____) | |__| |
+   \_____|_| |_|\___|_|  |_|____/|_____/|_____/
+                                                 ```                        `
+                                                s` `.....---.......--.```   -/
+ /---------- Welcome to CheriBSD ----------\    +o   .--`         /y:`      +.
+ |                                         |     yo`:.            :o      `+-
+ |  1. Boot Multi user [Enter]             |      y/               -/`   -o/
+ |  2. Boot Single user                    |     .-                  ::/sy+:.
+ |  3. Escape to loader prompt             |     /                     `--  /
+ |  4. Reboot                              |    `:                          :`
+ |  5. Cons: Serial                        |    `:                          :`
+ |                                         |     /                          /
+ |  Options:                               |     .-                        -.
+ |  6. Kernel: kernel (2 of 8)             |      --                      -.
+ |  7. Boot Options                        |       `:`                  `:`
+ |                                         |         .--             `--.
+ |                                         |            .---.....----.
+ \-----------------------------------------/
+```
+
+This can be done in one of two ways:
+
+1. By rotating through kernel selections by using the `6` key.  Then press the
+   `1' key to proceed with the boot.
+
+2. By escaping to the loader prompt by hitting the `3` key, unloading the
+   default kernel using the `unload kernel command`, and then booting the
+   desired kernel using `boot /boot/kernel` (replacing the kernel name as
+   required).