Debian Codegraph @

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

raw
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===================
4 PCI Test User Guide
5 ===================
6
7 :Author: Kishon Vijay Abraham I <[email protected]>
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 32 > functions/pci_epf_test/func1/msi_interrupts
85 # echo 2048 > functions/pci_epf_test/func1/msix_interrupts
86
87 By 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
97 The user can override a default value using e.g.::
98 # echo 1048576 > functions/pci_epf_test/func1/pci_epf_test.0/bar1_size
99
100 Overriding the default BAR sizes can only be done before binding the
101 pci-epf-test device to a PCI endpoint controller driver.
102
103 Note: Some endpoint controllers might have fixed-size BARs or reserved BARs;
104 for such controllers, the corresponding BAR size in configfs will be ignored.
105
106
107 Binding pci-epf-test Device to EP Controller
108 --------------------------------------------
109
110 In order for the endpoint function device to be useful, it has to be bound to
111 a PCI endpoint controller driver. Use the configfs to bind the function
112 device to one of the controller driver present in the system::
113
114 # ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/
115
116 Once the above step is completed, the PCI endpoint is ready to establish a link
117 with the host.
118
119
120 Start the Link
121 --------------
122
123 In order for the endpoint device to establish a link with the host, the _start_
124 field should be populated with '1'::
125
126 # echo 1 > controllers/51000000.pcie_ep/start
127
128
129 RootComplex Device
130 ==================
131
132 lspci Output
133 ------------
134
135 Note that the devices listed here correspond to the value populated in 1.4
136 above::
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
142 Using Endpoint Test function Device
143 -----------------------------------
144
145 Kselftest added in tools/testing/selftests/pci_endpoint can be used to run all
146 the default PCI endpoint tests. To build the Kselftest for PCI endpoint
147 subsystem, the following commands should be used::
148
149 # cd <kernel-dir>
150 # make -C tools/testing/selftests/pci_endpoint
151
152 or 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
157 The test will be located in <rootfs>/usr/bin/
158
159 Kselftest 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
219 Testcase 16 (pci_ep_data_transfer.dma.COPY_TEST) will fail for most of the DMA
220 capable endpoint controllers due to the absence of the MEMCPY over DMA. For such
221 controllers, it is advisable to skip this testcase using this
222 command::
223
224 # pci_endpoint_test -f pci_ep_bar -f pci_ep_basic -v memcpy -T COPY_TEST -v dma
225
226 Kselftest EP Doorbell
227 ~~~~~~~~~~~~~~~~~~~~~
228
229 If the Endpoint MSI controller is used for the doorbell usecase, run below
230 command 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