BPF in DPDK 18.05 as experimental

BPF in DPDK 18.05 as experimental

[Thomas Monjalon]

DPDK 18.05-rc3 will have a BPF experimental framework.

The symbols have been marked as experimental in the map file,
but the doxygen has no experimental mention,
the section in MAINTAINERS has not the EXPERIMENTAL tag,
and the API functions have not the attribute __rte_experimental.
Konstantin, please make a patch to make the experimental status clear.

Thanks

[PATCH] bpf: add missed EXPERIMENTAL tags

[Konstantin Ananyev]

- add EXPERIMENTAL tag for the section in MAINTAINERS.
- add EXPERIMENTAL tag to BPF public API files.
- add attribute __rte_experimental to BPF public API declarations.

Fixes: 94972f35a02e ("bpf: add BPF loading and execution framework")
Fixes: 5dba93ae5f2d ("bpf: add ability to load eBPF program from ELF")
Fixes: a93ff62a8938 ("bpf: add BPF loading and execution framework")

Reported-by: Thomas Monjalon <thomas@monjalon.net>
Signed-off-by: Konstantin Ananyev <konstantin.ananyev@intel.com>
---
 MAINTAINERS                     |  2 +-
 lib/librte_bpf/rte_bpf.h        | 26 ++++++++++++++++----------
 lib/librte_bpf/rte_bpf_ethdev.h | 15 ++++++++++-----
 3 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index 7a18e0dbf..2663f1c03 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -1100,7 +1100,7 @@ Latency statistics
 M: Reshma Pattan <reshma.pattan@intel.com>
 F: lib/librte_latencystats/
 
-BPF
+BPF - EXPERIMENTAL
 M: Konstantin Ananyev <konstantin.ananyev@intel.com>
 F: lib/librte_bpf/
 F: test/bpf/
diff --git a/lib/librte_bpf/rte_bpf.h b/lib/librte_bpf/rte_bpf.h
index 1d6c4a9d2..1249a992c 100644
--- 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
@@ -99,7 +100,8 @@ struct rte_bpf;
  * @param bpf
  *   BPF handle to destroy.
  */
-void rte_bpf_destroy(struct rte_bpf *bpf);
+void __rte_experimental
+rte_bpf_destroy(struct rte_bpf *bpf);
 
 /**
  * Create a new eBPF execution context and load given BPF code into it.
@@ -113,7 +115,8 @@ 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);
+struct rte_bpf * __rte_experimental
+rte_bpf_load(const struct rte_bpf_prm *prm);
 
 /**
  * Create a new eBPF execution context and load BPF code from given ELF
@@ -132,9 +135,9 @@ struct rte_bpf *rte_bpf_load(const struct rte_bpf_prm *prm);
  *   - EINVAL - invalid parameter passed to function
  *   - ENOMEM - can't reserve enough memory
  */
-struct rte_bpf *rte_bpf_elf_load(const struct rte_bpf_prm *prm,
-	const char *fname, const char *sname);
-
+struct rte_bpf * __rte_experimental
+rte_bpf_elf_load(const struct rte_bpf_prm *prm, const char *fname,
+		const char *sname);
 /**
  * Execute given BPF bytecode.
  *
@@ -145,7 +148,8 @@ struct rte_bpf *rte_bpf_elf_load(const struct rte_bpf_prm *prm,
  * @return
  *   BPF execution return value.
  */
-uint64_t rte_bpf_exec(const struct rte_bpf *bpf, void *ctx);
+uint64_t __rte_experimental
+rte_bpf_exec(const struct rte_bpf *bpf, void *ctx);
 
 /**
  * Execute given BPF bytecode over a set of input contexts.
@@ -161,8 +165,9 @@ 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);
+uint32_t __rte_experimental
+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.
@@ -175,7 +180,8 @@ 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);
+int __rte_experimental
+rte_bpf_get_jit(const struct rte_bpf *bpf, struct rte_bpf_jit *jit);
 
 #ifdef __cplusplus
 }
diff --git a/lib/librte_bpf/rte_bpf_ethdev.h b/lib/librte_bpf/rte_bpf_ethdev.h
index b4d4d3b16..31731e7a9 100644
--- a/lib/librte_bpf/rte_bpf_ethdev.h
+++ b/lib/librte_bpf/rte_bpf_ethdev.h
@@ -6,7 +6,8 @@
 #define _RTE_BPF_ETHDEV_H_
 
 /**
- * @file
+ * @file rte_bpf_ethdev.h
+ * @b EXPERIMENTAL: this API may change without prior notice
  *
  * API to install BPF filter as RX/TX callbacks for eth devices.
  * Note that right now:
@@ -44,7 +45,8 @@ enum {
  * @param queue
  *   The identifier of the RX queue on the given port
  */
-void rte_bpf_eth_rx_unload(uint16_t port, uint16_t queue);
+void __rte_experimental
+rte_bpf_eth_rx_unload(uint16_t port, uint16_t queue);
 
 /**
  * Unload previously loaded BPF program (if any) from given TX port/queue
@@ -55,7 +57,8 @@ void rte_bpf_eth_rx_unload(uint16_t port, uint16_t queue);
  * @param queue
  *   The identifier of the TX queue on the given port
  */
