Struct rbpf::EbpfVmMbuff

source ·

pub struct EbpfVmMbuff<'a> { /* private fields */ }

Expand description

A virtual machine to run eBPF program. This kind of VM is used for programs expecting to work on a metadata buffer containing pointers to packet data.

Examples

let prog = &[
    0x79, 0x11, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, // Load mem from mbuff at offset 8 into R1.
    0x69, 0x10, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, // ldhx r1[2], r0
    0x95, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00  // exit
];
let mem = &mut [
    0xaa, 0xbb, 0x11, 0x22, 0xcc, 0xdd
];

// Just for the example we create our metadata buffer from scratch, and we store the pointers
// to packet data start and end in it.
let mut mbuff = [0u8; 32];
unsafe {
    let mut data     = mbuff.as_ptr().offset(8)  as *mut u64;
    let mut data_end = mbuff.as_ptr().offset(24) as *mut u64;
    *data     = mem.as_ptr() as u64;
    *data_end = mem.as_ptr() as u64 + mem.len() as u64;
}

// Instantiate a VM.
let mut vm = rbpf::EbpfVmMbuff::new(Some(prog)).unwrap();

// Provide both a reference to the packet data, and to the metadata buffer.
let res = vm.execute_program(mem, &mut mbuff).unwrap();
assert_eq!(res, 0x2211);

Implementations

source

impl<'a> EbpfVmMbuff<'a>

source

