#include "ebpf_core_structs.h"
#include "ebpf_execution_type.h"
#include "ebpf_program_attach_type_guids.h"
#include "ebpf_result.h"
#include <specstrings.h>
#include <stdbool.h>
#include <stdint.h>

Data Structures
struct	_ebpf_stat

struct	_ebpf_section_info

struct	ebpf_api_verifier_stats_t

struct	_ebpf_test_run_options

Macros
#define	EBPF_NO_EXCEPT

Typedefs
typedef int32_t	fd_t

typedef intptr_t	ebpf_handle_t

typedef struct _ebpf_stat	ebpf_stat_t

typedef struct _ebpf_section_info	ebpf_section_info_t

typedef struct _ebpf_program_info	ebpf_program_info_t

typedef struct _ebpf_test_run_options	ebpf_test_run_options_t

Functions
_Must_inspect_result_ ebpf_result_t	ebpf_program_query_info (fd_t fd, ebpf_execution_type_t execution_type, _Outptr_result_z_ const char file_name, _Outptr_result_z_ const char *section_name) EBPF_NO_EXCEPT
	Query info about an eBPF program. More...

_Must_inspect_result_ ebpf_result_t	ebpf_enumerate_sections (const char file, bool verbose, _Outptr_result_maybenull_ ebpf_section_info_t infos, const char *error_message) EBPF_NO_EXCEPT
	Get list of programs and stats in an eBPF file. More...

void	ebpf_free_sections (ebpf_section_info_t *infos) EBPF_NO_EXCEPT
	Free memory returned from ebpf_enumerate_sections. More...

uint32_t	ebpf_api_elf_disassemble_section (const char file, const char section, const char disassembly, const char error_message) EBPF_NO_EXCEPT
	Convert an eBPF program to human readable byte code. More...

uint32_t	ebpf_api_elf_verify_section_from_file (const char file, const char section, const ebpf_program_type_t program_type, bool verbose, const char report, const char error_message, _Out_opt_ ebpf_api_verifier_stats_t stats) EBPF_NO_EXCEPT
	Verify that the program is safe to execute. More...

uint32_t	ebpf_api_elf_verify_section_from_memory (_In_reads_(data_length) const char data, size_t data_length, const char section, const ebpf_program_type_t program_type, bool verbose, const char report, const char error_message, _Out_opt_ ebpf_api_verifier_stats_t stats) EBPF_NO_EXCEPT
	Verify that the program is safe to execute. More...

void	ebpf_free_string (const char *string) EBPF_NO_EXCEPT
	Free memory for a string returned from an eBPF API. More...

uint32_t	ebpf_api_unpin_object (const uint8_t *name, uint32_t name_length) EBPF_NO_EXCEPT
	Dissociate a name with an object handle. More...

_Must_inspect_result_ ebpf_result_t	ebpf_object_unpin (const char *path) EBPF_NO_EXCEPT
	Unpin the object from the specified path. More...

_Must_inspect_result_ ebpf_result_t	ebpf_api_unlink_program (ebpf_handle_t link_handle) EBPF_NO_EXCEPT
	Detach the eBPF program from the link. More...

_Must_inspect_result_ ebpf_result_t	ebpf_api_close_handle (ebpf_handle_t handle) EBPF_NO_EXCEPT
	Close an eBPF handle. More...

_Must_inspect_result_ ebpf_result_t	ebpf_api_get_pinned_map_info (uint16_t map_count,(map_count) ebpf_map_info_t **map_info) EBPF_NO_EXCEPT
	Returns an array of ebpf_map_info_t for all pinned maps. More...

void	ebpf_api_map_info_free (uint16_t map_count, const ebpf_map_info_t *map_info) EBPF_NO_EXCEPT
	Helper Function to free array of ebpf_map_info_t allocated by ebpf_api_get_pinned_map_info function. More...

ebpf_execution_type_t	ebpf_object_get_execution_type (const struct bpf_object *object) EBPF_NO_EXCEPT
	Get the execution type for an eBPF object file. More...

_Must_inspect_result_ ebpf_result_t	ebpf_object_set_execution_type (_Inout_ struct bpf_object *object, ebpf_execution_type_t execution_type) EBPF_NO_EXCEPT
	Set the execution type for an eBPF object file. More...

_Must_inspect_result_ ebpf_result_t	ebpf_program_attach (const struct bpf_program program, const ebpf_attach_type_t attach_type, _In_reads_bytes_opt_(attach_params_size) void attach_parameters, size_t attach_params_size, struct bpf_link *link) EBPF_NO_EXCEPT
	Attach an eBPF program. More...

