HiSilicon PCIe PTT 튜닝 및 추적

HiSilicon PCIe PTT 소개

이 문서는 GPL-2.0으로 배포되는 `HiSilicon PCIe Tune and Trace device` 안내서다.

HiSilicon PCIe 튜닝 및 추적 장치(PTT)는 PCIe Root Complex 통합 Endpoint(RCiEP) 장치다. PCIe 링크의 이벤트를 동적으로 감시하고 조정하는 튜닝 기능과 TLP 헤더를 기록하는 추적 기능을 제공한다. 두 기능은 서로 독립적이지만, PCIe 링크 성능을 분석하고 개선할 때 함께 사용하는 것이 권장된다.

Kunpeng 930 SoC의 PCIe Root Complex는 여러 PCIe 코어로 구성된다. 각 코어에는 여러 Root Port와 하나의 PTT RCiEP가 있으며, PTT 장치는 자신이 속한 코어의 링크를 튜닝하고 추적할 수 있다.

PTT 장치 드라이버는 PTT 장치마다 하나의 PMU 장치를 등록한다. 각 장치 이름은 `hisi_ptt` 접두사 뒤에 장치가 위치한 SICL ID와 Core ID를 붙여 구성한다. Kunpeng 930 SoC는 여러 CPU 다이인 SCCL(Super CPU Cluster)과 여러 I/O 다이인 SICL(Super I/O Cluster)을 포함하며, SICL마다 PCIe Root Complex 하나가 있다.

    /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>

.. SPDX-License-Identifier: GPL-2.0

======================================
HiSilicon PCIe Tune and Trace device
======================================

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

HiSilicon PCIe tune and trace device (PTT) is a PCIe Root Complex
integrated Endpoint (RCiEP) device, providing the capability
to dynamically monitor and tune the PCIe link's events (tune),
and trace the TLP headers (trace). The two functions are independent,
but is recommended to use them together to analyze and enhance the
PCIe link's performance.

