rte_bpf.h File Reference

#include <rte_common.h>
#include <rte_mbuf.h>
#include <rte_malloc.h>
#include <bpf_def.h>

Go to the source code of this file.

Data Structures
struct	rte_bpf_arg
struct	rte_bpf_xsym
struct	rte_bpf_prm_ex
struct	rte_bpf_prm
struct	rte_bpf_jit
struct	rte_bpf_jit_ex

Macros
#define	RTE_BPF_EXEC_FLAG_JIT   RTE_BIT64(0)
#define	RTE_BPF_EXEC_FLAG_MASK   RTE_BPF_EXEC_FLAG_JIT
#define	RTE_BPF_ARG_PTR_TYPE(x)   ((x) & RTE_BPF_ARG_PTR)

Enumerations
enum	rte_bpf_arg_type {   RTE_BPF_ARG_UNDEF , RTE_BPF_ARG_RAW , RTE_BPF_ARG_PTR = 0x10 , RTE_BPF_ARG_PTR_MBUF ,   RTE_BPF_ARG_RESERVED }
enum	rte_bpf_xtype { RTE_BPF_XTYPE_FUNC , RTE_BPF_XTYPE_VAR }
enum	rte_bpf_origin { RTE_BPF_ORIGIN_RAW , RTE_BPF_ORIGIN_CBPF , RTE_BPF_ORIGIN_ELF_FILE , RTE_BPF_ORIGIN_ELF_MEMORY }

