ebpf_extension.h File Reference

#include "ebpf_result.h"
#include "ebpf_structs.h"
#include "ebpf_windows.h"

Go to the source code of this file.

Data Structures
struct	_ebpf_extension_dispatch_table
struct	_ebpf_extension_program_dispatch_table
struct	_ebpf_extension_data
struct	_ebpf_attach_provider_data
struct	_ebpf_execution_context_state
struct	_ebpf_base_map_provider_properties
struct	_ebpf_map_provider_dispatch_table
struct	_ebpf_map_client_dispatch_table
struct	_ebpf_map_provider_data
	Custom map provider data. More...
struct	_ebpf_map_client_data
	Custom map client data. More...

Macros
#define	EBPF_MAP_OPERATION_HELPER   0x01 /* Called by a BPF program. */
#define	EBPF_MAP_OPERATION_UPDATE   0x02 /* Update operation. */
#define	EBPF_MAP_OPERATION_MAP_CLEANUP   0x04 /* Map cleanup operation. */
#define	EBPF_LINK_DISPATCH_TABLE_FUNCTION_COUNT_1   4
#define	EBPF_LINK_DISPATCH_TABLE_FUNCTION_COUNT_CURRENT    EBPF_LINK_DISPATCH_TABLE_FUNCTION_COUNT_1
	Current number of functions in the dispatch table./*#end#*‍/.
#define	EBPF_CONTEXT_HEADER   uint64_t context_header[8]
#define	EBPF_CONTEXT_HEADER_SIZE   (sizeof(uint64_t) * 8)
#define	MAP_CONTEXT(map_pointer, offset)   ((void**)(((uint8_t*)(map_pointer)) + (offset)))

Typedefs
typedef ebpf_result_t(*	_ebpf_extension_dispatch_function) ()
typedef uint64_t	epoch_state_t[4]
typedef struct _ebpf_extension_dispatch_table	ebpf_extension_dispatch_table_t
typedef ebpf_result_t(*	ebpf_program_invoke_function_t) (const void *extension_client_binding_context, _Inout_ void *program_context, uint32_t *result)
	Invoke the eBPF program.
typedef ebpf_result_t(*	ebpf_program_batch_begin_invoke_function_t) (size_t state_size, _Out_writes_(state_size) void *state)
	Prepare the eBPF program for batch invocation.
typedef ebpf_result_t(*	ebpf_program_batch_invoke_function_t) (const void *extension_client_binding_context, _Inout_ void *program_context, uint32_t *result, const void *state)
	Invoke the eBPF program in batch mode.
typedef ebpf_result_t(*	ebpf_program_batch_end_invoke_function_t) (_Inout_ void *state)
	Clean up the eBPF program after batch invocation.
typedef enum _ebpf_link_dispatch_table_version	ebpf_link_dispatch_table_version_t
typedef struct _ebpf_extension_program_dispatch_table	ebpf_extension_program_dispatch_table_t
typedef struct _ebpf_extension_data	ebpf_extension_data_t
typedef struct _ebpf_attach_provider_data	ebpf_attach_provider_data_t
typedef struct _ebpf_execution_context_state	ebpf_execution_context_state_t
typedef ebpf_result_t(*	ebpf_process_map_create_t) (void *binding_context, uint32_t map_type, uint32_t key_size, uint32_t value_size, uint32_t max_entries, uint32_t *actual_value_size, void **map_context)
	Process map creation notification.
typedef void(*	ebpf_process_map_delete_t) (void *binding_context, void *map_context)
	Process a map delete notification.
typedef ebpf_result_t(*	ebpf_process_map_find_element_t) (void *binding_context, void *map_context, size_t key_size, _In_reads_opt_(key_size) const uint8_t *key, size_t in_value_size, _In_reads_(in_value_size) const uint8_t *in_value, size_t out_value_size, _Out_writes_opt_(out_value_size) uint8_t *out_value, uint32_t flags)
	Find (lookup) an element in a provider-backed map.
typedef ebpf_result_t(*	ebpf_process_map_add_element_t) (void *binding_context, void *map_context, size_t key_size, _In_reads_opt_(key_size) const uint8_t *key, size_t in_value_size, _In_reads_(in_value_size) const uint8_t *in_value, size_t out_value_size, _Out_writes_opt_(out_value_size) uint8_t *out_value, uint32_t flags)
	Add or update (insert/replace) an element in a provider-backed map.
typedef ebpf_result_t(*	ebpf_process_map_delete_element_t) (void *binding_context, void *map_context, size_t key_size, _In_reads_opt_(key_size) const uint8_t *key, size_t value_size, _In_reads_(value_size) const uint8_t *value, uint32_t flags)
	Delete an element from a provider-backed map.
typedef ebpf_result_t(*	ebpf_map_associate_program_type_t) (void *binding_context, void *map_context, const ebpf_program_type_t *program_type)
	Associate a program type with the map, which allows the map to be used by programs of that type.
typedef struct _ebpf_base_map_provider_properties	ebpf_base_map_provider_properties_t
typedef struct _ebpf_map_provider_dispatch_table	ebpf_base_map_provider_dispatch_table_t
typedef uint32_t	tag
typedef void(*	ebpf_epoch_free_t) (void *memory)
	Free memory under epoch control.
typedef void(*	ebpf_epoch_free_cache_aligned_t) (void *pointer)
	Free memory under epoch control.
typedef void(*	ebpf_epoch_enter_t) (void *epoch_state)
	Enter an epoch-protected region.
typedef void(*	ebpf_epoch_exit_t) (void *epoch_state)
	Exit an epoch-protected region.
typedef ebpf_result_t(*	ebpf_map_find_element_t) (const void *map, const uint8_t *key, uint8_t **value)
	Find an element in an eBPF map (client/runtime helper version).
typedef struct _ebpf_map_client_dispatch_table	ebpf_base_map_client_dispatch_table_t
typedef struct _ebpf_map_provider_data	ebpf_map_provider_data_t
	Custom map provider data.
typedef struct _ebpf_map_client_data	ebpf_map_client_data_t
	Custom map client data.

Enumerations
enum	_ebpf_link_dispatch_table_version { EBPF_LINK_DISPATCH_TABLE_VERSION_1 = 1 , EBPF_LINK_DISPATCH_TABLE_VERSION_CURRENT }

Functions
typedef	_Ret_writes_maybenull_ (size) void *(*ebpf_epoch_allocate_with_tag_t)(size_t size
	Allocate memory under epoch control.

Macro Definition Documentation

EBPF_CONTEXT_HEADER

#define EBPF_CONTEXT_HEADER   uint64_t context_header[8]

EBPF_CONTEXT_HEADER_SIZE

#define EBPF_CONTEXT_HEADER_SIZE   (sizeof(uint64_t) * 8)

EBPF_LINK_DISPATCH_TABLE_FUNCTION_COUNT_1

#define EBPF_LINK_DISPATCH_TABLE_FUNCTION_COUNT_1   4

EBPF_LINK_DISPATCH_TABLE_FUNCTION_COUNT_CURRENT

#define EBPF_LINK_DISPATCH_TABLE_FUNCTION_COUNT_CURRENT    EBPF_LINK_DISPATCH_TABLE_FUNCTION_COUNT_1

Current number of functions in the dispatch table./*#end#*‍/.

EBPF_MAP_OPERATION_HELPER

#define EBPF_MAP_OPERATION_HELPER   0x01 /* Called by a BPF program. */

