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         size_t size;     /**< for pointer types, size of data it points to */
  44         size_t buf_size;
  45         /**< for mbuf ptr type, max size of rte_mbuf data buffer */
  46 };
  47
  48 /**
  49  * determine is argument a pointer
  50  */
  51 #define RTE_BPF_ARG_PTR_TYPE(x) ((x) & RTE_BPF_ARG_PTR)
  52
  53 /**
  54  * Possible types for external symbols.
  55  */
  56 enum rte_bpf_xtype {
  57         RTE_BPF_XTYPE_FUNC, /**< function */
  58         RTE_BPF_XTYPE_VAR,  /**< variable */
  59         RTE_BPF_XTYPE_NUM
  60 };
  61
  62 /**
  63  * Definition for external symbols available in the BPF program.
  64  */
  65 struct rte_bpf_xsym {
  66         const char *name;        /**< name */
  67         enum rte_bpf_xtype type; /**< type */
  68         union {
  69                 uint64_t (*func)(uint64_t, uint64_t, uint64_t,
  70                                 uint64_t, uint64_t);
  71                 void *var;
  72         }; /**< value */
  73 };
  74
  75 /**
  76  * Input parameters for loading eBPF code.
  77  */
  78 struct rte_bpf_prm {
  79         const struct ebpf_insn *ins; /**< array of eBPF instructions */
  80         uint32_t nb_ins;            /**< number of instructions in ins */
  81         const struct rte_bpf_xsym *xsym;
  82         /**< array of external symbols that eBPF code is allowed to reference */
  83         uint32_t nb_xsym; /**< number of elements in xsym */
  84         struct rte_bpf_arg prog_arg; /**< eBPF program input arg description */
  85 };
  86
  87 /**
  88  * Information about compiled into native ISA eBPF code.
  89  */
  90 struct rte_bpf_jit {
  91         uint64_t (*func)(void *); /**< JIT-ed native code */
  92         size_t sz;                /**< size of JIT-ed code */
  93 };
  94
  95 struct rte_bpf;
  96
  97 /**
  98  * De-allocate all memory used by this eBPF execution context.
  99  *
 100  * @param bpf
 101  *   BPF handle to destroy.
 102  */
 103 void __rte_experimental
 104 rte_bpf_destroy(struct rte_bpf *bpf);
 105
 106 /**
 107  * Create a new eBPF execution context and load given BPF code into it.
 108  *
 109  * @param prm
 110  *  Parameters used to create and initialise the BPF exeution context.
 111  * @return
 112  *   BPF handle that is used in future BPF operations,
 113  *   or NULL on error, with error code set in rte_errno.
 114  *   Possible rte_errno errors include:
 115  *   - EINVAL - invalid parameter passed to function
 116  *   - ENOMEM - can't reserve enough memory
 117  */
 118 struct rte_bpf * __rte_experimental
 119 rte_bpf_load(const struct rte_bpf_prm *prm);
 120
 121 /**
 122  * Create a new eBPF execution context and load BPF code from given ELF
 123  * file into it.
 124  *
 125  * @param prm
 126  *  Parameters used to create and initialise the BPF exeution context.
 127  * @param fname
 128  *  Pathname for a ELF file.
 129  * @param sname
 130  *  Name of the executable section within the file to load.
 131  * @return
 132  *   BPF handle that is used in future BPF operations,
 133  *   or NULL on error, with error code set in rte_errno.
 134  *   Possible rte_errno errors include:
 135  *   - EINVAL - invalid parameter passed to function
 136  *   - ENOMEM - can't reserve enough memory
 137  */
 138 struct rte_bpf * __rte_experimental
 139 rte_bpf_elf_load(const struct rte_bpf_prm *prm, const char *fname,
 140                 const char *sname);
 141 /**
 142  * Execute given BPF bytecode.
 143  *
 144  * @param bpf
 145  *   handle for the BPF code to execute.
 146  * @param ctx
 147  *   pointer to input context.
 148  * @return
 149  *   BPF execution return value.
 150  */
 151 uint64_t __rte_experimental
 152 rte_bpf_exec(const struct rte_bpf *bpf, void *ctx);
 153
 154 /**
 155  * Execute given BPF bytecode over a set of input contexts.
 156  *
 157  * @param bpf
 158  *   handle for the BPF code to execute.
 159  * @param ctx
 160  *   array of pointers to the input contexts.
 161  * @param rc
 162  *   array of return values (one per input).
 163  * @param num
 164  *   number of elements in ctx[] (and rc[]).
 165  * @return
 166  *   number of successfully processed inputs.
 167  */
 168 uint32_t __rte_experimental
 169 rte_bpf_exec_burst(const struct rte_bpf *bpf, void *ctx[], uint64_t rc[],
 170                 uint32_t num);
 171
 172 /**
 173  * Provide information about natively compield code for given BPF handle.
 174  *
 175  * @param bpf
 176  *   handle for the BPF code.
 177  * @param jit
 178  *   pointer to the rte_bpf_jit structure to be filled with related data.
 179  * @return
 180  *   - -EINVAL if the parameters are invalid.
 181  *   - Zero if operation completed successfully.
 182  */
 183 int __rte_experimental
 184 rte_bpf_get_jit(const struct rte_bpf *bpf, struct rte_bpf_jit *jit);
 185
 186 #ifdef __cplusplus
 187 }
 188 #endif
 189
 190 #endif /* _RTE_BPF_H_ */