Contents

• Net DIM - Generic Network Dynamic Interrupt Moderation
  • Assumptions
  • Introduction
  • Net DIM Algorithm
  • Registering a Network Device to DIM
  • Example
  • Dynamic Interrupt Moderation (DIM) library API

Assumptions¶

This document assumes the reader has basic knowledge in network driversand in general interrupt moderation.

Introduction¶

Dynamic Interrupt Moderation (DIM) (in networking) refers to changing theinterrupt moderation configuration of a channel in order to optimize packetprocessing. The mechanism includes an algorithm which decides if and how tochange moderation parameters for a channel, usually by performing an analysis onruntime data sampled from the system. Net DIM is such a mechanism. In eachiteration of the algorithm, it analyses a given sample of the data, compares itto the previous sample and if required, it can decide to change some of theinterrupt moderation configuration fields. The data sample is composed of databandwidth, the number of packets and the number of events. The time betweensamples is also measured. Net DIM compares the current and the previous data andreturns an adjusted interrupt moderation configuration object. In some cases,the algorithm might decide not to change anything. The configuration fields arethe minimum duration (microseconds) allowed between events and the maximumnumber of wanted packets per event. The Net DIM algorithm ascribes importance toincrease bandwidth over reducing interrupt rate.

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.

The first two steps are straightforward, both the new and the previous data aresupplied by the driver registered to Net DIM. The previous data is the new datasupplied to the previous iteration. The comparison step checks the differencebetween the new and previous data and decides on the result of the last step.A step would result as “better” if bandwidth increases and as “worse” ifbandwidth reduces. If there is no change in bandwidth, the packet rate iscompared in a similar fashion - increase == “better” and decrease == “worse”.In case there is no change in the packet rate as well, the interrupt rate iscompared. Here the algorithm tries to optimize for lower interrupt rate so anincrease in the interrupt rate is considered “worse” and a decrease isconsidered “better”. Step #2 has an optimization for avoiding false results: itonly considers a difference between samples as valid if it is greater than acertain percentage. Also, since Net DIM does not measure anything by itself, itassumes the data provided by the driver is valid.

Step #3 decides on the suggested configuration based on the result from step #2and the internal state of the algorithm. The states reflect the “direction” ofthe algorithm: is it going left (reducing moderation), right (increasingmoderation) or standing still. Another optimization is that if a decisionto stay still is made multiple times, the interval between iterations of thealgorithm would increase in order to reduce calculation overhead. Also, after“parking” on one of the most left or most right decisions, the algorithm maydecide to verify this decision by taking a step in the other direction. This isdone in order to avoid getting stuck in a “deep sleep” scenario. Once adecision is made, an interrupt moderation configuration is selected fromthe predefined profiles.

The last step is to notify the registered driver that it should apply thesuggested configuration. This is done by scheduling a work function, defined bythe Net DIM API and provided by the registered driver.

As you can see, Net DIM itself does not actively interact with the system. Itwould have trouble making the correct decisions if the wrong data is supplied toit and it would be useless if the work function would not apply the suggestedconfiguration. This does, however, allow the registered driver some room formanoeuvre as it may provide partial data or ignore the algorithm suggestionunder some conditions.

Registering a Network Device to DIM¶

Net DIM API exposes the main functionnet_dim().This function is the entry point to the NetDIM algorithm and has to be called every time the driver would like to check ifit should change interrupt moderation parameters. The driver should provide twodata structures:structdim andstructdim_sample.structdimdescribes the state of DIM for a specific object (RX queue, TX queue,other queues, etc.). This includes the current selected profile, previous datasamples, the callback function provided by the driver and more.structdim_sample describes a data sample,which will be compared to the data sample stored instructdimin order to decide on the algorithm’s nextstep. The sample should include bytes, packets and interrupts, measured bythe driver.

In order to use Net DIM from a networking driver, the driver needs to call themainnet_dim() function. The recommended method is to callnet_dim() on eachinterrupt. Since Net DIM has a built-in moderation and it might decide to skipiterations 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 typestructdim to thenet_dim() function call. It is advised foreach entity using Net DIM to hold astructdim as part of itsdata structure and use it as the main Net DIM API object.Thestructdim_sample should hold the latestbytes, packets and interrupts count. No need to perform any calculations, justinclude the raw data.

