DPDK patches and discussions
 help / color / mirror / Atom feed
* [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis
@ 2020-02-05 15:17 Ray Kinsella
  2020-02-05 15:43 ` [dpdk-dev] [PATCH v3] " Ray Kinsella
                   ` (3 more replies)
  0 siblings, 4 replies; 9+ messages in thread
From: Ray Kinsella @ 2020-02-05 15:17 UTC (permalink / raw)
  To: dev; +Cc: john.mcnamara, nhorman, ferruh.yigit, marko.kovacevic, Ray Kinsella

When a maintainer is promoting an API to become part of the next major ABI
version by removing the experimental tag, possibly a few releases in advance of
the declaration of the next ABI version. The maintainer may choose to offer an
alias to the experimental tag, as removing the tag before the declaration of the
next major ABI version, would cause an ABI breakage for applications using the
API.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
 doc/guides/contributing/abi_policy.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 05ca959..9a4a102 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -159,6 +159,11 @@ The requirements for changing the ABI are:
      ``experimental``, as described in the section on :ref:`Experimental APIs
      and Libraries <experimental_apis>`.
 
+   - In situations where an ``experimental`` API has been stable for some time.
+     When promoting the API to become part of the next ABI version, the
+     maintainer may choose to provide an alias to the ``experimental`` tag, so
+     as not to break consuming applications.
+
 #. If a newly proposed API functionally replaces an existing one, when the new
    API becomes non-experimental, then the old one is marked with
    ``__rte_deprecated``.
@@ -317,6 +322,11 @@ not required. Though, an API should remain in experimental state for at least
 one release. Thereafter, the normal process of posting patch for review to
 mailing list can be followed.
 
+After the experimental tag has been formally removed, a tree/sub-tree maintainer
+may choose to offer an alias to the experimental tag so as not to break
+applications using the API. This alias can then be dropped at the declaration of
+next major ABI version.
+
 Libraries
 ~~~~~~~~~
 
-- 
2.7.4


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [dpdk-dev] [PATCH v3] doc: alias to experimental tag for stable apis
  2020-02-05 15:17 [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis Ray Kinsella
@ 2020-02-05 15:43 ` Ray Kinsella
  2020-02-18 10:46 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
                   ` (2 subsequent siblings)
  3 siblings, 0 replies; 9+ messages in thread
From: Ray Kinsella @ 2020-02-05 15:43 UTC (permalink / raw)
  To: dev; +Cc: john.mcnamara, nhorman, ferruh.yigit, marko.kovacevic, Ray Kinsella

When a maintainer is promoting an API to become part of the next major ABI
version by removing the experimental tag, possibly a few releases in
advance of the declaration of the next ABI version. The maintainer may
choose to offer an alias to the experimental tag, as removing the tag
before the declaration of the next major ABI version, would cause an ABI
breakage for applications using the API.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
 doc/guides/contributing/abi_policy.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 05ca959..9a4a102 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -159,6 +159,11 @@ The requirements for changing the ABI are:
      ``experimental``, as described in the section on :ref:`Experimental APIs
      and Libraries <experimental_apis>`.
 
+   - In situations where an ``experimental`` API has been stable for some time.
+     When promoting the API to become part of the next ABI version, the
+     maintainer may choose to provide an alias to the ``experimental`` tag, so
+     as not to break consuming applications.
+
 #. If a newly proposed API functionally replaces an existing one, when the new
    API becomes non-experimental, then the old one is marked with
    ``__rte_deprecated``.
@@ -317,6 +322,11 @@ not required. Though, an API should remain in experimental state for at least
 one release. Thereafter, the normal process of posting patch for review to
 mailing list can be followed.
 
+After the experimental tag has been formally removed, a tree/sub-tree maintainer
+may choose to offer an alias to the experimental tag so as not to break
+applications using the API. This alias can then be dropped at the declaration of
+next major ABI version.
+
 Libraries
 ~~~~~~~~~
 
-- 
2.7.4


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [dpdk-dev] [PATCH v4] doc: alias to experimental tag for stable apis
  2020-02-05 15:17 [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis Ray Kinsella
  2020-02-05 15:43 ` [dpdk-dev] [PATCH v3] " Ray Kinsella
@ 2020-02-18 10:46 ` Ray Kinsella
  2020-02-21 17:11   ` Ferruh Yigit
  2020-02-25 14:22   ` Kevin Traynor
  2020-02-25 15:35 ` [dpdk-dev] [PATCH] " Neil Horman
  2020-05-14 13:38 ` [dpdk-dev] [PATCH v5] " Ray Kinsella
  3 siblings, 2 replies; 9+ messages in thread
From: Ray Kinsella @ 2020-02-18 10:46 UTC (permalink / raw)
  To: dev
  Cc: john.mcnamara, nhorman, ferruh.yigit, marko.kovacevic,
	bruce.richardson, Ray Kinsella

When a maintainer is promoting an API to become part of the next major ABI
version by removing the experimental tag, possibly a few releases in
advance of the declaration of the next ABI version. The maintainer may
choose to offer an alias to the experimental tag, as removing the tag
before the declaration of the next major ABI version, would cause an ABI
breakage for applications using the API.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
---
 doc/guides/contributing/abi_policy.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 05ca959..7ae7de7 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -159,6 +159,11 @@ The requirements for changing the ABI are:
      ``experimental``, as described in the section on :ref:`Experimental APIs
      and Libraries <experimental_apis>`.
 
+   - In situations in which an ``experimental`` API has been stable for some
+     time. When promoting the API to become part of the next ABI version, the
+     maintainer may choose to provide an alias to the ``experimental`` tag, so
+     as not to break consuming applications.
+
 #. If a newly proposed API functionally replaces an existing one, when the new
    API becomes non-experimental, then the old one is marked with
    ``__rte_deprecated``.
@@ -317,6 +322,11 @@ not required. Though, an API should remain in experimental state for at least
 one release. Thereafter, the normal process of posting patch for review to
 mailing list can be followed.
 
+After the experimental tag has been formally removed, a tree/sub-tree maintainer
+may choose to offer an alias to the experimental tag so as not to break
+applications using the API. The alias is then dropped at the declaration of next
+major ABI version.
+
 Libraries
 ~~~~~~~~~
 
-- 
2.7.4


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH v4] doc: alias to experimental tag for stable apis
  2020-02-18 10:46 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
@ 2020-02-21 17:11   ` Ferruh Yigit
  2020-02-25 14:22   ` Kevin Traynor
  1 sibling, 0 replies; 9+ messages in thread
From: Ferruh Yigit @ 2020-02-21 17:11 UTC (permalink / raw)
  To: Ray Kinsella, dev
  Cc: john.mcnamara, nhorman, marko.kovacevic, bruce.richardson

On 2/18/2020 10:46 AM, Ray Kinsella wrote:
> When a maintainer is promoting an API to become part of the next major ABI
> version by removing the experimental tag, possibly a few releases in
> advance of the declaration of the next ABI version. The maintainer may
> choose to offer an alias to the experimental tag, as removing the tag
> before the declaration of the next major ABI version, would cause an ABI
> breakage for applications using the API.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
>  doc/guides/contributing/abi_policy.rst | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index 05ca959..7ae7de7 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -159,6 +159,11 @@ The requirements for changing the ABI are:
>       ``experimental``, as described in the section on :ref:`Experimental APIs
>       and Libraries <experimental_apis>`.
>  
> +   - In situations in which an ``experimental`` API has been stable for some
> +     time. When promoting the API to become part of the next ABI version, the
> +     maintainer may choose to provide an alias to the ``experimental`` tag, so
> +     as not to break consuming applications.
> +
>  #. If a newly proposed API functionally replaces an existing one, when the new
>     API becomes non-experimental, then the old one is marked with
>     ``__rte_deprecated``.
> @@ -317,6 +322,11 @@ not required. Though, an API should remain in experimental state for at least
>  one release. Thereafter, the normal process of posting patch for review to
>  mailing list can be followed.
>  
> +After the experimental tag has been formally removed, a tree/sub-tree maintainer
> +may choose to offer an alias to the experimental tag so as not to break
> +applications using the API. The alias is then dropped at the declaration of next
> +major ABI version.
> +
>  Libraries
>  ~~~~~~~~~
>  
> 

This leaves the decision to author/maintainer, I am more for making this a
requirement, but at least this enables it and better than nothing ;)

Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH v4] doc: alias to experimental tag for stable apis
  2020-02-18 10:46 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
  2020-02-21 17:11   ` Ferruh Yigit
@ 2020-02-25 14:22   ` Kevin Traynor
  1 sibling, 0 replies; 9+ messages in thread
