* [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging
@ 2017-12-01 18:56 Neil Horman
2017-12-01 18:56 ` [PATCH 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
` (7 more replies)
0 siblings, 8 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-01 18:56 UTC (permalink / raw)
To: dev
Hey all-
A few days ago, I was lamenting the fact that, when reviewing patches I
would frequently complain about ABI changes that were actually considered safe
because they were part of the EXPERIMENTAL api set. John M. asked me then what
I might do to improve the situation, and the following patch set is a proposal
that I've come up with.
In thinking about the problem I identified two issues that I think we
can improve on in this area:
1) Make experimental api calls more visible in the source code. That is to say,
when reviewing patches, it would be nice to have some sort of visual reference
that indicates that the changes being made are part of an experimental API and
therefore ABI concerns need not be addressed
2) Make experimenal api usage more visible to consumers of the DPDK, so that
they can make a more informed decision about the API's they consume in their
application. We make an effort to document all the experimental API's, but
there is no guarantee that a user will check the documentation before making use
of a new library.
This patch set attempts to achieve both of the above goals. To do this I've
added an __experimental macro tag, suitable for inserting into api forward
declarations and definitions.
The presence of the tag in the header and c files where the api code resides
increases the likelyhood that any patch submitted against them will include the
tag in the context, making it clear to reviewers that ABI stability isn't a
concern here.
Also, This tag marks each function it is used on with an attibute causing any
use of the fuction to emit a warning during the build
with a message indicating that the API call in question is not yet part of the
stable interface. Developers can then make an informed decision to suppress
that warning or not.
Because there is internal use of several experimental API's, this set also
includes a new override macro ALLOW_EXPERIMENTAL_FUNCTIONS to automatically
suprress these warnings. I think its fair to assume that, for internal use, we
almost always want to suppress these warnings, as by definition any change to
the apis (even their removal) must be done in parallel with an appropriate
change in the calling locations, lest the dpdk build itself break.
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* [PATCH 1/4] buildtools: Add tool to check EXPERIMENTAL api exports
2017-12-01 18:56 [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
@ 2017-12-01 18:56 ` Neil Horman
2017-12-01 18:56 ` [PATCH 2/4] compat: Add __experimental macro Neil Horman
` (6 subsequent siblings)
7 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-01 18:56 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John
This tools reads the given version map for a directory, and checks to ensure
that, for each symbol listed in the export list, the corresponding definition is
tagged as __experimental, erroring out if its not. In this way, we can ensure
that the EXPERIMENTAL api is kept in sync with the tags
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
---
buildtools/experimentalsyms.sh | 34 ++++++++++++++++++++++++++++++++++
1 file changed, 34 insertions(+)
create mode 100755 buildtools/experimentalsyms.sh
diff --git a/buildtools/experimentalsyms.sh b/buildtools/experimentalsyms.sh
new file mode 100755
index 000000000..dc01f71ba
--- /dev/null
+++ b/buildtools/experimentalsyms.sh
@@ -0,0 +1,34 @@
+#!/bin/sh
+
+MAPFILE=$1
+OBJFILE=$2
+
+if [ -d $MAPFILE ]
+then
+ exit 0
+fi
+
+if [ -d $OBJFILE ]
+then
+ exit 0
+fi
+
+for i in `awk 'BEGIN {found=0}
+ /.*EXPERIMENTAL.*/ {found=1}
+ /.*}.*;/ {found=0}
+ /.*;/ {if (found == 1) print $1}' $MAPFILE`
+do
+ SYM=`echo $i | sed -e"s/;//"`
+ objdump -t $OBJFILE | grep -q "\.text.*$SYM"
+ IN_TEXT=$?
+ objdump -t $OBJFILE | grep -q "\.text\.experimental.*$SYM"
+ IN_EXP=$?
+ if [ $IN_TEXT -eq 0 -a $IN_EXP -ne 0 ]
+ then
+ echo "$SYM is not flagged as experimental, but is listed in version map"
+ echo "Please add __experimental to the definition of $SYM"
+ exit 1
+ fi
+done
+exit 0
+
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCH 2/4] compat: Add __experimental macro
2017-12-01 18:56 [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-01 18:56 ` [PATCH 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
@ 2017-12-01 18:56 ` Neil Horman
2017-12-01 18:56 ` [PATCH 3/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
` (5 subsequent siblings)
7 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-01 18:56 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John
The __experimental macro tags a given exported function as being part of
the EXPERIMENTAL api. Use of this tag will cause any caller of the
function (that isn't removed by dead code elimination) to emit a warning
that the user is making use of an API whos stabilty isn't guaranteed.
It also places the function in the .text.experimental section, which is
used to validate the tag against the corresponding library version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
---
lib/librte_compat/rte_compat.h | 2 ++
1 file changed, 2 insertions(+)
diff --git a/lib/librte_compat/rte_compat.h b/lib/librte_compat/rte_compat.h
index 41e8032ba..c7c967d86 100644
--- a/lib/librte_compat/rte_compat.h
+++ b/lib/librte_compat/rte_compat.h
@@ -101,5 +101,7 @@
*/
#endif
+#define __experimental \
+__attribute__(( deprecated("Symbol is not yet part of stable abi"), section(".text.experimental") ))
#endif /* _RTE_COMPAT_H_ */
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCH 3/4] dpdk: add __experimental tag to appropriate api calls
2017-12-01 18:56 [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-01 18:56 ` [PATCH 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-01 18:56 ` [PATCH 2/4] compat: Add __experimental macro Neil Horman
@ 2017-12-01 18:56 ` Neil Horman
2017-12-01 18:56 ` [PATCH 4/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
` (4 subsequent siblings)
7 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-01 18:56 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John
Append the __experimental tag to api calls appearing in the EXPERIMENTAL
section of their libraries version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
---
lib/librte_eal/common/eal_common_dev.c | 5 ++-
lib/librte_eal/common/eal_common_devargs.c | 7 ++--
lib/librte_eal/common/include/rte_dev.h | 5 ++-
lib/librte_eal/common/include/rte_devargs.h | 7 ++--
lib/librte_eal/common/include/rte_service.h | 40 +++++++++---------
.../common/include/rte_service_component.h | 10 ++---
lib/librte_eal/common/rte_service.c | 49 +++++++++++-----------
lib/librte_eal/linuxapp/eal/eal.c | 1 +
lib/librte_ether/rte_mtr.c | 25 +++++------
lib/librte_ether/rte_mtr.h | 26 ++++++------
lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
lib/librte_security/rte_security.c | 16 +++----
lib/librte_security/rte_security.h | 23 +++++-----
14 files changed, 124 insertions(+), 114 deletions(-)
diff --git a/lib/librte_eal/common/eal_common_dev.c b/lib/librte_eal/common/eal_common_dev.c
index dda8f5835..8a46ccab6 100644
--- a/lib/librte_eal/common/eal_common_dev.c
+++ b/lib/librte_eal/common/eal_common_dev.c
@@ -37,6 +37,7 @@
#include <inttypes.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
#include <rte_dev.h>
#include <rte_devargs.h>
@@ -133,7 +134,7 @@ full_dev_name(const char *bus, const char *dev, const char *args)
return name;
}
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs)
{
struct rte_bus *bus;
@@ -203,7 +204,7 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
return ret;
}
-int rte_eal_hotplug_remove(const char *busname, const char *devname)
+int __experimental rte_eal_hotplug_remove(const char *busname, const char *devname)
{
struct rte_bus *bus;
struct rte_device *dev;
diff --git a/lib/librte_eal/common/eal_common_devargs.c b/lib/librte_eal/common/eal_common_devargs.c
index 6ac88d6ab..8e46d54bd 100644
--- a/lib/librte_eal/common/eal_common_devargs.c
+++ b/lib/librte_eal/common/eal_common_devargs.c
@@ -40,6 +40,7 @@
#include <stdio.h>
#include <string.h>
+#include <rte_compat.h>
#include <rte_dev.h>
#include <rte_devargs.h>
#include <rte_tailq.h>
@@ -85,7 +86,7 @@ bus_name_cmp(const struct rte_bus *bus, const void *name)
return strncmp(bus->name, name, strlen(bus->name));
}
-int
+int __experimental
rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
{
struct rte_bus *bus = NULL;
@@ -139,7 +140,7 @@ rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
return 0;
}
-int
+int __experimental
rte_eal_devargs_insert(struct rte_devargs *da)
{
int ret;
@@ -188,7 +189,7 @@ rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str)
return -1;
}
-int
+int __experimental
rte_eal_devargs_remove(const char *busname, const char *devname)
{
struct rte_devargs *d;
diff --git a/lib/librte_eal/common/include/rte_dev.h b/lib/librte_eal/common/include/rte_dev.h
index 9342e0cbd..e3e52dcb8 100644
--- a/lib/librte_eal/common/include/rte_dev.h
+++ b/lib/librte_eal/common/include/rte_dev.h
@@ -49,6 +49,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_log.h>
__attribute__((format(printf, 2, 0)))
@@ -209,7 +210,7 @@ int rte_eal_dev_detach(struct rte_device *dev);
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs);
/**
@@ -225,7 +226,7 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_remove(const char *busname, const char *devname);
+int __experimental rte_eal_hotplug_remove(const char *busname, const char *devname);
/**
* Device comparison function.
diff --git a/lib/librte_eal/common/include/rte_devargs.h b/lib/librte_eal/common/include/rte_devargs.h
index 58d585df6..7148949c9 100644
--- a/lib/librte_eal/common/include/rte_devargs.h
+++ b/lib/librte_eal/common/include/rte_devargs.h
@@ -50,6 +50,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
/**
@@ -136,7 +137,7 @@ int rte_eal_parse_devargs_str(const char *devargs_str,
* - 0 on success.
* - Negative errno on error.
*/
-int
+int __experimental
rte_eal_devargs_parse(const char *dev,
struct rte_devargs *da);
@@ -150,7 +151,7 @@ rte_eal_devargs_parse(const char *dev,
* - 0 on success
* - Negative on error.
*/
-int
+int __experimental
rte_eal_devargs_insert(struct rte_devargs *da);
/**
@@ -193,7 +194,7 @@ int rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str);
* <0 on error.
* >0 if the devargs was not within the user device list.
*/
-int rte_eal_devargs_remove(const char *busname, const char *devname);
+int __experimental rte_eal_devargs_remove(const char *busname, const char *devname);
/**
* Count the number of user devices of a specified type
diff --git a/lib/librte_eal/common/include/rte_service.h b/lib/librte_eal/common/include/rte_service.h
index 927244065..595f156d2 100644
--- a/lib/librte_eal/common/include/rte_service.h
+++ b/lib/librte_eal/common/include/rte_service.h
@@ -84,7 +84,7 @@ extern "C" {
*
* @return The number of services registered.
*/
-uint32_t rte_service_get_count(void);
+uint32_t __experimental rte_service_get_count(void);
/**
* @warning
@@ -111,7 +111,7 @@ uint32_t rte_service_get_count(void);
* @retval -EINVAL Null *service_id* pointer provided
* @retval -ENODEV No such service registered
*/
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
+int32_t __experimental rte_service_get_by_name(const char *name, uint32_t *service_id);
/**
* @warning
@@ -122,7 +122,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
* @return A pointer to the name of the service. The returned pointer remains
* in ownership of the service, and the application must not free it.
*/
-const char *rte_service_get_name(uint32_t id);
+const char __experimental *rte_service_get_name(uint32_t id);
/**
* @warning
@@ -135,7 +135,7 @@ const char *rte_service_get_name(uint32_t id);
* @retval 1 Capability supported by this service instance
* @retval 0 Capability not supported by this service instance
*/
-int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
+int32_t __experimental rte_service_probe_capability(uint32_t id, uint32_t capability);
/**
* @warning
@@ -159,7 +159,7 @@ int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
* @retval 0 lcore map updated successfully
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
+int32_t __experimental rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
uint32_t enable);
/**
@@ -175,7 +175,7 @@ int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
* @retval 0 lcore is not mapped to service
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
+int32_t __experimental rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
/**
* @warning
@@ -192,7 +192,7 @@ int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
* @retval 0 The service was successfully started
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __experimental rte_service_runstate_set(uint32_t id, uint32_t runstate);
/**
* @warning
@@ -210,7 +210,7 @@ int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
* @retval 0 Service is stopped
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_get(uint32_t id);
+int32_t __experimental rte_service_runstate_get(uint32_t id);
/**
* @warning
@@ -226,7 +226,7 @@ int32_t rte_service_runstate_get(uint32_t id);
* @retval 0 Success
* @retval -EINVAL Invalid service ID
*/
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
+int32_t __experimental rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
/**
* @warning
@@ -264,7 +264,7 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
* @retval -ENOEXEC Service is not in a run-able state
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_multithread_unsafe);
/**
@@ -280,7 +280,7 @@ int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
* @retval -EINVAL Failed to start core. The *lcore_id* passed in is not
* currently assigned to be a service core.
*/
-int32_t rte_service_lcore_start(uint32_t lcore_id);
+int32_t __experimental rte_service_lcore_start(uint32_t lcore_id);
/**
* @warning
@@ -299,7 +299,7 @@ int32_t rte_service_lcore_start(uint32_t lcore_id);
* The application must stop the service first, and then stop the
* lcore.
*/
-int32_t rte_service_lcore_stop(uint32_t lcore_id);
+int32_t __experimental rte_service_lcore_stop(uint32_t lcore_id);
/**
* @warning
@@ -315,7 +315,7 @@ int32_t rte_service_lcore_stop(uint32_t lcore_id);
* @retval -EALREADY lcore is already added to the service core list
* @retval -EINVAL Invalid lcore provided
*/
-int32_t rte_service_lcore_add(uint32_t lcore);
+int32_t __experimental rte_service_lcore_add(uint32_t lcore);
/**
* @warning
@@ -329,7 +329,7 @@ int32_t rte_service_lcore_add(uint32_t lcore);
* @retval -EBUSY Lcore is not stopped, stop service core before removing.
* @retval -EINVAL failed to add lcore to service core mask.
*/
-int32_t rte_service_lcore_del(uint32_t lcore);
+int32_t __experimental rte_service_lcore_del(uint32_t lcore);
/**
* @warning
@@ -346,7 +346,7 @@ int32_t rte_service_lcore_del(uint32_t lcore);
*
* @return The number of service cores currently configured.
*/
-int32_t rte_service_lcore_count(void);
+int32_t __experimental rte_service_lcore_count(void);
/**
* @warning
@@ -358,7 +358,7 @@ int32_t rte_service_lcore_count(void);
*
* @retval 0 Success
*/
-int32_t rte_service_lcore_reset_all(void);
+int32_t __experimental rte_service_lcore_reset_all(void);
/**
* @warning
@@ -372,7 +372,7 @@ int32_t rte_service_lcore_reset_all(void);
* @retval 0 Success
* @retval -EINVAL Invalid service pointer passed
*/
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
+int32_t __experimental rte_service_set_stats_enable(uint32_t id, int32_t enable);
/**
* @warning
@@ -393,7 +393,7 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
* service core list. No items have been populated, call this function
* with a size of at least *rte_service_core_count* items.
*/
-int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
+int32_t __experimental rte_service_lcore_list(uint32_t array[], uint32_t n);
/**
* @warning
@@ -406,7 +406,7 @@ int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
* @retval -EINVAL Invalid lcore provided
* @retval -ENOTSUP The provided lcore is not a service core.
*/
-int32_t rte_service_lcore_count_services(uint32_t lcore);
+int32_t __experimental rte_service_lcore_count_services(uint32_t lcore);
/**
* @warning
@@ -418,7 +418,7 @@ int32_t rte_service_lcore_count_services(uint32_t lcore);
* @retval 0 Statistics have been successfully dumped
* @retval -EINVAL Invalid service id provided
*/
-int32_t rte_service_dump(FILE *f, uint32_t id);
+int32_t __experimental rte_service_dump(FILE *f, uint32_t id);
#ifdef __cplusplus
}
diff --git a/lib/librte_eal/common/include/rte_service_component.h b/lib/librte_eal/common/include/rte_service_component.h
index ac965cb48..e414df56a 100644
--- a/lib/librte_eal/common/include/rte_service_component.h
+++ b/lib/librte_eal/common/include/rte_service_component.h
@@ -37,7 +37,7 @@
* Include this file if you are writing a component that requires CPU cycles to
* operate, and you wish to run the component using service cores
*/
-
+#include <rte_compat.h>
#include <rte_service.h>
/**
@@ -101,7 +101,7 @@ struct rte_service_spec {
* -EINVAL Attempted to register an invalid service (eg, no callback
* set)
*/
-int32_t rte_service_component_register(const struct rte_service_spec *spec,
+int32_t __experimental rte_service_component_register(const struct rte_service_spec *spec,
uint32_t *service_id);
/**
@@ -116,7 +116,7 @@ int32_t rte_service_component_register(const struct rte_service_spec *spec,
* @retval -EBUSY The service is currently running, stop the service before
* calling unregister. No action has been taken.
*/
-int32_t rte_service_component_unregister(uint32_t id);
+int32_t __experimental rte_service_component_unregister(uint32_t id);
/**
* @warning
@@ -134,7 +134,7 @@ int32_t rte_service_component_unregister(uint32_t id);
* @retval -ENODEV Error in enabling service lcore on a service
* @retval -ENOEXEC Error when starting services
*/
-int32_t rte_service_start_with_defaults(void);
+int32_t __experimental rte_service_start_with_defaults(void);
/**
* @warning
@@ -151,7 +151,7 @@ int32_t rte_service_start_with_defaults(void);
*
* @retval 0 Success
*/
-int32_t rte_service_component_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __experimental rte_service_component_runstate_set(uint32_t id, uint32_t runstate);
/**
* @warning
diff --git a/lib/librte_eal/common/rte_service.c b/lib/librte_eal/common/rte_service.c
index ae97e6b7f..c8991a8d2 100644
--- a/lib/librte_eal/common/rte_service.c
+++ b/lib/librte_eal/common/rte_service.c
@@ -38,6 +38,7 @@
#include <string.h>
#include <dirent.h>
+#include <rte_compat.h>
#include <rte_service.h>
#include "include/rte_service_component.h"
@@ -168,7 +169,7 @@ service_mt_safe(struct rte_service_spec_impl *s)
return !!(s->spec.capabilities & RTE_SERVICE_CAP_MT_SAFE);
}
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
+int32_t __experimental rte_service_set_stats_enable(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -181,7 +182,7 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
return 0;
}
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
+int32_t __experimental rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -194,13 +195,13 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
return 0;
}
-uint32_t
+uint32_t __experimental
rte_service_get_count(void)
{
return rte_service_count;
}
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
+int32_t __experimental rte_service_get_by_name(const char *name, uint32_t *service_id)
{
if (!service_id)
return -EINVAL;
@@ -217,7 +218,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
return -ENODEV;
}
-const char *
+const char * __experimental
rte_service_get_name(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -225,7 +226,7 @@ rte_service_get_name(uint32_t id)
return s->spec.name;
}
-int32_t
+int32_t __experimental
rte_service_probe_capability(uint32_t id, uint32_t capability)
{
struct rte_service_spec_impl *s;
@@ -233,7 +234,7 @@ rte_service_probe_capability(uint32_t id, uint32_t capability)
return !!(s->spec.capabilities & capability);
}
-int32_t
+int32_t __experimental
rte_service_component_register(const struct rte_service_spec *spec,
uint32_t *id_ptr)
{
@@ -266,7 +267,7 @@ rte_service_component_register(const struct rte_service_spec *spec,
return 0;
}
-int32_t
+int32_t __experimental
rte_service_component_unregister(uint32_t id)
{
uint32_t i;
@@ -287,7 +288,7 @@ rte_service_component_unregister(uint32_t id)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -302,7 +303,7 @@ rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -317,7 +318,7 @@ rte_service_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_runstate_get(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -378,7 +379,7 @@ service_run(uint32_t i, struct core_state *cs, uint64_t service_mask)
return 0;
}
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_mt_unsafe)
{
/* run service on calling core, using all-ones as the service mask */
@@ -434,7 +435,7 @@ rte_service_runner_func(void *arg)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_lcore_count(void)
{
int32_t count = 0;
@@ -444,7 +445,7 @@ rte_service_lcore_count(void)
return count;
}
-int32_t
+int32_t __experimental
rte_service_lcore_list(uint32_t array[], uint32_t n)
{
uint32_t count = rte_service_lcore_count();
@@ -467,7 +468,7 @@ rte_service_lcore_list(uint32_t array[], uint32_t n)
return count;
}
-int32_t
+int32_t __experimental
rte_service_lcore_count_services(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -480,7 +481,7 @@ rte_service_lcore_count_services(uint32_t lcore)
return __builtin_popcountll(cs->service_mask);
}
-int32_t
+int32_t __experimental
rte_service_start_with_defaults(void)
{
/* create a default mapping from cores to services, then start the
@@ -562,7 +563,7 @@ service_update(struct rte_service_spec *service, uint32_t lcore,
return 0;
}
-int32_t
+int32_t __experimental
rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
{
struct rte_service_spec_impl *s;
@@ -571,7 +572,7 @@ rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
return service_update(&s->spec, lcore, &on, 0);
}
-int32_t
+int32_t __experimental
rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
{
struct rte_service_spec_impl *s;
@@ -583,7 +584,7 @@ rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
return ret;
}
-int32_t rte_service_lcore_reset_all(void)
+int32_t __experimental rte_service_lcore_reset_all(void)
{
/* loop over cores, reset all to mask 0 */
uint32_t i;
@@ -614,7 +615,7 @@ set_lcore_state(uint32_t lcore, int32_t state)
lcore_states[lcore].is_service_core = (state == ROLE_SERVICE);
}
-int32_t
+int32_t __experimental
rte_service_lcore_add(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -633,7 +634,7 @@ rte_service_lcore_add(uint32_t lcore)
return rte_eal_wait_lcore(lcore);
}
-int32_t
+int32_t __experimental
rte_service_lcore_del(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -652,7 +653,7 @@ rte_service_lcore_del(uint32_t lcore)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_lcore_start(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -675,7 +676,7 @@ rte_service_lcore_start(uint32_t lcore)
return ret;
}
-int32_t
+int32_t __experimental
rte_service_lcore_stop(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -745,7 +746,7 @@ service_dump_calls_per_lcore(FILE *f, uint32_t lcore, uint32_t reset)
fprintf(f, "\n");
}
-int32_t rte_service_dump(FILE *f, uint32_t id)
+int32_t __experimental rte_service_dump(FILE *f, uint32_t id)
{
uint32_t i;
int print_one = (id != UINT32_MAX);
diff --git a/lib/librte_eal/linuxapp/eal/eal.c b/lib/librte_eal/linuxapp/eal/eal.c
index 229eec9f1..73a0da22c 100644
--- a/lib/librte_eal/linuxapp/eal/eal.c
+++ b/lib/librte_eal/linuxapp/eal/eal.c
@@ -53,6 +53,7 @@
#include <sys/io.h>
#endif
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_debug.h>
#include <rte_memory.h>
diff --git a/lib/librte_ether/rte_mtr.c b/lib/librte_ether/rte_mtr.c
index 4f56f8714..2cbe0bb5a 100644
--- a/lib/librte_ether/rte_mtr.c
+++ b/lib/librte_ether/rte_mtr.c
@@ -34,6 +34,7 @@
#include <stdint.h>
#include <rte_errno.h>
+#include "rte_compat.h"
#include "rte_ethdev.h"
#include "rte_mtr_driver.h"
#include "rte_mtr.h"
@@ -86,7 +87,7 @@ rte_mtr_ops_get(uint16_t port_id, struct rte_mtr_error *error)
})
/* MTR capabilities get */
-int
+int __experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error)
@@ -97,7 +98,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
}
/* MTR meter profile add */
-int
+int __experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -109,7 +110,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
}
/** MTR meter profile delete */
-int
+int __experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error)
@@ -120,7 +121,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
}
/** MTR object create */
-int
+int __experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -133,7 +134,7 @@ rte_mtr_create(uint16_t port_id,
}
/** MTR object destroy */
-int
+int __experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -144,7 +145,7 @@ rte_mtr_destroy(uint16_t port_id,
}
/** MTR object meter enable */
-int
+int __experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -155,7 +156,7 @@ rte_mtr_meter_enable(uint16_t port_id,
}
/** MTR object meter disable */
-int
+int __experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -166,7 +167,7 @@ rte_mtr_meter_disable(uint16_t port_id,
}
/** MTR object meter profile update */
-int
+int __experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -178,7 +179,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
}
/** MTR object meter DSCP table update */
-int
+int __experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -190,7 +191,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
}
/** MTR object policer action update */
-int
+int __experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -203,7 +204,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
}
/** MTR object enabled stats update */
-int
+int __experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -215,7 +216,7 @@ rte_mtr_stats_update(uint16_t port_id,
}
/** MTR object stats read */
-int
+int __experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_ether/rte_mtr.h b/lib/librte_ether/rte_mtr.h
index f6b6ef3b6..fd8361998 100644
--- a/lib/librte_ether/rte_mtr.h
+++ b/lib/librte_ether/rte_mtr.h
@@ -74,7 +74,7 @@
* @b EXPERIMENTAL: this API may change without prior notice
*/
#include <stdint.h>
-
+#include <rte_compat.h>
#include <rte_common.h>
#ifdef __cplusplus
@@ -447,7 +447,7 @@ struct rte_mtr_error {
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error);
@@ -470,7 +470,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -491,7 +491,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error);
@@ -519,7 +519,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
*
* @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
*/
-int
+int __experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -542,7 +542,7 @@ rte_mtr_create(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -569,7 +569,7 @@ rte_mtr_destroy(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -590,7 +590,7 @@ rte_mtr_meter_disable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -609,7 +609,7 @@ rte_mtr_meter_enable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -633,7 +633,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -659,7 +659,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -684,7 +684,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -715,7 +715,7 @@ rte_mtr_stats_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_flow_classify/rte_flow_classify.c b/lib/librte_flow_classify/rte_flow_classify.c
index e6f448643..6716672fc 100644
--- a/lib/librte_flow_classify/rte_flow_classify.c
+++ b/lib/librte_flow_classify/rte_flow_classify.c
@@ -31,6 +31,7 @@
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+#include <rte_compat.h>
#include <rte_flow_classify.h>
#include "rte_flow_classify_parse.h"
#include <rte_flow_driver.h>
@@ -245,7 +246,7 @@ rte_flow_classifier_check_params(struct rte_flow_classifier_params *params)
return 0;
}
-struct rte_flow_classifier *
+struct rte_flow_classifier * __experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params)
{
struct rte_flow_classifier *cls;
@@ -291,7 +292,7 @@ rte_flow_classify_table_free(struct rte_table *table)
table->ops.f_free(table->h_table);
}
-int
+int __experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls)
{
uint32_t i;
@@ -369,7 +370,7 @@ rte_table_check_params(struct rte_flow_classifier *cls,
return 0;
}
-int
+int __experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id)
@@ -483,7 +484,7 @@ allocate_acl_ipv4_5tuple_rule(void)
return rule;
}
-struct rte_flow_classify_rule *
+struct rte_flow_classify_rule * __experimental
rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
uint32_t table_id,
int *key_found,
@@ -582,7 +583,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
return rule;
}
-int
+int __experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule)
@@ -659,7 +660,7 @@ action_apply(struct rte_flow_classifier *cls,
return ret;
}
-int
+int __experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_flow_classify/rte_flow_classify.h b/lib/librte_flow_classify/rte_flow_classify.h
index 1211873a1..cd9516f9e 100644
--- a/lib/librte_flow_classify/rte_flow_classify.h
+++ b/lib/librte_flow_classify/rte_flow_classify.h
@@ -70,6 +70,7 @@
* with rte_flow_classifier_free()
*/
+#include <rte_compat.h>
#include <rte_ethdev.h>
#include <rte_ether.h>
#include <rte_flow.h>
@@ -176,7 +177,7 @@ struct rte_flow_classify_ipv4_5tuple_stats {
* @return
* Handle to flow classifier instance on success or NULL otherwise
*/
-struct rte_flow_classifier *
+struct rte_flow_classifier * __experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params);
/**
@@ -187,7 +188,7 @@ rte_flow_classifier_create(struct rte_flow_classifier_params *params);
* @return
* 0 on success, error code otherwise
*/
-int
+int __experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls);
/**
@@ -203,7 +204,7 @@ rte_flow_classifier_free(struct rte_flow_classifier *cls);
* @return
* 0 on success, error code otherwise
*/
-int
+int __experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id);
@@ -250,7 +251,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule);
@@ -274,7 +275,7 @@ rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_security/rte_security.c b/lib/librte_security/rte_security.c
index 1227fca8a..958b7273e 100644
--- a/lib/librte_security/rte_security.c
+++ b/lib/librte_security/rte_security.c
@@ -33,12 +33,12 @@
#include <rte_malloc.h>
#include <rte_dev.h>
-
+#include "rte_compat.h"
#include "rte_security.h"
#include "rte_security_driver.h"
struct rte_security_session *
-rte_security_session_create(struct rte_security_ctx *instance,
+__experimental rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp)
{
@@ -61,7 +61,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
return sess;
}
-int
+int __experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf)
@@ -70,7 +70,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
return instance->ops->session_update(instance->device, sess, conf);
}
-int
+int __experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats)
@@ -79,7 +79,7 @@ rte_security_session_stats_get(struct rte_security_ctx *instance,
return instance->ops->session_stats_get(instance->device, sess, stats);
}
-int
+int __experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess)
{
@@ -98,7 +98,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
return ret;
}
-int
+int __experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *m, void *params)
@@ -108,14 +108,14 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
sess, m, params);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capabilities_get(struct rte_security_ctx *instance)
{
RTE_FUNC_PTR_OR_ERR_RET(*instance->ops->capabilities_get, NULL);
return instance->ops->capabilities_get(instance->device);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx)
{
diff --git a/lib/librte_security/rte_security.h b/lib/librte_security/rte_security.h
index 653929b99..176378e78 100644
--- a/lib/librte_security/rte_security.h
+++ b/lib/librte_security/rte_security.h
@@ -52,6 +52,7 @@ extern "C" {
#include <netinet/ip.h>
#include <netinet/ip6.h>
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_crypto.h>
#include <rte_mbuf.h>
@@ -291,7 +292,7 @@ struct rte_security_session {
* - On success, pointer to session
* - On failure, NULL
*/
-struct rte_security_session *
+struct rte_security_session * __experimental
rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp);
@@ -306,7 +307,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
* - On success returns 0
* - On failure return errno
*/
-int
+int __experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf);
@@ -323,7 +324,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
* - -EINVAL if session is NULL.
* - -EBUSY if not all device private data has been freed.
*/
-int
+int __experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess);
@@ -340,7 +341,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
* - On success, zero.
* - On failure, a negative value.
*/
-int
+int __experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *mb, void *params);
@@ -351,7 +352,7 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
* @param sym_op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __experimental
__rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
struct rte_security_session *sess)
{
@@ -360,13 +361,13 @@ __rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
return 0;
}
-static inline void *
+static inline void * __experimental
get_sec_session_private_data(const struct rte_security_session *sess)
{
return sess->sess_private_data;
}
-static inline void
+static inline void __experimental
set_sec_session_private_data(struct rte_security_session *sess,
void *private_data)
{
@@ -382,7 +383,7 @@ set_sec_session_private_data(struct rte_security_session *sess,
* @param op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __experimental
rte_security_attach_session(struct rte_crypto_op *op,
struct rte_security_session *sess)
{
@@ -424,7 +425,7 @@ struct rte_security_stats {
* - On success return 0
* - On failure errno
*/
-int
+int __experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats);
@@ -507,7 +508,7 @@ struct rte_security_capability_idx {
* - Returns array of security capabilities.
* - Return NULL if no capabilities available.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capabilities_get(struct rte_security_ctx *instance);
/**
@@ -521,7 +522,7 @@ rte_security_capabilities_get(struct rte_security_ctx *instance);
* index criteria.
* - Return NULL if the capability not matched on security instance.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx);
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCH 4/4] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-01 18:56 [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (2 preceding siblings ...)
2017-12-01 18:56 ` [PATCH 3/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
@ 2017-12-01 18:56 ` Neil Horman
2017-12-08 17:14 ` [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (3 subsequent siblings)
7 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-01 18:56 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John
Add checks during build to ensure that all symbols in the EXPERIMENTAL
version map section have __experimental tags on their definitions, and
enable the warnings needed to announce their use. Also add a
ALLOW_EXPERIMENTAL_FUNCTIONS variable check to allow for in-tree dpdk
libraries to override those checks.
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
---
app/test-eventdev/Makefile | 2 ++
app/test-pmd/Makefile | 2 ++
drivers/event/sw/Makefile | 2 ++
drivers/net/failsafe/Makefile | 2 ++
drivers/net/ixgbe/Makefile | 2 ++
examples/eventdev_pipeline_sw_pmd/Makefile | 2 ++
examples/flow_classify/Makefile | 2 ++
examples/ipsec-secgw/Makefile | 2 ++
examples/service_cores/Makefile | 2 ++
lib/librte_eal/linuxapp/Makefile | 2 ++
lib/librte_eal/linuxapp/eal/Makefile | 4 ++++
lib/librte_eventdev/Makefile | 3 +++
lib/librte_security/Makefile | 3 +++
mk/internal/rte.compile-pre.mk | 14 ++++++++++++--
mk/toolchain/clang/rte.vars.mk | 2 +-
mk/toolchain/gcc/rte.vars.mk | 2 +-
mk/toolchain/icc/rte.vars.mk | 4 ++--
17 files changed, 46 insertions(+), 6 deletions(-)
diff --git a/app/test-eventdev/Makefile b/app/test-eventdev/Makefile
index dcb2ac476..e68870828 100644
--- a/app/test-eventdev/Makefile
+++ b/app/test-eventdev/Makefile
@@ -32,6 +32,8 @@ include $(RTE_SDK)/mk/rte.vars.mk
APP = dpdk-test-eventdev
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/app/test-pmd/Makefile b/app/test-pmd/Makefile
index d21308fcd..f0262a369 100644
--- a/app/test-pmd/Makefile
+++ b/app/test-pmd/Makefile
@@ -33,6 +33,8 @@ include $(RTE_SDK)/mk/rte.vars.mk
ifeq ($(CONFIG_RTE_TEST_PMD),y)
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
#
# library name
#
diff --git a/drivers/event/sw/Makefile b/drivers/event/sw/Makefile
index 2f2b67bac..0711ce46e 100644
--- a/drivers/event/sw/Makefile
+++ b/drivers/event/sw/Makefile
@@ -33,6 +33,8 @@ include $(RTE_SDK)/mk/rte.vars.mk
# library name
LIB = librte_pmd_sw_event.a
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# build flags
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/drivers/net/failsafe/Makefile b/drivers/net/failsafe/Makefile
index ea2a8fe46..795da9d56 100644
--- a/drivers/net/failsafe/Makefile
+++ b/drivers/net/failsafe/Makefile
@@ -36,6 +36,8 @@ LIB = librte_pmd_failsafe.a
EXPORT_MAP := rte_pmd_failsafe_version.map
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
LIBABIVER := 1
# Sources are stored in SRCS-y
diff --git a/drivers/net/ixgbe/Makefile b/drivers/net/ixgbe/Makefile
index 511a64eb0..b8431600a 100644
--- a/drivers/net/ixgbe/Makefile
+++ b/drivers/net/ixgbe/Makefile
@@ -36,6 +36,8 @@ include $(RTE_SDK)/mk/rte.vars.mk
#
LIB = librte_pmd_ixgbe.a
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/eventdev_pipeline_sw_pmd/Makefile b/examples/eventdev_pipeline_sw_pmd/Makefile
index de4e22c88..4272caf93 100644
--- a/examples/eventdev_pipeline_sw_pmd/Makefile
+++ b/examples/eventdev_pipeline_sw_pmd/Makefile
@@ -32,6 +32,8 @@ ifeq ($(RTE_SDK),)
$(error "Please define RTE_SDK environment variable")
endif
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# Default target, can be overridden by command line or environment
RTE_TARGET ?= x86_64-native-linuxapp-gcc
diff --git a/examples/flow_classify/Makefile b/examples/flow_classify/Makefile
index eecdde14c..b04747c40 100644
--- a/examples/flow_classify/Makefile
+++ b/examples/flow_classify/Makefile
@@ -33,6 +33,8 @@ ifeq ($(RTE_SDK),)
$(error "Please define RTE_SDK environment variable")
endif
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# Default target, can be overridden by command line or environment
RTE_TARGET ?= x86_64-native-linuxapp-gcc
diff --git a/examples/ipsec-secgw/Makefile b/examples/ipsec-secgw/Makefile
index 9fd33cb7f..90a4feca1 100644
--- a/examples/ipsec-secgw/Makefile
+++ b/examples/ipsec-secgw/Makefile
@@ -33,6 +33,8 @@ ifeq ($(RTE_SDK),)
$(error "Please define RTE_SDK environment variable")
endif
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# Default target, can be overridden by command line or environment
RTE_TARGET ?= x86_64-native-linuxapp-gcc
diff --git a/examples/service_cores/Makefile b/examples/service_cores/Makefile
index bd4a345dc..ba731e259 100644
--- a/examples/service_cores/Makefile
+++ b/examples/service_cores/Makefile
@@ -32,6 +32,8 @@ ifeq ($(RTE_SDK),)
$(error "Please define RTE_SDK environment variable")
endif
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# Default target, can be overridden by command line or environment
RTE_TARGET ?= x86_64-native-linuxapp-gcc
diff --git a/lib/librte_eal/linuxapp/Makefile b/lib/librte_eal/linuxapp/Makefile
index 2ebdf3139..11ee59e42 100644
--- a/lib/librte_eal/linuxapp/Makefile
+++ b/lib/librte_eal/linuxapp/Makefile
@@ -31,6 +31,8 @@
include $(RTE_SDK)/mk/rte.vars.mk
+ALLOW_EXPERIMENTAL_FUNCTIONS := 2
+
DIRS-$(CONFIG_RTE_EXEC_ENV_LINUXAPP) += eal
DIRS-$(CONFIG_RTE_EAL_IGB_UIO) += igb_uio
DIRS-$(CONFIG_RTE_KNI_KMOD) += kni
diff --git a/lib/librte_eal/linuxapp/eal/Makefile b/lib/librte_eal/linuxapp/eal/Makefile
index 5a7b8b2ac..84f8edf39 100644
--- a/lib/librte_eal/linuxapp/eal/Makefile
+++ b/lib/librte_eal/linuxapp/eal/Makefile
@@ -34,6 +34,10 @@ include $(RTE_SDK)/mk/rte.vars.mk
LIB = librte_eal.a
ARCH_DIR ?= $(RTE_ARCH)
+
+#Allow the use of experimental functions without warning
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
EXPORT_MAP := ../../rte_eal_version.map
VPATH += $(RTE_SDK)/lib/librte_eal/common/arch/$(ARCH_DIR)
diff --git a/lib/librte_eventdev/Makefile b/lib/librte_eventdev/Makefile
index 5ac22cde7..8ae9e16f3 100644
--- a/lib/librte_eventdev/Makefile
+++ b/lib/librte_eventdev/Makefile
@@ -36,6 +36,9 @@ LIB = librte_eventdev.a
# library version
LIBABIVER := 3
+# Allow the use of experimental functions
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# build flags
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/lib/librte_security/Makefile b/lib/librte_security/Makefile
index bb93ec33d..c2815fab8 100644
--- a/lib/librte_security/Makefile
+++ b/lib/librte_security/Makefile
@@ -36,6 +36,9 @@ LIB = librte_security.a
# library version
LIBABIVER := 1
+# Allow the use of experimental functions without warnings
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# build flags
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/mk/internal/rte.compile-pre.mk b/mk/internal/rte.compile-pre.mk
index da8dda498..f67048d75 100644
--- a/mk/internal/rte.compile-pre.mk
+++ b/mk/internal/rte.compile-pre.mk
@@ -72,18 +72,27 @@ CMDS-all := $(CMDS-y) $(CMDS-n) $(CMDS-)
-include $(DEPS-y) $(CMDS-y)
+ifdef ALLOW_EXPERIMENTAL_FUNCTIONS
+EXPERIMENTAL_CFLAGS := $(subst 1, -Wno-deprecated-declarations -Wno-deprecated -Wno-error=deprecated-declarations -Wno-error=deprecated, $(ALLOW_EXPERIMENTAL_FUNCTIONS))
+else
+EXPERIMENTAL_CFLAGS :=
+endif
+
# command to compile a .c file to generate an object
ifeq ($(USE_HOST),1)
C_TO_O = $(HOSTCC) -Wp,-MD,$(call obj2dep,$(@)).tmp $(HOST_CPPFLAGS) $(HOST_CFLAGS) \
- $(CFLAGS_$(@)) $(HOST_EXTRA_CPPFLAGS) $(HOST_EXTRA_CFLAGS) -o $@ -c $<
+ $(CFLAGS_$(@)) $(HOST_EXTRA_CPPFLAGS) $(HOST_EXTRA_CFLAGS) $(EXPERIMENTAL_CFLAGS) -o $@ -c $<
C_TO_O_STR = $(subst ','\'',$(C_TO_O)) #'# fix syntax highlight
C_TO_O_DISP = $(if $(V),"$(C_TO_O_STR)"," HOSTCC $(@)")
else
C_TO_O = $(CC) -Wp,-MD,$(call obj2dep,$(@)).tmp $(CPPFLAGS) $(CFLAGS) \
- $(CFLAGS_$(@)) $(EXTRA_CPPFLAGS) $(EXTRA_CFLAGS) -o $@ -c $<
+ $(CFLAGS_$(@)) $(EXTRA_CPPFLAGS) $(EXTRA_CFLAGS) $(EXPERIMENTAL_CFLAGS) -o $@ -c $<
C_TO_O_STR = $(subst ','\'',$(C_TO_O)) #'# fix syntax highlight
C_TO_O_DISP = $(if $(V),"$(C_TO_O_STR)"," CC $(@)")
endif
+EXPERIMENTAL_CHECK = $(RTE_SDK)/buildtools/experimentalsyms.sh
+CHECK_EXPERIMENTAL = $(EXPERIMENTAL_CHECK) $(SRCDIR)/$(EXPORT_MAP) $@
+
PMDINFO_GEN = $(RTE_SDK_BIN)/app/dpdk-pmdinfogen $@ $@.pmd.c
PMDINFO_CC = $(CC) $(CPPFLAGS) $(CFLAGS) -c -o $@.pmd.o $@.pmd.c
PMDINFO_LD = $(CROSS)ld $(LDFLAGS) -r -o $@.o $@.pmd.o $@
@@ -100,6 +109,7 @@ C_TO_O_DO = @set -e; \
echo $(C_TO_O_DISP); \
$(C_TO_O) && \
$(PMDINFO_TO_O) && \
+ $(CHECK_EXPERIMENTAL) && \
echo $(C_TO_O_CMD) > $(call obj2cmd,$(@)) && \
sed 's,'$@':,dep_'$@' =,' $(call obj2dep,$(@)).tmp > $(call obj2dep,$(@)) && \
rm -f $(call obj2dep,$(@)).tmp
diff --git a/mk/toolchain/clang/rte.vars.mk b/mk/toolchain/clang/rte.vars.mk
index dde922d22..3cfe92545 100644
--- a/mk/toolchain/clang/rte.vars.mk
+++ b/mk/toolchain/clang/rte.vars.mk
@@ -67,7 +67,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/gcc/rte.vars.mk b/mk/toolchain/gcc/rte.vars.mk
index 3b907e201..3356a37c8 100644
--- a/mk/toolchain/gcc/rte.vars.mk
+++ b/mk/toolchain/gcc/rte.vars.mk
@@ -75,7 +75,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wcast-align -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/icc/rte.vars.mk b/mk/toolchain/icc/rte.vars.mk
index 33a8ba79e..b4b992e0e 100644
--- a/mk/toolchain/icc/rte.vars.mk
+++ b/mk/toolchain/icc/rte.vars.mk
@@ -70,10 +70,10 @@ TOOLCHAIN_ASFLAGS =
# error #15527: loop was not vectorized: function call to fprintf cannot be vectorize
# was declared "deprecated"
# Warning #11074, 11076: to prevent "inline-max-size" warnings.
-WERROR_FLAGS := -Wall -w2 -diag-disable 271 -diag-warning 1478
+WERROR_FLAGS := -Wall -w2 -diag-disable 271 -diag-warning 1478
WERROR_FLAGS += -diag-disable 13368 -diag-disable 15527
WERROR_FLAGS += -diag-disable 188
-WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076
+WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076 -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror-all
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-01 18:56 [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (3 preceding siblings ...)
2017-12-01 18:56 ` [PATCH 4/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
@ 2017-12-08 17:14 ` Neil Horman
2017-12-08 17:14 ` [PATCHv2 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
` (3 more replies)
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (2 subsequent siblings)
7 siblings, 4 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-08 17:14 UTC (permalink / raw)
To: dev
Hey all-
A few days ago, I was lamenting the fact that, when reviewing patches I
would frequently complain about ABI changes that were actually considered safe
because they were part of the EXPERIMENTAL api set. John M. asked me then what
I might do to improve the situation, and the following patch set is a proposal
that I've come up with.
In thinking about the problem I identified two issues that I think we
can improve on in this area:
1) Make experimental api calls more visible in the source code. That is to say,
when reviewing patches, it would be nice to have some sort of visual reference
that indicates that the changes being made are part of an experimental API and
therefore ABI concerns need not be addressed
2) Make experimenal api usage more visible to consumers of the DPDK, so that
they can make a more informed decision about the API's they consume in their
application. We make an effort to document all the experimental API's, but
there is no guarantee that a user will check the documentation before making use
of a new library.
This patch set attempts to achieve both of the above goals. To do this I've
added an __experimental macro tag, suitable for inserting into api forward
declarations and definitions.
The presence of the tag in the header and c files where the api code resides
increases the likelyhood that any patch submitted against them will include the
tag in the context, making it clear to reviewers that ABI stability isn't a
concern here.
Also, This tag marks each function it is used on with an attibute causing any
use of the fuction to emit a warning during the build
with a message indicating that the API call in question is not yet part of the
stable interface. Developers can then make an informed decision to suppress
that warning or not.
Because there is internal use of several experimental API's, this set also
includes a new override macro ALLOW_EXPERIMENTAL_FUNCTIONS to automatically
suprress these warnings. I think its fair to assume that, for internal use, we
almost always want to suppress these warnings, as by definition any change to
the apis (even their removal) must be done in parallel with an appropriate
change in the calling locations, lest the dpdk build itself break.
Neil
---
Change Notes:
v2)
* Cleaned up checkpatch errors
* Added Allowance for building experimental on BSD
* Swapped Patch 3 and 4 so that we didn't have a commit level that issued
warnings/errors without need
^ permalink raw reply [flat|nested] 83+ messages in thread
* [PATCHv2 1/4] buildtools: Add tool to check EXPERIMENTAL api exports
2017-12-08 17:14 ` [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
@ 2017-12-08 17:14 ` Neil Horman
2017-12-08 17:14 ` [PATCHv2 2/4] compat: Add __experimental macro Neil Horman
` (2 subsequent siblings)
3 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-08 17:14 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John
This tools reads the given version map for a directory, and checks to
ensure that, for each symbol listed in the export list, the corresponding
definition is tagged as __experimental, erroring out if its not. In this
way, we can ensure that the EXPERIMENTAL api is kept in sync with the tags
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
---
buildtools/experimentalsyms.sh | 35 +++++++++++++++++++++++++++++++++++
1 file changed, 35 insertions(+)
create mode 100755 buildtools/experimentalsyms.sh
diff --git a/buildtools/experimentalsyms.sh b/buildtools/experimentalsyms.sh
new file mode 100755
index 000000000..7342ec9b3
--- /dev/null
+++ b/buildtools/experimentalsyms.sh
@@ -0,0 +1,35 @@
+#!/bin/sh
+
+MAPFILE=$1
+OBJFILE=$2
+
+if [ -d $MAPFILE ]
+then
+ exit 0
+fi
+
+if [ -d $OBJFILE ]
+then
+ exit 0
+fi
+
+for i in `awk 'BEGIN {found=0}
+ /.*EXPERIMENTAL.*/ {found=1}
+ /.*}.*;/ {found=0}
+ /.*;/ {if (found == 1) print $1}' $MAPFILE`
+do
+ SYM=`echo $i | sed -e"s/;//"`
+ objdump -t $OBJFILE | grep -q "\.text.*$SYM"
+ IN_TEXT=$?
+ objdump -t $OBJFILE | grep -q "\.text\.experimental.*$SYM"
+ IN_EXP=$?
+ if [ $IN_TEXT -eq 0 -a $IN_EXP -ne 0 ]
+ then
+ echo "$SYM is not flagged as experimental"
+ echo "but is listed in version map"
+ echo "Please add __experimental to the definition of $SYM"
+ exit 1
+ fi
+done
+exit 0
+
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv2 2/4] compat: Add __experimental macro
2017-12-08 17:14 ` [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-08 17:14 ` [PATCHv2 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
@ 2017-12-08 17:14 ` Neil Horman
2017-12-08 17:14 ` [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-08 17:14 ` [PATCHv2 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
3 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-08 17:14 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John
The __experimental macro tags a given exported function as being part of
the EXPERIMENTAL api. Use of this tag will cause any caller of the
function (that isn't removed by dead code elimination) to emit a warning
that the user is making use of an API whos stabilty isn't guaranteed.
It also places the function in the .text.experimental section, which is
used to validate the tag against the corresponding library version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
---
lib/librte_compat/rte_compat.h | 3 +++
1 file changed, 3 insertions(+)
diff --git a/lib/librte_compat/rte_compat.h b/lib/librte_compat/rte_compat.h
index 41e8032ba..3365a0345 100644
--- a/lib/librte_compat/rte_compat.h
+++ b/lib/librte_compat/rte_compat.h
@@ -101,5 +101,8 @@
*/
#endif
+#define __experimental \
+__attribute__((deprecated("Symbol is not yet part of stable abi"), \
+section(".text.experimental")))
#endif /* _RTE_COMPAT_H_ */
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-08 17:14 ` [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-08 17:14 ` [PATCHv2 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-08 17:14 ` [PATCHv2 2/4] compat: Add __experimental macro Neil Horman
@ 2017-12-08 17:14 ` Neil Horman
2017-12-11 11:35 ` Bruce Richardson
2017-12-08 17:14 ` [PATCHv2 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
3 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2017-12-08 17:14 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John
Add checks during build to ensure that all symbols in the EXPERIMENTAL
version map section have __experimental tags on their definitions, and
enable the warnings needed to announce their use. Also add a
ALLOW_EXPERIMENTAL_FUNCTIONS variable check to allow for in-tree dpdk
libraries to override those checks.
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
---
app/test-eventdev/Makefile | 2 ++
app/test-pmd/Makefile | 2 ++
drivers/event/sw/Makefile | 2 ++
drivers/net/failsafe/Makefile | 2 ++
drivers/net/ixgbe/Makefile | 2 ++
examples/eventdev_pipeline_sw_pmd/Makefile | 2 ++
examples/flow_classify/Makefile | 2 ++
examples/ipsec-secgw/Makefile | 2 ++
examples/service_cores/Makefile | 2 ++
lib/librte_eal/bsdapp/eal/Makefile | 2 ++
lib/librte_eal/linuxapp/Makefile | 2 ++
lib/librte_eal/linuxapp/eal/Makefile | 4 ++++
lib/librte_eventdev/Makefile | 3 +++
lib/librte_security/Makefile | 3 +++
mk/internal/rte.compile-pre.mk | 14 ++++++++++++--
mk/toolchain/clang/rte.vars.mk | 2 +-
mk/toolchain/gcc/rte.vars.mk | 2 +-
mk/toolchain/icc/rte.vars.mk | 2 +-
18 files changed, 47 insertions(+), 5 deletions(-)
diff --git a/app/test-eventdev/Makefile b/app/test-eventdev/Makefile
index dcb2ac476..e68870828 100644
--- a/app/test-eventdev/Makefile
+++ b/app/test-eventdev/Makefile
@@ -32,6 +32,8 @@ include $(RTE_SDK)/mk/rte.vars.mk
APP = dpdk-test-eventdev
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/app/test-pmd/Makefile b/app/test-pmd/Makefile
index d21308fcd..f0262a369 100644
--- a/app/test-pmd/Makefile
+++ b/app/test-pmd/Makefile
@@ -33,6 +33,8 @@ include $(RTE_SDK)/mk/rte.vars.mk
ifeq ($(CONFIG_RTE_TEST_PMD),y)
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
#
# library name
#
diff --git a/drivers/event/sw/Makefile b/drivers/event/sw/Makefile
index 2f2b67bac..0711ce46e 100644
--- a/drivers/event/sw/Makefile
+++ b/drivers/event/sw/Makefile
@@ -33,6 +33,8 @@ include $(RTE_SDK)/mk/rte.vars.mk
# library name
LIB = librte_pmd_sw_event.a
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# build flags
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/drivers/net/failsafe/Makefile b/drivers/net/failsafe/Makefile
index ea2a8fe46..795da9d56 100644
--- a/drivers/net/failsafe/Makefile
+++ b/drivers/net/failsafe/Makefile
@@ -36,6 +36,8 @@ LIB = librte_pmd_failsafe.a
EXPORT_MAP := rte_pmd_failsafe_version.map
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
LIBABIVER := 1
# Sources are stored in SRCS-y
diff --git a/drivers/net/ixgbe/Makefile b/drivers/net/ixgbe/Makefile
index 511a64eb0..b8431600a 100644
--- a/drivers/net/ixgbe/Makefile
+++ b/drivers/net/ixgbe/Makefile
@@ -36,6 +36,8 @@ include $(RTE_SDK)/mk/rte.vars.mk
#
LIB = librte_pmd_ixgbe.a
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/eventdev_pipeline_sw_pmd/Makefile b/examples/eventdev_pipeline_sw_pmd/Makefile
index de4e22c88..4272caf93 100644
--- a/examples/eventdev_pipeline_sw_pmd/Makefile
+++ b/examples/eventdev_pipeline_sw_pmd/Makefile
@@ -32,6 +32,8 @@ ifeq ($(RTE_SDK),)
$(error "Please define RTE_SDK environment variable")
endif
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# Default target, can be overridden by command line or environment
RTE_TARGET ?= x86_64-native-linuxapp-gcc
diff --git a/examples/flow_classify/Makefile b/examples/flow_classify/Makefile
index eecdde14c..b04747c40 100644
--- a/examples/flow_classify/Makefile
+++ b/examples/flow_classify/Makefile
@@ -33,6 +33,8 @@ ifeq ($(RTE_SDK),)
$(error "Please define RTE_SDK environment variable")
endif
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# Default target, can be overridden by command line or environment
RTE_TARGET ?= x86_64-native-linuxapp-gcc
diff --git a/examples/ipsec-secgw/Makefile b/examples/ipsec-secgw/Makefile
index 9fd33cb7f..90a4feca1 100644
--- a/examples/ipsec-secgw/Makefile
+++ b/examples/ipsec-secgw/Makefile
@@ -33,6 +33,8 @@ ifeq ($(RTE_SDK),)
$(error "Please define RTE_SDK environment variable")
endif
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# Default target, can be overridden by command line or environment
RTE_TARGET ?= x86_64-native-linuxapp-gcc
diff --git a/examples/service_cores/Makefile b/examples/service_cores/Makefile
index bd4a345dc..ba731e259 100644
--- a/examples/service_cores/Makefile
+++ b/examples/service_cores/Makefile
@@ -32,6 +32,8 @@ ifeq ($(RTE_SDK),)
$(error "Please define RTE_SDK environment variable")
endif
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# Default target, can be overridden by command line or environment
RTE_TARGET ?= x86_64-native-linuxapp-gcc
diff --git a/lib/librte_eal/bsdapp/eal/Makefile b/lib/librte_eal/bsdapp/eal/Makefile
index afa117de4..936010cd6 100644
--- a/lib/librte_eal/bsdapp/eal/Makefile
+++ b/lib/librte_eal/bsdapp/eal/Makefile
@@ -33,6 +33,8 @@ include $(RTE_SDK)/mk/rte.vars.mk
LIB = librte_eal.a
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
ARCH_DIR ?= $(RTE_ARCH)
VPATH += $(RTE_SDK)/lib/librte_eal/common
VPATH += $(RTE_SDK)/lib/librte_eal/common/arch/$(ARCH_DIR)
diff --git a/lib/librte_eal/linuxapp/Makefile b/lib/librte_eal/linuxapp/Makefile
index 2ebdf3139..11ee59e42 100644
--- a/lib/librte_eal/linuxapp/Makefile
+++ b/lib/librte_eal/linuxapp/Makefile
@@ -31,6 +31,8 @@
include $(RTE_SDK)/mk/rte.vars.mk
+ALLOW_EXPERIMENTAL_FUNCTIONS := 2
+
DIRS-$(CONFIG_RTE_EXEC_ENV_LINUXAPP) += eal
DIRS-$(CONFIG_RTE_EAL_IGB_UIO) += igb_uio
DIRS-$(CONFIG_RTE_KNI_KMOD) += kni
diff --git a/lib/librte_eal/linuxapp/eal/Makefile b/lib/librte_eal/linuxapp/eal/Makefile
index 5a7b8b2ac..36d17efb6 100644
--- a/lib/librte_eal/linuxapp/eal/Makefile
+++ b/lib/librte_eal/linuxapp/eal/Makefile
@@ -34,6 +34,10 @@ include $(RTE_SDK)/mk/rte.vars.mk
LIB = librte_eal.a
ARCH_DIR ?= $(RTE_ARCH)
+
+#Allow the use of experimental functions without warning
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
EXPORT_MAP := ../../rte_eal_version.map
VPATH += $(RTE_SDK)/lib/librte_eal/common/arch/$(ARCH_DIR)
diff --git a/lib/librte_eventdev/Makefile b/lib/librte_eventdev/Makefile
index 5ac22cde7..e37de2820 100644
--- a/lib/librte_eventdev/Makefile
+++ b/lib/librte_eventdev/Makefile
@@ -36,6 +36,9 @@ LIB = librte_eventdev.a
# library version
LIBABIVER := 3
+# Allow the use of experimental functions
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# build flags
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/lib/librte_security/Makefile b/lib/librte_security/Makefile
index bb93ec33d..c2815fab8 100644
--- a/lib/librte_security/Makefile
+++ b/lib/librte_security/Makefile
@@ -36,6 +36,9 @@ LIB = librte_security.a
# library version
LIBABIVER := 1
+# Allow the use of experimental functions without warnings
+ALLOW_EXPERIMENTAL_FUNCTIONS := 1
+
# build flags
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/mk/internal/rte.compile-pre.mk b/mk/internal/rte.compile-pre.mk
index da8dda498..dea7f01a2 100644
--- a/mk/internal/rte.compile-pre.mk
+++ b/mk/internal/rte.compile-pre.mk
@@ -72,18 +72,27 @@ CMDS-all := $(CMDS-y) $(CMDS-n) $(CMDS-)
-include $(DEPS-y) $(CMDS-y)
+ifdef ALLOW_EXPERIMENTAL_FUNCTIONS
+EXPERIMENTAL_CFLAGS := $(subst 1, -Wno-deprecated-declarations -Wno-deprecated -Wno-error=deprecated-declarations -Wno-error=deprecated, $(ALLOW_EXPERIMENTAL_FUNCTIONS))
+else
+EXPERIMENTAL_CFLAGS :=
+endif
+
# command to compile a .c file to generate an object
ifeq ($(USE_HOST),1)
C_TO_O = $(HOSTCC) -Wp,-MD,$(call obj2dep,$(@)).tmp $(HOST_CPPFLAGS) $(HOST_CFLAGS) \
- $(CFLAGS_$(@)) $(HOST_EXTRA_CPPFLAGS) $(HOST_EXTRA_CFLAGS) -o $@ -c $<
+ $(CFLAGS_$(@)) $(HOST_EXTRA_CPPFLAGS) $(HOST_EXTRA_CFLAGS) $(EXPERIMENTAL_CFLAGS) -o $@ -c $<
C_TO_O_STR = $(subst ','\'',$(C_TO_O)) #'# fix syntax highlight
C_TO_O_DISP = $(if $(V),"$(C_TO_O_STR)"," HOSTCC $(@)")
else
C_TO_O = $(CC) -Wp,-MD,$(call obj2dep,$(@)).tmp $(CPPFLAGS) $(CFLAGS) \
- $(CFLAGS_$(@)) $(EXTRA_CPPFLAGS) $(EXTRA_CFLAGS) -o $@ -c $<
+ $(CFLAGS_$(@)) $(EXTRA_CPPFLAGS) $(EXTRA_CFLAGS) $(EXPERIMENTAL_CFLAGS) -o $@ -c $<
C_TO_O_STR = $(subst ','\'',$(C_TO_O)) #'# fix syntax highlight
C_TO_O_DISP = $(if $(V),"$(C_TO_O_STR)"," CC $(@)")
endif
+EXPERIMENTAL_CHECK = $(RTE_SDK)/buildtools/experimentalsyms.sh
+CHECK_EXPERIMENTAL = $(EXPERIMENTAL_CHECK) $(SRCDIR)/$(EXPORT_MAP) $@
+
PMDINFO_GEN = $(RTE_SDK_BIN)/app/dpdk-pmdinfogen $@ $@.pmd.c
PMDINFO_CC = $(CC) $(CPPFLAGS) $(CFLAGS) -c -o $@.pmd.o $@.pmd.c
PMDINFO_LD = $(CROSS)ld $(LDFLAGS) -r -o $@.o $@.pmd.o $@
@@ -100,6 +109,7 @@ C_TO_O_DO = @set -e; \
echo $(C_TO_O_DISP); \
$(C_TO_O) && \
$(PMDINFO_TO_O) && \
+ $(CHECK_EXPERIMENTAL) && \
echo $(C_TO_O_CMD) > $(call obj2cmd,$(@)) && \
sed 's,'$@':,dep_'$@' =,' $(call obj2dep,$(@)).tmp > $(call obj2dep,$(@)) && \
rm -f $(call obj2dep,$(@)).tmp
diff --git a/mk/toolchain/clang/rte.vars.mk b/mk/toolchain/clang/rte.vars.mk
index dde922d22..3cfe92545 100644
--- a/mk/toolchain/clang/rte.vars.mk
+++ b/mk/toolchain/clang/rte.vars.mk
@@ -67,7 +67,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/gcc/rte.vars.mk b/mk/toolchain/gcc/rte.vars.mk
index 3b907e201..3356a37c8 100644
--- a/mk/toolchain/gcc/rte.vars.mk
+++ b/mk/toolchain/gcc/rte.vars.mk
@@ -75,7 +75,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wcast-align -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/icc/rte.vars.mk b/mk/toolchain/icc/rte.vars.mk
index 33a8ba79e..58940602e 100644
--- a/mk/toolchain/icc/rte.vars.mk
+++ b/mk/toolchain/icc/rte.vars.mk
@@ -73,7 +73,7 @@ TOOLCHAIN_ASFLAGS =
WERROR_FLAGS := -Wall -w2 -diag-disable 271 -diag-warning 1478
WERROR_FLAGS += -diag-disable 13368 -diag-disable 15527
WERROR_FLAGS += -diag-disable 188
-WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076
+WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076 -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror-all
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv2 4/4] dpdk: add __experimental tag to appropriate api calls
2017-12-08 17:14 ` [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (2 preceding siblings ...)
2017-12-08 17:14 ` [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
@ 2017-12-08 17:14 ` Neil Horman
3 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-08 17:14 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John
Append the __experimental tag to api calls appearing in the EXPERIMENTAL
section of their libraries version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
---
lib/librte_eal/common/eal_common_dev.c | 6 ++-
lib/librte_eal/common/eal_common_devargs.c | 7 +--
lib/librte_eal/common/include/rte_dev.h | 6 ++-
lib/librte_eal/common/include/rte_devargs.h | 8 ++--
lib/librte_eal/common/include/rte_service.h | 47 ++++++++++---------
.../common/include/rte_service_component.h | 14 +++---
lib/librte_eal/common/rte_service.c | 52 ++++++++++++----------
lib/librte_eal/linuxapp/eal/eal.c | 1 +
lib/librte_ether/rte_mtr.c | 25 ++++++-----
lib/librte_ether/rte_mtr.h | 26 +++++------
lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
lib/librte_security/rte_security.c | 16 +++----
lib/librte_security/rte_security.h | 23 +++++-----
14 files changed, 139 insertions(+), 116 deletions(-)
diff --git a/lib/librte_eal/common/eal_common_dev.c b/lib/librte_eal/common/eal_common_dev.c
index dda8f5835..ee866ddd2 100644
--- a/lib/librte_eal/common/eal_common_dev.c
+++ b/lib/librte_eal/common/eal_common_dev.c
@@ -37,6 +37,7 @@
#include <inttypes.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
#include <rte_dev.h>
#include <rte_devargs.h>
@@ -133,7 +134,7 @@ full_dev_name(const char *bus, const char *dev, const char *args)
return name;
}
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs)
{
struct rte_bus *bus;
@@ -203,7 +204,8 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
return ret;
}
-int rte_eal_hotplug_remove(const char *busname, const char *devname)
+int __experimental
+rte_eal_hotplug_remove(const char *busname, const char *devname)
{
struct rte_bus *bus;
struct rte_device *dev;
diff --git a/lib/librte_eal/common/eal_common_devargs.c b/lib/librte_eal/common/eal_common_devargs.c
index 6ac88d6ab..8e46d54bd 100644
--- a/lib/librte_eal/common/eal_common_devargs.c
+++ b/lib/librte_eal/common/eal_common_devargs.c
@@ -40,6 +40,7 @@
#include <stdio.h>
#include <string.h>
+#include <rte_compat.h>
#include <rte_dev.h>
#include <rte_devargs.h>
#include <rte_tailq.h>
@@ -85,7 +86,7 @@ bus_name_cmp(const struct rte_bus *bus, const void *name)
return strncmp(bus->name, name, strlen(bus->name));
}
-int
+int __experimental
rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
{
struct rte_bus *bus = NULL;
@@ -139,7 +140,7 @@ rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
return 0;
}
-int
+int __experimental
rte_eal_devargs_insert(struct rte_devargs *da)
{
int ret;
@@ -188,7 +189,7 @@ rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str)
return -1;
}
-int
+int __experimental
rte_eal_devargs_remove(const char *busname, const char *devname)
{
struct rte_devargs *d;
diff --git a/lib/librte_eal/common/include/rte_dev.h b/lib/librte_eal/common/include/rte_dev.h
index 9342e0cbd..ddb0a09a7 100644
--- a/lib/librte_eal/common/include/rte_dev.h
+++ b/lib/librte_eal/common/include/rte_dev.h
@@ -49,6 +49,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_log.h>
__attribute__((format(printf, 2, 0)))
@@ -209,7 +210,7 @@ int rte_eal_dev_detach(struct rte_device *dev);
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs);
/**
@@ -225,7 +226,8 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_remove(const char *busname, const char *devname);
+int __experimental rte_eal_hotplug_remove(const char *busname,
+ const char *devname);
/**
* Device comparison function.
diff --git a/lib/librte_eal/common/include/rte_devargs.h b/lib/librte_eal/common/include/rte_devargs.h
index 58d585df6..e4c10b6c5 100644
--- a/lib/librte_eal/common/include/rte_devargs.h
+++ b/lib/librte_eal/common/include/rte_devargs.h
@@ -50,6 +50,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
/**
@@ -136,7 +137,7 @@ int rte_eal_parse_devargs_str(const char *devargs_str,
* - 0 on success.
* - Negative errno on error.
*/
-int
+int __experimental
rte_eal_devargs_parse(const char *dev,
struct rte_devargs *da);
@@ -150,7 +151,7 @@ rte_eal_devargs_parse(const char *dev,
* - 0 on success
* - Negative on error.
*/
-int
+int __experimental
rte_eal_devargs_insert(struct rte_devargs *da);
/**
@@ -193,7 +194,8 @@ int rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str);
* <0 on error.
* >0 if the devargs was not within the user device list.
*/
-int rte_eal_devargs_remove(const char *busname, const char *devname);
+int __experimental rte_eal_devargs_remove(const char *busname,
+ const char *devname);
/**
* Count the number of user devices of a specified type
diff --git a/lib/librte_eal/common/include/rte_service.h b/lib/librte_eal/common/include/rte_service.h
index 927244065..da10d17ea 100644
--- a/lib/librte_eal/common/include/rte_service.h
+++ b/lib/librte_eal/common/include/rte_service.h
@@ -84,7 +84,7 @@ extern "C" {
*
* @return The number of services registered.
*/
-uint32_t rte_service_get_count(void);
+uint32_t __experimental rte_service_get_count(void);
/**
* @warning
@@ -111,7 +111,8 @@ uint32_t rte_service_get_count(void);
* @retval -EINVAL Null *service_id* pointer provided
* @retval -ENODEV No such service registered
*/
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
+int32_t __experimental rte_service_get_by_name(const char *name,
+ uint32_t *service_id);
/**
* @warning
@@ -122,7 +123,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
* @return A pointer to the name of the service. The returned pointer remains
* in ownership of the service, and the application must not free it.
*/
-const char *rte_service_get_name(uint32_t id);
+const char __experimental *rte_service_get_name(uint32_t id);
/**
* @warning
@@ -135,7 +136,8 @@ const char *rte_service_get_name(uint32_t id);
* @retval 1 Capability supported by this service instance
* @retval 0 Capability not supported by this service instance
*/
-int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
+int32_t __experimental rte_service_probe_capability(uint32_t id,
+ uint32_t capability);
/**
* @warning
@@ -159,8 +161,8 @@ int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
* @retval 0 lcore map updated successfully
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
- uint32_t enable);
+int32_t __experimental rte_service_map_lcore_set(uint32_t service_id,
+ uint32_t lcore, uint32_t enable);
/**
* @warning
@@ -175,7 +177,8 @@ int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
* @retval 0 lcore is not mapped to service
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
+int32_t __experimental rte_service_map_lcore_get(uint32_t service_id,
+ uint32_t lcore);
/**
* @warning
@@ -192,7 +195,7 @@ int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
* @retval 0 The service was successfully started
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __experimental rte_service_runstate_set(uint32_t id, uint32_t runstate);
/**
* @warning
@@ -210,7 +213,7 @@ int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
* @retval 0 Service is stopped
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_get(uint32_t id);
+int32_t __experimental rte_service_runstate_get(uint32_t id);
/**
* @warning
@@ -226,7 +229,8 @@ int32_t rte_service_runstate_get(uint32_t id);
* @retval 0 Success
* @retval -EINVAL Invalid service ID
*/
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
+int32_t __experimental rte_service_set_runstate_mapped_check(uint32_t id,
+ int32_t enable);
/**
* @warning
@@ -264,7 +268,7 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
* @retval -ENOEXEC Service is not in a run-able state
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_multithread_unsafe);
/**
@@ -280,7 +284,7 @@ int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
* @retval -EINVAL Failed to start core. The *lcore_id* passed in is not
* currently assigned to be a service core.
*/
-int32_t rte_service_lcore_start(uint32_t lcore_id);
+int32_t __experimental rte_service_lcore_start(uint32_t lcore_id);
/**
* @warning
@@ -299,7 +303,7 @@ int32_t rte_service_lcore_start(uint32_t lcore_id);
* The application must stop the service first, and then stop the
* lcore.
*/
-int32_t rte_service_lcore_stop(uint32_t lcore_id);
+int32_t __experimental rte_service_lcore_stop(uint32_t lcore_id);
/**
* @warning
@@ -315,7 +319,7 @@ int32_t rte_service_lcore_stop(uint32_t lcore_id);
* @retval -EALREADY lcore is already added to the service core list
* @retval -EINVAL Invalid lcore provided
*/
-int32_t rte_service_lcore_add(uint32_t lcore);
+int32_t __experimental rte_service_lcore_add(uint32_t lcore);
/**
* @warning
@@ -329,7 +333,7 @@ int32_t rte_service_lcore_add(uint32_t lcore);
* @retval -EBUSY Lcore is not stopped, stop service core before removing.
* @retval -EINVAL failed to add lcore to service core mask.
*/
-int32_t rte_service_lcore_del(uint32_t lcore);
+int32_t __experimental rte_service_lcore_del(uint32_t lcore);
/**
* @warning
@@ -346,7 +350,7 @@ int32_t rte_service_lcore_del(uint32_t lcore);
*
* @return The number of service cores currently configured.
*/
-int32_t rte_service_lcore_count(void);
+int32_t __experimental rte_service_lcore_count(void);
/**
* @warning
@@ -358,7 +362,7 @@ int32_t rte_service_lcore_count(void);
*
* @retval 0 Success
*/
-int32_t rte_service_lcore_reset_all(void);
+int32_t __experimental rte_service_lcore_reset_all(void);
/**
* @warning
@@ -372,7 +376,8 @@ int32_t rte_service_lcore_reset_all(void);
* @retval 0 Success
* @retval -EINVAL Invalid service pointer passed
*/
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
+int32_t __experimental rte_service_set_stats_enable(uint32_t id,
+ int32_t enable);
/**
* @warning
@@ -393,7 +398,7 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
* service core list. No items have been populated, call this function
* with a size of at least *rte_service_core_count* items.
*/
-int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
+int32_t __experimental rte_service_lcore_list(uint32_t array[], uint32_t n);
/**
* @warning
@@ -406,7 +411,7 @@ int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
* @retval -EINVAL Invalid lcore provided
* @retval -ENOTSUP The provided lcore is not a service core.
*/
-int32_t rte_service_lcore_count_services(uint32_t lcore);
+int32_t __experimental rte_service_lcore_count_services(uint32_t lcore);
/**
* @warning
@@ -418,7 +423,7 @@ int32_t rte_service_lcore_count_services(uint32_t lcore);
* @retval 0 Statistics have been successfully dumped
* @retval -EINVAL Invalid service id provided
*/
-int32_t rte_service_dump(FILE *f, uint32_t id);
+int32_t __experimental rte_service_dump(FILE *f, uint32_t id);
#ifdef __cplusplus
}
diff --git a/lib/librte_eal/common/include/rte_service_component.h b/lib/librte_eal/common/include/rte_service_component.h
index ac965cb48..a129258eb 100644
--- a/lib/librte_eal/common/include/rte_service_component.h
+++ b/lib/librte_eal/common/include/rte_service_component.h
@@ -37,7 +37,7 @@
* Include this file if you are writing a component that requires CPU cycles to
* operate, and you wish to run the component using service cores
*/
-
+#include <rte_compat.h>
#include <rte_service.h>
/**
@@ -101,8 +101,9 @@ struct rte_service_spec {
* -EINVAL Attempted to register an invalid service (eg, no callback
* set)
*/
-int32_t rte_service_component_register(const struct rte_service_spec *spec,
- uint32_t *service_id);
+int32_t __experimental
+rte_service_component_register(const struct rte_service_spec *spec,
+ uint32_t *service_id);
/**
* @warning
@@ -116,7 +117,7 @@ int32_t rte_service_component_register(const struct rte_service_spec *spec,
* @retval -EBUSY The service is currently running, stop the service before
* calling unregister. No action has been taken.
*/
-int32_t rte_service_component_unregister(uint32_t id);
+int32_t __experimental rte_service_component_unregister(uint32_t id);
/**
* @warning
@@ -134,7 +135,7 @@ int32_t rte_service_component_unregister(uint32_t id);
* @retval -ENODEV Error in enabling service lcore on a service
* @retval -ENOEXEC Error when starting services
*/
-int32_t rte_service_start_with_defaults(void);
+int32_t __experimental rte_service_start_with_defaults(void);
/**
* @warning
@@ -151,7 +152,8 @@ int32_t rte_service_start_with_defaults(void);
*
* @retval 0 Success
*/
-int32_t rte_service_component_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __experimental rte_service_component_runstate_set(uint32_t id,
+ uint32_t runstate);
/**
* @warning
diff --git a/lib/librte_eal/common/rte_service.c b/lib/librte_eal/common/rte_service.c
index ae97e6b7f..178354323 100644
--- a/lib/librte_eal/common/rte_service.c
+++ b/lib/librte_eal/common/rte_service.c
@@ -38,6 +38,7 @@
#include <string.h>
#include <dirent.h>
+#include <rte_compat.h>
#include <rte_service.h>
#include "include/rte_service_component.h"
@@ -168,7 +169,8 @@ service_mt_safe(struct rte_service_spec_impl *s)
return !!(s->spec.capabilities & RTE_SERVICE_CAP_MT_SAFE);
}
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
+int32_t __experimental
+rte_service_set_stats_enable(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -181,7 +183,8 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
return 0;
}
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
+int32_t __experimental
+rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -194,13 +197,14 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
return 0;
}
-uint32_t
+uint32_t __experimental
rte_service_get_count(void)
{
return rte_service_count;
}
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
+int32_t __experimental
+rte_service_get_by_name(const char *name, uint32_t *service_id)
{
if (!service_id)
return -EINVAL;
@@ -217,7 +221,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
return -ENODEV;
}
-const char *
+const char * __experimental
rte_service_get_name(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -225,7 +229,7 @@ rte_service_get_name(uint32_t id)
return s->spec.name;
}
-int32_t
+int32_t __experimental
rte_service_probe_capability(uint32_t id, uint32_t capability)
{
struct rte_service_spec_impl *s;
@@ -233,7 +237,7 @@ rte_service_probe_capability(uint32_t id, uint32_t capability)
return !!(s->spec.capabilities & capability);
}
-int32_t
+int32_t __experimental
rte_service_component_register(const struct rte_service_spec *spec,
uint32_t *id_ptr)
{
@@ -266,7 +270,7 @@ rte_service_component_register(const struct rte_service_spec *spec,
return 0;
}
-int32_t
+int32_t __experimental
rte_service_component_unregister(uint32_t id)
{
uint32_t i;
@@ -287,7 +291,7 @@ rte_service_component_unregister(uint32_t id)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -302,7 +306,7 @@ rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -317,7 +321,7 @@ rte_service_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_runstate_get(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -378,7 +382,7 @@ service_run(uint32_t i, struct core_state *cs, uint64_t service_mask)
return 0;
}
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_mt_unsafe)
{
/* run service on calling core, using all-ones as the service mask */
@@ -434,7 +438,7 @@ rte_service_runner_func(void *arg)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_lcore_count(void)
{
int32_t count = 0;
@@ -444,7 +448,7 @@ rte_service_lcore_count(void)
return count;
}
-int32_t
+int32_t __experimental
rte_service_lcore_list(uint32_t array[], uint32_t n)
{
uint32_t count = rte_service_lcore_count();
@@ -467,7 +471,7 @@ rte_service_lcore_list(uint32_t array[], uint32_t n)
return count;
}
-int32_t
+int32_t __experimental
rte_service_lcore_count_services(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -480,7 +484,7 @@ rte_service_lcore_count_services(uint32_t lcore)
return __builtin_popcountll(cs->service_mask);
}
-int32_t
+int32_t __experimental
rte_service_start_with_defaults(void)
{
/* create a default mapping from cores to services, then start the
@@ -562,7 +566,7 @@ service_update(struct rte_service_spec *service, uint32_t lcore,
return 0;
}
-int32_t
+int32_t __experimental
rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
{
struct rte_service_spec_impl *s;
@@ -571,7 +575,7 @@ rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
return service_update(&s->spec, lcore, &on, 0);
}
-int32_t
+int32_t __experimental
rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
{
struct rte_service_spec_impl *s;
@@ -583,7 +587,7 @@ rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
return ret;
}
-int32_t rte_service_lcore_reset_all(void)
+int32_t __experimental rte_service_lcore_reset_all(void)
{
/* loop over cores, reset all to mask 0 */
uint32_t i;
@@ -614,7 +618,7 @@ set_lcore_state(uint32_t lcore, int32_t state)
lcore_states[lcore].is_service_core = (state == ROLE_SERVICE);
}
-int32_t
+int32_t __experimental
rte_service_lcore_add(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -633,7 +637,7 @@ rte_service_lcore_add(uint32_t lcore)
return rte_eal_wait_lcore(lcore);
}
-int32_t
+int32_t __experimental
rte_service_lcore_del(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -652,7 +656,7 @@ rte_service_lcore_del(uint32_t lcore)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_lcore_start(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -675,7 +679,7 @@ rte_service_lcore_start(uint32_t lcore)
return ret;
}
-int32_t
+int32_t __experimental
rte_service_lcore_stop(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -745,7 +749,7 @@ service_dump_calls_per_lcore(FILE *f, uint32_t lcore, uint32_t reset)
fprintf(f, "\n");
}
-int32_t rte_service_dump(FILE *f, uint32_t id)
+int32_t __experimental rte_service_dump(FILE *f, uint32_t id)
{
uint32_t i;
int print_one = (id != UINT32_MAX);
diff --git a/lib/librte_eal/linuxapp/eal/eal.c b/lib/librte_eal/linuxapp/eal/eal.c
index 229eec9f1..73a0da22c 100644
--- a/lib/librte_eal/linuxapp/eal/eal.c
+++ b/lib/librte_eal/linuxapp/eal/eal.c
@@ -53,6 +53,7 @@
#include <sys/io.h>
#endif
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_debug.h>
#include <rte_memory.h>
diff --git a/lib/librte_ether/rte_mtr.c b/lib/librte_ether/rte_mtr.c
index 4f56f8714..2cbe0bb5a 100644
--- a/lib/librte_ether/rte_mtr.c
+++ b/lib/librte_ether/rte_mtr.c
@@ -34,6 +34,7 @@
#include <stdint.h>
#include <rte_errno.h>
+#include "rte_compat.h"
#include "rte_ethdev.h"
#include "rte_mtr_driver.h"
#include "rte_mtr.h"
@@ -86,7 +87,7 @@ rte_mtr_ops_get(uint16_t port_id, struct rte_mtr_error *error)
})
/* MTR capabilities get */
-int
+int __experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error)
@@ -97,7 +98,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
}
/* MTR meter profile add */
-int
+int __experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -109,7 +110,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
}
/** MTR meter profile delete */
-int
+int __experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error)
@@ -120,7 +121,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
}
/** MTR object create */
-int
+int __experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -133,7 +134,7 @@ rte_mtr_create(uint16_t port_id,
}
/** MTR object destroy */
-int
+int __experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -144,7 +145,7 @@ rte_mtr_destroy(uint16_t port_id,
}
/** MTR object meter enable */
-int
+int __experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -155,7 +156,7 @@ rte_mtr_meter_enable(uint16_t port_id,
}
/** MTR object meter disable */
-int
+int __experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -166,7 +167,7 @@ rte_mtr_meter_disable(uint16_t port_id,
}
/** MTR object meter profile update */
-int
+int __experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -178,7 +179,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
}
/** MTR object meter DSCP table update */
-int
+int __experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -190,7 +191,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
}
/** MTR object policer action update */
-int
+int __experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -203,7 +204,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
}
/** MTR object enabled stats update */
-int
+int __experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -215,7 +216,7 @@ rte_mtr_stats_update(uint16_t port_id,
}
/** MTR object stats read */
-int
+int __experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_ether/rte_mtr.h b/lib/librte_ether/rte_mtr.h
index f6b6ef3b6..fd8361998 100644
--- a/lib/librte_ether/rte_mtr.h
+++ b/lib/librte_ether/rte_mtr.h
@@ -74,7 +74,7 @@
* @b EXPERIMENTAL: this API may change without prior notice
*/
#include <stdint.h>
-
+#include <rte_compat.h>
#include <rte_common.h>
#ifdef __cplusplus
@@ -447,7 +447,7 @@ struct rte_mtr_error {
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error);
@@ -470,7 +470,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -491,7 +491,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error);
@@ -519,7 +519,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
*
* @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
*/
-int
+int __experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -542,7 +542,7 @@ rte_mtr_create(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -569,7 +569,7 @@ rte_mtr_destroy(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -590,7 +590,7 @@ rte_mtr_meter_disable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -609,7 +609,7 @@ rte_mtr_meter_enable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -633,7 +633,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -659,7 +659,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -684,7 +684,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -715,7 +715,7 @@ rte_mtr_stats_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_flow_classify/rte_flow_classify.c b/lib/librte_flow_classify/rte_flow_classify.c
index e6f448643..6716672fc 100644
--- a/lib/librte_flow_classify/rte_flow_classify.c
+++ b/lib/librte_flow_classify/rte_flow_classify.c
@@ -31,6 +31,7 @@
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+#include <rte_compat.h>
#include <rte_flow_classify.h>
#include "rte_flow_classify_parse.h"
#include <rte_flow_driver.h>
@@ -245,7 +246,7 @@ rte_flow_classifier_check_params(struct rte_flow_classifier_params *params)
return 0;
}
-struct rte_flow_classifier *
+struct rte_flow_classifier * __experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params)
{
struct rte_flow_classifier *cls;
@@ -291,7 +292,7 @@ rte_flow_classify_table_free(struct rte_table *table)
table->ops.f_free(table->h_table);
}
-int
+int __experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls)
{
uint32_t i;
@@ -369,7 +370,7 @@ rte_table_check_params(struct rte_flow_classifier *cls,
return 0;
}
-int
+int __experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id)
@@ -483,7 +484,7 @@ allocate_acl_ipv4_5tuple_rule(void)
return rule;
}
-struct rte_flow_classify_rule *
+struct rte_flow_classify_rule * __experimental
rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
uint32_t table_id,
int *key_found,
@@ -582,7 +583,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
return rule;
}
-int
+int __experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule)
@@ -659,7 +660,7 @@ action_apply(struct rte_flow_classifier *cls,
return ret;
}
-int
+int __experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_flow_classify/rte_flow_classify.h b/lib/librte_flow_classify/rte_flow_classify.h
index 1211873a1..cd9516f9e 100644
--- a/lib/librte_flow_classify/rte_flow_classify.h
+++ b/lib/librte_flow_classify/rte_flow_classify.h
@@ -70,6 +70,7 @@
* with rte_flow_classifier_free()
*/
+#include <rte_compat.h>
#include <rte_ethdev.h>
#include <rte_ether.h>
#include <rte_flow.h>
@@ -176,7 +177,7 @@ struct rte_flow_classify_ipv4_5tuple_stats {
* @return
* Handle to flow classifier instance on success or NULL otherwise
*/
-struct rte_flow_classifier *
+struct rte_flow_classifier * __experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params);
/**
@@ -187,7 +188,7 @@ rte_flow_classifier_create(struct rte_flow_classifier_params *params);
* @return
* 0 on success, error code otherwise
*/
-int
+int __experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls);
/**
@@ -203,7 +204,7 @@ rte_flow_classifier_free(struct rte_flow_classifier *cls);
* @return
* 0 on success, error code otherwise
*/
-int
+int __experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id);
@@ -250,7 +251,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule);
@@ -274,7 +275,7 @@ rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_security/rte_security.c b/lib/librte_security/rte_security.c
index 1227fca8a..958b7273e 100644
--- a/lib/librte_security/rte_security.c
+++ b/lib/librte_security/rte_security.c
@@ -33,12 +33,12 @@
#include <rte_malloc.h>
#include <rte_dev.h>
-
+#include "rte_compat.h"
#include "rte_security.h"
#include "rte_security_driver.h"
struct rte_security_session *
-rte_security_session_create(struct rte_security_ctx *instance,
+__experimental rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp)
{
@@ -61,7 +61,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
return sess;
}
-int
+int __experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf)
@@ -70,7 +70,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
return instance->ops->session_update(instance->device, sess, conf);
}
-int
+int __experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats)
@@ -79,7 +79,7 @@ rte_security_session_stats_get(struct rte_security_ctx *instance,
return instance->ops->session_stats_get(instance->device, sess, stats);
}
-int
+int __experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess)
{
@@ -98,7 +98,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
return ret;
}
-int
+int __experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *m, void *params)
@@ -108,14 +108,14 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
sess, m, params);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capabilities_get(struct rte_security_ctx *instance)
{
RTE_FUNC_PTR_OR_ERR_RET(*instance->ops->capabilities_get, NULL);
return instance->ops->capabilities_get(instance->device);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx)
{
diff --git a/lib/librte_security/rte_security.h b/lib/librte_security/rte_security.h
index 653929b99..176378e78 100644
--- a/lib/librte_security/rte_security.h
+++ b/lib/librte_security/rte_security.h
@@ -52,6 +52,7 @@ extern "C" {
#include <netinet/ip.h>
#include <netinet/ip6.h>
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_crypto.h>
#include <rte_mbuf.h>
@@ -291,7 +292,7 @@ struct rte_security_session {
* - On success, pointer to session
* - On failure, NULL
*/
-struct rte_security_session *
+struct rte_security_session * __experimental
rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp);
@@ -306,7 +307,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
* - On success returns 0
* - On failure return errno
*/
-int
+int __experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf);
@@ -323,7 +324,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
* - -EINVAL if session is NULL.
* - -EBUSY if not all device private data has been freed.
*/
-int
+int __experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess);
@@ -340,7 +341,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
* - On success, zero.
* - On failure, a negative value.
*/
-int
+int __experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *mb, void *params);
@@ -351,7 +352,7 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
* @param sym_op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __experimental
__rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
struct rte_security_session *sess)
{
@@ -360,13 +361,13 @@ __rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
return 0;
}
-static inline void *
+static inline void * __experimental
get_sec_session_private_data(const struct rte_security_session *sess)
{
return sess->sess_private_data;
}
-static inline void
+static inline void __experimental
set_sec_session_private_data(struct rte_security_session *sess,
void *private_data)
{
@@ -382,7 +383,7 @@ set_sec_session_private_data(struct rte_security_session *sess,
* @param op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __experimental
rte_security_attach_session(struct rte_crypto_op *op,
struct rte_security_session *sess)
{
@@ -424,7 +425,7 @@ struct rte_security_stats {
* - On success return 0
* - On failure errno
*/
-int
+int __experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats);
@@ -507,7 +508,7 @@ struct rte_security_capability_idx {
* - Returns array of security capabilities.
* - Return NULL if no capabilities available.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capabilities_get(struct rte_security_ctx *instance);
/**
@@ -521,7 +522,7 @@ rte_security_capabilities_get(struct rte_security_ctx *instance);
* index criteria.
* - Return NULL if the capability not matched on security instance.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx);
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* Re: [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-08 17:14 ` [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
@ 2017-12-11 11:35 ` Bruce Richardson
2017-12-11 12:40 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Bruce Richardson @ 2017-12-11 11:35 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, Thomas Monjalon, Mcnamara, John
On Fri, Dec 08, 2017 at 12:14:34PM -0500, Neil Horman wrote:
> Add checks during build to ensure that all symbols in the EXPERIMENTAL
> version map section have __experimental tags on their definitions, and
> enable the warnings needed to announce their use. Also add a
> ALLOW_EXPERIMENTAL_FUNCTIONS variable check to allow for in-tree dpdk
> libraries to override those checks.
>
> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> CC: Thomas Monjalon <thomas@monjalon.net>
> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> ---
Hi Neil,
if I read the patch functionality correctly, the
ALLOW_EXPERIMENTAL_FUNCTIONS variable simply suppresses all errors for
deprecated functions. However, what we really want is just to suppress
the errors for the experimental functions, and not any that really are
deprecated. While we may not have any now in DPDK, that doesn't mean it
might not be useful to have some in future.
Therefore, would an alternative scheme work where the experimental tag
is set to empty if the ALLOW_EXPERIMENTAL_FUNCTIONS define is set when
compiling?
/Bruce
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-11 11:35 ` Bruce Richardson
@ 2017-12-11 12:40 ` Neil Horman
2017-12-11 12:45 ` Bruce Richardson
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2017-12-11 12:40 UTC (permalink / raw)
To: Bruce Richardson; +Cc: dev, Thomas Monjalon, Mcnamara, John
On Mon, Dec 11, 2017 at 11:35:57AM +0000, Bruce Richardson wrote:
> On Fri, Dec 08, 2017 at 12:14:34PM -0500, Neil Horman wrote:
> > Add checks during build to ensure that all symbols in the EXPERIMENTAL
> > version map section have __experimental tags on their definitions, and
> > enable the warnings needed to announce their use. Also add a
> > ALLOW_EXPERIMENTAL_FUNCTIONS variable check to allow for in-tree dpdk
> > libraries to override those checks.
> >
> > Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> > CC: Thomas Monjalon <thomas@monjalon.net>
> > CC: "Mcnamara, John" <john.mcnamara@intel.com>
> > ---
>
> Hi Neil,
>
> if I read the patch functionality correctly, the
> ALLOW_EXPERIMENTAL_FUNCTIONS variable simply suppresses all errors for
> deprecated functions. However, what we really want is just to suppress
> the errors for the experimental functions, and not any that really are
> deprecated. While we may not have any now in DPDK, that doesn't mean it
> might not be useful to have some in future.
>
Well, they are all deprecated by the stict definition of the term, which is to
say that their usage is discouraged/disapproved. What I think you are saying is
that you would like to differentiate reasons for deprecation (i.e. deprecation
because an api is experimental, vs deprecation because an api is broken or going
to be removed). I'm not sure I see that we will get there anytime soon, but
yes, that seems like it would be a good ability to add in here.
> Therefore, would an alternative scheme work where the experimental tag
> is set to empty if the ALLOW_EXPERIMENTAL_FUNCTIONS define is set when
> compiling?
>
Yes, I think that could work. Perhaps what we can do is modify
ALLOW_EXPERIMENTAL_FUNCTIONS to set a CFLAGS like:
-DSUPPRESS_EXPERIMENTAL
And use that to toggle the definition on rte_compat.h between something that
deprecates the API call and an empty definition
Neil
> /Bruce
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-11 12:40 ` Neil Horman
@ 2017-12-11 12:45 ` Bruce Richardson
2017-12-11 18:44 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Bruce Richardson @ 2017-12-11 12:45 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, Thomas Monjalon, Mcnamara, John
On Mon, Dec 11, 2017 at 07:40:43AM -0500, Neil Horman wrote:
> On Mon, Dec 11, 2017 at 11:35:57AM +0000, Bruce Richardson wrote:
> > On Fri, Dec 08, 2017 at 12:14:34PM -0500, Neil Horman wrote:
> > > Add checks during build to ensure that all symbols in the EXPERIMENTAL
> > > version map section have __experimental tags on their definitions, and
> > > enable the warnings needed to announce their use. Also add a
> > > ALLOW_EXPERIMENTAL_FUNCTIONS variable check to allow for in-tree dpdk
> > > libraries to override those checks.
> > >
> > > Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> > > CC: Thomas Monjalon <thomas@monjalon.net>
> > > CC: "Mcnamara, John" <john.mcnamara@intel.com>
> > > ---
> >
> > Hi Neil,
> >
> > if I read the patch functionality correctly, the
> > ALLOW_EXPERIMENTAL_FUNCTIONS variable simply suppresses all errors for
> > deprecated functions. However, what we really want is just to suppress
> > the errors for the experimental functions, and not any that really are
> > deprecated. While we may not have any now in DPDK, that doesn't mean it
> > might not be useful to have some in future.
> >
> Well, they are all deprecated by the stict definition of the term, which is to
> say that their usage is discouraged/disapproved. What I think you are saying is
> that you would like to differentiate reasons for deprecation (i.e. deprecation
> because an api is experimental, vs deprecation because an api is broken or going
> to be removed). I'm not sure I see that we will get there anytime soon, but
> yes, that seems like it would be a good ability to add in here.
>
> > Therefore, would an alternative scheme work where the experimental tag
> > is set to empty if the ALLOW_EXPERIMENTAL_FUNCTIONS define is set when
> > compiling?
> >
> Yes, I think that could work. Perhaps what we can do is modify
> ALLOW_EXPERIMENTAL_FUNCTIONS to set a CFLAGS like:
> -DSUPPRESS_EXPERIMENTAL
>
> And use that to toggle the definition on rte_compat.h between something that
> deprecates the API call and an empty definition
>
Yes, exactly what I was thinking, but failed to express so clearly.
Also, would the flag be best set globally when building DPDK itself,
rather than changing individual makefiles per library?
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-11 12:45 ` Bruce Richardson
@ 2017-12-11 18:44 ` Neil Horman
0 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-11 18:44 UTC (permalink / raw)
To: Bruce Richardson; +Cc: dev, Thomas Monjalon, Mcnamara, John
On Mon, Dec 11, 2017 at 12:45:50PM +0000, Bruce Richardson wrote:
> On Mon, Dec 11, 2017 at 07:40:43AM -0500, Neil Horman wrote:
> > On Mon, Dec 11, 2017 at 11:35:57AM +0000, Bruce Richardson wrote:
> > > On Fri, Dec 08, 2017 at 12:14:34PM -0500, Neil Horman wrote:
> > > > Add checks during build to ensure that all symbols in the EXPERIMENTAL
> > > > version map section have __experimental tags on their definitions, and
> > > > enable the warnings needed to announce their use. Also add a
> > > > ALLOW_EXPERIMENTAL_FUNCTIONS variable check to allow for in-tree dpdk
> > > > libraries to override those checks.
> > > >
> > > > Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> > > > CC: Thomas Monjalon <thomas@monjalon.net>
> > > > CC: "Mcnamara, John" <john.mcnamara@intel.com>
> > > > ---
> > >
> > > Hi Neil,
> > >
> > > if I read the patch functionality correctly, the
> > > ALLOW_EXPERIMENTAL_FUNCTIONS variable simply suppresses all errors for
> > > deprecated functions. However, what we really want is just to suppress
> > > the errors for the experimental functions, and not any that really are
> > > deprecated. While we may not have any now in DPDK, that doesn't mean it
> > > might not be useful to have some in future.
> > >
> > Well, they are all deprecated by the stict definition of the term, which is to
> > say that their usage is discouraged/disapproved. What I think you are saying is
> > that you would like to differentiate reasons for deprecation (i.e. deprecation
> > because an api is experimental, vs deprecation because an api is broken or going
> > to be removed). I'm not sure I see that we will get there anytime soon, but
> > yes, that seems like it would be a good ability to add in here.
> >
> > > Therefore, would an alternative scheme work where the experimental tag
> > > is set to empty if the ALLOW_EXPERIMENTAL_FUNCTIONS define is set when
> > > compiling?
> > >
> > Yes, I think that could work. Perhaps what we can do is modify
> > ALLOW_EXPERIMENTAL_FUNCTIONS to set a CFLAGS like:
> > -DSUPPRESS_EXPERIMENTAL
> >
> > And use that to toggle the definition on rte_compat.h between something that
> > deprecates the API call and an empty definition
> >
>
> Yes, exactly what I was thinking, but failed to express so clearly.
>
> Also, would the flag be best set globally when building DPDK itself,
> rather than changing individual makefiles per library?
>
My personal opinion would be that the ability to set allowances on a fine
grained scale would be preferable to a global exception. I say that because I
could envision a new library getting written in which the author would not want
to use experimental APIS and would like the option to catch that during
development. I would like to think that adding -DALLOW_EXPERIMENTAL_APIS to any
new makefile in the DPDK build would be both little enough trouble to do without
irritation, and significant enough of a bump during development as to force the
developer to make a conscious choice about enabling experimental APIS. The idea
here is not to prevent developers from using experimental APIS (especially not
in the core dpdk library, as I noted previously), but to make them consciously
choose to use them, rather than just do so out of hand.
That said, I could be swayed if there was a sufficiently motivating reason to
grant a global exception.
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-01 18:56 [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (4 preceding siblings ...)
2017-12-08 17:14 ` [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
@ 2017-12-11 19:36 ` Neil Horman
2017-12-11 19:36 ` [PATCHv3 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
` (6 more replies)
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
2018-01-22 1:48 ` [PATCH 0/5] " Neil Horman
7 siblings, 7 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-11 19:36 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson
Hey all-
A few days ago, I was lamenting the fact that, when reviewing patches I
would frequently complain about ABI changes that were actually considered safe
because they were part of the EXPERIMENTAL api set. John M. asked me then what
I might do to improve the situation, and the following patch set is a proposal
that I've come up with.
In thinking about the problem I identified two issues that I think we
can improve on in this area:
1) Make experimental api calls more visible in the source code. That is to say,
when reviewing patches, it would be nice to have some sort of visual reference
that indicates that the changes being made are part of an experimental API and
therefore ABI concerns need not be addressed
2) Make experimenal api usage more visible to consumers of the DPDK, so that
they can make a more informed decision about the API's they consume in their
application. We make an effort to document all the experimental API's, but
there is no guarantee that a user will check the documentation before making use
of a new library.
This patch set attempts to achieve both of the above goals. To do this I've
added an __experimental macro tag, suitable for inserting into api forward
declarations and definitions.
The presence of the tag in the header and c files where the api code resides
increases the likelyhood that any patch submitted against them will include the
tag in the context, making it clear to reviewers that ABI stability isn't a
concern here.
Also, This tag marks each function it is used on with an attibute causing any
use of the fuction to emit a warning during the build
with a message indicating that the API call in question is not yet part of the
stable interface. Developers can then make an informed decision to suppress
that warning or not.
Because there is internal use of several experimental API's, this set also
includes a new override macro ALLOW_EXPERIMENTAL_APIS to automatically
suprress these warnings. I think its fair to assume that, for internal use, we
almost always want to suppress these warnings, as by definition any change to
the apis (even their removal) must be done in parallel with an appropriate
change in the calling locations, lest the dpdk build itself break.
Neil
---
Change Notes:
v2)
* Cleaned up checkpatch errors
* Added Allowance for building experimental on BSD
* Swapped Patch 3 and 4 so that we didn't have a commit level that issued
warnings/errors without need
v3)
* On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be defined in
CFLAGS rather than a makefile variable. This is more flexible in that it
allows us to suppress this specific feature rather than all uses of the
deprecated attribute, as we might use it for other features in the furute
^ permalink raw reply [flat|nested] 83+ messages in thread
* [PATCHv3 1/4] buildtools: Add tool to check EXPERIMENTAL api exports
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
@ 2017-12-11 19:36 ` Neil Horman
2017-12-11 19:36 ` [PATCHv3 2/4] compat: Add __experimental macro Neil Horman
` (5 subsequent siblings)
6 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-11 19:36 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson, Neil Horman
This tools reads the given version map for a directory, and checks to
ensure that, for each symbol listed in the export list, the corresponding
definition is tagged as __experimental, erroring out if its not. In this
way, we can ensure that the EXPERIMENTAL api is kept in sync with the tags
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
buildtools/experimentalsyms.sh | 35 +++++++++++++++++++++++++++++++++++
1 file changed, 35 insertions(+)
create mode 100755 buildtools/experimentalsyms.sh
diff --git a/buildtools/experimentalsyms.sh b/buildtools/experimentalsyms.sh
new file mode 100755
index 000000000..7342ec9b3
--- /dev/null
+++ b/buildtools/experimentalsyms.sh
@@ -0,0 +1,35 @@
+#!/bin/sh
+
+MAPFILE=$1
+OBJFILE=$2
+
+if [ -d $MAPFILE ]
+then
+ exit 0
+fi
+
+if [ -d $OBJFILE ]
+then
+ exit 0
+fi
+
+for i in `awk 'BEGIN {found=0}
+ /.*EXPERIMENTAL.*/ {found=1}
+ /.*}.*;/ {found=0}
+ /.*;/ {if (found == 1) print $1}' $MAPFILE`
+do
+ SYM=`echo $i | sed -e"s/;//"`
+ objdump -t $OBJFILE | grep -q "\.text.*$SYM"
+ IN_TEXT=$?
+ objdump -t $OBJFILE | grep -q "\.text\.experimental.*$SYM"
+ IN_EXP=$?
+ if [ $IN_TEXT -eq 0 -a $IN_EXP -ne 0 ]
+ then
+ echo "$SYM is not flagged as experimental"
+ echo "but is listed in version map"
+ echo "Please add __experimental to the definition of $SYM"
+ exit 1
+ fi
+done
+exit 0
+
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv3 2/4] compat: Add __experimental macro
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-11 19:36 ` [PATCHv3 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
@ 2017-12-11 19:36 ` Neil Horman
2017-12-11 19:36 ` [PATCHv3 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
` (4 subsequent siblings)
6 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-11 19:36 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson, Neil Horman
The __experimental macro tags a given exported function as being part of
the EXPERIMENTAL api. Use of this tag will cause any caller of the
function (that isn't removed by dead code elimination) to emit a warning
that the user is making use of an API whos stabilty isn't guaranteed.
It also places the function in the .text.experimental section, which is
used to validate the tag against the corresponding library version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
lib/librte_compat/rte_compat.h | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/lib/librte_compat/rte_compat.h b/lib/librte_compat/rte_compat.h
index 41e8032ba..450dd542c 100644
--- a/lib/librte_compat/rte_compat.h
+++ b/lib/librte_compat/rte_compat.h
@@ -101,5 +101,16 @@
*/
#endif
+#ifndef ALLOW_EXPERIMENTAL_APIS
+#define __experimental \
+__attribute__((deprecated("Symbol is not yet part of stable abi"), \
+section(".text.experimental")))
+
+#else
+
+#define __experimental \
+__attribute__((section(".text.experimental")))
+
+#endif
#endif /* _RTE_COMPAT_H_ */
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv3 3/4] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-11 19:36 ` [PATCHv3 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-11 19:36 ` [PATCHv3 2/4] compat: Add __experimental macro Neil Horman
@ 2017-12-11 19:36 ` Neil Horman
2017-12-11 19:36 ` [PATCHv3 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
` (3 subsequent siblings)
6 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-11 19:36 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson, Neil Horman
Add checks during build to ensure that all symbols in the EXPERIMENTAL
version map section have __experimental tags on their definitions, and
enable the warnings needed to announce their use. Also add an
ALLOW_EXPERIMENTAL_APIS define to allow individual libraries and files
to declare the acceptability of experimental api usage
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
app/test-eventdev/Makefile | 1 +
app/test-pmd/Makefile | 1 +
drivers/event/sw/Makefile | 1 +
drivers/net/failsafe/Makefile | 1 +
drivers/net/ixgbe/Makefile | 1 +
examples/eventdev_pipeline_sw_pmd/Makefile | 1 +
examples/flow_classify/Makefile | 1 +
examples/ipsec-secgw/Makefile | 1 +
examples/service_cores/Makefile | 1 +
lib/librte_eal/bsdapp/eal/Makefile | 1 +
lib/librte_eal/linuxapp/Makefile | 2 ++
lib/librte_eal/linuxapp/eal/Makefile | 2 ++
lib/librte_eventdev/Makefile | 1 +
lib/librte_security/Makefile | 1 +
mk/internal/rte.compile-pre.mk | 4 ++++
mk/toolchain/clang/rte.vars.mk | 2 +-
mk/toolchain/gcc/rte.vars.mk | 2 +-
mk/toolchain/icc/rte.vars.mk | 2 +-
18 files changed, 23 insertions(+), 3 deletions(-)
diff --git a/app/test-eventdev/Makefile b/app/test-eventdev/Makefile
index dcb2ac476..78bae7633 100644
--- a/app/test-eventdev/Makefile
+++ b/app/test-eventdev/Makefile
@@ -32,6 +32,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
APP = dpdk-test-eventdev
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/app/test-pmd/Makefile b/app/test-pmd/Makefile
index d21308fcd..23f9ddb86 100644
--- a/app/test-pmd/Makefile
+++ b/app/test-pmd/Makefile
@@ -38,6 +38,7 @@ ifeq ($(CONFIG_RTE_TEST_PMD),y)
#
APP = testpmd
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/drivers/event/sw/Makefile b/drivers/event/sw/Makefile
index 2f2b67bac..e54477ec5 100644
--- a/drivers/event/sw/Makefile
+++ b/drivers/event/sw/Makefile
@@ -34,6 +34,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
LIB = librte_pmd_sw_event.a
# build flags
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
# for older GCC versions, allow us to initialize an event using
diff --git a/drivers/net/failsafe/Makefile b/drivers/net/failsafe/Makefile
index ea2a8fe46..29f1f0ff2 100644
--- a/drivers/net/failsafe/Makefile
+++ b/drivers/net/failsafe/Makefile
@@ -50,6 +50,7 @@ SRCS-$(CONFIG_RTE_LIBRTE_PMD_FAILSAFE) += failsafe_flow.c
# No exported include files
# Basic CFLAGS:
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -std=gnu99 -Wextra
CFLAGS += -O3
CFLAGS += -I.
diff --git a/drivers/net/ixgbe/Makefile b/drivers/net/ixgbe/Makefile
index 511a64eb0..c1cf226f1 100644
--- a/drivers/net/ixgbe/Makefile
+++ b/drivers/net/ixgbe/Makefile
@@ -36,6 +36,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
#
LIB = librte_pmd_ixgbe.a
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/eventdev_pipeline_sw_pmd/Makefile b/examples/eventdev_pipeline_sw_pmd/Makefile
index de4e22c88..dc54b0df2 100644
--- a/examples/eventdev_pipeline_sw_pmd/Makefile
+++ b/examples/eventdev_pipeline_sw_pmd/Makefile
@@ -43,6 +43,7 @@ APP = eventdev_pipeline_sw_pmd
# all source are stored in SRCS-y
SRCS-y := main.c
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/flow_classify/Makefile b/examples/flow_classify/Makefile
index eecdde14c..905a11cef 100644
--- a/examples/flow_classify/Makefile
+++ b/examples/flow_classify/Makefile
@@ -45,6 +45,7 @@ APP = flow_classify
# all source are stored in SRCS-y
SRCS-y := flow_classify.c
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/ipsec-secgw/Makefile b/examples/ipsec-secgw/Makefile
index 9fd33cb7f..84ba9fd29 100644
--- a/examples/ipsec-secgw/Makefile
+++ b/examples/ipsec-secgw/Makefile
@@ -46,6 +46,7 @@ endif
APP = ipsec-secgw
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3 -gdwarf-2
CFLAGS += $(WERROR_FLAGS)
ifeq ($(CONFIG_RTE_TOOLCHAIN_ICC),y)
diff --git a/examples/service_cores/Makefile b/examples/service_cores/Makefile
index bd4a345dc..1f0448e27 100644
--- a/examples/service_cores/Makefile
+++ b/examples/service_cores/Makefile
@@ -43,6 +43,7 @@ APP = service_cores
# all source are stored in SRCS-y
SRCS-y := main.c
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += $(WERROR_FLAGS)
# workaround for a gcc bug with noreturn attribute
diff --git a/lib/librte_eal/bsdapp/eal/Makefile b/lib/librte_eal/bsdapp/eal/Makefile
index afa117de4..ed595f104 100644
--- a/lib/librte_eal/bsdapp/eal/Makefile
+++ b/lib/librte_eal/bsdapp/eal/Makefile
@@ -37,6 +37,7 @@ ARCH_DIR ?= $(RTE_ARCH)
VPATH += $(RTE_SDK)/lib/librte_eal/common
VPATH += $(RTE_SDK)/lib/librte_eal/common/arch/$(ARCH_DIR)
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -I$(SRCDIR)/include
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common/include
diff --git a/lib/librte_eal/linuxapp/Makefile b/lib/librte_eal/linuxapp/Makefile
index 2ebdf3139..37367fc88 100644
--- a/lib/librte_eal/linuxapp/Makefile
+++ b/lib/librte_eal/linuxapp/Makefile
@@ -36,4 +36,6 @@ DIRS-$(CONFIG_RTE_EAL_IGB_UIO) += igb_uio
DIRS-$(CONFIG_RTE_KNI_KMOD) += kni
DEPDIRS-kni := eal
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
+
include $(RTE_SDK)/mk/rte.subdir.mk
diff --git a/lib/librte_eal/linuxapp/eal/Makefile b/lib/librte_eal/linuxapp/eal/Makefile
index 5a7b8b2ac..ec810d92b 100644
--- a/lib/librte_eal/linuxapp/eal/Makefile
+++ b/lib/librte_eal/linuxapp/eal/Makefile
@@ -34,6 +34,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
LIB = librte_eal.a
ARCH_DIR ?= $(RTE_ARCH)
+
EXPORT_MAP := ../../rte_eal_version.map
VPATH += $(RTE_SDK)/lib/librte_eal/common/arch/$(ARCH_DIR)
@@ -41,6 +42,7 @@ LIBABIVER := 6
VPATH += $(RTE_SDK)/lib/librte_eal/common
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -I$(SRCDIR)/include
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common/include
diff --git a/lib/librte_eventdev/Makefile b/lib/librte_eventdev/Makefile
index 5ac22cde7..96afc3be8 100644
--- a/lib/librte_eventdev/Makefile
+++ b/lib/librte_eventdev/Makefile
@@ -37,6 +37,7 @@ LIB = librte_eventdev.a
LIBABIVER := 3
# build flags
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
LDLIBS += -lrte_eal -lrte_ring -lrte_ethdev -lrte_hash
diff --git a/lib/librte_security/Makefile b/lib/librte_security/Makefile
index bb93ec33d..d433937a5 100644
--- a/lib/librte_security/Makefile
+++ b/lib/librte_security/Makefile
@@ -37,6 +37,7 @@ LIB = librte_security.a
LIBABIVER := 1
# build flags
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
LDLIBS += -lrte_eal -lrte_mempool
diff --git a/mk/internal/rte.compile-pre.mk b/mk/internal/rte.compile-pre.mk
index da8dda498..83a53c202 100644
--- a/mk/internal/rte.compile-pre.mk
+++ b/mk/internal/rte.compile-pre.mk
@@ -84,6 +84,9 @@ C_TO_O = $(CC) -Wp,-MD,$(call obj2dep,$(@)).tmp $(CPPFLAGS) $(CFLAGS) \
C_TO_O_STR = $(subst ','\'',$(C_TO_O)) #'# fix syntax highlight
C_TO_O_DISP = $(if $(V),"$(C_TO_O_STR)"," CC $(@)")
endif
+EXPERIMENTAL_CHECK = $(RTE_SDK)/buildtools/experimentalsyms.sh
+CHECK_EXPERIMENTAL = $(EXPERIMENTAL_CHECK) $(SRCDIR)/$(EXPORT_MAP) $@
+
PMDINFO_GEN = $(RTE_SDK_BIN)/app/dpdk-pmdinfogen $@ $@.pmd.c
PMDINFO_CC = $(CC) $(CPPFLAGS) $(CFLAGS) -c -o $@.pmd.o $@.pmd.c
PMDINFO_LD = $(CROSS)ld $(LDFLAGS) -r -o $@.o $@.pmd.o $@
@@ -100,6 +103,7 @@ C_TO_O_DO = @set -e; \
echo $(C_TO_O_DISP); \
$(C_TO_O) && \
$(PMDINFO_TO_O) && \
+ $(CHECK_EXPERIMENTAL) && \
echo $(C_TO_O_CMD) > $(call obj2cmd,$(@)) && \
sed 's,'$@':,dep_'$@' =,' $(call obj2dep,$(@)).tmp > $(call obj2dep,$(@)) && \
rm -f $(call obj2dep,$(@)).tmp
diff --git a/mk/toolchain/clang/rte.vars.mk b/mk/toolchain/clang/rte.vars.mk
index dde922d22..3cfe92545 100644
--- a/mk/toolchain/clang/rte.vars.mk
+++ b/mk/toolchain/clang/rte.vars.mk
@@ -67,7 +67,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/gcc/rte.vars.mk b/mk/toolchain/gcc/rte.vars.mk
index 3b907e201..3356a37c8 100644
--- a/mk/toolchain/gcc/rte.vars.mk
+++ b/mk/toolchain/gcc/rte.vars.mk
@@ -75,7 +75,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wcast-align -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/icc/rte.vars.mk b/mk/toolchain/icc/rte.vars.mk
index 33a8ba79e..58940602e 100644
--- a/mk/toolchain/icc/rte.vars.mk
+++ b/mk/toolchain/icc/rte.vars.mk
@@ -73,7 +73,7 @@ TOOLCHAIN_ASFLAGS =
WERROR_FLAGS := -Wall -w2 -diag-disable 271 -diag-warning 1478
WERROR_FLAGS += -diag-disable 13368 -diag-disable 15527
WERROR_FLAGS += -diag-disable 188
-WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076
+WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076 -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror-all
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv3 4/4] dpdk: add __experimental tag to appropriate api calls
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (2 preceding siblings ...)
2017-12-11 19:36 ` [PATCHv3 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
@ 2017-12-11 19:36 ` Neil Horman
2017-12-12 14:07 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
` (2 subsequent siblings)
6 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-11 19:36 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson, Neil Horman
Append the __experimental tag to api calls appearing in the EXPERIMENTAL
section of their libraries version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
lib/librte_eal/common/eal_common_dev.c | 6 ++-
lib/librte_eal/common/eal_common_devargs.c | 7 +--
lib/librte_eal/common/include/rte_dev.h | 6 ++-
lib/librte_eal/common/include/rte_devargs.h | 8 ++--
lib/librte_eal/common/include/rte_service.h | 47 ++++++++++---------
.../common/include/rte_service_component.h | 14 +++---
lib/librte_eal/common/rte_service.c | 52 ++++++++++++----------
lib/librte_eal/linuxapp/eal/eal.c | 1 +
lib/librte_ether/rte_mtr.c | 25 ++++++-----
lib/librte_ether/rte_mtr.h | 26 +++++------
lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
lib/librte_security/rte_security.c | 16 +++----
lib/librte_security/rte_security.h | 23 +++++-----
14 files changed, 139 insertions(+), 116 deletions(-)
diff --git a/lib/librte_eal/common/eal_common_dev.c b/lib/librte_eal/common/eal_common_dev.c
index dda8f5835..ee866ddd2 100644
--- a/lib/librte_eal/common/eal_common_dev.c
+++ b/lib/librte_eal/common/eal_common_dev.c
@@ -37,6 +37,7 @@
#include <inttypes.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
#include <rte_dev.h>
#include <rte_devargs.h>
@@ -133,7 +134,7 @@ full_dev_name(const char *bus, const char *dev, const char *args)
return name;
}
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs)
{
struct rte_bus *bus;
@@ -203,7 +204,8 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
return ret;
}
-int rte_eal_hotplug_remove(const char *busname, const char *devname)
+int __experimental
+rte_eal_hotplug_remove(const char *busname, const char *devname)
{
struct rte_bus *bus;
struct rte_device *dev;
diff --git a/lib/librte_eal/common/eal_common_devargs.c b/lib/librte_eal/common/eal_common_devargs.c
index 6ac88d6ab..8e46d54bd 100644
--- a/lib/librte_eal/common/eal_common_devargs.c
+++ b/lib/librte_eal/common/eal_common_devargs.c
@@ -40,6 +40,7 @@
#include <stdio.h>
#include <string.h>
+#include <rte_compat.h>
#include <rte_dev.h>
#include <rte_devargs.h>
#include <rte_tailq.h>
@@ -85,7 +86,7 @@ bus_name_cmp(const struct rte_bus *bus, const void *name)
return strncmp(bus->name, name, strlen(bus->name));
}
-int
+int __experimental
rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
{
struct rte_bus *bus = NULL;
@@ -139,7 +140,7 @@ rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
return 0;
}
-int
+int __experimental
rte_eal_devargs_insert(struct rte_devargs *da)
{
int ret;
@@ -188,7 +189,7 @@ rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str)
return -1;
}
-int
+int __experimental
rte_eal_devargs_remove(const char *busname, const char *devname)
{
struct rte_devargs *d;
diff --git a/lib/librte_eal/common/include/rte_dev.h b/lib/librte_eal/common/include/rte_dev.h
index 9342e0cbd..ddb0a09a7 100644
--- a/lib/librte_eal/common/include/rte_dev.h
+++ b/lib/librte_eal/common/include/rte_dev.h
@@ -49,6 +49,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_log.h>
__attribute__((format(printf, 2, 0)))
@@ -209,7 +210,7 @@ int rte_eal_dev_detach(struct rte_device *dev);
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs);
/**
@@ -225,7 +226,8 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_remove(const char *busname, const char *devname);
+int __experimental rte_eal_hotplug_remove(const char *busname,
+ const char *devname);
/**
* Device comparison function.
diff --git a/lib/librte_eal/common/include/rte_devargs.h b/lib/librte_eal/common/include/rte_devargs.h
index 58d585df6..e4c10b6c5 100644
--- a/lib/librte_eal/common/include/rte_devargs.h
+++ b/lib/librte_eal/common/include/rte_devargs.h
@@ -50,6 +50,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
/**
@@ -136,7 +137,7 @@ int rte_eal_parse_devargs_str(const char *devargs_str,
* - 0 on success.
* - Negative errno on error.
*/
-int
+int __experimental
rte_eal_devargs_parse(const char *dev,
struct rte_devargs *da);
@@ -150,7 +151,7 @@ rte_eal_devargs_parse(const char *dev,
* - 0 on success
* - Negative on error.
*/
-int
+int __experimental
rte_eal_devargs_insert(struct rte_devargs *da);
/**
@@ -193,7 +194,8 @@ int rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str);
* <0 on error.
* >0 if the devargs was not within the user device list.
*/
-int rte_eal_devargs_remove(const char *busname, const char *devname);
+int __experimental rte_eal_devargs_remove(const char *busname,
+ const char *devname);
/**
* Count the number of user devices of a specified type
diff --git a/lib/librte_eal/common/include/rte_service.h b/lib/librte_eal/common/include/rte_service.h
index 927244065..da10d17ea 100644
--- a/lib/librte_eal/common/include/rte_service.h
+++ b/lib/librte_eal/common/include/rte_service.h
@@ -84,7 +84,7 @@ extern "C" {
*
* @return The number of services registered.
*/
-uint32_t rte_service_get_count(void);
+uint32_t __experimental rte_service_get_count(void);
/**
* @warning
@@ -111,7 +111,8 @@ uint32_t rte_service_get_count(void);
* @retval -EINVAL Null *service_id* pointer provided
* @retval -ENODEV No such service registered
*/
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
+int32_t __experimental rte_service_get_by_name(const char *name,
+ uint32_t *service_id);
/**
* @warning
@@ -122,7 +123,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
* @return A pointer to the name of the service. The returned pointer remains
* in ownership of the service, and the application must not free it.
*/
-const char *rte_service_get_name(uint32_t id);
+const char __experimental *rte_service_get_name(uint32_t id);
/**
* @warning
@@ -135,7 +136,8 @@ const char *rte_service_get_name(uint32_t id);
* @retval 1 Capability supported by this service instance
* @retval 0 Capability not supported by this service instance
*/
-int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
+int32_t __experimental rte_service_probe_capability(uint32_t id,
+ uint32_t capability);
/**
* @warning
@@ -159,8 +161,8 @@ int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
* @retval 0 lcore map updated successfully
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
- uint32_t enable);
+int32_t __experimental rte_service_map_lcore_set(uint32_t service_id,
+ uint32_t lcore, uint32_t enable);
/**
* @warning
@@ -175,7 +177,8 @@ int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
* @retval 0 lcore is not mapped to service
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
+int32_t __experimental rte_service_map_lcore_get(uint32_t service_id,
+ uint32_t lcore);
/**
* @warning
@@ -192,7 +195,7 @@ int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
* @retval 0 The service was successfully started
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __experimental rte_service_runstate_set(uint32_t id, uint32_t runstate);
/**
* @warning
@@ -210,7 +213,7 @@ int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
* @retval 0 Service is stopped
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_get(uint32_t id);
+int32_t __experimental rte_service_runstate_get(uint32_t id);
/**
* @warning
@@ -226,7 +229,8 @@ int32_t rte_service_runstate_get(uint32_t id);
* @retval 0 Success
* @retval -EINVAL Invalid service ID
*/
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
+int32_t __experimental rte_service_set_runstate_mapped_check(uint32_t id,
+ int32_t enable);
/**
* @warning
@@ -264,7 +268,7 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
* @retval -ENOEXEC Service is not in a run-able state
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_multithread_unsafe);
/**
@@ -280,7 +284,7 @@ int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
* @retval -EINVAL Failed to start core. The *lcore_id* passed in is not
* currently assigned to be a service core.
*/
-int32_t rte_service_lcore_start(uint32_t lcore_id);
+int32_t __experimental rte_service_lcore_start(uint32_t lcore_id);
/**
* @warning
@@ -299,7 +303,7 @@ int32_t rte_service_lcore_start(uint32_t lcore_id);
* The application must stop the service first, and then stop the
* lcore.
*/
-int32_t rte_service_lcore_stop(uint32_t lcore_id);
+int32_t __experimental rte_service_lcore_stop(uint32_t lcore_id);
/**
* @warning
@@ -315,7 +319,7 @@ int32_t rte_service_lcore_stop(uint32_t lcore_id);
* @retval -EALREADY lcore is already added to the service core list
* @retval -EINVAL Invalid lcore provided
*/
-int32_t rte_service_lcore_add(uint32_t lcore);
+int32_t __experimental rte_service_lcore_add(uint32_t lcore);
/**
* @warning
@@ -329,7 +333,7 @@ int32_t rte_service_lcore_add(uint32_t lcore);
* @retval -EBUSY Lcore is not stopped, stop service core before removing.
* @retval -EINVAL failed to add lcore to service core mask.
*/
-int32_t rte_service_lcore_del(uint32_t lcore);
+int32_t __experimental rte_service_lcore_del(uint32_t lcore);
/**
* @warning
@@ -346,7 +350,7 @@ int32_t rte_service_lcore_del(uint32_t lcore);
*
* @return The number of service cores currently configured.
*/
-int32_t rte_service_lcore_count(void);
+int32_t __experimental rte_service_lcore_count(void);
/**
* @warning
@@ -358,7 +362,7 @@ int32_t rte_service_lcore_count(void);
*
* @retval 0 Success
*/
-int32_t rte_service_lcore_reset_all(void);
+int32_t __experimental rte_service_lcore_reset_all(void);
/**
* @warning
@@ -372,7 +376,8 @@ int32_t rte_service_lcore_reset_all(void);
* @retval 0 Success
* @retval -EINVAL Invalid service pointer passed
*/
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
+int32_t __experimental rte_service_set_stats_enable(uint32_t id,
+ int32_t enable);
/**
* @warning
@@ -393,7 +398,7 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
* service core list. No items have been populated, call this function
* with a size of at least *rte_service_core_count* items.
*/
-int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
+int32_t __experimental rte_service_lcore_list(uint32_t array[], uint32_t n);
/**
* @warning
@@ -406,7 +411,7 @@ int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
* @retval -EINVAL Invalid lcore provided
* @retval -ENOTSUP The provided lcore is not a service core.
*/
-int32_t rte_service_lcore_count_services(uint32_t lcore);
+int32_t __experimental rte_service_lcore_count_services(uint32_t lcore);
/**
* @warning
@@ -418,7 +423,7 @@ int32_t rte_service_lcore_count_services(uint32_t lcore);
* @retval 0 Statistics have been successfully dumped
* @retval -EINVAL Invalid service id provided
*/
-int32_t rte_service_dump(FILE *f, uint32_t id);
+int32_t __experimental rte_service_dump(FILE *f, uint32_t id);
#ifdef __cplusplus
}
diff --git a/lib/librte_eal/common/include/rte_service_component.h b/lib/librte_eal/common/include/rte_service_component.h
index ac965cb48..a129258eb 100644
--- a/lib/librte_eal/common/include/rte_service_component.h
+++ b/lib/librte_eal/common/include/rte_service_component.h
@@ -37,7 +37,7 @@
* Include this file if you are writing a component that requires CPU cycles to
* operate, and you wish to run the component using service cores
*/
-
+#include <rte_compat.h>
#include <rte_service.h>
/**
@@ -101,8 +101,9 @@ struct rte_service_spec {
* -EINVAL Attempted to register an invalid service (eg, no callback
* set)
*/
-int32_t rte_service_component_register(const struct rte_service_spec *spec,
- uint32_t *service_id);
+int32_t __experimental
+rte_service_component_register(const struct rte_service_spec *spec,
+ uint32_t *service_id);
/**
* @warning
@@ -116,7 +117,7 @@ int32_t rte_service_component_register(const struct rte_service_spec *spec,
* @retval -EBUSY The service is currently running, stop the service before
* calling unregister. No action has been taken.
*/
-int32_t rte_service_component_unregister(uint32_t id);
+int32_t __experimental rte_service_component_unregister(uint32_t id);
/**
* @warning
@@ -134,7 +135,7 @@ int32_t rte_service_component_unregister(uint32_t id);
* @retval -ENODEV Error in enabling service lcore on a service
* @retval -ENOEXEC Error when starting services
*/
-int32_t rte_service_start_with_defaults(void);
+int32_t __experimental rte_service_start_with_defaults(void);
/**
* @warning
@@ -151,7 +152,8 @@ int32_t rte_service_start_with_defaults(void);
*
* @retval 0 Success
*/
-int32_t rte_service_component_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __experimental rte_service_component_runstate_set(uint32_t id,
+ uint32_t runstate);
/**
* @warning
diff --git a/lib/librte_eal/common/rte_service.c b/lib/librte_eal/common/rte_service.c
index ae97e6b7f..178354323 100644
--- a/lib/librte_eal/common/rte_service.c
+++ b/lib/librte_eal/common/rte_service.c
@@ -38,6 +38,7 @@
#include <string.h>
#include <dirent.h>
+#include <rte_compat.h>
#include <rte_service.h>
#include "include/rte_service_component.h"
@@ -168,7 +169,8 @@ service_mt_safe(struct rte_service_spec_impl *s)
return !!(s->spec.capabilities & RTE_SERVICE_CAP_MT_SAFE);
}
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
+int32_t __experimental
+rte_service_set_stats_enable(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -181,7 +183,8 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
return 0;
}
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
+int32_t __experimental
+rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -194,13 +197,14 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
return 0;
}
-uint32_t
+uint32_t __experimental
rte_service_get_count(void)
{
return rte_service_count;
}
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
+int32_t __experimental
+rte_service_get_by_name(const char *name, uint32_t *service_id)
{
if (!service_id)
return -EINVAL;
@@ -217,7 +221,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
return -ENODEV;
}
-const char *
+const char * __experimental
rte_service_get_name(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -225,7 +229,7 @@ rte_service_get_name(uint32_t id)
return s->spec.name;
}
-int32_t
+int32_t __experimental
rte_service_probe_capability(uint32_t id, uint32_t capability)
{
struct rte_service_spec_impl *s;
@@ -233,7 +237,7 @@ rte_service_probe_capability(uint32_t id, uint32_t capability)
return !!(s->spec.capabilities & capability);
}
-int32_t
+int32_t __experimental
rte_service_component_register(const struct rte_service_spec *spec,
uint32_t *id_ptr)
{
@@ -266,7 +270,7 @@ rte_service_component_register(const struct rte_service_spec *spec,
return 0;
}
-int32_t
+int32_t __experimental
rte_service_component_unregister(uint32_t id)
{
uint32_t i;
@@ -287,7 +291,7 @@ rte_service_component_unregister(uint32_t id)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -302,7 +306,7 @@ rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -317,7 +321,7 @@ rte_service_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_runstate_get(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -378,7 +382,7 @@ service_run(uint32_t i, struct core_state *cs, uint64_t service_mask)
return 0;
}
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_mt_unsafe)
{
/* run service on calling core, using all-ones as the service mask */
@@ -434,7 +438,7 @@ rte_service_runner_func(void *arg)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_lcore_count(void)
{
int32_t count = 0;
@@ -444,7 +448,7 @@ rte_service_lcore_count(void)
return count;
}
-int32_t
+int32_t __experimental
rte_service_lcore_list(uint32_t array[], uint32_t n)
{
uint32_t count = rte_service_lcore_count();
@@ -467,7 +471,7 @@ rte_service_lcore_list(uint32_t array[], uint32_t n)
return count;
}
-int32_t
+int32_t __experimental
rte_service_lcore_count_services(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -480,7 +484,7 @@ rte_service_lcore_count_services(uint32_t lcore)
return __builtin_popcountll(cs->service_mask);
}
-int32_t
+int32_t __experimental
rte_service_start_with_defaults(void)
{
/* create a default mapping from cores to services, then start the
@@ -562,7 +566,7 @@ service_update(struct rte_service_spec *service, uint32_t lcore,
return 0;
}
-int32_t
+int32_t __experimental
rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
{
struct rte_service_spec_impl *s;
@@ -571,7 +575,7 @@ rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
return service_update(&s->spec, lcore, &on, 0);
}
-int32_t
+int32_t __experimental
rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
{
struct rte_service_spec_impl *s;
@@ -583,7 +587,7 @@ rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
return ret;
}
-int32_t rte_service_lcore_reset_all(void)
+int32_t __experimental rte_service_lcore_reset_all(void)
{
/* loop over cores, reset all to mask 0 */
uint32_t i;
@@ -614,7 +618,7 @@ set_lcore_state(uint32_t lcore, int32_t state)
lcore_states[lcore].is_service_core = (state == ROLE_SERVICE);
}
-int32_t
+int32_t __experimental
rte_service_lcore_add(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -633,7 +637,7 @@ rte_service_lcore_add(uint32_t lcore)
return rte_eal_wait_lcore(lcore);
}
-int32_t
+int32_t __experimental
rte_service_lcore_del(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -652,7 +656,7 @@ rte_service_lcore_del(uint32_t lcore)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_lcore_start(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -675,7 +679,7 @@ rte_service_lcore_start(uint32_t lcore)
return ret;
}
-int32_t
+int32_t __experimental
rte_service_lcore_stop(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -745,7 +749,7 @@ service_dump_calls_per_lcore(FILE *f, uint32_t lcore, uint32_t reset)
fprintf(f, "\n");
}
-int32_t rte_service_dump(FILE *f, uint32_t id)
+int32_t __experimental rte_service_dump(FILE *f, uint32_t id)
{
uint32_t i;
int print_one = (id != UINT32_MAX);
diff --git a/lib/librte_eal/linuxapp/eal/eal.c b/lib/librte_eal/linuxapp/eal/eal.c
index 229eec9f1..73a0da22c 100644
--- a/lib/librte_eal/linuxapp/eal/eal.c
+++ b/lib/librte_eal/linuxapp/eal/eal.c
@@ -53,6 +53,7 @@
#include <sys/io.h>
#endif
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_debug.h>
#include <rte_memory.h>
diff --git a/lib/librte_ether/rte_mtr.c b/lib/librte_ether/rte_mtr.c
index 4f56f8714..2cbe0bb5a 100644
--- a/lib/librte_ether/rte_mtr.c
+++ b/lib/librte_ether/rte_mtr.c
@@ -34,6 +34,7 @@
#include <stdint.h>
#include <rte_errno.h>
+#include "rte_compat.h"
#include "rte_ethdev.h"
#include "rte_mtr_driver.h"
#include "rte_mtr.h"
@@ -86,7 +87,7 @@ rte_mtr_ops_get(uint16_t port_id, struct rte_mtr_error *error)
})
/* MTR capabilities get */
-int
+int __experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error)
@@ -97,7 +98,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
}
/* MTR meter profile add */
-int
+int __experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -109,7 +110,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
}
/** MTR meter profile delete */
-int
+int __experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error)
@@ -120,7 +121,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
}
/** MTR object create */
-int
+int __experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -133,7 +134,7 @@ rte_mtr_create(uint16_t port_id,
}
/** MTR object destroy */
-int
+int __experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -144,7 +145,7 @@ rte_mtr_destroy(uint16_t port_id,
}
/** MTR object meter enable */
-int
+int __experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -155,7 +156,7 @@ rte_mtr_meter_enable(uint16_t port_id,
}
/** MTR object meter disable */
-int
+int __experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -166,7 +167,7 @@ rte_mtr_meter_disable(uint16_t port_id,
}
/** MTR object meter profile update */
-int
+int __experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -178,7 +179,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
}
/** MTR object meter DSCP table update */
-int
+int __experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -190,7 +191,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
}
/** MTR object policer action update */
-int
+int __experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -203,7 +204,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
}
/** MTR object enabled stats update */
-int
+int __experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -215,7 +216,7 @@ rte_mtr_stats_update(uint16_t port_id,
}
/** MTR object stats read */
-int
+int __experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_ether/rte_mtr.h b/lib/librte_ether/rte_mtr.h
index f6b6ef3b6..fd8361998 100644
--- a/lib/librte_ether/rte_mtr.h
+++ b/lib/librte_ether/rte_mtr.h
@@ -74,7 +74,7 @@
* @b EXPERIMENTAL: this API may change without prior notice
*/
#include <stdint.h>
-
+#include <rte_compat.h>
#include <rte_common.h>
#ifdef __cplusplus
@@ -447,7 +447,7 @@ struct rte_mtr_error {
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error);
@@ -470,7 +470,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -491,7 +491,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error);
@@ -519,7 +519,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
*
* @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
*/
-int
+int __experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -542,7 +542,7 @@ rte_mtr_create(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -569,7 +569,7 @@ rte_mtr_destroy(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -590,7 +590,7 @@ rte_mtr_meter_disable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -609,7 +609,7 @@ rte_mtr_meter_enable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -633,7 +633,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -659,7 +659,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -684,7 +684,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -715,7 +715,7 @@ rte_mtr_stats_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_flow_classify/rte_flow_classify.c b/lib/librte_flow_classify/rte_flow_classify.c
index e6f448643..6716672fc 100644
--- a/lib/librte_flow_classify/rte_flow_classify.c
+++ b/lib/librte_flow_classify/rte_flow_classify.c
@@ -31,6 +31,7 @@
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+#include <rte_compat.h>
#include <rte_flow_classify.h>
#include "rte_flow_classify_parse.h"
#include <rte_flow_driver.h>
@@ -245,7 +246,7 @@ rte_flow_classifier_check_params(struct rte_flow_classifier_params *params)
return 0;
}
-struct rte_flow_classifier *
+struct rte_flow_classifier * __experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params)
{
struct rte_flow_classifier *cls;
@@ -291,7 +292,7 @@ rte_flow_classify_table_free(struct rte_table *table)
table->ops.f_free(table->h_table);
}
-int
+int __experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls)
{
uint32_t i;
@@ -369,7 +370,7 @@ rte_table_check_params(struct rte_flow_classifier *cls,
return 0;
}
-int
+int __experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id)
@@ -483,7 +484,7 @@ allocate_acl_ipv4_5tuple_rule(void)
return rule;
}
-struct rte_flow_classify_rule *
+struct rte_flow_classify_rule * __experimental
rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
uint32_t table_id,
int *key_found,
@@ -582,7 +583,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
return rule;
}
-int
+int __experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule)
@@ -659,7 +660,7 @@ action_apply(struct rte_flow_classifier *cls,
return ret;
}
-int
+int __experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_flow_classify/rte_flow_classify.h b/lib/librte_flow_classify/rte_flow_classify.h
index 1211873a1..cd9516f9e 100644
--- a/lib/librte_flow_classify/rte_flow_classify.h
+++ b/lib/librte_flow_classify/rte_flow_classify.h
@@ -70,6 +70,7 @@
* with rte_flow_classifier_free()
*/
+#include <rte_compat.h>
#include <rte_ethdev.h>
#include <rte_ether.h>
#include <rte_flow.h>
@@ -176,7 +177,7 @@ struct rte_flow_classify_ipv4_5tuple_stats {
* @return
* Handle to flow classifier instance on success or NULL otherwise
*/
-struct rte_flow_classifier *
+struct rte_flow_classifier * __experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params);
/**
@@ -187,7 +188,7 @@ rte_flow_classifier_create(struct rte_flow_classifier_params *params);
* @return
* 0 on success, error code otherwise
*/
-int
+int __experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls);
/**
@@ -203,7 +204,7 @@ rte_flow_classifier_free(struct rte_flow_classifier *cls);
* @return
* 0 on success, error code otherwise
*/
-int
+int __experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id);
@@ -250,7 +251,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule);
@@ -274,7 +275,7 @@ rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_security/rte_security.c b/lib/librte_security/rte_security.c
index 1227fca8a..958b7273e 100644
--- a/lib/librte_security/rte_security.c
+++ b/lib/librte_security/rte_security.c
@@ -33,12 +33,12 @@
#include <rte_malloc.h>
#include <rte_dev.h>
-
+#include "rte_compat.h"
#include "rte_security.h"
#include "rte_security_driver.h"
struct rte_security_session *
-rte_security_session_create(struct rte_security_ctx *instance,
+__experimental rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp)
{
@@ -61,7 +61,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
return sess;
}
-int
+int __experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf)
@@ -70,7 +70,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
return instance->ops->session_update(instance->device, sess, conf);
}
-int
+int __experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats)
@@ -79,7 +79,7 @@ rte_security_session_stats_get(struct rte_security_ctx *instance,
return instance->ops->session_stats_get(instance->device, sess, stats);
}
-int
+int __experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess)
{
@@ -98,7 +98,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
return ret;
}
-int
+int __experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *m, void *params)
@@ -108,14 +108,14 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
sess, m, params);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capabilities_get(struct rte_security_ctx *instance)
{
RTE_FUNC_PTR_OR_ERR_RET(*instance->ops->capabilities_get, NULL);
return instance->ops->capabilities_get(instance->device);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx)
{
diff --git a/lib/librte_security/rte_security.h b/lib/librte_security/rte_security.h
index 653929b99..176378e78 100644
--- a/lib/librte_security/rte_security.h
+++ b/lib/librte_security/rte_security.h
@@ -52,6 +52,7 @@ extern "C" {
#include <netinet/ip.h>
#include <netinet/ip6.h>
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_crypto.h>
#include <rte_mbuf.h>
@@ -291,7 +292,7 @@ struct rte_security_session {
* - On success, pointer to session
* - On failure, NULL
*/
-struct rte_security_session *
+struct rte_security_session * __experimental
rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp);
@@ -306,7 +307,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
* - On success returns 0
* - On failure return errno
*/
-int
+int __experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf);
@@ -323,7 +324,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
* - -EINVAL if session is NULL.
* - -EBUSY if not all device private data has been freed.
*/
-int
+int __experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess);
@@ -340,7 +341,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
* - On success, zero.
* - On failure, a negative value.
*/
-int
+int __experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *mb, void *params);
@@ -351,7 +352,7 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
* @param sym_op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __experimental
__rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
struct rte_security_session *sess)
{
@@ -360,13 +361,13 @@ __rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
return 0;
}
-static inline void *
+static inline void * __experimental
get_sec_session_private_data(const struct rte_security_session *sess)
{
return sess->sess_private_data;
}
-static inline void
+static inline void __experimental
set_sec_session_private_data(struct rte_security_session *sess,
void *private_data)
{
@@ -382,7 +383,7 @@ set_sec_session_private_data(struct rte_security_session *sess,
* @param op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __experimental
rte_security_attach_session(struct rte_crypto_op *op,
struct rte_security_session *sess)
{
@@ -424,7 +425,7 @@ struct rte_security_stats {
* - On success return 0
* - On failure errno
*/
-int
+int __experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats);
@@ -507,7 +508,7 @@ struct rte_security_capability_idx {
* - Returns array of security capabilities.
* - Return NULL if no capabilities available.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capabilities_get(struct rte_security_ctx *instance);
/**
@@ -521,7 +522,7 @@ rte_security_capabilities_get(struct rte_security_ctx *instance);
* index criteria.
* - Return NULL if the capability not matched on security instance.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx);
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (3 preceding siblings ...)
2017-12-11 19:36 ` [PATCHv3 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
@ 2017-12-12 14:07 ` Bruce Richardson
2017-12-30 17:15 ` Neil Horman
2017-12-12 14:33 ` Mcnamara, John
2017-12-12 15:11 ` Wiles, Keith
6 siblings, 1 reply; 83+ messages in thread
From: Bruce Richardson @ 2017-12-12 14:07 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, thomas, john.mcnamara
On Mon, Dec 11, 2017 at 02:36:15PM -0500, Neil Horman wrote:
> Hey all-
> A few days ago, I was lamenting the fact that, when reviewing patches I
> would frequently complain about ABI changes that were actually considered safe
> because they were part of the EXPERIMENTAL api set. John M. asked me then what
> I might do to improve the situation, and the following patch set is a proposal
> that I've come up with.
>
> In thinking about the problem I identified two issues that I think we
> can improve on in this area:
>
> 1) Make experimental api calls more visible in the source code. That is to say,
> when reviewing patches, it would be nice to have some sort of visual reference
> that indicates that the changes being made are part of an experimental API and
> therefore ABI concerns need not be addressed
>
> 2) Make experimenal api usage more visible to consumers of the DPDK, so that
> they can make a more informed decision about the API's they consume in their
> application. We make an effort to document all the experimental API's, but
> there is no guarantee that a user will check the documentation before making use
> of a new library.
>
> This patch set attempts to achieve both of the above goals. To do this I've
> added an __experimental macro tag, suitable for inserting into api forward
> declarations and definitions.
>
> The presence of the tag in the header and c files where the api code resides
> increases the likelyhood that any patch submitted against them will include the
> tag in the context, making it clear to reviewers that ABI stability isn't a
> concern here.
>
>
> Also, This tag marks each function it is used on with an attibute causing any
> use of the fuction to emit a warning during the build
> with a message indicating that the API call in question is not yet part of the
> stable interface. Developers can then make an informed decision to suppress
> that warning or not.
>
> Because there is internal use of several experimental API's, this set also
> includes a new override macro ALLOW_EXPERIMENTAL_APIS to automatically
> suprress these warnings. I think its fair to assume that, for internal use, we
> almost always want to suppress these warnings, as by definition any change to
> the apis (even their removal) must be done in parallel with an appropriate
> change in the calling locations, lest the dpdk build itself break.
>
> Neil
>
> ---
> Change Notes:
> v2)
> * Cleaned up checkpatch errors
> * Added Allowance for building experimental on BSD
> * Swapped Patch 3 and 4 so that we didn't have a commit level that issued
> warnings/errors without need
>
> v3)
> * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be defined in
> CFLAGS rather than a makefile variable. This is more flexible in that it
> allows us to suppress this specific feature rather than all uses of the
> deprecated attribute, as we might use it for other features in the furute
>
Despite the fact that this is making yet more work for porting to a new
build system, I think this is a good idea to have. As such,
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (4 preceding siblings ...)
2017-12-12 14:07 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
@ 2017-12-12 14:33 ` Mcnamara, John
2017-12-12 20:18 ` Neil Horman
2017-12-12 15:11 ` Wiles, Keith
6 siblings, 1 reply; 83+ messages in thread
From: Mcnamara, John @ 2017-12-12 14:33 UTC (permalink / raw)
To: Neil Horman, dev; +Cc: thomas, Richardson, Bruce
> -----Original Message-----
> From: Neil Horman [mailto:nhorman@tuxdriver.com]
> Sent: Monday, December 11, 2017 7:36 PM
> To: dev@dpdk.org
> Cc: thomas@monjalon.net; Mcnamara, John <john.mcnamara@intel.com>;
> Richardson, Bruce <bruce.richardson@intel.com>
> Subject: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
>
> Hey all-
> A few days ago, I was lamenting the fact that, when reviewing
> patches I would frequently complain about ABI changes that were actually
> considered safe because they were part of the EXPERIMENTAL api set. John
> M. asked me then what I might do to improve the situation, and the
> following patch set is a proposal that I've come up with.
Hi Neil,
Thanks for this and apologies in advance for making more work for you but
it would be good to have a short section in the Contributors Guide on how
to add/check experimental APIs. I think the information in this cover
letter could be repurposed along with a few code and shell examples.
Probably as a new high level section in the Contributors Guides:
http://dpdk.org/doc/guides/contributing/index.html
Thanks,
John
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (5 preceding siblings ...)
2017-12-12 14:33 ` Mcnamara, John
@ 2017-12-12 15:11 ` Wiles, Keith
2017-12-12 20:14 ` Neil Horman
6 siblings, 1 reply; 83+ messages in thread
From: Wiles, Keith @ 2017-12-12 15:11 UTC (permalink / raw)
To: Neil Horman; +Cc: DPDK, Thomas Monjalon, Mcnamara, John, Richardson, Bruce
> On Dec 11, 2017, at 1:36 PM, Neil Horman <nhorman@tuxdriver.com> wrote:
>
> Hey all-
> A few days ago, I was lamenting the fact that, when reviewing patches I
> would frequently complain about ABI changes that were actually considered safe
> because they were part of the EXPERIMENTAL api set. John M. asked me then what
> I might do to improve the situation, and the following patch set is a proposal
> that I've come up with.
>
> In thinking about the problem I identified two issues that I think we
> can improve on in this area:
One question is how does this effect the ABI map files or does it? If an API is exposed in the map file does it need any type of special indicator on that API line? It may not make much difference, but I was thinking it could be an indicator the API is experimental and may not exist. If the new experimental API is included in the map file then it could become a problem for systems expecting all of the APIs in the map file to be solid.
Regards,
Keith
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-12 15:11 ` Wiles, Keith
@ 2017-12-12 20:14 ` Neil Horman
0 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-12 20:14 UTC (permalink / raw)
To: Wiles, Keith; +Cc: DPDK, Thomas Monjalon, Mcnamara, John, Richardson, Bruce
On Tue, Dec 12, 2017 at 03:11:33PM +0000, Wiles, Keith wrote:
>
>
> > On Dec 11, 2017, at 1:36 PM, Neil Horman <nhorman@tuxdriver.com> wrote:
> >
> > Hey all-
> > A few days ago, I was lamenting the fact that, when reviewing patches I
> > would frequently complain about ABI changes that were actually considered safe
> > because they were part of the EXPERIMENTAL api set. John M. asked me then what
> > I might do to improve the situation, and the following patch set is a proposal
> > that I've come up with.
> >
> > In thinking about the problem I identified two issues that I think we
> > can improve on in this area:
>
> One question is how does this effect the ABI map files or does it? If an API is exposed in the map file does it need any type of special indicator on that API line? It may not make much difference, but I was thinking it could be an indicator the API is experimental and may not exist. If the new experimental API is included in the map file then it could become a problem for systems expecting all of the APIs in the map file to be solid.
>
> Regards,
> Keith
>
>
So, thats a few questions that are all interconnected, I'll try to answer them
as completely as I can:
1) Despite being experimental API's, they still need to be part of the version
map files. This is an always condition, and there are no ecpetions to that.
Failure to put an api call in the map file means it won't get exported when we
build as a shared library and so is unusable. This has been the case since we
introduced the map files. You'll note that each map file which exports
experimental APIS has an EXPERIMENTAL clause in the map for expressly this
purpose
2) One of the problems that I identified in my cover letter was that, when
reviewing patches (and when using API's), there was no clear indicator that the
patch we were reviewing was part of an experimental API (without
simeoultaneously consulting the map file). That was part of what this patch set
was meant to address (visual clues in the patch that told reviewers this was
part of an experimental API).
3) The __experimental tag is expressly meant to go on function definitions and
forward declarations to address the concern in (2) expressly
4) The __experimental tag is also meant to trigger a warning to users that build
code using experimental apis. At compile time a warning is generated for any
call made to said tagged api (unless -DALLOW_EXPERIMENTAL_APIS is set)
5) The one issue I had with this patch set was that there was a need to manually
keep in sync items tagged with __experimental and the symbols listed in the
EXPERIMENTAL section of a map file. The first patch in this series addresses
that by adding a build check to make sure that symbols in the map file are
tagged with __experimental in the source.
Hope that answers all your questions
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-12 14:33 ` Mcnamara, John
@ 2017-12-12 20:18 ` Neil Horman
0 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-12 20:18 UTC (permalink / raw)
To: Mcnamara, John; +Cc: dev, thomas, Richardson, Bruce
On Tue, Dec 12, 2017 at 02:33:13PM +0000, Mcnamara, John wrote:
>
>
> > -----Original Message-----
> > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > Sent: Monday, December 11, 2017 7:36 PM
> > To: dev@dpdk.org
> > Cc: thomas@monjalon.net; Mcnamara, John <john.mcnamara@intel.com>;
> > Richardson, Bruce <bruce.richardson@intel.com>
> > Subject: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
> >
> > Hey all-
> > A few days ago, I was lamenting the fact that, when reviewing
> > patches I would frequently complain about ABI changes that were actually
> > considered safe because they were part of the EXPERIMENTAL api set. John
> > M. asked me then what I might do to improve the situation, and the
> > following patch set is a proposal that I've come up with.
>
> Hi Neil,
>
> Thanks for this and apologies in advance for making more work for you but
> it would be good to have a short section in the Contributors Guide on how
> to add/check experimental APIs. I think the information in this cover
> letter could be repurposed along with a few code and shell examples.
>
> Probably as a new high level section in the Contributors Guides:
>
> http://dpdk.org/doc/guides/contributing/index.html
>
> Thanks,
>
> John
>
Thats ok, I was actually trying to think of where to add documentation for this
thing, but couldnt find a really appropriate place. I'll add that in and
repost.
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-01 18:56 [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (5 preceding siblings ...)
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
@ 2017-12-13 15:17 ` Neil Horman
2017-12-13 15:17 ` [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
` (7 more replies)
2018-01-22 1:48 ` [PATCH 0/5] " Neil Horman
7 siblings, 8 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-13 15:17 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson
Hey all-
A few days ago, I was lamenting the fact that, when reviewing patches I
would frequently complain about ABI changes that were actually considered safe
because they were part of the EXPERIMENTAL api set. John M. asked me then what
I might do to improve the situation, and the following patch set is a proposal
that I've come up with.
In thinking about the problem I identified two issues that I think we
can improve on in this area:
1) Make experimental api calls more visible in the source code. That is to say,
when reviewing patches, it would be nice to have some sort of visual reference
that indicates that the changes being made are part of an experimental API and
therefore ABI concerns need not be addressed
2) Make experimenal api usage more visible to consumers of the DPDK, so that
they can make a more informed decision about the API's they consume in their
application. We make an effort to document all the experimental API's, but
there is no guarantee that a user will check the documentation before making use
of a new library.
This patch set attempts to achieve both of the above goals. To do this I've
added an __experimental macro tag, suitable for inserting into api forward
declarations and definitions.
The presence of the tag in the header and c files where the api code resides
increases the likelyhood that any patch submitted against them will include the
tag in the context, making it clear to reviewers that ABI stability isn't a
concern here.
Also, This tag marks each function it is used on with an attibute causing any
use of the fuction to emit a warning during the build
with a message indicating that the API call in question is not yet part of the
stable interface. Developers can then make an informed decision to suppress
that warning or not.
Because there is internal use of several experimental API's, this set also
includes a new override macro ALLOW_EXPERIMENTAL_APIS to automatically
suprress these warnings. I think its fair to assume that, for internal use, we
almost always want to suppress these warnings, as by definition any change to
the apis (even their removal) must be done in parallel with an appropriate
change in the calling locations, lest the dpdk build itself break.
Neil
---
Change Notes:
v2)
* Cleaned up checkpatch errors
* Added Allowance for building experimental on BSD
* Swapped Patch 3 and 4 so that we didn't have a commit level that issued
warnings/errors without need
v3)
* On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be defined in
CFLAGS rather than a makefile variable. This is more flexible in that it
allows us to suppress this specific feature rather than all uses of the
deprecated attribute, as we might use it for other features in the furute
v4)
* Added documentation patch to contributors guide
^ permalink raw reply [flat|nested] 83+ messages in thread
* [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
@ 2017-12-13 15:17 ` Neil Horman
2018-01-21 18:31 ` Thomas Monjalon
2017-12-13 15:17 ` [PATCHv4 2/5] compat: Add __experimental macro Neil Horman
` (6 subsequent siblings)
7 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2017-12-13 15:17 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson, Neil Horman
This tools reads the given version map for a directory, and checks to
ensure that, for each symbol listed in the export list, the corresponding
definition is tagged as __experimental, erroring out if its not. In this
way, we can ensure that the EXPERIMENTAL api is kept in sync with the tags
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
buildtools/experimentalsyms.sh | 35 +++++++++++++++++++++++++++++++++++
1 file changed, 35 insertions(+)
create mode 100755 buildtools/experimentalsyms.sh
diff --git a/buildtools/experimentalsyms.sh b/buildtools/experimentalsyms.sh
new file mode 100755
index 000000000..7342ec9b3
--- /dev/null
+++ b/buildtools/experimentalsyms.sh
@@ -0,0 +1,35 @@
+#!/bin/sh
+
+MAPFILE=$1
+OBJFILE=$2
+
+if [ -d $MAPFILE ]
+then
+ exit 0
+fi
+
+if [ -d $OBJFILE ]
+then
+ exit 0
+fi
+
+for i in `awk 'BEGIN {found=0}
+ /.*EXPERIMENTAL.*/ {found=1}
+ /.*}.*;/ {found=0}
+ /.*;/ {if (found == 1) print $1}' $MAPFILE`
+do
+ SYM=`echo $i | sed -e"s/;//"`
+ objdump -t $OBJFILE | grep -q "\.text.*$SYM"
+ IN_TEXT=$?
+ objdump -t $OBJFILE | grep -q "\.text\.experimental.*$SYM"
+ IN_EXP=$?
+ if [ $IN_TEXT -eq 0 -a $IN_EXP -ne 0 ]
+ then
+ echo "$SYM is not flagged as experimental"
+ echo "but is listed in version map"
+ echo "Please add __experimental to the definition of $SYM"
+ exit 1
+ fi
+done
+exit 0
+
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv4 2/5] compat: Add __experimental macro
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
2017-12-13 15:17 ` [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
@ 2017-12-13 15:17 ` Neil Horman
2018-01-21 18:37 ` Thomas Monjalon
2017-12-13 15:17 ` [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
` (5 subsequent siblings)
7 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2017-12-13 15:17 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson, Neil Horman
The __experimental macro tags a given exported function as being part of
the EXPERIMENTAL api. Use of this tag will cause any caller of the
function (that isn't removed by dead code elimination) to emit a warning
that the user is making use of an API whos stabilty isn't guaranteed.
It also places the function in the .text.experimental section, which is
used to validate the tag against the corresponding library version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
lib/librte_compat/rte_compat.h | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/lib/librte_compat/rte_compat.h b/lib/librte_compat/rte_compat.h
index 41e8032ba..450dd542c 100644
--- a/lib/librte_compat/rte_compat.h
+++ b/lib/librte_compat/rte_compat.h
@@ -101,5 +101,16 @@
*/
#endif
+#ifndef ALLOW_EXPERIMENTAL_APIS
+#define __experimental \
+__attribute__((deprecated("Symbol is not yet part of stable abi"), \
+section(".text.experimental")))
+
+#else
+
+#define __experimental \
+__attribute__((section(".text.experimental")))
+
+#endif
#endif /* _RTE_COMPAT_H_ */
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
2017-12-13 15:17 ` [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-13 15:17 ` [PATCHv4 2/5] compat: Add __experimental macro Neil Horman
@ 2017-12-13 15:17 ` Neil Horman
2018-01-11 20:06 ` Ferruh Yigit
2018-01-21 18:50 ` Thomas Monjalon
2017-12-13 15:17 ` [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls Neil Horman
` (4 subsequent siblings)
7 siblings, 2 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-13 15:17 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson, Neil Horman
Add checks during build to ensure that all symbols in the EXPERIMENTAL
version map section have __experimental tags on their definitions, and
enable the warnings needed to announce their use. Also add an
ALLOW_EXPERIMENTAL_APIS define to allow individual libraries and files
to declare the acceptability of experimental api usage
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
app/test-eventdev/Makefile | 1 +
app/test-pmd/Makefile | 1 +
drivers/event/sw/Makefile | 1 +
drivers/net/failsafe/Makefile | 1 +
drivers/net/ixgbe/Makefile | 1 +
examples/eventdev_pipeline_sw_pmd/Makefile | 1 +
examples/flow_classify/Makefile | 1 +
examples/ipsec-secgw/Makefile | 1 +
examples/service_cores/Makefile | 1 +
lib/librte_eal/bsdapp/eal/Makefile | 1 +
lib/librte_eal/linuxapp/Makefile | 2 ++
lib/librte_eal/linuxapp/eal/Makefile | 2 ++
lib/librte_eventdev/Makefile | 1 +
lib/librte_security/Makefile | 1 +
mk/internal/rte.compile-pre.mk | 4 ++++
mk/toolchain/clang/rte.vars.mk | 2 +-
mk/toolchain/gcc/rte.vars.mk | 2 +-
mk/toolchain/icc/rte.vars.mk | 2 +-
18 files changed, 23 insertions(+), 3 deletions(-)
diff --git a/app/test-eventdev/Makefile b/app/test-eventdev/Makefile
index dcb2ac476..78bae7633 100644
--- a/app/test-eventdev/Makefile
+++ b/app/test-eventdev/Makefile
@@ -32,6 +32,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
APP = dpdk-test-eventdev
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/app/test-pmd/Makefile b/app/test-pmd/Makefile
index d21308fcd..23f9ddb86 100644
--- a/app/test-pmd/Makefile
+++ b/app/test-pmd/Makefile
@@ -38,6 +38,7 @@ ifeq ($(CONFIG_RTE_TEST_PMD),y)
#
APP = testpmd
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/drivers/event/sw/Makefile b/drivers/event/sw/Makefile
index 2f2b67bac..e54477ec5 100644
--- a/drivers/event/sw/Makefile
+++ b/drivers/event/sw/Makefile
@@ -34,6 +34,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
LIB = librte_pmd_sw_event.a
# build flags
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
# for older GCC versions, allow us to initialize an event using
diff --git a/drivers/net/failsafe/Makefile b/drivers/net/failsafe/Makefile
index ea2a8fe46..29f1f0ff2 100644
--- a/drivers/net/failsafe/Makefile
+++ b/drivers/net/failsafe/Makefile
@@ -50,6 +50,7 @@ SRCS-$(CONFIG_RTE_LIBRTE_PMD_FAILSAFE) += failsafe_flow.c
# No exported include files
# Basic CFLAGS:
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -std=gnu99 -Wextra
CFLAGS += -O3
CFLAGS += -I.
diff --git a/drivers/net/ixgbe/Makefile b/drivers/net/ixgbe/Makefile
index 511a64eb0..c1cf226f1 100644
--- a/drivers/net/ixgbe/Makefile
+++ b/drivers/net/ixgbe/Makefile
@@ -36,6 +36,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
#
LIB = librte_pmd_ixgbe.a
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/eventdev_pipeline_sw_pmd/Makefile b/examples/eventdev_pipeline_sw_pmd/Makefile
index de4e22c88..dc54b0df2 100644
--- a/examples/eventdev_pipeline_sw_pmd/Makefile
+++ b/examples/eventdev_pipeline_sw_pmd/Makefile
@@ -43,6 +43,7 @@ APP = eventdev_pipeline_sw_pmd
# all source are stored in SRCS-y
SRCS-y := main.c
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/flow_classify/Makefile b/examples/flow_classify/Makefile
index eecdde14c..905a11cef 100644
--- a/examples/flow_classify/Makefile
+++ b/examples/flow_classify/Makefile
@@ -45,6 +45,7 @@ APP = flow_classify
# all source are stored in SRCS-y
SRCS-y := flow_classify.c
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/ipsec-secgw/Makefile b/examples/ipsec-secgw/Makefile
index 9fd33cb7f..84ba9fd29 100644
--- a/examples/ipsec-secgw/Makefile
+++ b/examples/ipsec-secgw/Makefile
@@ -46,6 +46,7 @@ endif
APP = ipsec-secgw
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3 -gdwarf-2
CFLAGS += $(WERROR_FLAGS)
ifeq ($(CONFIG_RTE_TOOLCHAIN_ICC),y)
diff --git a/examples/service_cores/Makefile b/examples/service_cores/Makefile
index bd4a345dc..1f0448e27 100644
--- a/examples/service_cores/Makefile
+++ b/examples/service_cores/Makefile
@@ -43,6 +43,7 @@ APP = service_cores
# all source are stored in SRCS-y
SRCS-y := main.c
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += $(WERROR_FLAGS)
# workaround for a gcc bug with noreturn attribute
diff --git a/lib/librte_eal/bsdapp/eal/Makefile b/lib/librte_eal/bsdapp/eal/Makefile
index afa117de4..ed595f104 100644
--- a/lib/librte_eal/bsdapp/eal/Makefile
+++ b/lib/librte_eal/bsdapp/eal/Makefile
@@ -37,6 +37,7 @@ ARCH_DIR ?= $(RTE_ARCH)
VPATH += $(RTE_SDK)/lib/librte_eal/common
VPATH += $(RTE_SDK)/lib/librte_eal/common/arch/$(ARCH_DIR)
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -I$(SRCDIR)/include
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common/include
diff --git a/lib/librte_eal/linuxapp/Makefile b/lib/librte_eal/linuxapp/Makefile
index 2ebdf3139..37367fc88 100644
--- a/lib/librte_eal/linuxapp/Makefile
+++ b/lib/librte_eal/linuxapp/Makefile
@@ -36,4 +36,6 @@ DIRS-$(CONFIG_RTE_EAL_IGB_UIO) += igb_uio
DIRS-$(CONFIG_RTE_KNI_KMOD) += kni
DEPDIRS-kni := eal
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
+
include $(RTE_SDK)/mk/rte.subdir.mk
diff --git a/lib/librte_eal/linuxapp/eal/Makefile b/lib/librte_eal/linuxapp/eal/Makefile
index 5a7b8b2ac..ec810d92b 100644
--- a/lib/librte_eal/linuxapp/eal/Makefile
+++ b/lib/librte_eal/linuxapp/eal/Makefile
@@ -34,6 +34,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
LIB = librte_eal.a
ARCH_DIR ?= $(RTE_ARCH)
+
EXPORT_MAP := ../../rte_eal_version.map
VPATH += $(RTE_SDK)/lib/librte_eal/common/arch/$(ARCH_DIR)
@@ -41,6 +42,7 @@ LIBABIVER := 6
VPATH += $(RTE_SDK)/lib/librte_eal/common
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -I$(SRCDIR)/include
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common/include
diff --git a/lib/librte_eventdev/Makefile b/lib/librte_eventdev/Makefile
index 5ac22cde7..96afc3be8 100644
--- a/lib/librte_eventdev/Makefile
+++ b/lib/librte_eventdev/Makefile
@@ -37,6 +37,7 @@ LIB = librte_eventdev.a
LIBABIVER := 3
# build flags
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
LDLIBS += -lrte_eal -lrte_ring -lrte_ethdev -lrte_hash
diff --git a/lib/librte_security/Makefile b/lib/librte_security/Makefile
index bb93ec33d..d433937a5 100644
--- a/lib/librte_security/Makefile
+++ b/lib/librte_security/Makefile
@@ -37,6 +37,7 @@ LIB = librte_security.a
LIBABIVER := 1
# build flags
+CFLAGS += -DALLOW_EXPERIMENTAL_APIS
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
LDLIBS += -lrte_eal -lrte_mempool
diff --git a/mk/internal/rte.compile-pre.mk b/mk/internal/rte.compile-pre.mk
index da8dda498..83a53c202 100644
--- a/mk/internal/rte.compile-pre.mk
+++ b/mk/internal/rte.compile-pre.mk
@@ -84,6 +84,9 @@ C_TO_O = $(CC) -Wp,-MD,$(call obj2dep,$(@)).tmp $(CPPFLAGS) $(CFLAGS) \
C_TO_O_STR = $(subst ','\'',$(C_TO_O)) #'# fix syntax highlight
C_TO_O_DISP = $(if $(V),"$(C_TO_O_STR)"," CC $(@)")
endif
+EXPERIMENTAL_CHECK = $(RTE_SDK)/buildtools/experimentalsyms.sh
+CHECK_EXPERIMENTAL = $(EXPERIMENTAL_CHECK) $(SRCDIR)/$(EXPORT_MAP) $@
+
PMDINFO_GEN = $(RTE_SDK_BIN)/app/dpdk-pmdinfogen $@ $@.pmd.c
PMDINFO_CC = $(CC) $(CPPFLAGS) $(CFLAGS) -c -o $@.pmd.o $@.pmd.c
PMDINFO_LD = $(CROSS)ld $(LDFLAGS) -r -o $@.o $@.pmd.o $@
@@ -100,6 +103,7 @@ C_TO_O_DO = @set -e; \
echo $(C_TO_O_DISP); \
$(C_TO_O) && \
$(PMDINFO_TO_O) && \
+ $(CHECK_EXPERIMENTAL) && \
echo $(C_TO_O_CMD) > $(call obj2cmd,$(@)) && \
sed 's,'$@':,dep_'$@' =,' $(call obj2dep,$(@)).tmp > $(call obj2dep,$(@)) && \
rm -f $(call obj2dep,$(@)).tmp
diff --git a/mk/toolchain/clang/rte.vars.mk b/mk/toolchain/clang/rte.vars.mk
index dde922d22..3cfe92545 100644
--- a/mk/toolchain/clang/rte.vars.mk
+++ b/mk/toolchain/clang/rte.vars.mk
@@ -67,7 +67,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/gcc/rte.vars.mk b/mk/toolchain/gcc/rte.vars.mk
index 3b907e201..3356a37c8 100644
--- a/mk/toolchain/gcc/rte.vars.mk
+++ b/mk/toolchain/gcc/rte.vars.mk
@@ -75,7 +75,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wcast-align -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/icc/rte.vars.mk b/mk/toolchain/icc/rte.vars.mk
index 33a8ba79e..58940602e 100644
--- a/mk/toolchain/icc/rte.vars.mk
+++ b/mk/toolchain/icc/rte.vars.mk
@@ -73,7 +73,7 @@ TOOLCHAIN_ASFLAGS =
WERROR_FLAGS := -Wall -w2 -diag-disable 271 -diag-warning 1478
WERROR_FLAGS += -diag-disable 13368 -diag-disable 15527
WERROR_FLAGS += -diag-disable 188
-WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076
+WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076 -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror-all
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
` (2 preceding siblings ...)
2017-12-13 15:17 ` [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
@ 2017-12-13 15:17 ` Neil Horman
2018-01-11 20:06 ` Ferruh Yigit
2017-12-13 15:17 ` [PATCHv4 5/5] doc: Add ABI __experimental tag documentation Neil Horman
` (3 subsequent siblings)
7 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2017-12-13 15:17 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson, Neil Horman
Append the __experimental tag to api calls appearing in the EXPERIMENTAL
section of their libraries version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
lib/librte_eal/common/eal_common_dev.c | 6 ++-
lib/librte_eal/common/eal_common_devargs.c | 7 +--
lib/librte_eal/common/include/rte_dev.h | 6 ++-
lib/librte_eal/common/include/rte_devargs.h | 8 ++--
lib/librte_eal/common/include/rte_service.h | 47 ++++++++++---------
.../common/include/rte_service_component.h | 14 +++---
lib/librte_eal/common/rte_service.c | 52 ++++++++++++----------
lib/librte_eal/linuxapp/eal/eal.c | 1 +
lib/librte_ether/rte_mtr.c | 25 ++++++-----
lib/librte_ether/rte_mtr.h | 26 +++++------
lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
lib/librte_security/rte_security.c | 16 +++----
lib/librte_security/rte_security.h | 23 +++++-----
14 files changed, 139 insertions(+), 116 deletions(-)
diff --git a/lib/librte_eal/common/eal_common_dev.c b/lib/librte_eal/common/eal_common_dev.c
index dda8f5835..ee866ddd2 100644
--- a/lib/librte_eal/common/eal_common_dev.c
+++ b/lib/librte_eal/common/eal_common_dev.c
@@ -37,6 +37,7 @@
#include <inttypes.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
#include <rte_dev.h>
#include <rte_devargs.h>
@@ -133,7 +134,7 @@ full_dev_name(const char *bus, const char *dev, const char *args)
return name;
}
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs)
{
struct rte_bus *bus;
@@ -203,7 +204,8 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
return ret;
}
-int rte_eal_hotplug_remove(const char *busname, const char *devname)
+int __experimental
+rte_eal_hotplug_remove(const char *busname, const char *devname)
{
struct rte_bus *bus;
struct rte_device *dev;
diff --git a/lib/librte_eal/common/eal_common_devargs.c b/lib/librte_eal/common/eal_common_devargs.c
index 6ac88d6ab..8e46d54bd 100644
--- a/lib/librte_eal/common/eal_common_devargs.c
+++ b/lib/librte_eal/common/eal_common_devargs.c
@@ -40,6 +40,7 @@
#include <stdio.h>
#include <string.h>
+#include <rte_compat.h>
#include <rte_dev.h>
#include <rte_devargs.h>
#include <rte_tailq.h>
@@ -85,7 +86,7 @@ bus_name_cmp(const struct rte_bus *bus, const void *name)
return strncmp(bus->name, name, strlen(bus->name));
}
-int
+int __experimental
rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
{
struct rte_bus *bus = NULL;
@@ -139,7 +140,7 @@ rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
return 0;
}
-int
+int __experimental
rte_eal_devargs_insert(struct rte_devargs *da)
{
int ret;
@@ -188,7 +189,7 @@ rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str)
return -1;
}
-int
+int __experimental
rte_eal_devargs_remove(const char *busname, const char *devname)
{
struct rte_devargs *d;
diff --git a/lib/librte_eal/common/include/rte_dev.h b/lib/librte_eal/common/include/rte_dev.h
index 9342e0cbd..ddb0a09a7 100644
--- a/lib/librte_eal/common/include/rte_dev.h
+++ b/lib/librte_eal/common/include/rte_dev.h
@@ -49,6 +49,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_log.h>
__attribute__((format(printf, 2, 0)))
@@ -209,7 +210,7 @@ int rte_eal_dev_detach(struct rte_device *dev);
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs);
/**
@@ -225,7 +226,8 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_remove(const char *busname, const char *devname);
+int __experimental rte_eal_hotplug_remove(const char *busname,
+ const char *devname);
/**
* Device comparison function.
diff --git a/lib/librte_eal/common/include/rte_devargs.h b/lib/librte_eal/common/include/rte_devargs.h
index 58d585df6..e4c10b6c5 100644
--- a/lib/librte_eal/common/include/rte_devargs.h
+++ b/lib/librte_eal/common/include/rte_devargs.h
@@ -50,6 +50,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
/**
@@ -136,7 +137,7 @@ int rte_eal_parse_devargs_str(const char *devargs_str,
* - 0 on success.
* - Negative errno on error.
*/
-int
+int __experimental
rte_eal_devargs_parse(const char *dev,
struct rte_devargs *da);
@@ -150,7 +151,7 @@ rte_eal_devargs_parse(const char *dev,
* - 0 on success
* - Negative on error.
*/
-int
+int __experimental
rte_eal_devargs_insert(struct rte_devargs *da);
/**
@@ -193,7 +194,8 @@ int rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str);
* <0 on error.
* >0 if the devargs was not within the user device list.
*/
-int rte_eal_devargs_remove(const char *busname, const char *devname);
+int __experimental rte_eal_devargs_remove(const char *busname,
+ const char *devname);
/**
* Count the number of user devices of a specified type
diff --git a/lib/librte_eal/common/include/rte_service.h b/lib/librte_eal/common/include/rte_service.h
index 927244065..da10d17ea 100644
--- a/lib/librte_eal/common/include/rte_service.h
+++ b/lib/librte_eal/common/include/rte_service.h
@@ -84,7 +84,7 @@ extern "C" {
*
* @return The number of services registered.
*/
-uint32_t rte_service_get_count(void);
+uint32_t __experimental rte_service_get_count(void);
/**
* @warning
@@ -111,7 +111,8 @@ uint32_t rte_service_get_count(void);
* @retval -EINVAL Null *service_id* pointer provided
* @retval -ENODEV No such service registered
*/
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
+int32_t __experimental rte_service_get_by_name(const char *name,
+ uint32_t *service_id);
/**
* @warning
@@ -122,7 +123,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
* @return A pointer to the name of the service. The returned pointer remains
* in ownership of the service, and the application must not free it.
*/
-const char *rte_service_get_name(uint32_t id);
+const char __experimental *rte_service_get_name(uint32_t id);
/**
* @warning
@@ -135,7 +136,8 @@ const char *rte_service_get_name(uint32_t id);
* @retval 1 Capability supported by this service instance
* @retval 0 Capability not supported by this service instance
*/
-int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
+int32_t __experimental rte_service_probe_capability(uint32_t id,
+ uint32_t capability);
/**
* @warning
@@ -159,8 +161,8 @@ int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
* @retval 0 lcore map updated successfully
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
- uint32_t enable);
+int32_t __experimental rte_service_map_lcore_set(uint32_t service_id,
+ uint32_t lcore, uint32_t enable);
/**
* @warning
@@ -175,7 +177,8 @@ int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
* @retval 0 lcore is not mapped to service
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
+int32_t __experimental rte_service_map_lcore_get(uint32_t service_id,
+ uint32_t lcore);
/**
* @warning
@@ -192,7 +195,7 @@ int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
* @retval 0 The service was successfully started
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __experimental rte_service_runstate_set(uint32_t id, uint32_t runstate);
/**
* @warning
@@ -210,7 +213,7 @@ int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
* @retval 0 Service is stopped
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_get(uint32_t id);
+int32_t __experimental rte_service_runstate_get(uint32_t id);
/**
* @warning
@@ -226,7 +229,8 @@ int32_t rte_service_runstate_get(uint32_t id);
* @retval 0 Success
* @retval -EINVAL Invalid service ID
*/
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
+int32_t __experimental rte_service_set_runstate_mapped_check(uint32_t id,
+ int32_t enable);
/**
* @warning
@@ -264,7 +268,7 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
* @retval -ENOEXEC Service is not in a run-able state
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_multithread_unsafe);
/**
@@ -280,7 +284,7 @@ int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
* @retval -EINVAL Failed to start core. The *lcore_id* passed in is not
* currently assigned to be a service core.
*/
-int32_t rte_service_lcore_start(uint32_t lcore_id);
+int32_t __experimental rte_service_lcore_start(uint32_t lcore_id);
/**
* @warning
@@ -299,7 +303,7 @@ int32_t rte_service_lcore_start(uint32_t lcore_id);
* The application must stop the service first, and then stop the
* lcore.
*/
-int32_t rte_service_lcore_stop(uint32_t lcore_id);
+int32_t __experimental rte_service_lcore_stop(uint32_t lcore_id);
/**
* @warning
@@ -315,7 +319,7 @@ int32_t rte_service_lcore_stop(uint32_t lcore_id);
* @retval -EALREADY lcore is already added to the service core list
* @retval -EINVAL Invalid lcore provided
*/
-int32_t rte_service_lcore_add(uint32_t lcore);
+int32_t __experimental rte_service_lcore_add(uint32_t lcore);
/**
* @warning
@@ -329,7 +333,7 @@ int32_t rte_service_lcore_add(uint32_t lcore);
* @retval -EBUSY Lcore is not stopped, stop service core before removing.
* @retval -EINVAL failed to add lcore to service core mask.
*/
-int32_t rte_service_lcore_del(uint32_t lcore);
+int32_t __experimental rte_service_lcore_del(uint32_t lcore);
/**
* @warning
@@ -346,7 +350,7 @@ int32_t rte_service_lcore_del(uint32_t lcore);
*
* @return The number of service cores currently configured.
*/
-int32_t rte_service_lcore_count(void);
+int32_t __experimental rte_service_lcore_count(void);
/**
* @warning
@@ -358,7 +362,7 @@ int32_t rte_service_lcore_count(void);
*
* @retval 0 Success
*/
-int32_t rte_service_lcore_reset_all(void);
+int32_t __experimental rte_service_lcore_reset_all(void);
/**
* @warning
@@ -372,7 +376,8 @@ int32_t rte_service_lcore_reset_all(void);
* @retval 0 Success
* @retval -EINVAL Invalid service pointer passed
*/
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
+int32_t __experimental rte_service_set_stats_enable(uint32_t id,
+ int32_t enable);
/**
* @warning
@@ -393,7 +398,7 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
* service core list. No items have been populated, call this function
* with a size of at least *rte_service_core_count* items.
*/
-int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
+int32_t __experimental rte_service_lcore_list(uint32_t array[], uint32_t n);
/**
* @warning
@@ -406,7 +411,7 @@ int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
* @retval -EINVAL Invalid lcore provided
* @retval -ENOTSUP The provided lcore is not a service core.
*/
-int32_t rte_service_lcore_count_services(uint32_t lcore);
+int32_t __experimental rte_service_lcore_count_services(uint32_t lcore);
/**
* @warning
@@ -418,7 +423,7 @@ int32_t rte_service_lcore_count_services(uint32_t lcore);
* @retval 0 Statistics have been successfully dumped
* @retval -EINVAL Invalid service id provided
*/
-int32_t rte_service_dump(FILE *f, uint32_t id);
+int32_t __experimental rte_service_dump(FILE *f, uint32_t id);
#ifdef __cplusplus
}
diff --git a/lib/librte_eal/common/include/rte_service_component.h b/lib/librte_eal/common/include/rte_service_component.h
index ac965cb48..a129258eb 100644
--- a/lib/librte_eal/common/include/rte_service_component.h
+++ b/lib/librte_eal/common/include/rte_service_component.h
@@ -37,7 +37,7 @@
* Include this file if you are writing a component that requires CPU cycles to
* operate, and you wish to run the component using service cores
*/
-
+#include <rte_compat.h>
#include <rte_service.h>
/**
@@ -101,8 +101,9 @@ struct rte_service_spec {
* -EINVAL Attempted to register an invalid service (eg, no callback
* set)
*/
-int32_t rte_service_component_register(const struct rte_service_spec *spec,
- uint32_t *service_id);
+int32_t __experimental
+rte_service_component_register(const struct rte_service_spec *spec,
+ uint32_t *service_id);
/**
* @warning
@@ -116,7 +117,7 @@ int32_t rte_service_component_register(const struct rte_service_spec *spec,
* @retval -EBUSY The service is currently running, stop the service before
* calling unregister. No action has been taken.
*/
-int32_t rte_service_component_unregister(uint32_t id);
+int32_t __experimental rte_service_component_unregister(uint32_t id);
/**
* @warning
@@ -134,7 +135,7 @@ int32_t rte_service_component_unregister(uint32_t id);
* @retval -ENODEV Error in enabling service lcore on a service
* @retval -ENOEXEC Error when starting services
*/
-int32_t rte_service_start_with_defaults(void);
+int32_t __experimental rte_service_start_with_defaults(void);
/**
* @warning
@@ -151,7 +152,8 @@ int32_t rte_service_start_with_defaults(void);
*
* @retval 0 Success
*/
-int32_t rte_service_component_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __experimental rte_service_component_runstate_set(uint32_t id,
+ uint32_t runstate);
/**
* @warning
diff --git a/lib/librte_eal/common/rte_service.c b/lib/librte_eal/common/rte_service.c
index ae97e6b7f..178354323 100644
--- a/lib/librte_eal/common/rte_service.c
+++ b/lib/librte_eal/common/rte_service.c
@@ -38,6 +38,7 @@
#include <string.h>
#include <dirent.h>
+#include <rte_compat.h>
#include <rte_service.h>
#include "include/rte_service_component.h"
@@ -168,7 +169,8 @@ service_mt_safe(struct rte_service_spec_impl *s)
return !!(s->spec.capabilities & RTE_SERVICE_CAP_MT_SAFE);
}
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
+int32_t __experimental
+rte_service_set_stats_enable(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -181,7 +183,8 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
return 0;
}
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
+int32_t __experimental
+rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -194,13 +197,14 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
return 0;
}
-uint32_t
+uint32_t __experimental
rte_service_get_count(void)
{
return rte_service_count;
}
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
+int32_t __experimental
+rte_service_get_by_name(const char *name, uint32_t *service_id)
{
if (!service_id)
return -EINVAL;
@@ -217,7 +221,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
return -ENODEV;
}
-const char *
+const char * __experimental
rte_service_get_name(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -225,7 +229,7 @@ rte_service_get_name(uint32_t id)
return s->spec.name;
}
-int32_t
+int32_t __experimental
rte_service_probe_capability(uint32_t id, uint32_t capability)
{
struct rte_service_spec_impl *s;
@@ -233,7 +237,7 @@ rte_service_probe_capability(uint32_t id, uint32_t capability)
return !!(s->spec.capabilities & capability);
}
-int32_t
+int32_t __experimental
rte_service_component_register(const struct rte_service_spec *spec,
uint32_t *id_ptr)
{
@@ -266,7 +270,7 @@ rte_service_component_register(const struct rte_service_spec *spec,
return 0;
}
-int32_t
+int32_t __experimental
rte_service_component_unregister(uint32_t id)
{
uint32_t i;
@@ -287,7 +291,7 @@ rte_service_component_unregister(uint32_t id)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -302,7 +306,7 @@ rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -317,7 +321,7 @@ rte_service_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_runstate_get(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -378,7 +382,7 @@ service_run(uint32_t i, struct core_state *cs, uint64_t service_mask)
return 0;
}
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_mt_unsafe)
{
/* run service on calling core, using all-ones as the service mask */
@@ -434,7 +438,7 @@ rte_service_runner_func(void *arg)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_lcore_count(void)
{
int32_t count = 0;
@@ -444,7 +448,7 @@ rte_service_lcore_count(void)
return count;
}
-int32_t
+int32_t __experimental
rte_service_lcore_list(uint32_t array[], uint32_t n)
{
uint32_t count = rte_service_lcore_count();
@@ -467,7 +471,7 @@ rte_service_lcore_list(uint32_t array[], uint32_t n)
return count;
}
-int32_t
+int32_t __experimental
rte_service_lcore_count_services(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -480,7 +484,7 @@ rte_service_lcore_count_services(uint32_t lcore)
return __builtin_popcountll(cs->service_mask);
}
-int32_t
+int32_t __experimental
rte_service_start_with_defaults(void)
{
/* create a default mapping from cores to services, then start the
@@ -562,7 +566,7 @@ service_update(struct rte_service_spec *service, uint32_t lcore,
return 0;
}
-int32_t
+int32_t __experimental
rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
{
struct rte_service_spec_impl *s;
@@ -571,7 +575,7 @@ rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
return service_update(&s->spec, lcore, &on, 0);
}
-int32_t
+int32_t __experimental
rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
{
struct rte_service_spec_impl *s;
@@ -583,7 +587,7 @@ rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
return ret;
}
-int32_t rte_service_lcore_reset_all(void)
+int32_t __experimental rte_service_lcore_reset_all(void)
{
/* loop over cores, reset all to mask 0 */
uint32_t i;
@@ -614,7 +618,7 @@ set_lcore_state(uint32_t lcore, int32_t state)
lcore_states[lcore].is_service_core = (state == ROLE_SERVICE);
}
-int32_t
+int32_t __experimental
rte_service_lcore_add(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -633,7 +637,7 @@ rte_service_lcore_add(uint32_t lcore)
return rte_eal_wait_lcore(lcore);
}
-int32_t
+int32_t __experimental
rte_service_lcore_del(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -652,7 +656,7 @@ rte_service_lcore_del(uint32_t lcore)
return 0;
}
-int32_t
+int32_t __experimental
rte_service_lcore_start(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -675,7 +679,7 @@ rte_service_lcore_start(uint32_t lcore)
return ret;
}
-int32_t
+int32_t __experimental
rte_service_lcore_stop(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -745,7 +749,7 @@ service_dump_calls_per_lcore(FILE *f, uint32_t lcore, uint32_t reset)
fprintf(f, "\n");
}
-int32_t rte_service_dump(FILE *f, uint32_t id)
+int32_t __experimental rte_service_dump(FILE *f, uint32_t id)
{
uint32_t i;
int print_one = (id != UINT32_MAX);
diff --git a/lib/librte_eal/linuxapp/eal/eal.c b/lib/librte_eal/linuxapp/eal/eal.c
index 229eec9f1..73a0da22c 100644
--- a/lib/librte_eal/linuxapp/eal/eal.c
+++ b/lib/librte_eal/linuxapp/eal/eal.c
@@ -53,6 +53,7 @@
#include <sys/io.h>
#endif
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_debug.h>
#include <rte_memory.h>
diff --git a/lib/librte_ether/rte_mtr.c b/lib/librte_ether/rte_mtr.c
index 4f56f8714..2cbe0bb5a 100644
--- a/lib/librte_ether/rte_mtr.c
+++ b/lib/librte_ether/rte_mtr.c
@@ -34,6 +34,7 @@
#include <stdint.h>
#include <rte_errno.h>
+#include "rte_compat.h"
#include "rte_ethdev.h"
#include "rte_mtr_driver.h"
#include "rte_mtr.h"
@@ -86,7 +87,7 @@ rte_mtr_ops_get(uint16_t port_id, struct rte_mtr_error *error)
})
/* MTR capabilities get */
-int
+int __experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error)
@@ -97,7 +98,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
}
/* MTR meter profile add */
-int
+int __experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -109,7 +110,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
}
/** MTR meter profile delete */
-int
+int __experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error)
@@ -120,7 +121,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
}
/** MTR object create */
-int
+int __experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -133,7 +134,7 @@ rte_mtr_create(uint16_t port_id,
}
/** MTR object destroy */
-int
+int __experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -144,7 +145,7 @@ rte_mtr_destroy(uint16_t port_id,
}
/** MTR object meter enable */
-int
+int __experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -155,7 +156,7 @@ rte_mtr_meter_enable(uint16_t port_id,
}
/** MTR object meter disable */
-int
+int __experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -166,7 +167,7 @@ rte_mtr_meter_disable(uint16_t port_id,
}
/** MTR object meter profile update */
-int
+int __experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -178,7 +179,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
}
/** MTR object meter DSCP table update */
-int
+int __experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -190,7 +191,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
}
/** MTR object policer action update */
-int
+int __experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -203,7 +204,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
}
/** MTR object enabled stats update */
-int
+int __experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -215,7 +216,7 @@ rte_mtr_stats_update(uint16_t port_id,
}
/** MTR object stats read */
-int
+int __experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_ether/rte_mtr.h b/lib/librte_ether/rte_mtr.h
index f6b6ef3b6..fd8361998 100644
--- a/lib/librte_ether/rte_mtr.h
+++ b/lib/librte_ether/rte_mtr.h
@@ -74,7 +74,7 @@
* @b EXPERIMENTAL: this API may change without prior notice
*/
#include <stdint.h>
-
+#include <rte_compat.h>
#include <rte_common.h>
#ifdef __cplusplus
@@ -447,7 +447,7 @@ struct rte_mtr_error {
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error);
@@ -470,7 +470,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -491,7 +491,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error);
@@ -519,7 +519,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
*
* @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
*/
-int
+int __experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -542,7 +542,7 @@ rte_mtr_create(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -569,7 +569,7 @@ rte_mtr_destroy(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -590,7 +590,7 @@ rte_mtr_meter_disable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -609,7 +609,7 @@ rte_mtr_meter_enable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -633,7 +633,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -659,7 +659,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -684,7 +684,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -715,7 +715,7 @@ rte_mtr_stats_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_flow_classify/rte_flow_classify.c b/lib/librte_flow_classify/rte_flow_classify.c
index e6f448643..6716672fc 100644
--- a/lib/librte_flow_classify/rte_flow_classify.c
+++ b/lib/librte_flow_classify/rte_flow_classify.c
@@ -31,6 +31,7 @@
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
+#include <rte_compat.h>
#include <rte_flow_classify.h>
#include "rte_flow_classify_parse.h"
#include <rte_flow_driver.h>
@@ -245,7 +246,7 @@ rte_flow_classifier_check_params(struct rte_flow_classifier_params *params)
return 0;
}
-struct rte_flow_classifier *
+struct rte_flow_classifier * __experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params)
{
struct rte_flow_classifier *cls;
@@ -291,7 +292,7 @@ rte_flow_classify_table_free(struct rte_table *table)
table->ops.f_free(table->h_table);
}
-int
+int __experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls)
{
uint32_t i;
@@ -369,7 +370,7 @@ rte_table_check_params(struct rte_flow_classifier *cls,
return 0;
}
-int
+int __experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id)
@@ -483,7 +484,7 @@ allocate_acl_ipv4_5tuple_rule(void)
return rule;
}
-struct rte_flow_classify_rule *
+struct rte_flow_classify_rule * __experimental
rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
uint32_t table_id,
int *key_found,
@@ -582,7 +583,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
return rule;
}
-int
+int __experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule)
@@ -659,7 +660,7 @@ action_apply(struct rte_flow_classifier *cls,
return ret;
}
-int
+int __experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_flow_classify/rte_flow_classify.h b/lib/librte_flow_classify/rte_flow_classify.h
index 1211873a1..cd9516f9e 100644
--- a/lib/librte_flow_classify/rte_flow_classify.h
+++ b/lib/librte_flow_classify/rte_flow_classify.h
@@ -70,6 +70,7 @@
* with rte_flow_classifier_free()
*/
+#include <rte_compat.h>
#include <rte_ethdev.h>
#include <rte_ether.h>
#include <rte_flow.h>
@@ -176,7 +177,7 @@ struct rte_flow_classify_ipv4_5tuple_stats {
* @return
* Handle to flow classifier instance on success or NULL otherwise
*/
-struct rte_flow_classifier *
+struct rte_flow_classifier * __experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params);
/**
@@ -187,7 +188,7 @@ rte_flow_classifier_create(struct rte_flow_classifier_params *params);
* @return
* 0 on success, error code otherwise
*/
-int
+int __experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls);
/**
@@ -203,7 +204,7 @@ rte_flow_classifier_free(struct rte_flow_classifier *cls);
* @return
* 0 on success, error code otherwise
*/
-int
+int __experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id);
@@ -250,7 +251,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule);
@@ -274,7 +275,7 @@ rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_security/rte_security.c b/lib/librte_security/rte_security.c
index 1227fca8a..958b7273e 100644
--- a/lib/librte_security/rte_security.c
+++ b/lib/librte_security/rte_security.c
@@ -33,12 +33,12 @@
#include <rte_malloc.h>
#include <rte_dev.h>
-
+#include "rte_compat.h"
#include "rte_security.h"
#include "rte_security_driver.h"
struct rte_security_session *
-rte_security_session_create(struct rte_security_ctx *instance,
+__experimental rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp)
{
@@ -61,7 +61,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
return sess;
}
-int
+int __experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf)
@@ -70,7 +70,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
return instance->ops->session_update(instance->device, sess, conf);
}
-int
+int __experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats)
@@ -79,7 +79,7 @@ rte_security_session_stats_get(struct rte_security_ctx *instance,
return instance->ops->session_stats_get(instance->device, sess, stats);
}
-int
+int __experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess)
{
@@ -98,7 +98,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
return ret;
}
-int
+int __experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *m, void *params)
@@ -108,14 +108,14 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
sess, m, params);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capabilities_get(struct rte_security_ctx *instance)
{
RTE_FUNC_PTR_OR_ERR_RET(*instance->ops->capabilities_get, NULL);
return instance->ops->capabilities_get(instance->device);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx)
{
diff --git a/lib/librte_security/rte_security.h b/lib/librte_security/rte_security.h
index 653929b99..176378e78 100644
--- a/lib/librte_security/rte_security.h
+++ b/lib/librte_security/rte_security.h
@@ -52,6 +52,7 @@ extern "C" {
#include <netinet/ip.h>
#include <netinet/ip6.h>
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_crypto.h>
#include <rte_mbuf.h>
@@ -291,7 +292,7 @@ struct rte_security_session {
* - On success, pointer to session
* - On failure, NULL
*/
-struct rte_security_session *
+struct rte_security_session * __experimental
rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp);
@@ -306,7 +307,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
* - On success returns 0
* - On failure return errno
*/
-int
+int __experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf);
@@ -323,7 +324,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
* - -EINVAL if session is NULL.
* - -EBUSY if not all device private data has been freed.
*/
-int
+int __experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess);
@@ -340,7 +341,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
* - On success, zero.
* - On failure, a negative value.
*/
-int
+int __experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *mb, void *params);
@@ -351,7 +352,7 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
* @param sym_op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __experimental
__rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
struct rte_security_session *sess)
{
@@ -360,13 +361,13 @@ __rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
return 0;
}
-static inline void *
+static inline void * __experimental
get_sec_session_private_data(const struct rte_security_session *sess)
{
return sess->sess_private_data;
}
-static inline void
+static inline void __experimental
set_sec_session_private_data(struct rte_security_session *sess,
void *private_data)
{
@@ -382,7 +383,7 @@ set_sec_session_private_data(struct rte_security_session *sess,
* @param op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __experimental
rte_security_attach_session(struct rte_crypto_op *op,
struct rte_security_session *sess)
{
@@ -424,7 +425,7 @@ struct rte_security_stats {
* - On success return 0
* - On failure errno
*/
-int
+int __experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats);
@@ -507,7 +508,7 @@ struct rte_security_capability_idx {
* - Returns array of security capabilities.
* - Return NULL if no capabilities available.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capabilities_get(struct rte_security_ctx *instance);
/**
@@ -521,7 +522,7 @@ rte_security_capabilities_get(struct rte_security_ctx *instance);
* index criteria.
* - Return NULL if the capability not matched on security instance.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx);
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
` (3 preceding siblings ...)
2017-12-13 15:17 ` [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls Neil Horman
@ 2017-12-13 15:17 ` Neil Horman
2017-12-13 15:32 ` Bruce Richardson
` (2 more replies)
2017-12-13 15:32 ` [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
` (2 subsequent siblings)
7 siblings, 3 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-13 15:17 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson, Neil Horman
Document the need to add the __experimental tag to appropriate functions
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
doc/guides/contributing/versioning.rst | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
index 400090628..53f56397e 100644
--- a/doc/guides/contributing/versioning.rst
+++ b/doc/guides/contributing/versioning.rst
@@ -50,6 +50,15 @@ those new APIs and start finding issues with them, new DPDK APIs will be
automatically marked as ``experimental`` to allow for a period of stabilization
before they become part of a tracked ABI.
+Note that marking an API as experimental is a two 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 definitions of those exported functions, and
+their forward declarations (in the development header files), must be marked
+with the __experimental tag (see rte_compat.h). The DPDK build makefiles
+preform a check to ensure that the map file and the C code reflect the same
+list of symbols.
+
ABI versions, once released, are available until such time as their
deprecation has been noted in the Release Notes for at least one major release
cycle. For example consider the case where the ABI for DPDK 2.0 has been
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2017-12-13 15:17 ` [PATCHv4 5/5] doc: Add ABI __experimental tag documentation Neil Horman
@ 2017-12-13 15:32 ` Bruce Richardson
2018-01-11 20:06 ` Ferruh Yigit
2018-01-21 20:14 ` Thomas Monjalon
2 siblings, 0 replies; 83+ messages in thread
From: Bruce Richardson @ 2017-12-13 15:32 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, thomas, john.mcnamara
On Wed, Dec 13, 2017 at 10:17:28AM -0500, Neil Horman wrote:
> Document the need to add the __experimental tag to appropriate functions
>
> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> CC: Thomas Monjalon <thomas@monjalon.net>
> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> CC: Bruce Richardson <bruce.richardson@intel.com>
> ---
> doc/guides/contributing/versioning.rst | 9 +++++++++
> 1 file changed, 9 insertions(+)
>
> diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
> index 400090628..53f56397e 100644
> --- a/doc/guides/contributing/versioning.rst
> +++ b/doc/guides/contributing/versioning.rst
> @@ -50,6 +50,15 @@ those new APIs and start finding issues with them, new DPDK APIs will be
> automatically marked as ``experimental`` to allow for a period of stabilization
> before they become part of a tracked ABI.
>
> +Note that marking an API as experimental is a two 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 definitions of those exported functions, and
> +their forward declarations (in the development header files), must be marked
> +with the __experimental tag (see rte_compat.h). The DPDK build makefiles
> +preform a check to ensure that the map file and the C code reflect the same
> +list of symbols.
> +
Minor typo s/preform/perform/
> ABI versions, once released, are available until such time as their
> deprecation has been noted in the Release Notes for at least one major release
> cycle. For example consider the case where the ABI for DPDK 2.0 has been
> --
> 2.14.3
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
` (4 preceding siblings ...)
2017-12-13 15:17 ` [PATCHv4 5/5] doc: Add ABI __experimental tag documentation Neil Horman
@ 2017-12-13 15:32 ` Bruce Richardson
2017-12-21 14:21 ` Neil Horman
2017-12-30 19:20 ` Luca Boccassi
7 siblings, 0 replies; 83+ messages in thread
From: Bruce Richardson @ 2017-12-13 15:32 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, thomas, john.mcnamara
On Wed, Dec 13, 2017 at 10:17:23AM -0500, Neil Horman wrote:
> Hey all-
> A few days ago, I was lamenting the fact that, when reviewing patches I
> would frequently complain about ABI changes that were actually considered safe
> because they were part of the EXPERIMENTAL api set. John M. asked me then what
> I might do to improve the situation, and the following patch set is a proposal
> that I've come up with.
>
> In thinking about the problem I identified two issues that I think we
> can improve on in this area:
>
> 1) Make experimental api calls more visible in the source code. That is to say,
> when reviewing patches, it would be nice to have some sort of visual reference
> that indicates that the changes being made are part of an experimental API and
> therefore ABI concerns need not be addressed
>
> 2) Make experimenal api usage more visible to consumers of the DPDK, so that
> they can make a more informed decision about the API's they consume in their
> application. We make an effort to document all the experimental API's, but
> there is no guarantee that a user will check the documentation before making use
> of a new library.
>
> This patch set attempts to achieve both of the above goals. To do this I've
> added an __experimental macro tag, suitable for inserting into api forward
> declarations and definitions.
>
> The presence of the tag in the header and c files where the api code resides
> increases the likelyhood that any patch submitted against them will include the
> tag in the context, making it clear to reviewers that ABI stability isn't a
> concern here.
>
> Also, This tag marks each function it is used on with an attibute causing any
> use of the fuction to emit a warning during the build
> with a message indicating that the API call in question is not yet part of the
> stable interface. Developers can then make an informed decision to suppress
> that warning or not.
>
> Because there is internal use of several experimental API's, this set also
> includes a new override macro ALLOW_EXPERIMENTAL_APIS to automatically
> suprress these warnings. I think its fair to assume that, for internal use, we
> almost always want to suppress these warnings, as by definition any change to
> the apis (even their removal) must be done in parallel with an appropriate
> change in the calling locations, lest the dpdk build itself break.
>
> Neil
>
> ---
> Change Notes:
> v2)
> * Cleaned up checkpatch errors
> * Added Allowance for building experimental on BSD
> * Swapped Patch 3 and 4 so that we didn't have a commit level that issued
> warnings/errors without need
>
> v3)
> * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be defined in
> CFLAGS rather than a makefile variable. This is more flexible in that it
> allows us to suppress this specific feature rather than all uses of the
> deprecated attribute, as we might use it for other features in the furute
>
> v4)
> * Added documentation patch to contributors guide
>
Series Acked-by: Bruce Richardson <bruce.richardson@intel.com>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
` (5 preceding siblings ...)
2017-12-13 15:32 ` [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
@ 2017-12-21 14:21 ` Neil Horman
2017-12-30 19:20 ` Luca Boccassi
7 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-21 14:21 UTC (permalink / raw)
To: dev; +Cc: thomas, john.mcnamara, bruce.richardson
On Wed, Dec 13, 2017 at 10:17:23AM -0500, Neil Horman wrote:
> Hey all-
> A few days ago, I was lamenting the fact that, when reviewing patches I
> would frequently complain about ABI changes that were actually considered safe
> because they were part of the EXPERIMENTAL api set. John M. asked me then what
> I might do to improve the situation, and the following patch set is a proposal
> that I've come up with.
>
> In thinking about the problem I identified two issues that I think we
> can improve on in this area:
>
> 1) Make experimental api calls more visible in the source code. That is to say,
> when reviewing patches, it would be nice to have some sort of visual reference
> that indicates that the changes being made are part of an experimental API and
> therefore ABI concerns need not be addressed
>
> 2) Make experimenal api usage more visible to consumers of the DPDK, so that
> they can make a more informed decision about the API's they consume in their
> application. We make an effort to document all the experimental API's, but
> there is no guarantee that a user will check the documentation before making use
> of a new library.
>
> This patch set attempts to achieve both of the above goals. To do this I've
> added an __experimental macro tag, suitable for inserting into api forward
> declarations and definitions.
>
> The presence of the tag in the header and c files where the api code resides
> increases the likelyhood that any patch submitted against them will include the
> tag in the context, making it clear to reviewers that ABI stability isn't a
> concern here.
>
> Also, This tag marks each function it is used on with an attibute causing any
> use of the fuction to emit a warning during the build
> with a message indicating that the API call in question is not yet part of the
> stable interface. Developers can then make an informed decision to suppress
> that warning or not.
>
> Because there is internal use of several experimental API's, this set also
> includes a new override macro ALLOW_EXPERIMENTAL_APIS to automatically
> suprress these warnings. I think its fair to assume that, for internal use, we
> almost always want to suppress these warnings, as by definition any change to
> the apis (even their removal) must be done in parallel with an appropriate
> change in the calling locations, lest the dpdk build itself break.
>
> Neil
>
> ---
> Change Notes:
> v2)
> * Cleaned up checkpatch errors
> * Added Allowance for building experimental on BSD
> * Swapped Patch 3 and 4 so that we didn't have a commit level that issued
> warnings/errors without need
>
> v3)
> * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be defined in
> CFLAGS rather than a makefile variable. This is more flexible in that it
> allows us to suppress this specific feature rather than all uses of the
> deprecated attribute, as we might use it for other features in the furute
>
> v4)
> * Added documentation patch to contributors guide
>
>
Ping, can I get some more reviews/acks here please?
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-12 14:07 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
@ 2017-12-30 17:15 ` Neil Horman
2018-01-04 12:56 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2017-12-30 17:15 UTC (permalink / raw)
To: Bruce Richardson; +Cc: dev, thomas, john.mcnamara
On Tue, Dec 12, 2017 at 02:07:52PM +0000, Bruce Richardson wrote:
> On Mon, Dec 11, 2017 at 02:36:15PM -0500, Neil Horman wrote:
> > Hey all-
> > A few days ago, I was lamenting the fact that, when reviewing patches I
> > would frequently complain about ABI changes that were actually considered safe
> > because they were part of the EXPERIMENTAL api set. John M. asked me then what
> > I might do to improve the situation, and the following patch set is a proposal
> > that I've come up with.
> >
> > In thinking about the problem I identified two issues that I think we
> > can improve on in this area:
> >
> > 1) Make experimental api calls more visible in the source code. That is to say,
> > when reviewing patches, it would be nice to have some sort of visual reference
> > that indicates that the changes being made are part of an experimental API and
> > therefore ABI concerns need not be addressed
> >
> > 2) Make experimenal api usage more visible to consumers of the DPDK, so that
> > they can make a more informed decision about the API's they consume in their
> > application. We make an effort to document all the experimental API's, but
> > there is no guarantee that a user will check the documentation before making use
> > of a new library.
> >
> > This patch set attempts to achieve both of the above goals. To do this I've
> > added an __experimental macro tag, suitable for inserting into api forward
> > declarations and definitions.
> >
> > The presence of the tag in the header and c files where the api code resides
> > increases the likelyhood that any patch submitted against them will include the
> > tag in the context, making it clear to reviewers that ABI stability isn't a
> > concern here.
> >
> >
> > Also, This tag marks each function it is used on with an attibute causing any
> > use of the fuction to emit a warning during the build
> > with a message indicating that the API call in question is not yet part of the
> > stable interface. Developers can then make an informed decision to suppress
> > that warning or not.
> >
> > Because there is internal use of several experimental API's, this set also
> > includes a new override macro ALLOW_EXPERIMENTAL_APIS to automatically
> > suprress these warnings. I think its fair to assume that, for internal use, we
> > almost always want to suppress these warnings, as by definition any change to
> > the apis (even their removal) must be done in parallel with an appropriate
> > change in the calling locations, lest the dpdk build itself break.
> >
> > Neil
> >
> > ---
> > Change Notes:
> > v2)
> > * Cleaned up checkpatch errors
> > * Added Allowance for building experimental on BSD
> > * Swapped Patch 3 and 4 so that we didn't have a commit level that issued
> > warnings/errors without need
> >
> > v3)
> > * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be defined in
> > CFLAGS rather than a makefile variable. This is more flexible in that it
> > allows us to suppress this specific feature rather than all uses of the
> > deprecated attribute, as we might use it for other features in the furute
> >
>
> Despite the fact that this is making yet more work for porting to a new
> build system, I think this is a good idea to have. As such,
>
> Acked-by: Bruce Richardson <bruce.richardson@intel.com>
>
>
Thomas-
I just noticed that the ci tests are failing on the intel compiler, which
makes very little sense to me, as the error is a permission error on a bash
script that added in this series, which works during the gcc compilation. Can
you take a look at that please?
thanks
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
` (6 preceding siblings ...)
2017-12-21 14:21 ` Neil Horman
@ 2017-12-30 19:20 ` Luca Boccassi
2017-12-31 1:57 ` Neil Horman
7 siblings, 1 reply; 83+ messages in thread
From: Luca Boccassi @ 2017-12-30 19:20 UTC (permalink / raw)
To: Neil Horman, dev
On Wed, 2017-12-13 at 10:17 -0500, Neil Horman wrote:
> Hey all-
> A few days ago, I was lamenting the fact that, when reviewing
> patches I
> would frequently complain about ABI changes that were actually
> considered safe
> because they were part of the EXPERIMENTAL api set. John M. asked me
> then what
> I might do to improve the situation, and the following patch set is a
> proposal
> that I've come up with.
>
> In thinking about the problem I identified two issues that I
> think we
> can improve on in this area:
>
> 1) Make experimental api calls more visible in the source code. That
> is to say,
> when reviewing patches, it would be nice to have some sort of visual
> reference
> that indicates that the changes being made are part of an
> experimental API and
> therefore ABI concerns need not be addressed
>
> 2) Make experimenal api usage more visible to consumers of the DPDK,
> so that
> they can make a more informed decision about the API's they consume
> in their
> application. We make an effort to document all the experimental
> API's, but
> there is no guarantee that a user will check the documentation before
> making use
> of a new library.
>
> This patch set attempts to achieve both of the above goals. To do
> this I've
> added an __experimental macro tag, suitable for inserting into api
> forward
> declarations and definitions.
>
> The presence of the tag in the header and c files where the api code
> resides
> increases the likelyhood that any patch submitted against them will
> include the
> tag in the context, making it clear to reviewers that ABI stability
> isn't a
> concern here.
>
> Also, This tag marks each function it is used on with an attibute
> causing any
> use of the fuction to emit a warning during the build
> with a message indicating that the API call in question is not yet
> part of the
> stable interface. Developers can then make an informed decision to
> suppress
> that warning or not.
>
> Because there is internal use of several experimental API's, this set
> also
> includes a new override macro ALLOW_EXPERIMENTAL_APIS to
> automatically
> suprress these warnings. I think its fair to assume that, for
> internal use, we
> almost always want to suppress these warnings, as by definition any
> change to
> the apis (even their removal) must be done in parallel with an
> appropriate
> change in the calling locations, lest the dpdk build itself break.
>
> Neil
>
> ---
> Change Notes:
> v2)
> * Cleaned up checkpatch errors
> * Added Allowance for building experimental on BSD
> * Swapped Patch 3 and 4 so that we didn't have a commit level that
> issued
> warnings/errors without need
>
> v3)
> * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be
> defined in
> CFLAGS rather than a makefile variable. This is more flexible in
> that it
> allows us to suppress this specific feature rather than all uses of
> the
> deprecated attribute, as we might use it for other features in the
> furute
>
> v4)
> * Added documentation patch to contributors guide
Acked-by: Luca Boccassi <bluca@debian.org>
I really like the idea of showing warnings at build time for users of
the libraries, in fact I like it so much I'm going to shamelessly steal
it for another few projects I work on where we have an experimental
(DRAFT) api system :-)
--
Kind regards,
Luca Boccassi
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-30 19:20 ` Luca Boccassi
@ 2017-12-31 1:57 ` Neil Horman
0 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2017-12-31 1:57 UTC (permalink / raw)
To: Luca Boccassi; +Cc: dev
On Sat, Dec 30, 2017 at 08:20:58PM +0100, Luca Boccassi wrote:
> On Wed, 2017-12-13 at 10:17 -0500, Neil Horman wrote:
> > Hey all-
> > A few days ago, I was lamenting the fact that, when reviewing
> > patches I
> > would frequently complain about ABI changes that were actually
> > considered safe
> > because they were part of the EXPERIMENTAL api set. John M. asked me
> > then what
> > I might do to improve the situation, and the following patch set is a
> > proposal
> > that I've come up with.
> >
> > In thinking about the problem I identified two issues that I
> > think we
> > can improve on in this area:
> >
> > 1) Make experimental api calls more visible in the source code. That
> > is to say,
> > when reviewing patches, it would be nice to have some sort of visual
> > reference
> > that indicates that the changes being made are part of an
> > experimental API and
> > therefore ABI concerns need not be addressed
> >
> > 2) Make experimenal api usage more visible to consumers of the DPDK,
> > so that
> > they can make a more informed decision about the API's they consume
> > in their
> > application. We make an effort to document all the experimental
> > API's, but
> > there is no guarantee that a user will check the documentation before
> > making use
> > of a new library.
> >
> > This patch set attempts to achieve both of the above goals. To do
> > this I've
> > added an __experimental macro tag, suitable for inserting into api
> > forward
> > declarations and definitions.
> >
> > The presence of the tag in the header and c files where the api code
> > resides
> > increases the likelyhood that any patch submitted against them will
> > include the
> > tag in the context, making it clear to reviewers that ABI stability
> > isn't a
> > concern here.
> >
> > Also, This tag marks each function it is used on with an attibute
> > causing any
> > use of the fuction to emit a warning during the build
> > with a message indicating that the API call in question is not yet
> > part of the
> > stable interface. Developers can then make an informed decision to
> > suppress
> > that warning or not.
> >
> > Because there is internal use of several experimental API's, this set
> > also
> > includes a new override macro ALLOW_EXPERIMENTAL_APIS to
> > automatically
> > suprress these warnings. I think its fair to assume that, for
> > internal use, we
> > almost always want to suppress these warnings, as by definition any
> > change to
> > the apis (even their removal) must be done in parallel with an
> > appropriate
> > change in the calling locations, lest the dpdk build itself break.
> >
> > Neil
> >
> > ---
> > Change Notes:
> > v2)
> > * Cleaned up checkpatch errors
> > * Added Allowance for building experimental on BSD
> > * Swapped Patch 3 and 4 so that we didn't have a commit level that
> > issued
> > warnings/errors without need
> >
> > v3)
> > * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be
> > defined in
> > CFLAGS rather than a makefile variable. This is more flexible in
> > that it
> > allows us to suppress this specific feature rather than all uses of
> > the
> > deprecated attribute, as we might use it for other features in the
> > furute
> >
> > v4)
> > * Added documentation patch to contributors guide
>
> Acked-by: Luca Boccassi <bluca@debian.org>
>
> I really like the idea of showing warnings at build time for users of
> the libraries, in fact I like it so much I'm going to shamelessly steal
> it for another few projects I work on where we have an experimental
> (DRAFT) api system :-)
>
You're welcome to it :)
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2017-12-30 17:15 ` Neil Horman
@ 2018-01-04 12:56 ` Neil Horman
2018-01-05 14:08 ` Thomas Monjalon
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-04 12:56 UTC (permalink / raw)
To: Bruce Richardson; +Cc: dev, thomas, john.mcnamara
On Sat, Dec 30, 2017 at 12:15:17PM -0500, Neil Horman wrote:
> On Tue, Dec 12, 2017 at 02:07:52PM +0000, Bruce Richardson wrote:
> > On Mon, Dec 11, 2017 at 02:36:15PM -0500, Neil Horman wrote:
> > > Hey all-
> > > A few days ago, I was lamenting the fact that, when reviewing patches I
> > > would frequently complain about ABI changes that were actually considered safe
> > > because they were part of the EXPERIMENTAL api set. John M. asked me then what
> > > I might do to improve the situation, and the following patch set is a proposal
> > > that I've come up with.
> > >
> > > In thinking about the problem I identified two issues that I think we
> > > can improve on in this area:
> > >
> > > 1) Make experimental api calls more visible in the source code. That is to say,
> > > when reviewing patches, it would be nice to have some sort of visual reference
> > > that indicates that the changes being made are part of an experimental API and
> > > therefore ABI concerns need not be addressed
> > >
> > > 2) Make experimenal api usage more visible to consumers of the DPDK, so that
> > > they can make a more informed decision about the API's they consume in their
> > > application. We make an effort to document all the experimental API's, but
> > > there is no guarantee that a user will check the documentation before making use
> > > of a new library.
> > >
> > > This patch set attempts to achieve both of the above goals. To do this I've
> > > added an __experimental macro tag, suitable for inserting into api forward
> > > declarations and definitions.
> > >
> > > The presence of the tag in the header and c files where the api code resides
> > > increases the likelyhood that any patch submitted against them will include the
> > > tag in the context, making it clear to reviewers that ABI stability isn't a
> > > concern here.
> > >
> > >
> > > Also, This tag marks each function it is used on with an attibute causing any
> > > use of the fuction to emit a warning during the build
> > > with a message indicating that the API call in question is not yet part of the
> > > stable interface. Developers can then make an informed decision to suppress
> > > that warning or not.
> > >
> > > Because there is internal use of several experimental API's, this set also
> > > includes a new override macro ALLOW_EXPERIMENTAL_APIS to automatically
> > > suprress these warnings. I think its fair to assume that, for internal use, we
> > > almost always want to suppress these warnings, as by definition any change to
> > > the apis (even their removal) must be done in parallel with an appropriate
> > > change in the calling locations, lest the dpdk build itself break.
> > >
> > > Neil
> > >
> > > ---
> > > Change Notes:
> > > v2)
> > > * Cleaned up checkpatch errors
> > > * Added Allowance for building experimental on BSD
> > > * Swapped Patch 3 and 4 so that we didn't have a commit level that issued
> > > warnings/errors without need
> > >
> > > v3)
> > > * On suggestion from Bruce, modify ALLOW_EXPERIMENTAL_APIS to be defined in
> > > CFLAGS rather than a makefile variable. This is more flexible in that it
> > > allows us to suppress this specific feature rather than all uses of the
> > > deprecated attribute, as we might use it for other features in the furute
> > >
> >
> > Despite the fact that this is making yet more work for porting to a new
> > build system, I think this is a good idea to have. As such,
> >
> > Acked-by: Bruce Richardson <bruce.richardson@intel.com>
> >
> >
>
> Thomas-
> I just noticed that the ci tests are failing on the intel compiler, which
> makes very little sense to me, as the error is a permission error on a bash
> script that added in this series, which works during the gcc compilation. Can
> you take a look at that please?
>
> thanks
> Neil
>
Ping again Thomas, I've still heard nothing from you or the CI group about
getting more visibility into the odd permission problem in the CI runs this
seems to be encountering. I'd love to fix it, but the information in the report
is insufficient to have any idea whats going on and the problem does not occur
on local builds. Please advise.
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2018-01-04 12:56 ` Neil Horman
@ 2018-01-05 14:08 ` Thomas Monjalon
2018-01-05 16:00 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-05 14:08 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, Bruce Richardson, john.mcnamara, qian.q.xu, ci
04/01/2018 13:56, Neil Horman:
> On Sat, Dec 30, 2017 at 12:15:17PM -0500, Neil Horman wrote:
> > Thomas-
> > I just noticed that the ci tests are failing on the intel compiler, which
> > makes very little sense to me, as the error is a permission error on a bash
> > script that added in this series, which works during the gcc compilation. Can
> > you take a look at that please?
> >
> > thanks
> > Neil
> >
> Ping again Thomas, I've still heard nothing from you or the CI group about
> getting more visibility into the odd permission problem in the CI runs this
> seems to be encountering. I'd love to fix it, but the information in the report
> is insufficient to have any idea whats going on and the problem does not occur
> on local builds. Please advise.
Unfortunately, I have no clues about this setup.
The report is sent by sys_stv@intel.com.
Adding Qian as Cc.
The error is "buildtools/experimentalsyms.sh: Permission denied"
And the file mode is 100755.
Anyone from Intel to check what happens please?
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2018-01-05 14:08 ` Thomas Monjalon
@ 2018-01-05 16:00 ` Neil Horman
2018-01-09 1:32 ` [dpdk-ci] " Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-05 16:00 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: dev, Bruce Richardson, john.mcnamara, qian.q.xu, ci
On Fri, Jan 05, 2018 at 03:08:52PM +0100, Thomas Monjalon wrote:
> 04/01/2018 13:56, Neil Horman:
> > On Sat, Dec 30, 2017 at 12:15:17PM -0500, Neil Horman wrote:
> > > Thomas-
> > > I just noticed that the ci tests are failing on the intel compiler, which
> > > makes very little sense to me, as the error is a permission error on a bash
> > > script that added in this series, which works during the gcc compilation. Can
> > > you take a look at that please?
> > >
> > > thanks
> > > Neil
> > >
> > Ping again Thomas, I've still heard nothing from you or the CI group about
> > getting more visibility into the odd permission problem in the CI runs this
> > seems to be encountering. I'd love to fix it, but the information in the report
> > is insufficient to have any idea whats going on and the problem does not occur
> > on local builds. Please advise.
>
> Unfortunately, I have no clues about this setup.
> The report is sent by sys_stv@intel.com.
> Adding Qian as Cc.
>
> The error is "buildtools/experimentalsyms.sh: Permission denied"
> And the file mode is 100755.
>
> Anyone from Intel to check what happens please?
>
Thank you Thomas. I would really like to get this pushed in, as others have
acked it, but the lack of visibility into the CI errors is quite frustrating
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [dpdk-ci] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2018-01-05 16:00 ` Neil Horman
@ 2018-01-09 1:32 ` Neil Horman
2018-01-09 9:20 ` Thomas Monjalon
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-09 1:32 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: dev, Bruce Richardson, john.mcnamara, qian.q.xu, ci
On Fri, Jan 05, 2018 at 11:00:52AM -0500, Neil Horman wrote:
> On Fri, Jan 05, 2018 at 03:08:52PM +0100, Thomas Monjalon wrote:
> > 04/01/2018 13:56, Neil Horman:
> > > On Sat, Dec 30, 2017 at 12:15:17PM -0500, Neil Horman wrote:
> > > > Thomas-
> > > > I just noticed that the ci tests are failing on the intel compiler, which
> > > > makes very little sense to me, as the error is a permission error on a bash
> > > > script that added in this series, which works during the gcc compilation. Can
> > > > you take a look at that please?
> > > >
> > > > thanks
> > > > Neil
> > > >
> > > Ping again Thomas, I've still heard nothing from you or the CI group about
> > > getting more visibility into the odd permission problem in the CI runs this
> > > seems to be encountering. I'd love to fix it, but the information in the report
> > > is insufficient to have any idea whats going on and the problem does not occur
> > > on local builds. Please advise.
> >
> > Unfortunately, I have no clues about this setup.
> > The report is sent by sys_stv@intel.com.
> > Adding Qian as Cc.
> >
> > The error is "buildtools/experimentalsyms.sh: Permission denied"
> > And the file mode is 100755.
> >
> > Anyone from Intel to check what happens please?
> >
> Thank you Thomas. I would really like to get this pushed in, as others have
> acked it, but the lack of visibility into the CI errors is quite frustrating
> Neil
>
>
So I'm not sure where to go with this. I've emailed the ci group on their list,
I've asked them directly on this list, and asked you, Thomas for assistance in
getting hold of the ci maintainers, and there has been no response in over a
week now. This patch has been acked by a few people, and the builds work on
clang and gcc locally just fine. I'm inclined to ask you to take these patches
despite the ci errors. If the CI maintainers can't respond to needs for
visibility into the system, I don't think its reasonable to block patches based
on CI results.
Thoughts?
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [dpdk-ci] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2018-01-09 1:32 ` [dpdk-ci] " Neil Horman
@ 2018-01-09 9:20 ` Thomas Monjalon
2018-01-09 12:36 ` Neil Horman
2018-01-19 15:44 ` Neil Horman
0 siblings, 2 replies; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-09 9:20 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, Bruce Richardson, john.mcnamara, qian.q.xu, ci
09/01/2018 02:32, Neil Horman:
> On Fri, Jan 05, 2018 at 11:00:52AM -0500, Neil Horman wrote:
> > On Fri, Jan 05, 2018 at 03:08:52PM +0100, Thomas Monjalon wrote:
> > > 04/01/2018 13:56, Neil Horman:
> > > > On Sat, Dec 30, 2017 at 12:15:17PM -0500, Neil Horman wrote:
> > > > > Thomas-
> > > > > I just noticed that the ci tests are failing on the intel compiler, which
> > > > > makes very little sense to me, as the error is a permission error on a bash
> > > > > script that added in this series, which works during the gcc compilation. Can
> > > > > you take a look at that please?
> > > > >
> > > > > thanks
> > > > > Neil
> > > > >
> > > > Ping again Thomas, I've still heard nothing from you or the CI group about
> > > > getting more visibility into the odd permission problem in the CI runs this
> > > > seems to be encountering. I'd love to fix it, but the information in the report
> > > > is insufficient to have any idea whats going on and the problem does not occur
> > > > on local builds. Please advise.
> > >
> > > Unfortunately, I have no clues about this setup.
> > > The report is sent by sys_stv@intel.com.
> > > Adding Qian as Cc.
> > >
> > > The error is "buildtools/experimentalsyms.sh: Permission denied"
> > > And the file mode is 100755.
> > >
> > > Anyone from Intel to check what happens please?
> > >
> > Thank you Thomas. I would really like to get this pushed in, as others have
> > acked it, but the lack of visibility into the CI errors is quite frustrating
> > Neil
> >
> >
> So I'm not sure where to go with this. I've emailed the ci group on their list,
> I've asked them directly on this list, and asked you, Thomas for assistance in
> getting hold of the ci maintainers, and there has been no response in over a
> week now. This patch has been acked by a few people, and the builds work on
> clang and gcc locally just fine. I'm inclined to ask you to take these patches
> despite the ci errors. If the CI maintainers can't respond to needs for
> visibility into the system, I don't think its reasonable to block patches based
> on CI results.
>
> Thoughts?
> Neil
Yes, you're right, we can bypass this CI test.
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [dpdk-ci] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2018-01-09 9:20 ` Thomas Monjalon
@ 2018-01-09 12:36 ` Neil Horman
2018-01-19 15:44 ` Neil Horman
1 sibling, 0 replies; 83+ messages in thread
From: Neil Horman @ 2018-01-09 12:36 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: dev, Bruce Richardson, john.mcnamara, qian.q.xu, ci
On Tue, Jan 09, 2018 at 10:20:05AM +0100, Thomas Monjalon wrote:
> 09/01/2018 02:32, Neil Horman:
> > On Fri, Jan 05, 2018 at 11:00:52AM -0500, Neil Horman wrote:
> > > On Fri, Jan 05, 2018 at 03:08:52PM +0100, Thomas Monjalon wrote:
> > > > 04/01/2018 13:56, Neil Horman:
> > > > > On Sat, Dec 30, 2017 at 12:15:17PM -0500, Neil Horman wrote:
> > > > > > Thomas-
> > > > > > I just noticed that the ci tests are failing on the intel compiler, which
> > > > > > makes very little sense to me, as the error is a permission error on a bash
> > > > > > script that added in this series, which works during the gcc compilation. Can
> > > > > > you take a look at that please?
> > > > > >
> > > > > > thanks
> > > > > > Neil
> > > > > >
> > > > > Ping again Thomas, I've still heard nothing from you or the CI group about
> > > > > getting more visibility into the odd permission problem in the CI runs this
> > > > > seems to be encountering. I'd love to fix it, but the information in the report
> > > > > is insufficient to have any idea whats going on and the problem does not occur
> > > > > on local builds. Please advise.
> > > >
> > > > Unfortunately, I have no clues about this setup.
> > > > The report is sent by sys_stv@intel.com.
> > > > Adding Qian as Cc.
> > > >
> > > > The error is "buildtools/experimentalsyms.sh: Permission denied"
> > > > And the file mode is 100755.
> > > >
> > > > Anyone from Intel to check what happens please?
> > > >
> > > Thank you Thomas. I would really like to get this pushed in, as others have
> > > acked it, but the lack of visibility into the CI errors is quite frustrating
> > > Neil
> > >
> > >
> > So I'm not sure where to go with this. I've emailed the ci group on their list,
> > I've asked them directly on this list, and asked you, Thomas for assistance in
> > getting hold of the ci maintainers, and there has been no response in over a
> > week now. This patch has been acked by a few people, and the builds work on
> > clang and gcc locally just fine. I'm inclined to ask you to take these patches
> > despite the ci errors. If the CI maintainers can't respond to needs for
> > visibility into the system, I don't think its reasonable to block patches based
> > on CI results.
> >
> > Thoughts?
> > Neil
>
> Yes, you're right, we can bypass this CI test.
>
Thank you, much appreciated.
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls
2017-12-13 15:17 ` [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls Neil Horman
@ 2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 21:24 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Ferruh Yigit @ 2018-01-11 20:06 UTC (permalink / raw)
To: Neil Horman, dev; +Cc: thomas, john.mcnamara, bruce.richardson
On 12/13/2017 3:17 PM, Neil Horman wrote:
> Append the __experimental tag to api calls appearing in the EXPERIMENTAL
> section of their libraries version map
>
> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> CC: Thomas Monjalon <thomas@monjalon.net>
> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> CC: Bruce Richardson <bruce.richardson@intel.com>
> ---
> lib/librte_eal/common/eal_common_dev.c | 6 ++-
> lib/librte_eal/common/eal_common_devargs.c | 7 +--
> lib/librte_eal/common/include/rte_dev.h | 6 ++-
> lib/librte_eal/common/include/rte_devargs.h | 8 ++--
> lib/librte_eal/common/include/rte_service.h | 47 ++++++++++---------
> .../common/include/rte_service_component.h | 14 +++---
> lib/librte_eal/common/rte_service.c | 52 ++++++++++++----------
> lib/librte_eal/linuxapp/eal/eal.c | 1 +
> lib/librte_ether/rte_mtr.c | 25 ++++++-----
> lib/librte_ether/rte_mtr.h | 26 +++++------
> lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
> lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
> lib/librte_security/rte_security.c | 16 +++----
> lib/librte_security/rte_security.h | 23 +++++-----
It may not be the responsibility of this patchset, but there are more
experimental APIs in DPDK.
Using EXPERIMENTAL tag in linker script is relatively new approach and this was
not a requirement, so many experimental APIs are documented in API documentation
(header file doxygen comment).
Sample: librte_member
It is required to scan all header files and update their linker scripts for the
experimental APIs.
> 14 files changed, 139 insertions(+), 116 deletions(-)
<...>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-13 15:17 ` [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
@ 2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 20:50 ` Neil Horman
2018-01-21 18:50 ` Thomas Monjalon
1 sibling, 1 reply; 83+ messages in thread
From: Ferruh Yigit @ 2018-01-11 20:06 UTC (permalink / raw)
To: Neil Horman, dev; +Cc: thomas, john.mcnamara, bruce.richardson
On 12/13/2017 3:17 PM, Neil Horman wrote:
> Add checks during build to ensure that all symbols in the EXPERIMENTAL
> version map section have __experimental tags on their definitions, and
> enable the warnings needed to announce their use. Also add an
> ALLOW_EXPERIMENTAL_APIS define to allow individual libraries and files
> to declare the acceptability of experimental api usage
>
> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> CC: Thomas Monjalon <thomas@monjalon.net>
> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> CC: Bruce Richardson <bruce.richardson@intel.com>
> ---
> app/test-eventdev/Makefile | 1 +
> app/test-pmd/Makefile | 1 +
> drivers/event/sw/Makefile | 1 +
> drivers/net/failsafe/Makefile | 1 +
> drivers/net/ixgbe/Makefile | 1 +
> examples/eventdev_pipeline_sw_pmd/Makefile | 1 +
> examples/flow_classify/Makefile | 1 +
> examples/ipsec-secgw/Makefile | 1 +
> examples/service_cores/Makefile | 1 +
> lib/librte_eal/bsdapp/eal/Makefile | 1 +
> lib/librte_eal/linuxapp/Makefile | 2 ++
> lib/librte_eal/linuxapp/eal/Makefile | 2 ++
> lib/librte_eventdev/Makefile | 1 +
> lib/librte_security/Makefile | 1 +
> mk/internal/rte.compile-pre.mk | 4 ++++
> mk/toolchain/clang/rte.vars.mk | 2 +-
> mk/toolchain/gcc/rte.vars.mk | 2 +-
> mk/toolchain/icc/rte.vars.mk | 2 +-
> 18 files changed, 23 insertions(+), 3 deletions(-)
>
> diff --git a/app/test-eventdev/Makefile b/app/test-eventdev/Makefile
> index dcb2ac476..78bae7633 100644
> --- a/app/test-eventdev/Makefile
> +++ b/app/test-eventdev/Makefile
> @@ -32,6 +32,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
>
> APP = dpdk-test-eventdev
>
> +CFLAGS += -DALLOW_EXPERIMENTAL_APIS
Do we need this internally in DPDK? For application developers this is great,
they will get warning unless explicitly stated that they are OK with it.
Do we have any option than allowing them in DPDK library? And when experimental
API modified the users in the DPDK library internally guaranteed to be updated.
Why not globally allow this for all DPDK internally?
> CFLAGS += -O3
> CFLAGS += $(WERROR_FLAGS)
>
<...>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2017-12-13 15:17 ` [PATCHv4 5/5] doc: Add ABI __experimental tag documentation Neil Horman
2017-12-13 15:32 ` Bruce Richardson
@ 2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 21:29 ` Neil Horman
2018-01-21 20:14 ` Thomas Monjalon
2 siblings, 1 reply; 83+ messages in thread
From: Ferruh Yigit @ 2018-01-11 20:06 UTC (permalink / raw)
To: Neil Horman, dev; +Cc: thomas, john.mcnamara, bruce.richardson
On 12/13/2017 3:17 PM, Neil Horman wrote:
> Document the need to add the __experimental tag to appropriate functions
>
> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> CC: Thomas Monjalon <thomas@monjalon.net>
> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> CC: Bruce Richardson <bruce.richardson@intel.com>
> ---
> doc/guides/contributing/versioning.rst | 9 +++++++++
> 1 file changed, 9 insertions(+)
>
> diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
> index 400090628..53f56397e 100644
> --- a/doc/guides/contributing/versioning.rst
> +++ b/doc/guides/contributing/versioning.rst
> @@ -50,6 +50,15 @@ those new APIs and start finding issues with them, new DPDK APIs will be
> automatically marked as ``experimental`` to allow for a period of stabilization
> before they become part of a tracked ABI.
>
> +Note that marking an API as experimental is a two 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 definitions of those exported functions, and
> +their forward declarations (in the development header files), must be marked
> +with the __experimental tag (see rte_compat.h). The DPDK build makefiles
> +preform a check to ensure that the map file and the C code reflect the same
> +list of symbols.
There are more steps we historically do to mark an API as experimental:
- Add to function header comment experimental for API documentation, preferably
with a warning tag to highlight it:
/**
* @warning
* @b EXPERIMENTAL:
....
*/
- If whole APIs in header file are experimental, add same experimental warning
doxygen comment in file comment, again preferably with warning.
- If whole library is experimental, put EXPERIMENTAL tag into maintainers file
as well.
> +
> ABI versions, once released, are available until such time as their
> deprecation has been noted in the Release Notes for at least one major release
> cycle. For example consider the case where the ABI for DPDK 2.0 has been
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2018-01-11 20:06 ` Ferruh Yigit
@ 2018-01-11 20:50 ` Neil Horman
2018-01-12 11:49 ` Ferruh Yigit
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-11 20:50 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On Thu, Jan 11, 2018 at 08:06:43PM +0000, Ferruh Yigit wrote:
> On 12/13/2017 3:17 PM, Neil Horman wrote:
> > Add checks during build to ensure that all symbols in the EXPERIMENTAL
> > version map section have __experimental tags on their definitions, and
> > enable the warnings needed to announce their use. Also add an
> > ALLOW_EXPERIMENTAL_APIS define to allow individual libraries and files
> > to declare the acceptability of experimental api usage
> >
> > Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> > CC: Thomas Monjalon <thomas@monjalon.net>
> > CC: "Mcnamara, John" <john.mcnamara@intel.com>
> > CC: Bruce Richardson <bruce.richardson@intel.com>
> > ---
> > app/test-eventdev/Makefile | 1 +
> > app/test-pmd/Makefile | 1 +
> > drivers/event/sw/Makefile | 1 +
> > drivers/net/failsafe/Makefile | 1 +
> > drivers/net/ixgbe/Makefile | 1 +
> > examples/eventdev_pipeline_sw_pmd/Makefile | 1 +
> > examples/flow_classify/Makefile | 1 +
> > examples/ipsec-secgw/Makefile | 1 +
> > examples/service_cores/Makefile | 1 +
> > lib/librte_eal/bsdapp/eal/Makefile | 1 +
> > lib/librte_eal/linuxapp/Makefile | 2 ++
> > lib/librte_eal/linuxapp/eal/Makefile | 2 ++
> > lib/librte_eventdev/Makefile | 1 +
> > lib/librte_security/Makefile | 1 +
> > mk/internal/rte.compile-pre.mk | 4 ++++
> > mk/toolchain/clang/rte.vars.mk | 2 +-
> > mk/toolchain/gcc/rte.vars.mk | 2 +-
> > mk/toolchain/icc/rte.vars.mk | 2 +-
> > 18 files changed, 23 insertions(+), 3 deletions(-)
> >
> > diff --git a/app/test-eventdev/Makefile b/app/test-eventdev/Makefile
> > index dcb2ac476..78bae7633 100644
> > --- a/app/test-eventdev/Makefile
> > +++ b/app/test-eventdev/Makefile
> > @@ -32,6 +32,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
> >
> > APP = dpdk-test-eventdev
> >
> > +CFLAGS += -DALLOW_EXPERIMENTAL_APIS
>
> Do we need this internally in DPDK? For application developers this is great,
> they will get warning unless explicitly stated that they are OK with it.
>
I'm not sure what you're asking here. As I mentioned in the initial post, I
think we should give blanket permission to any in-tree dpdk library to allow the
use of experimental API's, but that doesn't really imply that all developers
would wan't it disabled all the time. That is to say, I could envision a
library author who, early in development would want to get a warning issued if
they used an unstable API, and, only once they were happy with their design and
choice of API usage, turn the warning off.
> Do we have any option than allowing them in DPDK library? And when experimental
> API modified the users in the DPDK library internally guaranteed to be updated.
> Why not globally allow this for all DPDK internally?
>
For the reason I gave above. We certainly could enable this in a more top-level
makefile so that for in-library systems it was opt-in rather than opt-out, but I
chose a more granular approach because I could envision newer libraries wanting
it on. I also felt, generally speaking, that where warning flags were
concerned, it generally desireous to have them on by default, and make people
explicitly choose to turn them off.
Regards
Neil
> > CFLAGS += -O3
> > CFLAGS += $(WERROR_FLAGS)
> >
>
> <...>
>
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls
2018-01-11 20:06 ` Ferruh Yigit
@ 2018-01-11 21:24 ` Neil Horman
2018-01-12 11:50 ` Ferruh Yigit
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-11 21:24 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On Thu, Jan 11, 2018 at 08:06:33PM +0000, Ferruh Yigit wrote:
> On 12/13/2017 3:17 PM, Neil Horman wrote:
> > Append the __experimental tag to api calls appearing in the EXPERIMENTAL
> > section of their libraries version map
> >
> > Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> > CC: Thomas Monjalon <thomas@monjalon.net>
> > CC: "Mcnamara, John" <john.mcnamara@intel.com>
> > CC: Bruce Richardson <bruce.richardson@intel.com>
> > ---
> > lib/librte_eal/common/eal_common_dev.c | 6 ++-
> > lib/librte_eal/common/eal_common_devargs.c | 7 +--
> > lib/librte_eal/common/include/rte_dev.h | 6 ++-
> > lib/librte_eal/common/include/rte_devargs.h | 8 ++--
> > lib/librte_eal/common/include/rte_service.h | 47 ++++++++++---------
> > .../common/include/rte_service_component.h | 14 +++---
> > lib/librte_eal/common/rte_service.c | 52 ++++++++++++----------
> > lib/librte_eal/linuxapp/eal/eal.c | 1 +
> > lib/librte_ether/rte_mtr.c | 25 ++++++-----
> > lib/librte_ether/rte_mtr.h | 26 +++++------
> > lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
> > lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
> > lib/librte_security/rte_security.c | 16 +++----
> > lib/librte_security/rte_security.h | 23 +++++-----
>
> It may not be the responsibility of this patchset, but there are more
> experimental APIs in DPDK.
>
Thats an interesting statement to make. This patchset creates a build time
check that compares symbols located in the EXPERIMENTAL version section of a
libraries' version map file to the symbols that are marked with this new tag,
throwing an error if they don't match. I believe what you say in that there may
be additional APIs that are experimental, but given that, I would have to
conclude one of the following:
1) The missing API's are macros or static inline functions that are not exported
from libraries directly
2) The documentation for experimental API's are out of sync, in that they have
legitimately moved to be supported API's and the documentation needs to be
updated
3) There are API's which are experimental that have been incorrectly placed in a
versioned tag.
I made a pretty good effort to scan comments for the word EXPERIMENTAL so that I
could catch item (1). And while I may not have caught them all, I'd like to
think I got a good chunk of them. That leaves cleanup of (2) and (3), which I
think this patchset can help us idenfity.
> Using EXPERIMENTAL tag in linker script is relatively new approach and this was
> not a requirement, so many experimental APIs are documented in API documentation
> (header file doxygen comment).
> Sample: librte_member
>
That sounds like case (3) above.
Thats a bit odd. I understand that the use of the EXPERIMENTAL version tag is
new, but once it was introduced it should have been made a requirement. There
would have been no penalty for moving the version number (as doing so would not
have violated ABI guarantees, given that those API's were appropriately
documented as experimental). If they have not been, then the use of the
EXPERIMENTAL tag isn't overly useful, as it doesn't provide any segregation of
the stable ABI from the unstable ABI.
> It is required to scan all header files and update their linker scripts for the
> experimental APIs.
>
Yes and no. If a given library is not marked as experimental in its version
map, this change won't flag it as a problem, but if its intended to be
experimental (i.e. if its likely to have its ABI fluctuate), then yes, we should
take the appropriate steps to flag it as such properly.
If a given library is intended to be experimental, I would say yes,
the author should make the appropriate chage to the version map, and then the
corresponding change to the headers and c files with this new tag.
Alternatively, they might choose to simply update the documentation to reflect
the fact that the ABI for that library is now stable.
The thing that should definately not hapen though, is a half measure. We
shouldn't allow libraries to call themselves experimental, and then excuse them
from any rules we have regarding their in-code representation. If we have an
EXPERIMENTAL version in the map, we should require its use, and by extension
require this tag when its merged for the reasons previously outlined
Neil
> > 14 files changed, 139 insertions(+), 116 deletions(-)
>
> <...>
>
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2018-01-11 20:06 ` Ferruh Yigit
@ 2018-01-11 21:29 ` Neil Horman
2018-01-12 11:50 ` Ferruh Yigit
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-11 21:29 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On Thu, Jan 11, 2018 at 08:06:48PM +0000, Ferruh Yigit wrote:
> On 12/13/2017 3:17 PM, Neil Horman wrote:
> > Document the need to add the __experimental tag to appropriate functions
> >
> > Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> > CC: Thomas Monjalon <thomas@monjalon.net>
> > CC: "Mcnamara, John" <john.mcnamara@intel.com>
> > CC: Bruce Richardson <bruce.richardson@intel.com>
> > ---
> > doc/guides/contributing/versioning.rst | 9 +++++++++
> > 1 file changed, 9 insertions(+)
> >
> > diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
> > index 400090628..53f56397e 100644
> > --- a/doc/guides/contributing/versioning.rst
> > +++ b/doc/guides/contributing/versioning.rst
> > @@ -50,6 +50,15 @@ those new APIs and start finding issues with them, new DPDK APIs will be
> > automatically marked as ``experimental`` to allow for a period of stabilization
> > before they become part of a tracked ABI.
> >
> > +Note that marking an API as experimental is a two 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 definitions of those exported functions, and
> > +their forward declarations (in the development header files), must be marked
> > +with the __experimental tag (see rte_compat.h). The DPDK build makefiles
> > +preform a check to ensure that the map file and the C code reflect the same
> > +list of symbols.
>
> There are more steps we historically do to mark an API as experimental:
> - Add to function header comment experimental for API documentation, preferably
> with a warning tag to highlight it:
>
> /**
> * @warning
> * @b EXPERIMENTAL:
> ....
> */
>
> - If whole APIs in header file are experimental, add same experimental warning
> doxygen comment in file comment, again preferably with warning.
>
> - If whole library is experimental, put EXPERIMENTAL tag into maintainers file
> as well.
>
Is that documented somewhere? I'd like to add this to the same location that it
otherwise is written out. The above location was the only place in the guide
that I could find reference to experimental markings.
> > +
> > ABI versions, once released, are available until such time as their
> > deprecation has been noted in the Release Notes for at least one major release
> > cycle. For example consider the case where the ABI for DPDK 2.0 has been
> >
>
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2018-01-11 20:50 ` Neil Horman
@ 2018-01-12 11:49 ` Ferruh Yigit
2018-01-12 12:44 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Ferruh Yigit @ 2018-01-12 11:49 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On 1/11/2018 8:50 PM, Neil Horman wrote:
> On Thu, Jan 11, 2018 at 08:06:43PM +0000, Ferruh Yigit wrote:
>> On 12/13/2017 3:17 PM, Neil Horman wrote:
>>> Add checks during build to ensure that all symbols in the EXPERIMENTAL
>>> version map section have __experimental tags on their definitions, and
>>> enable the warnings needed to announce their use. Also add an
>>> ALLOW_EXPERIMENTAL_APIS define to allow individual libraries and files
>>> to declare the acceptability of experimental api usage
>>>
>>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
>>> CC: Thomas Monjalon <thomas@monjalon.net>
>>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
>>> CC: Bruce Richardson <bruce.richardson@intel.com>
>>> ---
>>> app/test-eventdev/Makefile | 1 +
>>> app/test-pmd/Makefile | 1 +
>>> drivers/event/sw/Makefile | 1 +
>>> drivers/net/failsafe/Makefile | 1 +
>>> drivers/net/ixgbe/Makefile | 1 +
>>> examples/eventdev_pipeline_sw_pmd/Makefile | 1 +
>>> examples/flow_classify/Makefile | 1 +
>>> examples/ipsec-secgw/Makefile | 1 +
>>> examples/service_cores/Makefile | 1 +
>>> lib/librte_eal/bsdapp/eal/Makefile | 1 +
>>> lib/librte_eal/linuxapp/Makefile | 2 ++
>>> lib/librte_eal/linuxapp/eal/Makefile | 2 ++
>>> lib/librte_eventdev/Makefile | 1 +
>>> lib/librte_security/Makefile | 1 +
>>> mk/internal/rte.compile-pre.mk | 4 ++++
>>> mk/toolchain/clang/rte.vars.mk | 2 +-
>>> mk/toolchain/gcc/rte.vars.mk | 2 +-
>>> mk/toolchain/icc/rte.vars.mk | 2 +-
>>> 18 files changed, 23 insertions(+), 3 deletions(-)
>>>
>>> diff --git a/app/test-eventdev/Makefile b/app/test-eventdev/Makefile
>>> index dcb2ac476..78bae7633 100644
>>> --- a/app/test-eventdev/Makefile
>>> +++ b/app/test-eventdev/Makefile
>>> @@ -32,6 +32,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
>>>
>>> APP = dpdk-test-eventdev
>>>
>>> +CFLAGS += -DALLOW_EXPERIMENTAL_APIS
>>
>> Do we need this internally in DPDK? For application developers this is great,
>> they will get warning unless explicitly stated that they are OK with it.
>>
> I'm not sure what you're asking here. As I mentioned in the initial post, I
> think we should give blanket permission to any in-tree dpdk library to allow the
> use of experimental API's, but that doesn't really imply that all developers
> would wan't it disabled all the time. That is to say, I could envision a
> library author who, early in development would want to get a warning issued if
> they used an unstable API, and, only once they were happy with their design and
> choice of API usage, turn the warning off.
I got your point, but I think whoever using an experimental API in another
component in DPDK is almost always the author of the that experimental API, so
not sure this check is ever really needed within dpdk.
But OK, I guess it won't hurt to have more granular approach.
>
>> Do we have any option than allowing them in DPDK library? And when experimental
>> API modified the users in the DPDK library internally guaranteed to be updated.
>> Why not globally allow this for all DPDK internally?
>>
> For the reason I gave above. We certainly could enable this in a more top-level
> makefile so that for in-library systems it was opt-in rather than opt-out, but I
> chose a more granular approach because I could envision newer libraries wanting
> it on. I also felt, generally speaking, that where warning flags were
> concerned, it generally desireous to have them on by default, and make people
> explicitly choose to turn them off.
>
> Regards
> Neil
>
>
>>> CFLAGS += -O3
>>> CFLAGS += $(WERROR_FLAGS)
>>>
>>
>> <...>
>>
>>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls
2018-01-11 21:24 ` Neil Horman
@ 2018-01-12 11:50 ` Ferruh Yigit
2018-01-12 14:25 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Ferruh Yigit @ 2018-01-12 11:50 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On 1/11/2018 9:24 PM, Neil Horman wrote:
> On Thu, Jan 11, 2018 at 08:06:33PM +0000, Ferruh Yigit wrote:
>> On 12/13/2017 3:17 PM, Neil Horman wrote:
>>> Append the __experimental tag to api calls appearing in the EXPERIMENTAL
>>> section of their libraries version map
>>>
>>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
>>> CC: Thomas Monjalon <thomas@monjalon.net>
>>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
>>> CC: Bruce Richardson <bruce.richardson@intel.com>
>>> ---
>>> lib/librte_eal/common/eal_common_dev.c | 6 ++-
>>> lib/librte_eal/common/eal_common_devargs.c | 7 +--
>>> lib/librte_eal/common/include/rte_dev.h | 6 ++-
>>> lib/librte_eal/common/include/rte_devargs.h | 8 ++--
>>> lib/librte_eal/common/include/rte_service.h | 47 ++++++++++---------
>>> .../common/include/rte_service_component.h | 14 +++---
>>> lib/librte_eal/common/rte_service.c | 52 ++++++++++++----------
>>> lib/librte_eal/linuxapp/eal/eal.c | 1 +
>>> lib/librte_ether/rte_mtr.c | 25 ++++++-----
>>> lib/librte_ether/rte_mtr.h | 26 +++++------
>>> lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
>>> lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
>>> lib/librte_security/rte_security.c | 16 +++----
>>> lib/librte_security/rte_security.h | 23 +++++-----
>>
>> It may not be the responsibility of this patchset, but there are more
>> experimental APIs in DPDK.
>>
> Thats an interesting statement to make. This patchset creates a build time
> check that compares symbols located in the EXPERIMENTAL version section of a
> libraries' version map file to the symbols that are marked with this new tag,
> throwing an error if they don't match. I believe what you say in that there may
> be additional APIs that are experimental, but given that, I would have to
> conclude one of the following:
>
> 1) The missing API's are macros or static inline functions that are not exported
> from libraries directly
>
> 2) The documentation for experimental API's are out of sync, in that they have
> legitimately moved to be supported API's and the documentation needs to be
> updated
>
> 3) There are API's which are experimental that have been incorrectly placed in a
> versioned tag.
>
> I made a pretty good effort to scan comments for the word EXPERIMENTAL so that I
> could catch item (1). And while I may not have caught them all, I'd like to
> think I got a good chunk of them. That leaves cleanup of (2) and (3), which I
> think this patchset can help us idenfity.
>
>> Using EXPERIMENTAL tag in linker script is relatively new approach and this was
>> not a requirement, so many experimental APIs are documented in API documentation
>> (header file doxygen comment).
>> Sample: librte_member
>>
> That sounds like case (3) above.
>
> Thats a bit odd. I understand that the use of the EXPERIMENTAL version tag is
> new, but once it was introduced it should have been made a requirement. There
> would have been no penalty for moving the version number (as doing so would not
> have violated ABI guarantees, given that those API's were appropriately
> documented as experimental). If they have not been, then the use of the
> EXPERIMENTAL tag isn't overly useful, as it doesn't provide any segregation of
> the stable ABI from the unstable ABI.
>
>> It is required to scan all header files and update their linker scripts for the
>> experimental APIs.
>>
> Yes and no. If a given library is not marked as experimental in its version
> map, this change won't flag it as a problem, but if its intended to be
> experimental (i.e. if its likely to have its ABI fluctuate), then yes, we should
> take the appropriate steps to flag it as such properly.
>
> If a given library is intended to be experimental, I would say yes,
> the author should make the appropriate chage to the version map, and then the
> corresponding change to the headers and c files with this new tag.
> Alternatively, they might choose to simply update the documentation to reflect
> the fact that the ABI for that library is now stable.
>
> The thing that should definately not hapen though, is a half measure. We
> shouldn't allow libraries to call themselves experimental, and then excuse them
> from any rules we have regarding their in-code representation. If we have an
> EXPERIMENTAL version in the map, we should require its use, and by extension
> require this tag when its merged for the reasons previously outlined
My comment is for your item (3), but it is not fair to say "incorrectly placed"
because if I don't miss anything this has never been documented as correct way
to do, and lots of the existing usage is _before_ we start using EXPERIMENTAL
tag in the linker script, so they were doing right thing for that time.
Question is, is this patchset should fix them, since now this patchset defines
using EXPERIMENTAL tag in linker script as way to do it, or should we wait
maintainers to fix it after this has been documented. Waiting for maintainer may
take time because not all maintainers are following the mail list closely to
capture all expectations.
>
> Neil
>
>
>>> 14 files changed, 139 insertions(+), 116 deletions(-)
>>
>> <...>
>>
>>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2018-01-11 21:29 ` Neil Horman
@ 2018-01-12 11:50 ` Ferruh Yigit
2018-01-12 14:37 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Ferruh Yigit @ 2018-01-12 11:50 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On 1/11/2018 9:29 PM, Neil Horman wrote:
> On Thu, Jan 11, 2018 at 08:06:48PM +0000, Ferruh Yigit wrote:
>> On 12/13/2017 3:17 PM, Neil Horman wrote:
>>> Document the need to add the __experimental tag to appropriate functions
>>>
>>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
>>> CC: Thomas Monjalon <thomas@monjalon.net>
>>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
>>> CC: Bruce Richardson <bruce.richardson@intel.com>
<...>
>>> automatically marked as ``experimental`` to allow for a period of stabilization>>> before they become part of a tracked ABI.
Full sentences for above statement:
"
Since changes to APIs are most likely immediately after their introduction, as
users begin to take advantage of those new APIs and start finding issues with
them, new DPDK APIs will be automatically marked as experimental to allow for a
period of stabilization before they become part of a tracked ABI.
"
This part is not related to this patchset, but it will be hard to maintain above
behavior, "automatically marked" is not automatic now and moving them to stable
after one release is also not automatic. Do you have any suggestion on how to
manage this, do you think can your script be expanded to cover these checks?
>>>
>>> +Note that marking an API as experimental is a two 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 definitions of those exported functions, and
>>> +their forward declarations (in the development header files), must be marked
>>> +with the __experimental tag (see rte_compat.h). The DPDK build makefiles
>>> +preform a check to ensure that the map file and the C code reflect the same
>>> +list of symbols.
>>
>> There are more steps we historically do to mark an API as experimental:
>> - Add to function header comment experimental for API documentation, preferably
>> with a warning tag to highlight it:
>>
>> /**
>> * @warning
>> * @b EXPERIMENTAL:
>> ....
>> */
>>
>> - If whole APIs in header file are experimental, add same experimental warning
>> doxygen comment in file comment, again preferably with warning.
>>
>> - If whole library is experimental, put EXPERIMENTAL tag into maintainers file
>> as well.
>>
> Is that documented somewhere? I'd like to add this to the same location that it
> otherwise is written out. The above location was the only place in the guide
> that I could find reference to experimental markings.
As far as I know how to mark an API as experimental is not documented.
What do you think making a new section for this information?
>
>>> +
>>> ABI versions, once released, are available until such time as their
>>> deprecation has been noted in the Release Notes for at least one major release
>>> cycle. For example consider the case where the ABI for DPDK 2.0 has been
>>>
>>
>>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2018-01-12 11:49 ` Ferruh Yigit
@ 2018-01-12 12:44 ` Neil Horman
2018-01-21 18:54 ` Thomas Monjalon
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-12 12:44 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On Fri, Jan 12, 2018 at 11:49:57AM +0000, Ferruh Yigit wrote:
> On 1/11/2018 8:50 PM, Neil Horman wrote:
> > On Thu, Jan 11, 2018 at 08:06:43PM +0000, Ferruh Yigit wrote:
> >> On 12/13/2017 3:17 PM, Neil Horman wrote:
> >>> Add checks during build to ensure that all symbols in the EXPERIMENTAL
> >>> version map section have __experimental tags on their definitions, and
> >>> enable the warnings needed to announce their use. Also add an
> >>> ALLOW_EXPERIMENTAL_APIS define to allow individual libraries and files
> >>> to declare the acceptability of experimental api usage
> >>>
> >>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> >>> CC: Thomas Monjalon <thomas@monjalon.net>
> >>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> >>> CC: Bruce Richardson <bruce.richardson@intel.com>
> >>> ---
> >>> app/test-eventdev/Makefile | 1 +
> >>> app/test-pmd/Makefile | 1 +
> >>> drivers/event/sw/Makefile | 1 +
> >>> drivers/net/failsafe/Makefile | 1 +
> >>> drivers/net/ixgbe/Makefile | 1 +
> >>> examples/eventdev_pipeline_sw_pmd/Makefile | 1 +
> >>> examples/flow_classify/Makefile | 1 +
> >>> examples/ipsec-secgw/Makefile | 1 +
> >>> examples/service_cores/Makefile | 1 +
> >>> lib/librte_eal/bsdapp/eal/Makefile | 1 +
> >>> lib/librte_eal/linuxapp/Makefile | 2 ++
> >>> lib/librte_eal/linuxapp/eal/Makefile | 2 ++
> >>> lib/librte_eventdev/Makefile | 1 +
> >>> lib/librte_security/Makefile | 1 +
> >>> mk/internal/rte.compile-pre.mk | 4 ++++
> >>> mk/toolchain/clang/rte.vars.mk | 2 +-
> >>> mk/toolchain/gcc/rte.vars.mk | 2 +-
> >>> mk/toolchain/icc/rte.vars.mk | 2 +-
> >>> 18 files changed, 23 insertions(+), 3 deletions(-)
> >>>
> >>> diff --git a/app/test-eventdev/Makefile b/app/test-eventdev/Makefile
> >>> index dcb2ac476..78bae7633 100644
> >>> --- a/app/test-eventdev/Makefile
> >>> +++ b/app/test-eventdev/Makefile
> >>> @@ -32,6 +32,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
> >>>
> >>> APP = dpdk-test-eventdev
> >>>
> >>> +CFLAGS += -DALLOW_EXPERIMENTAL_APIS
> >>
> >> Do we need this internally in DPDK? For application developers this is great,
> >> they will get warning unless explicitly stated that they are OK with it.
> >>
> > I'm not sure what you're asking here. As I mentioned in the initial post, I
> > think we should give blanket permission to any in-tree dpdk library to allow the
> > use of experimental API's, but that doesn't really imply that all developers
> > would wan't it disabled all the time. That is to say, I could envision a
> > library author who, early in development would want to get a warning issued if
> > they used an unstable API, and, only once they were happy with their design and
> > choice of API usage, turn the warning off.
>
> I got your point, but I think whoever using an experimental API in another
> component in DPDK is almost always the author of the that experimental API, so
> not sure this check is ever really needed within dpdk.
>
I would have thought so too, but it doesn't really bear up. The example I used
to convince myself of a more granular approach was commit
9c38b704d280ac128003238d7d80bf07fa556a7d where the rte_service API was
introduced as experimental by Nikhil Rao, and then later used in the eal library
as part of commit a894d4815f79b0d76527d9c42b23327de1501711 by Harry van Haaren.
Its no big deal because, as we agree, internal usage should be considered safe,
but it seemed clear that differing authors were using each others code
(potentially oblivious to the experimental nature of those APIs)
> But OK, I guess it won't hurt to have more granular approach.
>
> >
> >> Do we have any option than allowing them in DPDK library? And when experimental
> >> API modified the users in the DPDK library internally guaranteed to be updated.
> >> Why not globally allow this for all DPDK internally?
> >>
> > For the reason I gave above. We certainly could enable this in a more top-level
> > makefile so that for in-library systems it was opt-in rather than opt-out, but I
> > chose a more granular approach because I could envision newer libraries wanting
> > it on. I also felt, generally speaking, that where warning flags were
> > concerned, it generally desireous to have them on by default, and make people
> > explicitly choose to turn them off.
> >
> > Regards
> > Neil
> >
> >
> >>> CFLAGS += -O3
> >>> CFLAGS += $(WERROR_FLAGS)
> >>>
> >>
> >> <...>
> >>
> >>
>
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls
2018-01-12 11:50 ` Ferruh Yigit
@ 2018-01-12 14:25 ` Neil Horman
2018-01-12 15:53 ` Ferruh Yigit
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-12 14:25 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On Fri, Jan 12, 2018 at 11:50:01AM +0000, Ferruh Yigit wrote:
> On 1/11/2018 9:24 PM, Neil Horman wrote:
> > On Thu, Jan 11, 2018 at 08:06:33PM +0000, Ferruh Yigit wrote:
> >> On 12/13/2017 3:17 PM, Neil Horman wrote:
> >>> Append the __experimental tag to api calls appearing in the EXPERIMENTAL
> >>> section of their libraries version map
> >>>
> >>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> >>> CC: Thomas Monjalon <thomas@monjalon.net>
> >>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> >>> CC: Bruce Richardson <bruce.richardson@intel.com>
> >>> ---
> >>> lib/librte_eal/common/eal_common_dev.c | 6 ++-
> >>> lib/librte_eal/common/eal_common_devargs.c | 7 +--
> >>> lib/librte_eal/common/include/rte_dev.h | 6 ++-
> >>> lib/librte_eal/common/include/rte_devargs.h | 8 ++--
> >>> lib/librte_eal/common/include/rte_service.h | 47 ++++++++++---------
> >>> .../common/include/rte_service_component.h | 14 +++---
> >>> lib/librte_eal/common/rte_service.c | 52 ++++++++++++----------
> >>> lib/librte_eal/linuxapp/eal/eal.c | 1 +
> >>> lib/librte_ether/rte_mtr.c | 25 ++++++-----
> >>> lib/librte_ether/rte_mtr.h | 26 +++++------
> >>> lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
> >>> lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
> >>> lib/librte_security/rte_security.c | 16 +++----
> >>> lib/librte_security/rte_security.h | 23 +++++-----
> >>
> >> It may not be the responsibility of this patchset, but there are more
> >> experimental APIs in DPDK.
> >>
> > Thats an interesting statement to make. This patchset creates a build time
> > check that compares symbols located in the EXPERIMENTAL version section of a
> > libraries' version map file to the symbols that are marked with this new tag,
> > throwing an error if they don't match. I believe what you say in that there may
> > be additional APIs that are experimental, but given that, I would have to
> > conclude one of the following:
> >
> > 1) The missing API's are macros or static inline functions that are not exported
> > from libraries directly
> >
> > 2) The documentation for experimental API's are out of sync, in that they have
> > legitimately moved to be supported API's and the documentation needs to be
> > updated
> >
> > 3) There are API's which are experimental that have been incorrectly placed in a
> > versioned tag.
> >
> > I made a pretty good effort to scan comments for the word EXPERIMENTAL so that I
> > could catch item (1). And while I may not have caught them all, I'd like to
> > think I got a good chunk of them. That leaves cleanup of (2) and (3), which I
> > think this patchset can help us idenfity.
> >
> >> Using EXPERIMENTAL tag in linker script is relatively new approach and this was
> >> not a requirement, so many experimental APIs are documented in API documentation
> >> (header file doxygen comment).
> >> Sample: librte_member
> >>
> > That sounds like case (3) above.
> >
> > Thats a bit odd. I understand that the use of the EXPERIMENTAL version tag is
> > new, but once it was introduced it should have been made a requirement. There
> > would have been no penalty for moving the version number (as doing so would not
> > have violated ABI guarantees, given that those API's were appropriately
> > documented as experimental). If they have not been, then the use of the
> > EXPERIMENTAL tag isn't overly useful, as it doesn't provide any segregation of
> > the stable ABI from the unstable ABI.
> >
> >> It is required to scan all header files and update their linker scripts for the
> >> experimental APIs.
> >>
> > Yes and no. If a given library is not marked as experimental in its version
> > map, this change won't flag it as a problem, but if its intended to be
> > experimental (i.e. if its likely to have its ABI fluctuate), then yes, we should
> > take the appropriate steps to flag it as such properly.
> >
> > If a given library is intended to be experimental, I would say yes,
> > the author should make the appropriate chage to the version map, and then the
> > corresponding change to the headers and c files with this new tag.
> > Alternatively, they might choose to simply update the documentation to reflect
> > the fact that the ABI for that library is now stable.
> >
> > The thing that should definately not hapen though, is a half measure. We
> > shouldn't allow libraries to call themselves experimental, and then excuse them
> > from any rules we have regarding their in-code representation. If we have an
> > EXPERIMENTAL version in the map, we should require its use, and by extension
> > require this tag when its merged for the reasons previously outlined
>
> My comment is for your item (3), but it is not fair to say "incorrectly placed"
> because if I don't miss anything this has never been documented as correct way
> to do, and lots of the existing usage is _before_ we start using EXPERIMENTAL
> tag in the linker script, so they were doing right thing for that time.
>
Ok, Apologies, perhaps incorrectly placed isn't a fair term to use. Perhaps it
would be better to say the experimental specification was insufficiently
documented? The point however remains. Defining an API category that conveys a
freedom of modification of ABI needs to follow rules for identification, and
providing a mechanism to tag said ABIs in the code without a requirement to use
it creates an confusing situation to say the least (i.e. some APIS will be
listed as belonging to the EXPERIMENTAL version, others won't, but will be
documented as such, creating an ambiguous status).
> Question is, is this patchset should fix them, since now this patchset defines
> using EXPERIMENTAL tag in linker script as way to do it, or should we wait
> maintainers to fix it after this has been documented. Waiting for maintainer may
> take time because not all maintainers are following the mail list closely to
> capture all expectations.
>
In answer, I think waiting for maintainers to correct their experimental
use isn't going to get anything done. As you said, not all maintainers monitor
all conversations closely enough to pick up on the need, and as we move forward
this effort will likely get de-prioitized, as the status quo will just continue
to exist. I would propose that we accept this patch, and then I subsequently
preform an audit on the documentation to find other APIs which are documented as
EXPERIMENTAL, but not tagged as such in their version files. I can submit
subsequent patches to reconcile those APIs that I find, which should get on the
respective maintainers radars. Does that sound reasonable?
Neil
> >
> > Neil
> >
> >
> >>> 14 files changed, 139 insertions(+), 116 deletions(-)
> >>
> >> <...>
> >>
> >>
>
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2018-01-12 11:50 ` Ferruh Yigit
@ 2018-01-12 14:37 ` Neil Horman
2018-01-12 15:55 ` Ferruh Yigit
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-12 14:37 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On Fri, Jan 12, 2018 at 11:50:12AM +0000, Ferruh Yigit wrote:
> On 1/11/2018 9:29 PM, Neil Horman wrote:
> > On Thu, Jan 11, 2018 at 08:06:48PM +0000, Ferruh Yigit wrote:
> >> On 12/13/2017 3:17 PM, Neil Horman wrote:
> >>> Document the need to add the __experimental tag to appropriate functions
> >>>
> >>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> >>> CC: Thomas Monjalon <thomas@monjalon.net>
> >>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> >>> CC: Bruce Richardson <bruce.richardson@intel.com>
>
> <...>
>
> >>> automatically marked as ``experimental`` to allow for a period of stabilization>>> before they become part of a tracked ABI.
>
> Full sentences for above statement:
> "
> Since changes to APIs are most likely immediately after their introduction, as
> users begin to take advantage of those new APIs and start finding issues with
> them, new DPDK APIs will be automatically marked as experimental to allow for a
> period of stabilization before they become part of a tracked ABI.
> "
>
> This part is not related to this patchset, but it will be hard to maintain above
> behavior, "automatically marked" is not automatic now and moving them to stable
> after one release is also not automatic. Do you have any suggestion on how to
> manage this, do you think can your script be expanded to cover these checks?
>
I would make the argument that this was never the case, but rather a statement
of principle. I assert that because I can find no mechanism anywhere in our
build system that 'automatically' documented or marked a new API as experimental
(please correct me if I'm wrong here). I think this was more meant to be a
directive to developers to do whatever coding was needed to preform such
marking/documentation in whatever style/format was current. E.g. introducers of
a new API should document everything as EXPERIMENTAL using the appropriate
doxygen tag and version map tag.
In answer to your question, While we might be able to expand my script to check
for new API's and ensure they are marked as experimental, I don't think thats
the right place to do it, because that script is run at build time, where the
state of the tree is transient. A better place to do it would be with a git hook
at checkin time, or in the checkpatch script to flag new apis as experimental
right before those new API's are comitted. Though I'm not a huge fan of that
either (at least not of the former suggestion). I say that because I think we
need to allow developers the freedom to determine the supported status of any
new API that they add. For example, it seems pretty clear that a new library
might want to have its entire API marked as experimental, but someone adding a
single new function to an existing API might be confident that the new function
is needed and should be immediately supported..
I think the better solution is to define the use of the EXPERIMENTAL tag in the
version map as the canonical location to define unstable API functions. Doing
so immediately commits an author to ensuring that the corresponding function
definitions are marked with the __experimental tags, which in turn will cause
any downstream users to be alerted to the fact that they might be using those
API's in their code, so they can take appropriate action. It still allows for
the Documentation to be out of sync, but alerting authors doing development I
think is the more important element here, as Documentation can be corrected more
easily than code in the field.
Thoughts?
Neil
> >>>
> >>> +Note that marking an API as experimental is a two 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 definitions of those exported functions, and
> >>> +their forward declarations (in the development header files), must be marked
> >>> +with the __experimental tag (see rte_compat.h). The DPDK build makefiles
> >>> +preform a check to ensure that the map file and the C code reflect the same
> >>> +list of symbols.
> >>
> >> There are more steps we historically do to mark an API as experimental:
> >> - Add to function header comment experimental for API documentation, preferably
> >> with a warning tag to highlight it:
> >>
> >> /**
> >> * @warning
> >> * @b EXPERIMENTAL:
> >> ....
> >> */
> >>
> >> - If whole APIs in header file are experimental, add same experimental warning
> >> doxygen comment in file comment, again preferably with warning.
> >>
> >> - If whole library is experimental, put EXPERIMENTAL tag into maintainers file
> >> as well.
> >>
> > Is that documented somewhere? I'd like to add this to the same location that it
> > otherwise is written out. The above location was the only place in the guide
> > that I could find reference to experimental markings.
>
> As far as I know how to mark an API as experimental is not documented.
> What do you think making a new section for this information?
>
> >
> >>> +
> >>> ABI versions, once released, are available until such time as their
> >>> deprecation has been noted in the Release Notes for at least one major release
> >>> cycle. For example consider the case where the ABI for DPDK 2.0 has been
> >>>
> >>
> >>
>
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls
2018-01-12 14:25 ` Neil Horman
@ 2018-01-12 15:53 ` Ferruh Yigit
0 siblings, 0 replies; 83+ messages in thread
From: Ferruh Yigit @ 2018-01-12 15:53 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On 1/12/2018 2:25 PM, Neil Horman wrote:
> On Fri, Jan 12, 2018 at 11:50:01AM +0000, Ferruh Yigit wrote:
>> On 1/11/2018 9:24 PM, Neil Horman wrote:
>>> On Thu, Jan 11, 2018 at 08:06:33PM +0000, Ferruh Yigit wrote:
>>>> On 12/13/2017 3:17 PM, Neil Horman wrote:
>>>>> Append the __experimental tag to api calls appearing in the EXPERIMENTAL
>>>>> section of their libraries version map
>>>>>
>>>>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
>>>>> CC: Thomas Monjalon <thomas@monjalon.net>
>>>>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
>>>>> CC: Bruce Richardson <bruce.richardson@intel.com>
>>>>> ---
>>>>> lib/librte_eal/common/eal_common_dev.c | 6 ++-
>>>>> lib/librte_eal/common/eal_common_devargs.c | 7 +--
>>>>> lib/librte_eal/common/include/rte_dev.h | 6 ++-
>>>>> lib/librte_eal/common/include/rte_devargs.h | 8 ++--
>>>>> lib/librte_eal/common/include/rte_service.h | 47 ++++++++++---------
>>>>> .../common/include/rte_service_component.h | 14 +++---
>>>>> lib/librte_eal/common/rte_service.c | 52 ++++++++++++----------
>>>>> lib/librte_eal/linuxapp/eal/eal.c | 1 +
>>>>> lib/librte_ether/rte_mtr.c | 25 ++++++-----
>>>>> lib/librte_ether/rte_mtr.h | 26 +++++------
>>>>> lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
>>>>> lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
>>>>> lib/librte_security/rte_security.c | 16 +++----
>>>>> lib/librte_security/rte_security.h | 23 +++++-----
>>>>
>>>> It may not be the responsibility of this patchset, but there are more
>>>> experimental APIs in DPDK.
>>>>
>>> Thats an interesting statement to make. This patchset creates a build time
>>> check that compares symbols located in the EXPERIMENTAL version section of a
>>> libraries' version map file to the symbols that are marked with this new tag,
>>> throwing an error if they don't match. I believe what you say in that there may
>>> be additional APIs that are experimental, but given that, I would have to
>>> conclude one of the following:
>>>
>>> 1) The missing API's are macros or static inline functions that are not exported
>>> from libraries directly
>>>
>>> 2) The documentation for experimental API's are out of sync, in that they have
>>> legitimately moved to be supported API's and the documentation needs to be
>>> updated
>>>
>>> 3) There are API's which are experimental that have been incorrectly placed in a
>>> versioned tag.
>>>
>>> I made a pretty good effort to scan comments for the word EXPERIMENTAL so that I
>>> could catch item (1). And while I may not have caught them all, I'd like to
>>> think I got a good chunk of them. That leaves cleanup of (2) and (3), which I
>>> think this patchset can help us idenfity.
>>>
>>>> Using EXPERIMENTAL tag in linker script is relatively new approach and this was
>>>> not a requirement, so many experimental APIs are documented in API documentation
>>>> (header file doxygen comment).
>>>> Sample: librte_member
>>>>
>>> That sounds like case (3) above.
>>>
>>> Thats a bit odd. I understand that the use of the EXPERIMENTAL version tag is
>>> new, but once it was introduced it should have been made a requirement. There
>>> would have been no penalty for moving the version number (as doing so would not
>>> have violated ABI guarantees, given that those API's were appropriately
>>> documented as experimental). If they have not been, then the use of the
>>> EXPERIMENTAL tag isn't overly useful, as it doesn't provide any segregation of
>>> the stable ABI from the unstable ABI.
>>>
>>>> It is required to scan all header files and update their linker scripts for the
>>>> experimental APIs.
>>>>
>>> Yes and no. If a given library is not marked as experimental in its version
>>> map, this change won't flag it as a problem, but if its intended to be
>>> experimental (i.e. if its likely to have its ABI fluctuate), then yes, we should
>>> take the appropriate steps to flag it as such properly.
>>>
>>> If a given library is intended to be experimental, I would say yes,
>>> the author should make the appropriate chage to the version map, and then the
>>> corresponding change to the headers and c files with this new tag.
>>> Alternatively, they might choose to simply update the documentation to reflect
>>> the fact that the ABI for that library is now stable.
>>>
>>> The thing that should definately not hapen though, is a half measure. We
>>> shouldn't allow libraries to call themselves experimental, and then excuse them
>>> from any rules we have regarding their in-code representation. If we have an
>>> EXPERIMENTAL version in the map, we should require its use, and by extension
>>> require this tag when its merged for the reasons previously outlined
>>
>> My comment is for your item (3), but it is not fair to say "incorrectly placed"
>> because if I don't miss anything this has never been documented as correct way
>> to do, and lots of the existing usage is _before_ we start using EXPERIMENTAL
>> tag in the linker script, so they were doing right thing for that time.
>>
> Ok, Apologies, perhaps incorrectly placed isn't a fair term to use. Perhaps it
> would be better to say the experimental specification was insufficiently
> documented? The point however remains. Defining an API category that conveys a
> freedom of modification of ABI needs to follow rules for identification, and
> providing a mechanism to tag said ABIs in the code without a requirement to use
> it creates an confusing situation to say the least (i.e. some APIS will be
> listed as belonging to the EXPERIMENTAL version, others won't, but will be
> documented as such, creating an ambiguous status).
>
>> Question is, is this patchset should fix them, since now this patchset defines
>> using EXPERIMENTAL tag in linker script as way to do it, or should we wait
>> maintainers to fix it after this has been documented. Waiting for maintainer may
>> take time because not all maintainers are following the mail list closely to
>> capture all expectations.
>>
>
> In answer, I think waiting for maintainers to correct their experimental
> use isn't going to get anything done. As you said, not all maintainers monitor
> all conversations closely enough to pick up on the need, and as we move forward
> this effort will likely get de-prioitized, as the status quo will just continue
> to exist. I would propose that we accept this patch, and then I subsequently
> preform an audit on the documentation to find other APIs which are documented as
> EXPERIMENTAL, but not tagged as such in their version files. I can submit
> subsequent patches to reconcile those APIs that I find, which should get on the
> respective maintainers radars. Does that sound reasonable?
Sounds good to me, hence
Series
Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>
>
> Neil
>
>>>
>>> Neil
>>>
>>>
>>>>> 14 files changed, 139 insertions(+), 116 deletions(-)
>>>>
>>>> <...>
>>>>
>>>>
>>
>>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2018-01-12 14:37 ` Neil Horman
@ 2018-01-12 15:55 ` Ferruh Yigit
2018-01-13 0:28 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Ferruh Yigit @ 2018-01-12 15:55 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On 1/12/2018 2:37 PM, Neil Horman wrote:
> On Fri, Jan 12, 2018 at 11:50:12AM +0000, Ferruh Yigit wrote:
>> On 1/11/2018 9:29 PM, Neil Horman wrote:
>>> On Thu, Jan 11, 2018 at 08:06:48PM +0000, Ferruh Yigit wrote:
>>>> On 12/13/2017 3:17 PM, Neil Horman wrote:
>>>>> Document the need to add the __experimental tag to appropriate functions
>>>>>
>>>>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
>>>>> CC: Thomas Monjalon <thomas@monjalon.net>
>>>>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
>>>>> CC: Bruce Richardson <bruce.richardson@intel.com>
>>
>> <...>
>>
>>>>> automatically marked as ``experimental`` to allow for a period of stabilization>>> before they become part of a tracked ABI.
>>
>> Full sentences for above statement:
>> "
>> Since changes to APIs are most likely immediately after their introduction, as
>> users begin to take advantage of those new APIs and start finding issues with
>> them, new DPDK APIs will be automatically marked as experimental to allow for a
>> period of stabilization before they become part of a tracked ABI.
>> "
>>
>> This part is not related to this patchset, but it will be hard to maintain above
>> behavior, "automatically marked" is not automatic now and moving them to stable
>> after one release is also not automatic. Do you have any suggestion on how to
>> manage this, do you think can your script be expanded to cover these checks?
>>
>
> I would make the argument that this was never the case, but rather a statement
> of principle. I assert that because I can find no mechanism anywhere in our
> build system that 'automatically' documented or marked a new API as experimental
> (please correct me if I'm wrong here). I think this was more meant to be a
> directive to developers to do whatever coding was needed to preform such
> marking/documentation in whatever style/format was current. E.g. introducers of
> a new API should document everything as EXPERIMENTAL using the appropriate
> doxygen tag and version map tag.
>
> In answer to your question, While we might be able to expand my script to check
> for new API's and ensure they are marked as experimental, I don't think thats
> the right place to do it, because that script is run at build time, where the
> state of the tree is transient. A better place to do it would be with a git hook
> at checkin time, or in the checkpatch script to flag new apis as experimental
> right before those new API's are comitted. Though I'm not a huge fan of that
> either (at least not of the former suggestion). I say that because I think we
> need to allow developers the freedom to determine the supported status of any
> new API that they add. For example, it seems pretty clear that a new library
> might want to have its entire API marked as experimental, but someone adding a
> single new function to an existing API might be confident that the new function
> is needed and should be immediately supported..
>
> I think the better solution is to define the use of the EXPERIMENTAL tag in the
> version map as the canonical location to define unstable API functions. Doing
> so immediately commits an author to ensuring that the corresponding function
> definitions are marked with the __experimental tags, which in turn will cause
> any downstream users to be alerted to the fact that they might be using those
> API's in their code, so they can take appropriate action. It still allows for
> the Documentation to be out of sync, but alerting authors doing development I
> think is the more important element here, as Documentation can be corrected more
> easily than code in the field.
>
> Thoughts?
After this point agree to using EXPERIMENTAL tag in the version map as standard,
but it will be hard to maintain "API is experimental for first release" without
help of any automated tool.
> Neil
>
>>>>>
>>>>> +Note that marking an API as experimental is a two 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 definitions of those exported functions, and
>>>>> +their forward declarations (in the development header files), must be marked
>>>>> +with the __experimental tag (see rte_compat.h). The DPDK build makefiles
>>>>> +preform a check to ensure that the map file and the C code reflect the same
>>>>> +list of symbols.
>>>>
>>>> There are more steps we historically do to mark an API as experimental:
>>>> - Add to function header comment experimental for API documentation, preferably
>>>> with a warning tag to highlight it:
>>>>
>>>> /**
>>>> * @warning
>>>> * @b EXPERIMENTAL:
>>>> ....
>>>> */
>>>>
>>>> - If whole APIs in header file are experimental, add same experimental warning
>>>> doxygen comment in file comment, again preferably with warning.
>>>>
>>>> - If whole library is experimental, put EXPERIMENTAL tag into maintainers file
>>>> as well.
>>>>
>>> Is that documented somewhere? I'd like to add this to the same location that it
>>> otherwise is written out. The above location was the only place in the guide
>>> that I could find reference to experimental markings.
>>
>> As far as I know how to mark an API as experimental is not documented.
>> What do you think making a new section for this information?
>>
>>>
>>>>> +
>>>>> ABI versions, once released, are available until such time as their
>>>>> deprecation has been noted in the Release Notes for at least one major release
>>>>> cycle. For example consider the case where the ABI for DPDK 2.0 has been
>>>>>
>>>>
>>>>
>>
>>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2018-01-12 15:55 ` Ferruh Yigit
@ 2018-01-13 0:28 ` Neil Horman
2018-01-13 15:56 ` Thomas Monjalon
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-13 0:28 UTC (permalink / raw)
To: Ferruh Yigit; +Cc: dev, thomas, john.mcnamara, bruce.richardson
On Fri, Jan 12, 2018 at 03:55:10PM +0000, Ferruh Yigit wrote:
> On 1/12/2018 2:37 PM, Neil Horman wrote:
> > On Fri, Jan 12, 2018 at 11:50:12AM +0000, Ferruh Yigit wrote:
> >> On 1/11/2018 9:29 PM, Neil Horman wrote:
> >>> On Thu, Jan 11, 2018 at 08:06:48PM +0000, Ferruh Yigit wrote:
> >>>> On 12/13/2017 3:17 PM, Neil Horman wrote:
> >>>>> Document the need to add the __experimental tag to appropriate functions
> >>>>>
> >>>>> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> >>>>> CC: Thomas Monjalon <thomas@monjalon.net>
> >>>>> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> >>>>> CC: Bruce Richardson <bruce.richardson@intel.com>
> >>
> >> <...>
> >>
> >>>>> automatically marked as ``experimental`` to allow for a period of stabilization>>> before they become part of a tracked ABI.
> >>
> >> Full sentences for above statement:
> >> "
> >> Since changes to APIs are most likely immediately after their introduction, as
> >> users begin to take advantage of those new APIs and start finding issues with
> >> them, new DPDK APIs will be automatically marked as experimental to allow for a
> >> period of stabilization before they become part of a tracked ABI.
> >> "
> >>
> >> This part is not related to this patchset, but it will be hard to maintain above
> >> behavior, "automatically marked" is not automatic now and moving them to stable
> >> after one release is also not automatic. Do you have any suggestion on how to
> >> manage this, do you think can your script be expanded to cover these checks?
> >>
> >
> > I would make the argument that this was never the case, but rather a statement
> > of principle. I assert that because I can find no mechanism anywhere in our
> > build system that 'automatically' documented or marked a new API as experimental
> > (please correct me if I'm wrong here). I think this was more meant to be a
> > directive to developers to do whatever coding was needed to preform such
> > marking/documentation in whatever style/format was current. E.g. introducers of
> > a new API should document everything as EXPERIMENTAL using the appropriate
> > doxygen tag and version map tag.
> >
> > In answer to your question, While we might be able to expand my script to check
> > for new API's and ensure they are marked as experimental, I don't think thats
> > the right place to do it, because that script is run at build time, where the
> > state of the tree is transient. A better place to do it would be with a git hook
> > at checkin time, or in the checkpatch script to flag new apis as experimental
> > right before those new API's are comitted. Though I'm not a huge fan of that
> > either (at least not of the former suggestion). I say that because I think we
> > need to allow developers the freedom to determine the supported status of any
> > new API that they add. For example, it seems pretty clear that a new library
> > might want to have its entire API marked as experimental, but someone adding a
> > single new function to an existing API might be confident that the new function
> > is needed and should be immediately supported..
> >
> > I think the better solution is to define the use of the EXPERIMENTAL tag in the
> > version map as the canonical location to define unstable API functions. Doing
> > so immediately commits an author to ensuring that the corresponding function
> > definitions are marked with the __experimental tags, which in turn will cause
> > any downstream users to be alerted to the fact that they might be using those
> > API's in their code, so they can take appropriate action. It still allows for
> > the Documentation to be out of sync, but alerting authors doing development I
> > think is the more important element here, as Documentation can be corrected more
> > easily than code in the field.
> >
> > Thoughts?
>
> After this point agree to using EXPERIMENTAL tag in the version map as standard,
> but it will be hard to maintain "API is experimental for first release" without
> help of any automated tool.
>
I completely agree, in fact I would say it is impossible to do without tooling,
with or without this change. I think we need to do 1 of 2 things:
1) Add some code to checkpatch.pl to put up a warning if any new apis are added
without marking them as experimental
2) Change the documentation to be a suggestion rather than a requirement.
I'll look into doing (1), but I'm wondering if (2) is the more flexible way to
go. I'm hesitant to enforce the initial marking of new APIs as experimental.
Thoughts?
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2018-01-13 0:28 ` Neil Horman
@ 2018-01-13 15:56 ` Thomas Monjalon
2018-01-14 14:36 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-13 15:56 UTC (permalink / raw)
To: Neil Horman; +Cc: Ferruh Yigit, dev, john.mcnamara, bruce.richardson
13/01/2018 01:28, Neil Horman:
> On Fri, Jan 12, 2018 at 03:55:10PM +0000, Ferruh Yigit wrote:
> > After this point agree to using EXPERIMENTAL tag in the version map as standard,
> > but it will be hard to maintain "API is experimental for first release" without
> > help of any automated tool.
> >
> I completely agree, in fact I would say it is impossible to do without tooling,
> with or without this change. I think we need to do 1 of 2 things:
>
> 1) Add some code to checkpatch.pl to put up a warning if any new apis are added
> without marking them as experimental
>
> 2) Change the documentation to be a suggestion rather than a requirement.
>
> I'll look into doing (1), but I'm wondering if (2) is the more flexible way to
> go. I'm hesitant to enforce the initial marking of new APIs as experimental.
> Thoughts?
There will be always cases where we are sure that the experimental step
is not needed.
Even if it is required and checked by a tool, we can ignore it, right?
However, there is no big benefit of bypassing the experimental step.
I am for making mandatory the new API as experimental.
We will handle the exceptions case by case if any.
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2018-01-13 15:56 ` Thomas Monjalon
@ 2018-01-14 14:36 ` Neil Horman
2018-01-14 16:27 ` Thomas Monjalon
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-14 14:36 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: Ferruh Yigit, dev, john.mcnamara, bruce.richardson
On Sat, Jan 13, 2018 at 04:56:11PM +0100, Thomas Monjalon wrote:
> 13/01/2018 01:28, Neil Horman:
> > On Fri, Jan 12, 2018 at 03:55:10PM +0000, Ferruh Yigit wrote:
> > > After this point agree to using EXPERIMENTAL tag in the version map as standard,
> > > but it will be hard to maintain "API is experimental for first release" without
> > > help of any automated tool.
> > >
> > I completely agree, in fact I would say it is impossible to do without tooling,
> > with or without this change. I think we need to do 1 of 2 things:
> >
> > 1) Add some code to checkpatch.pl to put up a warning if any new apis are added
> > without marking them as experimental
> >
> > 2) Change the documentation to be a suggestion rather than a requirement.
> >
> > I'll look into doing (1), but I'm wondering if (2) is the more flexible way to
> > go. I'm hesitant to enforce the initial marking of new APIs as experimental.
> > Thoughts?
>
> There will be always cases where we are sure that the experimental step
> is not needed.
> Even if it is required and checked by a tool, we can ignore it, right?
> However, there is no big benefit of bypassing the experimental step.
>
> I am for making mandatory the new API as experimental.
> We will handle the exceptions case by case if any.
>
If the consensus is to require experimental marking by default, and grant
exceptions as needed, then I would strongly suggest that we do this in
checkpatch as I can modify it to warn people of added API's (which will be
reflected in the CI tool, if the CI group is still maintaining it), but we can
collectively ignore it if its so clearly trivial that it requires no
experimental addition (which I think may freqently be the case).
I'll start work on that on monday
Best
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2018-01-14 14:36 ` Neil Horman
@ 2018-01-14 16:27 ` Thomas Monjalon
0 siblings, 0 replies; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-14 16:27 UTC (permalink / raw)
To: Neil Horman; +Cc: Ferruh Yigit, dev, john.mcnamara, bruce.richardson
14/01/2018 15:36, Neil Horman:
> On Sat, Jan 13, 2018 at 04:56:11PM +0100, Thomas Monjalon wrote:
> > 13/01/2018 01:28, Neil Horman:
> > > On Fri, Jan 12, 2018 at 03:55:10PM +0000, Ferruh Yigit wrote:
> > > > After this point agree to using EXPERIMENTAL tag in the version map as standard,
> > > > but it will be hard to maintain "API is experimental for first release" without
> > > > help of any automated tool.
> > > >
> > > I completely agree, in fact I would say it is impossible to do without tooling,
> > > with or without this change. I think we need to do 1 of 2 things:
> > >
> > > 1) Add some code to checkpatch.pl to put up a warning if any new apis are added
> > > without marking them as experimental
> > >
> > > 2) Change the documentation to be a suggestion rather than a requirement.
> > >
> > > I'll look into doing (1), but I'm wondering if (2) is the more flexible way to
> > > go. I'm hesitant to enforce the initial marking of new APIs as experimental.
> > > Thoughts?
> >
> > There will be always cases where we are sure that the experimental step
> > is not needed.
> > Even if it is required and checked by a tool, we can ignore it, right?
> > However, there is no big benefit of bypassing the experimental step.
> >
> > I am for making mandatory the new API as experimental.
> > We will handle the exceptions case by case if any.
> >
> If the consensus is to require experimental marking by default, and grant
> exceptions as needed, then I would strongly suggest that we do this in
> checkpatch as I can modify it to warn people of added API's (which will be
> reflected in the CI tool, if the CI group is still maintaining it), but we can
> collectively ignore it if its so clearly trivial that it requires no
> experimental addition (which I think may freqently be the case).
I am OK with this approach.
> I'll start work on that on monday
Good
I wonder how difficult it can be to implement.
Note: we do not maintain a fork of checkpatch.pl.
We just have a shell wrapper checkpatch.sh.
Maybe you should start a different tool.
Can it use Coccinelle?
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [dpdk-ci] [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging
2018-01-09 9:20 ` Thomas Monjalon
2018-01-09 12:36 ` Neil Horman
@ 2018-01-19 15:44 ` Neil Horman
1 sibling, 0 replies; 83+ messages in thread
From: Neil Horman @ 2018-01-19 15:44 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: dev, Bruce Richardson, john.mcnamara, qian.q.xu, ci
On Tue, Jan 09, 2018 at 10:20:05AM +0100, Thomas Monjalon wrote:
> 09/01/2018 02:32, Neil Horman:
> > On Fri, Jan 05, 2018 at 11:00:52AM -0500, Neil Horman wrote:
> > > On Fri, Jan 05, 2018 at 03:08:52PM +0100, Thomas Monjalon wrote:
> > > > 04/01/2018 13:56, Neil Horman:
> > > > > On Sat, Dec 30, 2017 at 12:15:17PM -0500, Neil Horman wrote:
> > > > > > Thomas-
> > > > > > I just noticed that the ci tests are failing on the intel compiler, which
> > > > > > makes very little sense to me, as the error is a permission error on a bash
> > > > > > script that added in this series, which works during the gcc compilation. Can
> > > > > > you take a look at that please?
> > > > > >
> > > > > > thanks
> > > > > > Neil
> > > > > >
> > > > > Ping again Thomas, I've still heard nothing from you or the CI group about
> > > > > getting more visibility into the odd permission problem in the CI runs this
> > > > > seems to be encountering. I'd love to fix it, but the information in the report
> > > > > is insufficient to have any idea whats going on and the problem does not occur
> > > > > on local builds. Please advise.
> > > >
> > > > Unfortunately, I have no clues about this setup.
> > > > The report is sent by sys_stv@intel.com.
> > > > Adding Qian as Cc.
> > > >
> > > > The error is "buildtools/experimentalsyms.sh: Permission denied"
> > > > And the file mode is 100755.
> > > >
> > > > Anyone from Intel to check what happens please?
> > > >
> > > Thank you Thomas. I would really like to get this pushed in, as others have
> > > acked it, but the lack of visibility into the CI errors is quite frustrating
> > > Neil
> > >
> > >
> > So I'm not sure where to go with this. I've emailed the ci group on their list,
> > I've asked them directly on this list, and asked you, Thomas for assistance in
> > getting hold of the ci maintainers, and there has been no response in over a
> > week now. This patch has been acked by a few people, and the builds work on
> > clang and gcc locally just fine. I'm inclined to ask you to take these patches
> > despite the ci errors. If the CI maintainers can't respond to needs for
> > visibility into the system, I don't think its reasonable to block patches based
> > on CI results.
> >
> > Thoughts?
> > Neil
>
> Yes, you're right, we can bypass this CI test.
>
Ping, I thought you were going to integrate this? Its been sitting here for
over a month now.
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports
2017-12-13 15:17 ` [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
@ 2018-01-21 18:31 ` Thomas Monjalon
2018-01-21 22:07 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-21 18:31 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, john.mcnamara, bruce.richardson
Hi Neil,
Sorry for the very late review.
I thought review had been done by others but it seems not.
Please find my comments below.
13/12/2017 16:17, Neil Horman:
> create mode 100755 buildtools/experimentalsyms.sh
When adding a new file, you must reference it in MAINTAINERS.
Please add it in the section "ABI versioning".
> --- /dev/null
> +++ b/buildtools/experimentalsyms.sh
I think the file name should include the word "check".
What about check-experimental-syms.sh ?
> @@ -0,0 +1,35 @@
> +#!/bin/sh
You must insert a SPDX license and copyright here.
> +if [ -d $MAPFILE ]
> +then
> + exit 0
> +fi
> +
> +if [ -d $OBJFILE ]
> +then
> + exit 0
> +fi
Why checking for not being a directory?
I guess you could check being a readable file (-r)?
Should it return an error?
> +for i in `awk 'BEGIN {found=0}
> + /.*EXPERIMENTAL.*/ {found=1}
> + /.*}.*;/ {found=0}
> + /.*;/ {if (found == 1) print $1}' $MAPFILE`
> +do
> + SYM=`echo $i | sed -e"s/;//"`
> + objdump -t $OBJFILE | grep -q "\.text.*$SYM"
> + IN_TEXT=$?
> + objdump -t $OBJFILE | grep -q "\.text\.experimental.*$SYM"
> + IN_EXP=$?
> + if [ $IN_TEXT -eq 0 -a $IN_EXP -ne 0 ]
> + then
> + echo "$SYM is not flagged as experimental"
> + echo "but is listed in version map"
> + echo "Please add __experimental to the definition of $SYM"
> + exit 1
> + fi
> +done
> +exit 0
exit 0 is useless at the end of a script.
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 2/5] compat: Add __experimental macro
2017-12-13 15:17 ` [PATCHv4 2/5] compat: Add __experimental macro Neil Horman
@ 2018-01-21 18:37 ` Thomas Monjalon
0 siblings, 0 replies; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-21 18:37 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, john.mcnamara, bruce.richardson
Hi,
I know I should have spotted these comments earlier,
I'm sorry to be late on this review.
13/12/2017 16:17, Neil Horman:
> +#ifndef ALLOW_EXPERIMENTAL_APIS
>
> +#define __experimental \
These macros should be in the DPDK namespace:
RTE_ALLOW_EXPERIMENTAL_API (no need of S)
__rte_experimental
> +__attribute__((deprecated("Symbol is not yet part of stable abi"), \
Nit: s/abi/ABI/
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2017-12-13 15:17 ` [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2018-01-11 20:06 ` Ferruh Yigit
@ 2018-01-21 18:50 ` Thomas Monjalon
2018-01-22 1:19 ` Neil Horman
1 sibling, 1 reply; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-21 18:50 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, john.mcnamara, bruce.richardson
13/12/2017 16:17, Neil Horman:
> --- a/lib/librte_eal/linuxapp/eal/Makefile
> +++ b/lib/librte_eal/linuxapp/eal/Makefile
> +CFLAGS += -DALLOW_EXPERIMENTAL_APIS
We can define this flag for the whole DPDK libraries,
in mk/rte.vars.mk
inside the block ifneq ($(BUILDING_RTE_SDK),)
> --- a/mk/internal/rte.compile-pre.mk
> +++ b/mk/internal/rte.compile-pre.mk
> +EXPERIMENTAL_CHECK = $(RTE_SDK)/buildtools/experimentalsyms.sh
> +CHECK_EXPERIMENTAL = $(EXPERIMENTAL_CHECK) $(SRCDIR)/$(EXPORT_MAP) $@
> echo $(C_TO_O_DISP); \
> $(C_TO_O) && \
> $(PMDINFO_TO_O) && \
> + $(CHECK_EXPERIMENTAL) && \
Inserting this check looks good.
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2018-01-12 12:44 ` Neil Horman
@ 2018-01-21 18:54 ` Thomas Monjalon
2018-01-22 1:34 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-21 18:54 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, Ferruh Yigit, john.mcnamara, bruce.richardson
12/01/2018 13:44, Neil Horman:
> On Fri, Jan 12, 2018 at 11:49:57AM +0000, Ferruh Yigit wrote:
> > On 1/11/2018 8:50 PM, Neil Horman wrote:
> > > On Thu, Jan 11, 2018 at 08:06:43PM +0000, Ferruh Yigit wrote:
> > >> On 12/13/2017 3:17 PM, Neil Horman wrote:
> > >>> --- a/app/test-eventdev/Makefile
> > >>> +++ b/app/test-eventdev/Makefile
> > >>> @@ -32,6 +32,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
> > >>>
> > >>> APP = dpdk-test-eventdev
> > >>>
> > >>> +CFLAGS += -DALLOW_EXPERIMENTAL_APIS
> > >>
> > >> Do we need this internally in DPDK? For application developers this is great,
> > >> they will get warning unless explicitly stated that they are OK with it.
> > >>
> > > I'm not sure what you're asking here. As I mentioned in the initial post, I
> > > think we should give blanket permission to any in-tree dpdk library to allow the
> > > use of experimental API's, but that doesn't really imply that all developers
> > > would wan't it disabled all the time. That is to say, I could envision a
> > > library author who, early in development would want to get a warning issued if
> > > they used an unstable API, and, only once they were happy with their design and
> > > choice of API usage, turn the warning off.
> >
> > I got your point, but I think whoever using an experimental API in another
> > component in DPDK is almost always the author of the that experimental API, so
> > not sure this check is ever really needed within dpdk.
> >
> I would have thought so too, but it doesn't really bear up. The example I used
> to convince myself of a more granular approach was commit
> 9c38b704d280ac128003238d7d80bf07fa556a7d where the rte_service API was
> introduced as experimental by Nikhil Rao, and then later used in the eal library
> as part of commit a894d4815f79b0d76527d9c42b23327de1501711 by Harry van Haaren.
> Its no big deal because, as we agree, internal usage should be considered safe,
> but it seemed clear that differing authors were using each others code
> (potentially oblivious to the experimental nature of those APIs)
>
> > But OK, I guess it won't hurt to have more granular approach.
> >
> > >
> > >> Do we have any option than allowing them in DPDK library? And when experimental
> > >> API modified the users in the DPDK library internally guaranteed to be updated.
> > >> Why not globally allow this for all DPDK internally?
> > >>
> > > For the reason I gave above. We certainly could enable this in a more top-level
> > > makefile so that for in-library systems it was opt-in rather than opt-out, but I
> > > chose a more granular approach because I could envision newer libraries wanting
> > > it on. I also felt, generally speaking, that where warning flags were
> > > concerned, it generally desireous to have them on by default, and make people
> > > explicitly choose to turn them off.
I think DPDK developpers look at the EXPERIMENTAL warning in the doxygen
above the prototype.
And when API will be switched to stable, we probably won't remove the flag
in the makefile to disable allowing experimental.
So at the end, we could just allow experimental API for all internal libs.
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 5/5] doc: Add ABI __experimental tag documentation
2017-12-13 15:17 ` [PATCHv4 5/5] doc: Add ABI __experimental tag documentation Neil Horman
2017-12-13 15:32 ` Bruce Richardson
2018-01-11 20:06 ` Ferruh Yigit
@ 2018-01-21 20:14 ` Thomas Monjalon
2 siblings, 0 replies; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-21 20:14 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, john.mcnamara, bruce.richardson
13/12/2017 16:17, Neil Horman:
> --- a/doc/guides/contributing/versioning.rst
> +++ b/doc/guides/contributing/versioning.rst
> +Note that marking an API as experimental is a two 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 definitions of those exported functions, and
> +their forward declarations (in the development header files), must be marked
> +with the __experimental tag (see rte_compat.h). The DPDK build makefiles
> +preform a check to ensure that the map file and the C code reflect the same
> +list of symbols.
Thanks for this text.
Bruce already commented about the type "preform".
Ferruh already commented about adding a string in doxygen header.
Ferruh already commented about adding sentences for new API.
I add that it would be the right place to explain the effect of the
attribute, and how it can be disabled at compilation.
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports
2018-01-21 18:31 ` Thomas Monjalon
@ 2018-01-21 22:07 ` Neil Horman
0 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2018-01-21 22:07 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: dev, john.mcnamara, bruce.richardson
On Sun, Jan 21, 2018 at 07:31:31PM +0100, Thomas Monjalon wrote:
> Hi Neil,
>
> Sorry for the very late review.
> I thought review had been done by others but it seems not.
> Please find my comments below.
>
> 13/12/2017 16:17, Neil Horman:
> > create mode 100755 buildtools/experimentalsyms.sh
>
> When adding a new file, you must reference it in MAINTAINERS.
> Please add it in the section "ABI versioning".
>
yup
> > --- /dev/null
> > +++ b/buildtools/experimentalsyms.sh
>
> I think the file name should include the word "check".
> What about check-experimental-syms.sh ?
>
> > @@ -0,0 +1,35 @@
> > +#!/bin/sh
>
> You must insert a SPDX license and copyright here.
>
Will do.
> > +if [ -d $MAPFILE ]
> > +then
> > + exit 0
> > +fi
> > +
> > +if [ -d $OBJFILE ]
> > +then
> > + exit 0
> > +fi
>
> Why checking for not being a directory?
> I guess you could check being a readable file (-r)?
> Should it return an error?
>
The objfile check is out of date (had it in place initially, and is no longer
needed). the mapfile check is there because dpdk apps use the same C_TO_O rule
and have no mapfile variable set.
> > +for i in `awk 'BEGIN {found=0}
> > + /.*EXPERIMENTAL.*/ {found=1}
> > + /.*}.*;/ {found=0}
> > + /.*;/ {if (found == 1) print $1}' $MAPFILE`
> > +do
> > + SYM=`echo $i | sed -e"s/;//"`
> > + objdump -t $OBJFILE | grep -q "\.text.*$SYM"
> > + IN_TEXT=$?
> > + objdump -t $OBJFILE | grep -q "\.text\.experimental.*$SYM"
> > + IN_EXP=$?
> > + if [ $IN_TEXT -eq 0 -a $IN_EXP -ne 0 ]
> > + then
> > + echo "$SYM is not flagged as experimental"
> > + echo "but is listed in version map"
> > + echo "Please add __experimental to the definition of $SYM"
> > + exit 1
> > + fi
> > +done
> > +exit 0
>
> exit 0 is useless at the end of a script.
Its there for clarity of exit value. I prefer to be expicit in that.
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2018-01-21 18:50 ` Thomas Monjalon
@ 2018-01-22 1:19 ` Neil Horman
0 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2018-01-22 1:19 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: dev, john.mcnamara, bruce.richardson
On Sun, Jan 21, 2018 at 07:50:08PM +0100, Thomas Monjalon wrote:
> 13/12/2017 16:17, Neil Horman:
> > --- a/lib/librte_eal/linuxapp/eal/Makefile
> > +++ b/lib/librte_eal/linuxapp/eal/Makefile
> > +CFLAGS += -DALLOW_EXPERIMENTAL_APIS
>
I think I addressed this in an earlier thread, but I'm opposed to doing
this. I'm strongly in favor of granting an exception to any developer who wants
to use experimental apis for in-tree code, but I would like for them to have to
opt into that decision, rather than just have a blanket allowance. I think
theres value in a developer having to make tha conscious decision when writing
new code.
> We can define this flag for the whole DPDK libraries,
> in mk/rte.vars.mk
> inside the block ifneq ($(BUILDING_RTE_SDK),)
>
> > --- a/mk/internal/rte.compile-pre.mk
> > +++ b/mk/internal/rte.compile-pre.mk
> > +EXPERIMENTAL_CHECK = $(RTE_SDK)/buildtools/experimentalsyms.sh
> > +CHECK_EXPERIMENTAL = $(EXPERIMENTAL_CHECK) $(SRCDIR)/$(EXPORT_MAP) $@
>
> > echo $(C_TO_O_DISP); \
> > $(C_TO_O) && \
> > $(PMDINFO_TO_O) && \
> > + $(CHECK_EXPERIMENTAL) && \
>
> Inserting this check looks good.
>
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2018-01-21 18:54 ` Thomas Monjalon
@ 2018-01-22 1:34 ` Neil Horman
2018-01-22 1:37 ` Thomas Monjalon
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-22 1:34 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: dev, Ferruh Yigit, john.mcnamara, bruce.richardson
On Sun, Jan 21, 2018 at 07:54:44PM +0100, Thomas Monjalon wrote:
> 12/01/2018 13:44, Neil Horman:
> > On Fri, Jan 12, 2018 at 11:49:57AM +0000, Ferruh Yigit wrote:
> > > On 1/11/2018 8:50 PM, Neil Horman wrote:
> > > > On Thu, Jan 11, 2018 at 08:06:43PM +0000, Ferruh Yigit wrote:
> > > >> On 12/13/2017 3:17 PM, Neil Horman wrote:
> > > >>> --- a/app/test-eventdev/Makefile
> > > >>> +++ b/app/test-eventdev/Makefile
> > > >>> @@ -32,6 +32,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
> > > >>>
> > > >>> APP = dpdk-test-eventdev
> > > >>>
> > > >>> +CFLAGS += -DALLOW_EXPERIMENTAL_APIS
> > > >>
> > > >> Do we need this internally in DPDK? For application developers this is great,
> > > >> they will get warning unless explicitly stated that they are OK with it.
> > > >>
> > > > I'm not sure what you're asking here. As I mentioned in the initial post, I
> > > > think we should give blanket permission to any in-tree dpdk library to allow the
> > > > use of experimental API's, but that doesn't really imply that all developers
> > > > would wan't it disabled all the time. That is to say, I could envision a
> > > > library author who, early in development would want to get a warning issued if
> > > > they used an unstable API, and, only once they were happy with their design and
> > > > choice of API usage, turn the warning off.
> > >
> > > I got your point, but I think whoever using an experimental API in another
> > > component in DPDK is almost always the author of the that experimental API, so
> > > not sure this check is ever really needed within dpdk.
> > >
> > I would have thought so too, but it doesn't really bear up. The example I used
> > to convince myself of a more granular approach was commit
> > 9c38b704d280ac128003238d7d80bf07fa556a7d where the rte_service API was
> > introduced as experimental by Nikhil Rao, and then later used in the eal library
> > as part of commit a894d4815f79b0d76527d9c42b23327de1501711 by Harry van Haaren.
> > Its no big deal because, as we agree, internal usage should be considered safe,
> > but it seemed clear that differing authors were using each others code
> > (potentially oblivious to the experimental nature of those APIs)
> >
> > > But OK, I guess it won't hurt to have more granular approach.
> > >
> > > >
> > > >> Do we have any option than allowing them in DPDK library? And when experimental
> > > >> API modified the users in the DPDK library internally guaranteed to be updated.
> > > >> Why not globally allow this for all DPDK internally?
> > > >>
> > > > For the reason I gave above. We certainly could enable this in a more top-level
> > > > makefile so that for in-library systems it was opt-in rather than opt-out, but I
> > > > chose a more granular approach because I could envision newer libraries wanting
> > > > it on. I also felt, generally speaking, that where warning flags were
> > > > concerned, it generally desireous to have them on by default, and make people
> > > > explicitly choose to turn them off.
>
> I think DPDK developpers look at the EXPERIMENTAL warning in the doxygen
> above the prototype.
I'm not sure I agree with that, but regardless, my initial reasoning for writing
this tag was to call attention to experimental API's during review, rather than
their use during development, so I didn't gripe about ABI changes on expemted
code. Additionally, weather they look at the docs or not, they can
pre-emptively turn off the warning if they choose.
> And when API will be switched to stable, we probably won't remove the flag
> in the makefile to disable allowing experimental.
Well, that remains to be seen I suppose.
> So at the end, we could just allow experimental API for all internal libs.
Thats a rather bootstrapping argument. You are effecitvely saying that no one
developing will ever want to be warned of using experimental APIs in DPDK, so
lets just turn it off everyone. I would really rather let individual developers
make that call at the time they author something new.
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2018-01-22 1:34 ` Neil Horman
@ 2018-01-22 1:37 ` Thomas Monjalon
0 siblings, 0 replies; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-22 1:37 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, Ferruh Yigit, john.mcnamara, bruce.richardson
22/01/2018 02:34, Neil Horman:
> On Sun, Jan 21, 2018 at 07:54:44PM +0100, Thomas Monjalon wrote:
> > 12/01/2018 13:44, Neil Horman:
> > > On Fri, Jan 12, 2018 at 11:49:57AM +0000, Ferruh Yigit wrote:
> > > > On 1/11/2018 8:50 PM, Neil Horman wrote:
> > > > > On Thu, Jan 11, 2018 at 08:06:43PM +0000, Ferruh Yigit wrote:
> > > > >> On 12/13/2017 3:17 PM, Neil Horman wrote:
> > > > >>> --- a/app/test-eventdev/Makefile
> > > > >>> +++ b/app/test-eventdev/Makefile
> > > > >>> @@ -32,6 +32,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
> > > > >>>
> > > > >>> APP = dpdk-test-eventdev
> > > > >>>
> > > > >>> +CFLAGS += -DALLOW_EXPERIMENTAL_APIS
> > > > >>
> > > > >> Do we need this internally in DPDK? For application developers this is great,
> > > > >> they will get warning unless explicitly stated that they are OK with it.
> > > > >>
> > > > > I'm not sure what you're asking here. As I mentioned in the initial post, I
> > > > > think we should give blanket permission to any in-tree dpdk library to allow the
> > > > > use of experimental API's, but that doesn't really imply that all developers
> > > > > would wan't it disabled all the time. That is to say, I could envision a
> > > > > library author who, early in development would want to get a warning issued if
> > > > > they used an unstable API, and, only once they were happy with their design and
> > > > > choice of API usage, turn the warning off.
> > > >
> > > > I got your point, but I think whoever using an experimental API in another
> > > > component in DPDK is almost always the author of the that experimental API, so
> > > > not sure this check is ever really needed within dpdk.
> > > >
> > > I would have thought so too, but it doesn't really bear up. The example I used
> > > to convince myself of a more granular approach was commit
> > > 9c38b704d280ac128003238d7d80bf07fa556a7d where the rte_service API was
> > > introduced as experimental by Nikhil Rao, and then later used in the eal library
> > > as part of commit a894d4815f79b0d76527d9c42b23327de1501711 by Harry van Haaren.
> > > Its no big deal because, as we agree, internal usage should be considered safe,
> > > but it seemed clear that differing authors were using each others code
> > > (potentially oblivious to the experimental nature of those APIs)
> > >
> > > > But OK, I guess it won't hurt to have more granular approach.
> > > >
> > > > >
> > > > >> Do we have any option than allowing them in DPDK library? And when experimental
> > > > >> API modified the users in the DPDK library internally guaranteed to be updated.
> > > > >> Why not globally allow this for all DPDK internally?
> > > > >>
> > > > > For the reason I gave above. We certainly could enable this in a more top-level
> > > > > makefile so that for in-library systems it was opt-in rather than opt-out, but I
> > > > > chose a more granular approach because I could envision newer libraries wanting
> > > > > it on. I also felt, generally speaking, that where warning flags were
> > > > > concerned, it generally desireous to have them on by default, and make people
> > > > > explicitly choose to turn them off.
> >
> > I think DPDK developpers look at the EXPERIMENTAL warning in the doxygen
> > above the prototype.
> I'm not sure I agree with that, but regardless, my initial reasoning for writing
> this tag was to call attention to experimental API's during review, rather than
> their use during development, so I didn't gripe about ABI changes on expemted
> code. Additionally, weather they look at the docs or not, they can
> pre-emptively turn off the warning if they choose.
>
> > And when API will be switched to stable, we probably won't remove the flag
> > in the makefile to disable allowing experimental.
> Well, that remains to be seen I suppose.
>
> > So at the end, we could just allow experimental API for all internal libs.
> Thats a rather bootstrapping argument. You are effecitvely saying that no one
> developing will ever want to be warned of using experimental APIs in DPDK, so
> lets just turn it off everyone. I would really rather let individual developers
> make that call at the time they author something new.
I don't see the benefit,
but I am OK to keep it like this.
^ permalink raw reply [flat|nested] 83+ messages in thread
* [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging
2017-12-01 18:56 [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
` (6 preceding siblings ...)
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
@ 2018-01-22 1:48 ` Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
` (5 more replies)
7 siblings, 6 replies; 83+ messages in thread
From: Neil Horman @ 2018-01-22 1:48 UTC (permalink / raw)
To: dev
Hey all-
A few days ago, I was lamenting the fact that, when reviewing patches I
would frequently complain about ABI changes that were actually considered safe
because they were part of the EXPERIMENTAL api set. John M. asked me then what
I might do to improve the situation, and the following patch set is a proposal
that I've come up with.
In thinking about the problem I identified two issues that I think we
can improve on in this area:
1) Make experimental api calls more visible in the source code. That is to say,
when reviewing patches, it would be nice to have some sort of visual reference
that indicates that the changes being made are part of an experimental API and
therefore ABI concerns need not be addressed
2) Make experimenal api usage more visible to consumers of the DPDK, so that
they can make a more informed decision about the API's they consume in their
application. We make an effort to document all the experimental API's, but
there is no guarantee that a user will check the documentation before making use
of a new library.
This patch set attempts to achieve both of the above goals. To do this I've
added an __experimental macro tag, suitable for inserting into api forward
declarations and definitions.
The presence of the tag in the header and c files where the api code resides
increases the likelyhood that any patch submitted against them will include the
tag in the context, making it clear to reviewers that ABI stability isn't a
concern here.
Also, This tag marks each function it is used on with an attibute causing any
use of the fuction to emit a warning during the build
with a message indicating that the API call in question is not yet part of the
stable interface. Developers can then make an informed decision to suppress
that warning or not.
Because there is internal use of several experimental API's, this set also
includes a new override macro ALLOW_EXPERIMENTAL_API to automatically
suprress these warnings. I think its fair to assume that, for internal use, we
almost always want to suppress these warnings, as by definition any change to
the apis (even their removal) must be done in parallel with an appropriate
change in the calling locations, lest the dpdk build itself break.
Neil
---
v5 Changes
* Clean ups suggested by Thomas
^ permalink raw reply [flat|nested] 83+ messages in thread
* [[PATCH v5] 1/5] buildtools: Add tool to check EXPERIMENTAL api exports
2018-01-22 1:48 ` [PATCH 0/5] " Neil Horman
@ 2018-01-22 1:48 ` Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 2/5] compat: Add __rte_experimental macro Neil Horman
` (4 subsequent siblings)
5 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2018-01-22 1:48 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John, Bruce Richardson
This tools reads the given version map for a directory, and checks to
ensure that, for each symbol listed in the export list, the corresponding
definition is tagged as __rte_experimental, erroring out if its not. In this
way, we can ensure that the EXPERIMENTAL api is kept in sync with the tags
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
MAINTAINERS | 1 +
buildtools/check-experimental-syms.sh | 32 ++++++++++++++++++++++++++++++++
2 files changed, 33 insertions(+)
create mode 100755 buildtools/check-experimental-syms.sh
diff --git a/MAINTAINERS b/MAINTAINERS
index b51c2d096..446d2545d 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -77,6 +77,7 @@ M: Neil Horman <nhorman@tuxdriver.com>
F: lib/librte_compat/
F: doc/guides/rel_notes/deprecation.rst
F: devtools/validate-abi.sh
+F: buildtools/check-experimental-syms.sh
Driver information
F: buildtools/pmdinfogen/
diff --git a/buildtools/check-experimental-syms.sh b/buildtools/check-experimental-syms.sh
new file mode 100755
index 000000000..7d21de35c
--- /dev/null
+++ b/buildtools/check-experimental-syms.sh
@@ -0,0 +1,32 @@
+#!/bin/sh
+
+# SPDX-License-Identifier: BSD-3-Clause
+
+MAPFILE=$1
+OBJFILE=$2
+
+if [ -d $MAPFILE ]
+then
+ exit 0
+fi
+
+for i in `awk 'BEGIN {found=0}
+ /.*EXPERIMENTAL.*/ {found=1}
+ /.*}.*;/ {found=0}
+ /.*;/ {if (found == 1) print $1}' $MAPFILE`
+do
+ SYM=`echo $i | sed -e"s/;//"`
+ objdump -t $OBJFILE | grep -q "\.text.*$SYM"
+ IN_TEXT=$?
+ objdump -t $OBJFILE | grep -q "\.text\.experimental.*$SYM"
+ IN_EXP=$?
+ if [ $IN_TEXT -eq 0 -a $IN_EXP -ne 0 ]
+ then
+ echo "$SYM is not flagged as experimental"
+ echo "but is listed in version map"
+ echo "Please add __rte_experimental to the definition of $SYM"
+ exit 1
+ fi
+done
+exit 0
+
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [[PATCH v5] 2/5] compat: Add __rte_experimental macro
2018-01-22 1:48 ` [PATCH 0/5] " Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
@ 2018-01-22 1:48 ` Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
` (3 subsequent siblings)
5 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2018-01-22 1:48 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John, Bruce Richardson
The __rte_experimental macro tags a given exported function as being part of
the EXPERIMENTAL api. Use of this tag will cause any caller of the
function (that isn't removed by dead code elimination) to emit a warning
that the user is making use of an API whos stabilty isn't guaranteed.
It also places the function in the .text.experimental section, which is
used to validate the tag against the corresponding library version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
lib/librte_compat/rte_compat.h | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/lib/librte_compat/rte_compat.h b/lib/librte_compat/rte_compat.h
index 41e8032ba..ad8f81ffe 100644
--- a/lib/librte_compat/rte_compat.h
+++ b/lib/librte_compat/rte_compat.h
@@ -101,5 +101,16 @@
*/
#endif
+#ifndef ALLOW_EXPERIMENTAL_API
+#define __rte_experimental \
+__attribute__((deprecated("Symbol is not yet part of stable ABI"), \
+section(".text.experimental")))
+
+#else
+
+#define __rte_experimental \
+__attribute__((section(".text.experimental")))
+
+#endif
#endif /* _RTE_COMPAT_H_ */
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [[PATCH v5] 3/5] Makefiles: Add experimental tag check and warnings to trigger on use
2018-01-22 1:48 ` [PATCH 0/5] " Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 2/5] compat: Add __rte_experimental macro Neil Horman
@ 2018-01-22 1:48 ` Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 4/5] dpdk: add __rte_experimental tag to appropriate api calls Neil Horman
` (2 subsequent siblings)
5 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2018-01-22 1:48 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John, Bruce Richardson
Add checks during build to ensure that all symbols in the EXPERIMENTAL
version map section have __experimental tags on their definitions, and
enable the warnings needed to announce their use. Also add an
ALLOW_EXPERIMENTAL_APIS define to allow individual libraries and files
to declare the acceptability of experimental api usage
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
app/test-eventdev/Makefile | 1 +
app/test-pmd/Makefile | 1 +
drivers/event/sw/Makefile | 1 +
drivers/net/failsafe/Makefile | 1 +
drivers/net/ixgbe/Makefile | 1 +
examples/eventdev_pipeline_sw_pmd/Makefile | 1 +
examples/flow_classify/Makefile | 1 +
examples/ipsec-secgw/Makefile | 1 +
examples/service_cores/Makefile | 1 +
lib/librte_eal/bsdapp/eal/Makefile | 1 +
lib/librte_eal/linuxapp/Makefile | 2 ++
lib/librte_eal/linuxapp/eal/Makefile | 2 ++
lib/librte_eventdev/Makefile | 1 +
lib/librte_security/Makefile | 1 +
mk/internal/rte.compile-pre.mk | 4 ++++
mk/toolchain/clang/rte.vars.mk | 2 +-
mk/toolchain/gcc/rte.vars.mk | 2 +-
mk/toolchain/icc/rte.vars.mk | 2 +-
18 files changed, 23 insertions(+), 3 deletions(-)
diff --git a/app/test-eventdev/Makefile b/app/test-eventdev/Makefile
index cfe567a6d..2a9cc1fb1 100644
--- a/app/test-eventdev/Makefile
+++ b/app/test-eventdev/Makefile
@@ -6,6 +6,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
APP = dpdk-test-eventdev
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/app/test-pmd/Makefile b/app/test-pmd/Makefile
index 82b3481c0..ce4e578fe 100644
--- a/app/test-pmd/Makefile
+++ b/app/test-pmd/Makefile
@@ -10,6 +10,7 @@ ifeq ($(CONFIG_RTE_TEST_PMD),y)
#
APP = testpmd
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/drivers/event/sw/Makefile b/drivers/event/sw/Makefile
index 0ff9a7f28..6c38bf6f6 100644
--- a/drivers/event/sw/Makefile
+++ b/drivers/event/sw/Makefile
@@ -7,6 +7,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
LIB = librte_pmd_sw_event.a
# build flags
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
# for older GCC versions, allow us to initialize an event using
diff --git a/drivers/net/failsafe/Makefile b/drivers/net/failsafe/Makefile
index ea2a8fe46..a3b8173aa 100644
--- a/drivers/net/failsafe/Makefile
+++ b/drivers/net/failsafe/Makefile
@@ -50,6 +50,7 @@ SRCS-$(CONFIG_RTE_LIBRTE_PMD_FAILSAFE) += failsafe_flow.c
# No exported include files
# Basic CFLAGS:
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -std=gnu99 -Wextra
CFLAGS += -O3
CFLAGS += -I.
diff --git a/drivers/net/ixgbe/Makefile b/drivers/net/ixgbe/Makefile
index 9efa5a40c..d0804fc5b 100644
--- a/drivers/net/ixgbe/Makefile
+++ b/drivers/net/ixgbe/Makefile
@@ -8,6 +8,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
#
LIB = librte_pmd_ixgbe.a
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/eventdev_pipeline_sw_pmd/Makefile b/examples/eventdev_pipeline_sw_pmd/Makefile
index 241d0c141..66914f633 100644
--- a/examples/eventdev_pipeline_sw_pmd/Makefile
+++ b/examples/eventdev_pipeline_sw_pmd/Makefile
@@ -16,6 +16,7 @@ APP = eventdev_pipeline_sw_pmd
# all source are stored in SRCS-y
SRCS-y := main.c
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/flow_classify/Makefile b/examples/flow_classify/Makefile
index 56062486f..a00b75eff 100644
--- a/examples/flow_classify/Makefile
+++ b/examples/flow_classify/Makefile
@@ -17,6 +17,7 @@ APP = flow_classify
# all source are stored in SRCS-y
SRCS-y := flow_classify.c
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
diff --git a/examples/ipsec-secgw/Makefile b/examples/ipsec-secgw/Makefile
index 9b7bacb3e..c4d07cc9d 100644
--- a/examples/ipsec-secgw/Makefile
+++ b/examples/ipsec-secgw/Makefile
@@ -18,6 +18,7 @@ endif
APP = ipsec-secgw
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -O3 -gdwarf-2
CFLAGS += $(WERROR_FLAGS)
ifeq ($(CONFIG_RTE_TOOLCHAIN_ICC),y)
diff --git a/examples/service_cores/Makefile b/examples/service_cores/Makefile
index 2dc36134b..4f79c9776 100644
--- a/examples/service_cores/Makefile
+++ b/examples/service_cores/Makefile
@@ -16,6 +16,7 @@ APP = service_cores
# all source are stored in SRCS-y
SRCS-y := main.c
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += $(WERROR_FLAGS)
# workaround for a gcc bug with noreturn attribute
diff --git a/lib/librte_eal/bsdapp/eal/Makefile b/lib/librte_eal/bsdapp/eal/Makefile
index 3c3407b78..5e6ae5da3 100644
--- a/lib/librte_eal/bsdapp/eal/Makefile
+++ b/lib/librte_eal/bsdapp/eal/Makefile
@@ -9,6 +9,7 @@ ARCH_DIR ?= $(RTE_ARCH)
VPATH += $(RTE_SDK)/lib/librte_eal/common
VPATH += $(RTE_SDK)/lib/librte_eal/common/arch/$(ARCH_DIR)
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -I$(SRCDIR)/include
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common/include
diff --git a/lib/librte_eal/linuxapp/Makefile b/lib/librte_eal/linuxapp/Makefile
index 7e94e914a..aa52a01ee 100644
--- a/lib/librte_eal/linuxapp/Makefile
+++ b/lib/librte_eal/linuxapp/Makefile
@@ -8,4 +8,6 @@ DIRS-$(CONFIG_RTE_EAL_IGB_UIO) += igb_uio
DIRS-$(CONFIG_RTE_KNI_KMOD) += kni
DEPDIRS-kni := eal
+CFLAGS += -DALLOW_EXPERIMENTAL_API
+
include $(RTE_SDK)/mk/rte.subdir.mk
diff --git a/lib/librte_eal/linuxapp/eal/Makefile b/lib/librte_eal/linuxapp/eal/Makefile
index 588c0bdfb..87c1db1f0 100644
--- a/lib/librte_eal/linuxapp/eal/Makefile
+++ b/lib/librte_eal/linuxapp/eal/Makefile
@@ -6,6 +6,7 @@ include $(RTE_SDK)/mk/rte.vars.mk
LIB = librte_eal.a
ARCH_DIR ?= $(RTE_ARCH)
+
EXPORT_MAP := ../../rte_eal_version.map
VPATH += $(RTE_SDK)/lib/librte_eal/common/arch/$(ARCH_DIR)
@@ -13,6 +14,7 @@ LIBABIVER := 6
VPATH += $(RTE_SDK)/lib/librte_eal/common
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -I$(SRCDIR)/include
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common
CFLAGS += -I$(RTE_SDK)/lib/librte_eal/common/include
diff --git a/lib/librte_eventdev/Makefile b/lib/librte_eventdev/Makefile
index 7fd78c7fd..d27dd0707 100644
--- a/lib/librte_eventdev/Makefile
+++ b/lib/librte_eventdev/Makefile
@@ -11,6 +11,7 @@ LIB = librte_eventdev.a
LIBABIVER := 3
# build flags
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
LDLIBS += -lrte_eal -lrte_ring -lrte_ethdev -lrte_hash
diff --git a/lib/librte_security/Makefile b/lib/librte_security/Makefile
index bd92343bd..8daebea46 100644
--- a/lib/librte_security/Makefile
+++ b/lib/librte_security/Makefile
@@ -10,6 +10,7 @@ LIB = librte_security.a
LIBABIVER := 1
# build flags
+CFLAGS += -DALLOW_EXPERIMENTAL_API
CFLAGS += -O3
CFLAGS += $(WERROR_FLAGS)
LDLIBS += -lrte_eal -lrte_mempool
diff --git a/mk/internal/rte.compile-pre.mk b/mk/internal/rte.compile-pre.mk
index d1dd6df02..a734cbbd0 100644
--- a/mk/internal/rte.compile-pre.mk
+++ b/mk/internal/rte.compile-pre.mk
@@ -56,6 +56,9 @@ C_TO_O = $(CC) -Wp,-MD,$(call obj2dep,$(@)).tmp $(CPPFLAGS) $(CFLAGS) \
C_TO_O_STR = $(subst ','\'',$(C_TO_O)) #'# fix syntax highlight
C_TO_O_DISP = $(if $(V),"$(C_TO_O_STR)"," CC $(@)")
endif
+EXPERIMENTAL_CHECK = $(RTE_SDK)/buildtools/check-experimental-syms.sh
+CHECK_EXPERIMENTAL = $(EXPERIMENTAL_CHECK) $(SRCDIR)/$(EXPORT_MAP) $@
+
PMDINFO_GEN = $(RTE_SDK_BIN)/app/dpdk-pmdinfogen $@ $@.pmd.c
PMDINFO_CC = $(CC) $(CPPFLAGS) $(CFLAGS) -c -o $@.pmd.o $@.pmd.c
PMDINFO_LD = $(CROSS)ld $(LDFLAGS) -r -o $@.o $@.pmd.o $@
@@ -72,6 +75,7 @@ C_TO_O_DO = @set -e; \
echo $(C_TO_O_DISP); \
$(C_TO_O) && \
$(PMDINFO_TO_O) && \
+ $(CHECK_EXPERIMENTAL) && \
echo $(C_TO_O_CMD) > $(call obj2cmd,$(@)) && \
sed 's,'$@':,dep_'$@' =,' $(call obj2dep,$(@)).tmp > $(call obj2dep,$(@)) && \
rm -f $(call obj2dep,$(@)).tmp
diff --git a/mk/toolchain/clang/rte.vars.mk b/mk/toolchain/clang/rte.vars.mk
index 52ca9fca3..3c49dc568 100644
--- a/mk/toolchain/clang/rte.vars.mk
+++ b/mk/toolchain/clang/rte.vars.mk
@@ -39,7 +39,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/gcc/rte.vars.mk b/mk/toolchain/gcc/rte.vars.mk
index 7763ba79b..7e4531bab 100644
--- a/mk/toolchain/gcc/rte.vars.mk
+++ b/mk/toolchain/gcc/rte.vars.mk
@@ -47,7 +47,7 @@ WERROR_FLAGS := -W -Wall -Wstrict-prototypes -Wmissing-prototypes
WERROR_FLAGS += -Wmissing-declarations -Wold-style-definition -Wpointer-arith
WERROR_FLAGS += -Wcast-align -Wnested-externs -Wcast-qual
WERROR_FLAGS += -Wformat-nonliteral -Wformat-security
-WERROR_FLAGS += -Wundef -Wwrite-strings
+WERROR_FLAGS += -Wundef -Wwrite-strings -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror
diff --git a/mk/toolchain/icc/rte.vars.mk b/mk/toolchain/icc/rte.vars.mk
index ff338d661..aa1422bf1 100644
--- a/mk/toolchain/icc/rte.vars.mk
+++ b/mk/toolchain/icc/rte.vars.mk
@@ -45,7 +45,7 @@ TOOLCHAIN_ASFLAGS =
WERROR_FLAGS := -Wall -w2 -diag-disable 271 -diag-warning 1478
WERROR_FLAGS += -diag-disable 13368 -diag-disable 15527
WERROR_FLAGS += -diag-disable 188
-WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076
+WERROR_FLAGS += -diag-disable 11074 -diag-disable 11076 -Wdeprecated
ifeq ($(RTE_DEVEL_BUILD),y)
WERROR_FLAGS += -Werror-all
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [[PATCH v5] 4/5] dpdk: add __rte_experimental tag to appropriate api calls
2018-01-22 1:48 ` [PATCH 0/5] " Neil Horman
` (2 preceding siblings ...)
2018-01-22 1:48 ` [[PATCH v5] 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
@ 2018-01-22 1:48 ` Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation Neil Horman
2018-01-29 21:46 ` [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging Thomas Monjalon
5 siblings, 0 replies; 83+ messages in thread
From: Neil Horman @ 2018-01-22 1:48 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John, Bruce Richardson
Append the __rte_experimental tag to api calls appearing in the EXPERIMENTAL
section of their libraries version map
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
lib/librte_eal/common/eal_common_dev.c | 6 ++-
lib/librte_eal/common/eal_common_devargs.c | 7 +--
lib/librte_eal/common/include/rte_dev.h | 6 ++-
lib/librte_eal/common/include/rte_devargs.h | 8 ++--
lib/librte_eal/common/include/rte_service.h | 47 ++++++++++---------
.../common/include/rte_service_component.h | 14 +++---
lib/librte_eal/common/rte_service.c | 52 ++++++++++++----------
lib/librte_eal/linuxapp/eal/eal.c | 1 +
lib/librte_ether/rte_mtr.c | 25 ++++++-----
lib/librte_ether/rte_mtr.h | 26 +++++------
lib/librte_flow_classify/rte_flow_classify.c | 13 +++---
lib/librte_flow_classify/rte_flow_classify.h | 11 ++---
lib/librte_security/rte_security.c | 16 +++----
lib/librte_security/rte_security.h | 23 +++++-----
14 files changed, 139 insertions(+), 116 deletions(-)
diff --git a/lib/librte_eal/common/eal_common_dev.c b/lib/librte_eal/common/eal_common_dev.c
index dda8f5835..0de1c5d62 100644
--- a/lib/librte_eal/common/eal_common_dev.c
+++ b/lib/librte_eal/common/eal_common_dev.c
@@ -37,6 +37,7 @@
#include <inttypes.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
#include <rte_dev.h>
#include <rte_devargs.h>
@@ -133,7 +134,7 @@ full_dev_name(const char *bus, const char *dev, const char *args)
return name;
}
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __rte_experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs)
{
struct rte_bus *bus;
@@ -203,7 +204,8 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
return ret;
}
-int rte_eal_hotplug_remove(const char *busname, const char *devname)
+int __rte_experimental
+rte_eal_hotplug_remove(const char *busname, const char *devname)
{
struct rte_bus *bus;
struct rte_device *dev;
diff --git a/lib/librte_eal/common/eal_common_devargs.c b/lib/librte_eal/common/eal_common_devargs.c
index 6ac88d6ab..3db07ee99 100644
--- a/lib/librte_eal/common/eal_common_devargs.c
+++ b/lib/librte_eal/common/eal_common_devargs.c
@@ -40,6 +40,7 @@
#include <stdio.h>
#include <string.h>
+#include <rte_compat.h>
#include <rte_dev.h>
#include <rte_devargs.h>
#include <rte_tailq.h>
@@ -85,7 +86,7 @@ bus_name_cmp(const struct rte_bus *bus, const void *name)
return strncmp(bus->name, name, strlen(bus->name));
}
-int
+int __rte_experimental
rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
{
struct rte_bus *bus = NULL;
@@ -139,7 +140,7 @@ rte_eal_devargs_parse(const char *dev, struct rte_devargs *da)
return 0;
}
-int
+int __rte_experimental
rte_eal_devargs_insert(struct rte_devargs *da)
{
int ret;
@@ -188,7 +189,7 @@ rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str)
return -1;
}
-int
+int __rte_experimental
rte_eal_devargs_remove(const char *busname, const char *devname)
{
struct rte_devargs *d;
diff --git a/lib/librte_eal/common/include/rte_dev.h b/lib/librte_eal/common/include/rte_dev.h
index 9342e0cbd..9fee224f2 100644
--- a/lib/librte_eal/common/include/rte_dev.h
+++ b/lib/librte_eal/common/include/rte_dev.h
@@ -49,6 +49,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_log.h>
__attribute__((format(printf, 2, 0)))
@@ -209,7 +210,7 @@ int rte_eal_dev_detach(struct rte_device *dev);
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_add(const char *busname, const char *devname,
+int __rte_experimental rte_eal_hotplug_add(const char *busname, const char *devname,
const char *devargs);
/**
@@ -225,7 +226,8 @@ int rte_eal_hotplug_add(const char *busname, const char *devname,
* @return
* 0 on success, negative on error.
*/
-int rte_eal_hotplug_remove(const char *busname, const char *devname);
+int __rte_experimental rte_eal_hotplug_remove(const char *busname,
+ const char *devname);
/**
* Device comparison function.
diff --git a/lib/librte_eal/common/include/rte_devargs.h b/lib/librte_eal/common/include/rte_devargs.h
index 58d585df6..e7579f82a 100644
--- a/lib/librte_eal/common/include/rte_devargs.h
+++ b/lib/librte_eal/common/include/rte_devargs.h
@@ -50,6 +50,7 @@ extern "C" {
#include <stdio.h>
#include <sys/queue.h>
+#include <rte_compat.h>
#include <rte_bus.h>
/**
@@ -136,7 +137,7 @@ int rte_eal_parse_devargs_str(const char *devargs_str,
* - 0 on success.
* - Negative errno on error.
*/
-int
+int __rte_experimental
rte_eal_devargs_parse(const char *dev,
struct rte_devargs *da);
@@ -150,7 +151,7 @@ rte_eal_devargs_parse(const char *dev,
* - 0 on success
* - Negative on error.
*/
-int
+int __rte_experimental
rte_eal_devargs_insert(struct rte_devargs *da);
/**
@@ -193,7 +194,8 @@ int rte_eal_devargs_add(enum rte_devtype devtype, const char *devargs_str);
* <0 on error.
* >0 if the devargs was not within the user device list.
*/
-int rte_eal_devargs_remove(const char *busname, const char *devname);
+int __rte_experimental rte_eal_devargs_remove(const char *busname,
+ const char *devname);
/**
* Count the number of user devices of a specified type
diff --git a/lib/librte_eal/common/include/rte_service.h b/lib/librte_eal/common/include/rte_service.h
index 5a763831e..ed95d025d 100644
--- a/lib/librte_eal/common/include/rte_service.h
+++ b/lib/librte_eal/common/include/rte_service.h
@@ -56,7 +56,7 @@ extern "C" {
*
* @return The number of services registered.
*/
-uint32_t rte_service_get_count(void);
+uint32_t __rte_experimental rte_service_get_count(void);
/**
* @warning
@@ -83,7 +83,8 @@ uint32_t rte_service_get_count(void);
* @retval -EINVAL Null *service_id* pointer provided
* @retval -ENODEV No such service registered
*/
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
+int32_t __rte_experimental rte_service_get_by_name(const char *name,
+ uint32_t *service_id);
/**
* @warning
@@ -94,7 +95,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id);
* @return A pointer to the name of the service. The returned pointer remains
* in ownership of the service, and the application must not free it.
*/
-const char *rte_service_get_name(uint32_t id);
+const char __rte_experimental *rte_service_get_name(uint32_t id);
/**
* @warning
@@ -107,7 +108,8 @@ const char *rte_service_get_name(uint32_t id);
* @retval 1 Capability supported by this service instance
* @retval 0 Capability not supported by this service instance
*/
-int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
+int32_t __rte_experimental rte_service_probe_capability(uint32_t id,
+ uint32_t capability);
/**
* @warning
@@ -131,8 +133,8 @@ int32_t rte_service_probe_capability(uint32_t id, uint32_t capability);
* @retval 0 lcore map updated successfully
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
- uint32_t enable);
+int32_t __rte_experimental rte_service_map_lcore_set(uint32_t service_id,
+ uint32_t lcore, uint32_t enable);
/**
* @warning
@@ -147,7 +149,8 @@ int32_t rte_service_map_lcore_set(uint32_t service_id, uint32_t lcore,
* @retval 0 lcore is not mapped to service
* @retval -EINVAL An invalid service or lcore was provided.
*/
-int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
+int32_t __rte_experimental rte_service_map_lcore_get(uint32_t service_id,
+ uint32_t lcore);
/**
* @warning
@@ -164,7 +167,7 @@ int32_t rte_service_map_lcore_get(uint32_t service_id, uint32_t lcore);
* @retval 0 The service was successfully started
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __rte_experimental rte_service_runstate_set(uint32_t id, uint32_t runstate);
/**
* @warning
@@ -182,7 +185,7 @@ int32_t rte_service_runstate_set(uint32_t id, uint32_t runstate);
* @retval 0 Service is stopped
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_runstate_get(uint32_t id);
+int32_t __rte_experimental rte_service_runstate_get(uint32_t id);
/**
* @warning
@@ -198,7 +201,8 @@ int32_t rte_service_runstate_get(uint32_t id);
* @retval 0 Success
* @retval -EINVAL Invalid service ID
*/
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
+int32_t __rte_experimental rte_service_set_runstate_mapped_check(uint32_t id,
+ int32_t enable);
/**
* @warning
@@ -236,7 +240,7 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enable);
* @retval -ENOEXEC Service is not in a run-able state
* @retval -EINVAL Invalid service id
*/
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __rte_experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_multithread_unsafe);
/**
@@ -252,7 +256,7 @@ int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
* @retval -EINVAL Failed to start core. The *lcore_id* passed in is not
* currently assigned to be a service core.
*/
-int32_t rte_service_lcore_start(uint32_t lcore_id);
+int32_t __rte_experimental rte_service_lcore_start(uint32_t lcore_id);
/**
* @warning
@@ -271,7 +275,7 @@ int32_t rte_service_lcore_start(uint32_t lcore_id);
* The application must stop the service first, and then stop the
* lcore.
*/
-int32_t rte_service_lcore_stop(uint32_t lcore_id);
+int32_t __rte_experimental rte_service_lcore_stop(uint32_t lcore_id);
/**
* @warning
@@ -287,7 +291,7 @@ int32_t rte_service_lcore_stop(uint32_t lcore_id);
* @retval -EALREADY lcore is already added to the service core list
* @retval -EINVAL Invalid lcore provided
*/
-int32_t rte_service_lcore_add(uint32_t lcore);
+int32_t __rte_experimental rte_service_lcore_add(uint32_t lcore);
/**
* @warning
@@ -301,7 +305,7 @@ int32_t rte_service_lcore_add(uint32_t lcore);
* @retval -EBUSY Lcore is not stopped, stop service core before removing.
* @retval -EINVAL failed to add lcore to service core mask.
*/
-int32_t rte_service_lcore_del(uint32_t lcore);
+int32_t __rte_experimental rte_service_lcore_del(uint32_t lcore);
/**
* @warning
@@ -318,7 +322,7 @@ int32_t rte_service_lcore_del(uint32_t lcore);
*
* @return The number of service cores currently configured.
*/
-int32_t rte_service_lcore_count(void);
+int32_t __rte_experimental rte_service_lcore_count(void);
/**
* @warning
@@ -330,7 +334,7 @@ int32_t rte_service_lcore_count(void);
*
* @retval 0 Success
*/
-int32_t rte_service_lcore_reset_all(void);
+int32_t __rte_experimental rte_service_lcore_reset_all(void);
/**
* @warning
@@ -344,7 +348,8 @@ int32_t rte_service_lcore_reset_all(void);
* @retval 0 Success
* @retval -EINVAL Invalid service pointer passed
*/
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
+int32_t __rte_experimental rte_service_set_stats_enable(uint32_t id,
+ int32_t enable);
/**
* @warning
@@ -365,7 +370,7 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enable);
* service core list. No items have been populated, call this function
* with a size of at least *rte_service_core_count* items.
*/
-int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
+int32_t __rte_experimental rte_service_lcore_list(uint32_t array[], uint32_t n);
/**
* @warning
@@ -378,7 +383,7 @@ int32_t rte_service_lcore_list(uint32_t array[], uint32_t n);
* @retval -EINVAL Invalid lcore provided
* @retval -ENOTSUP The provided lcore is not a service core.
*/
-int32_t rte_service_lcore_count_services(uint32_t lcore);
+int32_t __rte_experimental rte_service_lcore_count_services(uint32_t lcore);
/**
* @warning
@@ -390,7 +395,7 @@ int32_t rte_service_lcore_count_services(uint32_t lcore);
* @retval 0 Statistics have been successfully dumped
* @retval -EINVAL Invalid service id provided
*/
-int32_t rte_service_dump(FILE *f, uint32_t id);
+int32_t __rte_experimental rte_service_dump(FILE *f, uint32_t id);
#ifdef __cplusplus
}
diff --git a/lib/librte_eal/common/include/rte_service_component.h b/lib/librte_eal/common/include/rte_service_component.h
index 849c71d4a..1fe44f172 100644
--- a/lib/librte_eal/common/include/rte_service_component.h
+++ b/lib/librte_eal/common/include/rte_service_component.h
@@ -9,7 +9,7 @@
* Include this file if you are writing a component that requires CPU cycles to
* operate, and you wish to run the component using service cores
*/
-
+#include <rte_compat.h>
#include <rte_service.h>
/**
@@ -73,8 +73,9 @@ struct rte_service_spec {
* -EINVAL Attempted to register an invalid service (eg, no callback
* set)
*/
-int32_t rte_service_component_register(const struct rte_service_spec *spec,
- uint32_t *service_id);
+int32_t __rte_experimental
+rte_service_component_register(const struct rte_service_spec *spec,
+ uint32_t *service_id);
/**
* @warning
@@ -88,7 +89,7 @@ int32_t rte_service_component_register(const struct rte_service_spec *spec,
* @retval -EBUSY The service is currently running, stop the service before
* calling unregister. No action has been taken.
*/
-int32_t rte_service_component_unregister(uint32_t id);
+int32_t __rte_experimental rte_service_component_unregister(uint32_t id);
/**
* @warning
@@ -106,7 +107,7 @@ int32_t rte_service_component_unregister(uint32_t id);
* @retval -ENODEV Error in enabling service lcore on a service
* @retval -ENOEXEC Error when starting services
*/
-int32_t rte_service_start_with_defaults(void);
+int32_t __rte_experimental rte_service_start_with_defaults(void);
/**
* @warning
@@ -123,7 +124,8 @@ int32_t rte_service_start_with_defaults(void);
*
* @retval 0 Success
*/
-int32_t rte_service_component_runstate_set(uint32_t id, uint32_t runstate);
+int32_t __rte_experimental rte_service_component_runstate_set(uint32_t id,
+ uint32_t runstate);
/**
* @warning
diff --git a/lib/librte_eal/common/rte_service.c b/lib/librte_eal/common/rte_service.c
index 372d0bbb3..1b0be108b 100644
--- a/lib/librte_eal/common/rte_service.c
+++ b/lib/librte_eal/common/rte_service.c
@@ -9,6 +9,7 @@
#include <string.h>
#include <dirent.h>
+#include <rte_compat.h>
#include <rte_service.h>
#include "include/rte_service_component.h"
@@ -139,7 +140,8 @@ service_mt_safe(struct rte_service_spec_impl *s)
return !!(s->spec.capabilities & RTE_SERVICE_CAP_MT_SAFE);
}
-int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
+int32_t __rte_experimental
+rte_service_set_stats_enable(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -152,7 +154,8 @@ int32_t rte_service_set_stats_enable(uint32_t id, int32_t enabled)
return 0;
}
-int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
+int32_t __rte_experimental
+rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
{
struct rte_service_spec_impl *s;
SERVICE_VALID_GET_OR_ERR_RET(id, s, 0);
@@ -165,13 +168,14 @@ int32_t rte_service_set_runstate_mapped_check(uint32_t id, int32_t enabled)
return 0;
}
-uint32_t
+uint32_t __rte_experimental
rte_service_get_count(void)
{
return rte_service_count;
}
-int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
+int32_t __rte_experimental
+rte_service_get_by_name(const char *name, uint32_t *service_id)
{
if (!service_id)
return -EINVAL;
@@ -188,7 +192,7 @@ int32_t rte_service_get_by_name(const char *name, uint32_t *service_id)
return -ENODEV;
}
-const char *
+const char * __rte_experimental
rte_service_get_name(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -196,7 +200,7 @@ rte_service_get_name(uint32_t id)
return s->spec.name;
}
-int32_t
+int32_t __rte_experimental
rte_service_probe_capability(uint32_t id, uint32_t capability)
{
struct rte_service_spec_impl *s;
@@ -204,7 +208,7 @@ rte_service_probe_capability(uint32_t id, uint32_t capability)
return !!(s->spec.capabilities & capability);
}
-int32_t
+int32_t __rte_experimental
rte_service_component_register(const struct rte_service_spec *spec,
uint32_t *id_ptr)
{
@@ -237,7 +241,7 @@ rte_service_component_register(const struct rte_service_spec *spec,
return 0;
}
-int32_t
+int32_t __rte_experimental
rte_service_component_unregister(uint32_t id)
{
uint32_t i;
@@ -258,7 +262,7 @@ rte_service_component_unregister(uint32_t id)
return 0;
}
-int32_t
+int32_t __rte_experimental
rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -273,7 +277,7 @@ rte_service_component_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __rte_experimental
rte_service_runstate_set(uint32_t id, uint32_t runstate)
{
struct rte_service_spec_impl *s;
@@ -288,7 +292,7 @@ rte_service_runstate_set(uint32_t id, uint32_t runstate)
return 0;
}
-int32_t
+int32_t __rte_experimental
rte_service_runstate_get(uint32_t id)
{
struct rte_service_spec_impl *s;
@@ -349,7 +353,7 @@ service_run(uint32_t i, struct core_state *cs, uint64_t service_mask)
return 0;
}
-int32_t rte_service_run_iter_on_app_lcore(uint32_t id,
+int32_t __rte_experimental rte_service_run_iter_on_app_lcore(uint32_t id,
uint32_t serialize_mt_unsafe)
{
/* run service on calling core, using all-ones as the service mask */
@@ -405,7 +409,7 @@ rte_service_runner_func(void *arg)
return 0;
}
-int32_t
+int32_t __rte_experimental
rte_service_lcore_count(void)
{
int32_t count = 0;
@@ -415,7 +419,7 @@ rte_service_lcore_count(void)
return count;
}
-int32_t
+int32_t __rte_experimental
rte_service_lcore_list(uint32_t array[], uint32_t n)
{
uint32_t count = rte_service_lcore_count();
@@ -438,7 +442,7 @@ rte_service_lcore_list(uint32_t array[], uint32_t n)
return count;
}
-int32_t
+int32_t __rte_experimental
rte_service_lcore_count_services(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -451,7 +455,7 @@ rte_service_lcore_count_services(uint32_t lcore)
return __builtin_popcountll(cs->service_mask);
}
-int32_t
+int32_t __rte_experimental
rte_service_start_with_defaults(void)
{
/* create a default mapping from cores to services, then start the
@@ -533,7 +537,7 @@ service_update(struct rte_service_spec *service, uint32_t lcore,
return 0;
}
-int32_t
+int32_t __rte_experimental
rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
{
struct rte_service_spec_impl *s;
@@ -542,7 +546,7 @@ rte_service_map_lcore_set(uint32_t id, uint32_t lcore, uint32_t enabled)
return service_update(&s->spec, lcore, &on, 0);
}
-int32_t
+int32_t __rte_experimental
rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
{
struct rte_service_spec_impl *s;
@@ -554,7 +558,7 @@ rte_service_map_lcore_get(uint32_t id, uint32_t lcore)
return ret;
}
-int32_t rte_service_lcore_reset_all(void)
+int32_t __rte_experimental rte_service_lcore_reset_all(void)
{
/* loop over cores, reset all to mask 0 */
uint32_t i;
@@ -585,7 +589,7 @@ set_lcore_state(uint32_t lcore, int32_t state)
lcore_states[lcore].is_service_core = (state == ROLE_SERVICE);
}
-int32_t
+int32_t __rte_experimental
rte_service_lcore_add(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -604,7 +608,7 @@ rte_service_lcore_add(uint32_t lcore)
return rte_eal_wait_lcore(lcore);
}
-int32_t
+int32_t __rte_experimental
rte_service_lcore_del(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -623,7 +627,7 @@ rte_service_lcore_del(uint32_t lcore)
return 0;
}
-int32_t
+int32_t __rte_experimental
rte_service_lcore_start(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -646,7 +650,7 @@ rte_service_lcore_start(uint32_t lcore)
return ret;
}
-int32_t
+int32_t __rte_experimental
rte_service_lcore_stop(uint32_t lcore)
{
if (lcore >= RTE_MAX_LCORE)
@@ -716,7 +720,7 @@ service_dump_calls_per_lcore(FILE *f, uint32_t lcore, uint32_t reset)
fprintf(f, "\n");
}
-int32_t rte_service_dump(FILE *f, uint32_t id)
+int32_t __rte_experimental rte_service_dump(FILE *f, uint32_t id)
{
uint32_t i;
int print_one = (id != UINT32_MAX);
diff --git a/lib/librte_eal/linuxapp/eal/eal.c b/lib/librte_eal/linuxapp/eal/eal.c
index 229eec9f1..73a0da22c 100644
--- a/lib/librte_eal/linuxapp/eal/eal.c
+++ b/lib/librte_eal/linuxapp/eal/eal.c
@@ -53,6 +53,7 @@
#include <sys/io.h>
#endif
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_debug.h>
#include <rte_memory.h>
diff --git a/lib/librte_ether/rte_mtr.c b/lib/librte_ether/rte_mtr.c
index a80f19a5b..1046cb5fd 100644
--- a/lib/librte_ether/rte_mtr.c
+++ b/lib/librte_ether/rte_mtr.c
@@ -5,6 +5,7 @@
#include <stdint.h>
#include <rte_errno.h>
+#include "rte_compat.h"
#include "rte_ethdev.h"
#include "rte_mtr_driver.h"
#include "rte_mtr.h"
@@ -57,7 +58,7 @@ rte_mtr_ops_get(uint16_t port_id, struct rte_mtr_error *error)
})
/* MTR capabilities get */
-int
+int __rte_experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error)
@@ -68,7 +69,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
}
/* MTR meter profile add */
-int
+int __rte_experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -80,7 +81,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
}
/** MTR meter profile delete */
-int
+int __rte_experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error)
@@ -91,7 +92,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
}
/** MTR object create */
-int
+int __rte_experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -104,7 +105,7 @@ rte_mtr_create(uint16_t port_id,
}
/** MTR object destroy */
-int
+int __rte_experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -115,7 +116,7 @@ rte_mtr_destroy(uint16_t port_id,
}
/** MTR object meter enable */
-int
+int __rte_experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -126,7 +127,7 @@ rte_mtr_meter_enable(uint16_t port_id,
}
/** MTR object meter disable */
-int
+int __rte_experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error)
@@ -137,7 +138,7 @@ rte_mtr_meter_disable(uint16_t port_id,
}
/** MTR object meter profile update */
-int
+int __rte_experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -149,7 +150,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
}
/** MTR object meter DSCP table update */
-int
+int __rte_experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -161,7 +162,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
}
/** MTR object policer action update */
-int
+int __rte_experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -174,7 +175,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
}
/** MTR object enabled stats update */
-int
+int __rte_experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -186,7 +187,7 @@ rte_mtr_stats_update(uint16_t port_id,
}
/** MTR object stats read */
-int
+int __rte_experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_ether/rte_mtr.h b/lib/librte_ether/rte_mtr.h
index f6b6ef3b6..c4819b274 100644
--- a/lib/librte_ether/rte_mtr.h
+++ b/lib/librte_ether/rte_mtr.h
@@ -74,7 +74,7 @@
* @b EXPERIMENTAL: this API may change without prior notice
*/
#include <stdint.h>
-
+#include <rte_compat.h>
#include <rte_common.h>
#ifdef __cplusplus
@@ -447,7 +447,7 @@ struct rte_mtr_error {
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __rte_experimental
rte_mtr_capabilities_get(uint16_t port_id,
struct rte_mtr_capabilities *cap,
struct rte_mtr_error *error);
@@ -470,7 +470,7 @@ rte_mtr_capabilities_get(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __rte_experimental
rte_mtr_meter_profile_add(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_meter_profile *profile,
@@ -491,7 +491,7 @@ rte_mtr_meter_profile_add(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __rte_experimental
rte_mtr_meter_profile_delete(uint16_t port_id,
uint32_t meter_profile_id,
struct rte_mtr_error *error);
@@ -519,7 +519,7 @@ rte_mtr_meter_profile_delete(uint16_t port_id,
*
* @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
*/
-int
+int __rte_experimental
rte_mtr_create(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_params *params,
@@ -542,7 +542,7 @@ rte_mtr_create(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __rte_experimental
rte_mtr_destroy(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -569,7 +569,7 @@ rte_mtr_destroy(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __rte_experimental
rte_mtr_meter_disable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -590,7 +590,7 @@ rte_mtr_meter_disable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __rte_experimental
rte_mtr_meter_enable(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_error *error);
@@ -609,7 +609,7 @@ rte_mtr_meter_enable(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __rte_experimental
rte_mtr_meter_profile_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t meter_profile_id,
@@ -633,7 +633,7 @@ rte_mtr_meter_profile_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __rte_experimental
rte_mtr_meter_dscp_table_update(uint16_t port_id,
uint32_t mtr_id,
enum rte_mtr_color *dscp_table,
@@ -659,7 +659,7 @@ rte_mtr_meter_dscp_table_update(uint16_t port_id,
* @return
* 0 on success, non-zero error code otherwise.
*/
-int
+int __rte_experimental
rte_mtr_policer_actions_update(uint16_t port_id,
uint32_t mtr_id,
uint32_t action_mask,
@@ -684,7 +684,7 @@ rte_mtr_policer_actions_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __rte_experimental
rte_mtr_stats_update(uint16_t port_id,
uint32_t mtr_id,
uint64_t stats_mask,
@@ -715,7 +715,7 @@ rte_mtr_stats_update(uint16_t port_id,
*
* @see enum rte_mtr_stats_type
*/
-int
+int __rte_experimental
rte_mtr_stats_read(uint16_t port_id,
uint32_t mtr_id,
struct rte_mtr_stats *stats,
diff --git a/lib/librte_flow_classify/rte_flow_classify.c b/lib/librte_flow_classify/rte_flow_classify.c
index 65d0a7514..6a4d1eb3d 100644
--- a/lib/librte_flow_classify/rte_flow_classify.c
+++ b/lib/librte_flow_classify/rte_flow_classify.c
@@ -2,6 +2,7 @@
* Copyright(c) 2017 Intel Corporation
*/
+#include <rte_compat.h>
#include <rte_flow_classify.h>
#include "rte_flow_classify_parse.h"
#include <rte_flow_driver.h>
@@ -216,7 +217,7 @@ rte_flow_classifier_check_params(struct rte_flow_classifier_params *params)
return 0;
}
-struct rte_flow_classifier *
+struct rte_flow_classifier * __rte_experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params)
{
struct rte_flow_classifier *cls;
@@ -262,7 +263,7 @@ rte_flow_classify_table_free(struct rte_table *table)
table->ops.f_free(table->h_table);
}
-int
+int __rte_experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls)
{
uint32_t i;
@@ -340,7 +341,7 @@ rte_table_check_params(struct rte_flow_classifier *cls,
return 0;
}
-int
+int __rte_experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id)
@@ -454,7 +455,7 @@ allocate_acl_ipv4_5tuple_rule(void)
return rule;
}
-struct rte_flow_classify_rule *
+struct rte_flow_classify_rule * __rte_experimental
rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
uint32_t table_id,
int *key_found,
@@ -553,7 +554,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
return rule;
}
-int
+int __rte_experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule)
@@ -630,7 +631,7 @@ action_apply(struct rte_flow_classifier *cls,
return ret;
}
-int
+int __rte_experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_flow_classify/rte_flow_classify.h b/lib/librte_flow_classify/rte_flow_classify.h
index e5f3e61d9..084cb4fa4 100644
--- a/lib/librte_flow_classify/rte_flow_classify.h
+++ b/lib/librte_flow_classify/rte_flow_classify.h
@@ -41,6 +41,7 @@
* with rte_flow_classifier_free()
*/
+#include <rte_compat.h>
#include <rte_ethdev.h>
#include <rte_ether.h>
#include <rte_flow.h>
@@ -147,7 +148,7 @@ struct rte_flow_classify_ipv4_5tuple_stats {
* @return
* Handle to flow classifier instance on success or NULL otherwise
*/
-struct rte_flow_classifier *
+struct rte_flow_classifier * __rte_experimental
rte_flow_classifier_create(struct rte_flow_classifier_params *params);
/**
@@ -158,7 +159,7 @@ rte_flow_classifier_create(struct rte_flow_classifier_params *params);
* @return
* 0 on success, error code otherwise
*/
-int
+int __rte_experimental
rte_flow_classifier_free(struct rte_flow_classifier *cls);
/**
@@ -174,7 +175,7 @@ rte_flow_classifier_free(struct rte_flow_classifier *cls);
* @return
* 0 on success, error code otherwise
*/
-int
+int __rte_experimental
rte_flow_classify_table_create(struct rte_flow_classifier *cls,
struct rte_flow_classify_table_params *params,
uint32_t *table_id);
@@ -221,7 +222,7 @@ rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __rte_experimental
rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_flow_classify_rule *rule);
@@ -245,7 +246,7 @@ rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
* @return
* 0 on success, error code otherwise.
*/
-int
+int __rte_experimental
rte_flow_classifier_query(struct rte_flow_classifier *cls,
uint32_t table_id,
struct rte_mbuf **pkts,
diff --git a/lib/librte_security/rte_security.c b/lib/librte_security/rte_security.c
index 1227fca8a..0a5409ed8 100644
--- a/lib/librte_security/rte_security.c
+++ b/lib/librte_security/rte_security.c
@@ -33,12 +33,12 @@
#include <rte_malloc.h>
#include <rte_dev.h>
-
+#include "rte_compat.h"
#include "rte_security.h"
#include "rte_security_driver.h"
struct rte_security_session *
-rte_security_session_create(struct rte_security_ctx *instance,
+__rte_experimental rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp)
{
@@ -61,7 +61,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
return sess;
}
-int
+int __rte_experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf)
@@ -70,7 +70,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
return instance->ops->session_update(instance->device, sess, conf);
}
-int
+int __rte_experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats)
@@ -79,7 +79,7 @@ rte_security_session_stats_get(struct rte_security_ctx *instance,
return instance->ops->session_stats_get(instance->device, sess, stats);
}
-int
+int __rte_experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess)
{
@@ -98,7 +98,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
return ret;
}
-int
+int __rte_experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *m, void *params)
@@ -108,14 +108,14 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
sess, m, params);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __rte_experimental
rte_security_capabilities_get(struct rte_security_ctx *instance)
{
RTE_FUNC_PTR_OR_ERR_RET(*instance->ops->capabilities_get, NULL);
return instance->ops->capabilities_get(instance->device);
}
-const struct rte_security_capability *
+const struct rte_security_capability * __rte_experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx)
{
diff --git a/lib/librte_security/rte_security.h b/lib/librte_security/rte_security.h
index 653929b99..9fa8bc3f3 100644
--- a/lib/librte_security/rte_security.h
+++ b/lib/librte_security/rte_security.h
@@ -52,6 +52,7 @@ extern "C" {
#include <netinet/ip.h>
#include <netinet/ip6.h>
+#include <rte_compat.h>
#include <rte_common.h>
#include <rte_crypto.h>
#include <rte_mbuf.h>
@@ -291,7 +292,7 @@ struct rte_security_session {
* - On success, pointer to session
* - On failure, NULL
*/
-struct rte_security_session *
+struct rte_security_session * __rte_experimental
rte_security_session_create(struct rte_security_ctx *instance,
struct rte_security_session_conf *conf,
struct rte_mempool *mp);
@@ -306,7 +307,7 @@ rte_security_session_create(struct rte_security_ctx *instance,
* - On success returns 0
* - On failure return errno
*/
-int
+int __rte_experimental
rte_security_session_update(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_session_conf *conf);
@@ -323,7 +324,7 @@ rte_security_session_update(struct rte_security_ctx *instance,
* - -EINVAL if session is NULL.
* - -EBUSY if not all device private data has been freed.
*/
-int
+int __rte_experimental
rte_security_session_destroy(struct rte_security_ctx *instance,
struct rte_security_session *sess);
@@ -340,7 +341,7 @@ rte_security_session_destroy(struct rte_security_ctx *instance,
* - On success, zero.
* - On failure, a negative value.
*/
-int
+int __rte_experimental
rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_mbuf *mb, void *params);
@@ -351,7 +352,7 @@ rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
* @param sym_op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __rte_experimental
__rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
struct rte_security_session *sess)
{
@@ -360,13 +361,13 @@ __rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
return 0;
}
-static inline void *
+static inline void * __rte_experimental
get_sec_session_private_data(const struct rte_security_session *sess)
{
return sess->sess_private_data;
}
-static inline void
+static inline void __rte_experimental
set_sec_session_private_data(struct rte_security_session *sess,
void *private_data)
{
@@ -382,7 +383,7 @@ set_sec_session_private_data(struct rte_security_session *sess,
* @param op crypto operation
* @param sess security session
*/
-static inline int
+static inline int __rte_experimental
rte_security_attach_session(struct rte_crypto_op *op,
struct rte_security_session *sess)
{
@@ -424,7 +425,7 @@ struct rte_security_stats {
* - On success return 0
* - On failure errno
*/
-int
+int __rte_experimental
rte_security_session_stats_get(struct rte_security_ctx *instance,
struct rte_security_session *sess,
struct rte_security_stats *stats);
@@ -507,7 +508,7 @@ struct rte_security_capability_idx {
* - Returns array of security capabilities.
* - Return NULL if no capabilities available.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __rte_experimental
rte_security_capabilities_get(struct rte_security_ctx *instance);
/**
@@ -521,7 +522,7 @@ rte_security_capabilities_get(struct rte_security_ctx *instance);
* index criteria.
* - Return NULL if the capability not matched on security instance.
*/
-const struct rte_security_capability *
+const struct rte_security_capability * __rte_experimental
rte_security_capability_get(struct rte_security_ctx *instance,
struct rte_security_capability_idx *idx);
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation
2018-01-22 1:48 ` [PATCH 0/5] " Neil Horman
` (3 preceding siblings ...)
2018-01-22 1:48 ` [[PATCH v5] 4/5] dpdk: add __rte_experimental tag to appropriate api calls Neil Horman
@ 2018-01-22 1:48 ` Neil Horman
2018-01-23 10:35 ` Mcnamara, John
2018-01-29 21:46 ` [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging Thomas Monjalon
5 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-22 1:48 UTC (permalink / raw)
To: dev; +Cc: Neil Horman, Thomas Monjalon, Mcnamara, John, Bruce Richardson
Document the need to add the __experimental tag to appropriate functions
Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
CC: Thomas Monjalon <thomas@monjalon.net>
CC: "Mcnamara, John" <john.mcnamara@intel.com>
CC: Bruce Richardson <bruce.richardson@intel.com>
---
doc/guides/contributing/versioning.rst | 14 ++++++++++++++
1 file changed, 14 insertions(+)
diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst
index 400090628..b4de9ed04 100644
--- a/doc/guides/contributing/versioning.rst
+++ b/doc/guides/contributing/versioning.rst
@@ -50,6 +50,20 @@ those new APIs and start finding issues with them, new DPDK APIs will be
automatically marked as ``experimental`` to allow for a period of stabilization
before they become part of a tracked ABI.
+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 definitions of those exported functions, and
+their forward declarations (in the development header files), must be marked
+with the __rte_experimental tag (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 during compilation in the corresponding library Makefile.
+
+In addition to tagging the code with __rte_experimental, the
+doxygen markup must also contain the EXPERIMENTAL string, and the MAINTAINER
+file should note that the library contains EXPERIMENTAL APIs.
+
ABI versions, once released, are available until such time as their
deprecation has been noted in the Release Notes for at least one major release
cycle. For example consider the case where the ABI for DPDK 2.0 has been
--
2.14.3
^ permalink raw reply related [flat|nested] 83+ messages in thread
* Re: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation
2018-01-22 1:48 ` [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation Neil Horman
@ 2018-01-23 10:35 ` Mcnamara, John
2018-01-29 21:42 ` Thomas Monjalon
0 siblings, 1 reply; 83+ messages in thread
From: Mcnamara, John @ 2018-01-23 10:35 UTC (permalink / raw)
To: Neil Horman, dev; +Cc: Thomas Monjalon, Richardson, Bruce
> -----Original Message-----
> From: Neil Horman [mailto:nhorman@tuxdriver.com]
> Sent: Monday, January 22, 2018 1:48 AM
> To: dev@dpdk.org
> Cc: Neil Horman <nhorman@tuxdriver.com>; Thomas Monjalon
> <thomas@monjalon.net>; Mcnamara, John <john.mcnamara@intel.com>;
> Richardson, Bruce <bruce.richardson@intel.com>
> Subject: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation
>
> Document the need to add the __experimental tag to appropriate functions
>
> Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> CC: Thomas Monjalon <thomas@monjalon.net>
> CC: "Mcnamara, John" <john.mcnamara@intel.com>
> CC: Bruce Richardson <bruce.richardson@intel.com>
> ...
> +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 definitions of those exported functions, and their
> +forward declarations (in the development header files), must be marked
> +with the __rte_experimental tag (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 during compilation in the corresponding
> library Makefile.
> +
> +In addition to tagging the code with __rte_experimental, the doxygen
> +markup must also contain the EXPERIMENTAL string, and the MAINTAINER
> +file should note that the library contains EXPERIMENTAL APIs.
> +
> ABI versions, once released, are available until such time as their
> deprecation has been noted in the Release Notes for at least one major
> release cycle. For example consider the case where the ABI for DPDK 2.0
> has been
> --
> 2.14.3
Thanks for the update, and this work in general.
The rendered docs would probably look a better better with __rte_experimental
and ALLOW_EXPERIMENTAL_API is fixed width backticks ``var`` but that is only
a "nice to have" so no need for a respin.
Acked-by: John McNamara <john.mcnamara@intel.com>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation
2018-01-23 10:35 ` Mcnamara, John
@ 2018-01-29 21:42 ` Thomas Monjalon
0 siblings, 0 replies; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-29 21:42 UTC (permalink / raw)
To: Neil Horman; +Cc: dev, Mcnamara, John, Richardson, Bruce
23/01/2018 11:35, Mcnamara, John:
>
> > -----Original Message-----
> > From: Neil Horman [mailto:nhorman@tuxdriver.com]
> > Sent: Monday, January 22, 2018 1:48 AM
> > To: dev@dpdk.org
> > Cc: Neil Horman <nhorman@tuxdriver.com>; Thomas Monjalon
> > <thomas@monjalon.net>; Mcnamara, John <john.mcnamara@intel.com>;
> > Richardson, Bruce <bruce.richardson@intel.com>
> > Subject: [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation
> >
> > Document the need to add the __experimental tag to appropriate functions
> >
> > Signed-off-by: Neil Horman <nhorman@tuxdriver.com>
> > CC: Thomas Monjalon <thomas@monjalon.net>
> > CC: "Mcnamara, John" <john.mcnamara@intel.com>
> > CC: Bruce Richardson <bruce.richardson@intel.com>
> > ...
> > +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 definitions of those exported functions, and their
> > +forward declarations (in the development header files), must be marked
> > +with the __rte_experimental tag (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 during compilation in the corresponding
> > library Makefile.
> > +
> > +In addition to tagging the code with __rte_experimental, the doxygen
> > +markup must also contain the EXPERIMENTAL string, and the MAINTAINER
> > +file should note that the library contains EXPERIMENTAL APIs.
> > +
> > ABI versions, once released, are available until such time as their
> > deprecation has been noted in the Release Notes for at least one major
> > release cycle. For example consider the case where the ABI for DPDK 2.0
> > has been
> > --
> > 2.14.3
>
> Thanks for the update, and this work in general.
>
> The rendered docs would probably look a better better with __rte_experimental
> and ALLOW_EXPERIMENTAL_API is fixed width backticks ``var`` but that is only
> a "nice to have" so no need for a respin.
Backticks added on apply.
Also changed the last sentence from
the MAINTAINER file should note that the library contains EXPERIMENTAL APIs.
to
the MAINTAINERS file should note the EXPERIMENTAL libraries.
Indeed, the practice is to note only new libraries as experimental in
the MAINTAINERS files.
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging
2018-01-22 1:48 ` [PATCH 0/5] " Neil Horman
` (4 preceding siblings ...)
2018-01-22 1:48 ` [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation Neil Horman
@ 2018-01-29 21:46 ` Thomas Monjalon
2018-01-30 15:54 ` Neil Horman
5 siblings, 1 reply; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-29 21:46 UTC (permalink / raw)
To: Neil Horman; +Cc: dev
22/01/2018 02:48, Neil Horman:
> v5 Changes
> * Clean ups suggested by Thomas
There were a lot of new functions to tag when rebasing this v5.
Rebased and applied, thanks.
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging
2018-01-29 21:46 ` [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging Thomas Monjalon
@ 2018-01-30 15:54 ` Neil Horman
2018-01-30 16:15 ` Thomas Monjalon
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-30 15:54 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: dev
On Mon, Jan 29, 2018 at 10:46:27PM +0100, Thomas Monjalon wrote:
> 22/01/2018 02:48, Neil Horman:
> > v5 Changes
> > * Clean ups suggested by Thomas
>
> There were a lot of new functions to tag when rebasing this v5.
> Rebased and applied, thanks.
>
Sorry, not clear what you mean by this. Are you saying that there were several
new experimental API's added recently that my initial set of tags missed? If
so, thanks for doing that. I will also be sending another patch set soon, to
reconcile API's that are documented as experimental but not listed in the
version map as such
Neil
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging
2018-01-30 15:54 ` Neil Horman
@ 2018-01-30 16:15 ` Thomas Monjalon
2018-01-31 12:18 ` Neil Horman
0 siblings, 1 reply; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-30 16:15 UTC (permalink / raw)
To: Neil Horman; +Cc: dev
30/01/2018 16:54, Neil Horman:
> On Mon, Jan 29, 2018 at 10:46:27PM +0100, Thomas Monjalon wrote:
> > 22/01/2018 02:48, Neil Horman:
> > > v5 Changes
> > > * Clean ups suggested by Thomas
> >
> > There were a lot of new functions to tag when rebasing this v5.
> > Rebased and applied, thanks.
> >
> Sorry, not clear what you mean by this. Are you saying that there were several
> new experimental API's added recently that my initial set of tags missed? If
> so, thanks for doing that. I will also be sending another patch set soon, to
> reconcile API's that are documented as experimental but not listed in the
> version map as such
I meant that I have applied a lot of new experimental functions
after you sent the v5.
So I had to add the tag and CFLAGS for these new functions.
Usual rebase work.
About reconciling experimental functions and map,
we should also consider upgrading some functions to non-experimental.
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging
2018-01-30 16:15 ` Thomas Monjalon
@ 2018-01-31 12:18 ` Neil Horman
2018-01-31 12:36 ` Thomas Monjalon
0 siblings, 1 reply; 83+ messages in thread
From: Neil Horman @ 2018-01-31 12:18 UTC (permalink / raw)
To: Thomas Monjalon; +Cc: dev
On Tue, Jan 30, 2018 at 05:15:01PM +0100, Thomas Monjalon wrote:
> 30/01/2018 16:54, Neil Horman:
> > On Mon, Jan 29, 2018 at 10:46:27PM +0100, Thomas Monjalon wrote:
> > > 22/01/2018 02:48, Neil Horman:
> > > > v5 Changes
> > > > * Clean ups suggested by Thomas
> > >
> > > There were a lot of new functions to tag when rebasing this v5.
> > > Rebased and applied, thanks.
> > >
> > Sorry, not clear what you mean by this. Are you saying that there were several
> > new experimental API's added recently that my initial set of tags missed? If
> > so, thanks for doing that. I will also be sending another patch set soon, to
> > reconcile API's that are documented as experimental but not listed in the
> > version map as such
>
> I meant that I have applied a lot of new experimental functions
> after you sent the v5.
> So I had to add the tag and CFLAGS for these new functions.
> Usual rebase work.
>
Understood, thank you.
> About reconciling experimental functions and map,
> we should also consider upgrading some functions to non-experimental.
>
I figured if I were to just do a reconcilliation of everything that is currently
documented as experimental, that would be the impetus for their authors to yell
at me about their not actually being experimental anymore, and I could fix that
up in subsequent versions :)
Neil
>
>
^ permalink raw reply [flat|nested] 83+ messages in thread
* Re: [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging
2018-01-31 12:18 ` Neil Horman
@ 2018-01-31 12:36 ` Thomas Monjalon
0 siblings, 0 replies; 83+ messages in thread
From: Thomas Monjalon @ 2018-01-31 12:36 UTC (permalink / raw)
To: Neil Horman; +Cc: dev
31/01/2018 13:18, Neil Horman:
> On Tue, Jan 30, 2018 at 05:15:01PM +0100, Thomas Monjalon wrote:
> > 30/01/2018 16:54, Neil Horman:
> > > On Mon, Jan 29, 2018 at 10:46:27PM +0100, Thomas Monjalon wrote:
> > > > 22/01/2018 02:48, Neil Horman:
> > > > > v5 Changes
> > > > > * Clean ups suggested by Thomas
> > > >
> > > > There were a lot of new functions to tag when rebasing this v5.
> > > > Rebased and applied, thanks.
> > > >
> > > Sorry, not clear what you mean by this. Are you saying that there were several
> > > new experimental API's added recently that my initial set of tags missed? If
> > > so, thanks for doing that. I will also be sending another patch set soon, to
> > > reconcile API's that are documented as experimental but not listed in the
> > > version map as such
> >
> > I meant that I have applied a lot of new experimental functions
> > after you sent the v5.
> > So I had to add the tag and CFLAGS for these new functions.
> > Usual rebase work.
> >
> Understood, thank you.
>
> > About reconciling experimental functions and map,
> > we should also consider upgrading some functions to non-experimental.
> >
> I figured if I were to just do a reconcilliation of everything that is currently
> documented as experimental, that would be the impetus for their authors to yell
> at me about their not actually being experimental anymore, and I could fix that
> up in subsequent versions :)
OK, sounds like a plan.
^ permalink raw reply [flat|nested] 83+ messages in thread
end of thread, other threads:[~2018-01-31 12:37 UTC | newest]
Thread overview: 83+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-12-01 18:56 [PATCH 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-01 18:56 ` [PATCH 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-01 18:56 ` [PATCH 2/4] compat: Add __experimental macro Neil Horman
2017-12-01 18:56 ` [PATCH 3/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
2017-12-01 18:56 ` [PATCH 4/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-08 17:14 ` [PATCHv2 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-08 17:14 ` [PATCHv2 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-08 17:14 ` [PATCHv2 2/4] compat: Add __experimental macro Neil Horman
2017-12-08 17:14 ` [PATCHv2 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-11 11:35 ` Bruce Richardson
2017-12-11 12:40 ` Neil Horman
2017-12-11 12:45 ` Bruce Richardson
2017-12-11 18:44 ` Neil Horman
2017-12-08 17:14 ` [PATCHv2 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
2017-12-11 19:36 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Neil Horman
2017-12-11 19:36 ` [PATCHv3 1/4] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2017-12-11 19:36 ` [PATCHv3 2/4] compat: Add __experimental macro Neil Horman
2017-12-11 19:36 ` [PATCHv3 3/4] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2017-12-11 19:36 ` [PATCHv3 4/4] dpdk: add __experimental tag to appropriate api calls Neil Horman
2017-12-12 14:07 ` [PATCHv3 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
2017-12-30 17:15 ` Neil Horman
2018-01-04 12:56 ` Neil Horman
2018-01-05 14:08 ` Thomas Monjalon
2018-01-05 16:00 ` Neil Horman
2018-01-09 1:32 ` [dpdk-ci] " Neil Horman
2018-01-09 9:20 ` Thomas Monjalon
2018-01-09 12:36 ` Neil Horman
2018-01-19 15:44 ` Neil Horman
2017-12-12 14:33 ` Mcnamara, John
2017-12-12 20:18 ` Neil Horman
2017-12-12 15:11 ` Wiles, Keith
2017-12-12 20:14 ` Neil Horman
2017-12-13 15:17 ` [PATCHv4 " Neil Horman
2017-12-13 15:17 ` [PATCHv4 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2018-01-21 18:31 ` Thomas Monjalon
2018-01-21 22:07 ` Neil Horman
2017-12-13 15:17 ` [PATCHv4 2/5] compat: Add __experimental macro Neil Horman
2018-01-21 18:37 ` Thomas Monjalon
2017-12-13 15:17 ` [PATCHv4 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 20:50 ` Neil Horman
2018-01-12 11:49 ` Ferruh Yigit
2018-01-12 12:44 ` Neil Horman
2018-01-21 18:54 ` Thomas Monjalon
2018-01-22 1:34 ` Neil Horman
2018-01-22 1:37 ` Thomas Monjalon
2018-01-21 18:50 ` Thomas Monjalon
2018-01-22 1:19 ` Neil Horman
2017-12-13 15:17 ` [PATCHv4 4/5] dpdk: add __experimental tag to appropriate api calls Neil Horman
2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 21:24 ` Neil Horman
2018-01-12 11:50 ` Ferruh Yigit
2018-01-12 14:25 ` Neil Horman
2018-01-12 15:53 ` Ferruh Yigit
2017-12-13 15:17 ` [PATCHv4 5/5] doc: Add ABI __experimental tag documentation Neil Horman
2017-12-13 15:32 ` Bruce Richardson
2018-01-11 20:06 ` Ferruh Yigit
2018-01-11 21:29 ` Neil Horman
2018-01-12 11:50 ` Ferruh Yigit
2018-01-12 14:37 ` Neil Horman
2018-01-12 15:55 ` Ferruh Yigit
2018-01-13 0:28 ` Neil Horman
2018-01-13 15:56 ` Thomas Monjalon
2018-01-14 14:36 ` Neil Horman
2018-01-14 16:27 ` Thomas Monjalon
2018-01-21 20:14 ` Thomas Monjalon
2017-12-13 15:32 ` [PATCHv4 0/4] dpdk: enhance EXPERIMENTAL api tagging Bruce Richardson
2017-12-21 14:21 ` Neil Horman
2017-12-30 19:20 ` Luca Boccassi
2017-12-31 1:57 ` Neil Horman
2018-01-22 1:48 ` [PATCH 0/5] " Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 1/5] buildtools: Add tool to check EXPERIMENTAL api exports Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 2/5] compat: Add __rte_experimental macro Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 3/5] Makefiles: Add experimental tag check and warnings to trigger on use Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 4/5] dpdk: add __rte_experimental tag to appropriate api calls Neil Horman
2018-01-22 1:48 ` [[PATCH v5] 5/5] doc: Add ABI __experimental tag documentation Neil Horman
2018-01-23 10:35 ` Mcnamara, John
2018-01-29 21:42 ` Thomas Monjalon
2018-01-29 21:46 ` [PATCH 0/5] dpdk: enhance EXPERIMENTAL api tagging Thomas Monjalon
2018-01-30 15:54 ` Neil Horman
2018-01-30 16:15 ` Thomas Monjalon
2018-01-31 12:18 ` Neil Horman
2018-01-31 12:36 ` Thomas Monjalon
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.