Struct Cmdline

pub struct Cmdline { /* private fields */ }

A builder for a kernel command line string that validates the string as it’s being built.

Examples

let mut cl = Cmdline::new(100).unwrap();
cl.insert_str("foobar").unwrap();
assert_eq!(cl.as_cstring().unwrap().as_bytes_with_nul(), b"foobar\0");

Implementations

impl Cmdline

pub fn new(capacity: usize) -> Result<Cmdline>

Constructs an empty Cmdline with the given capacity, including the nul terminator.

Arguments

• capacity - Command line capacity. Must be greater than 0.

Examples

let cl = Cmdline::new(100).unwrap();

pub fn insert<T: AsRef<str>>(&mut self, key: T, val: T) -> Result<()>

Validates and inserts a key-value pair representing a boot arg of the command line.

Arguments

• key - Key to be inserted in the command line string.
• val - Value corresponding to key.

Examples

let mut cl = Cmdline::new(100).unwrap();
cl.insert("foo", "bar");
assert_eq!(cl.as_cstring().unwrap().as_bytes_with_nul(), b"foo=bar\0");

pub fn insert_multiple<T: AsRef<str>>( &mut self, key: T, vals: &[T], ) -> Result<()>

Validates and inserts a key-value1,…,valueN pair representing a boot arg of the command line.

Arguments

• key - Key to be inserted in the command line string.
• vals - Values corresponding to key.

Examples

let mut cl = Cmdline::new(100).unwrap();
cl.insert_multiple("foo", &["bar", "baz"]);
assert_eq!(
    cl.as_cstring().unwrap().as_bytes_with_nul(),
    b"foo=bar,baz\0"
);

pub fn insert_str<T: AsRef<str>>(&mut self, slug: T) -> Result<()>

Inserts a string in the boot args; returns an error if the string is invalid.

Arguments

• slug - String to be appended to the command line.

Examples

let mut cl = Cmdline::new(100).unwrap();
cl.insert_str("foobar").unwrap();
assert_eq!(cl.as_cstring().unwrap().as_bytes_with_nul(), b"foobar\0");

pub fn insert_init_args<T: AsRef<str>>(&mut self, slug: T) -> Result<()>

Inserts a string in the init args; returns an error if the string is invalid.

Arguments

• slug - String to be appended to the command line.

Examples

let mut cl = Cmdline::new(100).unwrap();
cl.insert_str("foo").unwrap();
cl.insert_init_args("bar").unwrap();
assert_eq!(
    cl.as_cstring().unwrap().as_bytes_with_nul(),
    b"foo -- bar\0"
);

pub fn as_cstring(&self) -> Result<CString>

Returns a C compatible representation of the command line The Linux kernel expects a null terminated cmdline according to the source: https://elixir.bootlin.com/linux/v5.10.139/source/kernel/params.c#L179

To get bytes of the cmdline to be written in guest’s memory (including the null terminator) from this representation, use CString::as_bytes_with_nul()

Examples

let mut cl = Cmdline::new(20).unwrap();
cl.insert_str("foo").unwrap();
cl.insert_init_args("bar").unwrap();
assert_eq!(
    cl.as_cstring().unwrap().as_bytes_with_nul(),
    b"foo -- bar\0"
);

pub fn add_virtio_mmio_device( &mut self, size: GuestUsize, baseaddr: GuestAddress, irq: u32, id: Option<u32>, ) -> Result<()>

Adds a virtio MMIO device to the kernel command line.

Multiple devices can be specified, with multiple virtio_mmio.device= options. This function must be called once per device. The function appends a string of the following format to the kernel command line: <size>@<baseaddr>:<irq>[:<id>]. For more details see the documentation (section virtio_mmio.device=).

Arguments

• size - Size of the slot the device occupies on the MMIO bus.
• baseaddr - Physical base address of the device.
• irq - Interrupt number to be used by the device.
• id - Optional platform device ID.

Examples

let mut cl = Cmdline::new(100).unwrap();
cl.add_virtio_mmio_device(1 << 12, GuestAddress(0x1000), 5, Some(42))
    .unwrap();
assert_eq!(
    cl.as_cstring().unwrap().as_bytes_with_nul(),
    b"virtio_mmio.device=4K@0x1000:5:42\0"
);

pub fn try_from(cmdline_raw: &str, capacity: usize) -> Result<Cmdline>

Tries to build a Cmdline with a given capacity from a str. The format of the str provided must be one of the following:

• <boot args> -- <init args>
• <boot args>

where <boot args> and <init args> can contain -- only if double quoted and <boot args> and <init args> contain at least one non-whitespace char each.

Providing a str not following these rules might end up in undefined behaviour of the resulting Cmdline.

Arguments

• cmdline_raw - Contains boot params and init params of the cmdline.
• capacity - Capacity of the cmdline.

Examples

let cl = Cmdline::try_from("foo -- bar", 100).unwrap();
assert_eq!(
    cl.as_cstring().unwrap().as_bytes_with_nul(),
    b"foo -- bar\0"
);

Trait Implementations

impl Clone for Cmdline

fn clone(&self) -> Cmdline

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cmdline

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Cmdline

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<Cmdline> for Vec<u8>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(cmdline: Cmdline) -> Result<Self, Self::Error>

Performs the conversion.