Devlink DPIPE

DPIPE 배경

이 문서는 `GPL-2.0` 라이선스를 따릅니다.

Devlink DPIPE

배경

hardware offload 과정에서는 hardware의 구체적인 사항 상당 부분을 표시할 수 없습니다. 그러나 이러한 세부 정보는 debugging에 유용하며, `devlink-dpipe`는 offload 과정을 들여다볼 수 있는 표준화된 방법을 제공합니다.

예를 들어 Linux kernel이 사용하는 routing longest prefix match(LPM) 알고리즘은 hardware 구현과 다를 수 있습니다. pipeline debug API인 DPIPE는 ASIC pipeline을 일반적인 방식으로 사용자가 관찰할 수 있게 하는 것을 목표로 합니다.

hardware offload는 사용자가 hardware 구현과 software 구현을 구별할 수 없도록 수행되는 것이 바람직합니다. 이 과정에서는 hardware 세부 사항이 무시되지만, 실제로는 그 정보가 큰 의미를 가질 수 있으므로 표준적인 방식으로 노출해야 합니다.

networking stack 전체의 control path를 switch ASIC으로 offload하려 하면 문제는 더욱 복잡해집니다. hardware model과 software model의 차이 때문에 일부 과정을 올바르게 표현할 수 없기 때문입니다.

대표적인 예가 kernel의 LPM 알고리즘입니다. 구성 API는 같아도 FIB(Forward Information Base)가 hardware의 LPC-trie(Level Path Compression trie)와 같은 모습이라고 가정할 수 없습니다.

kernel dump만으로 system 장애를 분석해서는 충분하지 않은 경우가 많습니다. 기반 hardware 정보를 함께 보면 debugging이 쉬워지고 performance 문제를 분석할 때도 도움이 됩니다.

.. SPDX-License-Identifier: GPL-2.0

=============
Devlink DPIPE
=============

Background
==========

While performing the hardware offloading process, much of the hardware
specifics cannot be presented. These details are useful for debugging, and
``devlink-dpipe`` provides a standardized way to provide visibility into the
offloading process.

For example, the routing longest prefix match (LPM) algorithm used by the
Linux kernel may differ from the hardware implementation. The pipeline debug
API (DPIPE) is aimed at providing the user visibility into the ASIC's
pipeline in a generic way.

The hardware offload process is expected to be done in a way that the user
should not be able to distinguish between the hardware vs. software
implementation. In this process, hardware specifics are neglected. In
reality those details can have lots of meaning and should be exposed in some
standard way.

This problem is made even more complex when one wishes to offload the
control path of the whole networking stack to a switch ASIC. Due to
differences in the hardware and software models some processes cannot be
represented correctly.

One example is the kernel's LPM algorithm which in many cases differs
greatly to the hardware implementation. The configuration API is the same,
but one cannot rely on the Forward Information Base (FIB) to look like the
Level Path Compression trie (LPC-trie) in hardware.

In many situations trying to analyze systems failure solely based on the
kernel's dump may not be enough. By combining this data with complementary
information about the underlying hardware, this debugging can be made
easier; additionally, the information can be useful when debugging
performance issues.

DPIPE 개요

개요

`devlink-dpipe` interface는 이 간극을 메웁니다. hardware pipeline을 match/action table의 graph로 모델링하고, 각 table은 특정 hardware block을 나타냅니다. 이 model은 P4 언어에서 처음 사용된 기존 개념입니다.

전통적으로 이 model은 hardware 구성의 대체 수단으로 사용됐지만, `devlink-dpipe`는 표준 구성 도구를 보완하는 관찰 수단으로 사용합니다. 따라서 표준 구성 도구로 설정을 바꾸면 `devlink-dpipe`가 보여 주는 system view도 그에 맞게 바뀌어야 합니다.

ACL(Access Control List)은 흔히 TCAM(Ternary Content Addressable Memory)으로 구현합니다. TCAM은 여러 region으로 나눌 수 있고, 복잡한 TC filter에는 priority와 lookup key가 다른 여러 rule이 들어갈 수 있습니다. 반면 hardware TCAM region의 lookup key는 미리 정해져 있습니다.

따라서 TCAM engine으로 TC filter rule을 offload하면 여러 TCAM region이 chain으로 연결될 수 있으며, 이는 data path latency에 영향을 줄 수 있습니다. 새로운 TC filter에 대응해 그 region들을 설명하는 table도 새로 만들어져야 합니다.

Overview
========

The ``devlink-dpipe`` interface closes this gap. The hardware's pipeline is
modeled as a graph of match/action tables. Each table represents a specific
hardware block. This model is not new, first being used by the P4 language.

Traditionally it has been used as an alternative model for hardware
configuration, but the ``devlink-dpipe`` interface uses it for visibility
purposes as a standard complementary tool. The system's view from
``devlink-dpipe`` should change according to the changes done by the
standard configuration tools.

For example, it’s quite common to  implement Access Control Lists (ACL)
using Ternary Content Addressable Memory (TCAM). The TCAM memory can be
divided into TCAM regions. Complex TC filters can have multiple rules with
different priorities and different lookup keys. On the other hand hardware
TCAM regions have a predefined lookup key. Offloading the TC filter rules
using TCAM engine can result in multiple TCAM regions being interconnected
in a chain (which may affect the data path latency). In response to a new TC
filter new tables should be created describing those regions.

DPIPE model과 table

Model

`DPIPE` model은 다음 object를 도입합니다.

• `headers`: packet 형식과 field 이름
• `tables`: hardware block
• `entries`: 특정 table의 실제 내용

`header`는 packet 형식을 설명하고 packet 안의 field에 이름을 부여합니다. `table`은 hardware block을 설명하고, `entry`는 특정 table의 실제 내용을 설명합니다.

hardware pipeline은 port별 구조가 아니라 ASIC 전체를 설명하므로 `devlink` infrastructure의 최상위에 연결됩니다.

driver는 동적인 동작을 지원하기 위해 runtime에 table을 등록하거나 해제할 수 있습니다. 동적으로 할당하고 해제할 수 있는 TCAM region 같은 hardware block을 설명하려면 이 기능이 반드시 필요합니다.

`devlink-dpipe`는 일반적으로 구성 용도가 아닙니다. 예외는 특정 table의 hardware counter를 제어하는 기능입니다.

userspace에서는 다음 command로 `dpipe` object를 가져옵니다.

Table

driver는 각 table에 대해 다음 operation을 구현해야 합니다.

Model
=====

The ``DPIPE`` model introduces several objects:

  * headers
  * tables
  * entries

A ``header`` describes packet formats and provides names for fields within
the packet. A ``table`` describes hardware blocks. An ``entry`` describes
the actual content of a specific table.

The hardware pipeline is not port specific, but rather describes the whole
ASIC. Thus it is tied to the top of the ``devlink`` infrastructure.

Drivers can register and unregister tables at run time, in order to support
dynamic behavior. This dynamic behavior is mandatory for describing hardware
blocks like TCAM regions which can be allocated and freed dynamically.

``devlink-dpipe`` generally is not intended for configuration. The exception
is hardware counting for a specific table.

The following commands are used to obtain the ``dpipe`` objects from
userspace:

  * ``table_get``: Receive a table's description.
  * ``headers_get``: Receive a device's supported headers.
  * ``entries_get``: Receive a table's current entries.
  * ``counters_set``: Enable or disable counters on a table.

Table
-----

The driver should implement the following operations for each table:

  * ``matches_dump``: Dump the supported matches.
  * ``actions_dump``: Dump the supported actions.
  * ``entries_dump``: Dump the actual content of the table.
  * ``counters_set_update``: Synchronize hardware with counters enabled or
    disabled.

Header, field와 match

Header/Field

P4와 마찬가지로 header와 field를 사용해 table 동작을 설명합니다. 표준 protocol header와 ASIC 전용 metadata는 구분해야 합니다. protocol header는 `devlink` core API에 선언하고, ASIC metadata는 driver에 정의합니다.

각 driver 전용 devlink 문서는 자신이 구현하는 driver 전용 `dpipe` header도 문서화해야 합니다. header와 field는 enumeration으로 식별합니다.

가시성을 더 높이기 위해 일부 ASIC metadata field를 kernel object에 mapping할 수 있습니다. 예를 들어 내부 router interface index를 net device ifindex에 직접 mapping하고, 서로 다른 VRF(Virtual Routing and Forwarding) table이 사용하는 FIB table index를 내부 routing table index에 mapping할 수 있습니다.

