ebpf_api.h

Go to the documentation of this file.

// Copyright (c) eBPF for Windows contributors
// SPDX-License-Identifier: MIT
 
#pragma once
 
#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 <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
#include <stdexcept>
#define EBPF_NO_EXCEPT noexcept
extern "C"
{
#else
#define EBPF_NO_EXCEPT
#endif
 
    typedef int32_t fd_t;
    extern __declspec(selectany) const fd_t ebpf_fd_invalid = -1;
    typedef intptr_t ebpf_handle_t;
 
    struct bpf_object;
    struct bpf_program;
    struct bpf_map;
    struct bpf_link;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_program_query_info(
        fd_t fd,
        _Out_ ebpf_execution_type_t* execution_type,
        _Outptr_result_z_ const char** file_name,
        _Outptr_result_z_ const char** section_name) EBPF_NO_EXCEPT;
 
    typedef struct _ebpf_stat
    {
        struct _ebpf_stat* next;
        _Field_z_ const char* key;
        int value;
    } ebpf_stat_t;
 
    typedef struct _ebpf_api_program_info
    {
        struct _ebpf_api_program_info* next;
        _Field_z_ const char* section_name;
        _Field_z_ const char* program_name;
        ebpf_program_type_t program_type;
        ebpf_attach_type_t expected_attach_type;
        size_t raw_data_size;
        _Field_size_(raw_data_size) char* raw_data;
        ebpf_stat_t* stats;
        size_t offset_in_section; // Byte offset of program in section.
    } ebpf_api_program_info_t;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_enumerate_programs(
        _In_z_ const char* file,
        bool verbose,
        _Outptr_result_maybenull_ ebpf_api_program_info_t** infos,
        _Outptr_result_maybenull_z_ const char** error_message) EBPF_NO_EXCEPT;
 
    void
    ebpf_free_programs(_In_opt_ _Post_invalid_ ebpf_api_program_info_t* infos) EBPF_NO_EXCEPT;
 
    uint32_t
    ebpf_api_elf_disassemble_program(
        _In_z_ const char* file,
        _In_opt_z_ const char* section_name,
        _In_opt_z_ const char* program_name,
        _Outptr_result_maybenull_z_ const char** disassembly,
        _Outptr_result_maybenull_z_ const char** error_message) EBPF_NO_EXCEPT;
 
    typedef struct
    {
        int total_unreachable;
        int total_warnings;
        int max_loop_count;
    } ebpf_api_verifier_stats_t;
 
    typedef struct _ebpf_verifier_map_info
    {
        uint32_t instruction_offset; 
        int32_t helper_id;           
        const char* map_name;        
        uint32_t map_type;           
        uint32_t value_size;         
        uint32_t max_entries;        
        bool is_inner_map_template;  
    } ebpf_verifier_map_info_t;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_get_map_annotations_from_verifier(
        _Outptr_result_buffer_maybenull_(*count) const ebpf_verifier_map_info_t** annotations,
        _Out_ size_t* count) EBPF_NO_EXCEPT;
 
    typedef enum _ebpf_verification_verbosity
    {
        EBPF_VERIFICATION_VERBOSITY_NORMAL = 0,
        EBPF_VERIFICATION_VERBOSITY_INFORMATIONAL = 1,
        EBPF_VERIFICATION_VERBOSITY_VERBOSE = 2,
    } ebpf_verification_verbosity_t;
 
    _Success_(return == 0) uint32_t ebpf_api_elf_verify_program_from_file(
        _In_z_ const char* file,
        _In_opt_z_ const char* section_name,
        _In_opt_z_ const char* program_name,
        _In_opt_ const ebpf_program_type_t* program_type,
        ebpf_verification_verbosity_t verbosity,
        _Outptr_result_maybenull_z_ const char** report,
        _Outptr_result_maybenull_z_ const char** error_message,
        _Out_opt_ ebpf_api_verifier_stats_t* stats) EBPF_NO_EXCEPT;
 
    _Success_(return == 0) uint32_t ebpf_api_elf_verify_program_from_memory(
        _In_reads_(data_length) const char* data,
        size_t data_length,
        _In_opt_z_ const char* section_name,
        _In_opt_z_ const char* program_name,
        _In_opt_ const ebpf_program_type_t* program_type,
        ebpf_verification_verbosity_t verbosity,
        _Outptr_result_maybenull_z_ const char** report,
        _Outptr_result_maybenull_z_ const char** error_message,
        _Out_opt_ ebpf_api_verifier_stats_t* stats) EBPF_NO_EXCEPT;
 
    void
    ebpf_free_string(_In_opt_ _Post_invalid_ const char* string) EBPF_NO_EXCEPT;
 
    uint32_t
    ebpf_api_unpin_object(const uint8_t* name, uint32_t name_length) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_object_unpin(_In_z_ const char* path) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_object_get_info_by_fd(
        fd_t bpf_fd,
        _Inout_updates_bytes_to_opt_(*info_size, *info_size) void* info,
        _Inout_opt_ uint32_t* info_size,
        _Out_opt_ ebpf_object_type_t* type) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_api_unlink_program(ebpf_handle_t link_handle) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_api_close_handle(ebpf_handle_t handle) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_api_get_pinned_map_info(
        _Out_ uint16_t* map_count,
        _Outptr_result_buffer_maybenull_(*map_count) ebpf_map_info_t** map_info) EBPF_NO_EXCEPT;
 
    void
    ebpf_api_map_info_free(
        uint16_t map_count,
        _In_opt_count_(map_count) _Post_ptr_invalid_ const ebpf_map_info_t* map_info) EBPF_NO_EXCEPT;
 
    ebpf_execution_type_t
    ebpf_object_get_execution_type(_In_ const struct bpf_object* object) EBPF_NO_EXCEPT;
 
    _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;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_object_load_native_by_fds(
        _In_z_ const char* file_name,
        _Inout_ size_t* count_of_maps,
        _Out_writes_opt_(*count_of_maps) fd_t* map_fds,
        _Inout_ size_t* count_of_programs,
        _Out_writes_opt_(*count_of_programs) fd_t* program_fds) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_program_attach(
        _In_ const struct bpf_program* program,
        _In_opt_ const ebpf_attach_type_t* attach_type,
        _In_reads_bytes_opt_(attach_params_size) void* attach_parameters,
        size_t attach_params_size,
        _Outptr_opt_ struct bpf_link** link) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_program_attach_by_fd(
        fd_t program_fd,
        _In_opt_ const ebpf_attach_type_t* attach_type,
        _In_reads_bytes_opt_(attach_parameters_size) void* attach_parameters,
        size_t attach_parameters_size,
        _Outptr_opt_ struct bpf_link** link) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_program_attach_by_fds(
        fd_t program_fd,
        _In_opt_ const ebpf_attach_type_t* attach_type,
        _In_reads_bytes_opt_(attach_parameters_size) void* attach_parameters,
        size_t attach_parameters_size,
        _Out_opt_ fd_t* link) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_link_detach(_Inout_ struct bpf_link* link) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_program_detach(
        fd_t program_fd,
        _In_ const ebpf_attach_type_t* attach_type,
        _In_reads_bytes_(attach_parameter_size) void* attach_parameter,
        size_t attach_parameter_size) EBPF_NO_EXCEPT;
 
    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;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_duplicate_fd(fd_t fd, _Out_ fd_t* dup) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_get_program_type_by_name(
        _In_z_ const char* name,
        _Out_ ebpf_program_type_t* program_type,
        _Out_ ebpf_attach_type_t* expected_attach_type) EBPF_NO_EXCEPT;
 
    _Ret_maybenull_z_ const char*
    ebpf_get_program_type_name(_In_ const ebpf_program_type_t* program_type) EBPF_NO_EXCEPT;
 
    _Ret_maybenull_z_ const char*
    ebpf_get_attach_type_name(_In_ const ebpf_attach_type_t* attach_type) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_get_next_pinned_object_path(
        _In_z_ const char* start_path,
        _Out_writes_z_(next_path_len) char* next_path,
        size_t next_path_len,
        _Inout_ ebpf_object_type_t* type) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_canonicalize_pin_path(_Out_writes_(output_size) char* output, size_t output_size, _In_z_ const char* input)
        EBPF_NO_EXCEPT;
 
    typedef struct _ebpf_program_info ebpf_program_info_t;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_get_program_info_from_verifier(_Outptr_ const ebpf_program_info_t** program_info) EBPF_NO_EXCEPT;
 
    typedef struct _ebpf_test_run_options
    {
        _Readable_bytes_(data_size_in) const uint8_t* data_in; 
        _Writable_bytes_(data_size_out) uint8_t* data_out;     
        size_t data_size_in;                                   
        size_t data_size_out; 
        _Readable_bytes_(context_size_in) const uint8_t* context_in; 
        _Writable_bytes_(context_size_out) uint8_t* context_out;     
        size_t context_size_in;                                      
        size_t context_size_out; 
        uint64_t return_value;   
        size_t repeat_count;     
        uint64_t duration;       
        uint32_t flags;          
        uint32_t cpu;            
        size_t batch_size;       
    } ebpf_test_run_options_t;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_program_test_run(fd_t program_fd, _Inout_ ebpf_test_run_options_t* options) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_ring_buffer_map_write(
        fd_t ring_buffer_map_fd, _In_reads_bytes_(data_length) const void* data, size_t data_length) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_ring_buffer_map_map_buffer(
        fd_t map_fd,
        _Outptr_result_maybenull_ void** consumer,
        _Outptr_result_maybenull_ const void** producer,
        _Outptr_result_buffer_maybenull_(*data_size) const uint8_t** data,
        _Out_ size_t* data_size) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_ring_buffer_map_unmap_buffer(
        fd_t map_fd, _In_ void* consumer, _In_ const void* producer, _In_ const void* data) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_map_set_wait_handle(fd_t map_fd, uint64_t index, ebpf_handle_t handle) EBPF_NO_EXCEPT;
 
    _Ret_maybenull_ const ebpf_program_type_t*
    ebpf_get_ebpf_program_type(bpf_prog_type_t bpf_program_type) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_get_ebpf_attach_type(bpf_attach_type_t bpf_attach_type, _Out_ ebpf_attach_type_t* ebpf_attach_type)
        EBPF_NO_EXCEPT;
 
    bpf_prog_type_t
    ebpf_get_bpf_program_type(_In_ const ebpf_program_type_t* program_type) EBPF_NO_EXCEPT;
 
    bpf_attach_type_t
    ebpf_get_bpf_attach_type(_In_ const ebpf_attach_type_t* ebpf_attach_type) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_perf_event_array_map_write(
        fd_t perf_event_array_map_fd,
        _In_reads_bytes_(data_length) const void* data,
        size_t data_length) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_program_synchronize() EBPF_NO_EXCEPT;
 
    //
    // Windows-specific Ring Buffer APIs
    //
 
    // Forward declarations and types needed for ring buffer APIs.
    struct ring_buffer;
 
    typedef struct _ebpf_ring_buffer_consumer_page
    {
        volatile uint64_t consumer_offset; 
    } ebpf_ring_buffer_consumer_page_t;
 
    typedef struct _ebpf_ring_buffer_producer_page
    {
        volatile uint64_t producer_offset; 
    } ebpf_ring_buffer_producer_page_t;
 
    typedef struct _ebpf_perf_event_array_producer_page
    {
        volatile uint64_t producer_offset; 
        uint64_t pad[7];                   
        volatile uint64_t lost_records;    
    } ebpf_perf_event_array_producer_page_t;
 
    // Compile-time asserts: perf event array producer page must begin with ring buffer producer page layout.
    static_assert(
        offsetof(ebpf_perf_event_array_producer_page_t, producer_offset) ==
            offsetof(ebpf_ring_buffer_producer_page_t, producer_offset),
        "ebpf_perf_event_array_producer_page_t.producer_offset must be at the same offset as in "
        "ebpf_ring_buffer_producer_page_t");
    static_assert(
        sizeof(ebpf_ring_buffer_producer_page_t) <= sizeof(ebpf_perf_event_array_producer_page_t),
        "ebpf_perf_event_array_producer_page_t must be at least as large as ebpf_ring_buffer_producer_page_t");
    static_assert(
        offsetof(ebpf_perf_event_array_producer_page_t, lost_records) >= 64,
        "lost_records must be in a separate cache line from producer_offset");
 
    typedef int (*ring_buffer_sample_fn)(void* ctx, void* data, size_t size);
 
    struct ebpf_ring_buffer_opts
    {
        size_t sz;      /* Size of this struct, for forward/backward compatibility (must match ring_buffer_opts). */
        uint64_t flags; /* Windows-specific ring buffer option flags. */
    };
 
    enum ebpf_ring_buffer_flags
    {
        EBPF_RINGBUF_FLAG_AUTO_CALLBACK = (uint64_t)1 << 0, /* Automatically invoke callback for each record. */
    };
 
    _Ret_maybenull_ struct ring_buffer*
    ebpf_ring_buffer__new(
        int map_fd,
        ring_buffer_sample_fn sample_cb,
        _In_opt_ void* ctx,
        _In_opt_ const struct ebpf_ring_buffer_opts* opts) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ _Success_(return == EBPF_SUCCESS) ebpf_result_t ebpf_ring_buffer_get_buffer(
        _In_ struct ring_buffer* rb,
        uint32_t index,
        _Outptr_result_maybenull_ ebpf_ring_buffer_consumer_page_t** consumer_page,
        _Outptr_result_maybenull_ const ebpf_ring_buffer_producer_page_t** producer_page,
        _Outptr_result_buffer_maybenull_(*data_size) const uint8_t** data,
        _Out_ uint64_t* data_size) EBPF_NO_EXCEPT;
 
    ebpf_handle_t
    ebpf_ring_buffer_get_wait_handle(_In_ struct ring_buffer* rb) EBPF_NO_EXCEPT;
 
    //
    // Windows-specific Perf Buffer APIs
    //
 
    struct ebpf_perf_buffer_opts
    {
        size_t sz;      /* size of this struct, for forward/backward compatibility */
        uint64_t flags; /* perf buffer option flags */
    };
 
    enum ebpf_perf_buffer_flags
    {
        EBPF_PERFBUF_FLAG_AUTO_CALLBACK = (uint64_t)1 << 0, /* Automatically invoke callback for each record */
    };
    typedef void (*perf_buffer_sample_fn)(void* ctx, int cpu, void* data, uint32_t size);
    typedef void (*perf_buffer_lost_fn)(void* ctx, int cpu, uint64_t cnt);
 
    _Ret_maybenull_ struct perf_buffer*
    ebpf_perf_buffer__new(
        int map_fd,
        size_t page_cnt,
        perf_buffer_sample_fn sample_cb,
        perf_buffer_lost_fn lost_cb,
        _In_opt_ void* ctx,
        _In_opt_ const struct ebpf_perf_buffer_opts* opts) EBPF_NO_EXCEPT;
 
    ebpf_handle_t
    ebpf_perf_buffer_get_wait_handle(_In_ const struct perf_buffer* pb) EBPF_NO_EXCEPT;
 
    _Must_inspect_result_ ebpf_result_t
    ebpf_api_get_data_section(
        _In_z_ const char* file_path,
        _In_z_ const char* section_name,
        _Out_writes_bytes_opt_(*data_size) uint8_t* data,
        _Inout_ size_t* data_size) EBPF_NO_EXCEPT;
 
#ifdef __cplusplus
}
#endif