Struct OptionsBuilder

Source

pub struct OptionsBuilder { /* private fields */ }

Expand description

Builder for Options.

Implementations§

Source §

impl OptionsBuilder

Source

pub fn new() -> Self

Create a builder initialized with libriscv defaults.

Source

pub fn max_memory(self, bytes: u64) -> Self

Examples found in repository ?

examples/basic.rs (line 12)

3fn main() -> Result<(), Box<dyn std::error::Error>> {
4    let args: Vec<String> = std::env::args().collect();
5    if args.len() < 2 {
6        eprintln!("Usage: {} [program file] [arguments ...]", args[0]);
7        std::process::exit(1);
8    }
9
10    let elf = std::fs::read(&args[1])?;
11    let options = Options::builder()
12        .max_memory(256 * 1024 * 1024)
13        .args(args[1..].iter())
14        .build()?;
15
16    let registry = SyscallRegistry::empty();
17    let mut machine = Machine::new(elf, options, &registry)?;
18    machine.run(u64::MAX)?;
19    println!("Program exited with status: {}", machine.return_value());
20    Ok(())
21}

More examples

Hide additional examples

examples/vmcall.rs (line 19)

10fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
11    let args: Vec<String> = std::env::args().collect();
12    if args.len() < 2 {
13        eprintln!("Usage: {} [program file] [arguments ...]", args[0]);
14        std::process::exit(1);
15    }
16
17    let elf = std::fs::read(&args[1])?;
18    let options = Options::builder()
19        .max_memory(64 * 1024 * 1024)
20        .args(args[1..].iter())
21        .build()?;
22
23    let registry = SyscallRegistry::empty();
24    let mut machine = Machine::new(elf, options, &registry)?;
25    machine.run(32_000_000)?;
26
27    if let Some(addr) = machine.address_of("my_function")? {
28        machine.setup_vmcall(addr)?;
29        let msg = b"Hello Sandboxed World!\0";
30        let str_addr = {
31            let mut regs = machine.registers()?;
32            reserve_stack(&mut regs, msg.len())?
33        };
34        machine.copy_to_guest(str_addr, msg)?;
35        {
36            let mut regs = machine.registers()?;
37            regs.set_x(10, str_addr)?;
38        }
39        machine.run(u64::MAX)?;
40    } else {
41        eprintln!("Symbol my_function not found");
42    }
43
44    println!("Program exited with status: {}", machine.return_value());
45    Ok(())
46}

Source

pub fn stack_size(self, bytes: u32) -> Self

Source

pub fn strict_sandbox(self, strict: bool) -> Self

Source

pub fn args<I, S>(self, args: I) -> Self
where I: IntoIterator<Item = S>, S: AsRef<str>,

Examples found in repository ?

examples/basic.rs (line 13)

3fn main() -> Result<(), Box<dyn std::error::Error>> {
4    let args: Vec<String> = std::env::args().collect();
5    if args.len() < 2 {
6        eprintln!("Usage: {} [program file] [arguments ...]", args[0]);
7        std::process::exit(1);
8    }
9
10    let elf = std::fs::read(&args[1])?;
11    let options = Options::builder()
12        .max_memory(256 * 1024 * 1024)
13        .args(args[1..].iter())
14        .build()?;
15
16    let registry = SyscallRegistry::empty();
17    let mut machine = Machine::new(elf, options, &registry)?;
18    machine.run(u64::MAX)?;
19    println!("Program exited with status: {}", machine.return_value());
20    Ok(())
21}

More examples

Hide additional examples

examples/vmcall.rs (line 20)

10fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
11    let args: Vec<String> = std::env::args().collect();
12    if args.len() < 2 {
13        eprintln!("Usage: {} [program file] [arguments ...]", args[0]);
14        std::process::exit(1);
15    }
16
17    let elf = std::fs::read(&args[1])?;
18    let options = Options::builder()
19        .max_memory(64 * 1024 * 1024)
20        .args(args[1..].iter())
21        .build()?;
22
23    let registry = SyscallRegistry::empty();
24    let mut machine = Machine::new(elf, options, &registry)?;
25    machine.run(32_000_000)?;
26
27    if let Some(addr) = machine.address_of("my_function")? {
28        machine.setup_vmcall(addr)?;
29        let msg = b"Hello Sandboxed World!\0";
30        let str_addr = {
31            let mut regs = machine.registers()?;
32            reserve_stack(&mut regs, msg.len())?
33        };
34        machine.copy_to_guest(str_addr, msg)?;
35        {
36            let mut regs = machine.registers()?;
37            regs.set_x(10, str_addr)?;
38        }
39        machine.run(u64::MAX)?;
40    } else {
41        eprintln!("Symbol my_function not found");
42    }
43
44    println!("Program exited with status: {}", machine.return_value());
45    Ok(())
46}

