ubpf.h

Go to the documentation of this file.

// Copyright (c) 2015 Big Switch Networks, Inc
// SPDX-License-Identifier: Apache-2.0
 
/*
 * Copyright 2015 Big Switch Networks, Inc
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef UBPF_H
#define UBPF_H
 
#ifdef __cplusplus
extern "C"
{
#endif
 
#include <ubpf_config.h>
 
#include <stdio.h>
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
 
#if !defined(UBPF_MAX_INSTS)
#define UBPF_MAX_INSTS 65536
#endif
 
#if !defined(UBPF_MAX_CALL_DEPTH)
#define UBPF_MAX_CALL_DEPTH 8
#endif
 
#if !defined(UBPF_EBPF_STACK_SIZE)
#define UBPF_EBPF_STACK_SIZE (UBPF_MAX_CALL_DEPTH * 512)
#endif
 
#if !defined(UBPF_EBPF_LOCAL_FUNCTION_STACK_SIZE)
#define UBPF_EBPF_LOCAL_FUNCTION_STACK_SIZE 256
#endif
 
#if !defined(UBPF_MAX_EXT_FUNCS)
#define UBPF_MAX_EXT_FUNCS 64
#endif
 
#define UBPF_EBPF_NONVOLATILE_SIZE (sizeof(uint64_t) * 5)
 
 
    struct ubpf_vm;
 
    typedef uint64_t (*ubpf_jit_fn)(void* mem, size_t mem_len);
 
    typedef uint64_t (*ubpf_jit_ex_fn)(void* mem, size_t mem_len, uint8_t* stack, size_t stack_len);
 
    enum JitMode
    {
        ExtendedJitMode,
        BasicJitMode
    };
 
    struct ubpf_vm*
    ubpf_create(void);
 
    void
    ubpf_destroy(struct ubpf_vm* vm);
 
    bool
    ubpf_toggle_bounds_check(struct ubpf_vm* vm, bool enable);
 
    bool
    ubpf_toggle_constant_blinding(struct ubpf_vm* vm, bool enable);
 
    enum ubpf_execution_profile
    {
        UBPF_EXECUTION_PROFILE_LEGACY = 0,
        UBPF_EXECUTION_PROFILE_SAFE = 1,
    };
 
    int
    ubpf_set_execution_profile(struct ubpf_vm* vm, enum ubpf_execution_profile profile);
 
    void
    ubpf_set_error_print(struct ubpf_vm* vm, int (*error_printf)(FILE* stream, const char* format, ...));
 
    typedef uint64_t (*external_function_t)(uint64_t p0, uint64_t p1, uint64_t p2, uint64_t p3, uint64_t p4);
 
    enum ubpf_safe_region_kind
    {
        UBPF_SAFE_REGION_POINTER = 0,
        UBPF_SAFE_REGION_HANDLE = 1,
    };
 
    enum ubpf_safe_region_permissions
    {
        UBPF_SAFE_REGION_READ = 1,
        UBPF_SAFE_REGION_WRITE = 2,
        UBPF_SAFE_REGION_ATOMIC = 4,
    };
 
    struct ubpf_safe_region
    {
        uint32_t id;
        void* base;
        uint64_t size;
        enum ubpf_safe_region_kind kind;
        uint32_t permissions;
    };
 
    enum ubpf_safe_helper_result_kind
    {
        UBPF_SAFE_HELPER_RESULT_SCALAR = 0,
        UBPF_SAFE_HELPER_RESULT_POINTER = 1,
        UBPF_SAFE_HELPER_RESULT_HANDLE = 2,
    };
 
    struct ubpf_safe_helper_descriptor
    {
        unsigned int index;
        const char* name;
        external_function_t fn;
        enum ubpf_safe_helper_result_kind result_kind;
        uint32_t region_id;
        uint64_t region_size;
    };
 
    external_function_t
    as_external_function_t(void* f);
 
    int
    ubpf_register(struct ubpf_vm* vm, unsigned int index, const char* name, external_function_t fn);
 
    int
    ubpf_register_safe_helper(struct ubpf_vm* vm, const struct ubpf_safe_helper_descriptor* descriptor);
 
    typedef uint64_t (*external_function_dispatcher_t)(
        uint64_t, uint64_t, uint64_t, uint64_t, uint64_t, unsigned int index, void* cookie);
 
    typedef bool (*external_function_validate_t)(unsigned int index, const struct ubpf_vm* vm);
 
    int
    ubpf_register_external_dispatcher(
        struct ubpf_vm* vm, external_function_dispatcher_t dispatcher, external_function_validate_t validater);
 
    typedef int (*stack_usage_calculator_t)(const struct ubpf_vm* vm, uint16_t pc, void* cookie);
 
    int
    ubpf_register_stack_usage_calculator(struct ubpf_vm* vm, stack_usage_calculator_t calculator, void* cookie);
 
    int
    ubpf_load(struct ubpf_vm* vm, const void* code, uint32_t code_len, char** errmsg);
 
    /*
     * Unload code from a VM
     *
     * This must be done before calling ubpf_load or ubpf_load_elf, except for the
     * first time those functions are called. It clears the VM instructions to
     * allow for new code to be loaded.
     *
     * It does not unregister any external functions.
     */
 
    void
    ubpf_unload_code(struct ubpf_vm* vm);
 
#if defined(UBPF_HAS_ELF_H)
    int
    ubpf_load_elf(struct ubpf_vm* vm, const void* elf, size_t elf_len, char** errmsg);
 
    int
    ubpf_load_elf_ex(struct ubpf_vm* vm, const void* elf, size_t elf_len, const char* main_section_name, char** errmsg);
#endif
 
    int
    ubpf_exec(const struct ubpf_vm* vm, void* mem, size_t mem_len, uint64_t* bpf_return_value);
 
    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_jit_fn
    ubpf_compile(struct ubpf_vm* vm, char** errmsg);
 
    ubpf_jit_ex_fn
    ubpf_compile_ex(struct ubpf_vm* vm, char** errmsg, enum JitMode jit_mode);
 
    ubpf_jit_fn
    ubpf_copy_jit(struct ubpf_vm* vm, void* buffer, size_t size, char** errmsg);
 
    int
    ubpf_translate(struct ubpf_vm* vm, uint8_t* buffer, size_t* size, char** errmsg);
 
    int
    ubpf_translate_ex(struct ubpf_vm* vm, uint8_t* buffer, size_t* size, char** errmsg, enum JitMode jit_mode);
 
    int
    ubpf_set_unwind_function_index(struct ubpf_vm* vm, unsigned int idx);
 
    void
    ubpf_set_registers(struct ubpf_vm* vm, uint64_t* regs);
 
    uint64_t*
    ubpf_get_registers(const struct ubpf_vm* vm);
 
    int
    ubpf_set_pointer_secret(struct ubpf_vm* vm, uint64_t secret);
 
    typedef 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);
 
    int
    ubpf_register_data_relocation(struct ubpf_vm* vm, void* user_context, ubpf_data_relocation relocation);
 
    typedef bool (*ubpf_bounds_check)(void* context, uint64_t addr, uint64_t size);
 
    int
    ubpf_register_data_bounds_check(struct ubpf_vm* vm, void* user_context, ubpf_bounds_check bounds_check);
 
    int
    ubpf_register_safe_region(struct ubpf_vm* vm, const struct ubpf_safe_region* region);
 
    int
    ubpf_set_jit_code_size(struct ubpf_vm* vm, size_t code_size);
 
    int
    ubpf_set_instruction_limit(struct ubpf_vm* vm, uint32_t limit, uint32_t* previous_limit);
 
    bool
    ubpf_toggle_undefined_behavior_check(struct ubpf_vm* vm, bool enable);
 
    bool
    ubpf_toggle_readonly_bytecode(struct ubpf_vm* vm, bool enable);
 
    typedef void (*ubpf_debug_fn)(
        void* context,
        int program_counter,
        const uint64_t registers[16],
        const uint8_t* stack_start,
        size_t stack_length,
        uint64_t register_mask,
        const uint8_t* stack_mask_start);
 
    int
    ubpf_register_debug_fn(struct ubpf_vm* vm, void* context, ubpf_debug_fn debug_function);
#ifdef __cplusplus
}
#endif
 
#endif