[PATCH] eal: fix lcore variables documentation

[PATCH] eal: fix lcore variables documentation

[Thomas Monjalon]

The lcore variables API is new in DPDK 24.11,
that's why the function rte_lcore_var_alloc() was marked experimental.
To be clearer, the whole header file (including all macros)
is marked experimental.

A change decreased the default buffer size from 1 MB to 128 kB,
missing to update the documentation, which is fixed here.

Fixes: 5bce9bed67ad ("eal: add static per-lcore memory allocation facility")
Fixes: f2fd6c2e080c ("config: limit lcore variable maximum size to 128k")

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
---
 doc/guides/prog_guide/lcore_var.rst | 2 +-
 lib/eal/include/rte_lcore_var.h     | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/guides/prog_guide/lcore_var.rst b/doc/guides/prog_guide/lcore_var.rst
index b492ad12c6..3d9384bc33 100644
--- a/doc/guides/prog_guide/lcore_var.rst
+++ b/doc/guides/prog_guide/lcore_var.rst
@@ -240,7 +240,7 @@ and huge pages for lcore variables:
   and their use would result in a significant amount of memory going to waste.
   An example: ~256 kB worth of lcore variables are allocated
   by DPDK libraries, PMDs and the application.
-  ``RTE_MAX_LCORE_VAR`` is set to 1 MB and ``RTE_MAX_LCORE`` to 128.
+  ``RTE_MAX_LCORE_VAR`` is set to 128 kB and ``RTE_MAX_LCORE`` to 128.
   With 4 kB OS pages, only the first ~64 pages of each of the 128 per-lcore id slices
   in the (only) ``lcore_var_buffer`` will actually be resident (paged in).
   Here, demand paging saves ~98 MB of memory.
diff --git a/lib/eal/include/rte_lcore_var.h b/lib/eal/include/rte_lcore_var.h
index 28d88cd89b..0216a67cab 100644
--- a/lib/eal/include/rte_lcore_var.h
+++ b/lib/eal/include/rte_lcore_var.h
@@ -15,6 +15,8 @@
  *
  * Please refer to the lcore variables' programmer's guide
  * for an overview of this API and its implementation.
+ *
+ * EXPERIMENTAL: this API may change, or be removed, without prior notice.
  */
 
 #include <stddef.h>
-- 
2.47.0

Re: [PATCH] eal: fix lcore variables documentation

[Mattias Rönnblom]

On 2024-11-14 18:09, Thomas Monjalon wrote:
> The lcore variables API is new in DPDK 24.11,
> that's why the function rte_lcore_var_alloc() was marked experimental.
> To be clearer, the whole header file (including all macros)
> is marked experimental.
> 
> A change decreased the default buffer size from 1 MB to 128 kB,
> missing to update the documentation, which is fixed here.
> 
> Fixes: 5bce9bed67ad ("eal: add static per-lcore memory allocation facility")
> Fixes: f2fd6c2e080c ("config: limit lcore variable maximum size to 128k")
> 
> Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
> ---
>   doc/guides/prog_guide/lcore_var.rst | 2 +-
>   lib/eal/include/rte_lcore_var.h     | 2 ++
>   2 files changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/guides/prog_guide/lcore_var.rst b/doc/guides/prog_guide/lcore_var.rst
> index b492ad12c6..3d9384bc33 100644
> --- a/doc/guides/prog_guide/lcore_var.rst
> +++ b/doc/guides/prog_guide/lcore_var.rst
> @@ -240,7 +240,7 @@ and huge pages for lcore variables:
>     and their use would result in a significant amount of memory going to waste.
>     An example: ~256 kB worth of lcore variables are allocated
>     by DPDK libraries, PMDs and the application.
> -  ``RTE_MAX_LCORE_VAR`` is set to 1 MB and ``RTE_MAX_LCORE`` to 128.
> +  ``RTE_MAX_LCORE_VAR`` is set to 128 kB and ``RTE_MAX_LCORE`` to 128.
>     With 4 kB OS pages, only the first ~64 pages of each of the 128 per-lcore id slices
>     in the (only) ``lcore_var_buffer`` will actually be resident (paged in).
>     Here, demand paging saves ~98 MB of memory.
> diff --git a/lib/eal/include/rte_lcore_var.h b/lib/eal/include/rte_lcore_var.h
> index 28d88cd89b..0216a67cab 100644
> --- a/lib/eal/include/rte_lcore_var.h
> +++ b/lib/eal/include/rte_lcore_var.h
> @@ -15,6 +15,8 @@
>    *
>    * Please refer to the lcore variables' programmer's guide
>    * for an overview of this API and its implementation.
> + *
> + * EXPERIMENTAL: this API may change, or be removed, without prior notice.
>    */
>   
>   #include <stddef.h>

Acked-by: Mattias Rönnblom <mattias.ronnblom@ericsson.com>

Thanks!