EBPF_MAP_OPERATION_MAP_CLEANUP

#define EBPF_MAP_OPERATION_MAP_CLEANUP   0x04 /* Map cleanup operation. */

EBPF_MAP_OPERATION_UPDATE

#define EBPF_MAP_OPERATION_UPDATE   0x02 /* Update operation. */

MAP_CONTEXT

#define MAP_CONTEXT	(		map_pointer,
			offset
	)		((void**)(((uint8_t*)(map_pointer)) + (offset)))

Typedef Documentation

_ebpf_extension_dispatch_function

typedef ebpf_result_t(* _ebpf_extension_dispatch_function) ()

ebpf_attach_provider_data_t

typedef struct _ebpf_attach_provider_data ebpf_attach_provider_data_t

ebpf_base_map_client_dispatch_table_t

typedef struct _ebpf_map_client_dispatch_table ebpf_base_map_client_dispatch_table_t

Dispatch table implemented by the eBPF runtime to provide RCU / epoch operations.

Notes:

Functions epoch_enter and epoch_exit allow a thread to enter and exit an epoch-protected region, which is necessary when calling the epoch memory operations. These functions are re-entrant, but should always be called in pairs.

Below is the list of epoch memory related functions exposed by eBPF runtime:

• epoch_allocate_with_tag: Allocate memory under epoch control with tag.
• epoch_allocate_cache_aligned_with_tag: Allocate cache aligned memory under epoch control with tag.
• epoch_free: Free memory under epoch control.
• epoch_free_cache_aligned: Free cache aligned memory under epoch control.

