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 "ebpf_core_structs.h"
7 #include "ebpf_execution_type.h"
9 #include "ebpf_result.h"
10 
11 #include <specstrings.h>
12 #include <stdbool.h>
13 #include <stdint.h>
14 
15 #ifdef __cplusplus
16 #include <stdexcept>
17 #define EBPF_NO_EXCEPT noexcept
18 extern "C"
19 {
20 #else
21 #define EBPF_NO_EXCEPT
22 #endif
23 
24  typedef int32_t fd_t;
25  extern __declspec(selectany) const fd_t ebpf_fd_invalid = -1;
26  typedef intptr_t ebpf_handle_t;
27 
28  struct bpf_object;
29  struct bpf_program;
30  struct bpf_map;
31  struct bpf_link;
32 
41  _Must_inspect_result_ ebpf_result_t
43  fd_t fd,
44  _Out_ ebpf_execution_type_t* execution_type,
45  _Outptr_result_z_ const char** file_name,
46  _Outptr_result_z_ const char** section_name) EBPF_NO_EXCEPT;
47 
48  typedef struct _ebpf_stat
49  {
50  struct _ebpf_stat* next;
51  _Field_z_ const char* key;
52  int value;
54 
55  typedef struct _ebpf_section_info
56  {
58  _Field_z_ const char* section_name;
59  _Field_z_ const char* program_type_name;
60  _Field_z_ const char* program_name;
63  size_t raw_data_size;
64  _Field_size_(raw_data_size) char* raw_data;
67 
77  _Must_inspect_result_ ebpf_result_t
79  _In_z_ const char* file,
80  bool verbose,
81  _Outptr_result_maybenull_ ebpf_section_info_t** infos,
82  _Outptr_result_maybenull_z_ const char** error_message) EBPF_NO_EXCEPT;
83 
88  void
89  ebpf_free_sections(_In_opt_ _Post_invalid_ ebpf_section_info_t* infos) EBPF_NO_EXCEPT;
90 
99  uint32_t
101  _In_z_ const char* file,
102  _In_z_ const char* section,
103  _Outptr_result_maybenull_z_ const char** disassembly,
104  _Outptr_result_maybenull_z_ const char** error_message) EBPF_NO_EXCEPT;
105 
106  typedef struct
107  {
112 
128  _Success_(return == 0) uint32_t ebpf_api_elf_verify_section_from_file(
129  _In_z_ const char* file,
130  _In_z_ const char* section,
131  _In_opt_ const ebpf_program_type_t* program_type,
132  bool verbose,
133  _Outptr_result_maybenull_z_ const char** report,
134  _Outptr_result_maybenull_z_ const char** error_message,
136 
153  _Success_(return == 0) uint32_t ebpf_api_elf_verify_section_from_memory(
154  _In_reads_(data_length) const char* data,
155  size_t data_length,
156  _In_z_ const char* section,
157  _In_opt_ const ebpf_program_type_t* program_type,
158  bool verbose,
159  _Outptr_result_maybenull_z_ const char** report,
160  _Outptr_result_maybenull_z_ const char** error_message,
162 
167  void
168  ebpf_free_string(_In_opt_ _Post_invalid_ const char* string) EBPF_NO_EXCEPT;
169 
175  uint32_t
176  ebpf_api_unpin_object(const uint8_t* name, uint32_t name_length) EBPF_NO_EXCEPT;
177 
184  _Must_inspect_result_ ebpf_result_t
185  ebpf_object_unpin(_In_z_ const char* path) EBPF_NO_EXCEPT;
186 
195  _Must_inspect_result_ ebpf_result_t
197 
205  _Must_inspect_result_ ebpf_result_t
207 
218  _Must_inspect_result_ ebpf_result_t
220  _Out_ uint16_t* map_count,
221  _Outptr_result_buffer_maybenull_(*map_count) ebpf_map_info_t** map_info) EBPF_NO_EXCEPT;
222 
230  void
232  uint16_t map_count,
233  _In_opt_count_(map_count) _Post_ptr_invalid_ const ebpf_map_info_t* map_info) EBPF_NO_EXCEPT;
234 
243  ebpf_object_get_execution_type(_In_ const struct bpf_object* object) EBPF_NO_EXCEPT;
244 
254  _Must_inspect_result_ ebpf_result_t
255  ebpf_object_set_execution_type(_Inout_ struct bpf_object* object, ebpf_execution_type_t execution_type)
257 
274  _Must_inspect_result_ ebpf_result_t
276  _In_ const struct bpf_program* program,
277  _In_opt_ const ebpf_attach_type_t* attach_type,
278  _In_reads_bytes_opt_(attach_params_size) void* attach_parameters,
279  size_t attach_params_size,
280  _Outptr_ struct bpf_link** link) EBPF_NO_EXCEPT;
281 
298  _Must_inspect_result_ ebpf_result_t
300  fd_t program_fd,
301  _In_opt_ const ebpf_attach_type_t* attach_type,
302  _In_reads_bytes_opt_(attach_parameters_size) void* attach_parameters,
303  size_t attach_parameters_size,
304  _Outptr_ struct bpf_link** link) EBPF_NO_EXCEPT;
305 
315  _Must_inspect_result_ ebpf_result_t
316  ebpf_link_detach(_Inout_ struct bpf_link* link) EBPF_NO_EXCEPT;
317 
331  _Must_inspect_result_ ebpf_result_t
333  fd_t program_fd,
334  _In_ const ebpf_attach_type_t* attach_type,
335  _In_reads_bytes_(attach_parameter_size) void* attach_parameter,
336  size_t attach_parameter_size) EBPF_NO_EXCEPT;
337 
348  void
349  ebpf_link_close(_Frees_ptr_ struct bpf_link* link) EBPF_NO_EXCEPT;
350 
358  _Must_inspect_result_ ebpf_result_t
360 
371  _Must_inspect_result_ ebpf_result_t
373  _In_z_ const char* name,
376 
384  _Ret_maybenull_z_ const char*
386 
394  _Ret_maybenull_z_ const char*
396 
406  _Must_inspect_result_ ebpf_result_t
408  _In_z_ const char* start_path, _Out_writes_z_(EBPF_MAX_PIN_PATH_LENGTH) char* next_path) EBPF_NO_EXCEPT;
409 
411 
421  _Must_inspect_result_ ebpf_result_t
423 
424  typedef struct _ebpf_test_run_options
425  {
426  _Readable_bytes_(data_size_in) const uint8_t* data_in;
427  _Writable_bytes_(data_size_out) uint8_t* data_out;
428  size_t data_size_in;
429  size_t data_size_out;
430  _Readable_bytes_(context_size_in) const uint8_t* context_in;
431  _Writable_bytes_(context_size_out) uint8_t* context_out;
434  uint64_t return_value;
435  size_t repeat_count;
436  uint64_t duration;
437  uint32_t flags;
438  uint32_t cpu;
439  size_t batch_size;
441 
450  _Must_inspect_result_ ebpf_result_t
452 
453 #ifdef __cplusplus
454 }
455 #endif
#define bpf_map
Definition: bpf_helpers_platform.h:15
struct _ebpf_stat ebpf_stat_t
_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.
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.
void ebpf_free_string(const char *string) EBPF_NO_EXCEPT
Free memory for a string returned from an eBPF API.
struct _ebpf_test_run_options ebpf_test_run_options_t
_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.
_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.
uint32_t ebpf_api_unpin_object(const uint8_t *name, uint32_t name_length) EBPF_NO_EXCEPT
Dissociate a name with an object handle.
_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.
_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.
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.
void ebpf_free_sections(ebpf_section_info_t *infos) EBPF_NO_EXCEPT
Free memory returned from ebpf_enumerate_sections.
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.
_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.
_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.
_Must_inspect_result_ ebpf_result_t ebpf_object_unpin(const char *path) EBPF_NO_EXCEPT
Unpin the object from the specified path.
_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.
#define EBPF_NO_EXCEPT
Definition: ebpf_api.h:21
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.
_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.
_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.
struct _ebpf_section_info ebpf_section_info_t
_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.
int32_t fd_t
Definition: ebpf_api.h:24
_Must_inspect_result_ ebpf_result_t ebpf_close_fd(fd_t fd) EBPF_NO_EXCEPT
Close a file descriptor. Also close the underlying handle.
_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.
_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.
_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.
intptr_t ebpf_handle_t
Definition: ebpf_api.h:26
void ebpf_link_close(_Frees_ptr_ struct bpf_link *link) EBPF_NO_EXCEPT
_Must_inspect_result_ ebpf_result_t ebpf_api_close_handle(ebpf_handle_t handle) EBPF_NO_EXCEPT
Close an eBPF handle.
const fd_t ebpf_fd_invalid
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.
_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.
This file contains eBPF definitions common to eBPF core libraries as well as the eBPF API library.
#define EBPF_MAX_PIN_PATH_LENGTH
Definition: ebpf_core_structs.h:16
enum _ebpf_execution_type ebpf_execution_type_t
enum ebpf_result ebpf_result_t
GUID ebpf_attach_type_t
Definition: ebpf_windows.h:44
GUID ebpf_program_type_t
Definition: ebpf_windows.h:43
eBPF Map Information
Definition: ebpf_core_structs.h:22
Definition: ebpf_program_types.h:32
Definition: ebpf_api.h:56
struct _ebpf_section_info * next
Definition: ebpf_api.h:57
_Field_z_ const char * section_name
Definition: ebpf_api.h:58
_Field_z_ const char * program_name
Definition: ebpf_api.h:60
_Field_z_ const char * program_type_name
Definition: ebpf_api.h:59
ebpf_attach_type_t expected_attach_type
Definition: ebpf_api.h:62
size_t raw_data_size
Definition: ebpf_api.h:63
ebpf_stat_t * stats
Definition: ebpf_api.h:65
ebpf_program_type_t program_type
Definition: ebpf_api.h:61
_Field_size_(raw_data_size) char *raw_data
Definition: ebpf_api.h:49
struct _ebpf_stat * next
Definition: ebpf_api.h:50
_Field_z_ const char * key
Definition: ebpf_api.h:51
int value
Definition: ebpf_api.h:52
Definition: ebpf_api.h:425
uint64_t duration
Duration in nanoseconds of the program execution.
Definition: ebpf_api.h:436
size_t batch_size
Number of times to repeat the program in a batch.
Definition: ebpf_api.h:439
_Readable_bytes_(context_size_in) const uint8_t *context_in
Input context to the program.
_Writable_bytes_(context_size_out) uint8_t *context_out
Output context from the program.
uint64_t return_value
Return value from the program.
Definition: ebpf_api.h:434
size_t repeat_count
Number of times to repeat the program.
Definition: ebpf_api.h:435
size_t context_size_in
Size of input context.
Definition: ebpf_api.h:432
uint32_t cpu
CPU to run the program on.
Definition: ebpf_api.h:438
size_t data_size_in
Size of input data.
Definition: ebpf_api.h:428
size_t context_size_out
Maximum length of context_out on input and actual length of context_out on output.
Definition: ebpf_api.h:433
uint32_t flags
Flags to control the test run.
Definition: ebpf_api.h:437
_Readable_bytes_(data_size_in) const uint8_t *data_in
Input data to the program.
_Writable_bytes_(data_size_out) uint8_t *data_out
Output data from the program.
size_t data_size_out
Maximum length of data_out on input and actual length of data_out on output.
Definition: ebpf_api.h:429
Definition: ebpf_api.h:107
int total_warnings
Definition: ebpf_api.h:109
int total_unreachable
Definition: ebpf_api.h:108
int max_instruction_count
Definition: ebpf_api.h:110