Skip to contentSkip to conversation

docs: networking: convert DIM to RST

PATCH In review Jakub Kicinski 2 participants 6 messages Apr 9, 2020 – Apr 11, 2020

Subsystems (4)
lore
Share & tools
lore

Jakub Kicinski

author maintainer
#0 lore raw

PATCH v2 1/2 docs: networking: convert DIM to RST

Convert the Dynamic Interrupt Moderation doc to RST and use the RST features like syntax highlight, function and structure documentation, enumerations, table of contents.

---
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%)
Documentation/networking/index.rst +1 -0
index 50133d9761c9..6538ede29661 100644
@@ -22,6 +22,7 @@ Linux Networking Documentation
    z8530book
    msg_zerocopy
    failover
+   net_dim
    net_failover
    phy
    sfp-phylink
Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +43 -47

156 lines not on this page · raw message

MAINTAINERS +1 -0
index 9271068bde63..46a3a01b54b9 100644
@@ -5961,6 +5961,7 @@ M:	Tal Gilboa <[email protected]>
 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" <[email protected]>
Signature · 1 line
2.25.1
author maintainer
#1 lore raw

PATCH v2 2/2 docs: networking: add full DIM API

From: Randy Dunlap <[email protected]>

Add the full net DIM API to the net_dim.rst file.

---
 Documentation/networking/net_dim.rst | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/networking/net_dim.rst +6 -0
index 1de1e3ec774b..3bed9fd95336 100644
@@ -168,3 +168,9 @@ usage is not complete but it should make the outline of the usage clear.
 	INIT_WORK(&my_entity->dim.work, my_driver_do_dim_work);
 	...
   }
+
+Dynamic Interrupt Moderation (DIM) library API
+==============================================
+
+.. kernel-doc:: include/linux/dim.h
+    :internal:
Signature · 1 line
2.25.1
#2 lore raw
In reply to Jakub Kicinski
Quoted 25 lines · Jakub Kicinski

Convert the Dynamic Interrupt Moderation doc to RST and use the RST features like syntax highlight, function and structure documentation, enumerations, table of contents.

---
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%)
Documentation/networking/index.rst +0 -0
index 50133d9761c9..6538ede29661 100644

Documentation/networking/index.rst Linux Networking Documentation · line 25

Quoted 4 lines
Documentation/networking/index.rst +1 -0
@@ -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 ..

Quoted 231 lines
Documentation/networking/index.rst +0 -0
    net_failover
    phy
    sfp-phylink
Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +5 -13
similarity index 79%
rename from Documentation/networking/net_dim.txt
rename to Documentation/networking/net_dim.rst
index 9bdb7d5a3ba3..1de1e3ec774b 100644
@@ -1,28 +1,20 @@
+======================================================
 Net DIM - Generic Network Dynamic Interrupt Moderation
 ======================================================
 
-Author:
-	Tal Gilboa <[email protected]>
-
-
-Contents
-=========
+:Author: Tal Gilboa <[email protected]>
 
-- 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.

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -2
-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

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +0 -0
@@ -41,14 +33,15 @@ number of wanted packets per event. The Net DIM

algorithm ascribes importance to
increase bandwidth over reducing interrupt rate.

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -5
-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.

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +4 -0
+
+#. 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

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +0 -0
@@ -89,19 +82,21 @@ manoeuvre as it may provide partial data or

ignore the algorithm suggestion
under some conditions.

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -4
-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

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -0
+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

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -1
-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.

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +0 -0
@@ -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

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -0
+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.

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +0 -0
@@ -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.

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -2
-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.

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -3
-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 */

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +1 -2
-void my_driver_do_dim_work(struct work_struct *work)
-{
+  /* Callback for net DIM to schedule on a decision to change

moderation */

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -0
+  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 */

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +1 -3
 	dim->state = DIM_START_MEASURE;
-}
+  }
 
-/* My driver's interrupt handler */
-int my_driver_handle_interrupt(struct my_driver_entity *my_entity,

...)

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -1
-{
+  /* My driver's interrupt handler */
+  int my_driver_handle_interrupt(struct my_driver_entity *my_entity,

...)

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +2 -2
+  {
...
 	/* 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, ...)

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +1 -1
-{
+  /* My entity's initialization function (my_entity was already

allocated) */
+ int my_driver_init_my_entity(struct my_driver_entity *my_entity, ...)

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +1 -0
+  {
...
 	/* Initiate struct work_struct with my driver's callback

function */

Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +1 -1
 	INIT_WORK(&my_entity->dim.work, my_driver_do_dim_work);
...
-}
+  }
MAINTAINERS +1 -0
index 9271068bde63..46a3a01b54b9 100644
@@ -5961,6 +5961,7 @@ M:	Tal Gilboa <[email protected]>
 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" <[email protected]>
author maintainer
#3 lore raw
Quoted 20 lines · On Thu, 9 Apr 2020 22:46:55 +0000 Saeed Mahameed wrote:
Quoted 19 lines · Jakub Kicinski

Convert the Dynamic Interrupt Moderation doc to RST and use the RST features like syntax highlight, function and structure documentation, enumerations, table of contents.

---
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%)
Quoted 13 lines

Documentation/networking/index.rst Linux Networking Documentation · line 25

Quoted 10 lines
Documentation/networking/index.rst +1 -0
index 50133d9761c9..6538ede29661 100644
@@ -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 ..

I mean.. so is msg_zerocopy just above ;-) I spotted slight alphabetical ordering there, which may have not been intentional, that's why I put it here. Marking with # things out of order, but based on just the first letter:

