Documentation/PCI/endpoint/pci-test-howto.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===================
   4 PCI Test User Guide
   5 ===================
   6
   7 :Author: Kishon Vijay Abraham I <kishon@ti.com>
   8
   9 This document is a guide to help users use pci-epf-test function driver
  10 and pci_endpoint_test host driver for testing PCI. The list of steps to
  11 be followed in the host side and EP side is given below.
  12
  13 Endpoint Device
  14 ===============
  15
  16 Endpoint Controller Devices
  17 ---------------------------
  18
  19 To find the list of endpoint controller devices in the system::
  20
  21         # ls /sys/class/pci_epc/
  22           51000000.pcie_ep
  23
  24 If PCI_ENDPOINT_CONFIGFS is enabled::
  25
  26         # ls /sys/kernel/config/pci_ep/controllers
  27           51000000.pcie_ep
  28
  29
  30 Endpoint Function Drivers
  31 -------------------------
  32
  33 To find the list of endpoint function drivers in the system::
  34
  35         # ls /sys/bus/pci-epf/drivers
  36           pci_epf_test
  37
  38 If PCI_ENDPOINT_CONFIGFS is enabled::
  39
  40         # ls /sys/kernel/config/pci_ep/functions
  41           pci_epf_test
  42
  43
  44 Creating pci-epf-test Device
  45 ----------------------------
  46
  47 PCI endpoint function device can be created using the configfs. To create
  48 pci-epf-test device, the following commands can be used::
  49
  50         # mount -t configfs none /sys/kernel/config
  51         # cd /sys/kernel/config/pci_ep/
  52         # mkdir functions/pci_epf_test/func1
  53
  54 The "mkdir func1" above creates the pci-epf-test function device that will
  55 be probed by pci_epf_test driver.
  56
  57 The PCI endpoint framework populates the directory with the following
  58 configurable fields::
  59
  60         # ls functions/pci_epf_test/func1
  61           baseclass_code        interrupt_pin   progif_code     subsys_id
  62           cache_line_size       msi_interrupts  revid           subsys_vendorid
  63           deviceid              msix_interrupts subclass_code   vendorid
  64
  65 The PCI endpoint function driver populates these entries with default values
  66 when the device is bound to the driver. The pci-epf-test driver populates
  67 vendorid with 0xffff and interrupt_pin with 0x0001::
  68
  69         # cat functions/pci_epf_test/func1/vendorid
  70           0xffff
  71         # cat functions/pci_epf_test/func1/interrupt_pin
  72           0x0001
  73
  74
  75 Configuring pci-epf-test Device
  76 -------------------------------
  77
  78 The user can configure the pci-epf-test device using configfs entry. In order
  79 to change the vendorid and the number of MSI interrupts used by the function
  80 device, the following commands can be used::
  81
  82         # echo 0x104c > functions/pci_epf_test/func1/vendorid
  83         # echo 0xb500 > functions/pci_epf_test/func1/deviceid
  84         # echo 16 > functions/pci_epf_test/func1/msi_interrupts
  85         # echo 8 > functions/pci_epf_test/func1/msix_interrupts
  86
  87
  88 Binding pci-epf-test Device to EP Controller
  89 --------------------------------------------
  90
  91 In order for the endpoint function device to be useful, it has to be bound to
  92 a PCI endpoint controller driver. Use the configfs to bind the function
  93 device to one of the controller driver present in the system::
  94
  95         # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/
  96
  97 Once the above step is completed, the PCI endpoint is ready to establish a link
  98 with the host.
  99
 100
 101 Start the Link
 102 --------------
 103
 104 In order for the endpoint device to establish a link with the host, the _start_
 105 field should be populated with '1'::
 106
 107         # echo 1 > controllers/51000000.pcie_ep/start
 108
 109
 110 RootComplex Device
 111 ==================
 112
 113 lspci Output
 114 ------------
 115
 116 Note that the devices listed here correspond to the value populated in 1.4
 117 above::
 118
 119         00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01)
 120         01:00.0 Unassigned class [ff00]: Texas Instruments Device b500
 121
 122
 123 Using Endpoint Test function Device
 124 -----------------------------------
 125
 126 pcitest.sh added in tools/pci/ can be used to run all the default PCI endpoint
 127 tests. To compile this tool the following commands should be used::
 128
 129         # cd <kernel-dir>
 130         # make -C tools/pci
 131
 132 or if you desire to compile and install in your system::
 133
 134         # cd <kernel-dir>
 135         # make -C tools/pci install
 136
 137 The tool and script will be located in <rootfs>/usr/bin/
 138
 139
 140 pcitest.sh Output
 141 ~~~~~~~~~~~~~~~~~
 142 ::
 143
 144         # pcitest.sh
 145         BAR tests
 146
 147         BAR0:           OKAY
 148         BAR1:           OKAY
 149         BAR2:           OKAY
 150         BAR3:           OKAY
 151         BAR4:           NOT OKAY
 152         BAR5:           NOT OKAY
 153
 154         Interrupt tests
 155
 156         SET IRQ TYPE TO LEGACY:         OKAY
 157         LEGACY IRQ:     NOT OKAY
 158         SET IRQ TYPE TO MSI:            OKAY
 159         MSI1:           OKAY
 160         MSI2:           OKAY
 161         MSI3:           OKAY
 162         MSI4:           OKAY
 163         MSI5:           OKAY
 164         MSI6:           OKAY
 165         MSI7:           OKAY
 166         MSI8:           OKAY
 167         MSI9:           OKAY
 168         MSI10:          OKAY
 169         MSI11:          OKAY
 170         MSI12:          OKAY
 171         MSI13:          OKAY
 172         MSI14:          OKAY
 173         MSI15:          OKAY
 174         MSI16:          OKAY
 175         MSI17:          NOT OKAY
 176         MSI18:          NOT OKAY
 177         MSI19:          NOT OKAY
 178         MSI20:          NOT OKAY
 179         MSI21:          NOT OKAY
 180         MSI22:          NOT OKAY
 181         MSI23:          NOT OKAY
 182         MSI24:          NOT OKAY
 183         MSI25:          NOT OKAY
 184         MSI26:          NOT OKAY
 185         MSI27:          NOT OKAY
 186         MSI28:          NOT OKAY
 187         MSI29:          NOT OKAY
 188         MSI30:          NOT OKAY
 189         MSI31:          NOT OKAY
 190         MSI32:          NOT OKAY
 191         SET IRQ TYPE TO MSI-X:          OKAY
 192         MSI-X1:         OKAY
 193         MSI-X2:         OKAY
 194         MSI-X3:         OKAY
 195         MSI-X4:         OKAY
 196         MSI-X5:         OKAY
 197         MSI-X6:         OKAY
 198         MSI-X7:         OKAY
 199         MSI-X8:         OKAY
 200         MSI-X9:         NOT OKAY
 201         MSI-X10:        NOT OKAY
 202         MSI-X11:        NOT OKAY
 203         MSI-X12:        NOT OKAY
 204         MSI-X13:        NOT OKAY
 205         MSI-X14:        NOT OKAY
 206         MSI-X15:        NOT OKAY
 207         MSI-X16:        NOT OKAY
 208         [...]
 209         MSI-X2047:      NOT OKAY
 210         MSI-X2048:      NOT OKAY
 211
 212         Read Tests
 213
 214         SET IRQ TYPE TO MSI:            OKAY
 215         READ (      1 bytes):           OKAY
 216         READ (   1024 bytes):           OKAY
 217         READ (   1025 bytes):           OKAY
 218         READ (1024000 bytes):           OKAY
 219         READ (1024001 bytes):           OKAY
 220
 221         Write Tests
 222
 223         WRITE (      1 bytes):          OKAY
 224         WRITE (   1024 bytes):          OKAY
 225         WRITE (   1025 bytes):          OKAY
 226         WRITE (1024000 bytes):          OKAY
 227         WRITE (1024001 bytes):          OKAY
 228
 229         Copy Tests
 230
 231         COPY (      1 bytes):           OKAY
 232         COPY (   1024 bytes):           OKAY
 233         COPY (   1025 bytes):           OKAY
 234         COPY (1024000 bytes):           OKAY
 235         COPY (1024001 bytes):           OKAY