_Must_inspect_result_ ebpf_result_t	ebpf_program_attach_by_fd (fd_t program_fd, const ebpf_attach_type_t attach_type, _In_reads_bytes_opt_(attach_parameters_size) void attach_parameters, size_t attach_parameters_size, struct bpf_link **link) EBPF_NO_EXCEPT
	Attach an eBPF program by program file descriptor. More...

_Must_inspect_result_ ebpf_result_t	ebpf_link_detach (_Inout_ struct bpf_link *link) EBPF_NO_EXCEPT
	Detach an eBPF program from an attach point represented by the bpf_link structure. More...

_Must_inspect_result_ ebpf_result_t	ebpf_program_detach (fd_t program_fd, const ebpf_attach_type_t attach_type, _In_reads_bytes_(attach_parameter_size) void attach_parameter, size_t attach_parameter_size) EBPF_NO_EXCEPT
	Detach an eBPF program. More...

void	ebpf_link_close (_Frees_ptr_ struct bpf_link *link) EBPF_NO_EXCEPT

_Must_inspect_result_ ebpf_result_t	ebpf_close_fd (fd_t fd) EBPF_NO_EXCEPT
	Close a file descriptor. Also close the underlying handle. More...

_Must_inspect_result_ ebpf_result_t	ebpf_get_program_type_by_name (const char name, ebpf_program_type_t program_type, ebpf_attach_type_t *expected_attach_type) EBPF_NO_EXCEPT
	Get eBPF program type and expected attach type by name. More...

_Ret_maybenull_z_ const char *	ebpf_get_program_type_name (const ebpf_program_type_t *program_type) EBPF_NO_EXCEPT
	Get the name of a given program type. More...

_Ret_maybenull_z_ const char *	ebpf_get_attach_type_name (const ebpf_attach_type_t *attach_type) EBPF_NO_EXCEPT
	Get the name of a given attach type. More...

_Must_inspect_result_ ebpf_result_t	ebpf_get_next_pinned_program_path (const char start_path, _Out_writes_z_(EBPF_MAX_PIN_PATH_LENGTH) char next_path) EBPF_NO_EXCEPT
	Gets the next pinned program after a given path. More...

_Must_inspect_result_ ebpf_result_t	ebpf_get_program_info_from_verifier (const ebpf_program_info_t **program_info) EBPF_NO_EXCEPT
	Get the set of program information used by the verifier during the last verification. More...

_Must_inspect_result_ ebpf_result_t	ebpf_program_test_run (fd_t program_fd, _Inout_ ebpf_test_run_options_t *options) EBPF_NO_EXCEPT
	Run the program in the eBPF VM, measure the execution time, and return the result. More...

Variables
const fd_t	ebpf_fd_invalid = -1

Macro Definition Documentation

◆ EBPF_NO_EXCEPT

#define EBPF_NO_EXCEPT

Typedef Documentation

◆ ebpf_handle_t

typedef intptr_t ebpf_handle_t

◆ ebpf_program_info_t

typedef struct _ebpf_program_info ebpf_program_info_t

◆ ebpf_section_info_t

typedef struct _ebpf_section_info ebpf_section_info_t

◆ ebpf_stat_t

typedef struct _ebpf_stat ebpf_stat_t

◆ ebpf_test_run_options_t

typedef struct _ebpf_test_run_options ebpf_test_run_options_t

◆ fd_t

typedef int32_t fd_t

Function Documentation

◆ ebpf_api_close_handle()

_Must_inspect_result_ ebpf_result_t ebpf_api_close_handle ( ebpf_handle_t handle )

Close an eBPF handle.

Parameters

[in] handle Handle to close.

Return values

EBPF_SUCCESS	Handle was closed.
EBPF_INVALID_OBJECT	Handle is not valid.

◆ ebpf_api_elf_disassemble_section()

uint32_t ebpf_api_elf_disassemble_section	(	const char *	file,
		const char *	section,
		const char **	disassembly,
		const char **	error_message
	)

Convert an eBPF program to human readable byte code.

Parameters

[in]	file	Name of ELF file containing eBPF program.
[in]	section	The name of the section to query.
[out]	disassembly	On success points text version of the program.
[out]	error_message	On failure points to a text description of the error.

◆ ebpf_api_elf_verify_section_from_file()

