DPAA2 Ethernet driver

지원 플랫폼과 DPAA2 네트워크 아키텍처

이 문서는 `GPL-2.0` 라이선스를 따르며 `isonum.txt`를 포함해 저작권 기호를 사용합니다. 저작권은 © 2017-2018 NXP에 있습니다.

DPAA2 Ethernet 드라이버

이 파일은 Freescale DPAA2 Ethernet 드라이버를 설명합니다.

지원 플랫폼

이 드라이버는 `LS2080A`, `LS2088A`, `LS1088A` 같은 Freescale DPAA2 SoC에 네트워킹 기능을 제공합니다.

아키텍처 개요

일반 NIC와 달리 DPAA2 아키텍처에는 네트워크 인터페이스 전체를 나타내는 단일 하드웨어 블록이 없습니다. 서로 분리된 여러 하드웨어 자원이 함께 네트워킹 기능을 구성합니다.

• 네트워크 인터페이스
• 큐와 채널
• 버퍼 풀
• MAC/PHY

모든 하드웨어 자원은 Management Complex(`MC`) portal을 통해 할당하고 구성합니다. MC는 대부분의 자원을 DPAA2 객체로 추상화하고, 이 객체를 구성하고 제어할 ABI를 노출합니다.

큐 같은 일부 하드웨어 자원에는 대응하는 MC 객체가 없습니다. 이런 자원은 다른 객체의 내부 자원으로 취급합니다.

DPAA2 아키텍처와 객체 추상화에 대한 자세한 설명은 `Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst`를 참고하십시오.

.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>

===============================
DPAA2 Ethernet driver
===============================

:Copyright: |copy| 2017-2018 NXP

This file provides documentation for the Freescale DPAA2 Ethernet driver.

Supported Platforms
===================
This driver provides networking support for Freescale DPAA2 SoCs, e.g.
LS2080A, LS2088A, LS1088A.


Architecture Overview
=====================
Unlike regular NICs, in the DPAA2 architecture there is no single hardware block
representing network interfaces; instead, several separate hardware resources
concur to provide the networking functionality:

- network interfaces
- queues, channels
- buffer pools
- MAC/PHY

All hardware resources are allocated and configured through the Management
Complex (MC) portals. MC abstracts most of these resources as DPAA2 objects
and exposes ABIs through which they can be configured and controlled. A few
hardware resources, like queues, do not have a corresponding MC object and
are treated as internal resources of other objects.

For a more detailed description of the DPAA2 architecture and its object
abstractions see
*Documentation/networking/device_drivers/ethernet/freescale/dpaa2/overview.rst*.

net device 구성 인터페이스와 DPAA2 객체

각 Linux net device는 Datapath Network Interface(`DPNI`) 객체를 기반으로 구성되며 Buffer Pool(`DPBP`), I/O Portal(`DPIO`), Concentrator(`DPCON`) 객체를 사용합니다.

구성 인터페이스

DPNI는 PHY와 직접 일대일로 대응하지 않는 네트워크 인터페이스입니다. DPBP는 하드웨어 버퍼 풀을 나타냅니다.

패킷 I/O는 DPCON 객체의 context에서 수행하며, 하드웨어 자원을 관리하고 통신할 때 DPIO portal을 사용합니다.

Each Linux net device is built on top of a Datapath Network Interface (DPNI)
object and uses Buffer Pools (DPBPs), I/O Portals (DPIOs) and Concentrators
(DPCONs).

Configuration interface::

                 -----------------------
                | DPAA2 Ethernet Driver |
                 -----------------------
                     .      .      .
                     .      .      .
             . . . . .      .      . . . . . .
             .              .                .
             .              .                .
         ----------     ----------      -----------
        | DPBP API |   | DPNI API |    | DPCON API |
         ----------     ----------      -----------
             .              .                .             software
    =======  .  ==========  .  ============  .  ===================
             .              .                .             hardware
         ------------------------------------------
        |            MC hardware portals           |
         ------------------------------------------
             .              .                .
             .              .                .
          ------         ------            -------
         | DPBP |       | DPNI |          | DPCON |
          ------         ------            -------

