1.. SPDX-License-Identifier: GPL-2.0 2 3=================== 4PCI Test User Guide 5=================== 6 7:Author: Kishon Vijay Abraham I <kishon@ti.com> 8 9This document is a guide to help users use pci-epf-test function driver 10and pci_endpoint_test host driver for testing PCI. The list of steps to 11be followed in the host side and EP side is given below. 12 13Endpoint Device 14=============== 15 16Endpoint Controller Devices 17--------------------------- 18 19To find the list of endpoint controller devices in the system:: 20 21 # ls /sys/class/pci_epc/ 22 51000000.pcie_ep 23 24If PCI_ENDPOINT_CONFIGFS is enabled:: 25 26 # ls /sys/kernel/config/pci_ep/controllers 27 51000000.pcie_ep 28 29 30Endpoint Function Drivers 31------------------------- 32 33To find the list of endpoint function drivers in the system:: 34 35 # ls /sys/bus/pci-epf/drivers 36 pci_epf_test 37 38If PCI_ENDPOINT_CONFIGFS is enabled:: 39 40 # ls /sys/kernel/config/pci_ep/functions 41 pci_epf_test 42 43 44Creating pci-epf-test Device 45---------------------------- 46 47PCI endpoint function device can be created using the configfs. To create 48pci-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 54The "mkdir func1" above creates the pci-epf-test function device that will 55be probed by pci_epf_test driver. 56 57The PCI endpoint framework populates the directory with the following 58configurable 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 65The PCI endpoint function driver populates these entries with default values 66when the device is bound to the driver. The pci-epf-test driver populates 67vendorid 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 75Configuring pci-epf-test Device 76------------------------------- 77 78The user can configure the pci-epf-test device using configfs entry. In order 79to change the vendorid and the number of MSI interrupts used by the function 80device, 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 32 > functions/pci_epf_test/func1/msi_interrupts 85 # echo 2048 > functions/pci_epf_test/func1/msix_interrupts 86 87By default, pci-epf-test uses the following BAR sizes:: 88 89 # grep . functions/pci_epf_test/func1/pci_epf_test.0/bar?_size 90 functions/pci_epf_test/func1/pci_epf_test.0/bar0_size:131072 91 functions/pci_epf_test/func1/pci_epf_test.0/bar1_size:131072 92 functions/pci_epf_test/func1/pci_epf_test.0/bar2_size:131072 93 functions/pci_epf_test/func1/pci_epf_test.0/bar3_size:131072 94 functions/pci_epf_test/func1/pci_epf_test.0/bar4_size:131072 95 functions/pci_epf_test/func1/pci_epf_test.0/bar5_size:1048576 96 97The user can override a default value using e.g.:: 98 # echo 1048576 > functions/pci_epf_test/func1/pci_epf_test.0/bar1_size 99 100Overriding the default BAR sizes can only be done before binding the 101pci-epf-test device to a PCI endpoint controller driver. 102 103Note: Some endpoint controllers might have fixed-size BARs or reserved BARs; 104for such controllers, the corresponding BAR size in configfs will be ignored. 105 106 107Binding pci-epf-test Device to EP Controller 108-------------------------------------------- 109 110In order for the endpoint function device to be useful, it has to be bound to 111a PCI endpoint controller driver. Use the configfs to bind the function 112device to one of the controller driver present in the system:: 113 114 # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/ 115 116Once the above step is completed, the PCI endpoint is ready to establish a link 117with the host. 118 119 120Start the Link 121-------------- 122 123In order for the endpoint device to establish a link with the host, the _start_ 124field should be populated with '1':: 125 126 # echo 1 > controllers/51000000.pcie_ep/start 127 128 129RootComplex Device 130================== 131 132lspci Output 133------------ 134 135Note that the devices listed here correspond to the value populated in 1.4 136above:: 137 138 00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01) 139 01:00.0 Unassigned class [ff00]: Texas Instruments Device b500 140 141 142Using Endpoint Test function Device 143----------------------------------- 144 145Kselftest added in tools/testing/selftests/pci_endpoint can be used to run all 146the default PCI endpoint tests. To build the Kselftest for PCI endpoint 147subsystem, the following commands should be used:: 148 149 # cd <kernel-dir> 150 # make -C tools/testing/selftests/pci_endpoint 151 152or if you desire to compile and install in your system:: 153 154 # cd <kernel-dir> 155 # make -C tools/testing/selftests/pci_endpoint INSTALL_PATH=/usr/bin install 156 157The test will be located in <rootfs>/usr/bin/ 158 159Kselftest Output 160~~~~~~~~~~~~~~~~ 161:: 162 163 # pci_endpoint_test 164 TAP version 13 165 1..16 166 # Starting 16 tests from 9 test cases. 167 # RUN pci_ep_bar.BAR0.BAR_TEST ... 168 # OK pci_ep_bar.BAR0.BAR_TEST 169 ok 1 pci_ep_bar.BAR0.BAR_TEST 170 # RUN pci_ep_bar.BAR1.BAR_TEST ... 171 # OK pci_ep_bar.BAR1.BAR_TEST 172 ok 2 pci_ep_bar.BAR1.BAR_TEST 173 # RUN pci_ep_bar.BAR2.BAR_TEST ... 174 # OK pci_ep_bar.BAR2.BAR_TEST 175 ok 3 pci_ep_bar.BAR2.BAR_TEST 176 # RUN pci_ep_bar.BAR3.BAR_TEST ... 177 # OK pci_ep_bar.BAR3.BAR_TEST 178 ok 4 pci_ep_bar.BAR3.BAR_TEST 179 # RUN pci_ep_bar.BAR4.BAR_TEST ... 180 # OK pci_ep_bar.BAR4.BAR_TEST 181 ok 5 pci_ep_bar.BAR4.BAR_TEST 182 # RUN pci_ep_bar.BAR5.BAR_TEST ... 183 # OK pci_ep_bar.BAR5.BAR_TEST 184 ok 6 pci_ep_bar.BAR5.BAR_TEST 185 # RUN pci_ep_basic.CONSECUTIVE_BAR_TEST ... 186 # OK pci_ep_basic.CONSECUTIVE_BAR_TEST 187 ok 7 pci_ep_basic.CONSECUTIVE_BAR_TEST 188 # RUN pci_ep_basic.LEGACY_IRQ_TEST ... 189 # OK pci_ep_basic.LEGACY_IRQ_TEST 190 ok 8 pci_ep_basic.LEGACY_IRQ_TEST 191 # RUN pci_ep_basic.MSI_TEST ... 192 # OK pci_ep_basic.MSI_TEST 193 ok 9 pci_ep_basic.MSI_TEST 194 # RUN pci_ep_basic.MSIX_TEST ... 195 # OK pci_ep_basic.MSIX_TEST 196 ok 10 pci_ep_basic.MSIX_TEST 197 # RUN pci_ep_data_transfer.memcpy.READ_TEST ... 198 # OK pci_ep_data_transfer.memcpy.READ_TEST 199 ok 11 pci_ep_data_transfer.memcpy.READ_TEST 200 # RUN pci_ep_data_transfer.memcpy.WRITE_TEST ... 201 # OK pci_ep_data_transfer.memcpy.WRITE_TEST 202 ok 12 pci_ep_data_transfer.memcpy.WRITE_TEST 203 # RUN pci_ep_data_transfer.memcpy.COPY_TEST ... 204 # OK pci_ep_data_transfer.memcpy.COPY_TEST 205 ok 13 pci_ep_data_transfer.memcpy.COPY_TEST 206 # RUN pci_ep_data_transfer.dma.READ_TEST ... 207 # OK pci_ep_data_transfer.dma.READ_TEST 208 ok 14 pci_ep_data_transfer.dma.READ_TEST 209 # RUN pci_ep_data_transfer.dma.WRITE_TEST ... 210 # OK pci_ep_data_transfer.dma.WRITE_TEST 211 ok 15 pci_ep_data_transfer.dma.WRITE_TEST 212 # RUN pci_ep_data_transfer.dma.COPY_TEST ... 213 # OK pci_ep_data_transfer.dma.COPY_TEST 214 ok 16 pci_ep_data_transfer.dma.COPY_TEST 215 # PASSED: 16 / 16 tests passed. 216 # Totals: pass:16 fail:0 xfail:0 xpass:0 skip:0 error:0 217 218 219Testcase 16 (pci_ep_data_transfer.dma.COPY_TEST) will fail for most of the DMA 220capable endpoint controllers due to the absence of the MEMCPY over DMA. For such 221controllers, it is advisable to skip this testcase using this 222command:: 223 224 # pci_endpoint_test -f pci_ep_bar -f pci_ep_basic -v memcpy -T COPY_TEST -v dma 225 226Kselftest EP Doorbell 227~~~~~~~~~~~~~~~~~~~~~ 228 229If the Endpoint MSI controller is used for the doorbell usecase, run below 230command for testing it: 231 232 # pci_endpoint_test -f pcie_ep_doorbell 233 234 # Starting 1 tests from 1 test cases. 235 # RUN pcie_ep_doorbell.DOORBELL_TEST ... 236 # OK pcie_ep_doorbell.DOORBELL_TEST 237 ok 1 pcie_ep_doorbell.DOORBELL_TEST 238 # PASSED: 1 / 1 tests passed. 239 # Totals: pass:1 fail:0 xfail:0 xpass:0 skip:0 error:0 240