mark experimental variables
RFC PATCH 1/1 mark experimental variables
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a __rte_experimental_var tag and mark existing variables.
---
Quick patch to try to catch experimental variables.
Not sure if we could use a single section, so please advise if there is better to do about this.
--- buildtools/check-experimental-syms.sh | 17 +++++++++++++++-- devtools/checkpatches.sh | 14 +++++++++----- doc/guides/contributing/abi_policy.rst | 7 ++++--- drivers/net/ice/rte_pmd_ice.h | 3 +++ lib/librte_cryptodev/rte_crypto_asym.h | 3 +++ lib/librte_eal/common/include/rte_compat.h | 5 +++++ lib/librte_ethdev/rte_flow.h | 17 +++++++++++++++++ lib/librte_port/rte_port_eventdev.h | 5 +++++ 8 files changed, 61 insertions(+), 10 deletions(-)
buildtools/check-experimental-syms.sh +15 -2
@@ -34,13 +34,26 @@ do Please add __rte_experimental to the definition of $SYM END_OF_MESSAGE ret=1 + elif grep -q "\.data.*[[:space:]]$SYM$" $DUMPFILE && + ! grep -q "\.data\.experimental.*[[:space:]]$SYM$" $DUMPFILE + then + cat >&2 <<- END_OF_MESSAGE + $SYM is not flagged as experimental + but is listed in version map + Please add __rte_experimental_var to the definition of $SYM + END_OF_MESSAGE + ret=1 fi done # Filter out symbols suffixed with a . for icc for SYM in `awk '{ - if ($2 != "l" && $4 == ".text.experimental" && !($NF ~ /\.$/)) { - print $NF + if ($2 == "l" || $NF ~ /\.$/) { + next; + } + if ($4 == ".text.experimental" || + $4 == ".data.experimental") { + print $NF; } }' $DUMPFILE` do
devtools/checkpatches.sh +9 -5
@@ -90,11 +90,15 @@ check_experimental_tags() { # <patch> "headers ("current_file")"; ret = 1; } - if ($1 != "+__rte_experimental" || $2 != "") { - print "__rte_experimental must appear alone on the line" \ - " immediately preceding the return type of a function." - ret = 1; + + if (NF == 1 && ($1 == "+__rte_experimental" || + $1 == "+__rte_experimental_var")) { + next; } + print "__rte_experimental or __rte_experimental_var must " \ + "appear alone on the line immediately preceding the " \ + "return type of a function."; + ret = 1; } END { exit ret;
@@ -178,7 +182,7 @@ check () { # <patch> <commit> <title> ret=1 fi - ! $verbose || printf '\nChecking __rte_experimental tags:\n' + ! $verbose || printf '\nChecking __rte_experimental* tags:\n' report=$(check_experimental_tags "$tmpinput") if [ $? -ne 0 ] ; then $headline_printed || print_headline "$3"
doc/guides/contributing/abi_policy.rst +4 -3
@@ -300,9 +300,10 @@ Note that marking an API as experimental is a multi step process. To mark an API as experimental, the symbols which are desired to be exported must be placed in an EXPERIMENTAL version block in the corresponding libraries' version map script. -Secondly, the corresponding prototypes of those exported functions (in the -development header files), must be marked with the ``__rte_experimental`` tag -(see ``rte_compat.h``). +Secondly, the corresponding prototypes of those exported functions (resp. +variables) must be marked with the ``__rte_experimental`` (resp. +``__rte_experimental_var``) tag in the development header files (see +``rte_compat.h``). The DPDK build makefiles perform a check to ensure that the map file and the C code reflect the same list of symbols. This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``
drivers/net/ice/rte_pmd_ice.h +3 -0
@@ -15,6 +15,8 @@*/ #include <stdio.h> + +#include <rte_compat.h> #include <rte_mbuf.h> #include <rte_mbuf_dyn.h>
@@ -81,6 +83,7 @@ union rte_net_ice_proto_xtr_metadata { };/* Offset of mbuf dynamic field for protocol extraction data */ +__rte_experimental_var extern int rte_net_ice_dynfield_proto_xtr_metadata_offs;/* Mask of mbuf dynamic flags for protocol extraction type */
lib/librte_cryptodev/rte_crypto_asym.h +3 -0
@@ -24,6 +24,7 @@ extern "C" {#include <rte_memory.h> #include <rte_mempool.h> #include <rte_common.h> +#include <rte_compat.h> #include "rte_crypto_sym.h"
@@ -37,10 +38,12 @@ typedef struct rte_crypto_param_t { } rte_crypto_param;/** asym xform type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_xform_strings[];/** asym operations type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_op_strings[];
lib/librte_eal/common/include/rte_compat.h +5 -0
@@ -11,11 +11,16 @@#define __rte_experimental \ __attribute__((deprecated("Symbol is not yet part of stable ABI"), \ section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((deprecated("Symbol is not yet part of stable ABI"), \ +section(".data.experimental")))#else #define __rte_experimental \ __attribute__((section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((section(".data.experimental")))#endif
lib/librte_ethdev/rte_flow.h +17 -0
@@ -19,6 +19,7 @@#include <rte_arp.h> #include <rte_common.h> +#include <rte_compat.h> #include <rte_ether.h> #include <rte_icmp.h> #include <rte_ip.h>
@@ -2531,9 +2532,11 @@ struct rte_flow_action_set_meta { };/* Mbuf dynamic field offset for metadata. */ +__rte_experimental_var extern int rte_flow_dynf_metadata_offs;/* Mbuf dynamic field flag mask for metadata. */ +__rte_experimental_var extern uint64_t rte_flow_dynf_metadata_mask;/* Mbuf dynamic field pointer for metadata. */
@@ -2548,14 +2551,24 @@ __rte_experimentalstatic inline uint32_t rte_flow_dynf_metadata_get (struct rte_mbuf *m) { +#ifdef ALLOW_EXPERIMENTAL_API return *RTE_FLOW_DYNF_METADATA (m); +#else +RTE_SET_USED (m); +return 0 ; +#endif }__rte_experimental static inline voidrte_flow_dynf_metadata_set (struct rte_mbuf *m,uint32_t v) { +#ifdef ALLOW_EXPERIMENTAL_API *RTE_FLOW_DYNF_METADATA (m) = v; +#else +RTE_SET_USED (m); +RTE_SET_USED (v); +#endif }/*
@@ -2800,7 +2813,11 @@ __rte_experimentalstatic inline int rte_flow_dynf_metadata_avail (void ) { +#ifdef ALLOW_EXPERIMENTAL_API return !!rte_flow_dynf_metadata_mask; +#else +return 0 ; +#endif }/**
lib/librte_port/rte_port_eventdev.h +5 -0
@@ -25,6 +25,8 @@ extern "C" {**/ #include <stdint.h> + +#include <rte_compat.h> #include <rte_eventdev.h> #include "rte_port.h"
@@ -39,6 +41,7 @@ struct rte_port_eventdev_reader_params { };/** Eventdev_reader port operations. */ +__rte_experimental_var extern struct rte_port_in_ops rte_port_eventdev_reader_ops;/** Eventdev_writer port parameters. */
@@ -63,6 +66,7 @@ struct rte_port_eventdev_writer_params { };/** Eventdev_writer port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_ops;/** Event_writer_nodrop port parameters. */
@@ -90,6 +94,7 @@ struct rte_port_eventdev_writer_nodrop_params { };/** Eventdev_writer_nodrop port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_nodrop_ops;#ifdef __cplusplus
Signature · 1 line
2.23.0
My 2c is that it feels a little unweildy to have to annotate, every variable declaration. and also extern reference with __rte_experimental_var.
Is there any easier way?
Other minor comments below.
Quoted 68 lines · David Marchand
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing variables.Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")Signed-off-by David Marchand <[email protected]>---
Quick patch to try to catch experimental variables.
Not sure if we could use a single section, so please advise if there is better to do about this.--- buildtools/check-experimental-syms.sh | 17 +++++++++++++++-- devtools/checkpatches.sh | 14 +++++++++----- doc/guides/contributing/abi_policy.rst | 7 ++++--- drivers/net/ice/rte_pmd_ice.h | 3 +++ lib/librte_cryptodev/rte_crypto_asym.h | 3 +++ lib/librte_eal/common/include/rte_compat.h | 5 +++++ lib/librte_ethdev/rte_flow.h | 17 +++++++++++++++++ lib/librte_port/rte_port_eventdev.h | 5 +++++ 8 files changed, 61 insertions(+), 10 deletions(-)buildtools/check-experimental-syms.sh +15
-2@@ -34,13 +34,26 @@ do Please add __rte_experimental to the definition of $SYM END_OF_MESSAGE ret=1 + elif grep -q "\.data.*[[:space:]]$SYM$" $DUMPFILE && + ! grep -q "\.data\.experimental.*[[:space:]]$SYM$" $DUMPFILE + then + cat >&2 <<- END_OF_MESSAGE + $SYM is not flagged as experimental + but is listed in version map + Please add __rte_experimental_var to the definition of $SYM + END_OF_MESSAGE + ret=1 fi done # Filter out symbols suffixed with a . for icc for SYM in `awk '{ - if ($2 != "l" && $4 == ".text.experimental" && !($NF ~ /\.$/)) { - print $NF + if ($2 == "l" || $NF ~ /\.$/) { + next; + } + if ($4 == ".text.experimental" || + $4 == ".data.experimental") { + print $NF; } }' $DUMPFILE` dodevtools/checkpatches.sh +0
-2@@ -90,11 +90,15 @@ check_experimental_tags() { # <patch> "headers ("current_file")"; ret = 1; } - if ($1 != "+__rte_experimental" || $2 != "") { - print "__rte_experimental must appear alone on the line" \
devtools/checkpatches.sh check_experimental_tags() { # <patch> · line 100
Quoted 10 lines
devtools/checkpatches.sh +7
-2- " immediately preceding the return type of a function." - ret = 1; + + if (NF == 1 && ($1 == "+__rte_experimental" || + $1 == "+__rte_experimental_var")) { + next; } + print "__rte_experimental or __rte_experimental_var must " \ + "appear alone on the line immediately preceding the " \ + "return type of a function.";
or variable?
Quoted 18 lines
devtools/checkpatches.sh +2
-1+ ret = 1; } END { exit ret;@@ -178,7 +182,7 @@ check () { # <patch> <commit> <title> ret=1 fi - ! $verbose || printf '\nChecking __rte_experimental tags:\n' + ! $verbose || printf '\nChecking __rte_experimental* tags:\n' report=$(check_experimental_tags "$tmpinput") if [ $? -ne 0 ] ; then $headline_printed || print_headline "$3"doc/guides/contributing/abi_policy.rst +0
-0
doc/guides/contributing/abi_policy.rst Note that marking an API as experimental is a multi step process. · line 306
Quoted 10 lines
doc/guides/contributing/abi_policy.rst +4
-3@@ -300,9 +300,10 @@ Note that marking an API as experimental is a multi step process. To mark an API as experimental, the symbols which are desired to be exported must be placed in an EXPERIMENTAL version block in the corresponding libraries' version map script. -Secondly, the corresponding prototypes of those exported functions (in the -development header files), must be marked with the ``__rte_experimental`` tag -(see ``rte_compat.h``). +Secondly, the corresponding prototypes of those exported functions (resp. +variables) must be marked with the ``__rte_experimental`` (resp. +``__rte_experimental_var``) tag in the development header files (see +``rte_compat.h``).
Suggest simplifying as follows (remove the resp.).
Secondly, the corresponding prototypes of those exported functions (or variables) must be marked with the ``__rte_experimental`` (or ``__rte_experimental_var``) tag in the development header files (see ``rte_compat.h``).
Quoted 169 lines
doc/guides/contributing/abi_policy.rst +0
-0The DPDK build makefiles perform a check to ensure that the map file and the C code reflect the same list of symbols. This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``drivers/net/ice/rte_pmd_ice.h +3
-0@@ -15,6 +15,8 @@*/ #include <stdio.h> + +#include <rte_compat.h> #include <rte_mbuf.h> #include <rte_mbuf_dyn.h> @@ -81,6 +83,7 @@ union rte_net_ice_proto_xtr_metadata { };/* Offset of mbuf dynamic field for protocol extraction data */ +__rte_experimental_var extern int rte_net_ice_dynfield_proto_xtr_metadata_offs;/* Mask of mbuf dynamic flags for protocol extraction type */ lib/librte_cryptodev/rte_crypto_asym.h +3
-0@@ -24,6 +24,7 @@ extern "C" {#include <rte_memory.h> #include <rte_mempool.h> #include <rte_common.h> +#include <rte_compat.h> #include "rte_crypto_sym.h" @@ -37,10 +38,12 @@ typedef struct rte_crypto_param_t { } rte_crypto_param;/** asym xform type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_xform_strings[];/** asym operations type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_op_strings[];lib/librte_eal/common/include/rte_compat.h +5
-0@@ -11,11 +11,16 @@#define __rte_experimental \ __attribute__((deprecated("Symbol is not yet part of stable ABI"), \ section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((deprecated("Symbol is not yet part of stable ABI"), \ +section(".data.experimental")))#else #define __rte_experimental \ __attribute__((section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((section(".data.experimental")))#endif lib/librte_ethdev/rte_flow.h +17
-0@@ -19,6 +19,7 @@#include <rte_arp.h> #include <rte_common.h> +#include <rte_compat.h> #include <rte_ether.h> #include <rte_icmp.h> #include <rte_ip.h> @@ -2531,9 +2532,11 @@ struct rte_flow_action_set_meta { };/* Mbuf dynamic field offset for metadata. */ +__rte_experimental_var extern int rte_flow_dynf_metadata_offs;/* Mbuf dynamic field flag mask for metadata. */ +__rte_experimental_var extern uint64_t rte_flow_dynf_metadata_mask;/* Mbuf dynamic field pointer for metadata. */ @@ -2548,14 +2551,24 @@ __rte_experimentalstatic inline uint32_t rte_flow_dynf_metadata_get (struct rte_mbuf *m) { +#ifdef ALLOW_EXPERIMENTAL_API return *RTE_FLOW_DYNF_METADATA (m); +#else +RTE_SET_USED (m); +return 0 ; +#endif }__rte_experimental static inline voidrte_flow_dynf_metadata_set (struct rte_mbuf *m,uint32_t v) { +#ifdef ALLOW_EXPERIMENTAL_API *RTE_FLOW_DYNF_METADATA (m) = v; +#else +RTE_SET_USED (m); +RTE_SET_USED (v); +#endif }/* @@ -2800,7 +2813,11 @@ __rte_experimentalstatic inline int rte_flow_dynf_metadata_avail (void ) { +#ifdef ALLOW_EXPERIMENTAL_API return !!rte_flow_dynf_metadata_mask; +#else +return 0 ; +#endif }/** lib/librte_port/rte_port_eventdev.h +5
-0@@ -25,6 +25,8 @@ extern "C" {**/ #include <stdint.h> + +#include <rte_compat.h> #include <rte_eventdev.h> #include "rte_port.h" @@ -39,6 +41,7 @@ struct rte_port_eventdev_reader_params { };/** Eventdev_reader port operations. */ +__rte_experimental_var extern struct rte_port_in_ops rte_port_eventdev_reader_ops;/** Eventdev_writer port parameters. */ @@ -63,6 +66,7 @@ struct rte_port_eventdev_writer_params { };/** Eventdev_writer port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_ops;/** Event_writer_nodrop port parameters. */ @@ -90,6 +94,7 @@ struct rte_port_eventdev_writer_nodrop_params { };/** Eventdev_writer_nodrop port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_nodrop_ops;#ifdef __cplusplus
Quoted 6 lines · Ray Kinsella
My 2c is that it feels a little unweildy to have to annotate, every variable declaration. and also extern reference with
__rte_experimental_var.Is there any easier way?
We use this framework so that the users are aware they are relying on experimental API that can change overnight.
It would not happen if we could hide all of this behind accessors. But here we reference them through macros / inlines with performance in mind.
This performance impact needs to be confirmed as a real requirement. I caught some oddity like the librte_port stuff (with no in-tree users, but different topic).
Quoted 10 lines
Quoted 10 lines
devtools/checkpatches.sh +2
-4@@ -90,11 +90,15 @@ check_experimental_tags() { # <patch> "headers ("current_file")"; ret = 1; } - if ($1 != "+__rte_experimental" || $2 != "") { - print "__rte_experimental must appear alone on the line" \ - " immediately preceding the return type of a function." - ret = 1; + + if (NF == 1 && ($1 == "+__rte_experimental" ||
Quoted 8 lines
devtools/checkpatches.sh check_experimental_tags() { # <patch> · line 100
Quoted 6 lines
devtools/checkpatches.sh +5
-0+ $1 == "+__rte_experimental_var")) { + next; } + print "__rte_experimental or __rte_experimental_var must " \ + "appear alone on the line immediately preceding the " \ + "return type of a function.";or variable?
Yes.
Quoted 14 lines
doc/guides/contributing/abi_policy.rst Note that marking an API as experimental is a multi step process. · line 306
Quoted 11 lines
doc/guides/contributing/abi_policy.rst +4
-3@@ -300,9 +300,10 @@ Note that marking an API as experimental is a multi step process. To mark an API as experimental, the symbols which are desired to be exported must be placed in an EXPERIMENTAL version block in the corresponding libraries' version map script. -Secondly, the corresponding prototypes of those exported functions (in the -development header files), must be marked with the ``__rte_experimental`` tag -(see ``rte_compat.h``). +Secondly, the corresponding prototypes of those exported functions (resp. +variables) must be marked with the ``__rte_experimental`` (resp. +``__rte_experimental_var``) tag in the development header files (see +``rte_compat.h``).Suggest simplifying as follows (remove the resp.).
Quoted 4 lines
Secondly, the corresponding prototypes of those exported functions (or variables) must be marked with the ``__rte_experimental`` (or ``__rte_experimental_var``) tag in the development header files (see ``rte_compat.h``).
"or" sounds better.
Signature · 1 line
David Marchand
Quoted 6 lines · Ray Kinsella
My 2c is that it feels a little unweildy to have to annotate, every variable declaration. and also extern reference with
__rte_experimental_var.Is there any easier way?
Note, just to be clear, its not every variable, only the ones exposed as global variable meant to be accessed outside of the library that are not part of a versioned ABI.
Quoted 290 lines
Other minor comments below.
Quoted 68 lines · David Marchand
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing variables.Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")Signed-off-by David Marchand <[email protected]>---
Quick patch to try to catch experimental variables.
Not sure if we could use a single section, so please advise if there is better to do about this.--- buildtools/check-experimental-syms.sh | 17 +++++++++++++++-- devtools/checkpatches.sh | 14 +++++++++----- doc/guides/contributing/abi_policy.rst | 7 ++++--- drivers/net/ice/rte_pmd_ice.h | 3 +++ lib/librte_cryptodev/rte_crypto_asym.h | 3 +++ lib/librte_eal/common/include/rte_compat.h | 5 +++++ lib/librte_ethdev/rte_flow.h | 17 +++++++++++++++++ lib/librte_port/rte_port_eventdev.h | 5 +++++ 8 files changed, 61 insertions(+), 10 deletions(-)buildtools/check-experimental-syms.sh +15
-2@@ -34,13 +34,26 @@ do Please add __rte_experimental to the definition of $SYM END_OF_MESSAGE ret=1 + elif grep -q "\.data.*[[:space:]]$SYM$" $DUMPFILE && + ! grep -q "\.data\.experimental.*[[:space:]]$SYM$" $DUMPFILE + then + cat >&2 <<- END_OF_MESSAGE + $SYM is not flagged as experimental + but is listed in version map + Please add __rte_experimental_var to the definition of $SYM + END_OF_MESSAGE + ret=1 fi done # Filter out symbols suffixed with a . for icc for SYM in `awk '{ - if ($2 != "l" && $4 == ".text.experimental" && !($NF ~ /\.$/)) { - print $NF + if ($2 == "l" || $NF ~ /\.$/) { + next; + } + if ($4 == ".text.experimental" || + $4 == ".data.experimental") { + print $NF; } }' $DUMPFILE` dodevtools/checkpatches.sh +0
-2@@ -90,11 +90,15 @@ check_experimental_tags() { # <patch> "headers ("current_file")"; ret = 1; } - if ($1 != "+__rte_experimental" || $2 != "") { - print "__rte_experimental must appear alone on the line" \devtools/checkpatches.sh check_experimental_tags() { # <patch> · line 100
Quoted 10 lines
devtools/checkpatches.sh +7
-2- " immediately preceding the return type of a function." - ret = 1; + + if (NF == 1 && ($1 == "+__rte_experimental" || + $1 == "+__rte_experimental_var")) { + next; } + print "__rte_experimental or __rte_experimental_var must " \ + "appear alone on the line immediately preceding the " \ + "return type of a function.";or variable?
Quoted 18 lines
devtools/checkpatches.sh +2
-1+ ret = 1; } END { exit ret;@@ -178,7 +182,7 @@ check () { # <patch> <commit> <title> ret=1 fi - ! $verbose || printf '\nChecking __rte_experimental tags:\n' + ! $verbose || printf '\nChecking __rte_experimental* tags:\n' report=$(check_experimental_tags "$tmpinput") if [ $? -ne 0 ] ; then $headline_printed || print_headline "$3"doc/guides/contributing/abi_policy.rst +0
-0doc/guides/contributing/abi_policy.rst Note that marking an API as experimental is a multi step process. · line 306
Quoted 10 lines
doc/guides/contributing/abi_policy.rst +4
-3@@ -300,9 +300,10 @@ Note that marking an API as experimental is a multi step process. To mark an API as experimental, the symbols which are desired to be exported must be placed in an EXPERIMENTAL version block in the corresponding libraries' version map script. -Secondly, the corresponding prototypes of those exported functions (in the -development header files), must be marked with the ``__rte_experimental`` tag -(see ``rte_compat.h``). +Secondly, the corresponding prototypes of those exported functions (resp. +variables) must be marked with the ``__rte_experimental`` (resp. +``__rte_experimental_var``) tag in the development header files (see +``rte_compat.h``).Suggest simplifying as follows (remove the resp.).
Secondly, the corresponding prototypes of those exported functions (or variables) must be marked with the ``__rte_experimental`` (or ``__rte_experimental_var``) tag in the development header files (see ``rte_compat.h``).
Quoted 169 lines
doc/guides/contributing/abi_policy.rst +0
-0The DPDK build makefiles perform a check to ensure that the map file and the C code reflect the same list of symbols. This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``drivers/net/ice/rte_pmd_ice.h +3
-0@@ -15,6 +15,8 @@*/ #include <stdio.h> + +#include <rte_compat.h> #include <rte_mbuf.h> #include <rte_mbuf_dyn.h> @@ -81,6 +83,7 @@ union rte_net_ice_proto_xtr_metadata { };/* Offset of mbuf dynamic field for protocol extraction data */ +__rte_experimental_var extern int rte_net_ice_dynfield_proto_xtr_metadata_offs;/* Mask of mbuf dynamic flags for protocol extraction type */ lib/librte_cryptodev/rte_crypto_asym.h +3
-0@@ -24,6 +24,7 @@ extern "C" {#include <rte_memory.h> #include <rte_mempool.h> #include <rte_common.h> +#include <rte_compat.h> #include "rte_crypto_sym.h" @@ -37,10 +38,12 @@ typedef struct rte_crypto_param_t { } rte_crypto_param;/** asym xform type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_xform_strings[];/** asym operations type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_op_strings[];lib/librte_eal/common/include/rte_compat.h +5
-0@@ -11,11 +11,16 @@#define __rte_experimental \ __attribute__((deprecated("Symbol is not yet part of stable ABI"), \ section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((deprecated("Symbol is not yet part of stable ABI"), \ +section(".data.experimental")))#else #define __rte_experimental \ __attribute__((section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((section(".data.experimental")))#endif lib/librte_ethdev/rte_flow.h +17
-0@@ -19,6 +19,7 @@#include <rte_arp.h> #include <rte_common.h> +#include <rte_compat.h> #include <rte_ether.h> #include <rte_icmp.h> #include <rte_ip.h> @@ -2531,9 +2532,11 @@ struct rte_flow_action_set_meta { };/* Mbuf dynamic field offset for metadata. */ +__rte_experimental_var extern int rte_flow_dynf_metadata_offs;/* Mbuf dynamic field flag mask for metadata. */ +__rte_experimental_var extern uint64_t rte_flow_dynf_metadata_mask;/* Mbuf dynamic field pointer for metadata. */ @@ -2548,14 +2551,24 @@ __rte_experimentalstatic inline uint32_t rte_flow_dynf_metadata_get (struct rte_mbuf *m) { +#ifdef ALLOW_EXPERIMENTAL_API return *RTE_FLOW_DYNF_METADATA (m); +#else +RTE_SET_USED (m); +return 0 ; +#endif }__rte_experimental static inline voidrte_flow_dynf_metadata_set (struct rte_mbuf *m,uint32_t v) { +#ifdef ALLOW_EXPERIMENTAL_API *RTE_FLOW_DYNF_METADATA (m) = v; +#else +RTE_SET_USED (m); +RTE_SET_USED (v); +#endif }/* @@ -2800,7 +2813,11 @@ __rte_experimentalstatic inline int rte_flow_dynf_metadata_avail (void ) { +#ifdef ALLOW_EXPERIMENTAL_API return !!rte_flow_dynf_metadata_mask; +#else +return 0 ; +#endif }/** lib/librte_port/rte_port_eventdev.h +5
-0@@ -25,6 +25,8 @@ extern "C" {**/ #include <stdint.h> + +#include <rte_compat.h> #include <rte_eventdev.h> #include "rte_port.h" @@ -39,6 +41,7 @@ struct rte_port_eventdev_reader_params { };/** Eventdev_reader port operations. */ +__rte_experimental_var extern struct rte_port_in_ops rte_port_eventdev_reader_ops;/** Eventdev_writer port parameters. */ @@ -63,6 +66,7 @@ struct rte_port_eventdev_writer_params { };/** Eventdev_writer port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_ops;/** Event_writer_nodrop port parameters. */ @@ -90,6 +94,7 @@ struct rte_port_eventdev_writer_nodrop_params { };/** Eventdev_writer_nodrop port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_nodrop_ops;#ifdef __cplusplus
Quoted 5 lines · David Marchand
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing variables.
Quoted 9 lines
Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")Signed-off-by David Marchand <[email protected]>---
Quick patch to try to catch experimental variables.
Not sure if we could use a single section, so please advise if there is better to do about this.
I don't see any definition of __rte_experimental_var here, won't the preprocessor choke on this when you try to compile without that?
Neil
Quoted 264 lines
--- buildtools/check-experimental-syms.sh | 17 +++++++++++++++-- devtools/checkpatches.sh | 14 +++++++++----- doc/guides/contributing/abi_policy.rst | 7 ++++--- drivers/net/ice/rte_pmd_ice.h | 3 +++ lib/librte_cryptodev/rte_crypto_asym.h | 3 +++ lib/librte_eal/common/include/rte_compat.h | 5 +++++ lib/librte_ethdev/rte_flow.h | 17 +++++++++++++++++ lib/librte_port/rte_port_eventdev.h | 5 +++++ 8 files changed, 61 insertions(+), 10 deletions(-)buildtools/check-experimental-syms.sh +15
-2@@ -34,13 +34,26 @@ do Please add __rte_experimental to the definition of $SYM END_OF_MESSAGE ret=1 + elif grep -q "\.data.*[[:space:]]$SYM$" $DUMPFILE && + ! grep -q "\.data\.experimental.*[[:space:]]$SYM$" $DUMPFILE + then + cat >&2 <<- END_OF_MESSAGE + $SYM is not flagged as experimental + but is listed in version map + Please add __rte_experimental_var to the definition of $SYM + END_OF_MESSAGE + ret=1 fi done # Filter out symbols suffixed with a . for icc for SYM in `awk '{ - if ($2 != "l" && $4 == ".text.experimental" && !($NF ~ /\.$/)) { - print $NF + if ($2 == "l" || $NF ~ /\.$/) { + next; + } + if ($4 == ".text.experimental" || + $4 == ".data.experimental") { + print $NF; } }' $DUMPFILE` dodevtools/checkpatches.sh +9
-5@@ -90,11 +90,15 @@ check_experimental_tags() { # <patch> "headers ("current_file")"; ret = 1; } - if ($1 != "+__rte_experimental" || $2 != "") { - print "__rte_experimental must appear alone on the line" \ - " immediately preceding the return type of a function." - ret = 1; + + if (NF == 1 && ($1 == "+__rte_experimental" || + $1 == "+__rte_experimental_var")) { + next; } + print "__rte_experimental or __rte_experimental_var must " \ + "appear alone on the line immediately preceding the " \ + "return type of a function."; + ret = 1; } END { exit ret;@@ -178,7 +182,7 @@ check () { # <patch> <commit> <title> ret=1 fi - ! $verbose || printf '\nChecking __rte_experimental tags:\n' + ! $verbose || printf '\nChecking __rte_experimental* tags:\n' report=$(check_experimental_tags "$tmpinput") if [ $? -ne 0 ] ; then $headline_printed || print_headline "$3"doc/guides/contributing/abi_policy.rst +4
-3@@ -300,9 +300,10 @@ Note that marking an API as experimental is a multi step process. To mark an API as experimental, the symbols which are desired to be exported must be placed in an EXPERIMENTAL version block in the corresponding libraries' version map script. -Secondly, the corresponding prototypes of those exported functions (in the -development header files), must be marked with the ``__rte_experimental`` tag -(see ``rte_compat.h``). +Secondly, the corresponding prototypes of those exported functions (resp. +variables) must be marked with the ``__rte_experimental`` (resp. +``__rte_experimental_var``) tag in the development header files (see +``rte_compat.h``). The DPDK build makefiles perform a check to ensure that the map file and the C code reflect the same list of symbols. This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``drivers/net/ice/rte_pmd_ice.h +3
-0@@ -15,6 +15,8 @@*/ #include <stdio.h> + +#include <rte_compat.h> #include <rte_mbuf.h> #include <rte_mbuf_dyn.h> @@ -81,6 +83,7 @@ union rte_net_ice_proto_xtr_metadata { };/* Offset of mbuf dynamic field for protocol extraction data */ +__rte_experimental_var extern int rte_net_ice_dynfield_proto_xtr_metadata_offs;/* Mask of mbuf dynamic flags for protocol extraction type */ lib/librte_cryptodev/rte_crypto_asym.h +3
-0@@ -24,6 +24,7 @@ extern "C" {#include <rte_memory.h> #include <rte_mempool.h> #include <rte_common.h> +#include <rte_compat.h> #include "rte_crypto_sym.h" @@ -37,10 +38,12 @@ typedef struct rte_crypto_param_t { } rte_crypto_param;/** asym xform type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_xform_strings[];/** asym operations type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_op_strings[];lib/librte_eal/common/include/rte_compat.h +5
-0@@ -11,11 +11,16 @@#define __rte_experimental \ __attribute__((deprecated("Symbol is not yet part of stable ABI"), \ section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((deprecated("Symbol is not yet part of stable ABI"), \ +section(".data.experimental")))#else #define __rte_experimental \ __attribute__((section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((section(".data.experimental")))#endif lib/librte_ethdev/rte_flow.h +17
-0@@ -19,6 +19,7 @@#include <rte_arp.h> #include <rte_common.h> +#include <rte_compat.h> #include <rte_ether.h> #include <rte_icmp.h> #include <rte_ip.h> @@ -2531,9 +2532,11 @@ struct rte_flow_action_set_meta { };/* Mbuf dynamic field offset for metadata. */ +__rte_experimental_var extern int rte_flow_dynf_metadata_offs;/* Mbuf dynamic field flag mask for metadata. */ +__rte_experimental_var extern uint64_t rte_flow_dynf_metadata_mask;/* Mbuf dynamic field pointer for metadata. */ @@ -2548,14 +2551,24 @@ __rte_experimentalstatic inline uint32_t rte_flow_dynf_metadata_get (struct rte_mbuf *m) { +#ifdef ALLOW_EXPERIMENTAL_API return *RTE_FLOW_DYNF_METADATA (m); +#else +RTE_SET_USED (m); +return 0 ; +#endif }__rte_experimental static inline voidrte_flow_dynf_metadata_set (struct rte_mbuf *m,uint32_t v) { +#ifdef ALLOW_EXPERIMENTAL_API *RTE_FLOW_DYNF_METADATA (m) = v; +#else +RTE_SET_USED (m); +RTE_SET_USED (v); +#endif }/* @@ -2800,7 +2813,11 @@ __rte_experimentalstatic inline int rte_flow_dynf_metadata_avail (void ) { +#ifdef ALLOW_EXPERIMENTAL_API return !!rte_flow_dynf_metadata_mask; +#else +return 0 ; +#endif }/** lib/librte_port/rte_port_eventdev.h +5
-0@@ -25,6 +25,8 @@ extern "C" {**/ #include <stdint.h> + +#include <rte_compat.h> #include <rte_eventdev.h> #include "rte_port.h" @@ -39,6 +41,7 @@ struct rte_port_eventdev_reader_params { };/** Eventdev_reader port operations. */ +__rte_experimental_var extern struct rte_port_in_ops rte_port_eventdev_reader_ops;/** Eventdev_writer port parameters. */ @@ -63,6 +66,7 @@ struct rte_port_eventdev_writer_params { };/** Eventdev_writer port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_ops;/** Event_writer_nodrop port parameters. */ @@ -90,6 +94,7 @@ struct rte_port_eventdev_writer_nodrop_params { };/** Eventdev_writer_nodrop port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_nodrop_ops;#ifdef __cplusplusSignature · 1 line
2.23.0
Quoted 9 lines · Neil Horman
Quoted 8 lines · David Marchand
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing variables.Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")
Quoted 8 lines
Quoted 6 lines
Signed-off-by David Marchand <[email protected]>---
Quick patch to try to catch experimental variables.
Not sure if we could use a single section, so please advise if there is better to do about this.I don't see any definition of
__rte_experimental_varhere, won't the preprocessor choke on this when you try to compile without that?
Sorry, not getting your point.
If there is an issue, then it is the same as __rte_experimental.
[snip]
Quoted 21 lines
Quoted 21 lines
lib/librte_eal/common/include/rte_compat.h +5
-0@@ -11,11 +11,16 @@#define __rte_experimental \ __attribute__((deprecated("Symbol is not yet part of stable ABI"), \ section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((deprecated("Symbol is not yet part of stable ABI"), \ +section(".data.experimental")))#else #define __rte_experimental \ __attribute__((section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((section(".data.experimental")))#endif
Signature · 1 line
David Marchand
Neil Horman
Acked-byQuoted 16 lines · David Marchand
Quoted 15 lines · Neil Horman
Quoted 14 lines · David Marchand
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing variables.Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")Signed-off-by David Marchand <[email protected]>---
Quick patch to try to catch experimental variables.
Not sure if we could use a single section, so please advise if there is better to do about this.
Quoted 6 lines
Quoted 2 lines
I don't see any definition of
__rte_experimental_varhere, won't the preprocessor choke on this when you try to compile without that?Sorry, not getting your point.
If there is an issue, then it is the same as__rte_experimental.
No, there is no issue, I'm just blind. For some reason cscope wasn't finding the definition of __rte_experimental_var when I applied your patch for me. Its clear you have it below.
Quoted 29 lines
[snip]
Quoted 21 lines
Quoted 21 lines
lib/librte_eal/common/include/rte_compat.h +5
-0@@ -11,11 +11,16 @@#define __rte_experimental \ __attribute__((deprecated("Symbol is not yet part of stable ABI"), \ section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((deprecated("Symbol is not yet part of stable ABI"), \ +section(".data.experimental")))#else #define __rte_experimental \ __attribute__((section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((section(".data.experimental")))#endif Signature · 1 line
David Marchand
Quoted 21 lines · Neil Horman
Quoted 19 lines · David Marchand
Quoted 17 lines · Neil Horman
Quoted 5 lines · David Marchand
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing variables.Quoted 9 lines
Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")Signed-off-by David Marchand <[email protected]>---
Quick patch to try to catch experimental variables.
Not sure if we could use a single section, so please advise if there is better to do about this.I don't see any definition of
__rte_experimental_varhere, won't the preprocessor choke on this when you try to compile without that?
Quoted 6 lines
Quoted 3 lines
Sorry, not getting your point.
If there is an issue, then it is the same as__rte_experimental.No, there is no issue, I'm just blind. For some reason cscope wasn't finding the definition of
__rte_experimental_varwhen I applied your patch for me. Its clear you have it below.
Ok, thanks for confirming.
Quoted 1 line
Acked-by Neil Horman <[email protected]>
I will do an extra pass and submit a non RFC patch with your ack if I have no change.
Thanks Neil.
Signature · 1 line
David Marchand
PATCH 1/1 mark experimental variables
In reply to David MarchandSo far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a __rte_experimental_var tag and mark existing exported variables.
---
Changelog since RFC:
- s/resp\./or/ in documentation,
- caught more variables by looking at the *COM* section,
--- buildtools/check-experimental-syms.sh | 17 +++++++++++++++-- devtools/checkpatches.sh | 16 ++++++++++++---- doc/guides/contributing/abi_policy.rst | 7 ++++--- drivers/net/ice/rte_pmd_ice.h | 8 ++++++++ lib/librte_bbdev/rte_bbdev.h | 1 + lib/librte_cryptodev/rte_crypto_asym.h | 3 +++ lib/librte_eal/common/include/rte_compat.h | 5 +++++ lib/librte_ethdev/rte_flow.h | 17 +++++++++++++++++ lib/librte_port/rte_port_eventdev.h | 5 +++++ lib/librte_rcu/rte_rcu_qsbr.h | 1 + 10 files changed, 71 insertions(+), 9 deletions(-)
buildtools/check-experimental-syms.sh +15 -2
@@ -34,13 +34,26 @@ do Please add __rte_experimental to the definition of $SYM END_OF_MESSAGE ret=1 + elif grep -qe "\(\.data\|\*COM\*\).*[[:space:]]$SYM$" $DUMPFILE && + ! grep -q "\.data\.experimental.*[[:space:]]$SYM$" $DUMPFILE + then + cat >&2 <<- END_OF_MESSAGE + $SYM is not flagged as experimental + but is listed in version map + Please add __rte_experimental_var to the definition of $SYM + END_OF_MESSAGE + ret=1 fi done # Filter out symbols suffixed with a . for icc for SYM in `awk '{ - if ($2 != "l" && $4 == ".text.experimental" && !($NF ~ /\.$/)) { - print $NF + if ($2 == "l" || $NF ~ /\.$/) { + next; + } + if ($4 == ".text.experimental" || + $4 == ".data.experimental") { + print $NF; } }' $DUMPFILE` do
devtools/checkpatches.sh +12 -4
@@ -90,11 +90,19 @@ check_experimental_tags() { # <patch> "headers ("current_file")"; ret = 1; } - if ($1 != "+__rte_experimental" || $2 != "") { + + if (NF == 1 && ($1 == "+__rte_experimental" || + $1 == "+__rte_experimental_var")) { + next; + } + if ($0 ~ "__rte_experimental_var") { + print "__rte_experimental_var must appear alone on the line" \ + " immediately preceding the type of a variable."; + } else { print "__rte_experimental must appear alone on the line" \ - " immediately preceding the return type of a function." - ret = 1; + " immediately preceding the return type of a function."; } + ret = 1; } END { exit ret;
@@ -178,7 +186,7 @@ check () { # <patch> <commit> <title> ret=1 fi - ! $verbose || printf '\nChecking __rte_experimental tags:\n' + ! $verbose || printf '\nChecking __rte_experimental* tags:\n' report=$(check_experimental_tags "$tmpinput") if [ $? -ne 0 ] ; then $headline_printed || print_headline "$3"
doc/guides/contributing/abi_policy.rst +4 -3
@@ -300,9 +300,10 @@ Note that marking an API as experimental is a multi step process. To mark an API as experimental, the symbols which are desired to be exported must be placed in an EXPERIMENTAL version block in the corresponding libraries' version map script. -Secondly, the corresponding prototypes of those exported functions (in the -development header files), must be marked with the ``__rte_experimental`` tag -(see ``rte_compat.h``). +Secondly, the corresponding prototypes of those exported functions (or +variables) must be marked with the ``__rte_experimental`` (or +``__rte_experimental_var``) tag in the development header files (see +``rte_compat.h``). The DPDK build makefiles perform a check to ensure that the map file and the C code reflect the same list of symbols. This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``
drivers/net/ice/rte_pmd_ice.h +8 -0
@@ -15,6 +15,8 @@*/ #include <stdio.h> + +#include <rte_compat.h> #include <rte_mbuf.h> #include <rte_mbuf_dyn.h>
@@ -81,13 +83,19 @@ union rte_net_ice_proto_xtr_metadata { };/* Offset of mbuf dynamic field for protocol extraction data */ +__rte_experimental_var extern int rte_net_ice_dynfield_proto_xtr_metadata_offs;/* Mask of mbuf dynamic flags for protocol extraction type */ +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_vlan_mask; +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_ipv4_mask; +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_ipv6_mask; +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_ipv6_flow_mask; +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_tcp_mask;/**
lib/librte_bbdev/rte_bbdev.h +1 -0
@@ -466,6 +466,7 @@ struct __rte_cache_aligned rte_bbdev { };/** @internal array of all devices */ +__rte_experimental_var extern struct rte_bbdev rte_bbdev_devices[];/**
lib/librte_cryptodev/rte_crypto_asym.h +3 -0
@@ -24,6 +24,7 @@ extern "C" {#include <rte_memory.h> #include <rte_mempool.h> #include <rte_common.h> +#include <rte_compat.h> #include "rte_crypto_sym.h"
@@ -37,10 +38,12 @@ typedef struct rte_crypto_param_t { } rte_crypto_param;/** asym xform type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_xform_strings[];/** asym operations type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_op_strings[];
lib/librte_eal/common/include/rte_compat.h +5 -0
@@ -11,11 +11,16 @@#define __rte_experimental \ __attribute__((deprecated("Symbol is not yet part of stable ABI"), \ section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((deprecated("Symbol is not yet part of stable ABI"), \ +section(".data.experimental")))#else #define __rte_experimental \ __attribute__((section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((section(".data.experimental")))#endif
lib/librte_ethdev/rte_flow.h +17 -0
@@ -19,6 +19,7 @@#include <rte_arp.h> #include <rte_common.h> +#include <rte_compat.h> #include <rte_ether.h> #include <rte_icmp.h> #include <rte_ip.h>
@@ -2531,9 +2532,11 @@ struct rte_flow_action_set_meta { };/* Mbuf dynamic field offset for metadata. */ +__rte_experimental_var extern int rte_flow_dynf_metadata_offs;/* Mbuf dynamic field flag mask for metadata. */ +__rte_experimental_var extern uint64_t rte_flow_dynf_metadata_mask;/* Mbuf dynamic field pointer for metadata. */
@@ -2548,14 +2551,24 @@ __rte_experimentalstatic inline uint32_t rte_flow_dynf_metadata_get (struct rte_mbuf *m) { +#ifdef ALLOW_EXPERIMENTAL_API return *RTE_FLOW_DYNF_METADATA (m); +#else +RTE_SET_USED (m); +return 0 ; +#endif }__rte_experimental static inline voidrte_flow_dynf_metadata_set (struct rte_mbuf *m,uint32_t v) { +#ifdef ALLOW_EXPERIMENTAL_API *RTE_FLOW_DYNF_METADATA (m) = v; +#else +RTE_SET_USED (m); +RTE_SET_USED (v); +#endif }/*
@@ -2800,7 +2813,11 @@ __rte_experimentalstatic inline int rte_flow_dynf_metadata_avail (void ) { +#ifdef ALLOW_EXPERIMENTAL_API return !!rte_flow_dynf_metadata_mask; +#else +return 0 ; +#endif }/**
lib/librte_port/rte_port_eventdev.h +5 -0
@@ -25,6 +25,8 @@ extern "C" {**/ #include <stdint.h> + +#include <rte_compat.h> #include <rte_eventdev.h> #include "rte_port.h"
@@ -39,6 +41,7 @@ struct rte_port_eventdev_reader_params { };/** Eventdev_reader port operations. */ +__rte_experimental_var extern struct rte_port_in_ops rte_port_eventdev_reader_ops;/** Eventdev_writer port parameters. */
@@ -63,6 +66,7 @@ struct rte_port_eventdev_writer_params { };/** Eventdev_writer port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_ops;/** Event_writer_nodrop port parameters. */
@@ -90,6 +94,7 @@ struct rte_port_eventdev_writer_nodrop_params { };/** Eventdev_writer_nodrop port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_nodrop_ops;#ifdef __cplusplus
lib/librte_rcu/rte_rcu_qsbr.h +1 -0
@@ -35,6 +35,7 @@ extern "C" {#include <rte_debug.h> #include <rte_atomic.h> +__rte_experimental_var extern int rte_rcu_log_type;#if RTE_LOG_DP_LEVEL >=RTE_LOG_DEBUG
Signature · 1 line
2.23.0
Quoted 10 lines · David Marchand
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing exported variables.Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")Signed-off-by David Marchand <[email protected]>
Quoted 320 lines · David Marchand
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing exported variables.Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")Signed-off-by David Marchand <[email protected]>---
Changelog since RFC:
- s/resp\./or/ in documentation,
- caught more variables by looking at the *COM* section,--- buildtools/check-experimental-syms.sh | 17 +++++++++++++++-- devtools/checkpatches.sh | 16 ++++++++++++---- doc/guides/contributing/abi_policy.rst | 7 ++++--- drivers/net/ice/rte_pmd_ice.h | 8 ++++++++ lib/librte_bbdev/rte_bbdev.h | 1 + lib/librte_cryptodev/rte_crypto_asym.h | 3 +++ lib/librte_eal/common/include/rte_compat.h | 5 +++++ lib/librte_ethdev/rte_flow.h | 17 +++++++++++++++++ lib/librte_port/rte_port_eventdev.h | 5 +++++ lib/librte_rcu/rte_rcu_qsbr.h | 1 + 10 files changed, 71 insertions(+), 9 deletions(-)buildtools/check-experimental-syms.sh +15
-2@@ -34,13 +34,26 @@ do Please add __rte_experimental to the definition of $SYM END_OF_MESSAGE ret=1 + elif grep -qe "\(\.data\|\*COM\*\).*[[:space:]]$SYM$" $DUMPFILE && + ! grep -q "\.data\.experimental.*[[:space:]]$SYM$" $DUMPFILE + then + cat >&2 <<- END_OF_MESSAGE + $SYM is not flagged as experimental + but is listed in version map + Please add __rte_experimental_var to the definition of $SYM + END_OF_MESSAGE + ret=1 fi done # Filter out symbols suffixed with a . for icc for SYM in `awk '{ - if ($2 != "l" && $4 == ".text.experimental" && !($NF ~ /\.$/)) { - print $NF + if ($2 == "l" || $NF ~ /\.$/) { + next; + } + if ($4 == ".text.experimental" || + $4 == ".data.experimental") { + print $NF; } }' $DUMPFILE` dodevtools/checkpatches.sh +12
-4@@ -90,11 +90,19 @@ check_experimental_tags() { # <patch> "headers ("current_file")"; ret = 1; } - if ($1 != "+__rte_experimental" || $2 != "") { + + if (NF == 1 && ($1 == "+__rte_experimental" || + $1 == "+__rte_experimental_var")) { + next; + } + if ($0 ~ "__rte_experimental_var") { + print "__rte_experimental_var must appear alone on the line" \ + " immediately preceding the type of a variable."; + } else { print "__rte_experimental must appear alone on the line" \ - " immediately preceding the return type of a function." - ret = 1; + " immediately preceding the return type of a function."; } + ret = 1; } END { exit ret;@@ -178,7 +186,7 @@ check () { # <patch> <commit> <title> ret=1 fi - ! $verbose || printf '\nChecking __rte_experimental tags:\n' + ! $verbose || printf '\nChecking __rte_experimental* tags:\n' report=$(check_experimental_tags "$tmpinput") if [ $? -ne 0 ] ; then $headline_printed || print_headline "$3"doc/guides/contributing/abi_policy.rst +4
-3@@ -300,9 +300,10 @@ Note that marking an API as experimental is a multi step process. To mark an API as experimental, the symbols which are desired to be exported must be placed in an EXPERIMENTAL version block in the corresponding libraries' version map script. -Secondly, the corresponding prototypes of those exported functions (in the -development header files), must be marked with the ``__rte_experimental`` tag -(see ``rte_compat.h``). +Secondly, the corresponding prototypes of those exported functions (or +variables) must be marked with the ``__rte_experimental`` (or +``__rte_experimental_var``) tag in the development header files (see +``rte_compat.h``). The DPDK build makefiles perform a check to ensure that the map file and the C code reflect the same list of symbols. This check can be circumvented by defining ``ALLOW_EXPERIMENTAL_API``drivers/net/ice/rte_pmd_ice.h +8
-0@@ -15,6 +15,8 @@*/ #include <stdio.h> + +#include <rte_compat.h> #include <rte_mbuf.h> #include <rte_mbuf_dyn.h> @@ -81,13 +83,19 @@ union rte_net_ice_proto_xtr_metadata { };/* Offset of mbuf dynamic field for protocol extraction data */ +__rte_experimental_var extern int rte_net_ice_dynfield_proto_xtr_metadata_offs;/* Mask of mbuf dynamic flags for protocol extraction type */ +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_vlan_mask; +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_ipv4_mask; +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_ipv6_mask; +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_ipv6_flow_mask; +__rte_experimental_var extern uint64_t rte_net_ice_dynflag_proto_xtr_tcp_mask;/** lib/librte_bbdev/rte_bbdev.h +1
-0@@ -466,6 +466,7 @@ struct __rte_cache_aligned rte_bbdev { };/** @internal array of all devices */ +__rte_experimental_var extern struct rte_bbdev rte_bbdev_devices[];/** lib/librte_cryptodev/rte_crypto_asym.h +3
-0@@ -24,6 +24,7 @@ extern "C" {#include <rte_memory.h> #include <rte_mempool.h> #include <rte_common.h> +#include <rte_compat.h> #include "rte_crypto_sym.h" @@ -37,10 +38,12 @@ typedef struct rte_crypto_param_t { } rte_crypto_param;/** asym xform type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_xform_strings[];/** asym operations type name strings */ +__rte_experimental_var extern const char * rte_crypto_asym_op_strings[];lib/librte_eal/common/include/rte_compat.h +5
-0@@ -11,11 +11,16 @@#define __rte_experimental \ __attribute__((deprecated("Symbol is not yet part of stable ABI"), \ section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((deprecated("Symbol is not yet part of stable ABI"), \ +section(".data.experimental")))#else #define __rte_experimental \ __attribute__((section(".text.experimental"))) +#define __rte_experimental_var \ +__attribute__((section(".data.experimental")))#endif lib/librte_ethdev/rte_flow.h +17
-0@@ -19,6 +19,7 @@#include <rte_arp.h> #include <rte_common.h> +#include <rte_compat.h> #include <rte_ether.h> #include <rte_icmp.h> #include <rte_ip.h> @@ -2531,9 +2532,11 @@ struct rte_flow_action_set_meta { };/* Mbuf dynamic field offset for metadata. */ +__rte_experimental_var extern int rte_flow_dynf_metadata_offs;/* Mbuf dynamic field flag mask for metadata. */ +__rte_experimental_var extern uint64_t rte_flow_dynf_metadata_mask;/* Mbuf dynamic field pointer for metadata. */ @@ -2548,14 +2551,24 @@ __rte_experimentalstatic inline uint32_t rte_flow_dynf_metadata_get (struct rte_mbuf *m) { +#ifdef ALLOW_EXPERIMENTAL_API return *RTE_FLOW_DYNF_METADATA (m); +#else +RTE_SET_USED (m); +return 0 ; +#endif }__rte_experimental static inline voidrte_flow_dynf_metadata_set (struct rte_mbuf *m,uint32_t v) { +#ifdef ALLOW_EXPERIMENTAL_API *RTE_FLOW_DYNF_METADATA (m) = v; +#else +RTE_SET_USED (m); +RTE_SET_USED (v); +#endif }/* @@ -2800,7 +2813,11 @@ __rte_experimentalstatic inline int rte_flow_dynf_metadata_avail (void ) { +#ifdef ALLOW_EXPERIMENTAL_API return !!rte_flow_dynf_metadata_mask; +#else +return 0 ; +#endif }/** lib/librte_port/rte_port_eventdev.h +5
-0@@ -25,6 +25,8 @@ extern "C" {**/ #include <stdint.h> + +#include <rte_compat.h> #include <rte_eventdev.h> #include "rte_port.h" @@ -39,6 +41,7 @@ struct rte_port_eventdev_reader_params { };/** Eventdev_reader port operations. */ +__rte_experimental_var extern struct rte_port_in_ops rte_port_eventdev_reader_ops;/** Eventdev_writer port parameters. */ @@ -63,6 +66,7 @@ struct rte_port_eventdev_writer_params { };/** Eventdev_writer port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_ops;/** Event_writer_nodrop port parameters. */ @@ -90,6 +94,7 @@ struct rte_port_eventdev_writer_nodrop_params { };/** Eventdev_writer_nodrop port operations. */ +__rte_experimental_var extern struct rte_port_out_ops rte_port_eventdev_writer_nodrop_ops;#ifdef __cpluspluslib/librte_rcu/rte_rcu_qsbr.h +1
-0@@ -35,6 +35,7 @@ extern "C" {#include <rte_debug.h> #include <rte_atomic.h> +__rte_experimental_var extern int rte_rcu_log_type;#if RTE_LOG_DP_LEVEL >=RTE_LOG_DEBUG Signature · 1 line
2.23.0
02/12/2019 16:20, David Marchand:
buildtools/check-experimental-syms.sh do · line 38
Quoted 13 lines
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing exported variables.Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")Signed-off-by David Marchand <[email protected]>---
buildtools/check-experimental-syms.sh +2
-0+ elif grep -qe "\(\.data\|\*COM\*\).*[[:space:]]$SYM$" $DUMPFILE && + ! grep -q "\.data\.experimental.*[[:space:]]$SYM$" $DUMPFILE
I like such regex ;)
I don't know COM section but I am not an ELF expert.
Maybe you can just add a comment in the commit log about searching the symbol in .data and COM sections, even if we don't know exactly why.
One more comment for the record,
I would like we avoid having some variables in the ABI.
Feel free to push this patch.
Quoted 11 lines · Thomas Monjalon
02/12/2019 16:20, David Marchand:
Quoted 9 lines
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing exported variables.Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")
Quoted 6 lines
buildtools/check-experimental-syms.sh do · line 38
Quoted 4 lines
Signed-off-by David Marchand <[email protected]>---
buildtools/check-experimental-syms.sh +2
-0+ elif grep -qe "\(\.data\|\*COM\*\).*[[:space:]]$SYM$" $DUMPFILE && + ! grep -q "\.data\.experimental.*[[:space:]]$SYM$" $DUMPFILEI like such regex ;)
Err.. thanks?
Quoted 1 line
I don't know COM section but I am not an ELF expert.
I am no ELF expert either.
IIUC, this section is a special one used when generating object files for common symbols but the compiler is not sure where the actual symbol should go.
It is then resolved as .data or .bss when linking.
Quoted 2 lines
Maybe you can just add a comment in the commit log about searching the symbol in .data and COM sections, even if we don't know exactly why.
Actually, this is a good thing you asked about it. I did a new check before/after the series.
Example for rte_net_ice_dynflag_proto_xtr_vlan_mask.
Before:/home/dmarchan/builds/build-gcc-shared/drivers/a715181@@tmp_rte_pmd_ice@sta/net_ice_ice_rxtx.c.o
0000000000000008 O *COM* 0000000000000008rte_net_ice_dynflag_proto_xtr_vlan_mask /home/dmarchan/builds/build-gcc-shared/drivers/a715181@@tmp_rte_pmd_ice@sta/net_ice_ice_ethdev.c.o
0000000000000000 *UND* 0000000000000000rte_net_ice_dynflag_proto_xtr_vlan_mask /home/dmarchan/builds/build-gcc-shared/drivers/libtmp_rte_pmd_ice.a
0000000000000000 *UND* 0000000000000000rte_net_ice_dynflag_proto_xtr_vlan_mask
0000000000000008 O *COM* 0000000000000008rte_net_ice_dynflag_proto_xtr_vlan_mask /home/dmarchan/builds/build-gcc-shared/drivers/librte_pmd_ice.a
0000000000000000 *UND* 0000000000000000rte_net_ice_dynflag_proto_xtr_vlan_mask
0000000000000008 O *COM* 0000000000000008rte_net_ice_dynflag_proto_xtr_vlan_mask /home/dmarchan/builds/build-gcc-shared/drivers/librte_pmd_ice.so.20.0.1
0000000000063890 g O .bss 0000000000000008rte_net_ice_dynflag_proto_xtr_vlan_mask
After:/home/dmarchan/builds/build-gcc-shared/drivers/a715181@@tmp_rte_pmd_ice@sta/net_ice_ice_rxtx.c.o
0000000000000020 g O .data.experimental 0000000000000008rte_net_ice_dynflag_proto_xtr_vlan_mask /home/dmarchan/builds/build-gcc-shared/drivers/a715181@@tmp_rte_pmd_ice@sta/net_ice_ice_ethdev.c.o
0000000000000000 *UND* 0000000000000000rte_net_ice_dynflag_proto_xtr_vlan_mask /home/dmarchan/builds/build-gcc-shared/drivers/libtmp_rte_pmd_ice.a
0000000000000000 *UND* 0000000000000000rte_net_ice_dynflag_proto_xtr_vlan_mask
0000000000000020 g O .data.experimental 0000000000000008rte_net_ice_dynflag_proto_xtr_vlan_mask /home/dmarchan/builds/build-gcc-shared/drivers/librte_pmd_ice.a
0000000000000000 *UND* 0000000000000000rte_net_ice_dynflag_proto_xtr_vlan_mask
0000000000000020 g O .data.experimental 0000000000000008rte_net_ice_dynflag_proto_xtr_vlan_mask /home/dmarchan/builds/build-gcc-shared/drivers/librte_pmd_ice.so.20.0.100000000000604f0 g O .data 0000000000000008rte_net_ice_dynflag_proto_xtr_vlan_mask
The thing that scares me is that the final symbol gets moved from .bss to .data in the .so.
Neil?
--
David Marchand
Quoted 14 lines · On Mon, 25 Nov 2019 17:13:14 +0100 David Marchand <[email protected]>…
So far, we did not pay attention to direct access to variables but they are part of the API/ABI too and should be clearly identified.
Introduce a
__rte_experimental_vartag and mark existing variables.Fixes a4bcd61de82d ("buildtools: add script to check experimental API exports")Signed-off-by David Marchand <[email protected]>---
Quick patch to try to catch experimental variables.
Not sure if we could use a single section, so please advise if there is better to do about this.
Quoted 10 lines
--- buildtools/check-experimental-syms.sh | 17 +++++++++++++++-- devtools/checkpatches.sh | 14 +++++++++----- doc/guides/contributing/abi_policy.rst | 7 ++++--- drivers/net/ice/rte_pmd_ice.h | 3 +++ lib/librte_cryptodev/rte_crypto_asym.h | 3 +++ lib/librte_eal/common/include/rte_compat.h | 5 +++++ lib/librte_ethdev/rte_flow.h | 17 +++++++++++++++++ lib/librte_port/rte_port_eventdev.h | 5 +++++ 8 files changed, 61 insertions(+), 10 deletions(-)
This is a good idea, but the patch has gone stale in 4 years. Symbols have changed, directories have changed.
If someone wants to continue this, please rebase and recheck.
Marking the original patch with Changes Requested.