rte_bpf_validate_debug.h File Reference

#include <bpf_def.h>
#include <rte_compat.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	rte_bpf_validate_debug_callback

Typedefs
typedef int(*	rte_bpf_validate_debug_point_process_t) (struct rte_bpf_validate_debug_point *point, void *ctx)

Enumerations
enum	rte_bpf_validate_debug_event

Functions
__rte_experimental struct rte_bpf_validate_debug *	rte_bpf_validate_debug_create (void)
__rte_experimental void	rte_bpf_validate_debug_destroy (struct rte_bpf_validate_debug *debug)
__rte_experimental struct rte_bpf_validate_debug_point *	rte_bpf_validate_debug_break (struct rte_bpf_validate_debug *debug, uint32_t pc, const struct rte_bpf_validate_debug_callback *callback)
__rte_experimental struct rte_bpf_validate_debug_point *	rte_bpf_validate_debug_catch (struct rte_bpf_validate_debug *debug, enum rte_bpf_validate_debug_event event, const struct rte_bpf_validate_debug_callback *callback)
__rte_experimental void	rte_bpf_validate_debug_point_destroy (struct rte_bpf_validate_debug_point *point)
__rte_experimental const struct rte_bpf_prm_ex *	rte_bpf_validate_debug_get_bpf_param (const struct rte_bpf_validate_debug *debug)
__rte_experimental int	rte_bpf_validate_debug_get_ins (const struct rte_bpf_validate_debug *debug, const struct ebpf_insn **ins, uint32_t *nb_ins)
__rte_experimental struct rte_bpf_validate_debug_point *	rte_bpf_validate_debug_get_last_point (const struct rte_bpf_validate_debug *debug)
__rte_experimental uint32_t	rte_bpf_validate_debug_get_pc (const struct rte_bpf_validate_debug *debug)
__rte_experimental int	rte_bpf_validate_debug_get_validation_result (const struct rte_bpf_validate_debug *debug, int *result)
__rte_experimental int	rte_bpf_validate_debug_can_access (const struct rte_bpf_validate_debug *debug, const struct ebpf_insn *access, uint64_t off64)
__rte_experimental int	rte_bpf_validate_debug_may_jump (const struct rte_bpf_validate_debug *debug, const struct ebpf_insn *jump, uint64_t imm64)
__rte_experimental int	rte_bpf_validate_debug_format_register_info (const struct rte_bpf_validate_debug *debug, char *buffer, size_t bufsz, uint8_t reg)
__rte_experimental int	rte_bpf_validate_debug_format_frame_info (const struct rte_bpf_validate_debug *debug, char *buffer, size_t bufsz, int32_t offset)
__rte_experimental int32_t	rte_bpf_validate_debug_get_frame_size (const struct rte_bpf_validate_debug *debug)
__rte_experimental int	rte_bpf_validate_debug_format_value (char *buffer, size_t bufsz, char format, uint64_t value)
__rte_experimental int	rte_bpf_validate_debug_format_interval (char *buffer, size_t bufsz, char format, uint64_t min, uint64_t max)

Detailed Description

Debugging interface for BPF validation.

Can be used for debugging BPF validation problems as well as in tests.

Definition in file rte_bpf_validate_debug.h.

Typedef Documentation

rte_bpf_validate_debug_point_process_t

typedef int(* rte_bpf_validate_debug_point_process_t) (struct rte_bpf_validate_debug_point *point, void *ctx)

Invoked by rte_bpf_validate_debug_for_each_point for each breakpoint and catchpoint.

Definition at line 68 of file rte_bpf_validate_debug.h.

Enumeration Type Documentation

rte_bpf_validate_debug_event

enum rte_bpf_validate_debug_event

Supported validate events.

Valid events begin from 0 and end before RTE_BPF_VALIDATE_DEBUG_EVENT_END.

Definition at line 35 of file rte_bpf_validate_debug.h.

Function Documentation

rte_bpf_validate_debug_create()

__rte_experimental struct rte_bpf_validate_debug * rte_bpf_validate_debug_create

(

void

)

Create new debug instance.

Returns

Debug instance in case of success. NULL with rte_errno set in case of a failure.

rte_bpf_validate_debug_destroy()

__rte_experimental void rte_bpf_validate_debug_destroy

