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  * @b EXPERIMENTAL: this API may change without prior notice
  11  *
  12  * RTE BPF support.
  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_PTR_STACK,
  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         RTE_BPF_XTYPE_NUM
  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 __rte_experimental
 117 void
 118 rte_bpf_destroy(struct rte_bpf *bpf);
 119
 120 /**
 121  * Create a new eBPF execution context and load given BPF code into it.
 122  *
 123  * @param prm
 124  *  Parameters used to create and initialise the BPF execution context.
 125  * @return
 126  *   BPF handle that is used in future BPF operations,
 127  *   or NULL on error, with error code set in rte_errno.
 128  *   Possible rte_errno errors include:
 129  *   - EINVAL - invalid parameter passed to function
 130  *   - ENOMEM - can't reserve enough memory
 131  */
 132 __rte_experimental
 133 struct rte_bpf *
 134 rte_bpf_load(const struct rte_bpf_prm *prm);
 135
 136 /**
 137  * Create a new eBPF execution context and load BPF code from given ELF
 138  * file into it.
 139  * Note that if the function will encounter EBPF_PSEUDO_CALL instruction
 140  * that references external symbol, it will treat is as standard BPF_CALL
 141  * to the external helper function.
 142  *
 143  * @param prm
 144  *  Parameters used to create and initialise the BPF execution context.
 145  * @param fname
 146  *  Pathname for a ELF file.
 147  * @param sname
 148  *  Name of the executable section within the file to load.
 149  * @return
 150  *   BPF handle that is used in future BPF operations,
 151  *   or NULL on error, with error code set in rte_errno.
 152  *   Possible rte_errno errors include:
 153  *   - EINVAL - invalid parameter passed to function
 154  *   - ENOMEM - can't reserve enough memory
 155  */
 156 __rte_experimental
 157 struct rte_bpf *
 158 rte_bpf_elf_load(const struct rte_bpf_prm *prm, const char *fname,
 159                 const char *sname);
 160 /**
 161  * Execute given BPF bytecode.
 162  *
 163  * @param bpf
 164  *   handle for the BPF code to execute.
 165  * @param ctx
 166  *   pointer to input context.
 167  * @return
 168  *   BPF execution return value.
 169  */
 170 __rte_experimental
 171 uint64_t
 172 rte_bpf_exec(const struct rte_bpf *bpf, void *ctx);
 173
 174 /**
 175  * Execute given BPF bytecode over a set of input contexts.
 176  *
 177  * @param bpf
 178  *   handle for the BPF code to execute.
 179  * @param ctx
 180  *   array of pointers to the input contexts.
 181  * @param rc
 182  *   array of return values (one per input).
 183  * @param num
 184  *   number of elements in ctx[] (and rc[]).
 185  * @return
 186  *   number of successfully processed inputs.
 187  */
 188 __rte_experimental
 189 uint32_t
 190 rte_bpf_exec_burst(const struct rte_bpf *bpf, void *ctx[], uint64_t rc[],
 191                 uint32_t num);
 192
 193 /**
 194  * Provide information about natively compiled code for given BPF handle.
 195  *
 196  * @param bpf
 197  *   handle for the BPF code.
 198  * @param jit
 199  *   pointer to the rte_bpf_jit structure to be filled with related data.
 200  * @return
 201  *   - -EINVAL if the parameters are invalid.
 202  *   - Zero if operation completed successfully.
 203  */
 204 __rte_experimental
 205 int
 206 rte_bpf_get_jit(const struct rte_bpf *bpf, struct rte_bpf_jit *jit);
 207
 208 #ifdef __cplusplus
 209 }
 210 #endif
 211
 212 #endif /* _RTE_BPF_H_ */