Net DIM - Generic Network Dynamic Interrupt Moderation

전제와 DIM의 목적

이 문서는 network driver와 일반적인 interrupt moderation의 기초 지식을 전제로 합니다. Networking의 DIM(Dynamic Interrupt Moderation)은 packet 처리 성능을 최적화하도록 channel의 interrupt moderation configuration을 runtime에 바꾸는 기법이며 Net DIM은 Linux의 범용 구현입니다.

각 iteration은 driver가 제공한 현재 sample을 이전 sample과 비교하고 필요하면 moderation configuration을 조정합니다. Sample은 data bandwidth, packet 수, event 수와 sample 사이 시간으로 구성됩니다. 결과 configuration은 event 사이 최소 시간인 microsecond 값과 event 하나당 원하는 최대 packet 수를 담습니다.

Algorithm은 interrupt rate 감소보다 bandwidth 증가를 우선합니다. 상황에 따라 configuration을 바꾸지 않을 수 있으며 Net DIM 자체는 측정하지 않고 driver가 제공한 누적 data에 의존합니다.

======================================================
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.

비교·방향·profile 선택 algorithm

Iteration은 새 sample 계산, 이전 sample과 비교, 추천 moderation field 결정, driver work scheduling의 네 단계입니다. 새 sample과 이전 sample은 등록한 driver가 제공하며 이전 iteration의 current sample이 다음 비교의 previous sample이 됩니다.

비교는 먼저 bandwidth를 봅니다. 증가하면 better, 감소하면 worse입니다. Bandwidth가 같으면 packet rate를 같은 방식으로 비교하고 그것도 같으면 interrupt rate를 봅니다. Interrupt rate는 낮추는 것이 목표이므로 증가는 worse, 감소는 better입니다. 작은 noise를 잘못 판정하지 않도록 차이가 일정 percentage보다 클 때만 유효하게 봅니다.

결정 state는 moderation을 줄이는 left, 늘리는 right, 유지하는 standing still 방향을 나타냅니다. 여러 번 연속 정지하면 계산 overhead를 줄이기 위해 iteration interval을 늘립니다. 가장 왼쪽이나 오른쪽 profile에 parking한 뒤에는 deep sleep처럼 한 극단에 갇히지 않았는지 반대 방향으로 한 step 움직여 검증할 수 있습니다.

결정을 내리면 predefined profile에서 configuration을 고르고 Net DIM API가 driver 제공 work function을 schedule하여 적용을 알립니다. Net DIM은 hardware에 직접 접근하지 않으므로 잘못된 sample이나 적용하지 않는 callback에서는 효과가 없습니다. 반대로 driver가 일부 data만 제공하거나 특정 조건에서 suggestion을 무시할 여지도 있습니다.

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
the predefined profiles.

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

As you can see, Net DIM itself does not actively interact with the system. It
would have trouble making the correct decisions if the wrong data is supplied to
it and it would be useless if the work function would not apply the suggested
configuration. This does, however, allow the registered driver some room for
manoeuvre as it may provide partial data or ignore the algorithm suggestion
under some conditions.

Driver 등록과 callback 계약

Driver는 moderation 변경 여부를 확인할 때마다 main API `net_dim()`을 호출합니다. `struct dim`은 RX queue, TX queue 같은 대상 하나의 현재 profile, 이전 sample, driver callback과 algorithm state를 보관합니다. 각 entity의 data structure 안에 전용 `struct dim`을 포함하는 방식이 권장됩니다.

`struct dim_sample`에는 driver가 측정한 최신 byte, packet, interrupt 누적 count를 계산하지 않은 raw 값으로 넣습니다. 매 interrupt마다 `net_dim()`을 호출해도 됩니다. Net DIM 내부에 moderation과 iteration skip logic이 있으므로 caller가 별도로 call 빈도를 제한할 필요가 없습니다.

`net_dim()`은 값을 반환하지 않습니다. Parameter 변경이 필요하면 driver가 제공한 callback을 별도 thread에서 schedule하여 data flow에 overhead를 더하지 않습니다. Driver가 work를 완료한 뒤 DIM state를 다음 iteration을 시작할 올바른 상태로 바꿔야 합니다.

Registering a Network Device to DIM
===================================

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
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.
: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.

In order to use Net DIM from a networking driver, the driver needs to call the
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
: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
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.