pub fn new(prog: Option<&'a [u8]>) -> Result<EbpfVmMbuff<'a>, Error>

Create a new virtual machine instance, and load an eBPF program into that instance. When attempting to load the program, it passes through a simple verifier.

pub fn set_program(&mut self, prog: &'a [u8]) -> Result<(), Error>

Load a new eBPF program into the virtual machine instance.

pub fn set_verifier(&mut self, verifier: Verifier) -> Result<(), Error>

Set a new verifier function. The function should return an Error if the program should be rejected by the virtual machine. If a program has been loaded to the VM already, the verifier is immediately run.

Examples

use std::io::{Error, ErrorKind};
use rbpf::ebpf;

// Define a simple verifier function.
fn verifier(prog: &[u8]) -> Result<(), Error> {
    let last_insn = ebpf::get_insn(prog, (prog.len() / ebpf::INSN_SIZE) - 1);
    if last_insn.opc != ebpf::EXIT {
        return Err(Error::new(ErrorKind::Other,
                   "[Verifier] Error: program does not end with “EXIT” instruction"));
    }
    Ok(())
}

let prog1 = &[
    0xb7, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // mov r0, 0
    0x95, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00  // exit
];

// Instantiate a VM.
let mut vm = rbpf::EbpfVmMbuff::new(Some(prog1)).unwrap();
// Change the verifier.
vm.set_verifier(verifier).unwrap();

source

pub fn register_helper(&mut self, key: u32, function: Helper) -> Result<(), Error>

Register a built-in or user-defined helper function in order to use it later from within the eBPF program. The helper is registered into a hashmap, so the key can be any u32.

If using JIT-compiled eBPF programs, be sure to register all helpers before compiling the program. You should be able to change registered helpers after compiling, but not to add new ones (i.e. with new keys).

Examples

use rbpf::helpers;

// This program was compiled with clang, from a C program containing the following single
// instruction: `return bpf_trace_printk("foo %c %c %c\n", 10, 1, 2, 3);`
let prog = &[
    0x18, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // load 0 as u64 into r1 (That would be
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, // replaced by tc by the address of
                                                    // the format string, in the .map
                                                    // section of the ELF file).
    0xb7, 0x02, 0x00, 0x00, 0x0a, 0x00, 0x00, 0x00, // mov r2, 10
    0xb7, 0x03, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, // mov r3, 1
    0xb7, 0x04, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, // mov r4, 2
    0xb7, 0x05, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, // mov r5, 3
    0x85, 0x00, 0x00, 0x00, 0x06, 0x00, 0x00, 0x00, // call helper with key 6
    0x95, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00  // exit
];

// Instantiate a VM.
let mut vm = rbpf::EbpfVmMbuff::new(Some(prog)).unwrap();

// Register a helper.
// On running the program this helper will print the content of registers r3, r4 and r5 to
// standard output.
vm.register_helper(6, helpers::bpf_trace_printf).unwrap();

source

pub fn execute_program(&self, mem: &[u8], mbuff: &[u8]) -> Result<u64, Error>

Execute the program loaded, with the given packet data and metadata buffer.

If the program is made to be compatible with Linux kernel, it is expected to load the address of the beginning and of the end of the memory area used for packet data from the metadata buffer, at some appointed offsets. It is up to the user to ensure that these pointers are correctly stored in the buffer.

Examples

let prog = &[
    0x79, 0x11, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, // Load mem from mbuff into R1.
    0x69, 0x10, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, // ldhx r1[2], r0
    0x95, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00  // exit
];
let mem = &mut [
    0xaa, 0xbb, 0x11, 0x22, 0xcc, 0xdd
];

// Just for the example we create our metadata buffer from scratch, and we store the
// pointers to packet data start and end in it.
let mut mbuff = [0u8; 32];
unsafe {
    let mut data     = mbuff.as_ptr().offset(8)  as *mut u64;
    let mut data_end = mbuff.as_ptr().offset(24) as *mut u64;
    *data     = mem.as_ptr() as u64;
    *data_end = mem.as_ptr() as u64 + mem.len() as u64;
}

// Instantiate a VM.
let mut vm = rbpf::EbpfVmMbuff::new(Some(prog)).unwrap();

// Provide both a reference to the packet data, and to the metadata buffer.
let res = vm.execute_program(mem, &mut mbuff).unwrap();
assert_eq!(res, 0x2211);

source

pub fn jit_compile(&mut self) -> Result<(), Error>

JIT-compile the loaded program. No argument required for this.

If using helper functions, be sure to register them into the VM before calling this function.

Examples

let prog = &[
    0x79, 0x11, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, // Load mem from mbuff into R1.
    0x69, 0x10, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, // ldhx r1[2], r0
    0x95, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00  // exit
];

// Instantiate a VM.
let mut vm = rbpf::EbpfVmMbuff::new(Some(prog)).unwrap();

vm.jit_compile();

source

pub unsafe fn execute_program_jit(
 &self,
 mem: &mut [u8],
 mbuff: &'a mut [u8]
) -> Result<u64, Error>

Execute the previously JIT-compiled program, with the given packet data and metadata buffer, in a manner very similar to execute_program().

If the program is made to be compatible with Linux kernel, it is expected to load the address of the beginning and of the end of the memory area used for packet data from the metadata buffer, at some appointed offsets. It is up to the user to ensure that these pointers are correctly stored in the buffer.

Safety

WARNING: JIT-compiled assembly code is not safe, in particular there is no runtime check for memory access; so if the eBPF program attempts erroneous accesses, this may end very bad (program may segfault). It may be wise to check that the program works with the interpreter before running the JIT-compiled version of it.

For this reason the function should be called from within an unsafe bloc.

Examples

let prog = &[
    0x79, 0x11, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, // Load mem from mbuff into r1.
    0x69, 0x10, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00, // ldhx r1[2], r0
    0x95, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00  // exit
];
let mem = &mut [
    0xaa, 0xbb, 0x11, 0x22, 0xcc, 0xdd
];

// Just for the example we create our metadata buffer from scratch, and we store the
// pointers to packet data start and end in it.
let mut mbuff = [0u8; 32];
unsafe {
    let mut data     = mbuff.as_ptr().offset(8)  as *mut u64;
    let mut data_end = mbuff.as_ptr().offset(24) as *mut u64;
    *data     = mem.as_ptr() as u64;
    *data_end = mem.as_ptr() as u64 + mem.len() as u64;
}

// Instantiate a VM.
let mut vm = rbpf::EbpfVmMbuff::new(Some(prog)).unwrap();

vm.jit_compile();

// Provide both a reference to the packet data, and to the metadata buffer.
unsafe {
    let res = vm.execute_program_jit(mem, &mut mbuff).unwrap();
    assert_eq!(res, 0x2211);
}

Auto Trait Implementations

impl<'a> RefUnwindSafe for EbpfVmMbuff<'a>

impl<'a> Send for EbpfVmMbuff<'a>

impl<'a> Sync for EbpfVmMbuff<'a>

impl<'a> Unpin for EbpfVmMbuff<'a>

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source

impl<T, U> TryFrom for Twhere
U: Into<T>,

type Error = Infallible

The type returned in the event of a conversion error.

const: unstable · source

fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

Performs the conversion.

source

impl<T, U> TryInto for Twhere
U: TryFrom<T>,

type Error = >::Error

The type returned in the event of a conversion error.

const: unstable · source

fn try_into(self) -> Result<U, >::Error>

Performs the conversion.

Struct rbpf::EbpfVmMbuff

Implementations

impl<'a> EbpfVmMbuff<'a>

pub fn new(prog: Option<&'a [u8]>) -> Result<EbpfVmMbuff<'a>, Error>

pub fn set_program(&mut self, prog: &'a [u8]) -> Result<(), Error>

pub fn set_verifier(&mut self, verifier: Verifier) -> Result<(), Error>

pub fn register_helper(&mut self, key: u32, function: Helper) -> Result<(), Error>

pub fn execute_program(&self, mem: &[u8], mbuff: &[u8]) -> Result<u64, Error>

pub fn jit_compile(&mut self) -> Result<(), Error>

pub unsafe fn execute_program_jit( &self, mem: &mut [u8], mbuff: &'a mut [u8]) -> Result<u64, Error>

Auto Trait Implementations

impl<'a> RefUnwindSafe for EbpfVmMbuff<'a>

impl<'a> Send for EbpfVmMbuff<'a>

impl<'a> Sync for EbpfVmMbuff<'a>

impl<'a> Unpin for EbpfVmMbuff<'a>

impl<'a> UnwindSafe for EbpfVmMbuff<'a>

Blanket Implementations

impl<T> Any for Twhere T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for Twhere T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for Twhere T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> From<T> for T

fn from(t: T) -> T

impl<T, U> Into<U> for Twhere U: From<T>,

fn into(self) -> U

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

type Error = Infallible

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

pub unsafe fn execute_program_jit(
&self,
mem: &mut [u8],
mbuff: &'a mut [u8]
) -> Result<u64, Error>

impl<T> Any for Twhere
T: 'static + ?Sized,

impl<T> Borrow<T> for Twhere
T: ?Sized,

impl<T> BorrowMut<T> for Twhere
T: ?Sized,

impl<T, U> Into<U> for Twhere
U: From<T>,

impl<T, U> TryFrom<U> for Twhere
U: Into<T>,

impl<T, U> TryInto<U> for Twhere
U: TryFrom<T>,