• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# vmbase
2
3This directory contains a Rust crate and static library which can be used to write `no_std` Rust
4binaries to run in an aarch64 VM under crosvm (via the VirtualizationService), such as for pVM
5firmware, a VM bootloader or kernel.
6
7In particular it provides:
8
9- An [entry point](entry.S) that initializes the MMU with a hard-coded identity mapping, enables the
10  cache, prepares the image and allocates a stack.
11- An [exception vector](exceptions.S) to call your exception handlers.
12- A UART driver and `println!` macro for early console logging.
13- Functions to shutdown or reboot the VM.
14
15Libraries are also available for heap allocation, page table manipulation and PSCI calls.
16
17## Usage
18
19The [example](example/) subdirectory contains an example of how to use it for a VM bootloader.
20
21### Build file
22
23Start by creating a `rust_ffi_static` rule containing your main module:
24
25```soong
26rust_ffi_static {
27    name: "libvmbase_example",
28    defaults: ["vmbase_ffi_defaults"],
29    crate_name: "vmbase_example",
30    srcs: ["src/main.rs"],
31    rustlibs: [
32        "libvmbase",
33    ],
34}
35```
36
37`vmbase_ffi_defaults`, among other things, specifies the stdlibs including the `compiler_builtins`
38and `core` crate. These must be explicitly specified as we don't want the normal set of libraries
39used for a C++ binary intended to run in Android userspace.
40
41### Entry point
42
43Your main module needs to specify a couple of special attributes:
44
45```rust
46#![no_main]
47#![no_std]
48```
49
50This tells rustc that it doesn't depend on `std`, and won't have the usual `main` function as an
51entry point. Instead, `vmbase` provides a macro to specify your main function:
52
53```rust
54use vmbase::{logger, main};
55use log::{info, LevelFilter};
56
57main!(main);
58
59pub fn main(arg0: u64, arg1: u64, arg2: u64, arg3: u64) {
60    logger::init(LevelFilter::Info).unwrap();
61    info!("Hello world");
62}
63```
64
65vmbase adds a wrapper around your main function to initialize the console driver first (with the
66UART at base address `0x3f8`, the first UART allocated by crosvm), and make a PSCI `SYSTEM_OFF` call
67to shutdown the VM if your main function ever returns.
68
69You can also shutdown the VM by calling `vmbase::power::shutdown` or 'reboot' by calling
70`vmbase::power::reboot`. Either will cause crosvm to terminate the VM, but by convention we use
71shutdown to indicate that the VM has finished cleanly, and reboot to indicate an error condition.
72
73### Exception handlers
74
75You must provide handlers for each of the 8 types of exceptions which can occur on aarch64. These
76must use the C ABI, and have the expected names. For example, to log sync exceptions and reboot:
77
78```rust
79use vmbase::power::reboot;
80
81extern "C" fn sync_exception_current() {
82    let mut esr: u64;
83    unsafe {
84        asm!("mrs {esr}, esr_el1", esr = out(reg) esr);
85    }
86    panic!("sync_exception_current, esr={:#08x}", esr);
87}
88```
89
90The `println!` macro shouldn't be used in exception handlers, because it relies on a global instance
91of the UART driver which might be locked when the exception happens, which would result in deadlock.
92
93See [example/src/exceptions.rs](examples/src/exceptions.rs) for a complete example.
94
95### Linker script and initial idmap
96
97The [entry point](entry.S) code expects to be provided a hardcoded identity-mapped page table to use
98initially. This must contain at least the region where the image itself is loaded, some writable
99DRAM to use for the `.bss` and `.data` sections and stack, and a device mapping for the UART MMIO
100region. See the [example/idmap.S](example/idmap.S) for an example of how this can be constructed.
101
102The addresses in the pagetable must map the addresses the image is linked at, as we don't support
103relocation. This can be achieved with a linker script, like the one in
104[example/image.ld](example/image.ld). The key part is the regions provided to be used for the image
105and writable data:
106
107```ld
108MEMORY
109{
110	image		: ORIGIN = 0x80200000, LENGTH = 2M
111	writable_data	: ORIGIN = 0x80400000, LENGTH = 2M
112}
113```
114
115### Building a binary
116
117To link your Rust code together with the entry point code and idmap into a static binary, you need
118to use a `cc_binary` rule:
119
120```soong
121cc_binary {
122    name: "vmbase_example",
123    defaults: ["vmbase_elf_defaults"],
124    srcs: [
125        "idmap.S",
126    ],
127    static_libs: [
128        "libvmbase_example",
129    ],
130    linker_scripts: [
131        "image.ld",
132        ":vmbase_sections",
133    ],
134}
135```
136
137This takes your Rust library (`libvmbase_example`), the vmbase library entry point and exception
138vector (`libvmbase_entry`) and your initial idmap (`idmap.S`) and builds a static binary with your
139linker script (`image.ld`) and the one provided by vmbase ([`sections.ld`](sections.ld)). This is an
140ELF binary, but to run it as a VM bootloader you need to `objcopy` it to a raw binary image instead,
141which you can do with a `raw_binary` rule:
142
143```soong
144raw_binary {
145    name: "vmbase_example_bin",
146    stem: "vmbase_example.bin",
147    src: ":vmbase_example",
148    enabled: false,
149    target: {
150        android_arm64: {
151            enabled: true,
152        },
153    },
154}
155```
156
157The resulting binary can then be used to start a VM by passing it as the bootloader in a
158`VirtualMachineRawConfig`.
159