lib/librte_bpf/rte_bpf.h

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