Each of the above four functions MUST be called within an epoch-protected region (i.e., after ebpf_epoch_enter() and before ebpf_epoch_exit()). Failure to do so may lead to undefined behavior. Provider dispatch function invocations (defined in ebpf_base_map_provider_dispatch_table_t), and BPF helper function callbacks already are epoch-protected, hence these APIs can be directly called in those contexts. If the provider intends to use these APIs outside the above mentioned contexts, it must ensure that the calls are made within an epoch-protected region.

Similarly, find_element_function can only be invoked in an epoch-protected region, as explained above. Calling it from outside an epoch-protected region may lead to undefined behavior.

ebpf_base_map_provider_dispatch_table_t

typedef struct _ebpf_map_provider_dispatch_table ebpf_base_map_provider_dispatch_table_t

Dispatch table implemented by the eBPF extension to provide map operations. This table is used to provide map operations to the eBPF core.

ebpf_base_map_provider_properties_t

typedef struct _ebpf_base_map_provider_properties ebpf_base_map_provider_properties_t

ebpf_epoch_enter_t

typedef void(* ebpf_epoch_enter_t) (void *epoch_state)

Enter an epoch-protected region.

Parameters

[in]

epoch_state

Pointer to epoch state to be filled in. Its size should be at least sizeof(epoch_state_t).

ebpf_epoch_exit_t

typedef void(* ebpf_epoch_exit_t) (void *epoch_state)

Exit an epoch-protected region.

Parameters

[in]

epoch_state

Pointer to epoch state returned by epoch_enter_t.

ebpf_epoch_free_cache_aligned_t

typedef void(* ebpf_epoch_free_cache_aligned_t) (void *pointer)

Free memory under epoch control.

Parameters

[in]

memory

Allocation to be freed once epoch ends.

ebpf_epoch_free_t

typedef void(* ebpf_epoch_free_t) (void *memory)

Free memory under epoch control.

Parameters

[in]

memory

Allocation to be freed once epoch ends.

ebpf_execution_context_state_t

typedef struct _ebpf_execution_context_state ebpf_execution_context_state_t

ebpf_extension_data_t

typedef struct _ebpf_extension_data ebpf_extension_data_t

ebpf_extension_dispatch_table_t

typedef struct _ebpf_extension_dispatch_table ebpf_extension_dispatch_table_t

ebpf_extension_program_dispatch_table_t

typedef struct _ebpf_extension_program_dispatch_table ebpf_extension_program_dispatch_table_t

ebpf_link_dispatch_table_version_t

typedef enum _ebpf_link_dispatch_table_version ebpf_link_dispatch_table_version_t

ebpf_map_associate_program_type_t

typedef ebpf_result_t(* ebpf_map_associate_program_type_t) (void *binding_context, void *map_context, const ebpf_program_type_t *program_type)

Associate a program type with the map, which allows the map to be used by programs of that type.

Parameters

[in]	binding_context	The binding context provided when the map provider was bound.
[in]	map_context	The eBPF map context.
[in]	program_type	The program type.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_OPERATION_NOT_SUPPORTED	The operation is not supported.

ebpf_map_client_data_t

typedef struct _ebpf_map_client_data ebpf_map_client_data_t

Custom map client data.

ebpf_map_find_element_t

typedef ebpf_result_t(* ebpf_map_find_element_t) (const void *map, const uint8_t *key, uint8_t **value)

Find an element in an eBPF map (client/runtime helper version).

Parameters

[in]	map	The eBPF map to query.
[in]	key	Pointer to the key to search for.
[out]	value	Receives a pointer to the value associated with the key.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_KEY_NOT_FOUND	The key was not found in the map.
EBPF_INVALID_OBJECT	An invalid map was provided.

ebpf_map_provider_data_t

typedef struct _ebpf_map_provider_data ebpf_map_provider_data_t

Custom map provider data.

ebpf_process_map_add_element_t

typedef ebpf_result_t(* ebpf_process_map_add_element_t) (void *binding_context, void *map_context, size_t key_size, _In_reads_opt_(key_size) const uint8_t *key, size_t in_value_size, _In_reads_(in_value_size) const uint8_t *in_value, size_t out_value_size, _Out_writes_opt_(out_value_size) uint8_t *out_value, uint32_t flags)

