eBPF for Windows
Go to the documentation of this file.
1 // Copyright (c) Microsoft Corporation
2 // SPDX-License-Identifier: MIT
4 #pragma once
6 #include "ebpf_core_structs.h"
7 #include "ebpf_execution_type.h"
9 #include "ebpf_result.h"
11 #include <specstrings.h>
12 #include <stdbool.h>
13 #include <stdint.h>
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
24  typedef int32_t fd_t;
25  extern __declspec(selectany) const fd_t ebpf_fd_invalid = -1;
26  typedef intptr_t ebpf_handle_t;
28  struct bpf_object;
29  struct bpf_program;
30  struct bpf_map;
31  struct bpf_link;
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;
48  typedef struct _ebpf_stat
49  {
50  struct _ebpf_stat* next;
51  _Field_z_ const char* key;
52  int value;
55  typedef struct _ebpf_section_info
56  {
58  _Field_z_ const char* section_name;
59  _Field_z_ const char* program_name;
62  size_t raw_data_size;
63  _Field_size_(raw_data_size) char* raw_data;
76  _Must_inspect_result_ ebpf_result_t
78  _In_z_ const char* file,
79  bool verbose,
80  _Outptr_result_maybenull_ ebpf_section_info_t** infos,
81  _Outptr_result_maybenull_z_ const char** error_message) EBPF_NO_EXCEPT;
87  void
88  ebpf_free_sections(_In_opt_ _Post_invalid_ ebpf_section_info_t* infos) EBPF_NO_EXCEPT;
98  uint32_t
100  _In_z_ const char* file,
101  _In_z_ const char* section,
102  _Outptr_result_maybenull_z_ const char** disassembly,
103  _Outptr_result_maybenull_z_ const char** error_message) EBPF_NO_EXCEPT;
105  typedef struct
106  {
127  _Success_(return == 0) uint32_t ebpf_api_elf_verify_section_from_file(
128  _In_z_ const char* file,
129  _In_z_ const char* section,
130  _In_opt_ const ebpf_program_type_t* program_type,
131  bool verbose,
132  _Outptr_result_maybenull_z_ const char** report,
133  _Outptr_result_maybenull_z_ const char** error_message,
152  _Success_(return == 0) uint32_t ebpf_api_elf_verify_section_from_memory(
153  _In_reads_(data_length) const char* data,
154  size_t data_length,
155  _In_z_ const char* section,
156  _In_opt_ const ebpf_program_type_t* program_type,
157  bool verbose,
158  _Outptr_result_maybenull_z_ const char** report,
159  _Outptr_result_maybenull_z_ const char** error_message,
166  void
167  ebpf_free_string(_In_opt_ _Post_invalid_ const char* string) EBPF_NO_EXCEPT;
174  uint32_t
175  ebpf_api_unpin_object(const uint8_t* name, uint32_t name_length) EBPF_NO_EXCEPT;
183  _Must_inspect_result_ ebpf_result_t
184  ebpf_object_unpin(_In_z_ const char* path) EBPF_NO_EXCEPT;
194  _Must_inspect_result_ ebpf_result_t
204  _Must_inspect_result_ ebpf_result_t
217  _Must_inspect_result_ ebpf_result_t
219  _Out_ uint16_t* map_count,
220  _Outptr_result_buffer_maybenull_(*map_count) ebpf_map_info_t** map_info) EBPF_NO_EXCEPT;
229  void
231  uint16_t map_count,
232  _In_opt_count_(map_count) _Post_ptr_invalid_ const ebpf_map_info_t* map_info) EBPF_NO_EXCEPT;
242  ebpf_object_get_execution_type(_In_ const struct bpf_object* object) EBPF_NO_EXCEPT;
253  _Must_inspect_result_ ebpf_result_t
254  ebpf_object_set_execution_type(_Inout_ struct bpf_object* object, ebpf_execution_type_t execution_type)
273  _Must_inspect_result_ ebpf_result_t
275  _In_ const struct bpf_program* program,
276  _In_opt_ const ebpf_attach_type_t* attach_type,
277  _In_reads_bytes_opt_(attach_params_size) void* attach_parameters,
278  size_t attach_params_size,
279  _Outptr_ struct bpf_link** link) EBPF_NO_EXCEPT;
297  _Must_inspect_result_ ebpf_result_t
299  fd_t program_fd,
300  _In_opt_ const ebpf_attach_type_t* attach_type,
301  _In_reads_bytes_opt_(attach_parameters_size) void* attach_parameters,
302  size_t attach_parameters_size,
303  _Outptr_ struct bpf_link** link) EBPF_NO_EXCEPT;
314  _Must_inspect_result_ ebpf_result_t
315  ebpf_link_detach(_Inout_ struct bpf_link* link) EBPF_NO_EXCEPT;
330  _Must_inspect_result_ ebpf_result_t
332  fd_t program_fd,
333  _In_ const ebpf_attach_type_t* attach_type,
334  _In_reads_bytes_(attach_parameter_size) void* attach_parameter,
335  size_t attach_parameter_size) EBPF_NO_EXCEPT;
347  void
348  ebpf_link_close(_Frees_ptr_ struct bpf_link* link) EBPF_NO_EXCEPT;
357  _Must_inspect_result_ ebpf_result_t
370  _Must_inspect_result_ ebpf_result_t
372  _In_z_ const char* name,
383  _Ret_maybenull_z_ const char*
393  _Ret_maybenull_z_ const char*
405  _Must_inspect_result_ ebpf_result_t
407  _In_z_ const char* start_path, _Out_writes_z_(EBPF_MAX_PIN_PATH_LENGTH) char* next_path) EBPF_NO_EXCEPT;
420  _Must_inspect_result_ ebpf_result_t
423  typedef struct _ebpf_test_run_options
424  {
425  _Readable_bytes_(data_size_in) const uint8_t* data_in;
426  _Writable_bytes_(data_size_out) uint8_t* data_out;
427  size_t data_size_in;
428  size_t data_size_out;
429  _Readable_bytes_(context_size_in) const uint8_t* context_in;
430  _Writable_bytes_(context_size_out) uint8_t* context_out;
433  uint64_t return_value;
434  size_t repeat_count;
435  uint64_t duration;
436  uint32_t flags;
437  uint32_t cpu;
438  size_t batch_size;
449  _Must_inspect_result_ ebpf_result_t
452 #ifdef __cplusplus
453 }
454 #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.
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.
Definition: ebpf_core_structs.h:15
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:21
Definition: ebpf_program_types.h:39
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:59
ebpf_attach_type_t expected_attach_type
Definition: ebpf_api.h:61
size_t raw_data_size
Definition: ebpf_api.h:62
ebpf_stat_t * stats
Definition: ebpf_api.h:64
ebpf_program_type_t program_type
Definition: ebpf_api.h:60
_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:424
uint64_t duration
Duration in nanoseconds of the program execution.
Definition: ebpf_api.h:435
size_t batch_size
Number of times to repeat the program in a batch.
Definition: ebpf_api.h:438
_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:433
size_t repeat_count
Number of times to repeat the program.
Definition: ebpf_api.h:434
size_t context_size_in
Size of input context.
Definition: ebpf_api.h:431
uint32_t cpu
CPU to run the program on.
Definition: ebpf_api.h:437
size_t data_size_in
Size of input data.
Definition: ebpf_api.h:427
size_t context_size_out
Maximum length of context_out on input and actual length of context_out on output.
Definition: ebpf_api.h:432
uint32_t flags
Flags to control the test run.
Definition: ebpf_api.h:436
_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:428
Definition: ebpf_api.h:106
int total_warnings
Definition: ebpf_api.h:108
int total_unreachable
Definition: ebpf_api.h:107
int max_instruction_count
Definition: ebpf_api.h:109