On Thu, 2020-04-09 at 14:21 -0700, Jakub Kicinski wrote:
> Convert the Dynamic Interrupt Moderation doc to RST and
> use the RST features like syntax highlight, function and
> structure documentation, enumerations, table of contents.
>
> Signed-off-by: Jakub Kicinski <kuba@xxxxxxxxxx>
> Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> ---
> v2:
> - remove the functions/type definition markup
> - change the contents definition (the :local: seem to
> not work too well with kdoc)
> ---
> Documentation/networking/index.rst | 1 +
> .../networking/{net_dim.txt => net_dim.rst} | 90 +++++++++------
> ----
> MAINTAINERS | 1 +
> 3 files changed, 45 insertions(+), 47 deletions(-)
> rename Documentation/networking/{net_dim.txt => net_dim.rst} (79%)
>
> diff --git a/Documentation/networking/index.rst
> b/Documentation/networking/index.rst
> index 50133d9761c9..6538ede29661 100644
> --- a/Documentation/networking/index.rst
> +++ b/Documentation/networking/index.rst
> @@ -22,6 +22,7 @@ Linux Networking Documentation
> z8530book
> msg_zerocopy
> failover
> + net_dim
net_dim is a performance feature, i would move further down the list
where the perf features such as scaling and offloads are ..
> net_failover
> phy
> sfp-phylink
> diff --git a/Documentation/networking/net_dim.txt
> b/Documentation/networking/net_dim.rst
> similarity index 79%
> rename from Documentation/networking/net_dim.txt
> rename to Documentation/networking/net_dim.rst
> index 9bdb7d5a3ba3..1de1e3ec774b 100644
> --- a/Documentation/networking/net_dim.txt
> +++ b/Documentation/networking/net_dim.rst
> @@ -1,28 +1,20 @@
> +======================================================
> Net DIM - Generic Network Dynamic Interrupt Moderation
> ======================================================
>
> -Author:
> - Tal Gilboa <talgi@xxxxxxxxxxxx>
> -
> -
> -Contents
> -=========
> +:Author: Tal Gilboa <talgi@xxxxxxxxxxxx>
>
> -- Assumptions
> -- Introduction
> -- The Net DIM Algorithm
> -- Registering a Network Device to DIM
> -- Example
> +.. contents:: :depth: 2
>
> -Part 0: Assumptions
> -======================
> +Assumptions
> +===========
>
> This document assumes the reader has basic knowledge in network
> drivers
> and in general interrupt moderation.
>
>
> -Part I: Introduction
> -======================
> +Introduction
> +============
>
> Dynamic Interrupt Moderation (DIM) (in networking) refers to
> changing the
> interrupt moderation configuration of a channel in order to optimize
> packet
> @@ -41,14 +33,15 @@ number of wanted packets per event. The Net DIM
> algorithm ascribes importance to
> increase bandwidth over reducing interrupt rate.
>
>
> -Part II: The Net DIM Algorithm
> -===============================
> +Net DIM Algorithm
> +=================
>
> Each iteration of the Net DIM algorithm follows these steps:
> -1. Calculates new data sample.
> -2. Compares it to previous sample.
> -3. Makes a decision - suggests interrupt moderation configuration
> fields.
> -4. Applies a schedule work function, which applies suggested
> configuration.
> +
> +#. Calculates new data sample.
> +#. Compares it to previous sample.
> +#. Makes a decision - suggests interrupt moderation configuration
> fields.
> +#. Applies a schedule work function, which applies suggested
> configuration.
>
> The first two steps are straightforward, both the new and the
> previous data are
> supplied by the driver registered to Net DIM. The previous data is
> the new data
> @@ -89,19 +82,21 @@ manoeuvre as it may provide partial data or
> ignore the algorithm suggestion
> under some conditions.
>
>
> -Part III: Registering a Network Device to DIM
> -==============================================
> +Registering a Network Device to DIM
> +===================================
>
> -Net DIM API exposes the main function net_dim(struct dim *dim,
> -struct dim_sample end_sample). This function is the entry point to
> the Net
> +Net DIM API exposes the main function net_dim().
> +This function is the entry point to the Net
> DIM algorithm and has to be called every time the driver would like
> to check if
> it should change interrupt moderation parameters. The driver should
> provide two
> -data structures: struct dim and struct dim_sample. Struct dim
> +data structures: :c:type:`struct dim <dim>` and
> +:c:type:`struct dim_sample <dim_sample>`. :c:type:`struct dim <dim>`
> describes the state of DIM for a specific object (RX queue, TX
> queue,
> other queues, etc.). This includes the current selected profile,
> previous data
> samples, the callback function provided by the driver and more.
> -Struct dim_sample describes a data sample, which will be compared to
> the
> -data sample stored in struct dim in order to decide on the
> algorithm's next
> +:c:type:`struct dim_sample <dim_sample>` describes a data sample,
> +which will be compared to the data sample stored in :c:type:`struct
> dim <dim>`
> +in order to decide on the algorithm's next
> step. The sample should include bytes, packets and interrupts,
> measured by
> the driver.
>
> @@ -110,9 +105,10 @@ main net_dim() function. The recommended method
> is to call net_dim() on each
> interrupt. Since Net DIM has a built-in moderation and it might
> decide to skip
> iterations under certain conditions, there is no need to moderate
> the net_dim()
> calls as well. As mentioned above, the driver needs to provide an
> object of type
> -struct dim to the net_dim() function call. It is advised for each
> entity
> -using Net DIM to hold a struct dim as part of its data structure and
> use it
> -as the main Net DIM API object. The struct dim_sample should hold
> the latest
> +:c:type:`struct dim <dim>` to the net_dim() function call. It is
> advised for
> +each entity using Net DIM to hold a :c:type:`struct dim <dim>` as
> part of its
> +data structure and use it as the main Net DIM API object.
> +The :c:type:`struct dim_sample <dim_sample>` should hold the latest
> bytes, packets and interrupts count. No need to perform any
> calculations, just
> include the raw data.
>
> @@ -124,19 +120,19 @@ the data flow. After the work is done, Net DIM
> algorithm needs to be set to
> the proper state in order to move to the next iteration.
>
>
> -Part IV: Example
> -=================
> +Example
> +=======
>
> The following code demonstrates how to register a driver to Net DIM.
> The actual
> usage is not complete but it should make the outline of the usage
> clear.
>
> -my_driver.c:
> +.. code-block:: c
>
> -#include <linux/dim.h>
> + #include <linux/dim.h>
>
> -/* Callback for net DIM to schedule on a decision to change
> moderation */
> -void my_driver_do_dim_work(struct work_struct *work)
> -{
> + /* Callback for net DIM to schedule on a decision to change
> moderation */
> + void my_driver_do_dim_work(struct work_struct *work)
> + {
> /* Get struct dim from struct work_struct */
> struct dim *dim = container_of(work, struct dim,
> work);
> @@ -145,11 +141,11 @@ void my_driver_do_dim_work(struct work_struct
> *work)
>
> /* Signal net DIM work is done and it should move to next
> iteration */
> dim->state = DIM_START_MEASURE;
> -}
> + }
>
> -/* My driver's interrupt handler */
> -int my_driver_handle_interrupt(struct my_driver_entity *my_entity,
> ...)
> -{
> + /* My driver's interrupt handler */
> + int my_driver_handle_interrupt(struct my_driver_entity *my_entity,
> ...)
> + {
> ...
> /* A struct to hold current measured data */
> struct dim_sample dim_sample;
> @@ -162,13 +158,13 @@ int my_driver_handle_interrupt(struct
> my_driver_entity *my_entity, ...)
> /* Call net DIM */
> net_dim(&my_entity->dim, dim_sample);
> ...
> -}
> + }
>
> -/* My entity's initialization function (my_entity was already
> allocated) */
> -int my_driver_init_my_entity(struct my_driver_entity *my_entity,
> ...)
> -{
> + /* My entity's initialization function (my_entity was already
> allocated) */
> + int my_driver_init_my_entity(struct my_driver_entity *my_entity,
> ...)
> + {
> ...
> /* Initiate struct work_struct with my driver's callback
> function */
> INIT_WORK(&my_entity->dim.work, my_driver_do_dim_work);
> ...
> -}
> + }
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 9271068bde63..46a3a01b54b9 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -5961,6 +5961,7 @@ M: Tal Gilboa <talgi@xxxxxxxxxxxx>
> S: Maintained
> F: include/linux/dim.h
> F: lib/dim/
> +F: Documentation/networking/net_dim.rst
>
> DZ DECSTATION DZ11 SERIAL DRIVER
> M: "Maciej W. Rozycki" <macro@xxxxxxxxxxxxxx>