examples/advanced_syscalls.rs (line 163)

149fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
150    let args: Vec<String> = std::env::args().collect();
151    if args.len() < 2 {
152        eprintln!("Usage: {} [program file]", args[0]);
153        std::process::exit(1);
154    }
155
156    let elf = std::fs::read(&args[1])?;
157
158    let registry = host_syscalls::registry()?;
159
160    let options = Options::builder()
161        .stdout_handler(stdout_callback_handler())
162        .error_handler(error_callback_handler())
163        .args(["program"])
164        .build()?;
165
166    let mut machine = Machine::new(elf, options, &registry)?;
167    machine.run(u64::MAX)?;
168
169    let addr = HOST_FN_ADDR.load(Ordering::Relaxed);
170    if addr != 0 {
171        machine.setup_vmcall(addr)?;
172        let msg = b"Hello from a callback function!\0";
173        let str_addr = {
174            let mut regs = machine.registers()?;
175            reserve_stack(&mut regs, msg.len())?
176        };
177        machine.copy_to_guest(str_addr, msg)?;
178        {
179            let mut regs = machine.registers()?;
180            regs.set_x(10, str_addr)?;
181        }
182        machine.run(u64::MAX)?;
183    } else {
184        eprintln!("Host function 502 was not called");
185    }
186
187    println!("Done");
188    Ok(())
189}

Source

pub fn clear_args(self) -> Self

Source

pub fn error_handler(self, handler: ErrorHandler) -> Self

Examples found in repository ?

examples/advanced_syscalls.rs (line 162)

149fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
150    let args: Vec<String> = std::env::args().collect();
151    if args.len() < 2 {
152        eprintln!("Usage: {} [program file]", args[0]);
153        std::process::exit(1);
154    }
155
156    let elf = std::fs::read(&args[1])?;
157
158    let registry = host_syscalls::registry()?;
159
160    let options = Options::builder()
161        .stdout_handler(stdout_callback_handler())
162        .error_handler(error_callback_handler())
163        .args(["program"])
164        .build()?;
165
166    let mut machine = Machine::new(elf, options, &registry)?;
167    machine.run(u64::MAX)?;
168
169    let addr = HOST_FN_ADDR.load(Ordering::Relaxed);
170    if addr != 0 {
171        machine.setup_vmcall(addr)?;
172        let msg = b"Hello from a callback function!\0";
173        let str_addr = {
174            let mut regs = machine.registers()?;
175            reserve_stack(&mut regs, msg.len())?
176        };
177        machine.copy_to_guest(str_addr, msg)?;
178        {
179            let mut regs = machine.registers()?;
180            regs.set_x(10, str_addr)?;
181        }
182        machine.run(u64::MAX)?;
183    } else {
184        eprintln!("Host function 502 was not called");
185    }
186
187    println!("Done");
188    Ok(())
189}

Source

pub fn stdout_handler(self, handler: StdoutHandler) -> Self

Examples found in repository ?

examples/advanced_syscalls.rs (line 161)

149fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
150    let args: Vec<String> = std::env::args().collect();
151    if args.len() < 2 {
152        eprintln!("Usage: {} [program file]", args[0]);
153        std::process::exit(1);
154    }
155
156    let elf = std::fs::read(&args[1])?;
157
158    let registry = host_syscalls::registry()?;
159
160    let options = Options::builder()
161        .stdout_handler(stdout_callback_handler())
162        .error_handler(error_callback_handler())
163        .args(["program"])
164        .build()?;
165
166    let mut machine = Machine::new(elf, options, &registry)?;
167    machine.run(u64::MAX)?;
168
169    let addr = HOST_FN_ADDR.load(Ordering::Relaxed);
170    if addr != 0 {
171        machine.setup_vmcall(addr)?;
172        let msg = b"Hello from a callback function!\0";
173        let str_addr = {
174            let mut regs = machine.registers()?;
175            reserve_stack(&mut regs, msg.len())?
176        };
177        machine.copy_to_guest(str_addr, msg)?;
178        {
179            let mut regs = machine.registers()?;
180            regs.set_x(10, str_addr)?;
181        }
182        machine.run(u64::MAX)?;
183    } else {
184        eprintln!("Host function 502 was not called");
185    }
186
187    println!("Done");
188    Ok(())
189}

Source

pub fn opaque(self, opaque: *mut c_void) -> Self

Source

pub fn build(self) -> Result<Options>

Examples found in repository ?

examples/basic.rs (line 14)

3fn main() -> Result<(), Box<dyn std::error::Error>> {
4    let args: Vec<String> = std::env::args().collect();
5    if args.len() < 2 {
6        eprintln!("Usage: {} [program file] [arguments ...]", args[0]);
7        std::process::exit(1);
8    }
9
10    let elf = std::fs::read(&args[1])?;
11    let options = Options::builder()
12        .max_memory(256 * 1024 * 1024)
13        .args(args[1..].iter())
14        .build()?;
15
16    let registry = SyscallRegistry::empty();
17    let mut machine = Machine::new(elf, options, &registry)?;
18    machine.run(u64::MAX)?;
19    println!("Program exited with status: {}", machine.return_value());
20    Ok(())
21}

More examples

Hide additional examples

examples/vmcall.rs (line 21)

10fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
11    let args: Vec<String> = std::env::args().collect();
12    if args.len() < 2 {
13        eprintln!("Usage: {} [program file] [arguments ...]", args[0]);
14        std::process::exit(1);
15    }
16
17    let elf = std::fs::read(&args[1])?;
18    let options = Options::builder()
19        .max_memory(64 * 1024 * 1024)
20        .args(args[1..].iter())
21        .build()?;
22
23    let registry = SyscallRegistry::empty();
24    let mut machine = Machine::new(elf, options, &registry)?;
25    machine.run(32_000_000)?;
26
27    if let Some(addr) = machine.address_of("my_function")? {
28        machine.setup_vmcall(addr)?;
29        let msg = b"Hello Sandboxed World!\0";
30        let str_addr = {
31            let mut regs = machine.registers()?;
32            reserve_stack(&mut regs, msg.len())?
33        };
34        machine.copy_to_guest(str_addr, msg)?;
35        {
36            let mut regs = machine.registers()?;
37            regs.set_x(10, str_addr)?;
38        }
39        machine.run(u64::MAX)?;
40    } else {
41        eprintln!("Symbol my_function not found");
42    }
43
44    println!("Program exited with status: {}", machine.return_value());
45    Ok(())
46}

examples/advanced_syscalls.rs (line 164)

149fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
150    let args: Vec<String> = std::env::args().collect();
151    if args.len() < 2 {
152        eprintln!("Usage: {} [program file]", args[0]);
153        std::process::exit(1);
154    }
155
156    let elf = std::fs::read(&args[1])?;
157
158    let registry = host_syscalls::registry()?;
159
160    let options = Options::builder()
161        .stdout_handler(stdout_callback_handler())
162        .error_handler(error_callback_handler())
163        .args(["program"])
164        .build()?;
165
166    let mut machine = Machine::new(elf, options, &registry)?;
167    machine.run(u64::MAX)?;
168
169    let addr = HOST_FN_ADDR.load(Ordering::Relaxed);
170    if addr != 0 {
171        machine.setup_vmcall(addr)?;
172        let msg = b"Hello from a callback function!\0";
173        let str_addr = {
174            let mut regs = machine.registers()?;
175            reserve_stack(&mut regs, msg.len())?
176        };
177        machine.copy_to_guest(str_addr, msg)?;
178        {
179            let mut regs = machine.registers()?;
180            regs.set_x(10, str_addr)?;
181        }
182        machine.run(u64::MAX)?;
183    } else {
184        eprintln!("Host function 502 was not called");
185    }
186
187    println!("Done");
188    Ok(())
189}