-void rte_bpf_eth_tx_unload(uint16_t port, uint16_t queue);
+void __rte_experimental
+rte_bpf_eth_tx_unload(uint16_t port, uint16_t queue);
 
 /**
  * Load BPF program from the ELF file and install callback to execute it
@@ -77,7 +80,8 @@ void rte_bpf_eth_tx_unload(uint16_t port, uint16_t queue);
  * @return
  *   Zero on successful completion or negative error code otherwise.
  */
-int rte_bpf_eth_rx_elf_load(uint16_t port, uint16_t queue,
+int __rte_experimental
+rte_bpf_eth_rx_elf_load(uint16_t port, uint16_t queue,
 	const struct rte_bpf_prm *prm, const char *fname, const char *sname,
 	uint32_t flags);
 
@@ -101,7 +105,8 @@ int rte_bpf_eth_rx_elf_load(uint16_t port, uint16_t queue,
  * @return
  *   Zero on successful completion or negative error code otherwise.
  */
-int rte_bpf_eth_tx_elf_load(uint16_t port, uint16_t queue,
+int __rte_experimental
+rte_bpf_eth_tx_elf_load(uint16_t port, uint16_t queue,
 	const struct rte_bpf_prm *prm, const char *fname, const char *sname,
 	uint32_t flags);
 
-- 
2.13.6

Re: [PATCH] bpf: add missed EXPERIMENTAL tags

[Ferruh Yigit]

On 5/14/2018 2:15 PM, Konstantin Ananyev wrote:
> - add EXPERIMENTAL tag for the section in MAINTAINERS.
> - add EXPERIMENTAL tag to BPF public API files.
> - add attribute __rte_experimental to BPF public API declarations.
> 
> Fixes: 94972f35a02e ("bpf: add BPF loading and execution framework")
> Fixes: 5dba93ae5f2d ("bpf: add ability to load eBPF program from ELF")
> Fixes: a93ff62a8938 ("bpf: add BPF loading and execution framework")
> 
> Reported-by: Thomas Monjalon <thomas@monjalon.net>
> Signed-off-by: Konstantin Ananyev <konstantin.ananyev@intel.com>

Off the topic.

I guess this patch earned a free Ack as being pactwork patch 40000 :)
https://dpdk.org/dev/patchwork/patch/40000/


The historical numbers from DPDK patchwork:
40000 - May 14, 2018 (217 days)
30000 - Oct. 9, 2017 (258 days)
20000 - Jan. 25, 2017 (372 days)
10000 - Jan. 20, 2016 (645 days)
00001 - April 16, 2014


DPDK is getting faster and faster :)

Re: [PATCH] bpf: add missed EXPERIMENTAL tags

[Thomas Monjalon]

14/05/2018 16:20, Ferruh Yigit:
> On 5/14/2018 2:15 PM, Konstantin Ananyev wrote:
> > - add EXPERIMENTAL tag for the section in MAINTAINERS.
> > - add EXPERIMENTAL tag to BPF public API files.
> > - add attribute __rte_experimental to BPF public API declarations.
> > 
> > Fixes: 94972f35a02e ("bpf: add BPF loading and execution framework")
> > Fixes: 5dba93ae5f2d ("bpf: add ability to load eBPF program from ELF")
> > Fixes: a93ff62a8938 ("bpf: add BPF loading and execution framework")
> > 
> > Reported-by: Thomas Monjalon <thomas@monjalon.net>
> > Signed-off-by: Konstantin Ananyev <konstantin.ananyev@intel.com>
> 
> Off the topic.
> 
> I guess this patch earned a free Ack as being pactwork patch 40000 :)
> https://dpdk.org/dev/patchwork/patch/40000/
> 
> 
> The historical numbers from DPDK patchwork:
> 40000 - May 14, 2018 (217 days)
> 30000 - Oct. 9, 2017 (258 days)
> 20000 - Jan. 25, 2017 (372 days)
> 10000 - Jan. 20, 2016 (645 days)
> 00001 - April 16, 2014
> 
> 
> DPDK is getting faster and faster :)

Yes, it's impressive and scary!

Re: [PATCH] bpf: add missed EXPERIMENTAL tags

[Thomas Monjalon]

14/05/2018 15:15, Konstantin Ananyev:
> - add EXPERIMENTAL tag for the section in MAINTAINERS.
> - add EXPERIMENTAL tag to BPF public API files.
> - add attribute __rte_experimental to BPF public API declarations.
> 
> Fixes: 94972f35a02e ("bpf: add BPF loading and execution framework")
> Fixes: 5dba93ae5f2d ("bpf: add ability to load eBPF program from ELF")
> Fixes: a93ff62a8938 ("bpf: add BPF loading and execution framework")
> 
> Reported-by: Thomas Monjalon <thomas@monjalon.net>
> Signed-off-by: Konstantin Ananyev <konstantin.ananyev@intel.com>
> ---
>  MAINTAINERS                     |  2 +-
>  lib/librte_bpf/rte_bpf.h        | 26 ++++++++++++++++----------
>  lib/librte_bpf/rte_bpf_ethdev.h | 15 ++++++++++-----
>  3 files changed, 27 insertions(+), 16 deletions(-)