Thenet_dim() call itself does not return anything. Instead Net DIM relies onthe driver to provide a callback function, which is called when the algorithmdecides to make a change in the interrupt moderation parameters. This callbackwill be scheduled and run in a separate thread in order not to add overhead tothe data flow. After the work is done, Net DIM algorithm needs to be set tothe proper state in order to move to the next iteration.

Example¶

The following code demonstrates how to register a driver to Net DIM. The actualusage is not complete but it should make the outline of the usage clear.

#include<linux/dim.h>/* Callback for net DIM to schedule on a decision to change moderation */voidmy_driver_do_dim_work(structwork_struct*work){/* Get struct dim from struct work_struct */structdim*dim=container_of(work,structdim,work);/* Do interrupt moderation related stuff */.../* Signal net DIM work is done and it should move to next iteration */dim->state=DIM_START_MEASURE;}/* My driver's interrupt handler */intmy_driver_handle_interrupt(structmy_driver_entity*my_entity,...){.../* A struct to hold current measured data */structdim_sampledim_sample;.../* Initiate data sample struct with current data */dim_update_sample(my_entity->events,my_entity->packets,my_entity->bytes,&dim_sample);/* Call net DIM */net_dim(&my_entity->dim,dim_sample);...}/* My entity's initialization function (my_entity was already allocated) */intmy_driver_init_my_entity(structmy_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);...}

Dynamic Interrupt Moderation (DIM) library API¶

structdim_cq_moder¶

Structure for CQ moderation values. Used for communications between DIM and its consumer.

Definition

struct dim_cq_moder {  u16 usec;  u16 pkts;  u16 comps;  u8 cq_period_mode;};

Members

usec

CQ timer suggestion (by DIM)

pkts

CQ packet counter suggestion (by DIM)

comps

Completion counter

cq_period_mode

CQ period count mode (from CQE/EQE)

structdim_sample¶

Structure for DIM sample data. Used for communications between DIM and its consumer.

Definition

struct dim_sample {  ktime_t time;  u32 pkt_ctr;  u32 byte_ctr;  u16 event_ctr;  u32 comp_ctr;};

Members

time

Sample timestamp

pkt_ctr

Number of packets

byte_ctr

Number of bytes

event_ctr

Number of events

comp_ctr

Current completion counter

structdim_stats¶

Structure for DIM stats. Used for holding current measured rates.

Definition

struct dim_stats {  int ppms;  int bpms;  int epms;  int cpms;  int cpe_ratio;};

Members

ppms

Packets per msec

bpms

Bytes per msec

epms

Events per msec

cpms

Completions per msec

cpe_ratio

Ratio of completions to events

structdim¶

Main structure for dynamic interrupt moderation (DIM). Used for holding all information about a specific DIM instance.

Definition

struct dim {  u8 state;  struct dim_stats prev_stats;  struct dim_sample start_sample;  struct dim_sample measuring_sample;  struct work_struct work;  void *priv;  u8 profile_ix;  u8 mode;  u8 tune_state;  u8 steps_right;  u8 steps_left;  u8 tired;};

Members

state

Algorithm state (see below)

prev_stats

Measured rates from previous iteration (for comparison)

start_sample

Sampled data at start of current iteration

measuring_sample

Adim_sample that is used to update the current events

work

Work to perform on action required

priv

A pointer to the struct that points to dim

profile_ix

Current moderation profile

mode

CQ period count mode

tune_state

Algorithm tuning state (see below)

steps_right

Number of steps taken towards higher moderation

steps_left

Number of steps taken towards lower moderation

tired

Parking depth counter

enumdim_cq_period_mode¶

Modes for CQ period count

Constants

DIM_CQ_PERIOD_MODE_START_FROM_EQE

Start counting from EQE

DIM_CQ_PERIOD_MODE_START_FROM_CQE

Start counting from CQE (implies timer reset)

DIM_CQ_PERIOD_NUM_MODES

Number of modes

enumdim_state¶

DIM algorithm states

Constants

DIM_START_MEASURE

This is the first iteration (also after applying a new profile)

DIM_MEASURE_IN_PROGRESS

Algorithm is already in progress - check ifneed to perform an action

DIM_APPLY_NEW_PROFILE

DIM consumer is currently applying a profile - no need to measure

Description

These will determine if the algorithm is in a valid state to start an iteration.

enumdim_tune_state¶

DIM algorithm tune states

Constants

DIM_PARKING_ON_TOP

Algorithm found a local top point - exit on significant difference

DIM_PARKING_TIRED

Algorithm found a deep top point - don’t exit if tired > 0

DIM_GOING_RIGHT

Algorithm is currently trying higher moderation levels

DIM_GOING_LEFT

Algorithm is currently trying lower moderation levels

Description

These will determine which action the algorithm should perform.

enumdim_stats_state¶

DIM algorithm statistics states

Constants

DIM_STATS_WORSE

Current iteration shows worse performance than before

DIM_STATS_SAME

Current iteration shows same performance than before

DIM_STATS_BETTER

Current iteration shows better performance than before

Description

These will determine the verdict of current iteration.

enumdim_step_result¶

DIM algorithm step results

Constants

DIM_STEPPED

Performed a regular step

DIM_TOO_TIRED

Same kind of step was done multiple times - should go totired parking

DIM_ON_EDGE

Stepped to the most left/right profile

Description

These describe the result of a step.

booldim_on_top(structdim * dim)¶

check if current state is a good place to stop (top location)

Parameters

structdim*dim

DIM context

Description

Check if current profile is a good place to park at.This will result in reducing the DIM checks frequency as we assume weshouldn’t probably change profiles, unless traffic pattern wasn’t changed.

voiddim_turn(structdim * dim)¶

change profile altering direction

Parameters

structdim*dim

DIM context

Description

Go left if we were going right and vice-versa.Do nothing if currently parking.

voiddim_park_on_top(structdim * dim)¶

enter a parking state on a top location

Parameters

structdim*dim

DIM context

Description

Enter parking state.Clear all movement history.

voiddim_park_tired(structdim * dim)¶

enter a tired parking state

Parameters

structdim*dim

DIM context

Description

Enter parking state.Clear all movement history and cause DIM checks frequency to reduce.

voiddim_calc_stats(structdim_sample * start, structdim_sample * end, structdim_stats * curr_stats)¶

calculate the difference between two samples

Parameters

structdim_sample*start

start sample

structdim_sample*end

end sample

structdim_stats*curr_stats

delta between samples

Description

Calculate the delta between two samples (in data rates).Takes into consideration counter wrap-around.

voiddim_update_sample(u16 event_ctr, u64 packets, u64 bytes, structdim_sample * s)¶

set a sample’s fields with given values

Parameters

u16event_ctr

number of events to set

u64packets

number of packets to set

u64bytes

number of bytes to set

structdim_sample*s

DIM sample

voiddim_update_sample_with_comps(u16 event_ctr, u64 packets, u64 bytes, u64 comps, structdim_sample * s)¶

set a sample’s fields with given values including the completion parameter

Parameters

u16event_ctr

number of events to set

u64packets

number of packets to set

u64bytes

number of bytes to set

u64comps

number of completions to set

structdim_sample*s

DIM sample

structdim_cq_modernet_dim_get_rx_moderation(u8 cq_period_mode, int ix)¶

provide a CQ moderation object for the given RX profile

Parameters

u8cq_period_mode

CQ period mode

intix

Profile index

structdim_cq_modernet_dim_get_def_rx_moderation(u8 cq_period_mode)¶

provide the default RX moderation

Parameters

u8cq_period_mode

CQ period mode

structdim_cq_modernet_dim_get_tx_moderation(u8 cq_period_mode, int ix)¶

provide a CQ moderation object for the given TX profile

Parameters

u8cq_period_mode

CQ period mode

intix

Profile index

structdim_cq_modernet_dim_get_def_tx_moderation(u8 cq_period_mode)¶

provide the default TX moderation

Parameters

u8cq_period_mode

CQ period mode

voidnet_dim(structdim * dim, structdim_sample end_sample)¶

main DIM algorithm entry point

Parameters

structdim*dim

DIM instance information

structdim_sampleend_sample

Current data measurement

Description

Called by the consumer.This is the main logic of the algorithm, where data is processed in orderto decide on next required action.

voidrdma_dim(structdim * dim, u64 completions)¶

Runs the adaptive moderation.

Parameters

structdim*dim

The moderation struct.

u64completions

The number of completions collected in this round.

Description

Each call to rdma_dim takes the latest amount of completions thathave been collected and counts them as a new event.Once enough events have been collected the algorithm decides a newmoderation level.