[PATCH net-next] Documentation: update networking/page_pool.rst with ethtool APIs

[PATCH net-next] Documentation: update networking/page_pool.rst with ethtool APIs

[Lorenzo Bianconi]

Update page_pool documentation with page_pool ethtool stats APIs.

Signed-off-by: Lorenzo Bianconi <lorenzo@kernel.org>
---
 Documentation/networking/page_pool.rst | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst
index 5db8c263b0c6..ef5e18cf7cdf 100644
--- a/Documentation/networking/page_pool.rst
+++ b/Documentation/networking/page_pool.rst
@@ -146,6 +146,29 @@ The ``struct page_pool_recycle_stats`` has the following fields:
   * ``ring_full``: page released from page pool because the ptr ring was full
   * ``released_refcnt``: page released (and not recycled) because refcnt > 1
 
+The following APIs can be used to report page_pool stats through ethtool and
+avoid code duplication in each driver:
+
+* page_pool_ethtool_stats_get_strings(): reports page_pool ethtool stats
+  strings according to the ``struct page_pool_stats``
+     * ``rx_pp_alloc_fast``
+     * ``rx_pp_alloc_slow``
+     * ``rx_pp_alloc_slow_ho``
+     * ``rx_pp_alloc_empty``
+     * ``rx_pp_alloc_refill``
+     * ``rx_pp_alloc_waive``
+     * ``rx_pp_recycle_cached``
+     * ``rx_pp_recycle_cache_full``
+     * ``rx_pp_recycle_ring``
+     * ``rx_pp_recycle_ring_full``
+     * ``rx_pp_recycle_released_ref``
+
+* page_pool_ethtool_stats_get_count(): reports the number of stats defined in
+  the ethtool page_pool APIs
+
+* page_pool_ethtool_stats_get(u64 \*data, void \*stats): reports the page_pool statistics accounted in
+  the ``stats`` pointer in the ethtool ``data`` pointer provided by the caller
+
 Coding examples
 ===============
 
-- 
2.35.3

Re: [PATCH net-next] Documentation: update networking/page_pool.rst with ethtool APIs

[Andrew Lunn]

On Mon, May 09, 2022 at 12:00:01PM +0200, Lorenzo Bianconi wrote:
> Update page_pool documentation with page_pool ethtool stats APIs.
> 
> Signed-off-by: Lorenzo Bianconi <lorenzo@kernel.org>
> ---
>  Documentation/networking/page_pool.rst | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
> 
> diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst
> index 5db8c263b0c6..ef5e18cf7cdf 100644
> --- a/Documentation/networking/page_pool.rst
> +++ b/Documentation/networking/page_pool.rst
> @@ -146,6 +146,29 @@ The ``struct page_pool_recycle_stats`` has the following fields:
>    * ``ring_full``: page released from page pool because the ptr ring was full
>    * ``released_refcnt``: page released (and not recycled) because refcnt > 1
>  
> +The following APIs can be used to report page_pool stats through ethtool and
> +avoid code duplication in each driver:
> +
> +* page_pool_ethtool_stats_get_strings(): reports page_pool ethtool stats
> +  strings according to the ``struct page_pool_stats``
> +     * ``rx_pp_alloc_fast``
> +     * ``rx_pp_alloc_slow``
> +     * ``rx_pp_alloc_slow_ho``
> +     * ``rx_pp_alloc_empty``
> +     * ``rx_pp_alloc_refill``
> +     * ``rx_pp_alloc_waive``
> +     * ``rx_pp_recycle_cached``
> +     * ``rx_pp_recycle_cache_full``
> +     * ``rx_pp_recycle_ring``
> +     * ``rx_pp_recycle_ring_full``
> +     * ``rx_pp_recycle_released_ref``

My knowledge of Sphinx is pretty poor. Is it possible to put this list
next to the actual definition and cross reference it? When new
counters are added, they are more likely to be added to the list, if
the list is nearby.

    Andrew

Re: [PATCH net-next] Documentation: update networking/page_pool.rst with ethtool APIs

[Jakub Kicinski]

On Mon, 9 May 2022 14:25:10 +0200 Andrew Lunn wrote:
> On Mon, May 09, 2022 at 12:00:01PM +0200, Lorenzo Bianconi wrote:
> > Update page_pool documentation with page_pool ethtool stats APIs.
> > 
> > Signed-off-by: Lorenzo Bianconi <lorenzo@kernel.org>
> > ---
> >  Documentation/networking/page_pool.rst | 23 +++++++++++++++++++++++
> >  1 file changed, 23 insertions(+)
> > 
> > diff --git a/Documentation/networking/page_pool.rst b/Documentation/networking/page_pool.rst
> > index 5db8c263b0c6..ef5e18cf7cdf 100644
> > --- a/Documentation/networking/page_pool.rst
> > +++ b/Documentation/networking/page_pool.rst
> > @@ -146,6 +146,29 @@ The ``struct page_pool_recycle_stats`` has the following fields:
> >    * ``ring_full``: page released from page pool because the ptr ring was full
> >    * ``released_refcnt``: page released (and not recycled) because refcnt > 1
> >  
> > +The following APIs can be used to report page_pool stats through ethtool and
> > +avoid code duplication in each driver:
> > +
> > +* page_pool_ethtool_stats_get_strings(): reports page_pool ethtool stats
> > +  strings according to the ``struct page_pool_stats``
> > +     * ``rx_pp_alloc_fast``
> > +     * ``rx_pp_alloc_slow``
> > +     * ``rx_pp_alloc_slow_ho``
> > +     * ``rx_pp_alloc_empty``
> > +     * ``rx_pp_alloc_refill``
> > +     * ``rx_pp_alloc_waive``
> > +     * ``rx_pp_recycle_cached``
> > +     * ``rx_pp_recycle_cache_full``
> > +     * ``rx_pp_recycle_ring``
> > +     * ``rx_pp_recycle_ring_full``
> > +     * ``rx_pp_recycle_released_ref``  
> 
> My knowledge of Sphinx is pretty poor. Is it possible to put this list
> next to the actual definition and cross reference it? When new
> counters are added, they are more likely to be added to the list, if
> the list is nearby.

We can render kdoc into documentation. Not sure what's most suitable
here.

BTW does ``struct xyz`` result in correct linking to the kdoc like
:c:type:`xyz` would or I think these days also pure struct xyz?

Re: [PATCH net-next] Documentation: update networking/page_pool.rst with ethtool APIs

[Jonathan Corbet]

Jakub Kicinski <kuba@kernel.org> writes:

> BTW does ``struct xyz`` result in correct linking to the kdoc like
> :c:type:`xyz` would or I think these days also pure struct xyz?

Putting text into ``literal markup`` will interfere with our automarkup
magic.  Please just say "struct foo" and the right thing should happen.

Thanks,

jon