Documentation/networking/net_dim.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/net_dim.rst

File Facts

System: Linux kernel
Corpus path: Documentation/networking/net_dim.rst
Extension: .rst
Size: 9575 bytes
Lines: 219
Domain: Support Tooling And Documentation
Bucket: Documentation
Inferred role: Support Tooling And Documentation: documentation
Status: atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.
Defines or uses C structs; map object ownership, embedded links, reference counts, and lock ownership.

Dependency Surface

linux/dim.h

Detected Declarations

function Moderation
function my_driver_handle_interrupt
function my_driver_init_my_entity

Annotated Snippet

======================================================
Net DIM - Generic Network Dynamic Interrupt Moderation
======================================================

:Author: Tal Gilboa <talgi@mellanox.com>

.. contents:: :depth: 2

Assumptions
===========

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


Introduction
============

Dynamic Interrupt Moderation (DIM) (in networking) refers to changing the
interrupt moderation configuration of a channel in order to optimize packet
processing. The mechanism includes an algorithm which decides if and how to
change moderation parameters for a channel, usually by performing an analysis on
runtime data sampled from the system. Net DIM is such a mechanism. In each
iteration of the algorithm, it analyses a given sample of the data, compares it
to the previous sample and if required, it can decide to change some of the
interrupt moderation configuration fields. The data sample is composed of data
bandwidth, the number of packets and the number of events. The time between
samples is also measured. Net DIM compares the current and the previous data and
returns an adjusted interrupt moderation configuration object. In some cases,
the algorithm might decide not to change anything. The configuration fields are
the minimum duration (microseconds) allowed between events and the maximum
number of wanted packets per event. The Net DIM algorithm ascribes importance to
increase bandwidth over reducing interrupt rate.


Net DIM Algorithm
=================

Each iteration of the Net DIM algorithm follows these steps:

#. 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
supplied to the previous iteration. The comparison step checks the difference
between 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" if
bandwidth reduces. If there is no change in bandwidth, the packet rate is
compared in a similar fashion - increase == "better" and decrease == "worse".
In case there is no change in the packet rate as well, the interrupt rate is
compared. Here the algorithm tries to optimize for lower interrupt rate so an
increase in the interrupt rate is considered "worse" and a decrease is
considered "better". Step #2 has an optimization for avoiding false results: it
only considers a difference between samples as valid if it is greater than a
certain percentage. Also, since Net DIM does not measure anything by itself, it
assumes the data provided by the driver is valid.

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

Annotation

Immediate include surface: `linux/dim.h`.
Detected declarations: `function Moderation`, `function my_driver_handle_interrupt`, `function my_driver_init_my_entity`.
Atlas domain: Support Tooling And Documentation / Documentation.
Implementation status: atlas-only.

Implementation Notes

This generated page is the file-by-file coverage layer; curated subsystem chapters should link here when they synthesize a multi-file control flow.
Core OS pages should be promoted from atlas-only to deep-reviewed when they explain data structures, invariants, locking, lifecycle, and C implementation snippets.
Driver-family pages are intentionally pattern-oriented unless they are part of the selected PCIe/NVMe representative device path.