(

struct rte_bpf_validate_debug *

debug

)

Destroy debug instance.

Behavior is undefined if validation with this debug instance is ongoing.

Parameters

debug

Debug instance, or NULL.

rte_bpf_validate_debug_break()

__rte_experimental struct rte_bpf_validate_debug_point * rte_bpf_validate_debug_break	(	struct rte_bpf_validate_debug *	debug,
		uint32_t	pc,
		const struct rte_bpf_validate_debug_callback *	callback
	)

Create new breakpoint at specified location.

Can be called before the validation has started. If at validation start later the program will not have the specified instruction, the start will fail.

It is allowed to create breakpoints for the same location a callback is currently executing for, but it will not be invoked in the same cycle.

Parameters

debug	Debug instance.
pc	Program counter to create breakpoint at.
callback	Callback to invoke.

Returns

New breakpoint on success, NULL with rte_errno set on failure.

rte_bpf_validate_debug_catch()

__rte_experimental struct rte_bpf_validate_debug_point * rte_bpf_validate_debug_catch	(	struct rte_bpf_validate_debug *	debug,
		enum rte_bpf_validate_debug_event	event,
		const struct rte_bpf_validate_debug_callback *	callback
	)

Create new catchpoint for specified event.

Can be called before the validation has started.

It is allowed to create catchpoints for the same event a callback is currently executing for, but it will not be invoked in the same cycle.

Parameters

debug	Debug instance.
event	Validation event to create catchpoint for.
callback	Callback to invoke.

Returns

New breakpoint on success, NULL with rte_errno set on failure.

rte_bpf_validate_debug_point_destroy()

__rte_experimental void rte_bpf_validate_debug_point_destroy

(

struct rte_bpf_validate_debug_point *

point

)

Delete breakpoint or catchpoint and free all associated resources.

If a callback is currently being executed, calling this API is allowed for:

• breakpoint or catchpoint the callback is executed for;
• breakpoints or catchpoints for other locations or events; and NOT allowed for:
• other breakpoints or catchpoints for the same location or event.

Parameters

point

Breakpoint or catchpoint to destroy, or NULL.

rte_bpf_validate_debug_get_bpf_param()

__rte_experimental const struct rte_bpf_prm_ex * rte_bpf_validate_debug_get_bpf_param

(

const struct rte_bpf_validate_debug *

debug

)

Get effective eBPF parameters struct.

Parameters

debug

Debug instance.

Returns

Parameters struct of the validated eBPF program, including code with all patches and relocations applied.

rte_bpf_validate_debug_get_ins()

__rte_experimental int rte_bpf_validate_debug_get_ins	(	const struct rte_bpf_validate_debug *	debug,
		const struct ebpf_insn **	ins,
		uint32_t *	nb_ins
	)

Get pointer to effective eBPF program instructions.

Parameters

debug	Debug instance.
ins	Upon return, program instructions with all patches and relocations applied.
nb_ins	Upon return, number of program instructions.

Returns

Non-negative value on success, negative errno on failure.

rte_bpf_validate_debug_get_last_point()

__rte_experimental struct rte_bpf_validate_debug_point * rte_bpf_validate_debug_get_last_point

(

const struct rte_bpf_validate_debug *

debug

)

Get last triggered breakpoint or catchpoint.

Can be used to destroy currently processed breakpoint or catchpoint.

The pointer may be invalid if the breakpoint or catchpoint has already been destroyed earlier.

Parameters

debug

Debug instance.

Returns

Last triggered breakpoint or callpoint, including one the callback is currently executing for. NULL of none were triggered in the current validation process.

rte_bpf_validate_debug_get_pc()

__rte_experimental uint32_t rte_bpf_validate_debug_get_pc

(

const struct rte_bpf_validate_debug *

debug

)

Get current instruction index, or one after last if finishing.

Parameters

debug

Debug instance.

Returns

Current program counter being validated, or one after last. UINT32_MAX if no program is being validated.

rte_bpf_validate_debug_get_validation_result()

__rte_experimental int rte_bpf_validate_debug_get_validation_result	(	const struct rte_bpf_validate_debug *	debug,
		int *	result
	)

Get the validation result, if it has finished.

Parameters

