eBPF for Windows
Data Structures | Macros | Typedefs | Functions | Variables
ebpf_api.h File Reference
#include <specstrings.h>
#include <stdbool.h>
#include <stdint.h>
#include "ebpf_core_structs.h"
#include "ebpf_execution_type.h"
#include "ebpf_program_attach_type_guids.h"
#include "ebpf_result.h"

Go to the source code of this file.

Data Structures

struct  _ebpf_stat
 
struct  _ebpf_section_info
 
struct  ebpf_api_verifier_stats_t
 

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
 

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)
 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)
 Get list of programs and stats in an eBPF file. More...
 
void ebpf_free_sections (ebpf_section_info_t *infos)
 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)
 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)
 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)
 Verify that the program is safe to execute. More...
 
void ebpf_free_string (const char *string)
 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)
 Dissociate a name with an object handle. More...
 
_Must_inspect_result_ ebpf_result_t ebpf_object_unpin (const char *path)
 Unpin the object from the specified path. More...
 
_Must_inspect_result_ ebpf_result_t ebpf_api_unlink_program (ebpf_handle_t link_handle)
 Detach the eBPF program from the link. More...
 
_Must_inspect_result_ ebpf_result_t ebpf_api_close_handle (ebpf_handle_t handle)
 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)
 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)
 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 (struct bpf_object *object)
 Get the execution type for an eBPF object file. More...
 
_Must_inspect_result_ ebpf_result_t ebpf_object_set_execution_type (struct bpf_object *object, ebpf_execution_type_t execution_type)
 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)
 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)
 Attach an eBPF program by program file descriptor. More...
 
_Must_inspect_result_ ebpf_result_t ebpf_link_detach (struct bpf_link *link)
 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)
 
_Must_inspect_result_ ebpf_result_t ebpf_close_fd (fd_t fd)
 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)
 Get eBPF program type and expected attach type by name. More...
 
const _Ret_maybenull_z_ char * ebpf_get_program_type_name (const ebpf_program_type_t *program_type)
 Get the name of a given program type. More...
 
const _Ret_maybenull_z_ char * ebpf_get_attach_type_name (const ebpf_attach_type_t *attach_type)
 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)
 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)
 Get the set of program information used by the verifier during the last verification. 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

◆ ebpf_section_info_t

◆ ebpf_stat_t

typedef struct _ebpf_stat ebpf_stat_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]handleHandle to close.
Return values
EBPF_SUCCESSHandle was closed.
EBPF_INVALID_OBJECTHandle 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]fileName of ELF file containing eBPF program.
[in]sectionThe name of the section to query.
[out]disassemblyOn success points text version of the program.
[out]error_messageOn 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]fileName of ELF file containing eBPF program.
[in]sectionThe name of the section to query.
[in]program_typeOptional program type. If NULL, the program type is derived from the section name.
[in]verboseObtain additional info about the programs.
[out]reportPoints to a text section describing why the program failed verification.
[out]error_messageOn failure points to a text description of the error.
[out]statsIf non-NULL, returns verification statistics.
Return values
0Verification succeeded.
1Verification 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]dataMemory containing the ELF file containing eBPF program.
[in]data_lengthLength of data.
[in]sectionThe name of the section to query.
[in]program_typeOptional program type. If NULL, the program type is derived from the section name.
[in]verboseObtain additional info about the programs.
[out]reportPoints to a text section describing why the program failed verification.
[out]error_messageOn failure points to a text description of the error.
[out]statsIf non-NULL, returns verification statistics.
Return values
0Verification succeeded.
1Verification 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_countNumber of pinned maps.
[out]map_infoArray of ebpf_map_info_t for pinned maps.
Return values
EBPF_SUCCESSThe API suceeded.
EBPF_NO_MEMORYOut of memory.
EBPF_INVALID_ARGUMENTOne 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_countLength of array to be freed.
[in]map_infoMap 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_handleHandle to the link.
Return values
EBPF_SUCCESSThe operations succeeded.
EBPF_INVALID_ARGUMENTThe 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]nameName to dissociate.
[in]name_lengthLength 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]fdFile descriptor to be closed.
Return values
EBPF_SUCCESSThe operation was successful.
EBPF_INVALID_FDInvalid 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]fileName of file containing eBPF programs.
  • *
    Parameters
    [in]verboseObtain additional info about the programs.
  • *
    Parameters
    [out]infosOn success points to a list of eBPF programs. The caller is responsible for freeing the list via ebpf_free_sections().
  • *
    Parameters
    [out]error_messageOn 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]dataMemory to free.