Add or update (insert/replace) an element in a provider-backed map.

If the provider does not update the original value, i.e., updates_original_value is set to false in ebpf_base_map_provider_properties_t, out_value will be NULL and out_value_size will be 0.

Parameters

[in]	binding_context	The binding context provided when the map provider was bound.
[in]	map_context	The eBPF map context.
[in]	key_size	The size of the key in bytes.
[in]	key	Pointer to the key being updated (may be NULL for helper-mode operations, depending on the base map implementation).
[in]	in_value_size	The size in bytes of the input value.
[in]	in_value	Pointer to the input value bytes.
[in]	out_value_size	The size in bytes of the destination (stored) value buffer.
[out]	out_value	Optional pointer to the destination (stored) value buffer to populate.
[in]	flags	Update flags. Supported values: EBPF_MAP_OPERATION_HELPER - The update is invoked from a BPF program.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_OPERATION_NOT_SUPPORTED	The operation is not supported.
EBPF_INVALID_ARGUMENT	One or more parameters are incorrect.
EBPF_NO_MEMORY	Unable to allocate memory.

ebpf_process_map_create_t

typedef ebpf_result_t(* ebpf_process_map_create_t) (void *binding_context, uint32_t map_type, uint32_t key_size, uint32_t value_size, uint32_t max_entries, uint32_t *actual_value_size, void **map_context)

Process map creation notification.

Parameters

[in]	binding_context	The binding context provided when the map provider was bound.
[in]	map_type	The type of map to create.
[in]	key_size	The size of the key in bytes.
[in]	value_size	The value size requested by the caller in bytes.
[in]	max_entries	The maximum number of entries in the map.
[out]	actual_value_size	The value size in bytes that will actually be stored in the map.
[out]	map_context	Provider-defined per-map context. The eBPF core will pass this back to subsequent map operations and will eventually pass it to ebpf_process_map_delete_t.

Note: When a map lookup happens from user mode, the value is copied into the buffer provided by the user, whereas when a map lookup happens from a BPF program, a pointer to the value is provided to the program, and the program can read or modify the value in place.

Therefore, for maps where an extension intends to modify the actual value being stored in the map, map CRUD operations from BPF programs are disallowed by the eBPF runtime.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_NO_MEMORY	Unable to allocate memory.
EBPF_INVALID_ARGUMENT	One or more parameters are incorrect.

ebpf_process_map_delete_element_t

typedef ebpf_result_t(* ebpf_process_map_delete_element_t) (void *binding_context, void *map_context, size_t key_size, _In_reads_opt_(key_size) const uint8_t *key, size_t value_size, _In_reads_(value_size) const uint8_t *value, uint32_t flags)

Delete an element from a provider-backed map.

This function can be called in three scenarios:

1. Normal map element deletion.
2. Deletion performed as part of an update operation (replacing an existing entry).
3. Deletion performed as part of map cleanup. When deletion is part of an update operation, EBPF_MAP_OPERATION_UPDATE is set in the flags parameter. When map cleanup is in progress, EBPF_MAP_OPERATION_MAP_CLEANUP is set in the flags parameter. In both these cases, the provider must not fail the deletion.

Parameters

[in]	binding_context	The binding context provided when the map provider was bound.
[in]	map_context	The eBPF map context.
[in]	key_size	The size of the key in bytes.
[in]	key	Pointer to the key to delete. If the key is not found, the map is unchanged.
[in]	value_size	The size in bytes of the provider's stored value buffer.
[in]	value	Pointer to the provider's stored value buffer for the entry being deleted.
[in]	flags	Delete flags. Possible values: EBPF_MAP_OPERATION_UPDATE - The delete is invoked as part of an update operation. EBPF_MAP_OPERATION_MAP_CLEANUP - The delete is invoked as part of a map cleanup operation. EBPF_MAP_OPERATION_HELPER - The delete is invoked from a BPF program.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_KEY_NOT_FOUND	The key was not found in the map.
EBPF_OPERATION_NOT_SUPPORTED	The operation is not supported.

ebpf_process_map_delete_t

typedef void(* ebpf_process_map_delete_t) (void *binding_context, void *map_context)

Process a map delete notification.

Parameters

[in]	binding_context	The binding context provided when the map provider was bound.
[in]	map_context	The map context to delete.