uint32_t ebpf_api_elf_verify_section_from_file	(	const char *	file,
		const char *	section,
		const ebpf_program_type_t *	program_type,
		bool	verbose,
		const char **	report,
		const char **	error_message,
		_Out_opt_ ebpf_api_verifier_stats_t *	stats
	)

Verify that the program is safe to execute.

Parameters

[in]	file	Name of ELF file containing eBPF program.
[in]	section	The name of the section to query.
[in]	program_type	Optional program type. If NULL, the program type is derived from the section name.
[in]	verbose	Obtain additional info about the programs.
[out]	report	Points to a text section describing why the program failed verification.
[out]	error_message	On failure points to a text description of the error.
[out]	stats	If non-NULL, returns verification statistics.

Return values

0	Verification succeeded.
1	Verification failed.

◆ ebpf_api_elf_verify_section_from_memory()

uint32_t ebpf_api_elf_verify_section_from_memory	(	_In_reads_(data_length) const char *	data,
		size_t	data_length,
		const char *	section,
		const ebpf_program_type_t *	program_type,
		bool	verbose,
		const char **	report,
		const char **	error_message,
		_Out_opt_ ebpf_api_verifier_stats_t *	stats
	)

Verify that the program is safe to execute.

Parameters

[in]	data	Memory containing the ELF file containing eBPF program.
[in]	data_length	Length of data.
[in]	section	The name of the section to query.
[in]	program_type	Optional program type. If NULL, the program type is derived from the section name.
[in]	verbose	Obtain additional info about the programs.
[out]	report	Points to a text section describing why the program failed verification.
[out]	error_message	On failure points to a text description of the error.
[out]	stats	If non-NULL, returns verification statistics.

Return values

0	Verification succeeded.
1	Verification failed.

◆ ebpf_api_get_pinned_map_info()

_Must_inspect_result_ ebpf_result_t ebpf_api_get_pinned_map_info	(	uint16_t *	map_count,
		map_count ebpf_map_info_t *	map_info
	)

Returns an array of ebpf_map_info_t for all pinned maps.

Parameters

[out]	map_count	Number of pinned maps.
[out]	map_info	Array of ebpf_map_info_t for pinned maps.

Return values

EBPF_SUCCESS	The API succeeded.
EBPF_NO_MEMORY	Out of memory.
EBPF_INVALID_ARGUMENT	One or more parameters are wrong.

◆ ebpf_api_map_info_free()

void ebpf_api_map_info_free	(	uint16_t	map_count,
		const ebpf_map_info_t *	map_info
	)

Helper Function to free array of ebpf_map_info_t allocated by ebpf_api_get_pinned_map_info function.

Parameters

[in]	map_count	Length of array to be freed.
[in]	map_info	Map to be freed.

◆ ebpf_api_unlink_program()

_Must_inspect_result_ ebpf_result_t ebpf_api_unlink_program ( ebpf_handle_t link_handle )

Detach the eBPF program from the link.

Parameters

[in] link_handle Handle to the link.

Return values

EBPF_SUCCESS	The operations succeeded.
EBPF_INVALID_ARGUMENT	The link handle is invalid.

◆ ebpf_api_unpin_object()

uint32_t ebpf_api_unpin_object	(	const uint8_t *	name,
		uint32_t	name_length
	)

Dissociate a name with an object handle.

Parameters

[in]	name	Name to dissociate.
[in]	name_length	Length in bytes of the name.

◆ ebpf_close_fd()

_Must_inspect_result_ ebpf_result_t ebpf_close_fd ( fd_t fd )

Close a file descriptor. Also close the underlying handle.

Parameters

[in] fd File descriptor to be closed.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_INVALID_FD	Invalid fd was provided.

◆ ebpf_enumerate_sections()

_Must_inspect_result_ ebpf_result_t ebpf_enumerate_sections	(	const char *	file,
		bool	verbose,
		_Outptr_result_maybenull_ ebpf_section_info_t **	infos,
		const char **	error_message
	)

Get list of programs and stats in an eBPF file.

*- *
Parameters

[in] file Name of file containing eBPF programs.
*
Parameters

[in] verbose Obtain additional info about the programs.
*
Parameters

[out] infos On success points to a list of eBPF programs. The caller is responsible for freeing the list via ebpf_free_sections().
*
Parameters

[out] error_message On failure points to a text description of
* the error.

◆ ebpf_free_sections()

void ebpf_free_sections ( ebpf_section_info_t * infos )

Free memory returned from ebpf_enumerate_sections.

Parameters

[in] data Memory to free.

◆ ebpf_free_string()

void ebpf_free_string ( const char * string )