You need to add __rte_experimental in function definitions too (.c file).

There is a tool to check it: buildtools/check-experimental-syms.sh

Re: [PATCH] bpf: add missed EXPERIMENTAL tags

[Ananyev, Konstantin]

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas@monjalon.net]
> Sent: Monday, May 14, 2018 3:31 PM
> To: Ananyev, Konstantin <konstantin.ananyev@intel.com>
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH] bpf: add missed EXPERIMENTAL tags
> 
> 14/05/2018 15:15, Konstantin Ananyev:
> > - add EXPERIMENTAL tag for the section in MAINTAINERS.
> > - add EXPERIMENTAL tag to BPF public API files.
> > - add attribute __rte_experimental to BPF public API declarations.
> >
> > Fixes: 94972f35a02e ("bpf: add BPF loading and execution framework")
> > Fixes: 5dba93ae5f2d ("bpf: add ability to load eBPF program from ELF")
> > Fixes: a93ff62a8938 ("bpf: add BPF loading and execution framework")
> >
> > Reported-by: Thomas Monjalon <thomas@monjalon.net>
> > Signed-off-by: Konstantin Ananyev <konstantin.ananyev@intel.com>
> > ---
> >  MAINTAINERS                     |  2 +-
> >  lib/librte_bpf/rte_bpf.h        | 26 ++++++++++++++++----------
> >  lib/librte_bpf/rte_bpf_ethdev.h | 15 ++++++++++-----
> >  3 files changed, 27 insertions(+), 16 deletions(-)
> 
> You need to add __rte_experimental in function definitions too (.c file).

I believe that was done in initial commit.

> 
> There is a tool to check it: buildtools/check-experimental-syms.sh
> 

./buildtools/check-experimental-syms.sh lib/librte_bpf/rte_bpf_version.map x86_64-native-linuxapp-gcc-meson/lib/librte_bpf.a

Don't produce any errors/warnings for me.
Do I miss something here?

Konstantin

Re: [PATCH] bpf: add missed EXPERIMENTAL tags

[Thomas Monjalon]

14/05/2018 16:55, Ananyev, Konstantin:
> 
> > -----Original Message-----
> > From: Thomas Monjalon [mailto:thomas@monjalon.net]
> > Sent: Monday, May 14, 2018 3:31 PM
> > To: Ananyev, Konstantin <konstantin.ananyev@intel.com>
> > Cc: dev@dpdk.org
> > Subject: Re: [dpdk-dev] [PATCH] bpf: add missed EXPERIMENTAL tags
> > 
> > 14/05/2018 15:15, Konstantin Ananyev:
> > > - add EXPERIMENTAL tag for the section in MAINTAINERS.
> > > - add EXPERIMENTAL tag to BPF public API files.
> > > - add attribute __rte_experimental to BPF public API declarations.
> > >
> > > Fixes: 94972f35a02e ("bpf: add BPF loading and execution framework")
> > > Fixes: 5dba93ae5f2d ("bpf: add ability to load eBPF program from ELF")
> > > Fixes: a93ff62a8938 ("bpf: add BPF loading and execution framework")
> > >
> > > Reported-by: Thomas Monjalon <thomas@monjalon.net>
> > > Signed-off-by: Konstantin Ananyev <konstantin.ananyev@intel.com>
> > > ---
> > >  MAINTAINERS                     |  2 +-
> > >  lib/librte_bpf/rte_bpf.h        | 26 ++++++++++++++++----------
> > >  lib/librte_bpf/rte_bpf_ethdev.h | 15 ++++++++++-----
> > >  3 files changed, 27 insertions(+), 16 deletions(-)
> > 
> > You need to add __rte_experimental in function definitions too (.c file).
> 
> I believe that was done in initial commit.

I did not check, sorry.

> > There is a tool to check it: buildtools/check-experimental-syms.sh
> > 
> 
> ./buildtools/check-experimental-syms.sh lib/librte_bpf/rte_bpf_version.map x86_64-native-linuxapp-gcc-meson/lib/librte_bpf.a
> 
> Don't produce any errors/warnings for me.
> Do I miss something here?

No, it's me doing wrong assumption :)

Re: [PATCH] bpf: add missed EXPERIMENTAL tags

[Thomas Monjalon]

14/05/2018 15:15, Konstantin Ananyev:
> - add EXPERIMENTAL tag for the section in MAINTAINERS.
> - add EXPERIMENTAL tag to BPF public API files.
> - add attribute __rte_experimental to BPF public API declarations.
> 
> Fixes: 94972f35a02e ("bpf: add BPF loading and execution framework")
> Fixes: 5dba93ae5f2d ("bpf: add ability to load eBPF program from ELF")
> Fixes: a93ff62a8938 ("bpf: add BPF loading and execution framework")
> 
> Reported-by: Thomas Monjalon <thomas@monjalon.net>
> Signed-off-by: Konstantin Ananyev <konstantin.ananyev@intel.com>

Applied, thanks