diff --git a/globals.html b/globals.html index 03fba8eb0..91ee4a0eb 100644 --- a/globals.html +++ b/globals.html @@ -61,10 +61,26 @@
-
Here is a list of all functions, variables, defines, enums, and typedefs with links to the files they belong to:
+ + +

◆ ubpf_jit_ex_fn

+ +
+
+ + + + +
typedef uint64_t(* ubpf_jit_ex_fn) (void *mem, size_t mem_len, uint8_t *stack, size_t stack_len)
+
+ +

Opaque type for a uBPF JIT compiled function with external stack.

+
@@ -333,6 +408,37 @@

Enumeration Type Documentation

+ +

◆ JitMode

+ +
+
+ + + + +
enum JitMode
+
+ +

Enum to describe JIT mode.

+

ExtendedJitMode specifies that an invocation of that code have 4 parameters:

    +
  1. A pointer to the program's memory space.
    2. +
  2. The size of the program's memory space.
    3. +
  3. A pointer to memory to be used by the program as a stack during execution.
    4. +
  4. The size of the provided stack space. See ubpf_jit_ex_fn for more information.
    5. +
+

BasicJitMode specifies that an invocation of that code have 2 parameters:

    +
  1. A pointer to the program's memory space.
    2. +
  2. The size of the program's memory space. The function generated by the JITer executing in basic mode automatically allocates a stack for the program's execution. See ubpf_jit_fn for more information.
    3. +
+ + + +
Enumerator
ExtendedJitMode 
BasicJitMode 
+

Function Documentation

@@ -396,10 +502,58 @@

Parameters
+ + + +
[in]vmThe VM to compile the program in.
[out]errmsgThe error message, if any. This should be freed by the caller.
+
+ +
Returns
ubpf_jit_fn A pointer to the compiled program, or NULL on failure.
+ + + + +

◆ ubpf_compile_ex()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
ubpf_jit_ex_fn ubpf_compile_ex (struct ubpf_vm * vm,
char ** errmsg,
enum JitMode jit_mode 
)
+
+ +

Compile a BPF program in the VM to native code.

+

A program must be loaded into the VM and all external functions (or the external helper dispatcher) must be registered before calling this function.

+

The JITer executes in the prescribed mode when invoked through this function. If jit_mode is basic, the caller will have to cast the function pointer to the appropriate type (ubpf_jit_fn).

Parameters
+
[in]vmThe VM to compile the program in.
[out]errmsgThe error message, if any. This should be freed by the caller.
[in]jit_modeThe mode in which to execute the JITer – basic or extended.
@@ -447,6 +601,7 @@

Parameters
@@ -562,6 +717,58 @@

+

◆ ubpf_exec_ex()

+ +
+
+

[in]vmThe VM of the already JIT'd program.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
int ubpf_exec_ex (const struct ubpf_vm * vm,
void * mem,
size_t mem_len,
uint64_t * bpf_return_value,
uint8_t * stack,
size_t stack_len 
)
+

+
@@ -852,6 +1059,60 @@

+

◆ ubpf_register_stack_usage_calculator()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + +
int ubpf_register_stack_usage_calculator (struct ubpf_vm * vm,
stack_usage_calculator_t calculator,
void * cookie 
)
+
+ +

Register a function that will be called during eBPF program validation to determine stack usage for a local function.

+

In eBPF, the frame pointer is a read-only register. Therefore, the eBPF interpreter or the eBPF JITer need to know the stack usage for each local function so that the frame pointer can be adjusted properly on behalf of the calling function. The callback registered here has access to a cookie for context (specified in the call to this function), the PC (in the eBPF program) of the first instruction of a local function and the ubpf_vm.

+

The callback's job is to calculate the amount of stack space used by the local function that starts at the given PC.

+

If the callback returns 0 or there is no callback registered, the eBPF interpreter/JITer assume that the local function uses the maximum stack available according to the spec (512K).

+
Parameters
+ + + + +
[in]vmThe VM to register the callback with.
[in]dispatcherThe callback that will be invoked to determine the amount of stack usage for a local function that starts at ...
[in]pcThe pc of the function whose stack usage the callback must caculate.
+
+
+
Return values
+ + + +
0Success.
-1Failure.
+
+
+
@@ -1183,12 +1444,80 @@