The net_dim() call itself does not return anything. Instead Net DIM relies on
the driver to provide a callback function, which is called when the algorithm
decides to make a change in the interrupt moderation parameters. This callback
will be scheduled and run in a separate thread in order not to add overhead to
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.

Driver 구현 예제

예제는 `<linux/dim.h>`를 include하고 `my_driver_do_dim_work()`를 DIM work callback으로 등록합니다. Callback은 `container_of()`로 `work_struct`에서 `struct dim`을 얻고 interrupt moderation을 적용한 뒤 `dim->state = DIM_START_MEASURE`로 다음 측정을 허용합니다.

Interrupt handler는 `struct dim_sample`을 만들고 `dim_update_sample(events, packets, bytes, &dim_sample)`로 현재 raw counter를 채운 다음 `net_dim(&my_entity->dim, &dim_sample)`을 호출합니다. Entity initialization은 `INIT_WORK(&my_entity->dim.work, my_driver_do_dim_work)`로 callback을 연결합니다.

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.

.. code-block:: c

  #include <linux/dim.h>

  /* Callback for net DIM to schedule on a decision to change moderation */
  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);
        /* 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 */
  int my_driver_handle_interrupt(struct my_driver_entity *my_entity, ...)
  {
        ...
        /* A struct to hold current measured data */
        struct dim_sample dim_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) */
  int my_driver_init_my_entity(struct my_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);
        ...
  }

Device별 RX·TX profile tuning

Net DIM preset profile이 모든 network device 특성과 맞지는 않아 profile mismatch가 suboptimal performance를 만들 수 있습니다. 이를 해결하려고 device별 `rx-profile`과 `tx-profile`을 조회·수정하는 control을 제공합니다.

예제 device `ethx`가 RX profile 설정과 `usec`, `pkts` field 수정만 지원한다고 가정합니다. `ethtool -C ethx rx-profile ...`에서 `n`은 그 field를 수정하지 않는다는 뜻이고 `_`는 profile array의 구조체 element를 구분합니다.

`ethtool -c ethx`로 현재 profile을 조회합니다. 예제는 다섯 RX entry의 `.usec`와 `.pkts`를 보여 주며 지원하지 않는 `.comps`와 TX profile은 `n/a`입니다. Device가 지원하지 않는 `n/a` field를 수정하면 error가 보고됩니다.

Tuning DIM
==========

Net DIM serves a range of network devices and delivers excellent acceleration
benefits. Yet, it has been observed that some preset configurations of DIM may
not align seamlessly with the varying specifications of network devices, and
this discrepancy has been identified as a factor to the suboptimal performance
outcomes of DIM-enabled network devices, related to a mismatch in profiles.

To address this issue, Net DIM introduces a per-device control to modify and
access a device's ``rx-profile`` and ``tx-profile`` parameters:
Assume that the target network device is named ethx, and ethx only declares
support for RX profile setting and supports modification of ``usec`` field
and ``pkts`` field (See the data structure:
:c:type:`struct dim_cq_moder <dim_cq_moder>`).

You can use ethtool to modify the current RX DIM profile where all
values are 64::

    $ ethtool -C ethx rx-profile 1,1,n_2,2,n_3,n,n_n,4,n_n,n,n

``n`` means do not modify this field, and ``_`` separates structure
elements of the profile array.

Querying the current profiles using::

    $ ethtool -c ethx
    ...
    rx-profile:
    {.usec =   1, .pkts =   1, .comps = n/a,},
    {.usec =   2, .pkts =   2, .comps = n/a,},
    {.usec =   3, .pkts =  64, .comps = n/a,},
    {.usec =  64, .pkts =   4, .comps = n/a,},
    {.usec =  64, .pkts =  64, .comps = n/a,}
    tx-profile:   n/a

If the network device does not support specific fields of DIM profiles,
the corresponding ``n/a`` will display. If the ``n/a`` field is being
modified, error messages will be reported.

DIM library API

Dynamic Interrupt Moderation library의 내부 kernel-doc는 `include/linux/dim.h`에서 생성됩니다. 실제 구조체 field와 internal API signature는 이 header의 문서가 기준입니다.

Dynamic Interrupt Moderation (DIM) library API
==============================================

.. kernel-doc:: include/linux/dim.h
    :internal: