1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2018 Intel Corporation 3 */ 4 5 #ifndef _RTE_BPF_H_ 6 #define _RTE_BPF_H_ 7 8 /** 9 * @file rte_bpf.h 10 * 11 * RTE BPF support. 12 * 13 * librte_bpf provides a framework to load and execute eBPF bytecode 14 * inside user-space dpdk based applications. 15 * It supports basic set of features from eBPF spec 16 * (https://www.kernel.org/doc/Documentation/networking/filter.txt). 17 */ 18 19 #include <rte_compat.h> 20 #include <rte_common.h> 21 #include <rte_mbuf.h> 22 #include <bpf_def.h> 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /** 29 * Possible types for function/BPF program arguments. 30 */ 31 enum rte_bpf_arg_type { 32 RTE_BPF_ARG_UNDEF, /**< undefined */ 33 RTE_BPF_ARG_RAW, /**< scalar value */ 34 RTE_BPF_ARG_PTR = 0x10, /**< pointer to data buffer */ 35 RTE_BPF_ARG_PTR_MBUF, /**< pointer to rte_mbuf */ 36 RTE_BPF_ARG_RESERVED /**< reserved for internal use */ 37 }; 38 39 /** 40 * function argument information 41 */ 42 struct rte_bpf_arg { 43 enum rte_bpf_arg_type type; 44 /** 45 * for ptr type - max size of data buffer it points to 46 * for raw type - the size (in bytes) of the value 47 */ 48 size_t size; 49 size_t buf_size; 50 /**< for mbuf ptr type, max size of rte_mbuf data buffer */ 51 }; 52 53 /** 54 * determine is argument a pointer 55 */ 56 #define RTE_BPF_ARG_PTR_TYPE(x) ((x) & RTE_BPF_ARG_PTR) 57 58 /** 59 * Possible types for external symbols. 60 */ 61 enum rte_bpf_xtype { 62 RTE_BPF_XTYPE_FUNC, /**< function */ 63 RTE_BPF_XTYPE_VAR /**< variable */ 64 }; 65 66 /** 67 * Definition for external symbols available in the BPF program. 68 */ 69 struct rte_bpf_xsym { 70 const char *name; /**< name */ 71 enum rte_bpf_xtype type; /**< type */ 72 union { 73 struct { 74 uint64_t (*val)(uint64_t, uint64_t, uint64_t, 75 uint64_t, uint64_t); 76 uint32_t nb_args; 77 struct rte_bpf_arg args[EBPF_FUNC_MAX_ARGS]; 78 /**< Function arguments descriptions. */ 79 struct rte_bpf_arg ret; /**< function return value. */ 80 } func; 81 struct { 82 void *val; /**< actual memory location */ 83 struct rte_bpf_arg desc; /**< type, size, etc. */ 84 } var; /**< external variable */ 85 }; 86 }; 87 88 /** 89 * Input parameters for loading eBPF code. 90 */ 91 struct rte_bpf_prm { 92 const struct ebpf_insn *ins; /**< array of eBPF instructions */ 93 uint32_t nb_ins; /**< number of instructions in ins */ 94 const struct rte_bpf_xsym *xsym; 95 /**< array of external symbols that eBPF code is allowed to reference */ 96 uint32_t nb_xsym; /**< number of elements in xsym */ 97 struct rte_bpf_arg prog_arg; /**< eBPF program input arg description */ 98 }; 99 100 /** 101 * Information about compiled into native ISA eBPF code. 102 */ 103 struct rte_bpf_jit { 104 uint64_t (*func)(void *); /**< JIT-ed native code */ 105 size_t sz; /**< size of JIT-ed code */ 106 }; 107 108 struct rte_bpf; 109 110 /** 111 * De-allocate all memory used by this eBPF execution context. 112 * 113 * @param bpf 114 * BPF handle to destroy. 115 */ 116 void 117 rte_bpf_destroy(struct rte_bpf *bpf); 118 119 /** 120 * Create a new eBPF execution context and load given BPF code into it. 121 * 122 * @param prm 123 * Parameters used to create and initialise the BPF execution context. 124 * @return 125 * BPF handle that is used in future BPF operations, 126 * or NULL on error, with error code set in rte_errno. 127 * Possible rte_errno errors include: 128 * - EINVAL - invalid parameter passed to function 129 * - ENOMEM - can't reserve enough memory 130 */ 131 struct rte_bpf * 132 rte_bpf_load(const struct rte_bpf_prm *prm); 133 134 /** 135 * Create a new eBPF execution context and load BPF code from given ELF 136 * file into it. 137 * Note that if the function will encounter EBPF_PSEUDO_CALL instruction 138 * that references external symbol, it will treat is as standard BPF_CALL 139 * to the external helper function. 140 * 141 * @param prm 142 * Parameters used to create and initialise the BPF execution context. 143 * @param fname 144 * Pathname for a ELF file. 145 * @param sname 146 * Name of the executable section within the file to load. 147 * @return 148 * BPF handle that is used in future BPF operations, 149 * or NULL on error, with error code set in rte_errno. 150 * Possible rte_errno errors include: 151 * - EINVAL - invalid parameter passed to function 152 * - ENOMEM - can't reserve enough memory 153 */ 154 struct rte_bpf * 155 rte_bpf_elf_load(const struct rte_bpf_prm *prm, const char *fname, 156 const char *sname); 157 /** 158 * Execute given BPF bytecode. 159 * 160 * @param bpf 161 * handle for the BPF code to execute. 162 * @param ctx 163 * pointer to input context. 164 * @return 165 * BPF execution return value. 166 */ 167 uint64_t 168 rte_bpf_exec(const struct rte_bpf *bpf, void *ctx); 169 170 /** 171 * Execute given BPF bytecode over a set of input contexts. 172 * 173 * @param bpf 174 * handle for the BPF code to execute. 175 * @param ctx 176 * array of pointers to the input contexts. 177 * @param rc 178 * array of return values (one per input). 179 * @param num 180 * number of elements in ctx[] (and rc[]). 181 * @return 182 * number of successfully processed inputs. 183 */ 184 uint32_t 185 rte_bpf_exec_burst(const struct rte_bpf *bpf, void *ctx[], uint64_t rc[], 186 uint32_t num); 187 188 /** 189 * Provide information about natively compiled code for given BPF handle. 190 * 191 * @param bpf 192 * handle for the BPF code. 193 * @param jit 194 * pointer to the rte_bpf_jit structure to be filled with related data. 195 * @return 196 * - -EINVAL if the parameters are invalid. 197 * - Zero if operation completed successfully. 198 */ 199 int 200 rte_bpf_get_jit(const struct rte_bpf *bpf, struct rte_bpf_jit *jit); 201 202 /** 203 * Dump epf instructions to a file. 204 * 205 * @param f 206 * A pointer to a file for output 207 * @param buf 208 * A pointer to BPF instructions 209 * @param len 210 * Number of BPF instructions to dump. 211 */ 212 __rte_experimental 213 void 214 rte_bpf_dump(FILE *f, const struct ebpf_insn *buf, uint32_t len); 215 216 struct bpf_program; 217 218 /** 219 * Convert a Classic BPF program from libpcap into a DPDK BPF code. 220 * 221 * @param prog 222 * Classic BPF program from pcap_compile(). 223 * @return 224 * Pointer to BPF program (allocated with *rte_malloc*) 225 * that is used in future BPF operations, 226 * or NULL on error, with error code set in rte_errno. 227 * Possible rte_errno errors include: 228 * - EINVAL - invalid parameter passed to function 229 * - ENOMEM - can't reserve enough memory 230 * - ENOTSUP - operation not supported 231 */ 232 __rte_experimental 233 struct rte_bpf_prm * 234 rte_bpf_convert(const struct bpf_program *prog); 235 236 #ifdef __cplusplus 237 } 238 #endif 239 240 #endif /* _RTE_BPF_H_ */ 241