search

solana-labs / rbpf

Rust virtual machine and JIT compiler for eBPF programs
Apache License 2.0
288 stars 173 forks source link

readme

solana_rbpf

Rust (user-space) virtual machine for eBPF

Build Status Crates.io

Description

This is a fork of RBPF by Quentin Monnet.

This crate contains a virtual machine for eBPF program execution. BPF, as in Berkeley Packet Filter, is an assembly-like language initially developed for BSD systems, in order to filter packets in the kernel with tools such as tcpdump so as to avoid useless copies to user-space. It was ported to Linux, where it evolved into eBPF (extended BPF), a faster version with more features. While BPF programs are originally intended to run in the kernel, the virtual machine of this crate enables running it in user-space applications; it contains an interpreter, an x86_64 JIT-compiler for eBPF programs, as well as an assembler, disassembler and verifier.

The crate is supposed to compile and run on Linux, MacOS X, and Windows, although the JIT-compiler does not work with Windows at this time.

Link to the crate

This crate is available from crates.io, so it should work out of the box by adding it as a dependency in your Cargo.toml file:

[dependencies]
solana_rbpf = "0.8.2"

You can also use the development version from this GitHub repository. This should be as simple as putting this inside your Cargo.toml:

[dependencies]
solana_rbpf = { git = "https://github.com/solana-labs/rbpf", branch = "main" }

Of course, if you prefer, you can clone it locally, possibly hack the crate, and then indicate the path of your local version in Cargo.toml:

[dependencies]
solana_rbpf = { path = "path/to/solana_rbpf" }

Then indicate in your source code that you want to use the crate:

extern crate solana_rbpf;

API

The API is pretty well documented inside the source code. You should also be able to access an online version of the documentation from here, automatically generated from the crates.io version (may not be up-to-date with master branch). Examples, unit tests and performance benchmarks should also prove helpful.

Here are the steps to follow to run an eBPF program with rbpf:

  1. Create the config and a loader built-in program, add some functions.
  2. Create an executable, either from the bytecode or an ELF.
  3. If you want a JIT-compiled program, compile it.
  4. Create a memory mapping, consisting of multiple memory regions.
  5. Create a context object which will also acts as instruction meter.
  6. Create a virtual machine using all of the previous steps.
  7. Execute your program: Either run the interpreter or call the JIT-compiled function.

Developer

Dependencies

Build and test instructions

License

Following the effort of the Rust language project itself in order to ease integration with other projects, the rbpf crate is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.