1====================================================== 2Net DIM - Generic Network Dynamic Interrupt Moderation 3====================================================== 4 5:Author: Tal Gilboa <talgi@mellanox.com> 6 7.. contents:: :depth: 2 8 9Assumptions 10=========== 11 12This document assumes the reader has basic knowledge in network drivers 13and in general interrupt moderation. 14 15 16Introduction 17============ 18 19Dynamic Interrupt Moderation (DIM) (in networking) refers to changing the 20interrupt moderation configuration of a channel in order to optimize packet 21processing. The mechanism includes an algorithm which decides if and how to 22change moderation parameters for a channel, usually by performing an analysis on 23runtime data sampled from the system. Net DIM is such a mechanism. In each 24iteration of the algorithm, it analyses a given sample of the data, compares it 25to the previous sample and if required, it can decide to change some of the 26interrupt moderation configuration fields. The data sample is composed of data 27bandwidth, the number of packets and the number of events. The time between 28samples is also measured. Net DIM compares the current and the previous data and 29returns an adjusted interrupt moderation configuration object. In some cases, 30the algorithm might decide not to change anything. The configuration fields are 31the minimum duration (microseconds) allowed between events and the maximum 32number of wanted packets per event. The Net DIM algorithm ascribes importance to 33increase bandwidth over reducing interrupt rate. 34 35 36Net DIM Algorithm 37================= 38 39Each iteration of the Net DIM algorithm follows these steps: 40 41#. Calculates new data sample. 42#. Compares it to previous sample. 43#. Makes a decision - suggests interrupt moderation configuration fields. 44#. Applies a schedule work function, which applies suggested configuration. 45 46The first two steps are straightforward, both the new and the previous data are 47supplied by the driver registered to Net DIM. The previous data is the new data 48supplied to the previous iteration. The comparison step checks the difference 49between the new and previous data and decides on the result of the last step. 50A step would result as "better" if bandwidth increases and as "worse" if 51bandwidth reduces. If there is no change in bandwidth, the packet rate is 52compared in a similar fashion - increase == "better" and decrease == "worse". 53In case there is no change in the packet rate as well, the interrupt rate is 54compared. Here the algorithm tries to optimize for lower interrupt rate so an 55increase in the interrupt rate is considered "worse" and a decrease is 56considered "better". Step #2 has an optimization for avoiding false results: it 57only considers a difference between samples as valid if it is greater than a 58certain percentage. Also, since Net DIM does not measure anything by itself, it 59assumes the data provided by the driver is valid. 60 61Step #3 decides on the suggested configuration based on the result from step #2 62and the internal state of the algorithm. The states reflect the "direction" of 63the algorithm: is it going left (reducing moderation), right (increasing 64moderation) or standing still. Another optimization is that if a decision 65to stay still is made multiple times, the interval between iterations of the 66algorithm would increase in order to reduce calculation overhead. Also, after 67"parking" on one of the most left or most right decisions, the algorithm may 68decide to verify this decision by taking a step in the other direction. This is 69done in order to avoid getting stuck in a "deep sleep" scenario. Once a 70decision is made, an interrupt moderation configuration is selected from 71the predefined profiles. 72 73The last step is to notify the registered driver that it should apply the 74suggested configuration. This is done by scheduling a work function, defined by 75the Net DIM API and provided by the registered driver. 76 77As you can see, Net DIM itself does not actively interact with the system. It 78would have trouble making the correct decisions if the wrong data is supplied to 79it and it would be useless if the work function would not apply the suggested 80configuration. This does, however, allow the registered driver some room for 81manoeuvre as it may provide partial data or ignore the algorithm suggestion 82under some conditions. 83 84 85Registering a Network Device to DIM 86=================================== 87 88Net DIM API exposes the main function net_dim(). 89This function is the entry point to the Net 90DIM algorithm and has to be called every time the driver would like to check if 91it should change interrupt moderation parameters. The driver should provide two 92data structures: :c:type:`struct dim <dim>` and 93:c:type:`struct dim_sample <dim_sample>`. :c:type:`struct dim <dim>` 94describes the state of DIM for a specific object (RX queue, TX queue, 95other queues, etc.). This includes the current selected profile, previous data 96samples, the callback function provided by the driver and more. 97:c:type:`struct dim_sample <dim_sample>` describes a data sample, 98which will be compared to the data sample stored in :c:type:`struct dim <dim>` 99in order to decide on the algorithm's next 100step. The sample should include bytes, packets and interrupts, measured by 101the driver. 102 103In order to use Net DIM from a networking driver, the driver needs to call the 104main net_dim() function. The recommended method is to call net_dim() on each 105interrupt. Since Net DIM has a built-in moderation and it might decide to skip 106iterations under certain conditions, there is no need to moderate the net_dim() 107calls as well. As mentioned above, the driver needs to provide an object of type 108:c:type:`struct dim <dim>` to the net_dim() function call. It is advised for 109each entity using Net DIM to hold a :c:type:`struct dim <dim>` as part of its 110data structure and use it as the main Net DIM API object. 111The :c:type:`struct dim_sample <dim_sample>` should hold the latest 112bytes, packets and interrupts count. No need to perform any calculations, just 113include the raw data. 114 115The net_dim() call itself does not return anything. Instead Net DIM relies on 116the driver to provide a callback function, which is called when the algorithm 117decides to make a change in the interrupt moderation parameters. This callback 118will be scheduled and run in a separate thread in order not to add overhead to 119the data flow. After the work is done, Net DIM algorithm needs to be set to 120the proper state in order to move to the next iteration. 121 122 123Example 124======= 125 126The following code demonstrates how to register a driver to Net DIM. The actual 127usage is not complete but it should make the outline of the usage clear. 128 129.. code-block:: c 130 131 #include <linux/dim.h> 132 133 /* Callback for net DIM to schedule on a decision to change moderation */ 134 void my_driver_do_dim_work(struct work_struct *work) 135 { 136 /* Get struct dim from struct work_struct */ 137 struct dim *dim = container_of(work, struct dim, 138 work); 139 /* Do interrupt moderation related stuff */ 140 ... 141 142 /* Signal net DIM work is done and it should move to next iteration */ 143 dim->state = DIM_START_MEASURE; 144 } 145 146 /* My driver's interrupt handler */ 147 int my_driver_handle_interrupt(struct my_driver_entity *my_entity, ...) 148 { 149 ... 150 /* A struct to hold current measured data */ 151 struct dim_sample dim_sample; 152 ... 153 /* Initiate data sample struct with current data */ 154 dim_update_sample(my_entity->events, 155 my_entity->packets, 156 my_entity->bytes, 157 &dim_sample); 158 /* Call net DIM */ 159 net_dim(&my_entity->dim, dim_sample); 160 ... 161 } 162 163 /* My entity's initialization function (my_entity was already allocated) */ 164 int my_driver_init_my_entity(struct my_driver_entity *my_entity, ...) 165 { 166 ... 167 /* Initiate struct work_struct with my driver's callback function */ 168 INIT_WORK(&my_entity->dim.work, my_driver_do_dim_work); 169 ... 170 } 171 172 173Tuning DIM 174========== 175 176Net DIM serves a range of network devices and delivers excellent acceleration 177benefits. Yet, it has been observed that some preset configurations of DIM may 178not align seamlessly with the varying specifications of network devices, and 179this discrepancy has been identified as a factor to the suboptimal performance 180outcomes of DIM-enabled network devices, related to a mismatch in profiles. 181 182To address this issue, Net DIM introduces a per-device control to modify and 183access a device's ``rx-profile`` and ``tx-profile`` parameters: 184Assume that the target network device is named ethx, and ethx only declares 185support for RX profile setting and supports modification of ``usec`` field 186and ``pkts`` field (See the data structure: 187:c:type:`struct dim_cq_moder <dim_cq_moder>`). 188 189You can use ethtool to modify the current RX DIM profile where all 190values are 64:: 191 192 $ ethtool -C ethx rx-profile 1,1,n_2,2,n_3,n,n_n,4,n_n,n,n 193 194``n`` means do not modify this field, and ``_`` separates structure 195elements of the profile array. 196 197Querying the current profiles using:: 198 199 $ ethtool -c ethx 200 ... 201 rx-profile: 202 {.usec = 1, .pkts = 1, .comps = n/a,}, 203 {.usec = 2, .pkts = 2, .comps = n/a,}, 204 {.usec = 3, .pkts = 64, .comps = n/a,}, 205 {.usec = 64, .pkts = 4, .comps = n/a,}, 206 {.usec = 64, .pkts = 64, .comps = n/a,} 207 tx-profile: n/a 208 209If the network device does not support specific fields of DIM profiles, 210the corresponding ``n/a`` will display. If the ``n/a`` field is being 211modified, error messages will be reported. 212 213 214Dynamic Interrupt Moderation (DIM) library API 215============================================== 216 217.. kernel-doc:: include/linux/dim.h 218 :internal: 219