# netdev-FAQ
af_xdp
bareudp
batman-adv
can
can_ucan_protocol
device_drivers/index
dsa/index
devlink/index
ethtool-netlink
ieee802154
j1939
kapi
# z8530book
msg_zerocopy
# failover
net_dim
net_failover
phy
sfp-phylink
# alias
# bridge
snmp_counter
# checksum-offloads
segmentation-offloads
scaling
tls
tls-offload
# nfc
6lowpan

My feeling is that we should start considering splitting kernel-only docs and admin-only docs for networking, which I believe is the direction Jon and folks want Documentation/ to go. But I wasn't brave enough to be the first one. Then we can impose some more structure, like putting all "performance" docs in one subdir..?

WDYT?

#4 lore raw
Quoted 38 lines · Jakub Kicinski
Quoted 22 lines · On Thu, 9 Apr 2020 22:46:55 +0000 Saeed Mahameed wrote:
Quoted 21 lines · Jakub Kicinski

Convert the Dynamic Interrupt Moderation doc to RST and use the RST features like syntax highlight, function and structure documentation, enumerations, table of contents.

---
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%)

Quoted 14 lines

Documentation/networking/index.rst Linux Networking Documentation · line 25

Quoted 10 lines
Documentation/networking/index.rst +1 -0
index 50133d9761c9..6538ede29661 100644
@@ -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 ..

Quoted 5 lines

I mean.. so is msg_zerocopy just above ;-) I spotted slight alphabetical ordering there, which may have not been intentional, that's why I put it here. Marking with # things out of order, but based on just the first letter:

Oh i didn't see the alphabetical order :), then i guess your patch is ok.

Quoted 31 lines

# netdev-FAQ
af_xdp
bareudp
batman-adv
can
can_ucan_protocol
device_drivers/index
dsa/index
devlink/index
ethtool-netlink
ieee802154
j1939
kapi
# z8530book
msg_zerocopy
# failover
net_dim
net_failover
phy
sfp-phylink
# alias
# bridge
snmp_counter
# checksum-offloads
segmentation-offloads
scaling
tls
tls-offload
# nfc
6lowpan

Quoted 7 lines

My feeling is that we should start considering splitting kernel-only docs and admin-only docs for networking, which I believe is the direction Jon and folks want Documentation/ to go. But I wasn't brave enough to be the first one. Then we can impose some more structure, like putting all "performance" docs in one subdir..?

WDYT?

That was my initial thought, but it seemed like a lot of work and really not related to your patch.

But yes, categorizing is the way to go.. alphabetical order doesn't really make any sense unless you know exactly what you are looking for, which is never the case :),
For someone who want to learn about performance tuning or something specific like coalescing, what should they look for ? DIM, NET DIM, moderation or coalescing ? so if we categorize and keep the subdirs lists short and focused, it will be very easy for people to browse the networking docs..

Things can grow large very fast beyond our control.. We should really embrace the "Magic number 7" approach [1] :)

Helps keep things short, organized and focused.

[1]
https://www.i-programmer.info/babbages-bag/621-the-magic-number-seven.html

Thanks,
Saeed.

author maintainer
#5 lore raw
Quoted 39 lines · On Fri, 10 Apr 2020 21:59:56 +0000 Saeed Mahameed wrote:
Quoted 38 lines · Jakub Kicinski
Quoted 36 lines · On Thu, 9 Apr 2020 22:46:55 +0000 Saeed Mahameed wrote:
Quoted 27 lines · Jakub Kicinski

Convert the Dynamic Interrupt Moderation doc to RST and use the RST features like syntax highlight, function and structure documentation, enumerations, table of contents.

---
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%)

Documentation/networking/index.rst +0 -0
index 50133d9761c9..6538ede29661 100644

Documentation/networking/index.rst Linux Networking Documentation · line 25

Quoted 4 lines
Documentation/networking/index.rst +1 -0
@@ -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 ..

Quoted 8 lines
Quoted 5 lines

I mean.. so is msg_zerocopy just above ;-) I spotted slight alphabetical ordering there, which may have not been intentional, that's why I put it here. Marking with # things out of order, but based on just the first letter:

Oh i didn't see the alphabetical order :), then i guess your patch is ok.

Cool, applied.

Quoted 42 lines
Quoted 31 lines

# netdev-FAQ
af_xdp
bareudp
batman-adv
can
can_ucan_protocol
device_drivers/index
dsa/index
devlink/index
ethtool-netlink
ieee802154
j1939
kapi
# z8530book
msg_zerocopy
# failover
net_dim
net_failover
phy
sfp-phylink
# alias
# bridge
snmp_counter
# checksum-offloads
segmentation-offloads
scaling
tls
tls-offload
# nfc
6lowpan

Quoted 7 lines

My feeling is that we should start considering splitting kernel-only docs and admin-only docs for networking, which I believe is the direction Jon and folks want Documentation/ to go. But I wasn't brave enough to be the first one. Then we can impose some more structure, like putting all "performance" docs in one subdir..?

WDYT?

That was my initial thought, but it seemed like a lot of work and really not related to your patch.

Quoted 8 lines

But yes, categorizing is the way to go.. alphabetical order doesn't really make any sense unless you know exactly what you are looking for, which is never the case :),
For someone who want to learn about performance tuning or something specific like coalescing, what should they look for ? DIM, NET DIM, moderation or coalescing ? so if we categorize and keep the subdirs lists short and focused, it will be very easy for people to browse the networking docs..

Fully agree.

Quoted 7 lines

Things can grow large very fast beyond our control.. We should really embrace the "Magic number 7" approach [1] :)

Helps keep things short, organized and focused.

[1]
https://www.i-programmer.info/babbages-bag/621-the-magic-number-seven.html

Here I thought the magic number was 3 :-P

https://queue.acm.org/detail.cfm?id=3387947