Match

match는 단순한 형태를 유지하며 hardware operation에 가깝게 표현합니다. LPM 같은 match type은 지원하지 않습니다. 바로 그 처리 과정을 세부적으로 드러내는 것이 DPIPE의 목적이기 때문입니다.

특정 field를 식별하려면 header ID와 field ID를 지정해야 합니다. tunneling packet처럼 같은 type의 header가 여러 개 있을 때 구분할 수 있도록 header index도 지정해야 합니다.

Header/Field
------------

In a similar way to P4 headers and fields are used to describe a table's
behavior. There is a slight difference between the standard protocol headers
and specific ASIC metadata. The protocol headers should be declared in the
``devlink`` core API. On the other hand ASIC meta data is driver specific
and should be defined in the driver. Additionally, each driver-specific
devlink documentation file should document the driver-specific ``dpipe``
headers it implements. The headers and fields are identified by enumeration.

In order to provide further visibility some ASIC metadata fields could be
mapped to kernel objects. For example, internal router interface indexes can
be directly mapped to the net device ifindex. FIB table indexes used by
different Virtual Routing and Forwarding (VRF) tables can be mapped to
internal routing table indexes.

Match
-----

Matches are kept primitive and close to hardware operation. Match types like
LPM are not supported due to the fact that this is exactly a process we wish
to describe in full detail. Example of matches:

  * ``field_exact``: Exact match on a specific field.
  * ``field_exact_mask``: Exact match on a specific field after masking.
  * ``field_range``: Match on a specific range.

The id's of the header and the field should be specified in order to
identify the specific field. Furthermore, the header index should be
specified in order to distinguish multiple headers of the same type in a
packet (tunneling).

Action과 entry

Action

match와 마찬가지로 action도 단순한 형태를 유지하며 hardware operation에 가깝게 표현합니다.

Entry

특정 table의 entry는 요청할 때 dump할 수 있습니다. 각 entry는 index로 식별하며, 그 속성은 match/action 값 목록과 해당 counter로 설명합니다. table 내용을 dump하면 table 사이의 상호 작용을 파악할 수 있습니다.

Action
------

Similar to match, the actions are kept primitive and close to hardware
operation. For example:

  * ``field_modify``: Modify the field value.
  * ``field_inc``: Increment the field value.
  * ``push_header``: Add a header.
  * ``pop_header``: Remove a header.

Entry
-----

Entries of a specific table can be dumped on demand. Each eentry is
identified with an index and its properties are described by a list of
match/action values and specific counter. By dumping the tables content the
interactions between tables can be resolved.

추상화 예제와 LPM

추상화 예제

다음은 Mellanox Spectrum ASIC의 L3 부분을 추상화한 예입니다. block은 pipeline에 나타나는 순서대로 설명합니다. 예제의 table 크기는 실제 hardware 크기가 아니라 설명을 위한 값입니다.

LPM

LPM 알고리즘은 hash table 목록으로 구현할 수 있습니다. 각 hash table에는 prefix 길이가 같은 route가 들어갑니다. 목록의 root는 `/32`이고, miss가 발생하면 hardware가 다음 hash table로 진행합니다. 검색 깊이는 data path latency에 영향을 줍니다.

hit한 entry에는 MAC address를 해석하는 다음 pipeline stage의 정보가 들어 있습니다. 다음 stage는 직접 연결된 route를 위한 local host table이거나 next-hop을 위한 adjacency table입니다. 두 LPM table은 `meta.lpm_prefix` field로 연결합니다.

table lpm_prefix_16 {
  size: 4096,
  counters_enabled: true,
  match: { meta.vr_id: exact,
           ipv4.dst_addr: exact_mask,
           ipv6.dst_addr: exact_mask,
           meta.lpm_prefix: exact },
  action: { meta.adj_index: set,
            meta.adj_group_size: set,
            meta.rif_port: set,
            meta.lpm_prefix: set },
}

Abstraction Example
===================

The following is an example of the abstraction model of the L3 part of
Mellanox Spectrum ASIC. The blocks are described in the order they appear in
the pipeline. The table sizes in the following examples are not real
hardware sizes and are provided for demonstration purposes.

LPM
---