Free memory for a string returned from an eBPF API.

Parameters

[in] string Memory to free.

◆ ebpf_get_attach_type_name()

_Ret_maybenull_z_ const char* ebpf_get_attach_type_name ( const ebpf_attach_type_t * attach_type )

Get the name of a given attach type.

Parameters

[in] attach_type Attach type.

Returns: Name of the attach type, or NULL if not found.

◆ ebpf_get_next_pinned_program_path()

_Must_inspect_result_ ebpf_result_t ebpf_get_next_pinned_program_path	(	const char *	start_path,
		_Out_writes_z_(EBPF_MAX_PIN_PATH_LENGTH) char *	next_path
	)

Gets the next pinned program after a given path.

Parameters

[in]	start_path	Path to look for an entry greater than.
[out]	next_path	Returns the next path, if one exists.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_NO_MORE_KEYS	No more entries found.

◆ ebpf_get_program_info_from_verifier()

_Must_inspect_result_ ebpf_result_t ebpf_get_program_info_from_verifier ( const ebpf_program_info_t ** program_info )

Get the set of program information used by the verifier during the last verification.

Parameters

[out] program_info Pointer to the program information used to verify the program.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_OBJECT_NOT_FOUND	No program information was found.

◆ ebpf_get_program_type_by_name()

_Must_inspect_result_ ebpf_result_t ebpf_get_program_type_by_name	(	const char *	name,
		ebpf_program_type_t *	program_type,
		ebpf_attach_type_t *	expected_attach_type
	)

Get eBPF program type and expected attach type by name.

Parameters

[in]	name	Name, as if it were a section name in an ELF file.
[out]	program_type	eBPF program type.
[out]	expected_attach_type	Expected eBPF attach type.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_KEY_NOT_FOUND	No program type was found.

◆ ebpf_get_program_type_name()

_Ret_maybenull_z_ const char* ebpf_get_program_type_name ( const ebpf_program_type_t * program_type )

Get the name of a given program type.

Parameters

[in] program_type Program type.

Returns: Name of the program type, or NULL if not found.

◆ ebpf_link_close()

void ebpf_link_close ( _Frees_ptr_ struct bpf_link * link )

Clean up and free bpf_link structure. Also close the underlying link fd.

Parameters

[in] link Pointer to the bpf_link structure.

See also: bpf_link__destroy; bpf_link_detach

◆ ebpf_link_detach()

_Must_inspect_result_ ebpf_result_t ebpf_link_detach ( _Inout_ struct bpf_link * link )

Detach an eBPF program from an attach point represented by the bpf_link structure.

Parameters

[in,out] link Pointer to bpf_link structure.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_INVALID_OBJECT	Invalid object was passed.

◆ ebpf_object_get_execution_type()

ebpf_execution_type_t ebpf_object_get_execution_type ( const struct bpf_object * object )

Get the execution type for an eBPF object file.

Parameters

[in] object The eBPF object file.

Returns: Execution type.

◆ ebpf_object_set_execution_type()

_Must_inspect_result_ ebpf_result_t ebpf_object_set_execution_type	(	_Inout_ struct bpf_object *	object,
		ebpf_execution_type_t	execution_type
	)

Set the execution type for an eBPF object file.

Parameters

[in,out]	object	The eBPF object file.
[in]	execution_type	Execution type to set.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_INVALID_ARGUMENT	One or more parameters are incorrect.

◆ ebpf_object_unpin()

_Must_inspect_result_ ebpf_result_t ebpf_object_unpin ( const char * path )

Unpin the object from the specified path.

Parameters

[in] path Path from which to unpin.

Return values

EBPF_SUCCESS The operation was successful.

◆ ebpf_program_attach()

_Must_inspect_result_ ebpf_result_t ebpf_program_attach	(	const struct bpf_program *	program,
		const ebpf_attach_type_t *	attach_type,
		_In_reads_bytes_opt_(attach_params_size) void *	attach_parameters,
		size_t	attach_params_size,
		struct bpf_link **	link
	)

Attach an eBPF program.

Parameters

[in]	program	Pointer to the eBPF program.
[in]	attach_type	Optionally, the attach type for attaching the program. If attach type is not specified, then the earlier provided attach type or attach type derived from section prefix will be used to attach the program.
[in]	attach_params_size	Size of the attach parameters.
[in]	attach_parameters	Optionally, attach parameters. This is an opaque flat buffer containing the attach parameters which is interpreted by the extension provider.
[out]	link	Pointer to ebpf_link structure.

Return values