From: Kevin Traynor @ 2020-02-25 14:22 UTC (permalink / raw)
  To: Ray Kinsella, dev
  Cc: john.mcnamara, nhorman, ferruh.yigit, marko.kovacevic, bruce.richardson

On 18/02/2020 10:46, Ray Kinsella wrote:
> When a maintainer is promoting an API to become part of the next major ABI
> version by removing the experimental tag, possibly a few releases in
> advance of the declaration of the next ABI version. The maintainer may
> choose to offer an alias to the experimental tag, as removing the tag
> before the declaration of the next major ABI version, would cause an ABI
> breakage for applications using the API.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
>  doc/guides/contributing/abi_policy.rst | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index 05ca959..7ae7de7 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -159,6 +159,11 @@ The requirements for changing the ABI are:
>       ``experimental``, as described in the section on :ref:`Experimental APIs
>       and Libraries <experimental_apis>`.
>  
> +   - In situations in which an ``experimental`` API has been stable for some
> +     time. When promoting the API to become part of the next ABI version, the
> +     maintainer may choose to provide an alias to the ``experimental`` tag, so
> +     as not to break consuming applications.
> +
>  #. If a newly proposed API functionally replaces an existing one, when the new
>     API becomes non-experimental, then the old one is marked with
>     ``__rte_deprecated``.
> @@ -317,6 +322,11 @@ not required. Though, an API should remain in experimental state for at least
>  one release. Thereafter, the normal process of posting patch for review to
>  mailing list can be followed.
>  
> +After the experimental tag has been formally removed, a tree/sub-tree maintainer
> +may choose to offer an alias to the experimental tag so as not to break
> +applications using the API. The alias is then dropped at the declaration of next
> +major ABI version.
> +
>  Libraries
>  ~~~~~~~~~
>  
> 

Sounds good. It doesn't change the minimum contract but gives some
flexibility to deal with individual cases.

Acked-by: Kevin Traynor <ktraynor@redhat.com>


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis
  2020-02-05 15:17 [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis Ray Kinsella
  2020-02-05 15:43 ` [dpdk-dev] [PATCH v3] " Ray Kinsella
  2020-02-18 10:46 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
@ 2020-02-25 15:35 ` Neil Horman
  2020-02-25 17:57   ` David Marchand
  2020-05-14 13:38 ` [dpdk-dev] [PATCH v5] " Ray Kinsella
  3 siblings, 1 reply; 9+ messages in thread
From: Neil Horman @ 2020-02-25 15:35 UTC (permalink / raw)
  To: Ray Kinsella; +Cc: dev, john.mcnamara, ferruh.yigit, marko.kovacevic

On Wed, Feb 05, 2020 at 03:17:52PM +0000, Ray Kinsella wrote:
> When a maintainer is promoting an API to become part of the next major ABI
> version by removing the experimental tag, possibly a few releases in advance of
> the declaration of the next ABI version. The maintainer may choose to offer an
> alias to the experimental tag, as removing the tag before the declaration of the
> next major ABI version, would cause an ABI breakage for applications using the
> API.
> 
> Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> ---
>  doc/guides/contributing/abi_policy.rst | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> index 05ca959..9a4a102 100644
> --- a/doc/guides/contributing/abi_policy.rst
> +++ b/doc/guides/contributing/abi_policy.rst
> @@ -159,6 +159,11 @@ The requirements for changing the ABI are:
>       ``experimental``, as described in the section on :ref:`Experimental APIs
>       and Libraries <experimental_apis>`.
>  
> +   - In situations where an ``experimental`` API has been stable for some time.
> +     When promoting the API to become part of the next ABI version, the
> +     maintainer may choose to provide an alias to the ``experimental`` tag, so
> +     as not to break consuming applications.
> +
I don't have any issue with the approach, but just to ask the question, is it
worth providing an example here, of how exactly to do this?  The use of
VERSION_SYMBOL isn't often used, and so may be non-obvious.

Actually, as I look at it, the VERSION_SYMBOL macro assume a DPDK_ prefix on the
version string, which works for versioned symbols, but not for the EXPERIMENTAL
symbol version (no DPDK_ prefix).  We should probably create a variant of the
VERSION_SYMBOL macro to allow aliasing to the EXPERIMENTAL version, something
like ALIAS_TO_EXPERIMENTAL() or some such

Neil

>  #. If a newly proposed API functionally replaces an existing one, when the new
>     API becomes non-experimental, then the old one is marked with
>     ``__rte_deprecated``.
> @@ -317,6 +322,11 @@ not required. Though, an API should remain in experimental state for at least
>  one release. Thereafter, the normal process of posting patch for review to
>  mailing list can be followed.
>  
> +After the experimental tag has been formally removed, a tree/sub-tree maintainer
> +may choose to offer an alias to the experimental tag so as not to break
> +applications using the API. This alias can then be dropped at the declaration of
> +next major ABI version.
> +
>  Libraries
>  ~~~~~~~~~
>  
> -- 
> 2.7.4
> 
> 

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis
  2020-02-25 15:35 ` [dpdk-dev] [PATCH] " Neil Horman
@ 2020-02-25 17:57   ` David Marchand
  0 siblings, 0 replies; 9+ messages in thread
From: David Marchand @ 2020-02-25 17:57 UTC (permalink / raw)
  To: Ray Kinsella, Neil Horman
  Cc: dev, Mcnamara, John, Yigit, Ferruh, Kovacevic, Marko

On Tue, Feb 25, 2020 at 4:36 PM Neil Horman <nhorman@tuxdriver.com> wrote:
>
> On Wed, Feb 05, 2020 at 03:17:52PM +0000, Ray Kinsella wrote:
> > When a maintainer is promoting an API to become part of the next major ABI
> > version by removing the experimental tag, possibly a few releases in advance of
> > the declaration of the next ABI version. The maintainer may choose to offer an
> > alias to the experimental tag, as removing the tag before the declaration of the
> > next major ABI version, would cause an ABI breakage for applications using the
> > API.
> >
> > Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
> > ---
> >  doc/guides/contributing/abi_policy.rst | 10 ++++++++++
> >  1 file changed, 10 insertions(+)
> >
> > diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
> > index 05ca959..9a4a102 100644
> > --- a/doc/guides/contributing/abi_policy.rst
> > +++ b/doc/guides/contributing/abi_policy.rst
> > @@ -159,6 +159,11 @@ The requirements for changing the ABI are:
> >       ``experimental``, as described in the section on :ref:`Experimental APIs
> >       and Libraries <experimental_apis>`.
> >
> > +   - In situations where an ``experimental`` API has been stable for some time.
> > +     When promoting the API to become part of the next ABI version, the
> > +     maintainer may choose to provide an alias to the ``experimental`` tag, so
> > +     as not to break consuming applications.
> > +
> I don't have any issue with the approach, but just to ask the question, is it
> worth providing an example here, of how exactly to do this?  The use of
> VERSION_SYMBOL isn't often used, and so may be non-obvious.
>
> Actually, as I look at it, the VERSION_SYMBOL macro assume a DPDK_ prefix on the
> version string, which works for versioned symbols, but not for the EXPERIMENTAL
> symbol version (no DPDK_ prefix).  We should probably create a variant of the
> VERSION_SYMBOL macro to allow aliasing to the EXPERIMENTAL version, something
> like ALIAS_TO_EXPERIMENTAL() or some such

Let's clarify this part so this can be merged in early 20.05.
Thanks.


-- 
David Marchand


^ permalink raw reply	[flat|nested] 9+ messages in thread

* [dpdk-dev] [PATCH v5] doc: alias to experimental tag for stable apis
  2020-02-05 15:17 [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis Ray Kinsella
                   ` (2 preceding siblings ...)
  2020-02-25 15:35 ` [dpdk-dev] [PATCH] " Neil Horman
@ 2020-05-14 13:38 ` Ray Kinsella
  2020-05-14 16:31   ` David Marchand
  3 siblings, 1 reply; 9+ messages in thread
From: Ray Kinsella @ 2020-05-14 13:38 UTC (permalink / raw)
  To: dev
  Cc: Ray Kinsella, Ferruh Yigit, Kevin Traynor, David Marchand,
	Neil Horman, John McNamara, Marko Kovacevic

When a maintainer is promoting an API to become part of the next major ABI
version by removing the experimental tag, possibly a few releases in
advance of the declaration of the next ABI version. The maintainer may
choose to offer an alias to the experimental tag, as removing the tag
before the declaration of the next major ABI version, would cause an ABI
breakage for applications using the API.

Signed-off-by: Ray Kinsella <mdr@ashroe.eu>
Acked-by: Ferruh Yigit <ferruh.yigit@intel.com>
Acked-by: Kevin Traynor <ktraynor@redhat.com>
---
This patch depends on "doc: fix references to bind_default_symbol".
https://patches.dpdk.org/patch/69850/

v5:
 * Added section on aliasing to experimental. requested by
   Neil Horman <nhorman@tuxdriver.com>

CC: Ferruh Yigit <ferruh.yigit@intel.com>
CC: Kevin Traynor <ktraynor@redhat.com>
CC: David Marchand <david.marchand@redhat.com>

 doc/guides/contributing/abi_policy.rst     |  10 ++
 doc/guides/contributing/abi_versioning.rst | 158 ++++++++++++++++++++++++++++-
 2 files changed, 167 insertions(+), 1 deletion(-)

diff --git a/doc/guides/contributing/abi_policy.rst b/doc/guides/contributing/abi_policy.rst
index 86e7dd9..c33bff1 100644
--- a/doc/guides/contributing/abi_policy.rst
+++ b/doc/guides/contributing/abi_policy.rst
@@ -160,6 +160,11 @@ The requirements for changing the ABI are:
      ``experimental``, as described in the section on :ref:`Experimental APIs
      and Libraries <experimental_apis>`.

+   - In situations in which an ``experimental`` symbol has been stable for some
+     time. When promoting the symbol to become part of the next ABI version, the
+     maintainer may choose to provide an alias to the ``experimental`` tag, so
+     as not to break consuming applications.
+
 #. If a newly proposed API functionally replaces an existing one, when the new
    API becomes non-experimental, then the old one is marked with
    ``__rte_deprecated``.
@@ -318,6 +323,11 @@ not required. Though, an API should remain in experimental state for at least
 one release. Thereafter, the normal process of posting patch for review to
 mailing list can be followed.

+After the experimental tag has been formally removed, a tree/sub-tree maintainer
+may choose to offer an alias to the experimental tag so as not to break
+applications using the symbol. The alias is then dropped at the declaration of
+next major ABI version.
+
 Libraries
 ~~~~~~~~~

diff --git a/doc/guides/contributing/abi_versioning.rst b/doc/guides/contributing/abi_versioning.rst
index 7065979..4832e8f 100644
--- a/doc/guides/contributing/abi_versioning.rst
+++ b/doc/guides/contributing/abi_versioning.rst
@@ -156,6 +156,11 @@ The macros exported are:
   ``be`` to signal that it is being used as an implementation of a particular
   version of symbol ``b``.

+* ``VERSION_SYMBOL_EXPERIMENTAL(b, e)``: Creates a symbol version table entry
+  binding versioned symbol ``b@EXPERIMENTAL`` to the internal function ``be``.
+  The macro is used when a symbol matures to become part of the stable ABI, to
+  provide an alias to experimental for some time.
+
 .. _example_abi_macro_usage:

 Examples of ABI Macro use
@@ -361,7 +366,7 @@ and a new DPDK_21 version, used by future built applications.
 .. note::

    **Before you leave**, please take care to the review the sections on
-   :ref:`Mapping static symbols <mapping_static_symbols>`, :ref:`Enabling
+   :ref:`mapping static symbols <mapping_static_symbols>`, :ref:`enabling
    versioning macros <enabling_versioning_macros>` and :ref:`ABI deprecation
    <abi_decprecation>`.

@@ -415,6 +420,157 @@ at the start of the head of the file. This will indicate to the tool-chain to
 enable the function version macros when building. There is no corresponding
 directive required for the ``make`` build system.

+.. _aliasing_experimental_symbols:
+
+Aliasing experimental symbols
+_____________________________
+
+In situations in which an ``experimental`` symbol has been stable for some time,
+and it becomes a candidate for promotion to the stable ABI. At this time, when
+promoting the symbol, maintainer may choose to provide an alias to the
+``experimental`` symbol version, so as not to break consuming applications.
+
+The process to provide an alias to ``experimental`` is similar to that, of
+:ref:`symbol visioning <example_abi_macro_usage>` described above. Assume we
+have an experimental function ``rte_acl_create`` as follows
+
+.. code-block:: c
+
+ #include <rte_compat.h>;
+
+ /*
+  * Create an acl context object for apps to
+  * manipulate
+  */
+ __rte_experimental
+ struct rte_acl_ctx *
+ rte_acl_create(const struct rte_acl_param *param)
+ {
+ ...
+ }
+
+In the map file, experimental symbols are listed as part of the ``experimental``
+version node.
+
+.. code-block:: none
+
+   DPDK_20 {
+        global:
+        ...
+
+        local: *;
+   };
+
+   EXPERIMENTAL {
+        global:
+
+        rte_acl_create
+   };
+
+When we promote the symbol to the stable ABI, we simply strip the
+``rte_experimental`` annotation from the function and move the symbol from the
+``experimental`` node, to the node of the next major ABI version as follow.
+
+.. code-block:: c
+
+ /*
+  * Create an acl context object for apps to
+  * manipulate
+  */
+ struct rte_acl_ctx *
+ rte_acl_create(const struct rte_acl_param *param)
+ {
+        ...
+ }
+
+We then update the map file, adding the symbol ``rte_acl_create`` to the ``v21``
+version node.
+
+.. code-block:: none
+
+   DPDK_20 {
+        global:
+        ...
+
+        local: *;
+   };
+
+   DPDK_21 {
+        global:
+
+        rte_acl_create
+   } DPDK_20;
+
+
+Although there are strictly no guarantees or commitments associated with
+:ref:`experimental symbols <experimental_apis>`, a maintainer may wish to offer
+an alias to experimental. The process to add an alias to experimental, is
+similar to the symbol versioning process. Assuming we have an experimental
+symbol as before, we now add the symbol to both the ``experimental`` and ``v21``
+version nodes.
+
+.. code-block:: c
+
+ #include <rte_compat.h>;
+ #include <rte_function_versioning.h>;
+
+ /*
+  * Create an acl context object for apps to
+  * manipulate
+  */
+ struct rte_acl_ctx *
+ rte_acl_create(const struct rte_acl_param *param)
+ {
+ ...
+ }
+
+ __rte_experimental
+ struct rte_acl_ctx *
+ rte_acl_create_e(const struct rte_acl_param *param)
+ {
+    return rte_acl_create(param);
+ }
+ VERSION_SYMBOL_EXPERIMENTAL(rte_acl_create, _e);
+
+ struct rte_acl_ctx *
+ rte_acl_create_v21(const struct rte_acl_param *param)
+ {
+    return rte_acl_create(param);
+ }
+ BIND_DEFAULT_SYMBOL(rte_acl_create, _v21, 21);
+
+
+In the map file, we map the symbol to both the experimental and ``v21`` version
+nodes.
+
+.. code-block:: none
+
+   DPDK_20 {
+        global:
+        ...
+
+        local: *;
+   };
+
+   DPDK_21 {
+        global:
+
+        rte_acl_create
+   } DPDK_20;
+
+   EXPERIMENTAL {
+        global:
+
+        rte_acl_create
+   };
+
+.. note::
+
+   Please note, similar to :ref:`symbol visioning <example_abi_macro_usage>`
+   when aliasing to experimental you will also need to take care of
+   :ref:`mapping static symbols <mapping_static_symbols>`.
+
+
 .. _abi_decprecation:

 Deprecating part of a public API
--
2.7.4

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [dpdk-dev] [PATCH v5] doc: alias to experimental tag for stable apis
  2020-05-14 13:38 ` [dpdk-dev] [PATCH v5] " Ray Kinsella
@ 2020-05-14 16:31   ` David Marchand
  0 siblings, 0 replies; 9+ messages in thread
From: David Marchand @ 2020-05-14 16:31 UTC (permalink / raw)
  To: Ray Kinsella
  Cc: dev, Ferruh Yigit, Kevin Traynor, Neil Horman, John McNamara,
	Marko Kovacevic

On Thu, May 14, 2020 at 3:39 PM Ray Kinsella <mdr@ashroe.eu> wrote:
> +In the map file, experimental symbols are listed as part of the ``experimental``
> +version node.
> +
> +.. code-block:: none
> +
> +   DPDK_20 {
> +        global:
> +        ...
> +
> +        local: *;
> +   };
> +
> +   EXPERIMENTAL {
> +        global:
> +
> +        rte_acl_create

Missing ; and idem for the rest of the patch.


-- 
David Marchand


^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2020-05-14 16:32 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-02-05 15:17 [dpdk-dev] [PATCH] doc: alias to experimental tag for stable apis Ray Kinsella
2020-02-05 15:43 ` [dpdk-dev] [PATCH v3] " Ray Kinsella
2020-02-18 10:46 ` [dpdk-dev] [PATCH v4] " Ray Kinsella
2020-02-21 17:11   ` Ferruh Yigit
2020-02-25 14:22   ` Kevin Traynor
2020-02-25 15:35 ` [dpdk-dev] [PATCH] " Neil Horman
2020-02-25 17:57   ` David Marchand
2020-05-14 13:38 ` [dpdk-dev] [PATCH v5] " Ray Kinsella
2020-05-14 16:31   ` David Marchand

DPDK patches and discussions

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ https://inbox.dpdk.org/dev \
		dev@dpdk.org
	public-inbox-index dev

Example config snippet for mirrors.
Newsgroup available over NNTP:
	nntp://inbox.dpdk.org/inbox.dpdk.dev


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git