debug	Debug instance.
result	Upon successful return, the validation result (negative if validation failed).

Returns

Non-negative value if validation has finished and result variable was written; -EAGAIN if validation is still ongoing; other negative errno in case of failure;

rte_bpf_validate_debug_can_access()

__rte_experimental int rte_bpf_validate_debug_can_access	(	const struct rte_bpf_validate_debug *	debug,
		const struct ebpf_insn *	access,
		uint64_t	off64
	)

Check if specified memory access instruction is currently valid.

Parameters

debug	Debug instance.
access	Memory load or store eBPF instruction.
off64	Additional 64-bit offset added to ins->off.

Returns

1 if specified memory access is currently valid; 0 if specified memory access is currently invalid; negative errno in case of failure;

rte_bpf_validate_debug_may_jump()

__rte_experimental int rte_bpf_validate_debug_may_jump	(	const struct rte_bpf_validate_debug *	debug,
		const struct ebpf_insn *	jump,
		uint64_t	imm64
	)

Get possible truth values of the specified jump condition.

Parameters

debug	Debug instance.
jump	Conditional jump instruction specifying the condition.
imm64	Additional 64-bit immediate added to the source.

Returns

in case of success, bitwise combination of: RTE_BPF_VALIDATE_DEBUG_MAY_BE_FALSE if the jump condition may be false; RTE_BPF_VALIDATE_DEBUG_MAY_BE_TRUE if the jump condition may be true; negative errno in case of failure.

rte_bpf_validate_debug_format_register_info()

__rte_experimental int rte_bpf_validate_debug_format_register_info	(	const struct rte_bpf_validate_debug *	debug,
		char *	buffer,
		size_t	bufsz,
		uint8_t	reg
	)

Format information about specified register for the user.

Parameters buffer, bufsz and return value work the same way as for snprintf.

Parameters

debug	Debug instance.
buffer	Buffer to fill with register information.
bufsz	Buffer size (including space for terminating zero).
reg	Register to provide information about.

Returns

Number of characters needed excluding terminating zero.

rte_bpf_validate_debug_format_frame_info()

__rte_experimental int rte_bpf_validate_debug_format_frame_info	(	const struct rte_bpf_validate_debug *	debug,
		char *	buffer,
		size_t	bufsz,
		int32_t	offset
	)

Format information about specified stack frame location for the user.

Parameters buffer, bufsz and return value work the same way as for snprintf.

Parameters

debug	Debug instance.
buffer	Buffer to fill with register information.
bufsz	Buffer size (including space for terminating zero).
offset	Stack frame offset to provide information about, in bytes. Typically a negative multiple of 8.

Returns

Number of characters needed excluding terminating zero.

rte_bpf_validate_debug_get_frame_size()

__rte_experimental int32_t rte_bpf_validate_debug_get_frame_size

(

const struct rte_bpf_validate_debug *

debug

)

Get program stack frame size.

Parameters

debug

Debug instance.

Returns

Program stack frame size in bytes.

rte_bpf_validate_debug_format_value()

__rte_experimental int rte_bpf_validate_debug_format_value	(	char *	buffer,
		size_t	bufsz,
		char	format,
		uint64_t	value
	)

Format value following the style of register format function.

Parameters buffer, bufsz and return value work the same way as for snprintf.

Parameters

buffer	Buffer to fill with register information.
bufsz	Buffer size (including space for terminating zero).
format	One of characters 'd' or 'x' for signed or hexadecimal format.
value	Formatted value, can be signed typecast to unsigned.

Returns

Number of characters needed excluding terminating zero.

rte_bpf_validate_debug_format_interval()

__rte_experimental int rte_bpf_validate_debug_format_interval	(	char *	buffer,
		size_t	bufsz,
		char	format,
		uint64_t	min,
		uint64_t	max
	)

Format interval following the style of register format function.

Parameters buffer, bufsz and return value work the same way as for snprintf.

Parameters

buffer	Buffer to fill with register information.
bufsz	Buffer size (including space for terminating zero).
format	One of characters 'd' or 'x' for signed or hexadecimal format.
min	Minimum value of the interval, can be signed typecast to unsigned.
max	Maximum value of the interval, can be signed typecast to unsigned.

Returns

Number of characters needed excluding terminating zero.