docs: networking: convert DIM to RST
Subsystems (4)
Jakub Kicinski
maintainerPATCH v2 2/2 docs: networking: add full DIM API
In reply to Jakub KicinskiFrom: 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
@@ -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
Jakub Kicinski
maintainerPATCH 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
@@ -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
@@ -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
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.
Signed-off-by Jakub Kicinski <[email protected]>Reviewed-by Randy Dunlap <[email protected]>---
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
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
-0net_failover phy sfp-phylinkDocumentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +5
-13@@ -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 networkdrivers
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 tochanging the
interrupt moderation configuration of a channel in order to optimize
packetDocumentation/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 DIMalgorithm 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 configurationfields.
-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 configurationfields.
+#. 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 dataDocumentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +0
-0@@ -89,19 +82,21 @@ manoeuvre as it may provide partial data orignore 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 tothe 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 liketo check if
it should change interrupt moderation parameters. The driver should
provide twoDocumentation/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, TXqueue,
other queues, etc.). This includes the current selected profile,
previous data
samples, the callback function provided by the driver and more.
-Structdim_sampledescribes 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 methodis 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
thenet_dim()
calls as well. As mentioned above, the driver needs to provide an
object of type
-struct dim to thenet_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 structdim_sampleshould hold the latest
+:c:type:struct dim <dim>to thenet_dim()function call. It is advised for
+each entity using Net DIM to hold a :c:type:struct dim <dim>as part of itsDocumentation/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 anycalculations, 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 DIMalgorithm 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 changemoderation */
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 changemoderation */
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 nextiteration */
Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +1
-3dim->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 alreadyallocated) */
-intmy_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 alreadyallocated) */
+ intmy_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 callbackfunction */
Documentation/networking/net_dim.rst renamed from Documentation/networking/net_dim.txt +1
-1INIT_WORK(&my_entity->dim.work, my_driver_do_dim_work); -} + }MAINTAINERS +1
-0@@ -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]>
Jakub Kicinski
maintainerQuoted 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.
Signed-off-by Jakub Kicinski <[email protected]>Reviewed-by Randy Dunlap <[email protected]>---
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@@ -22,6 +22,7 @@ Linux Networking Documentation z8530book msg_zerocopy failover + net_dim
net_dimis 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?
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.
Signed-off-by Jakub Kicinski <[email protected]>Reviewed-by Randy Dunlap <[email protected]>---
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@@ -22,6 +22,7 @@ Linux Networking Documentation z8530book msg_zerocopy failover + net_dim
net_dimis 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_zerocopyjust 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.
Jakub Kicinski
maintainerQuoted 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.
Signed-off-by Jakub Kicinski <[email protected]>Reviewed-by Randy Dunlap <[email protected]>---
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
-0Documentation/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_dimis 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_zerocopyjust 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
6lowpanQuoted 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