Parameters
+ + + + + +
[in]vmThe VM to translate the program in.
[out]bufferThe buffer to store the translated code in.
[in]sizeThe size of the buffer.
[out]errmsgThe error message, if any. This should be freed by the caller.
+
+ +
Return values
+ + + +
0Success.
-1Failure.
+
+
+ + + + +

◆ ubpf_translate_ex()

+ +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
int ubpf_translate_ex (struct ubpf_vm * vm,
uint8_t * buffer,
size_t * size,
char ** errmsg,
enum JitMode jit_mode 
)
+
+ +

Translate the eBPF byte code to machine code.

+

A program must be loaded into the VM and all external functions must be registered before calling this function.

+

The JITer executes in the prescribed mode when invoked through this function.

Parameters
+
[in]vmThe VM to translate the program in.
[out]bufferThe buffer to store the translated code in.
[in]sizeThe size of the buffer.
[out]errmsgThe error message, if any. This should be freed by the caller.
[in]jit_modeThe mode in which to execute the JITer – basic or extended.
diff --git a/ubpf_8h_source.html b/ubpf_8h_source.html index 155ea5f02..7b0ced40c 100644 --- a/ubpf_8h_source.html +++ b/ubpf_8h_source.html @@ -107,152 +107,188 @@
39 #define UBPF_MAX_INSTS 65536
40 #endif
41 
-
45 #if !defined(UBPF_STACK_SIZE)
-
46 #define UBPF_STACK_SIZE 512
+
45 #if !defined(UBPF_EBPF_STACK_SIZE)
+
46 #define UBPF_EBPF_STACK_SIZE 512
47 #endif
48 
-
52 #if !defined(UBPF_MAX_CALL_DEPTH)
-
53 #define UBPF_MAX_CALL_DEPTH 10
-
54 #endif
-
55 
-
59  struct ubpf_vm;
-
60 
-
64  typedef uint64_t (*ubpf_jit_fn)(void* mem, size_t mem_len);
-
65 
-
71  struct ubpf_vm*
-
72  ubpf_create(void);
+
49 #define UBPF_EBPF_NONVOLATILE_SIZE (sizeof(uint64_t) * 5)
+
50 
+
54 #if !defined(UBPF_MAX_CALL_DEPTH)
+
55 #define UBPF_MAX_CALL_DEPTH 10
+
56 #endif
+
57 
+
61  struct ubpf_vm;
+
62 
+
66  typedef uint64_t (*ubpf_jit_fn)(void* mem, size_t mem_len);
+
67 
+
72  typedef uint64_t (*ubpf_jit_ex_fn)(void* mem, size_t mem_len, uint8_t* stack, size_t stack_len);
73 
-
79  void
-
80  ubpf_destroy(struct ubpf_vm* vm);
-
81 
-
89  bool
-
90  ubpf_toggle_bounds_check(struct ubpf_vm* vm, bool enable);
-
91 
-
98  void
-
99  ubpf_set_error_print(struct ubpf_vm* vm, int (*error_printf)(FILE* stream, const char* format, ...));
-
100 
-
104  typedef uint64_t (*external_function_t)(uint64_t p0, uint64_t p1, uint64_t p2, uint64_t p3, uint64_t p4);
-
105 
-
115  external_function_t
-
116  as_external_function_t(void* f);
-
117 
-
131  int
-
132  ubpf_register(struct ubpf_vm* vm, unsigned int index, const char* name, external_function_t fn);
-
133 
-
137  typedef uint64_t (*external_function_dispatcher_t)(
-
138  uint64_t, uint64_t, uint64_t, uint64_t, uint64_t, unsigned int index, void* cookie);
-
139 
-
143  typedef bool (*external_function_validate_t)(unsigned int index, const struct ubpf_vm* vm);
-
144 
-
161  int
-
162  ubpf_register_external_dispatcher(
-
163  struct ubpf_vm* vm,
-
164  external_function_dispatcher_t dispatcher,
-
165  external_function_validate_t validater);
-
166 
-
182  int
-
183  ubpf_load(struct ubpf_vm* vm, const void* code, uint32_t code_len, char** errmsg);
-
184 
-
185  /*
-
186  * Unload code from a VM
-
187  *
-
188  * This must be done before calling ubpf_load or ubpf_load_elf, except for the
-
189  * first time those functions are called. It clears the VM instructions to
-
190  * allow for new code to be loaded.
-
191  *
-
192  * It does not unregister any external functions.
-
193  */
-
194 
-
202  void
-
203  ubpf_unload_code(struct ubpf_vm* vm);
-
204 
-
205 #if defined(UBPF_HAS_ELF_H)
+
91  enum JitMode
+
92  {
+
93  ExtendedJitMode,
+
94  BasicJitMode
+
95  };
+
96 
+
102  struct ubpf_vm*
+
103  ubpf_create(void);
+
104 
+
110  void
+
111  ubpf_destroy(struct ubpf_vm* vm);
+
112 
+
120  bool
+
121  ubpf_toggle_bounds_check(struct ubpf_vm* vm, bool enable);
+
122 
+
129  void
+
130  ubpf_set_error_print(struct ubpf_vm* vm, int (*error_printf)(FILE* stream, const char* format, ...));
+
131 
+
135  typedef uint64_t (*external_function_t)(uint64_t p0, uint64_t p1, uint64_t p2, uint64_t p3, uint64_t p4);
+
136 
+
146  external_function_t
+
147  as_external_function_t(void* f);
+
148 
+
162  int
+
163  ubpf_register(struct ubpf_vm* vm, unsigned int index, const char* name, external_function_t fn);
+
164 
+
168  typedef uint64_t (*external_function_dispatcher_t)(
+
169  uint64_t, uint64_t, uint64_t, uint64_t, uint64_t, unsigned int index, void* cookie);
+
170 
+
174  typedef bool (*external_function_validate_t)(unsigned int index, const struct ubpf_vm* vm);
+
175 
+
192  int
+
193  ubpf_register_external_dispatcher(
+
194  struct ubpf_vm* vm, external_function_dispatcher_t dispatcher, external_function_validate_t validater);
+
195 
+
201  typedef int (*stack_usage_calculator_t)(const struct ubpf_vm* vm, uint16_t pc, void* cookie);
+
202 
226  int
-
227  ubpf_load_elf(struct ubpf_vm* vm, const void* elf, size_t elf_len, char** errmsg);
+
227  ubpf_register_stack_usage_calculator(struct ubpf_vm* vm, stack_usage_calculator_t calculator, void* cookie);
228 
-
251  int
-
252  ubpf_load_elf_ex(struct ubpf_vm* vm, const void* elf, size_t elf_len, const char* main_section_name, char** errmsg);
-
253 #endif
-
254 
-
268  int
-
269  ubpf_exec(const struct ubpf_vm* vm, void* mem, size_t mem_len, uint64_t* bpf_return_value);
-
270 
-
282  ubpf_jit_fn
-
283  ubpf_compile(struct ubpf_vm* vm, char** errmsg);
-
284 
-
296  ubpf_jit_fn
-
297  ubpf_copy_jit(struct ubpf_vm* vm, void *buffer, size_t size, char** errmsg);
-
298 
-
312  int
-
313  ubpf_translate(struct ubpf_vm* vm, uint8_t* buffer, size_t* size, char** errmsg);
-
314 
-
326  int
-
327  ubpf_set_unwind_function_index(struct ubpf_vm* vm, unsigned int idx);
-
328 
-
335  void
-
336  ubpf_set_registers(struct ubpf_vm* vm, uint64_t* regs);
-
337 
-
344  uint64_t*
-
345  ubpf_get_registers(const struct ubpf_vm* vm);
-
346 
-
355  int
-
356  ubpf_set_pointer_secret(struct ubpf_vm* vm, uint64_t secret);
+
244  int
+
245  ubpf_load(struct ubpf_vm* vm, const void* code, uint32_t code_len, char** errmsg);
+
246 
+
247  /*
+
248  * Unload code from a VM
+
249  *
+
250  * This must be done before calling ubpf_load or ubpf_load_elf, except for the
+
251  * first time those functions are called. It clears the VM instructions to
+
252  * allow for new code to be loaded.
+
253  *
+
254  * It does not unregister any external functions.
+
255  */
+
256 
+
264  void
+
265  ubpf_unload_code(struct ubpf_vm* vm);
+
266 
+
267 #if defined(UBPF_HAS_ELF_H)
+
288  int
+
289  ubpf_load_elf(struct ubpf_vm* vm, const void* elf, size_t elf_len, char** errmsg);
+
290 
+
313  int
+
314  ubpf_load_elf_ex(struct ubpf_vm* vm, const void* elf, size_t elf_len, const char* main_section_name, char** errmsg);
+
315 #endif
+
316 
+
330  int
+
331  ubpf_exec(const struct ubpf_vm* vm, void* mem, size_t mem_len, uint64_t* bpf_return_value);
+
332 
+
333  int
+
334  ubpf_exec_ex(
+
335  const struct ubpf_vm* vm,
+
336  void* mem,
+
337  size_t mem_len,
+
338  uint64_t* bpf_return_value,
+
339  uint8_t* stack,
+
340  size_t stack_len);
+
341 
+
355  ubpf_jit_fn
+
356  ubpf_compile(struct ubpf_vm* vm, char** errmsg);
357 
-
370  typedef uint64_t (*ubpf_data_relocation)(
-
371  void* user_context,
-
372  const uint8_t* data,
-
373  uint64_t data_size,
-
374  const char* symbol_name,
-
375  uint64_t symbol_offset,
-
376  uint64_t symbol_size);
-
377 
-
385  int
-
386  ubpf_register_data_relocation(struct ubpf_vm* vm, void* user_context, ubpf_data_relocation relocation);
-
387 
-
388  typedef bool (*ubpf_bounds_check)(void* context, uint64_t addr, uint64_t size);
-
389 
-
399  int
-
400  ubpf_register_data_bounds_check(struct ubpf_vm* vm, void* user_context, ubpf_bounds_check bounds_check);
-
401 
-
414  int
-
415  ubpf_set_jit_code_size(struct ubpf_vm* vm, size_t code_size);
-
416 
+
374  ubpf_jit_ex_fn
+
375  ubpf_compile_ex(struct ubpf_vm* vm, char** errmsg, enum JitMode jit_mode);
+
376 
+
391  ubpf_jit_fn
+
392  ubpf_copy_jit(struct ubpf_vm* vm, void* buffer, size_t size, char** errmsg);
+
393 
+
409  int
+
410  ubpf_translate(struct ubpf_vm* vm, uint8_t* buffer, size_t* size, char** errmsg);
+
411 
428  int
-
429  ubpf_set_instruction_limit(struct ubpf_vm* vm, uint32_t limit, uint32_t* previous_limit);
+
429  ubpf_translate_ex(struct ubpf_vm* vm, uint8_t* buffer, size_t* size, char** errmsg, enum JitMode jit_mode);
430 
-
431 
-
432 #ifdef __cplusplus
-
433 }
-
434 #endif
-
435 
-
436 #endif
+
442  int
+
443  ubpf_set_unwind_function_index(struct ubpf_vm* vm, unsigned int idx);
+
444 
+
451  void
+
452  ubpf_set_registers(struct ubpf_vm* vm, uint64_t* regs);
+
453 
+
460  uint64_t*
+
461  ubpf_get_registers(const struct ubpf_vm* vm);
+
462 
+
471  int
+
472  ubpf_set_pointer_secret(struct ubpf_vm* vm, uint64_t secret);
+
473 
+
486  typedef uint64_t (*ubpf_data_relocation)(
+
487  void* user_context,
+
488  const uint8_t* data,
+
489  uint64_t data_size,
+
490  const char* symbol_name,
+
491  uint64_t symbol_offset,
+
492  uint64_t symbol_size);
+
493 
+
501  int
+
502  ubpf_register_data_relocation(struct ubpf_vm* vm, void* user_context, ubpf_data_relocation relocation);
+
503 
+
504  typedef bool (*ubpf_bounds_check)(void* context, uint64_t addr, uint64_t size);
+
505 
+
515  int
+
516  ubpf_register_data_bounds_check(struct ubpf_vm* vm, void* user_context, ubpf_bounds_check bounds_check);
+
517 
+
530  int
+
531  ubpf_set_jit_code_size(struct ubpf_vm* vm, size_t code_size);
+
532 
+
544  int
+
545  ubpf_set_instruction_limit(struct ubpf_vm* vm, uint32_t limit, uint32_t* previous_limit);
+
546 
+
547 #ifdef __cplusplus
+
548 }
+
549 #endif
+
550 
+
551 #endif
ubpf_set_unwind_function_index
int ubpf_set_unwind_function_index(struct ubpf_vm *vm, unsigned int idx)
Instruct the uBPF runtime to apply unwind-on-success semantics to a helper function....
+
stack_usage_calculator_t
int(* stack_usage_calculator_t)(const struct ubpf_vm *vm, uint16_t pc, void *cookie)
The type of a stack usage calculator callback function.
Definition: ubpf.h:201
ubpf_exec
int ubpf_exec(const struct ubpf_vm *vm, void *mem, size_t mem_len, uint64_t *bpf_return_value)
Execute a BPF program in the VM using the interpreter.
ubpf_register_external_dispatcher
int ubpf_register_external_dispatcher(struct ubpf_vm *vm, external_function_dispatcher_t dispatcher, external_function_validate_t validater)
Register a function that dispatches to external helpers The immediate field of a CALL instruction is ...
+
ubpf_compile_ex
ubpf_jit_ex_fn ubpf_compile_ex(struct ubpf_vm *vm, char **errmsg, enum JitMode jit_mode)
Compile a BPF program in the VM to native code.
ubpf_register_data_bounds_check
int ubpf_register_data_bounds_check(struct ubpf_vm *vm, void *user_context, ubpf_bounds_check bounds_check)
Set a bounds check function for the VM.
ubpf_get_registers
uint64_t * ubpf_get_registers(const struct ubpf_vm *vm)
Retrieve the storage location for the BPF registers in the VM.
+
ubpf_jit_ex_fn
uint64_t(* ubpf_jit_ex_fn)(void *mem, size_t mem_len, uint8_t *stack, size_t stack_len)
Opaque type for a uBPF JIT compiled function with external stack.
Definition: ubpf.h:72
ubpf_set_pointer_secret
int ubpf_set_pointer_secret(struct ubpf_vm *vm, uint64_t secret)
Optional secret to improve ROP protection.
ubpf_register
int ubpf_register(struct ubpf_vm *vm, unsigned int index, const char *name, external_function_t fn)
Register an external function. The immediate field of a CALL instruction is an index into an array of...
+
JitMode
JitMode
Enum to describe JIT mode.
Definition: ubpf.h:92
+
BasicJitMode
@ BasicJitMode
Definition: ubpf.h:94
+
ExtendedJitMode
@ ExtendedJitMode
Definition: ubpf.h:93
as_external_function_t
external_function_t as_external_function_t(void *f)
Cast an external function to external_function_t Some external functions may not use all the paramete...
-
ubpf_jit_fn
uint64_t(* ubpf_jit_fn)(void *mem, size_t mem_len)
Opaque type for a uBPF JIT compiled function.
Definition: ubpf.h:64
-
ubpf_bounds_check
bool(* ubpf_bounds_check)(void *context, uint64_t addr, uint64_t size)
Definition: ubpf.h:388
+
ubpf_jit_fn
uint64_t(* ubpf_jit_fn)(void *mem, size_t mem_len)
Opaque type for a uBPF JIT compiled function.
Definition: ubpf.h:66
+
ubpf_bounds_check
bool(* ubpf_bounds_check)(void *context, uint64_t addr, uint64_t size)
Definition: ubpf.h:504
ubpf_compile
ubpf_jit_fn ubpf_compile(struct ubpf_vm *vm, char **errmsg)
Compile a BPF program in the VM to native code.
ubpf_register_data_relocation
int ubpf_register_data_relocation(struct ubpf_vm *vm, void *user_context, ubpf_data_relocation relocation)
Set a relocation function for the VM.
-
ubpf_data_relocation
uint64_t(* ubpf_data_relocation)(void *user_context, const uint8_t *data, uint64_t data_size, const char *symbol_name, uint64_t symbol_offset, uint64_t symbol_size)
Data relocation function that is called by the VM when it encounters a R_BPF_64_64 relocation in the ...
Definition: ubpf.h:370
+
ubpf_exec_ex
int ubpf_exec_ex(const struct ubpf_vm *vm, void *mem, size_t mem_len, uint64_t *bpf_return_value, uint8_t *stack, size_t stack_len)
+
ubpf_data_relocation
uint64_t(* ubpf_data_relocation)(void *user_context, const uint8_t *data, uint64_t data_size, const char *symbol_name, uint64_t symbol_offset, uint64_t symbol_size)
Data relocation function that is called by the VM when it encounters a R_BPF_64_64 relocation in the ...
Definition: ubpf.h:486
ubpf_toggle_bounds_check
bool ubpf_toggle_bounds_check(struct ubpf_vm *vm, bool enable)
Enable / disable bounds_check. Bounds check is enabled by default, but it may be too restrictive.
ubpf_create
struct ubpf_vm * ubpf_create(void)
Create a new uBPF VM.
ubpf_load
int ubpf_load(struct ubpf_vm *vm, const void *code, uint32_t code_len, char **errmsg)
Load code into a VM. This must be done before calling ubpf_exec or ubpf_compile and after registering...
-
external_function_validate_t
bool(* external_function_validate_t)(unsigned int index, const struct ubpf_vm *vm)
The type of an external helper validation function.
Definition: ubpf.h:143
+
external_function_validate_t
bool(* external_function_validate_t)(unsigned int index, const struct ubpf_vm *vm)
The type of an external helper validation function.
Definition: ubpf.h:174
ubpf_set_jit_code_size
int ubpf_set_jit_code_size(struct ubpf_vm *vm, size_t code_size)
Set a size for the buffer allocated to machine code generated during JIT compilation....
-
external_function_t
uint64_t(* external_function_t)(uint64_t p0, uint64_t p1, uint64_t p2, uint64_t p3, uint64_t p4)
The type of an external function.
Definition: ubpf.h:104
+
external_function_t
uint64_t(* external_function_t)(uint64_t p0, uint64_t p1, uint64_t p2, uint64_t p3, uint64_t p4)
The type of an external function.
Definition: ubpf.h:135
ubpf_copy_jit
ubpf_jit_fn ubpf_copy_jit(struct ubpf_vm *vm, void *buffer, size_t size, char **errmsg)
Copy the JIT'd program code to the given buffer.
-
external_function_dispatcher_t
uint64_t(* external_function_dispatcher_t)(uint64_t, uint64_t, uint64_t, uint64_t, uint64_t, unsigned int index, void *cookie)
The type of an external helper dispatcher function.
Definition: ubpf.h:137
+
external_function_dispatcher_t
uint64_t(* external_function_dispatcher_t)(uint64_t, uint64_t, uint64_t, uint64_t, uint64_t, unsigned int index, void *cookie)
The type of an external helper dispatcher function.
Definition: ubpf.h:168
+
ubpf_register_stack_usage_calculator
int ubpf_register_stack_usage_calculator(struct ubpf_vm *vm, stack_usage_calculator_t calculator, void *cookie)
Register a function that will be called during eBPF program validation to determine stack usage for a...
ubpf_translate
int ubpf_translate(struct ubpf_vm *vm, uint8_t *buffer, size_t *size, char **errmsg)
Translate the eBPF byte code to machine code.
ubpf_set_instruction_limit
int ubpf_set_instruction_limit(struct ubpf_vm *vm, uint32_t limit, uint32_t *previous_limit)
Set the instruction limit for the VM. This is the maximum number of instructions that a program may e...
ubpf_destroy
void ubpf_destroy(struct ubpf_vm *vm)
Free a uBPF VM.
ubpf_set_error_print
void ubpf_set_error_print(struct ubpf_vm *vm, int(*error_printf)(FILE *stream, const char *format,...))
Set the function to be invoked if the program hits a fatal error.
ubpf_unload_code
void ubpf_unload_code(struct ubpf_vm *vm)
Unload code from a VM.
ubpf_set_registers
void ubpf_set_registers(struct ubpf_vm *vm, uint64_t *regs)
Override the storage location for the BPF registers in the VM.
+
ubpf_translate_ex
int ubpf_translate_ex(struct ubpf_vm *vm, uint8_t *buffer, size_t *size, char **errmsg, enum JitMode jit_mode)
Translate the eBPF byte code to machine code.