Documentation/trace/hisi-ptt.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======================================
   4 HiSilicon PCIe Tune and Trace device
   5 ======================================
   6
   7 Introduction
   8 ============
   9
  10 HiSilicon PCIe tune and trace device (PTT) is a PCIe Root Complex
  11 integrated Endpoint (RCiEP) device, providing the capability
  12 to dynamically monitor and tune the PCIe link's events (tune),
  13 and trace the TLP headers (trace). The two functions are independent,
  14 but is recommended to use them together to analyze and enhance the
  15 PCIe link's performance.
  16
  17 On Kunpeng 930 SoC, the PCIe Root Complex is composed of several
  18 PCIe cores. Each PCIe core includes several Root Ports and a PTT
  19 RCiEP, like below. The PTT device is capable of tuning and
  20 tracing the links of the PCIe core.
  21 ::
  22
  23           +--------------Core 0-------+
  24           |       |       [   PTT   ] |
  25           |       |       [Root Port]---[Endpoint]
  26           |       |       [Root Port]---[Endpoint]
  27           |       |       [Root Port]---[Endpoint]
  28     Root Complex  |------Core 1-------+
  29           |       |       [   PTT   ] |
  30           |       |       [Root Port]---[ Switch ]---[Endpoint]
  31           |       |       [Root Port]---[Endpoint] `-[Endpoint]
  32           |       |       [Root Port]---[Endpoint]
  33           +---------------------------+
  34
  35 The PTT device driver registers one PMU device for each PTT device.
  36 The name of each PTT device is composed of 'hisi_ptt' prefix with
  37 the id of the SICL and the Core where it locates. The Kunpeng 930
  38 SoC encapsulates multiple CPU dies (SCCL, Super CPU Cluster) and
  39 IO dies (SICL, Super I/O Cluster), where there's one PCIe Root
  40 Complex for each SICL.
  41 ::
  42
  43     /sys/devices/hisi_ptt<sicl_id>_<core_id>
  44
  45 Tune
  46 ====
  47
  48 PTT tune is designed for monitoring and adjusting PCIe link parameters (events).
  49 Currently we support events in 2 classes. The scope of the events
  50 covers the PCIe core to which the PTT device belongs.
  51
  52 Each event is presented as a file under $(PTT PMU dir)/tune, and
  53 a simple open/read/write/close cycle will be used to tune the event.
  54 ::
  55
  56     $ cd /sys/devices/hisi_ptt<sicl_id>_<core_id>/tune
  57     $ ls
  58     qos_tx_cpl    qos_tx_np    qos_tx_p
  59     tx_path_rx_req_alloc_buf_level
  60     tx_path_tx_req_alloc_buf_level
  61     $ cat qos_tx_dp
  62     1
  63     $ echo 2 > qos_tx_dp
  64     $ cat qos_tx_dp
  65     2
  66
  67 Current value (numerical value) of the event can be simply read
  68 from the file, and the desired value written to the file to tune.
  69
  70 1. Tx Path QoS Control
  71 ------------------------
  72
  73 The following files are provided to tune the QoS of the tx path of
  74 the PCIe core.
  75
  76 - qos_tx_cpl: weight of Tx completion TLPs
  77 - qos_tx_np: weight of Tx non-posted TLPs
  78 - qos_tx_p: weight of Tx posted TLPs
  79
  80 The weight influences the proportion of certain packets on the PCIe link.
  81 For example, for the storage scenario, increase the proportion
  82 of the completion packets on the link to enhance the performance as
  83 more completions are consumed.
  84
  85 The available tune data of these events is [0, 1, 2].
  86 Writing a negative value will return an error, and out of range
  87 values will be converted to 2. Note that the event value just
  88 indicates a probable level, but is not precise.
  89
  90 2. Tx Path Buffer Control
  91 -------------------------
  92
  93 Following files are provided to tune the buffer of tx path of the PCIe core.
  94
  95 - rx_alloc_buf_level: watermark of Rx requested
  96 - tx_alloc_buf_level: watermark of Tx requested
  97
  98 These events influence the watermark of the buffer allocated for each
  99 type. Rx means the inbound while Tx means outbound. The packets will
 100 be stored in the buffer first and then transmitted either when the
 101 watermark reached or when timed out. For a busy direction, you should
 102 increase the related buffer watermark to avoid frequently posting and
 103 thus enhance the performance. In most cases just keep the default value.
 104
 105 The available tune data of above events is [0, 1, 2].
 106 Writing a negative value will return an error, and out of range
 107 values will be converted to 2. Note that the event value just
 108 indicates a probable level, but is not precise.
 109
 110 Trace
 111 =====
 112
 113 PTT trace is designed for dumping the TLP headers to the memory, which
 114 can be used to analyze the transactions and usage condition of the PCIe
 115 Link. You can choose to filter the traced headers by either Requester ID,
 116 or those downstream of a set of Root Ports on the same core of the PTT
 117 device. It's also supported to trace the headers of certain type and of
 118 certain direction.
 119
 120 You can use the perf command `perf record` to set the parameters, start
 121 trace and get the data. It's also supported to decode the trace
 122 data with `perf report`. The control parameters for trace is inputted
 123 as event code for each events, which will be further illustrated later.
 124 An example usage is like
 125 ::
 126
 127     $ perf record -e hisi_ptt0_2/filter=0x80001,type=1,direction=1,
 128       format=1/ -- sleep 5
 129
 130 This will trace the TLP headers downstream root port 0000:00:10.1 (event
 131 code for event 'filter' is 0x80001) with type of posted TLP requests,
 132 direction of inbound and traced data format of 8DW.
 133
 134 1. Filter
 135 ---------
 136
 137 The TLP headers to trace can be filtered by the Root Ports or the Requester ID
 138 of the Endpoint, which are located on the same core of the PTT device. You can
 139 set the filter by specifying the `filter` parameter which is required to start
 140 the trace. The parameter value is 20 bit. Bit 19 indicates the filter type.
 141 1 for Root Port filter and 0 for Requester filter. Bit[15:0] indicates the
 142 filter value. The value for a Root Port is a mask of the core port id which is
 143 calculated from its PCI Slot ID as (slotid & 7) * 2. The value for a Requester
 144 is the Requester ID (Device ID of the PCIe function). Bit[18:16] is currently
 145 reserved for extension.
 146
 147 For example, if the desired filter is Endpoint function 0000:01:00.1 the filter
 148 value will be 0x00101. If the desired filter is Root Port 0000:00:10.0 then
 149 then filter value is calculated as 0x80001.
 150
 151 Note that multiple Root Ports can be specified at one time, but only one
 152 Endpoint function can be specified in one trace. Specifying both Root Port
 153 and function at the same time is not supported. Driver maintains a list of
 154 available filters and will check the invalid inputs.
 155
 156 Currently the available filters are detected in driver's probe. If the supported
 157 devices are removed/added after probe, you may need to reload the driver to update
 158 the filters.
 159
 160 2. Type
 161 -------
 162
 163 You can trace the TLP headers of certain types by specifying the `type`
 164 parameter, which is required to start the trace. The parameter value is
 165 8 bit. Current supported types and related values are shown below:
 166
 167 - 8'b00000001: posted requests (P)
 168 - 8'b00000010: non-posted requests (NP)
 169 - 8'b00000100: completions (CPL)
 170
 171 You can specify multiple types when tracing inbound TLP headers, but can only
 172 specify one when tracing outbound TLP headers.
 173
 174 3. Direction
 175 ------------
 176
 177 You can trace the TLP headers from certain direction, which is relative
 178 to the Root Port or the PCIe core, by specifying the `direction` parameter.
 179 This is optional and the default parameter is inbound. The parameter value
 180 is 4 bit. When the desired format is 4DW, directions and related values
 181 supported are shown below:
 182
 183 - 4'b0000: inbound TLPs (P, NP, CPL)
 184 - 4'b0001: outbound TLPs (P, NP, CPL)
 185 - 4'b0010: outbound TLPs (P, NP, CPL) and inbound TLPs (P, NP, CPL B)
 186 - 4'b0011: outbound TLPs (P, NP, CPL) and inbound TLPs (CPL A)
 187
 188 When the desired format is 8DW, directions and related values supported are
 189 shown below:
 190
 191 - 4'b0000: reserved
 192 - 4'b0001: outbound TLPs (P, NP, CPL)
 193 - 4'b0010: inbound TLPs (P, NP, CPL B)
 194 - 4'b0011: inbound TLPs (CPL A)
 195
 196 Inbound completions are classified into two types:
 197
 198 - completion A (CPL A): completion of CHI/DMA/Native non-posted requests, except for CPL B
 199 - completion B (CPL B): completion of DMA remote2local and P2P non-posted requests
 200
 201 4. Format
 202 --------------
 203
 204 You can change the format of the traced TLP headers by specifying the
 205 `format` parameter. The default format is 4DW. The parameter value is 4 bit.
 206 Current supported formats and related values are shown below:
 207
 208 - 4'b0000: 4DW length per TLP header
 209 - 4'b0001: 8DW length per TLP header
 210
 211 The traced TLP header format is different from the PCIe standard.
 212
 213 When using the 8DW data format, the entire TLP header is logged
 214 (Header DW0-3 shown below). For example, the TLP header for Memory
 215 Reads with 64-bit addresses is shown in PCIe r5.0, Figure 2-17;
 216 the header for Configuration Requests is shown in Figure 2.20, etc.
 217
 218 In addition, 8DW trace buffer entries contain a timestamp and
 219 possibly a prefix for a PASID TLP prefix (see Figure 6-20, PCIe r5.0).
 220 Otherwise this field will be all 0.
 221
 222 The bit[31:11] of DW0 is always 0x1fffff, which can be
 223 used to distinguish the data format. 8DW format is like
 224 ::
 225
 226     bits [                 31:11                 ][       10:0       ]
 227          |---------------------------------------|-------------------|
 228      DW0 [                0x1fffff               ][ Reserved (0x7ff) ]
 229      DW1 [                       Prefix                              ]
 230      DW2 [                     Header DW0                            ]
 231      DW3 [                     Header DW1                            ]
 232      DW4 [                     Header DW2                            ]
 233      DW5 [                     Header DW3                            ]
 234      DW6 [                   Reserved (0x0)                          ]
 235      DW7 [                        Time                               ]
 236
 237 When using the 4DW data format, DW0 of the trace buffer entry
 238 contains selected fields of DW0 of the TLP, together with a
 239 timestamp.  DW1-DW3 of the trace buffer entry contain DW1-DW3
 240 directly from the TLP header.
 241
 242 4DW format is like
 243 ::
 244
 245     bits [31:30] [ 29:25 ][24][23][22][21][    20:11   ][    10:0    ]
 246          |-----|---------|---|---|---|---|-------------|-------------|
 247      DW0 [ Fmt ][  Type  ][T9][T8][TH][SO][   Length   ][    Time    ]
 248      DW1 [                     Header DW1                            ]
 249      DW2 [                     Header DW2                            ]
 250      DW3 [                     Header DW3                            ]
 251
 252 5. Memory Management
 253 --------------------
 254
 255 The traced TLP headers will be written to the memory allocated
 256 by the driver. The hardware accepts 4 DMA address with same size,
 257 and writes the buffer sequentially like below. If DMA addr 3 is
 258 finished and the trace is still on, it will return to addr 0.
 259 ::
 260
 261     +->[DMA addr 0]->[DMA addr 1]->[DMA addr 2]->[DMA addr 3]-+
 262     +---------------------------------------------------------+
 263
 264 Driver will allocate each DMA buffer of 4MiB. The finished buffer
 265 will be copied to the perf AUX buffer allocated by the perf core.
 266 Once the AUX buffer is full while the trace is still on, driver
 267 will commit the AUX buffer first and then apply for a new one with
 268 the same size. The size of AUX buffer is default to 16MiB. User can
 269 adjust the size by specifying the `-m` parameter of the perf command.
 270
 271 6. Decoding
 272 -----------
 273
 274 You can decode the traced data with `perf report -D` command (currently
 275 only support to dump the raw trace data). The traced data will be decoded
 276 according to the format described previously (take 8DW as an example):
 277 ::
 278
 279     [...perf headers and other information]
 280     . ... HISI PTT data: size 4194304 bytes
 281     .  00000000: 00 00 00 00                                 Prefix
 282     .  00000004: 01 00 00 60                                 Header DW0
 283     .  00000008: 0f 1e 00 01                                 Header DW1
 284     .  0000000c: 04 00 00 00                                 Header DW2
 285     .  00000010: 40 00 81 02                                 Header DW3
 286     .  00000014: 33 c0 04 00                                 Time
 287     .  00000020: 00 00 00 00                                 Prefix
 288     .  00000024: 01 00 00 60                                 Header DW0
 289     .  00000028: 0f 1e 00 01                                 Header DW1
 290     .  0000002c: 04 00 00 00                                 Header DW2
 291     .  00000030: 40 00 81 02                                 Header DW3
 292     .  00000034: 02 00 00 00                                 Time
 293     .  00000040: 00 00 00 00                                 Prefix
 294     .  00000044: 01 00 00 60                                 Header DW0
 295     .  00000048: 0f 1e 00 01                                 Header DW1
 296     .  0000004c: 04 00 00 00                                 Header DW2
 297     .  00000050: 40 00 81 02                                 Header DW3
 298     [...]