On Kunpeng 930 SoC, the PCIe Root Complex is composed of several
PCIe cores. Each PCIe core includes several Root Ports and a PTT
RCiEP, like below. The PTT device is capable of tuning and
tracing the links of the PCIe core.
::

          +--------------Core 0-------+
          |       |       [   PTT   ] |
          |       |       [Root Port]---[Endpoint]
          |       |       [Root Port]---[Endpoint]
          |       |       [Root Port]---[Endpoint]
    Root Complex  |------Core 1-------+
          |       |       [   PTT   ] |
          |       |       [Root Port]---[ Switch ]---[Endpoint]
          |       |       [Root Port]---[Endpoint] `-[Endpoint]
          |       |       [Root Port]---[Endpoint]
          +---------------------------+

The PTT device driver registers one PMU device for each PTT device.
The name of each PTT device is composed of 'hisi_ptt' prefix with
the id of the SICL and the Core where it locates. The Kunpeng 930
SoC encapsulates multiple CPU dies (SCCL, Super CPU Cluster) and
IO dies (SICL, Super I/O Cluster), where there's one PCIe Root
Complex for each SICL.
::

    /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>

PTT 튜닝 인터페이스

PTT 튜닝은 PCIe 링크 매개변수, 즉 이벤트를 감시하고 조정하기 위한 기능이다. 현재 두 클래스의 이벤트를 지원하며, 이벤트 범위는 PTT 장치가 속한 PCIe 코어 전체다.

각 이벤트는 `$(PTT PMU dir)/tune` 아래의 파일 하나로 제공된다. 파일을 열고 읽거나 쓴 뒤 닫는 단순한 주기로 현재 값을 확인하고 원하는 값으로 조정한다.

    $ cd /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>/tune
    $ ls
    qos_tx_cpl    qos_tx_np    qos_tx_p
    tx_path_rx_req_alloc_buf_level
    tx_path_tx_req_alloc_buf_level
    $ cat qos_tx_dp
    1
    $ echo 2 > qos_tx_dp
    $ cat qos_tx_dp
    2

이벤트 파일에서 현재 수치 값을 읽을 수 있고, 원하는 수치 값을 같은 파일에 쓰면 해당 이벤트가 조정된다. 위 예시의 명령과 파일 이름은 원문 표기를 그대로 보존한다.

Tune
====

PTT tune is designed for monitoring and adjusting PCIe link parameters (events).
Currently we support events in 2 classes. The scope of the events
covers the PCIe core to which the PTT device belongs.

Each event is presented as a file under $(PTT PMU dir)/tune, and
a simple open/read/write/close cycle will be used to tune the event.
::

    $ cd /sys/bus/event_source/devices/hisi_ptt<sicl_id>_<core_id>/tune
    $ ls
    qos_tx_cpl    qos_tx_np    qos_tx_p
    tx_path_rx_req_alloc_buf_level
    tx_path_tx_req_alloc_buf_level
    $ cat qos_tx_dp
    1
    $ echo 2 > qos_tx_dp
    $ cat qos_tx_dp
    2

Current value (numerical value) of the event can be simply read
from the file, and the desired value written to the file to tune.

Tx 경로 QoS 제어

다음 파일은 PCIe 코어 Tx 경로의 QoS를 조정한다.

가중치는 특정 패킷이 PCIe 링크에서 차지하는 비율에 영향을 준다. 예를 들어 storage 시나리오에서는 completion 소비가 많으므로 링크에서 completion 패킷 비율을 높여 성능을 향상할 수 있다.

사용 가능한 튜닝 값은 `[0, 1, 2]`다. 음수를 쓰면 오류가 반환되고 범위를 벗어난 값은 `2`로 변환된다. 이벤트 값은 개략적인 수준을 나타낼 뿐 정밀한 양을 뜻하지 않는다.

1. Tx Path QoS Control
------------------------

The following files are provided to tune the QoS of the tx path of
the PCIe core.

- qos_tx_cpl: weight of Tx completion TLPs
- qos_tx_np: weight of Tx non-posted TLPs
- qos_tx_p: weight of Tx posted TLPs

The weight influences the proportion of certain packets on the PCIe link.
For example, for the storage scenario, increase the proportion
of the completion packets on the link to enhance the performance as
more completions are consumed.

The available tune data of these events is [0, 1, 2].
Writing a negative value will return an error, and out of range
values will be converted to 2. Note that the event value just
indicates a probable level, but is not precise.

Tx 경로 버퍼 제어

다음 파일은 PCIe 코어 Tx 경로의 버퍼를 조정한다.

이 이벤트는 각 유형에 할당되는 버퍼의 watermark에 영향을 준다. 패킷은 먼저 버퍼에 저장되며, watermark에 도달하거나 timeout이 발생하면 전송된다. 트래픽이 많은 방향에서는 관련 watermark를 높여 너무 잦은 전송을 피하고 성능을 개선할 수 있다. 다만 대부분의 경우 기본값을 유지하면 된다.

사용 가능한 값은 `[0, 1, 2]`다. 음수는 오류를 반환하고 범위를 벗어난 값은 `2`로 변환된다. 이 값 역시 정확한 수치가 아니라 개략적인 수준을 나타낸다.

2. Tx Path Buffer Control
-------------------------

Following files are provided to tune the buffer of tx path of the PCIe core.

- rx_alloc_buf_level: watermark of Rx requested
- tx_alloc_buf_level: watermark of Tx requested

These events influence the watermark of the buffer allocated for each
type. Rx means the inbound while Tx means outbound. The packets will
be stored in the buffer first and then transmitted either when the
watermark reached or when timed out. For a busy direction, you should
increase the related buffer watermark to avoid frequently posting and
thus enhance the performance. In most cases just keep the default value.

The available tune data of above events is [0, 1, 2].
Writing a negative value will return an error, and out of range
values will be converted to 2. Note that the event value just
indicates a probable level, but is not precise.

TLP 헤더 추적

PTT 추적은 TLP 헤더를 메모리에 덤프하여 PCIe 링크의 transaction과 사용 상태를 분석하는 기능이다. Requester ID 또는 PTT 장치와 같은 코어에 있는 Root Port 집합의 downstream을 기준으로 헤더를 필터링할 수 있고, 특정 유형과 방향도 선택할 수 있다.

`perf record`로 매개변수를 설정하고 추적을 시작해 데이터를 얻으며, `perf report`로 추적 데이터를 디코딩할 수 있다. 각 추적 제어 매개변수는 perf event 코드로 입력한다.

    $ perf record -e hisi_ptt0_2/filter=0x80001,type=1,direction=1,
      format=1/ -- sleep 5

이 명령은 downstream Root Port `0000:00:10.1`의 TLP 헤더를 추적한다. `filter` 이벤트 코드는 `0x80001`, 유형은 posted TLP request, 방향은 inbound, 데이터 형식은 8DW다.

Trace
=====

PTT trace is designed for dumping the TLP headers to the memory, which
can be used to analyze the transactions and usage condition of the PCIe
Link. You can choose to filter the traced headers by either Requester ID,
or those downstream of a set of Root Ports on the same core of the PTT
device. It's also supported to trace the headers of certain type and of
certain direction.

You can use the perf command `perf record` to set the parameters, start
trace and get the data. It's also supported to decode the trace
data with `perf report`. The control parameters for trace is inputted
as event code for each events, which will be further illustrated later.
An example usage is like
::

    $ perf record -e hisi_ptt0_2/filter=0x80001,type=1,direction=1,
      format=1/ -- sleep 5

This will trace the TLP headers downstream root port 0000:00:10.1 (event
code for event 'filter' is 0x80001) with type of posted TLP requests,
direction of inbound and traced data format of 8DW.

추적 필터

추적할 TLP 헤더는 PTT 장치와 같은 코어에 있는 Root Port 또는 Endpoint의 Requester ID로 필터링한다. 필수 `filter` 매개변수는 20비트 값이다.

Root Port 값은 core port ID의 mask이며 PCI Slot ID로부터 `(slotid & 7) * 2`로 계산한다. Requester 값은 해당 PCIe function의 Device ID인 Requester ID다.

Endpoint function `0000:01:00.1`을 지정하면 필터 값은 `0x00101`이다. Root Port `0000:00:10.0`을 지정하면 원문 계산 결과는 `0x80001`이다.

드라이버는 지원하는 모든 Root Port와 Requester 필터를 sysfs에도 노출한다. 각 필터는 관련 PCIe 장치 이름인 `domain:bus:device.function`을 파일 이름으로 사용한다. Root Port 필터는 `$(PTT PMU dir)/root_port_filters`, Requester 필터는 `$(PTT PMU dir)/requester_filters` 아래에 있다.

한 번에 여러 Root Port를 지정할 수 있지만 한 번의 추적에는 Endpoint function 하나만 지정할 수 있다. Root Port와 function을 동시에 지정하는 것은 지원하지 않는다. 드라이버는 사용 가능한 필터 목록을 유지하고 잘못된 입력을 검사한다.

사용 가능한 필터는 동적으로 갱신되므로 hotplug가 발생하거나 장치를 수동으로 제거한 뒤 rescan해도 현재 장치 상태에 맞는 필터 정보를 얻는다.

1. Filter
---------

The TLP headers to trace can be filtered by the Root Ports or the Requester ID
of the Endpoint, which are located on the same core of the PTT device. You can
set the filter by specifying the `filter` parameter which is required to start
the trace. The parameter value is 20 bit. Bit 19 indicates the filter type.
1 for Root Port filter and 0 for Requester filter. Bit[15:0] indicates the
filter value. The value for a Root Port is a mask of the core port id which is
calculated from its PCI Slot ID as (slotid & 7) * 2. The value for a Requester
is the Requester ID (Device ID of the PCIe function). Bit[18:16] is currently
reserved for extension.

For example, if the desired filter is Endpoint function 0000:01:00.1 the filter
value will be 0x00101. If the desired filter is Root Port 0000:00:10.0 then
then filter value is calculated as 0x80001.

The driver also presents every supported Root Port and Requester filter through
sysfs. Each filter will be an individual file with name of its related PCIe
device name (domain:bus:device.function). The files of Root Port filters are
under $(PTT PMU dir)/root_port_filters and files of Requester filters
are under $(PTT PMU dir)/requester_filters.

Note that multiple Root Ports can be specified at one time, but only one
Endpoint function can be specified in one trace. Specifying both Root Port
and function at the same time is not supported. Driver maintains a list of
available filters and will check the invalid inputs.

The available filters will be dynamically updated, which means you will always
get correct filter information when hotplug events happen, or when you manually
remove/rescan the devices.

추적 TLP 유형

필수 `type` 매개변수로 추적할 TLP 헤더 유형을 선택한다. 값의 폭은 8비트다.

inbound TLP 헤더를 추적할 때는 여러 유형을 지정할 수 있지만, outbound TLP 헤더를 추적할 때는 한 유형만 지정할 수 있다.

2. Type
-------

You can trace the TLP headers of certain types by specifying the `type`
parameter, which is required to start the trace. The parameter value is
8 bit. Current supported types and related values are shown below:

- 8'b00000001: posted requests (P)
- 8'b00000010: non-posted requests (NP)
- 8'b00000100: completions (CPL)

You can specify multiple types when tracing inbound TLP headers, but can only
specify one when tracing outbound TLP headers.

추적 방향

Root Port 또는 PCIe 코어를 기준으로 한 TLP 헤더 방향은 `direction` 매개변수로 지정한다. 이 매개변수는 선택 사항이며 기본값은 inbound다. 값의 폭은 4비트다.

inbound completion은 두 유형으로 나뉜다. completion A(CPL A)는 CPL B를 제외한 CHI/DMA/Native non-posted request의 completion이고, completion B(CPL B)는 DMA remote2local 및 P2P non-posted request의 completion이다.

3. Direction
------------

You can trace the TLP headers from certain direction, which is relative
to the Root Port or the PCIe core, by specifying the `direction` parameter.
This is optional and the default parameter is inbound. The parameter value
is 4 bit. When the desired format is 4DW, directions and related values
supported are shown below:

- 4'b0000: inbound TLPs (P, NP, CPL)
- 4'b0001: outbound TLPs (P, NP, CPL)
- 4'b0010: outbound TLPs (P, NP, CPL) and inbound TLPs (P, NP, CPL B)
- 4'b0011: outbound TLPs (P, NP, CPL) and inbound TLPs (CPL A)

When the desired format is 8DW, directions and related values supported are
shown below:

- 4'b0000: reserved
- 4'b0001: outbound TLPs (P, NP, CPL)
- 4'b0010: inbound TLPs (P, NP, CPL B)
- 4'b0011: inbound TLPs (CPL A)

Inbound completions are classified into two types:

- completion A (CPL A): completion of CHI/DMA/Native non-posted requests, except for CPL B
- completion B (CPL B): completion of DMA remote2local and P2P non-posted requests

추적 데이터 형식

`format` 매개변수로 추적한 TLP 헤더 형식을 바꿀 수 있다. 기본값은 4DW이고 값의 폭은 4비트다. `4'b0000`은 TLP 헤더당 4DW, `4'b0001`은 TLP 헤더당 8DW를 뜻한다. 기록되는 TLP 헤더 형식은 PCIe 표준 형식과 다르다.

8DW 데이터 형식은 전체 TLP 헤더인 Header DW0-3을 기록한다. 예를 들어 64비트 주소를 사용하는 Memory Read의 TLP 헤더는 PCIe r5.0 Figure 2-17, Configuration Request 헤더는 Figure 2.20에 정의되어 있다.

8DW trace buffer entry에는 timestamp와 선택적인 PASID TLP prefix도 들어간다. PASID TLP prefix는 PCIe r5.0 Figure 6-20을 참조하며, prefix가 없으면 해당 필드는 모두 `0`이다. DW0의 bit[31:11]은 항상 `0x1fffff`이므로 데이터 형식을 구분하는 표지로 사용할 수 있다.

4DW 데이터 형식에서는 trace buffer entry의 DW0에 TLP DW0에서 선택한 필드와 timestamp가 함께 들어간다. trace buffer entry의 DW1-DW3에는 TLP 헤더의 DW1-DW3가 그대로 들어간다.

4. Format
--------------

You can change the format of the traced TLP headers by specifying the
`format` parameter. The default format is 4DW. The parameter value is 4 bit.
Current supported formats and related values are shown below:

- 4'b0000: 4DW length per TLP header
- 4'b0001: 8DW length per TLP header

The traced TLP header format is different from the PCIe standard.

When using the 8DW data format, the entire TLP header is logged
(Header DW0-3 shown below). For example, the TLP header for Memory
Reads with 64-bit addresses is shown in PCIe r5.0, Figure 2-17;
the header for Configuration Requests is shown in Figure 2.20, etc.

In addition, 8DW trace buffer entries contain a timestamp and
possibly a prefix for a PASID TLP prefix (see Figure 6-20, PCIe r5.0).
Otherwise this field will be all 0.

The bit[31:11] of DW0 is always 0x1fffff, which can be
used to distinguish the data format. 8DW format is like
::

    bits [                 31:11                 ][       10:0       ]
         |---------------------------------------|-------------------|
     DW0 [                0x1fffff               ][ Reserved (0x7ff) ]
     DW1 [                       Prefix                              ]
     DW2 [                     Header DW0                            ]
     DW3 [                     Header DW1                            ]
     DW4 [                     Header DW2                            ]
     DW5 [                     Header DW3                            ]
     DW6 [                   Reserved (0x0)                          ]
     DW7 [                        Time                               ]

When using the 4DW data format, DW0 of the trace buffer entry
contains selected fields of DW0 of the TLP, together with a
timestamp.  DW1-DW3 of the trace buffer entry contain DW1-DW3
directly from the TLP header.

4DW format is like
::

    bits [31:30] [ 29:25 ][24][23][22][21][    20:11   ][    10:0    ]
         |-----|---------|---|---|---|---|-------------|-------------|
     DW0 [ Fmt ][  Type  ][T9][T8][TH][SO][   Length   ][    Time    ]
     DW1 [                     Header DW1                            ]
     DW2 [                     Header DW2                            ]
     DW3 [                     Header DW3                            ]

추적 메모리 관리

추적한 TLP 헤더는 드라이버가 할당한 메모리에 기록된다. 하드웨어는 크기가 같은 DMA 주소 네 개를 받아 버퍼에 순서대로 기록한다. DMA addr 3을 모두 쓴 뒤에도 추적이 계속되면 DMA addr 0으로 돌아간다.

드라이버는 각 DMA 버퍼를 4MiB로 할당한다. 완료된 버퍼는 perf core가 할당한 perf AUX 버퍼로 복사된다. 추적 중 AUX 버퍼가 가득 차면 드라이버가 먼저 AUX 버퍼를 commit하고 같은 크기의 새 버퍼를 요청한다. AUX 버퍼 기본 크기는 16MiB이며, 사용자는 perf 명령의 `-m` 매개변수로 크기를 조정할 수 있다.

5. Memory Management
--------------------

The traced TLP headers will be written to the memory allocated
by the driver. The hardware accepts 4 DMA address with same size,
and writes the buffer sequentially like below. If DMA addr 3 is
finished and the trace is still on, it will return to addr 0.
::

    +->[DMA addr 0]->[DMA addr 1]->[DMA addr 2]->[DMA addr 3]-+
    +---------------------------------------------------------+

Driver will allocate each DMA buffer of 4MiB. The finished buffer
will be copied to the perf AUX buffer allocated by the perf core.
Once the AUX buffer is full while the trace is still on, driver
will commit the AUX buffer first and then apply for a new one with
the same size. The size of AUX buffer is default to 16MiB. User can
adjust the size by specifying the `-m` parameter of the perf command.

추적 데이터 디코딩

`perf report -D` 명령으로 추적 데이터를 디코딩할 수 있다. 현재는 raw trace data 덤프만 지원한다. 데이터는 앞에서 설명한 형식에 따라 디코딩되며 다음은 8DW 예시다.

    [...perf headers and other information]
    . ... HISI PTT data: size 4194304 bytes
    .  00000000: 00 00 00 00                                 Prefix
    .  00000004: 01 00 00 60                                 Header DW0
    .  00000008: 0f 1e 00 01                                 Header DW1
    .  0000000c: 04 00 00 00                                 Header DW2
    .  00000010: 40 00 81 02                                 Header DW3
    .  00000014: 33 c0 04 00                                 Time
    .  00000020: 00 00 00 00                                 Prefix
    .  00000024: 01 00 00 60                                 Header DW0
    .  00000028: 0f 1e 00 01                                 Header DW1
    .  0000002c: 04 00 00 00                                 Header DW2
    .  00000030: 40 00 81 02                                 Header DW3
    .  00000034: 02 00 00 00                                 Time
    .  00000040: 00 00 00 00                                 Prefix
    .  00000044: 01 00 00 60                                 Header DW0
    .  00000048: 0f 1e 00 01                                 Header DW1
    .  0000004c: 04 00 00 00                                 Header DW2
    .  00000050: 40 00 81 02                                 Header DW3
    [...]

각 8DW entry는 Prefix, Header DW0-DW3, Time 순서로 표시된다. 출력의 byte offset과 16진수 값은 원문 예시를 그대로 보존했다.

6. Decoding
-----------

You can decode the traced data with `perf report -D` command (currently
only support to dump the raw trace data). The traced data will be decoded
according to the format described previously (take 8DW as an example):
::

    [...perf headers and other information]
    . ... HISI PTT data: size 4194304 bytes
    .  00000000: 00 00 00 00                                 Prefix
    .  00000004: 01 00 00 60                                 Header DW0
    .  00000008: 0f 1e 00 01                                 Header DW1
    .  0000000c: 04 00 00 00                                 Header DW2
    .  00000010: 40 00 81 02                                 Header DW3
    .  00000014: 33 c0 04 00                                 Time
    .  00000020: 00 00 00 00                                 Prefix
    .  00000024: 01 00 00 60                                 Header DW0
    .  00000028: 0f 1e 00 01                                 Header DW1
    .  0000002c: 04 00 00 00                                 Header DW2
    .  00000030: 40 00 81 02                                 Header DW3
    .  00000034: 02 00 00 00                                 Time
    .  00000040: 00 00 00 00                                 Prefix
    .  00000044: 01 00 00 60                                 Header DW0
    .  00000048: 0f 1e 00 01                                 Header DW1
    .  0000004c: 04 00 00 00                                 Header DW2
    .  00000050: 40 00 81 02                                 Header DW3
    [...]