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