3 releases (breaking)
0.3.0 | Nov 15, 2023 |
---|---|
0.2.0 | Nov 1, 2021 |
0.1.0 | Aug 5, 2021 |
#370 in Unix APIs
16,608 downloads per month
Used in 2 crates
58KB
937 lines
vm-fdt
The vm-fdt crate provides the ability to write Flattened Devicetree blobs as defined in the Devicetree specification.
In projects such as Crosvm and Firecracker the device tree is used to specify the virtual machine topology (memory, vcpu, caches, interrupts, and others) when booting the OS.
Design
In vm-fdt we define and work with the following primitives:
- FDT writer (
FdtWriter
), - nodes (
FdtWriterNode
), and - properties (defined as key-value pairs).
An FDT has one or multiple nodes, and each node can optionally have properties and child nodes, creating a tree structure.
The FdtWriter
structure provides an interface suitable
for dynamically generating a Devicetree blob at runtime. The supported
operations are:
- Creating a node. This is done by calling
begin_node
on theFdtWriter
. The call returns an object of typeFdtWriterNode
on which we can set properties (using theproperty_*
functions as defined below), or add child nodes (via nested calls tobegin_node
). Properties for the node can only be added before creating child nodes (as defined in the specification). Each node must end with a call to theend_node
function. - Create properties. Properties are key-value pairs, where the key is a string, and the value is a raw bytes array. To make it easier to use, such that the caller of the FDT interface does not need to create a raw byte array, we define wrappers over common property types as follows:
property_null
(an empty property)property_string
property_string_list
property_u32
property_u64
property_array_u32
property_array_u64
property
(raw byte array)
Threat Model
Input: The caller of the vm-fdt public interface is trusted.
Output: The content of the FDT blob resides in memory, and it’s trusted. The
memory allocated by this crate is directly proportional with the number of
nodes and properties defined by the user (through the property*
and
begin_node
functions).
#NR | Threat | Mitigation |
---|---|---|
1 | Due to a programming error the FDT code causes large memory allocations. | The operator of the vm-fdt interface is trusted, and the memory allocations are directly proportional to the number of calls to the public FDT interface. At the vm-fdt level, the maximum size allowed for the blob is 4.3 GB. This is enforced by checking that the length of the data blob fits in an u32, and the maximum value of an u32 is 4294967295 (~4.3 GB). The caller of the vm-fdt interface can check the size of the FDT blob upon calling the finish function. |
2 | Passing large arrays of memory reservations when initializing the FdtWriter leads to undefined behavior. | The length of the memory reservations is checked. All subsequent operations based on input are checked for overflows. |
3 | Passing overlapping memory reservations when initializing the FdtWriter leads to undefined behavior when loading the blob in guest memory | The FDT specification explicitly defines that the memory reservation entries MUST not overlap. This is enforced by the FdtWriter, and checked in the unit tests. |
Usage
The following code is creating an FDT blob with a root node that has 3 properties ("compatible", "#address-cells", and "#size-cells"), and contains 2 child nodes:
- "chosen", which has 2 properties ("linux,pci-probe-only" and "bootargs").
- "memory", which has one property ("device_type")
Below is a graphic representation of the FDT.
use vm_fdt::{FdtWriter, Error};
fn create_fdt() -> Result<Vec<u8>, Error> {
let mut fdt = FdtWriter::new()?;
let root_node = fdt.begin_node("root")?;
fdt.property_string("compatible", "linux,dummy-virt")?;
fdt.property_u32("#address-cells", 0x2)?;
fdt.property_u32("#size-cells", 0x2)?;
let chosen_node = fdt.begin_node("chosen")?;
fdt.property_u32("linux,pci-probe-only", 1)?;
fdt.property_string("bootargs", "panic=-1 console=hvc0")?;
fdt.end_node(chosen_node)?;
let memory_node = fdt.begin_node("memory")?;
fdt.property_string("device_type", "memory")?;
fdt.end_node(memory_node)?;
fdt.end_node(root_node)?;
fdt.finish()
}
Features
This crate defines a development feature: long_running_test
. This feature
SHOULD NOT be used in production as it might enable functionality that is safe
only for development use cases.
License
This project is licensed under either of
- Apache License, Version 2.0
- BSD-3-Clause License
Dependencies
~0–450KB