The LPM algorithm can be implemented as a list of hash tables. Each hash
table contains routes with the same prefix length. The root of the list is
/32, and in case of a miss the hardware will continue to the next hash
table. The depth of the search will affect the data path latency.

In case of a hit the entry contains information about the next stage of the
pipeline which resolves the MAC address. The next stage can be either local
host table for directly connected routes, or adjacency table for next-hops.
The ``meta.lpm_prefix`` field is used to connect two LPM tables.

.. code::

    table lpm_prefix_16 {
      size: 4096,
      counters_enabled: true,
      match: { meta.vr_id: exact,
               ipv4.dst_addr: exact_mask,
               ipv6.dst_addr: exact_mask,
               meta.lpm_prefix: exact },
      action: { meta.adj_index: set,
                meta.adj_group_size: set,
                meta.rif_port: set,
                meta.lpm_prefix: set },
    }

Local host와 adjacency table

Local Host

local route에서는 LPM lookup이 egress router interface(RIF)를 이미 결정하지만 정확한 MAC address는 아직 알 수 없습니다. local host table은 output interface ID와 destination IP address를 key로 결합하는 hash table이며, 결과는 MAC address입니다.

table local_host {
  size: 4096,
  counters_enabled: true,
  match: { meta.rif_port: exact,
           ipv4.dst_addr: exact},
  action: { ethernet.daddr: set }
}

Adjacency

remote route에서는 이 table이 ECMP를 수행합니다. LPM lookup 결과로 얻은 ECMP group size와 index는 이 table의 global offset이 됩니다. 동시에 packet hash를 생성하며, ECMP group size와 packet hash를 바탕으로 local offset을 만듭니다. 여러 LPM entry가 같은 adjacency group을 가리킬 수 있습니다.

table adjacency {
  size: 4096,
  counters_enabled: true,
  match: { meta.adj_index: exact,
           meta.adj_group_size: exact,
           meta.packet_hash_index: exact },
  action: { ethernet.daddr: set,
            meta.erif: set }
}

Local Host
----------

In the case of local routes the LPM lookup already resolves the egress
router interface (RIF), yet the exact MAC address is not known. The local
host table is a hash table combining the output interface id with
destination IP address as a key. The result is the MAC address.

.. code::

    table local_host {
      size: 4096,
      counters_enabled: true,
      match: { meta.rif_port: exact,
               ipv4.dst_addr: exact},
      action: { ethernet.daddr: set }
    }

Adjacency
---------

In case of remote routes this table does the ECMP. The LPM lookup results in
ECMP group size and index that serves as a global offset into this table.
Concurrently a hash of the packet is generated. Based on the ECMP group size
and the packet's hash a local offset is generated. Multiple LPM entries can
point to the same adjacency group.

.. code::

    table adjacency {
      size: 4096,
      counters_enabled: true,
      match: { meta.adj_index: exact,
               meta.adj_group_size: exact,
               meta.packet_hash_index: exact },
      action: { ethernet.daddr: set,
                meta.erif: set }
    }

ERIF table

ERIF

이전 table에서 egress RIF와 destination MAC을 결정한 경우, 이 table은 TTL 감소와 MTU 검사 같은 여러 operation을 수행합니다. 그런 다음 forward 또는 drop을 결정하고, packet type인 broadcast, unicast, multicast에 따라 port L3 statistic을 갱신합니다.

table erif {
  size: 800,
  counters_enabled: true,
  match: { meta.rif_port: exact,
           meta.is_l3_unicast: exact,
           meta.is_l3_broadcast: exact,
           meta.is_l3_multicast, exact },
  action: { meta.l3_drop: set,
            meta.l3_forward: set }
}

ERIF
----

In case the egress RIF and destination MAC have been resolved by previous
tables this table does multiple operations like TTL decrease and MTU check.
Then the decision of forward/drop is taken and the port L3 statistics are
updated based on the packet's type (broadcast, unicast, multicast).

.. code::

    table erif {
      size: 800,
      counters_enabled: true,
      match: { meta.rif_port: exact,
               meta.is_l3_unicast: exact,
               meta.is_l3_broadcast: exact,
               meta.is_l3_multicast, exact },
      action: { meta.l3_drop: set,
                meta.l3_forward: set }
    }