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