EBPF_SUCCESS The operation was successful.

◆ ebpf_program_attach_by_fd()

_Must_inspect_result_ ebpf_result_t ebpf_program_attach_by_fd	(	fd_t	program_fd,
		const ebpf_attach_type_t *	attach_type,
		_In_reads_bytes_opt_(attach_parameters_size) void *	attach_parameters,
		size_t	attach_parameters_size,
		struct bpf_link **	link
	)

Attach an eBPF program by program file descriptor.

Parameters

[in]	program_fd	An eBPF program file descriptor.
[in]	attach_type	Optionally, the attach type for attaching the program. If attach type is not specified, then the earlier provided attach type or attach type derived from section prefix will be used to attach the program.
[in]	attach_parameters_size	Size of the attach parameters.
[in]	attach_parameters	Optionally, attach parameters. This is an opaque flat buffer containing the attach parameters which is interpreted by the extension provider.
[out]	link	Pointer to ebpf_link structure.

Return values

EBPF_SUCCESS The operation was successful.

◆ ebpf_program_detach()

_Must_inspect_result_ ebpf_result_t ebpf_program_detach	(	fd_t	program_fd,
		const ebpf_attach_type_t *	attach_type,
		_In_reads_bytes_(attach_parameter_size) void *	attach_parameter,
		size_t	attach_parameter_size
	)

Detach an eBPF program.

Parameters

[in]	program_fd	File descriptor of program to detach. If set to -1, this parameter is ignored.
[in]	attach_type	The attach type for attaching the program.
[in]	attach_parameter_size	Size of the attach parameter.
[in]	attach_parameter	Pointer to attach parameter. This is an opaque flat buffer containing the attach parameters which is interpreted by the extension provider.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_INVALID_OBJECT	Invalid object was passed.

◆ ebpf_program_query_info()

_Must_inspect_result_ ebpf_result_t ebpf_program_query_info	(	fd_t	fd,
		ebpf_execution_type_t *	execution_type,
		_Outptr_result_z_ const char **	file_name,
		_Outptr_result_z_ const char **	section_name
	)

Query info about an eBPF program.

Parameters

[in]	fd	File descriptor of an eBPF program.
[out]	execution_type	On success, contains the execution type.
[out]	file_name	On success, contains the file name.
[out]	section_name	On success, contains the section name.

Return values

EBPF_SUCCESS The operation was successful.

◆ ebpf_program_test_run()

_Must_inspect_result_ ebpf_result_t ebpf_program_test_run	(	fd_t	program_fd,
		_Inout_ ebpf_test_run_options_t *	options
	)

Run the program in the eBPF VM, measure the execution time, and return the result.

Parameters

[in]	program_fd	File descriptor of the program to run.
[in,out]	options	Options to control the test run and results.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_INVALID_OBJECT	Invalid object was passed.

Variable Documentation

◆ ebpf_fd_invalid

const fd_t ebpf_fd_invalid = -1

extern

Data Structures

Macros

Typedefs

Functions

Variables

Macro Definition Documentation

◆ EBPF_NO_EXCEPT

Typedef Documentation

◆ ebpf_handle_t

◆ ebpf_program_info_t

◆ ebpf_section_info_t

◆ ebpf_stat_t

◆ ebpf_test_run_options_t

◆ fd_t

Function Documentation

◆ ebpf_api_close_handle()

◆ ebpf_api_elf_disassemble_section()

◆ ebpf_api_elf_verify_section_from_file()

◆ ebpf_api_elf_verify_section_from_memory()

◆ ebpf_api_get_pinned_map_info()

◆ ebpf_api_map_info_free()

◆ ebpf_api_unlink_program()

◆ ebpf_api_unpin_object()

◆ ebpf_close_fd()

◆ ebpf_enumerate_sections()

◆ ebpf_free_sections()

◆ ebpf_free_string()

◆ ebpf_get_attach_type_name()

◆ ebpf_get_next_pinned_program_path()

◆ ebpf_get_program_info_from_verifier()

◆ ebpf_get_program_type_by_name()

◆ ebpf_get_program_type_name()

◆ ebpf_link_close()

◆ ebpf_link_detach()

◆ ebpf_object_get_execution_type()

◆ ebpf_object_set_execution_type()

◆ ebpf_object_unpin()

◆ ebpf_program_attach()

◆ ebpf_program_attach_by_fd()

◆ ebpf_program_detach()

◆ ebpf_program_query_info()

◆ ebpf_program_test_run()

Variable Documentation

◆ ebpf_fd_invalid