The DPNIs are network interfaces without a direct one-on-one mapping to PHYs.
DPBPs represent hardware buffer pools. Packet I/O is performed in the context
of DPCON objects, using DPIO portals for managing and communicating with the
hardware resources.

데이터 경로, 큐·채널 알림과 버퍼 풀

데이터 경로(I/O) 인터페이스

Datapath I/O(`DPIO`) portal은 enqueue·dequeue 서비스, 데이터 가용성 알림, 버퍼 풀 관리를 제공합니다.

DPIO는 데이터 프레임을 다루는 모든 DPAA2 객체, 따라서 모든 DPAA2 커널 드라이버가 공유합니다. 다만 트래픽 분산을 위해 각 DPIO에는 CPU affinity를 설정해야 합니다.

프레임은 하드웨어 frame queue를 통해 송수신합니다. 하드웨어 scheduling을 위해 여러 큐를 channel로 묶을 수 있습니다.

Ethernet 드라이버는 송신 프레임을 egress queue에 enqueue합니다. 송신이 끝나면 Tx confirmation frame이 CPU로 돌아옵니다.

ingress queue에 프레임이 도착하면 CPU에 데이터 가용성 알림을 보냅니다. 알림은 channel 단위로 발생하므로 같은 channel의 여러 큐에 프레임이 있어도 알림은 하나만 전송됩니다.

channel이 알림을 한 번 발생시킨 뒤에는 반드시 명시적으로 rearm해야 합니다.

각 네트워크 인터페이스는 CPU에 affinity가 설정된 여러 Rx, Tx, confirmation queue를 가질 수 있습니다. 하나 이상의 큐를 처리하는 CPU마다 channel, 즉 DPCON 하나를 둡니다.

DPCON은 각 core에 affinity가 설정된 DPIO를 통해 ingress 트래픽을 여러 CPU로 분산합니다.

하드웨어 버퍼 풀은 ingress frame 데이터를 저장합니다. 각 네트워크 인터페이스는 자신이 단독 소유하는 버퍼 풀을 하나 가지며, 커널이 할당한 버퍼로 그 풀을 채웁니다.

Datapath (I/O) interface::

         -----------------------------------------------
        |           DPAA2 Ethernet Driver               |
         -----------------------------------------------
          |          ^        ^         |            |
          |          |        |         |            |
   enqueue|   dequeue|   data |  dequeue|       seed |
    (Tx)  | (Rx, TxC)|  avail.|  request|     buffers|
          |          |  notify|         |            |
          |          |        |         |            |
          V          |        |         V            V
         -----------------------------------------------
        |                 DPIO Driver                   |
         -----------------------------------------------
          |          |        |         |            |          software
          |          |        |         |            |  ================
          |          |        |         |            |          hardware
         -----------------------------------------------
        |               I/O hardware portals            |
         -----------------------------------------------
          |          ^        ^         |            |
          |          |        |         |            |
          |          |        |         V            |
          V          |    ================           V
        ----------------------           |      -------------
 queues  ----------------------          |     | Buffer pool |
          ----------------------         |      -------------
                   =======================
                                Channel

Datapath I/O (DPIO) portals provide enqueue and dequeue services, data
availability notifications and buffer pool management. DPIOs are shared between
all DPAA2 objects (and implicitly all DPAA2 kernel drivers) that work with data
frames, but must be affine to the CPUs for the purpose of traffic distribution.

Frames are transmitted and received through hardware frame queues, which can be
grouped in channels for the purpose of hardware scheduling. The Ethernet driver
enqueues TX frames on egress queues and after transmission is complete a TX
confirmation frame is sent back to the CPU.

When frames are available on ingress queues, a data availability notification
is sent to the CPU; notifications are raised per channel, so even if multiple
queues in the same channel have available frames, only one notification is sent.
After a channel fires a notification, is must be explicitly rearmed.

Each network interface can have multiple Rx, Tx and confirmation queues affined
to CPUs, and one channel (DPCON) for each CPU that services at least one queue.
DPCONs are used to distribute ingress traffic to different CPUs via the cores'
affine DPIOs.

The role of hardware buffer pools is storage of ingress frame data. Each network
interface has a privately owned buffer pool which it seeds with kernel allocated
buffers.

DPNI 연결 구조와 네트워크 인터페이스 생성