Functions
void	rte_bpf_destroy (struct rte_bpf *bpf)
__rte_experimental struct rte_bpf *	rte_bpf_load_ex (const struct rte_bpf_prm_ex *prm) __rte_malloc __rte_dealloc(rte_bpf_destroy
__rte_experimental struct rte_bpf struct rte_bpf *	rte_bpf_load (const struct rte_bpf_prm *prm) __rte_malloc __rte_dealloc(rte_bpf_destroy
__rte_experimental struct rte_bpf struct rte_bpf struct rte_bpf *	rte_bpf_elf_load (const struct rte_bpf_prm *prm, const char *fname, const char *sname) __rte_malloc __rte_dealloc(rte_bpf_destroy
__rte_experimental struct rte_bpf struct rte_bpf struct rte_bpf uint64_t	rte_bpf_exec (const struct rte_bpf *bpf, void *ctx)
__rte_experimental uint64_t	rte_bpf_exec_ex (const struct rte_bpf *bpf, const struct rte_bpf_prog_ctx *ctx, uint64_t flags)
uint32_t	rte_bpf_exec_burst (const struct rte_bpf *bpf, void *ctx[], uint64_t rc[], uint32_t num)
__rte_experimental uint32_t	rte_bpf_exec_burst_ex (const struct rte_bpf *bpf, const struct rte_bpf_prog_ctx *ctx, uint64_t rc[], uint32_t num, uint64_t flags)
int	rte_bpf_get_jit (const struct rte_bpf *bpf, struct rte_bpf_jit *jit)
__rte_experimental int	rte_bpf_get_jit_ex (const struct rte_bpf *bpf, struct rte_bpf_jit_ex *jit)
__rte_experimental bool	rte_bpf_insn_is_wide (const struct ebpf_insn *ins)
__rte_experimental int	rte_bpf_format (char *buffer, size_t bufsz, const struct ebpf_insn *ins, uint32_t pc, uint32_t flags)
void	rte_bpf_dump (FILE *f, const struct ebpf_insn *buf, uint32_t len)
struct rte_bpf_prm *	rte_bpf_convert (const struct bpf_program *prog) __rte_malloc __rte_dealloc_free

Detailed Description

RTE BPF support.

librte_bpf provides a framework to load and execute eBPF bytecode inside user-space dpdk based applications. It supports basic set of features from eBPF spec (https://www.kernel.org/doc/Documentation/networking/filter.txt).

Definition in file rte_bpf.h.

Macro Definition Documentation

RTE_BPF_EXEC_FLAG_JIT

#define RTE_BPF_EXEC_FLAG_JIT   RTE_BIT64(0)

use JIT-compiled version

Definition at line 28 of file rte_bpf.h.

RTE_BPF_EXEC_FLAG_MASK

#define RTE_BPF_EXEC_FLAG_MASK   RTE_BPF_EXEC_FLAG_JIT

Mask with all supported RTE_BPF_EXEC_FLAG_* flags set.

Definition at line 31 of file rte_bpf.h.

RTE_BPF_ARG_PTR_TYPE

#define RTE_BPF_ARG_PTR_TYPE

(

x

)

((x) & RTE_BPF_ARG_PTR)

determine is argument a pointer

Definition at line 78 of file rte_bpf.h.

Enumeration Type Documentation

rte_bpf_arg_type

enum rte_bpf_arg_type

Possible types for function/BPF program arguments.

Enumerator
RTE_BPF_ARG_UNDEF	undefined
RTE_BPF_ARG_RAW	scalar value
RTE_BPF_ARG_PTR	pointer to data buffer
RTE_BPF_ARG_PTR_MBUF	pointer to rte_mbuf
RTE_BPF_ARG_RESERVED	reserved for internal use

Definition at line 53 of file rte_bpf.h.

rte_bpf_xtype

enum rte_bpf_xtype

Possible types for external symbols.

Enumerator
RTE_BPF_XTYPE_FUNC	function
RTE_BPF_XTYPE_VAR	variable

Definition at line 83 of file rte_bpf.h.

rte_bpf_origin

enum rte_bpf_origin

Possible origins of eBPF program code.

Enumerator
RTE_BPF_ORIGIN_RAW	code loaded from raw array
RTE_BPF_ORIGIN_CBPF	code converted from cbpf
RTE_BPF_ORIGIN_ELF_FILE	code loaded from elf_file
RTE_BPF_ORIGIN_ELF_MEMORY	code loaded from elf_memory

Definition at line 113 of file rte_bpf.h.

Function Documentation

rte_bpf_destroy()

void rte_bpf_destroy

(

struct rte_bpf *

bpf

)

De-allocate all memory used by this eBPF execution context.

Parameters

bpf	BPF handle to destroy.

rte_bpf_load_ex()

__rte_experimental struct rte_bpf * rte_bpf_load_ex

(

const struct rte_bpf_prm_ex *

prm

)

Warning

EXPERIMENTAL: This API may change, or be removed, without prior notice.

Create a new eBPF execution context, load code from specified origin into it.

Parameters

prm	Parameters used to create and initialise the BPF execution context.

Member sz must be set to the struct size as known to the application. If it exceeds the size known to the library, and the extra part has non-zero bytes, parameter is rejected. If it's smaller than the size known to the library, defaults are used for the members that are not present.

Returns

BPF handle that is used in future BPF operations, or NULL on error, with error code set in rte_errno. Possible rte_errno errors include:

• EINVAL - invalid parameter passed to function
• ENOMEM - can't reserve enough memory
• ENOTSUP - requested feature is not supported (e.g. no libelf to load ELF)

rte_bpf_load()

__rte_experimental struct rte_bpf struct rte_bpf * rte_bpf_load

(

const struct rte_bpf_prm *

prm

)

Create a new eBPF execution context and load given BPF code into it.

Parameters

prm	Parameters used to create and initialise the BPF execution context.

Returns

BPF handle that is used in future BPF operations, or NULL on error, with error code set in rte_errno. Possible rte_errno errors include:

• EINVAL - invalid parameter passed to function
• ENOMEM - can't reserve enough memory

rte_bpf_elf_load()

__rte_experimental struct rte_bpf struct rte_bpf struct rte_bpf * rte_bpf_elf_load	(	const struct rte_bpf_prm *	prm,
		const char *	fname,
		const char *	sname
	)

Create a new eBPF execution context and load BPF code from given ELF file into it. Note that if the function will encounter EBPF_PSEUDO_CALL instruction that references external symbol, it will treat is as standard BPF_CALL to the external helper function.

Parameters

prm	Parameters used to create and initialise the BPF execution context.
fname	Pathname for a ELF file.
sname	Name of the executable section within the file to load.

Returns

BPF handle that is used in future BPF operations, or NULL on error, with error code set in rte_errno. Possible rte_errno errors include:

• EINVAL - invalid parameter passed to function
• ENOMEM - can't reserve enough memory

rte_bpf_exec()

__rte_experimental struct rte_bpf struct rte_bpf struct rte_bpf uint64_t rte_bpf_exec	(	const struct rte_bpf *	bpf,
		void *	ctx
	)

Execute given BPF bytecode accepting 1 argument.

Parameters

bpf	handle for the BPF code to execute.
ctx	pointer to input context.

Returns

BPF execution return value.

rte_bpf_exec_ex()

__rte_experimental uint64_t rte_bpf_exec_ex	(	const struct rte_bpf *	bpf,
		const struct rte_bpf_prog_ctx *	ctx,
		uint64_t	flags
	)

Warning

EXPERIMENTAL: This API may change, or be removed, without prior notice.

Execute given BPF bytecode accepting any number of arguments.

Parameters

bpf	handle for the BPF code to execute.
ctx	program arguments tuple.
flags	bitwise OR of RTE_BPF_EXEC_FLAG_* values controlling execution. Flag RTE_BPF_EXEC_FLAG_JIT requires presence of JIT version (can be checked with rte_bpf_get_jit_ex).

Returns

BPF execution return value.

rte_bpf_exec_burst()

uint32_t rte_bpf_exec_burst	(	const struct rte_bpf *	bpf,
		void *	ctx[],
		uint64_t	rc[],
		uint32_t	num
	)

Execute given BPF bytecode accepting 1 argument over a set of input contexts.

Parameters

bpf	handle for the BPF code to execute.
ctx	array of pointers to the input contexts.
rc	array of return values (one per input).
num	number of elements in ctx[] (and rc[]).

Returns

number of successfully processed inputs.

rte_bpf_exec_burst_ex()

__rte_experimental uint32_t rte_bpf_exec_burst_ex	(	const struct rte_bpf *	bpf,
		const struct rte_bpf_prog_ctx *	ctx,
		uint64_t	rc[],
		uint32_t	num,
		uint64_t	flags
	)

Warning

EXPERIMENTAL: This API may change, or be removed, without prior notice.

Execute given BPF program accepting any number of arguments over a set of input contexts.

Parameters

bpf	handle for the BPF code to execute.
ctx	pointer to array of program argument tuples, can be NULL for nullary programs.
rc	array of return values (one per input).
num	number executions, number of elements in arrays ctx and rc[].
flags	bitwise OR of RTE_BPF_EXEC_FLAG_* values controlling execution. Flag RTE_BPF_EXEC_FLAG_JIT requires presence of JIT version (can be checked with rte_bpf_get_jit_ex).

Returns

number of successfully processed inputs.

rte_bpf_get_jit()

int rte_bpf_get_jit	(	const struct rte_bpf *	bpf,
		struct rte_bpf_jit *	jit
	)

Provide information about natively compiled code for given BPF program accepting 1 argument.

Parameters

bpf	handle for the BPF code.
jit	pointer to the rte_bpf_jit structure to be filled with related data.

Returns

• -EINVAL if the parameters are invalid.
• Zero if operation completed successfully.

rte_bpf_get_jit_ex()

__rte_experimental int rte_bpf_get_jit_ex	(	const struct rte_bpf *	bpf,
		struct rte_bpf_jit_ex *	jit
	)

Warning

EXPERIMENTAL: This API may change, or be removed, without prior notice.

Get function JIT-compiled from the BPF program.

Parameters

bpf	handle for the BPF code.
jit	pointer to the struct rte_bpf_jit_ex.

Returns

• -EINVAL if the parameters are invalid.
• -ENOENT if there is no JIT-compiled version.
• Zero if operation completed successfully.

rte_bpf_insn_is_wide()

__rte_experimental bool rte_bpf_insn_is_wide

(

const struct ebpf_insn *

ins

)

Determine instruction width.

Returns

True if ins points to a wide (128-bit) instruction.

rte_bpf_format()

__rte_experimental int rte_bpf_format	(	char *	buffer,
		size_t	bufsz,
		const struct ebpf_insn *	ins,
		uint32_t	pc,
		uint32_t	flags
	)

Print eBPF instruction into a buffer.

Semantics of handling buffer size repeats those of snprintf.

Parameters

buffer	Output buffer (may be NULL if bufsz is zero).
bufsz	Output buffer size.
ins	Narrow or wide (depending on opcode) eBPF instruction. That is, when rte_bpf_insn_is_wide is true ins[1] is also accessed.
pc	Current instruction number for displaying absolute jump targets.
flags	Bitwise-OR combination of RTE_BPF_FORMAT_FLAG_* values.

Returns

Number of characters to be written excluding terminating zero.

rte_bpf_dump()

void rte_bpf_dump	(	FILE *	f,
		const struct ebpf_insn *	buf,
		uint32_t	len
	)

Dump epf instructions to a file.

Parameters

f	A pointer to a file for output
buf	A pointer to BPF instructions
len	Number of BPF instructions to dump.

rte_bpf_convert()

struct rte_bpf_prm * rte_bpf_convert

(

const struct bpf_program *

prog

)

Convert a Classic BPF program from libpcap into a DPDK BPF code.

Parameters

prog	Classic BPF program from pcap_compile().

Returns

Pointer to BPF program (allocated with rte_malloc) that is used in future BPF operations, or NULL on error, with error code set in rte_errno. Possible rte_errno errors include:

• EINVAL - invalid parameter passed to function
• ENOMEM - can't reserve enough memory
• ENOTSUP - operation not supported