eBPF for Windows
ebpf_api.h
Go to the documentation of this file.
1 // Copyright (c) Microsoft Corporation
2 // SPDX-License-Identifier: MIT
3 
4 #pragma once
5 
6 #include <stdbool.h>
7 #include <stdint.h>
8 #include "ebpf_core_structs.h"
9 #include "ebpf_execution_type.h"
11 #include "ebpf_result.h"
12 
13 #ifdef __cplusplus
14 #include <stdexcept>
15 #define EBPF_NO_EXCEPT noexcept
16 extern "C"
17 {
18 #else
19 #define EBPF_NO_EXCEPT
20 #endif
21 
22  typedef int32_t fd_t;
23  extern __declspec(selectany) const fd_t ebpf_fd_invalid = -1;
24  typedef intptr_t ebpf_handle_t;
25 
26  struct bpf_object;
27  struct bpf_program;
28  struct bpf_map;
29  struct bpf_link;
30 
41  fd_t fd,
42  _Out_ ebpf_execution_type_t* execution_type,
43  _Outptr_result_z_ const char** file_name,
44  _Outptr_result_z_ const char** section_name);
45 
46  typedef struct _ebpf_stat
47  {
48  struct _ebpf_stat* next;
49  _Field_z_ const char* key;
50  int value;
51  } ebpf_stat_t;
52 
53  typedef struct _ebpf_section_info
54  {
56  _Field_z_ const char* section_name;
57  _Field_z_ const char* program_type_name;
58  _Field_z_ const char* program_name;
61  size_t raw_data_size;
62  _Field_size_(raw_data_size) char* raw_data;
65 
77  _In_z_ const char* file,
78  bool verbose,
79  _Outptr_result_maybenull_ ebpf_section_info_t** infos,
80  _Outptr_result_maybenull_z_ const char** error_message);
81 
86  void
87  ebpf_free_sections(_In_opt_ ebpf_section_info_t* infos);
88 
97  uint32_t
99  _In_z_ const char* file,
100  _In_z_ const char* section,
101  _Outptr_result_maybenull_z_ const char** disassembly,
102  _Outptr_result_maybenull_z_ const char** error_message);
103 
104  typedef struct
105  {
110 
126  _Success_(return == 0) uint32_t ebpf_api_elf_verify_section_from_file(
127  _In_z_ const char* file,
128  _In_z_ const char* section,
129  _In_opt_ const ebpf_program_type_t* program_type,
130  bool verbose,
131  _Outptr_result_maybenull_z_ const char** report,
132  _Outptr_result_maybenull_z_ const char** error_message,
133  _Out_opt_ ebpf_api_verifier_stats_t* stats);
134 
151  _Success_(return == 0) uint32_t ebpf_api_elf_verify_section_from_memory(
152  _In_reads_(data_length) const char* data,
153  size_t data_length,
154  _In_z_ const char* section,
155  _In_opt_ const ebpf_program_type_t* program_type,
156  bool verbose,
157  _Outptr_result_maybenull_z_ const char** report,
158  _Outptr_result_maybenull_z_ const char** error_message,
159  _Out_opt_ ebpf_api_verifier_stats_t* stats);
160 
165  void
166  ebpf_free_string(_In_opt_ _Post_invalid_ const char* string);
167 
173  uint32_t
174  ebpf_api_unpin_object(const uint8_t* name, uint32_t name_length);
175 
183  ebpf_object_unpin(_In_z_ const char* path);
184 
191  uint32_t
192  ebpf_api_get_pinned_map(const uint8_t* name, uint32_t name_length, ebpf_handle_t* handle);
193 
204 
214 
227  _Out_ uint16_t* map_count, _Outptr_result_buffer_maybenull_(*map_count) ebpf_map_info_t** map_info);
228 
236  void
238  uint16_t map_count, _In_opt_count_(map_count) _Post_ptr_invalid_ const ebpf_map_info_t* map_info);
239 
248  ebpf_object_get_execution_type(_In_ struct bpf_object* object);
249 
260  ebpf_object_set_execution_type(_In_ struct bpf_object* object, ebpf_execution_type_t execution_type);
261 
280  _In_ const struct bpf_program* program,
281  _In_opt_ const ebpf_attach_type_t* attach_type,
282  _In_reads_bytes_opt_(attach_params_size) void* attach_parameters,
283  _In_ size_t attach_params_size,
284  _Outptr_ struct bpf_link** link);
285 
304  fd_t program_fd,
305  _In_opt_ const ebpf_attach_type_t* attach_type,
306  _In_reads_bytes_opt_(attach_parameters_size) void* attach_parameters,
307  _In_ size_t attach_parameters_size,
308  _Outptr_ struct bpf_link** link);
309 
320  ebpf_link_detach(_In_ struct bpf_link* link);
321 
337  fd_t program_fd,
338  _In_ const ebpf_attach_type_t* attach_type,
339  _In_reads_bytes_(attach_parameter_size) void* attach_parameter,
340  size_t attach_parameter_size) EBPF_NO_EXCEPT;
341 
355  ebpf_link_close(_In_ _Post_invalid_ struct bpf_link* link);
356 
365  ebpf_close_fd(fd_t fd);
366 
379  _In_z_ const char* name,
382 
390  _Ret_maybenull_z_ const char*
392 
400  _Ret_maybenull_z_ const char*
401  ebpf_get_attach_type_name(_In_ const ebpf_attach_type_t* attach_type);
402 
414  _In_z_ const char* start_path, _Out_writes_z_(EBPF_MAX_PIN_PATH_LENGTH) char* next_path);
415 
417 
428  ebpf_get_program_info_from_verifier(_Outptr_ const ebpf_program_info_t** program_info);
429 
430 #ifdef __cplusplus
431 }
432 #endif
ebpf_link_close
ebpf_result_t ebpf_link_close(struct bpf_link *link)
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.
ebpf_api_verifier_stats_t
Definition: ebpf_api.h:104
_ebpf_section_info::raw_data_size
size_t raw_data_size
Definition: ebpf_api.h:61
_ebpf_section_info::expected_attach_type
ebpf_attach_type_t expected_attach_type
Definition: ebpf_api.h:60
_ebpf_program_info
Definition: ebpf_program_types.h:41
ebpf_handle_t
intptr_t ebpf_handle_t
Definition: ebpf_api.h:24
ebpf_execution_type_t
enum _ebpf_execution_type ebpf_execution_type_t
ebpf_free_sections
void ebpf_free_sections(ebpf_section_info_t *infos)
Free memory returned from ebpf_enumerate_sections.
_ebpf_stat
Definition: ebpf_api.h:46
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.
_ebpf_section_info::_Field_size_
_Field_size_(raw_data_size) char *raw_data
ebpf_program_query_info
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.
ebpf_object_set_execution_type
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.
ebpf_api_verifier_stats_t::max_instruction_count
int max_instruction_count
Definition: ebpf_api.h:108
_ebpf_stat::value
int value
Definition: ebpf_api.h:50
ebpf_enumerate_sections
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.
_ebpf_section_info::stats
ebpf_stat_t * stats
Definition: ebpf_api.h:63
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.
ebpf_section_info_t
struct _ebpf_section_info ebpf_section_info_t
ebpf_program_attach_type_guids.h
_ebpf_section_info::program_type
ebpf_program_type_t program_type
Definition: ebpf_api.h:59
ebpf_api_verifier_stats_t::total_warnings
int total_warnings
Definition: ebpf_api.h:107
ebpf_fd_invalid
const fd_t ebpf_fd_invalid
ebpf_free_string
void ebpf_free_string(const char *string)
Free memory for a string returned from an eBPF API.
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.
fd_t
int32_t fd_t
Definition: ebpf_api.h:22
ebpf_get_program_type_by_name
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.
ebpf_api_get_pinned_map
uint32_t ebpf_api_get_pinned_map(const uint8_t *name, uint32_t name_length, ebpf_handle_t *handle)
Find a map given its associated name.
ebpf_program_type_t
GUID ebpf_program_type_t
Definition: ebpf_windows.h:38
ebpf_close_fd
ebpf_result_t ebpf_close_fd(fd_t fd)
Close a file descriptor. Also close the underlying handle.
ebpf_api_verifier_stats_t::total_unreachable
int total_unreachable
Definition: ebpf_api.h:106
ebpf_core_structs.h
ebpf_program_attach_by_fd
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.
ebpf_program_detach
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.
_ebpf_section_info
Definition: ebpf_api.h:53
_ebpf_map_info
eBPF Map Information
Definition: ebpf_core_structs.h:18
ebpf_api_unlink_program
ebpf_result_t ebpf_api_unlink_program(ebpf_handle_t link_handle)
Detach the eBPF program from the link.
_ebpf_section_info::program_type_name
const _Field_z_ char * program_type_name
Definition: ebpf_api.h:57
ebpf_stat_t
struct _ebpf_stat ebpf_stat_t
ebpf_get_program_info_from_verifier
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.
ebpf_execution_type.h
_ebpf_stat::key
const _Field_z_ char * key
Definition: ebpf_api.h:49
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.
ebpf_object_unpin
ebpf_result_t ebpf_object_unpin(const char *path)
Unpin the object from the specified path.
EBPF_NO_EXCEPT
#define EBPF_NO_EXCEPT
Definition: ebpf_api.h:19
ebpf_api_get_pinned_map_info
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.
ebpf_api_close_handle
ebpf_result_t ebpf_api_close_handle(ebpf_handle_t handle)
Close an eBPF handle.
ebpf_result_t
enum ebpf_result ebpf_result_t
_ebpf_section_info::section_name
const _Field_z_ char * section_name
Definition: ebpf_api.h:56
bpf_map
#define bpf_map
Definition: bpf_helpers_platform.h:10
EBPF_MAX_PIN_PATH_LENGTH
#define EBPF_MAX_PIN_PATH_LENGTH
Definition: ebpf_core_structs.h:13
ebpf_link_detach
ebpf_result_t ebpf_link_detach(struct bpf_link *link)
Detach an eBPF program from an attach point represented by the bpf_link structure.
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.
ebpf_get_next_pinned_program_path
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.
ebpf_program_attach
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.
_ebpf_stat::next
struct _ebpf_stat * next
Definition: ebpf_api.h:48
ebpf_attach_type_t
GUID ebpf_attach_type_t
Definition: ebpf_windows.h:39
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.
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.
_ebpf_section_info::program_name
const _Field_z_ char * program_name
Definition: ebpf_api.h:58
ebpf_result.h
_ebpf_section_info::next
struct _ebpf_section_info * next
Definition: ebpf_api.h:55