DPNI와 PHY는 분리되어 있습니다. DPNI는 DPMAC 객체를 통해 PHY에 연결할 수도 있고 내부 link를 통해 다른 DPNI에 연결할 수도 있습니다.

이 연결은 MC가 관리하며 Ethernet 드라이버에는 완전히 투명합니다.

네트워크 인터페이스 생성

MC bus에서 probe한 DPNI 객체마다 net device 하나를 생성합니다. 각 DPNI에는 네트워크 인터페이스의 구성 옵션과 연관 하드웨어 자원을 결정하는 여러 속성이 있습니다.

DPNI 객체와 네트워크 인터페이스에 필요한 다른 DPAA2 객체는 두 방법 중 하나로 MC bus의 container에 추가할 수 있습니다.

• 정적 생성: 부팅할 때 MC가 parsing하는 Datapath Layout Binary(`DPL`) 파일 사용
• 동적 생성: 실행 중 DPAA2 object API 사용

DPNIs are decoupled from PHYs; a DPNI can be connected to a PHY through a DPMAC
object or to another DPNI through an internal link, but the connection is
managed by MC and completely transparent to the Ethernet driver.

::

     ---------     ---------     ---------
    | eth if1 |   | eth if2 |   | eth ifn |
     ---------     ---------     ---------
          .           .          .
          .           .          .
          .           .          .
         ---------------------------
        |   DPAA2 Ethernet Driver   |
         ---------------------------
          .           .          .
          .           .          .
          .           .          .
       ------      ------      ------            -------
      | DPNI |    | DPNI |    | DPNI |          | DPMAC |----+
       ------      ------      ------            -------     |
         |           |           |                  |        |
         |           |           |                  |      -----
          ===========             ==================      | PHY |
                                                           -----

Creating a Network Interface
============================
A net device is created for each DPNI object probed on the MC bus. Each DPNI has
a number of properties which determine the network interface configuration
options and associated hardware resources.

DPNI objects (and the other DPAA2 objects needed for a network interface) can be
added to a container on the MC bus in one of two ways: statically, through a
Datapath Layout Binary file (DPL) that is parsed by MC at boot time; or created
dynamically at runtime, via the DPAA2 objects APIs.

기능, 오프로딩과 통계

기능과 오프로딩

IPv4/IPv6의 TCP와 UDP 프레임에 대해 하드웨어 checksum offloading을 지원합니다. RX와 TX의 checksum offload는 ethtool로 각각 독립적으로 구성할 수 있습니다.

ingress 경로에서 unicast와 multicast MAC filtering의 하드웨어 offload를 지원하며 이 기능은 항상 활성화됩니다.

RX와 TX 경로 모두 scatter-gather frame을 지원합니다. TX의 SG 지원은 ethtool로 구성할 수 있고 RX에서는 항상 활성화됩니다.

DPAA2 하드웨어는 최대 10K bytes의 jumbo Ethernet frame을 처리할 수 있습니다.

Ethernet 드라이버는 출발지 IP, 목적지 IP, IP protocol, L4 출발지 port, L4 목적지 port로 구성된 5-tuple key를 이용하는 고정 flow hashing 방식을 정의합니다. 현재 사용자 구성은 지원하지 않습니다.

네트워크 인터페이스의 하드웨어별 통계와 일부 비표준 드라이버 통계는 `ethtool -S` 옵션으로 확인할 수 있습니다.

Features & Offloads
===================
Hardware checksum offloading is supported for TCP and UDP over IPv4/6 frames.
The checksum offloads can be independently configured on RX and TX through
ethtool.

Hardware offload of unicast and multicast MAC filtering is supported on the
ingress path and permanently enabled.

Scatter-gather frames are supported on both RX and TX paths. On TX, SG support
is configurable via ethtool; on RX it is always enabled.

The DPAA2 hardware can process jumbo Ethernet frames of up to 10K bytes.

The Ethernet driver defines a static flow hashing scheme that distributes
traffic based on a 5-tuple key: src IP, dst IP, IP proto, L4 src port,
L4 dst port. No user configuration is supported for now.

Hardware specific statistics for the network interface as well as some
non-standard driver stats can be consulted through ethtool -S option.