요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
===================
4
PCI Test User Guide
5
===================
7
:Author: Kishon Vijay Abraham I <[email protected]>
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.
13
Endpoint Device
14
===============
16
Endpoint Controller Devices
17
---------------------------
19
To find the list of endpoint controller devices in the system::
21
# ls /sys/class/pci_epc/
22
51000000.pcie_ep
24
If PCI_ENDPOINT_CONFIGFS is enabled::
26
# ls /sys/kernel/config/pci_ep/controllers
27
51000000.pcie_ep
30
Endpoint Function Drivers
31
-------------------------
33
To find the list of endpoint function drivers in the system::
35
# ls /sys/bus/pci-epf/drivers
36
pci_epf_test
38
If PCI_ENDPOINT_CONFIGFS is enabled::
40
# ls /sys/kernel/config/pci_ep/functions
41
pci_epf_test
44
Creating pci-epf-test Device
45
----------------------------
47
PCI endpoint function device can be created using the configfs. To create
48
pci-epf-test device, the following commands can be used::
50
# mount -t configfs none /sys/kernel/config
51
# cd /sys/kernel/config/pci_ep/
52
# mkdir functions/pci_epf_test/func1
54
The "mkdir func1" above creates the pci-epf-test function device that will
55
be probed by pci_epf_test driver.
57
The PCI endpoint framework populates the directory with the following
58
configurable fields::
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
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::
69
# cat functions/pci_epf_test/func1/vendorid
70
0xffff
71
# cat functions/pci_epf_test/func1/interrupt_pin
72
0x0001
75
Configuring pci-epf-test Device
76
-------------------------------
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::
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
88
Binding pci-epf-test Device to EP Controller
89
--------------------------------------------
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::
95
# ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/
97
Once the above step is completed, the PCI endpoint is ready to establish a link
98
with the host.
101
Start the Link
102
--------------
104
In order for the endpoint device to establish a link with the host, the _start_
105
field should be populated with '1'::
107
# echo 1 > controllers/51000000.pcie_ep/start
110
RootComplex Device
111
==================
113
lspci Output
114
------------
116
Note that the devices listed here correspond to the value populated in 1.4
117
above::
119
00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01)
120
01:00.0 Unassigned class [ff00]: Texas Instruments Device b500
123
Using Endpoint Test function Device
124
-----------------------------------
126
Kselftest added in tools/testing/selftests/pci_endpoint can be used to run all
127
the default PCI endpoint tests. To build the Kselftest for PCI endpoint
128
subsystem, the following commands should be used::
130
# cd <kernel-dir>
131
# make -C tools/testing/selftests/pci_endpoint
133
or if you desire to compile and install in your system::
135
# cd <kernel-dir>
136
# make -C tools/testing/selftests/pci_endpoint INSTALL_PATH=/usr/bin install
138
The test will be located in <rootfs>/usr/bin/
140
Kselftest Output
141
~~~~~~~~~~~~~~~~
142
::
144
# pci_endpoint_test
145
TAP version 13
146
1..16
147
# Starting 16 tests from 9 test cases.
148
# RUN pci_ep_bar.BAR0.BAR_TEST ...
149
# OK pci_ep_bar.BAR0.BAR_TEST
150
ok 1 pci_ep_bar.BAR0.BAR_TEST
151
# RUN pci_ep_bar.BAR1.BAR_TEST ...
152
# OK pci_ep_bar.BAR1.BAR_TEST
153
ok 2 pci_ep_bar.BAR1.BAR_TEST
154
# RUN pci_ep_bar.BAR2.BAR_TEST ...
155
# OK pci_ep_bar.BAR2.BAR_TEST
156
ok 3 pci_ep_bar.BAR2.BAR_TEST
157
# RUN pci_ep_bar.BAR3.BAR_TEST ...
158
# OK pci_ep_bar.BAR3.BAR_TEST
159
ok 4 pci_ep_bar.BAR3.BAR_TEST
160
# RUN pci_ep_bar.BAR4.BAR_TEST ...
161
# OK pci_ep_bar.BAR4.BAR_TEST
162
ok 5 pci_ep_bar.BAR4.BAR_TEST
163
# RUN pci_ep_bar.BAR5.BAR_TEST ...
164
# OK pci_ep_bar.BAR5.BAR_TEST
165
ok 6 pci_ep_bar.BAR5.BAR_TEST
166
# RUN pci_ep_basic.CONSECUTIVE_BAR_TEST ...
167
# OK pci_ep_basic.CONSECUTIVE_BAR_TEST
168
ok 7 pci_ep_basic.CONSECUTIVE_BAR_TEST
169
# RUN pci_ep_basic.LEGACY_IRQ_TEST ...
170
# OK pci_ep_basic.LEGACY_IRQ_TEST
171
ok 8 pci_ep_basic.LEGACY_IRQ_TEST
172
# RUN pci_ep_basic.MSI_TEST ...
173
# OK pci_ep_basic.MSI_TEST
174
ok 9 pci_ep_basic.MSI_TEST
175
# RUN pci_ep_basic.MSIX_TEST ...
176
# OK pci_ep_basic.MSIX_TEST
177
ok 10 pci_ep_basic.MSIX_TEST
178
# RUN pci_ep_data_transfer.memcpy.READ_TEST ...
179
# OK pci_ep_data_transfer.memcpy.READ_TEST
180
ok 11 pci_ep_data_transfer.memcpy.READ_TEST
181
# RUN pci_ep_data_transfer.memcpy.WRITE_TEST ...
182
# OK pci_ep_data_transfer.memcpy.WRITE_TEST
183
ok 12 pci_ep_data_transfer.memcpy.WRITE_TEST
184
# RUN pci_ep_data_transfer.memcpy.COPY_TEST ...
185
# OK pci_ep_data_transfer.memcpy.COPY_TEST
186
ok 13 pci_ep_data_transfer.memcpy.COPY_TEST
187
# RUN pci_ep_data_transfer.dma.READ_TEST ...
188
# OK pci_ep_data_transfer.dma.READ_TEST
189
ok 14 pci_ep_data_transfer.dma.READ_TEST
190
# RUN pci_ep_data_transfer.dma.WRITE_TEST ...
191
# OK pci_ep_data_transfer.dma.WRITE_TEST
192
ok 15 pci_ep_data_transfer.dma.WRITE_TEST
193
# RUN pci_ep_data_transfer.dma.COPY_TEST ...
194
# OK pci_ep_data_transfer.dma.COPY_TEST
195
ok 16 pci_ep_data_transfer.dma.COPY_TEST
196
# PASSED: 16 / 16 tests passed.
197
# Totals: pass:16 fail:0 xfail:0 xpass:0 skip:0 error:0
200
Testcase 16 (pci_ep_data_transfer.dma.COPY_TEST) will fail for most of the DMA
201
capable endpoint controllers due to the absence of the MEMCPY over DMA. For such
202
controllers, it is advisable to skip this testcase using this
203
command::
205
# pci_endpoint_test -f pci_ep_bar -f pci_ep_basic -v memcpy -T COPY_TEST -v dma
207
Kselftest EP Doorbell
208
~~~~~~~~~~~~~~~~~~~~~
210
If the Endpoint MSI controller is used for the doorbell usecase, run below
211
command for testing it:
213
# pci_endpoint_test -f pcie_ep_doorbell
215
# Starting 1 tests from 1 test cases.
216
# RUN pcie_ep_doorbell.DOORBELL_TEST ...
217
# OK pcie_ep_doorbell.DOORBELL_TEST
218
ok 1 pcie_ep_doorbell.DOORBELL_TEST
219
# PASSED: 1 / 1 tests passed.
220
# Totals: pass:1 fail:0 xfail:0 xpass:0 skip:0 error:0
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
EP·host test driver
1-12저자는 Kishon Vijay Abraham I입니다. 이 문서는 `pci-epf-test` function driver와 `pci_endpoint_test` host driver로 PCI를 시험하는 EP 측·host 측 절차를 안내합니다.
.. SPDX-License-Identifier: GPL-2.0
===================
PCI Test User Guide
===================
:Author: Kishon Vijay Abraham I <[email protected]>
This document is a guide to help users use pci-epf-test function driver
and pci_endpoint_test host driver for testing PCI. The list of steps to
be followed in the host side and EP side is given below.
Endpoint controller 확인
13-29System의 endpoint controller device는 class 또는 configfs에서 확인합니다.
# ls /sys/class/pci_epc/
51000000.pcie_ep
# ls /sys/kernel/config/pci_ep/controllers
51000000.pcie_ep두 번째 경로는 `PCI_ENDPOINT_CONFIGFS`가 활성화됐을 때 사용합니다.
Endpoint Device
===============
Endpoint Controller Devices
---------------------------
To find the list of endpoint controller devices in the system::
# ls /sys/class/pci_epc/
51000000.pcie_ep
If PCI_ENDPOINT_CONFIGFS is enabled::
# ls /sys/kernel/config/pci_ep/controllers
51000000.pcie_ep
Endpoint function driver 확인
30-43등록된 function driver는 PCI EPF bus 또는 configfs에서 확인합니다.
# ls /sys/bus/pci-epf/drivers
pci_epf_test
# ls /sys/kernel/config/pci_ep/functions
pci_epf_testEndpoint Function Drivers
-------------------------
To find the list of endpoint function drivers in the system::
# ls /sys/bus/pci-epf/drivers
pci_epf_test
If PCI_ENDPOINT_CONFIGFS is enabled::
# ls /sys/kernel/config/pci_ep/functions
pci_epf_test
pci-epf-test device 생성
44-74Configfs를 mount하고 `pci_epf_test` 아래에 `func1` directory를 만들면 `pci_epf_test` driver가 probe할 function device가 생성됩니다.
# mount -t configfs none /sys/kernel/config
# cd /sys/kernel/config/pci_ep/
# mkdir functions/pci_epf_test/func1Framework는 function directory에 standard PCI configuration field를 만듭니다. Driver에 bind될 때 `vendorid` 기본값 `0xffff`, `interrupt_pin` 기본값 `0x0001`을 채웁니다.
구분Field
Identityvendorid, deviceid, revid
Classprogif_code, subclass_code, baseclass_code
Systemcache_line_size, subsys_vendorid, subsys_id
Interruptinterrupt_pin, msi_interrupts, msix_interrupts
Function의 PCI identity, class와 interrupt capability를 설정합니다.
# cat functions/pci_epf_test/func1/vendorid
0xffff
# cat functions/pci_epf_test/func1/interrupt_pin
0x0001Creating pci-epf-test Device
----------------------------
PCI endpoint function device can be created using the configfs. To create
pci-epf-test device, the following commands can be used::
# mount -t configfs none /sys/kernel/config
# cd /sys/kernel/config/pci_ep/
# mkdir functions/pci_epf_test/func1
The "mkdir func1" above creates the pci-epf-test function device that will
be probed by pci_epf_test driver.
The PCI endpoint framework populates the directory with the following
configurable fields::
# ls functions/pci_epf_test/func1
baseclass_code interrupt_pin progif_code subsys_id
cache_line_size msi_interrupts revid subsys_vendorid
deviceid msix_interrupts subclass_code vendorid
The PCI endpoint function driver populates these entries with default values
when the device is bound to the driver. The pci-epf-test driver populates
vendorid with 0xffff and interrupt_pin with 0x0001::
# cat functions/pci_epf_test/func1/vendorid
0xffff
# cat functions/pci_epf_test/func1/interrupt_pin
0x0001
PCI ID와 interrupt 수 구성
75-87Configfs로 TI test function의 vendor·device ID와 MSI·MSI-X vector 수를 설정합니다.
# echo 0x104c > functions/pci_epf_test/func1/vendorid
# echo 0xb500 > functions/pci_epf_test/func1/deviceid
# echo 32 > functions/pci_epf_test/func1/msi_interrupts
# echo 2048 > functions/pci_epf_test/func1/msix_interruptsConfiguring pci-epf-test Device
-------------------------------
The user can configure the pci-epf-test device using configfs entry. In order
to change the vendorid and the number of MSI interrupts used by the function
device, the following commands can be used::
# echo 0x104c > functions/pci_epf_test/func1/vendorid
# echo 0xb500 > functions/pci_epf_test/func1/deviceid
# echo 32 > functions/pci_epf_test/func1/msi_interrupts
# echo 2048 > functions/pci_epf_test/func1/msix_interrupts
EP controller에 binding
88-100Function device를 사용하려면 system의 PCI endpoint controller driver에 bind해야 합니다. Configfs에서 function symlink를 controller directory에 만듭니다.
# ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/Symlink를 만든 뒤 endpoint는 host와 link를 맺을 준비가 됩니다.
Binding pci-epf-test Device to EP Controller
--------------------------------------------
In order for the endpoint function device to be useful, it has to be bound to
a PCI endpoint controller driver. Use the configfs to bind the function
device to one of the controller driver present in the system::
# ln -s functions/pci_epf_test/func1 controllers/51000000.pcie_ep/
Once the above step is completed, the PCI endpoint is ready to establish a link
with the host.
Link 시작
101-109Controller의 `start` field에 `1`을 써 endpoint-host link를 시작합니다.
# echo 1 > controllers/51000000.pcie_ep/startDiscover EPC + EPF→Create func1→Configure IDs + MSI/MSI-X→Bind to 51000000.pcie_ep→start = 1
Test EPF를 만들고 구성·bind한 뒤 link를 시작합니다.
Start the Link
--------------
In order for the endpoint device to establish a link with the host, the _start_
field should be populated with '1'::
# echo 1 > controllers/51000000.pcie_ep/start
Root Complex lspci 출력
110-122Root Complex에는 PCI bridge와 앞서 설정한 TI device `b500` test function이 표시됩니다.
00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01)
01:00.0 Unassigned class [ff00]: Texas Instruments Device b500RootComplex Device
==================
lspci Output
------------
Note that the devices listed here correspond to the value populated in 1.4
above::
00:00.0 PCI bridge: Texas Instruments Device 8888 (rev 01)
01:00.0 Unassigned class [ff00]: Texas Instruments Device b500
PCI endpoint Kselftest build
123-139`tools/testing/selftests/pci_endpoint`의 Kselftest로 기본 PCI endpoint test 전체를 실행할 수 있습니다.
# cd <kernel-dir>
# make -C tools/testing/selftests/pci_endpoint
# make -C tools/testing/selftests/pci_endpoint INSTALL_PATH=/usr/bin installInstall한 test는 `<rootfs>/usr/bin/`에 놓입니다.
Using Endpoint Test function Device
-----------------------------------
Kselftest added in tools/testing/selftests/pci_endpoint can be used to run all
the default PCI endpoint tests. To build the Kselftest for PCI endpoint
subsystem, the following commands should be used::
# cd <kernel-dir>
# make -C tools/testing/selftests/pci_endpoint
or if you desire to compile and install in your system::
# cd <kernel-dir>
# make -C tools/testing/selftests/pci_endpoint INSTALL_PATH=/usr/bin install
The test will be located in <rootfs>/usr/bin/
기본 16개 Kselftest
140-199`pci_endpoint_test`는 TAP version 13으로 9개 test case에서 16개 test를 실행합니다.
번호Test
1..6BAR0..BAR5 BAR_TEST
7CONSECUTIVE_BAR_TEST
8LEGACY_IRQ_TEST
9MSI_TEST
10MSIX_TEST
11..13memcpy READ/WRITE/COPY_TEST
14..16dma READ/WRITE/COPY_TEST
원문 출력에서 모두 통과한 test group입니다.
예제 결과는 `16 / 16` pass이며 fail, xfail, xpass, skip, error가 모두 0입니다.
# pci_endpoint_test
TAP version 13
1..16
# Starting 16 tests from 9 test cases.
...
# PASSED: 16 / 16 tests passed.
# Totals: pass:16 fail:0 xfail:0 xpass:0 skip:0 error:0Kselftest Output
~~~~~~~~~~~~~~~~
::
# pci_endpoint_test
TAP version 13
1..16
# Starting 16 tests from 9 test cases.
# RUN pci_ep_bar.BAR0.BAR_TEST ...
# OK pci_ep_bar.BAR0.BAR_TEST
ok 1 pci_ep_bar.BAR0.BAR_TEST
# RUN pci_ep_bar.BAR1.BAR_TEST ...
# OK pci_ep_bar.BAR1.BAR_TEST
ok 2 pci_ep_bar.BAR1.BAR_TEST
# RUN pci_ep_bar.BAR2.BAR_TEST ...
# OK pci_ep_bar.BAR2.BAR_TEST
ok 3 pci_ep_bar.BAR2.BAR_TEST
# RUN pci_ep_bar.BAR3.BAR_TEST ...
# OK pci_ep_bar.BAR3.BAR_TEST
ok 4 pci_ep_bar.BAR3.BAR_TEST
# RUN pci_ep_bar.BAR4.BAR_TEST ...
# OK pci_ep_bar.BAR4.BAR_TEST
ok 5 pci_ep_bar.BAR4.BAR_TEST
# RUN pci_ep_bar.BAR5.BAR_TEST ...
# OK pci_ep_bar.BAR5.BAR_TEST
ok 6 pci_ep_bar.BAR5.BAR_TEST
# RUN pci_ep_basic.CONSECUTIVE_BAR_TEST ...
# OK pci_ep_basic.CONSECUTIVE_BAR_TEST
ok 7 pci_ep_basic.CONSECUTIVE_BAR_TEST
# RUN pci_ep_basic.LEGACY_IRQ_TEST ...
# OK pci_ep_basic.LEGACY_IRQ_TEST
ok 8 pci_ep_basic.LEGACY_IRQ_TEST
# RUN pci_ep_basic.MSI_TEST ...
# OK pci_ep_basic.MSI_TEST
ok 9 pci_ep_basic.MSI_TEST
# RUN pci_ep_basic.MSIX_TEST ...
# OK pci_ep_basic.MSIX_TEST
ok 10 pci_ep_basic.MSIX_TEST
# RUN pci_ep_data_transfer.memcpy.READ_TEST ...
# OK pci_ep_data_transfer.memcpy.READ_TEST
ok 11 pci_ep_data_transfer.memcpy.READ_TEST
# RUN pci_ep_data_transfer.memcpy.WRITE_TEST ...
# OK pci_ep_data_transfer.memcpy.WRITE_TEST
ok 12 pci_ep_data_transfer.memcpy.WRITE_TEST
# RUN pci_ep_data_transfer.memcpy.COPY_TEST ...
# OK pci_ep_data_transfer.memcpy.COPY_TEST
ok 13 pci_ep_data_transfer.memcpy.COPY_TEST
# RUN pci_ep_data_transfer.dma.READ_TEST ...
# OK pci_ep_data_transfer.dma.READ_TEST
ok 14 pci_ep_data_transfer.dma.READ_TEST
# RUN pci_ep_data_transfer.dma.WRITE_TEST ...
# OK pci_ep_data_transfer.dma.WRITE_TEST
ok 15 pci_ep_data_transfer.dma.WRITE_TEST
# RUN pci_ep_data_transfer.dma.COPY_TEST ...
# OK pci_ep_data_transfer.dma.COPY_TEST
ok 16 pci_ep_data_transfer.dma.COPY_TEST
# PASSED: 16 / 16 tests passed.
# Totals: pass:16 fail:0 xfail:0 xpass:0 skip:0 error:0
DMA COPY test 예외
200-206대부분의 DMA-capable endpoint controller는 DMA MEMCPY를 지원하지 않아 test 16 `pci_ep_data_transfer.dma.COPY_TEST`가 실패합니다. 이런 controller에서는 다음 command로 해당 test를 제외하는 것이 좋습니다.
# pci_endpoint_test -f pci_ep_bar -f pci_ep_basic -v memcpy -T COPY_TEST -v dmaTestcase 16 (pci_ep_data_transfer.dma.COPY_TEST) will fail for most of the DMA
capable endpoint controllers due to the absence of the MEMCPY over DMA. For such
controllers, it is advisable to skip this testcase using this
command::
# pci_endpoint_test -f pci_ep_bar -f pci_ep_basic -v memcpy -T COPY_TEST -v dma
Endpoint MSI doorbell test
207-220Endpoint MSI controller를 doorbell use case에 사용한다면 `pcie_ep_doorbell` test를 실행합니다.
# pci_endpoint_test -f pcie_ep_doorbell
# Starting 1 tests from 1 test cases.
# RUN pcie_ep_doorbell.DOORBELL_TEST ...
# OK pcie_ep_doorbell.DOORBELL_TEST
ok 1 pcie_ep_doorbell.DOORBELL_TEST
# PASSED: 1 / 1 tests passed.
# Totals: pass:1 fail:0 xfail:0 xpass:0 skip:0 error:0Kselftest EP Doorbell
~~~~~~~~~~~~~~~~~~~~~
If the Endpoint MSI controller is used for the doorbell usecase, run below
command for testing it:
# pci_endpoint_test -f pcie_ep_doorbell
# Starting 1 tests from 1 test cases.
# RUN pcie_ep_doorbell.DOORBELL_TEST ...
# OK pcie_ep_doorbell.DOORBELL_TEST
ok 1 pcie_ep_doorbell.DOORBELL_TEST
# PASSED: 1 / 1 tests passed.
# Totals: pass:1 fail:0 xfail:0 xpass:0 skip:0 error:0
요약·해설
pci-test-howto.rst:1-220EP에서 test function의 PCI ID와 interrupt 수를 설정해 controller에 bind·start하고, host에서 16개 기본 Kselftest와 선택적 doorbell test를 실행합니다.
DMA MEMCPY가 없는 controller에서는 `dma.COPY_TEST`를 제외해야 합니다.