요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
===================================================================
4
PCI Non-Transparent Bridge (NTB) Endpoint Function (EPF) User Guide
5
===================================================================
7
:Author: Kishon Vijay Abraham I <[email protected]>
9
This document is a guide to help users use pci-epf-ntb function driver
10
and ntb_hw_epf host driver for NTB functionality. The list of steps to
11
be followed in the host side and EP side is given below. For the hardware
12
configuration and internals of NTB using configurable endpoints see
13
Documentation/PCI/endpoint/pci-ntb-function.rst
15
Endpoint Device
16
===============
18
Endpoint Controller Devices
19
---------------------------
21
For implementing NTB functionality at least two endpoint controller devices
22
are required.
24
To find the list of endpoint controller devices in the system::
26
# ls /sys/class/pci_epc/
27
2900000.pcie-ep 2910000.pcie-ep
29
If PCI_ENDPOINT_CONFIGFS is enabled::
31
# ls /sys/kernel/config/pci_ep/controllers
32
2900000.pcie-ep 2910000.pcie-ep
35
Endpoint Function Drivers
36
-------------------------
38
To find the list of endpoint function drivers in the system::
40
# ls /sys/bus/pci-epf/drivers
41
pci_epf_ntb pci_epf_ntb
43
If PCI_ENDPOINT_CONFIGFS is enabled::
45
# ls /sys/kernel/config/pci_ep/functions
46
pci_epf_ntb pci_epf_ntb
49
Creating pci-epf-ntb Device
50
----------------------------
52
PCI endpoint function device can be created using the configfs. To create
53
pci-epf-ntb device, the following commands can be used::
55
# mount -t configfs none /sys/kernel/config
56
# cd /sys/kernel/config/pci_ep/
57
# mkdir functions/pci_epf_ntb/func1
59
The "mkdir func1" above creates the pci-epf-ntb function device that will
60
be probed by pci_epf_ntb driver.
62
The PCI endpoint framework populates the directory with the following
63
configurable fields::
65
# ls functions/pci_epf_ntb/func1
66
baseclass_code deviceid msi_interrupts pci-epf-ntb.0
67
progif_code secondary subsys_id vendorid
68
cache_line_size interrupt_pin msix_interrupts primary
69
revid subclass_code subsys_vendor_id
71
The PCI endpoint function driver populates these entries with default values
72
when the device is bound to the driver. The pci-epf-ntb driver populates
73
vendorid with 0xffff and interrupt_pin with 0x0001::
75
# cat functions/pci_epf_ntb/func1/vendorid
76
0xffff
77
# cat functions/pci_epf_ntb/func1/interrupt_pin
78
0x0001
81
Configuring pci-epf-ntb Device
82
-------------------------------
84
The user can configure the pci-epf-ntb device using its configfs entry. In order
85
to change the vendorid and the deviceid, the following
86
commands can be used::
88
# echo 0x104c > functions/pci_epf_ntb/func1/vendorid
89
# echo 0xb00d > functions/pci_epf_ntb/func1/deviceid
91
The PCI endpoint framework also automatically creates a sub-directory in the
92
function attribute directory. This sub-directory has the same name as the name
93
of the function device and is populated with the following NTB specific
94
attributes that can be configured by the user::
96
# ls functions/pci_epf_ntb/func1/pci_epf_ntb.0/
97
db_count mw1 mw2 mw3 mw4 num_mws
98
spad_count
100
A sample configuration for NTB function is given below::
102
# echo 4 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/db_count
103
# echo 128 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/spad_count
104
# echo 2 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/num_mws
105
# echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw1
106
# echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw2
108
Binding pci-epf-ntb Device to EP Controller
109
--------------------------------------------
111
NTB function device should be attached to two PCI endpoint controllers
112
connected to the two hosts. Use the 'primary' and 'secondary' entries
113
inside NTB function device to attach one PCI endpoint controller to
114
primary interface and the other PCI endpoint controller to the secondary
115
interface::
117
# ln -s controllers/2900000.pcie-ep/ functions/pci-epf-ntb/func1/primary
118
# ln -s controllers/2910000.pcie-ep/ functions/pci-epf-ntb/func1/secondary
120
Once the above step is completed, both the PCI endpoint controllers are ready to
121
establish a link with the host.
124
Start the Link
125
--------------
127
In order for the endpoint device to establish a link with the host, the _start_
128
field should be populated with '1'. For NTB, both the PCI endpoint controllers
129
should establish link with the host::
131
# echo 1 > controllers/2900000.pcie-ep/start
132
# echo 1 > controllers/2910000.pcie-ep/start
135
RootComplex Device
136
==================
138
lspci Output
139
------------
141
Note that the devices listed here correspond to the values populated in
142
"Creating pci-epf-ntb Device" section above::
144
# lspci
145
0000:00:00.0 PCI bridge: Texas Instruments Device b00d
146
0000:01:00.0 RAM memory: Texas Instruments Device b00d
149
Using ntb_hw_epf Device
150
-----------------------
152
The host side software follows the standard NTB software architecture in Linux.
153
All the existing client side NTB utilities like NTB Transport Client and NTB
154
Netdev, NTB Ping Pong Test Client and NTB Tool Test Client can be used with NTB
155
function device.
157
For more information on NTB see
158
:doc:`Non-Transparent Bridge <../../driver-api/ntb>`
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
EPF·host driver 사용 범위
1-14저자는 Kishon Vijay Abraham I입니다. 이 문서는 NTB 기능에 `pci-epf-ntb` function driver와 `ntb_hw_epf` host driver를 사용하는 EP 측·host 측 절차를 안내합니다.
Configurable endpoint를 이용한 NTB hardware 구성과 내부 구조는 `Documentation/PCI/endpoint/pci-ntb-function.rst`를 참조합니다.
.. SPDX-License-Identifier: GPL-2.0
===================================================================
PCI Non-Transparent Bridge (NTB) Endpoint Function (EPF) User Guide
===================================================================
:Author: Kishon Vijay Abraham I <[email protected]>
This document is a guide to help users use pci-epf-ntb function driver
and ntb_hw_epf host driver for NTB functionality. The list of steps to
be followed in the host side and EP side is given below. For the hardware
configuration and internals of NTB using configurable endpoints see
Documentation/PCI/endpoint/pci-ntb-function.rst
Endpoint controller 확인
15-34NTB 기능을 구현하려면 endpoint controller device가 최소 두 개 필요합니다. System class 또는 configfs에서 목록을 확인합니다.
# ls /sys/class/pci_epc/
2900000.pcie-ep 2910000.pcie-ep
# ls /sys/kernel/config/pci_ep/controllers
2900000.pcie-ep 2910000.pcie-ep두 번째 command는 `PCI_ENDPOINT_CONFIGFS`가 활성화됐을 때 사용할 수 있습니다.
Endpoint Device
===============
Endpoint Controller Devices
---------------------------
For implementing NTB functionality at least two endpoint controller devices
are required.
To find the list of endpoint controller devices in the system::
# ls /sys/class/pci_epc/
2900000.pcie-ep 2910000.pcie-ep
If PCI_ENDPOINT_CONFIGFS is enabled::
# ls /sys/kernel/config/pci_ep/controllers
2900000.pcie-ep 2910000.pcie-ep
Endpoint function driver 확인
35-48등록된 endpoint function driver는 PCI EPF bus 또는 configfs에서 확인합니다.
# ls /sys/bus/pci-epf/drivers
pci_epf_ntb
# ls /sys/kernel/config/pci_ep/functions
pci_epf_ntbEndpoint Function Drivers
-------------------------
To find the list of endpoint function drivers in the system::
# ls /sys/bus/pci-epf/drivers
pci_epf_ntb pci_epf_ntb
If PCI_ENDPOINT_CONFIGFS is enabled::
# ls /sys/kernel/config/pci_ep/functions
pci_epf_ntb pci_epf_ntb
pci-epf-ntb device 생성
49-80Configfs를 mount하고 `pci_epf_ntb` 아래에 `func1` directory를 만들면 `pci_epf_ntb` driver가 probe할 function device가 생성됩니다.
# mount -t configfs none /sys/kernel/config
# cd /sys/kernel/config/pci_ep/
# mkdir functions/pci_epf_ntb/func1PCI endpoint framework는 function directory에 standard configuration field와 `primary`, `secondary`, function-specific subdirectory를 채웁니다.
구분Entry
PCI identity/classvendorid, deviceid, revid, progif_code, subclass_code, baseclass_code
Systemcache_line_size, subsys_vendor_id, subsys_id
Interruptinterrupt_pin, msi_interrupts, msix_interrupts
Dual interfaceprimary, secondary
NTB specificpci_epf_ntb.0
`functions/pci_epf_ntb/func1`의 주요 entry입니다.
EPF device가 driver에 bind되면 driver가 default 값을 채웁니다. `pci-epf-ntb`의 기본 `vendorid`는 `0xffff`, `interrupt_pin`은 `0x0001`입니다.
# cat functions/pci_epf_ntb/func1/vendorid
0xffff
# cat functions/pci_epf_ntb/func1/interrupt_pin
0x0001Creating pci-epf-ntb Device
----------------------------
PCI endpoint function device can be created using the configfs. To create
pci-epf-ntb device, the following commands can be used::
# mount -t configfs none /sys/kernel/config
# cd /sys/kernel/config/pci_ep/
# mkdir functions/pci_epf_ntb/func1
The "mkdir func1" above creates the pci-epf-ntb function device that will
be probed by pci_epf_ntb driver.
The PCI endpoint framework populates the directory with the following
configurable fields::
# ls functions/pci_epf_ntb/func1
baseclass_code deviceid msi_interrupts pci-epf-ntb.0
progif_code secondary subsys_id vendorid
cache_line_size interrupt_pin msix_interrupts primary
revid subclass_code subsys_vendor_id
The PCI endpoint function driver populates these entries with default values
when the device is bound to the driver. The pci-epf-ntb driver populates
vendorid with 0xffff and interrupt_pin with 0x0001::
# cat functions/pci_epf_ntb/func1/vendorid
0xffff
# cat functions/pci_epf_ntb/func1/interrupt_pin
0x0001
PCI ID와 NTB resource 구성
81-107Configfs entry를 통해 `vendorid`와 `deviceid`를 TI NTB 예제 값으로 변경합니다.
# echo 0x104c > functions/pci_epf_ntb/func1/vendorid
# echo 0xb00d > functions/pci_epf_ntb/func1/deviceidFramework가 function device name과 같은 `pci_epf_ntb.0` subdirectory를 자동으로 만들고 NTB 전용 configurable attribute를 제공합니다.
Attribute예제 값
db_count4
spad_count128
num_mws2
mw10x100000
mw20x100000
mw3 / mw4미사용
Doorbell, scratchpad와 memory window를 설정합니다.
# echo 4 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/db_count
# echo 128 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/spad_count
# echo 2 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/num_mws
# echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw1
# echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw2Configuring pci-epf-ntb Device
-------------------------------
The user can configure the pci-epf-ntb device using its configfs entry. In order
to change the vendorid and the deviceid, the following
commands can be used::
# echo 0x104c > functions/pci_epf_ntb/func1/vendorid
# echo 0xb00d > functions/pci_epf_ntb/func1/deviceid
The PCI endpoint framework also automatically creates a sub-directory in the
function attribute directory. This sub-directory has the same name as the name
of the function device and is populated with the following NTB specific
attributes that can be configured by the user::
# ls functions/pci_epf_ntb/func1/pci_epf_ntb.0/
db_count mw1 mw2 mw3 mw4 num_mws
spad_count
A sample configuration for NTB function is given below::
# echo 4 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/db_count
# echo 128 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/spad_count
# echo 2 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/num_mws
# echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw1
# echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw2
두 EP controller에 binding
108-123NTB function device는 두 host에 각각 연결된 PCI endpoint controller 두 개에 attach해야 합니다. `primary`와 `secondary` entry에 controller symlink를 만들어 interface를 구분합니다.
# ln -s controllers/2900000.pcie-ep/ functions/pci_epf_ntb/func1/primary
# ln -s controllers/2910000.pcie-ep/ functions/pci_epf_ntb/func1/secondarySymlink가 만들어지면 두 PCI endpoint controller 모두 host와 link를 맺을 준비가 됩니다.
HOST1→2900000.pcie-ep primary→pci_epf_ntb/func1→2910000.pcie-ep secondary→HOST2
하나의 function device가 primary와 secondary controller를 통해 서로 다른 host에 연결됩니다.
Binding pci-epf-ntb Device to EP Controller
--------------------------------------------
NTB function device should be attached to two PCI endpoint controllers
connected to the two hosts. Use the 'primary' and 'secondary' entries
inside NTB function device to attach one PCI endpoint controller to
primary interface and the other PCI endpoint controller to the secondary
interface::
# ln -s controllers/2900000.pcie-ep/ functions/pci-epf-ntb/func1/primary
# ln -s controllers/2910000.pcie-ep/ functions/pci-epf-ntb/func1/secondary
Once the above step is completed, both the PCI endpoint controllers are ready to
establish a link with the host.
두 link 시작
124-134Endpoint device가 host와 link를 맺게 하려면 controller의 `start` field에 `1`을 씁니다. NTB에서는 두 controller를 모두 시작해야 합니다.
# echo 1 > controllers/2900000.pcie-ep/start
# echo 1 > controllers/2910000.pcie-ep/startDiscover EPC + EPF→Create func1→Configure PCI ID + NTB fields→Bind primary + secondary→start = 1 on both EPCs
두 controller가 모두 start된 뒤 양쪽 host가 NTB device를 사용할 수 있습니다.
Start the Link
--------------
In order for the endpoint device to establish a link with the host, the _start_
field should be populated with '1'. For NTB, both the PCI endpoint controllers
should establish link with the host::
# echo 1 > controllers/2900000.pcie-ep/start
# echo 1 > controllers/2910000.pcie-ep/start
Root Complex에서 device 확인
135-148Root Complex의 `lspci`에는 앞에서 설정한 `deviceid` `b00d`가 PCI bridge와 RAM memory function으로 표시됩니다.
# lspci
0000:00:00.0 PCI bridge: Texas Instruments Device b00d
0000:01:00.0 RAM memory: Texas Instruments Device b00dRootComplex Device
==================
lspci Output
------------
Note that the devices listed here correspond to the values populated in
"Creating pci-epf-ntb Device" section above::
# lspci
0000:00:00.0 PCI bridge: Texas Instruments Device b00d
0000:01:00.0 RAM memory: Texas Instruments Device b00d
ntb_hw_epf와 client utility
149-158Host 측 software는 Linux의 표준 NTB software architecture를 따릅니다. NTB function device에는 기존 client utility를 그대로 사용할 수 있습니다.
Client용도
NTB Transport Client / NTB NetdevTransport와 network device
NTB Ping Pong Test ClientDoorbell·scratchpad ping-pong 시험
NTB Tool Test ClientNTB resource 검사
`ntb_hw_epf` device와 함께 사용할 수 있는 client입니다.
NTB에 대한 자세한 내용은 `Non-Transparent Bridge` 문서 `../../driver-api/ntb`를 참조합니다.
Using ntb_hw_epf Device
-----------------------
The host side software follows the standard NTB software architecture in Linux.
All the existing client side NTB utilities like NTB Transport Client and NTB
Netdev, NTB Ping Pong Test Client and NTB Tool Test Client can be used with NTB
function device.
For more information on NTB see
:doc:`Non-Transparent Bridge <../../driver-api/ntb>`
요약·해설
pci-ntb-howto.rst:1-158EP 측에서 NTB function의 PCI ID와 doorbell·scratchpad·memory window를 설정하고 서로 다른 EPC를 primary·secondary에 연결한 뒤 두 link를 모두 시작합니다.
각 Root Complex는 `ntb_hw_epf`를 통해 표준 Linux NTB client와 test utility를 사용할 수 있습니다.