◆ ebpf_free_string()

void ebpf_free_string ( const char *  string)

Free memory for a string returned from an eBPF API.

Parameters
[in]stringMemory to free.

◆ ebpf_get_attach_type_name()

const _Ret_maybenull_z_ char* ebpf_get_attach_type_name ( const ebpf_attach_type_t attach_type)

Get the name of a given attach type.

Parameters
[in]attach_typeAttach 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_pathPath to look for an entry greater than.
[out]next_pathReturns the next path, if one exists.
Return values
EBPF_SUCCESSThe operation was successful.
EBPF_NO_MORE_KEYSNo 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_infoPointer to the program information used to verify the program.
Return values
EBPF_SUCCESSThe operation was successful.
EBPF_OBJECT_NOT_FOUNDNo 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]nameName, as if it were a section name in an ELF file.
[out]program_typeeBPF program type.
[out]expected_attach_typeExpected eBPF attach type.
Return values
EBPF_SUCCESSThe operation was successful.
EBPF_KEY_NOT_FOUNDNo program type was found.

◆ ebpf_get_program_type_name()

const _Ret_maybenull_z_ char* ebpf_get_program_type_name ( const ebpf_program_type_t program_type)

Get the name of a given program type.

Parameters
[in]program_typeProgram 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]linkPointer 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 ( struct bpf_link *  link)

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

Parameters
[in]linkPointer to bpf_link structure.
Return values
EBPF_SUCCESSThe operation was successful.
EBPF_INVALID_OBJECTInvalid object was passed.

◆ ebpf_object_get_execution_type()

ebpf_execution_type_t ebpf_object_get_execution_type ( struct bpf_object *  object)

Get the execution type for an eBPF object file.

Parameters
[in]objectThe eBPF object file.
Returns
Execution type.

◆ ebpf_object_set_execution_type()

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

Set the execution type for an eBPF object file.

Parameters
[in]objectThe eBPF object file.
[in]execution_typeExecution type to set.
Return values
EBPF_SUCCESSThe operation was successful.
EBPF_INVALID_ARGUMENTOne 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]pathPath from which to unpin.
Return values
EBPF_SUCCESSThe 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]programPointer to the eBPF program.
[in]attach_typeOptionally, 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_sizeSize of the attach parameters.
[in]attach_parametersOptionally, attach parameters. This is an opaque flat buffer containing the attach parameters which is interpreted by the extension provider.
[out]linkPointer to ebpf_link structure.
Return values
EBPF_SUCCESSThe 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_fdAn eBPF program file descriptor.
[in]attach_typeOptionally, 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_sizeSize of the attach parameters.
[in]attach_parametersOptionally, attach parameters. This is an opaque flat buffer containing the attach parameters which is interpreted by the extension provider.
[out]linkPointer to ebpf_link structure.
Return values
EBPF_SUCCESSThe 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_fdFile descriptor of program to detach. If set to -1, this parameter is ignored.
[in]attach_typeThe attach type for attaching the program.
[in]attach_parameter_sizeSize of the attach parameter.
[in]attach_parameterPointer to attach parameter. This is an opaque flat buffer containing the attach parameters which is interpreted by the extension provider.
Return values
EBPF_SUCCESSThe operation was successful.
EBPF_INVALID_OBJECTInvalid 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]fdFile descriptor of an eBPF program.
[out]execution_typeOn success, contains the execution type.
[out]file_nameOn success, contains the file name.
[out]section_nameOn success, contains the section name.
Return values
EBPF_SUCCESSThe operation was successful.

Variable Documentation

◆ ebpf_fd_invalid

const fd_t ebpf_fd_invalid = -1