devtools: test pkg-config file
[dpdk.git] / 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_ */