ebpf_process_map_find_element_t

typedef ebpf_result_t(* ebpf_process_map_find_element_t) (void *binding_context, void *map_context, size_t key_size, _In_reads_opt_(key_size) const uint8_t *key, size_t in_value_size, _In_reads_(in_value_size) const uint8_t *in_value, size_t out_value_size, _Out_writes_opt_(out_value_size) uint8_t *out_value, uint32_t flags)

Find (lookup) an element in a provider-backed map.

If the provider does not update the original value, i.e., updates_original_value is set to false in ebpf_base_map_provider_properties_t, out_value will be NULL and out_value_size will be 0.

Parameters

[in]	binding_context	The binding context provided when the map provider was bound.
[in]	map_context	The eBPF map context.
[in]	key_size	The size of the key in bytes.
[in]	key	Optionally, pointer to the key being looked up.
[in]	in_value_size	The size in bytes of the provider's stored value buffer.
[in]	in_value	Pointer to the provider's stored value buffer for the entry.
[in]	out_value_size	The size in bytes of the output value buffer.
[out]	out_value	Optional output buffer to receive the value bytes.
[in]	flags	Find flags. Supported values: EBPF_MAP_OPERATION_HELPER - The lookup is invoked from a BPF program.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_OPERATION_NOT_SUPPORTED	The operation is not supported.
EBPF_INVALID_ARGUMENT	One or more parameters are incorrect.
EBPF_KEY_NOT_FOUND	The key was not found in the map.

ebpf_program_batch_begin_invoke_function_t

typedef ebpf_result_t(* ebpf_program_batch_begin_invoke_function_t) (size_t state_size, _Out_writes_(state_size) void *state)

Prepare the eBPF program for batch invocation.

Parameters

[in]	state_size	The size of the state to be allocated, which should be greater than or equal to sizeof(ebpf_execution_context_state_t).
[out]	state	The state to be used for batch invocation.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_NO_MEMORY	The operation failed due to lack of memory.
EBPF_EXTENSION_FAILED_TO_LOAD	The required extension is not loaded.

ebpf_program_batch_end_invoke_function_t

typedef ebpf_result_t(* ebpf_program_batch_end_invoke_function_t) (_Inout_ void *state)

Clean up the eBPF program after batch invocation.

Parameters

[in,out]

state

The state to be used for batch invocation.

Return values

EBPF_SUCCESS

The operation was successful.

ebpf_program_batch_invoke_function_t

typedef ebpf_result_t(* ebpf_program_batch_invoke_function_t) (const void *extension_client_binding_context, _Inout_ void *program_context, uint32_t *result, const void *state)

Invoke the eBPF program in batch mode.

Parameters

[in]	extension_client_binding_context	The context provided by the extension client when the binding was created.
[in,out]	program_context	The context for this invocation of the eBPF program.
[out]	result	The result of the eBPF program.
[in]	state	The state to be used for batch invocation.

Return values

EBPF_SUCCESS

The operation was successful.

ebpf_program_invoke_function_t

typedef ebpf_result_t(* ebpf_program_invoke_function_t) (const void *extension_client_binding_context, _Inout_ void *program_context, uint32_t *result)

Invoke the eBPF program.

Parameters

[in]	extension_client_binding_context	The context provided by the extension client when the binding was created.
[in,out]	program_context	The context for this invocation of the eBPF program.
[out]	result	The result of the eBPF program.

Return values

EBPF_SUCCESS	The operation was successful.
EBPF_NO_MEMORY	The operation failed due to lack of memory.
EBPF_EXTENSION_FAILED_TO_LOAD	The required extension is not loaded.

epoch_state_t

typedef uint64_t epoch_state_t[4]

tag

typedef uint32_t tag

Enumeration Type Documentation

_ebpf_link_dispatch_table_version

enum _ebpf_link_dispatch_table_version

Enumerator
EBPF_LINK_DISPATCH_TABLE_VERSION_1	Initial version of the dispatch table.
EBPF_LINK_DISPATCH_TABLE_VERSION_CURRENT	Current version of the dispatch table.

Function Documentation

_Ret_writes_maybenull_()

typedef _Ret_writes_maybenull_

(

size

)

Allocate memory under epoch control.

Allocate cache aligned memory under epoch control.

Parameters

[in]	size	Size of memory to allocate.
[in]	tag	Pool tag to use.

Returns

Pointer to memory block allocated, or null on failure.