bpf: hide internal program argument type

[dpdk.git] / lib / librte_bpf / rte_bpf.h

diff --git a/lib/librte_bpf/rte_bpf.h b/lib/librte_bpf/rte_bpf.h
index 4b3d970..cbf1cdd 100644 (file)
--- a/lib/librte_bpf/rte_bpf.h
+++ b/lib/librte_bpf/rte_bpf.h
@@ -6,7 +6,8 @@
 #define _RTE_BPF_H_
 
 /**
- * @file
+ * @file rte_bpf.h
+ * @b EXPERIMENTAL: this API may change without prior notice
  *
  * RTE BPF support.
  * librte_bpf provides a framework to load and execute eBPF bytecode
@@ -31,7 +32,7 @@ enum rte_bpf_arg_type {
        RTE_BPF_ARG_RAW,        /**< scalar value */
        RTE_BPF_ARG_PTR = 0x10, /**< pointer to data buffer */
        RTE_BPF_ARG_PTR_MBUF,   /**< pointer to rte_mbuf */
-       RTE_BPF_ARG_PTR_STACK,
+       RTE_BPF_ARG_RESERVED,   /**< reserved for internal use */
 };
 
 /**
@@ -39,7 +40,11 @@ enum rte_bpf_arg_type {
  */
 struct rte_bpf_arg {
        enum rte_bpf_arg_type type;
-       size_t size;     /**< for pointer types, size of data it points to */
+       /**
+        * for ptr type - max size of data buffer it points to
+        * for raw type - the size (in bytes) of the value
+        */
+       size_t size;
        size_t buf_size;
        /**< for mbuf ptr type, max size of rte_mbuf data buffer */
 };
@@ -65,10 +70,19 @@ struct rte_bpf_xsym {
        const char *name;        /**< name */
        enum rte_bpf_xtype type; /**< type */
        union {
-               uint64_t (*func)(uint64_t, uint64_t, uint64_t,
+               struct {
+                       uint64_t (*val)(uint64_t, uint64_t, uint64_t,
                                uint64_t, uint64_t);
-               void *var;
-       }; /**< value */
+                       uint32_t nb_args;
+                       struct rte_bpf_arg args[EBPF_FUNC_MAX_ARGS];
+                       /**< Function arguments descriptions. */
+                       struct rte_bpf_arg ret; /**< function return value. */
+               } func;
+               struct {
+                       void *val; /**< actual memory location */
+                       struct rte_bpf_arg desc; /**< type, size, etc. */
+               } var; /**< external variable */
+       };
 };
 
 /**
@@ -99,13 +113,15 @@ struct rte_bpf;
  * @param bpf
  *   BPF handle to destroy.
  */
-void rte_bpf_destroy(struct rte_bpf *bpf);
+__rte_experimental
+void
+rte_bpf_destroy(struct rte_bpf *bpf);
 
 /**
  * Create a new eBPF execution context and load given BPF code into it.
  *
  * @param prm
- *  Parameters used to create and initialise the BPF exeution context.
+ *  Parameters used to create and initialise the BPF execution context.
  * @return
  *   BPF handle that is used in future BPF operations,
  *   or NULL on error, with error code set in rte_errno.
@@ -113,8 +129,34 @@ void rte_bpf_destroy(struct rte_bpf *bpf);
  *   - EINVAL - invalid parameter passed to function
  *   - ENOMEM - can't reserve enough memory
  */
-struct rte_bpf *rte_bpf_load(const struct rte_bpf_prm *prm);
+__rte_experimental
+struct rte_bpf *
+rte_bpf_load(const struct rte_bpf_prm *prm);
 
+/**
+ * Create a new eBPF execution context and load BPF code from given ELF
+ * file into it.
+ * Note that if the function will encounter EBPF_PSEUDO_CALL instruction
+ * that references external symbol, it will treat is as standard BPF_CALL
+ * to the external helper function.
+ *
+ * @param prm
+ *  Parameters used to create and initialise the BPF execution context.
+ * @param fname
+ *  Pathname for a ELF file.
+ * @param sname
+ *  Name of the executable section within the file to load.
+ * @return
+ *   BPF handle that is used in future BPF operations,
+ *   or NULL on error, with error code set in rte_errno.
+ *   Possible rte_errno errors include:
+ *   - EINVAL - invalid parameter passed to function
+ *   - ENOMEM - can't reserve enough memory
+ */
+__rte_experimental
+struct rte_bpf *
+rte_bpf_elf_load(const struct rte_bpf_prm *prm, const char *fname,
+               const char *sname);
 /**
  * Execute given BPF bytecode.
  *
@@ -125,7 +167,9 @@ struct rte_bpf *rte_bpf_load(const struct rte_bpf_prm *prm);
  * @return
  *   BPF execution return value.
  */
-uint64_t rte_bpf_exec(const struct rte_bpf *bpf, void *ctx);
+__rte_experimental
+uint64_t
+rte_bpf_exec(const struct rte_bpf *bpf, void *ctx);
 
 /**
  * Execute given BPF bytecode over a set of input contexts.
@@ -141,11 +185,13 @@ uint64_t rte_bpf_exec(const struct rte_bpf *bpf, void *ctx);
  * @return
  *   number of successfully processed inputs.
  */
-uint32_t rte_bpf_exec_burst(const struct rte_bpf *bpf, void *ctx[],
-       uint64_t rc[], uint32_t num);
+__rte_experimental
+uint32_t
+rte_bpf_exec_burst(const struct rte_bpf *bpf, void *ctx[], uint64_t rc[],
+               uint32_t num);
 
 /**
- * Provide information about natively compield code for given BPF handle.
+ * Provide information about natively compiled code for given BPF handle.
  *
  * @param bpf
  *   handle for the BPF code.
@@ -155,7 +201,9 @@ uint32_t rte_bpf_exec_burst(const struct rte_bpf *bpf, void *ctx[],
  *   - -EINVAL if the parameters are invalid.
  *   - Zero if operation completed successfully.
  */
-int rte_bpf_get_jit(const struct rte_bpf *bpf, struct rte_bpf_jit *jit);
+__rte_experimental
+int
+rte_bpf_get_jit(const struct rte_bpf *bpf, struct rte_bpf_jit *jit);
 
 #ifdef __cplusplus
 }