1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 :Author: Kishon Vijay Abraham I <kishon@ti.com> 3 :Author: Kishon Vijay Abraham I <kishon@ti.com>
4 4
5 This document is a guide to use the PCI Endpoi 5 This document is a guide to use the PCI Endpoint Framework in order to create
6 endpoint controller driver, endpoint function 6 endpoint controller driver, endpoint function driver, and using configfs
7 interface to bind the function driver to the c 7 interface to bind the function driver to the controller driver.
8 8
9 Introduction 9 Introduction
10 ============ 10 ============
11 11
12 Linux has a comprehensive PCI subsystem to sup 12 Linux has a comprehensive PCI subsystem to support PCI controllers that
13 operates in Root Complex mode. The subsystem h 13 operates in Root Complex mode. The subsystem has capability to scan PCI bus,
14 assign memory resources and IRQ resources, loa 14 assign memory resources and IRQ resources, load PCI driver (based on
15 vendor ID, device ID), support other services 15 vendor ID, device ID), support other services like hot-plug, power management,
16 advanced error reporting and virtual channels. 16 advanced error reporting and virtual channels.
17 17
18 However the PCI controller IP integrated in so 18 However the PCI controller IP integrated in some SoCs is capable of operating
19 either in Root Complex mode or Endpoint mode. 19 either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will
20 add endpoint mode support in Linux. This will 20 add endpoint mode support in Linux. This will help to run Linux in an
21 EP system which can have a wide variety of use 21 EP system which can have a wide variety of use cases from testing or
22 validation, co-processor accelerator, etc. 22 validation, co-processor accelerator, etc.
23 23
24 PCI Endpoint Core 24 PCI Endpoint Core
25 ================= 25 =================
26 26
27 The PCI Endpoint Core layer comprises 3 compon 27 The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
28 library, the Endpoint Function library, and th 28 library, the Endpoint Function library, and the configfs layer to bind the
29 endpoint function with the endpoint controller 29 endpoint function with the endpoint controller.
30 30
31 PCI Endpoint Controller(EPC) Library 31 PCI Endpoint Controller(EPC) Library
32 ------------------------------------ 32 ------------------------------------
33 33
34 The EPC library provides APIs to be used by th 34 The EPC library provides APIs to be used by the controller that can operate
35 in endpoint mode. It also provides APIs to be 35 in endpoint mode. It also provides APIs to be used by function driver/library
36 in order to implement a particular endpoint fu 36 in order to implement a particular endpoint function.
37 37
38 APIs for the PCI controller Driver 38 APIs for the PCI controller Driver
39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40 40
41 This section lists the APIs that the PCI Endpo 41 This section lists the APIs that the PCI Endpoint core provides to be used
42 by the PCI controller driver. 42 by the PCI controller driver.
43 43
44 * devm_pci_epc_create()/pci_epc_create() 44 * devm_pci_epc_create()/pci_epc_create()
45 45
46 The PCI controller driver should implement 46 The PCI controller driver should implement the following ops:
47 47
48 * write_header: ops to populate confi 48 * write_header: ops to populate configuration space header
49 * set_bar: ops to configure the BAR 49 * set_bar: ops to configure the BAR
50 * clear_bar: ops to reset the BAR 50 * clear_bar: ops to reset the BAR
51 * alloc_addr_space: ops to allocate i 51 * alloc_addr_space: ops to allocate in PCI controller address space
52 * free_addr_space: ops to free the al 52 * free_addr_space: ops to free the allocated address space
53 * raise_irq: ops to raise a legacy, M 53 * raise_irq: ops to raise a legacy, MSI or MSI-X interrupt
54 * start: ops to start the PCI link 54 * start: ops to start the PCI link
55 * stop: ops to stop the PCI link 55 * stop: ops to stop the PCI link
56 56
57 The PCI controller driver can then create a 57 The PCI controller driver can then create a new EPC device by invoking
58 devm_pci_epc_create()/pci_epc_create(). 58 devm_pci_epc_create()/pci_epc_create().
59 59
60 * devm_pci_epc_destroy()/pci_epc_destroy() 60 * devm_pci_epc_destroy()/pci_epc_destroy()
61 61
62 The PCI controller driver can destroy the E 62 The PCI controller driver can destroy the EPC device created by either
63 devm_pci_epc_create() or pci_epc_create() u 63 devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
64 pci_epc_destroy(). 64 pci_epc_destroy().
65 65
66 * pci_epc_linkup() 66 * pci_epc_linkup()
67 67
68 In order to notify all the function devices 68 In order to notify all the function devices that the EPC device to which
69 they are linked has established a link with 69 they are linked has established a link with the host, the PCI controller
70 driver should invoke pci_epc_linkup(). 70 driver should invoke pci_epc_linkup().
71 71
72 * pci_epc_mem_init() 72 * pci_epc_mem_init()
73 73
74 Initialize the pci_epc_mem structure used f 74 Initialize the pci_epc_mem structure used for allocating EPC addr space.
75 75
76 * pci_epc_mem_exit() 76 * pci_epc_mem_exit()
77 77
78 Cleanup the pci_epc_mem structure allocated 78 Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
79 79
80 80
81 EPC APIs for the PCI Endpoint Function Driver !! 81 APIs for the PCI Endpoint Function Driver
82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ !! 82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83 83
84 This section lists the APIs that the PCI Endpo 84 This section lists the APIs that the PCI Endpoint core provides to be used
85 by the PCI endpoint function driver. 85 by the PCI endpoint function driver.
86 86
87 * pci_epc_write_header() 87 * pci_epc_write_header()
88 88
89 The PCI endpoint function driver should use 89 The PCI endpoint function driver should use pci_epc_write_header() to
90 write the standard configuration header to 90 write the standard configuration header to the endpoint controller.
91 91
92 * pci_epc_set_bar() 92 * pci_epc_set_bar()
93 93
94 The PCI endpoint function driver should use 94 The PCI endpoint function driver should use pci_epc_set_bar() to configure
95 the Base Address Register in order for the 95 the Base Address Register in order for the host to assign PCI addr space.
96 Register space of the function driver is us 96 Register space of the function driver is usually configured
97 using this API. 97 using this API.
98 98
99 * pci_epc_clear_bar() 99 * pci_epc_clear_bar()
100 100
101 The PCI endpoint function driver should use 101 The PCI endpoint function driver should use pci_epc_clear_bar() to reset
102 the BAR. 102 the BAR.
103 103
104 * pci_epc_raise_irq() 104 * pci_epc_raise_irq()
105 105
106 The PCI endpoint function driver should use 106 The PCI endpoint function driver should use pci_epc_raise_irq() to raise
107 Legacy Interrupt, MSI or MSI-X Interrupt. 107 Legacy Interrupt, MSI or MSI-X Interrupt.
108 108
109 * pci_epc_mem_alloc_addr() 109 * pci_epc_mem_alloc_addr()
110 110
111 The PCI endpoint function driver should use 111 The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
112 allocate memory address from EPC addr space 112 allocate memory address from EPC addr space which is required to access
113 RC's buffer 113 RC's buffer
114 114
115 * pci_epc_mem_free_addr() 115 * pci_epc_mem_free_addr()
116 116
117 The PCI endpoint function driver should use 117 The PCI endpoint function driver should use pci_epc_mem_free_addr() to
118 free the memory space allocated using pci_e 118 free the memory space allocated using pci_epc_mem_alloc_addr().
119 119
120 Other EPC APIs !! 120 Other APIs
121 ~~~~~~~~~~~~~~ !! 121 ~~~~~~~~~~
122 122
123 There are other APIs provided by the EPC libra 123 There are other APIs provided by the EPC library. These are used for binding
124 the EPF device with EPC device. pci-ep-cfs.c c 124 the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
125 using these APIs. 125 using these APIs.
126 126
127 * pci_epc_get() 127 * pci_epc_get()
128 128
129 Get a reference to the PCI endpoint control 129 Get a reference to the PCI endpoint controller based on the device name of
130 the controller. 130 the controller.
131 131
132 * pci_epc_put() 132 * pci_epc_put()
133 133
134 Release the reference to the PCI endpoint c 134 Release the reference to the PCI endpoint controller obtained using
135 pci_epc_get() 135 pci_epc_get()
136 136
137 * pci_epc_add_epf() 137 * pci_epc_add_epf()
138 138
139 Add a PCI endpoint function to a PCI endpoi 139 Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
140 can have up to 8 functions according to the 140 can have up to 8 functions according to the specification.
141 141
142 * pci_epc_remove_epf() 142 * pci_epc_remove_epf()
143 143
144 Remove the PCI endpoint function from PCI e 144 Remove the PCI endpoint function from PCI endpoint controller.
145 145
146 * pci_epc_start() 146 * pci_epc_start()
147 147
148 The PCI endpoint function driver should inv 148 The PCI endpoint function driver should invoke pci_epc_start() once it
149 has configured the endpoint function and wa 149 has configured the endpoint function and wants to start the PCI link.
150 150
151 * pci_epc_stop() 151 * pci_epc_stop()
152 152
153 The PCI endpoint function driver should inv 153 The PCI endpoint function driver should invoke pci_epc_stop() to stop
154 the PCI LINK. 154 the PCI LINK.
155 155
156 156
157 PCI Endpoint Function(EPF) Library 157 PCI Endpoint Function(EPF) Library
158 ---------------------------------- 158 ----------------------------------
159 159
160 The EPF library provides APIs to be used by th 160 The EPF library provides APIs to be used by the function driver and the EPC
161 library to provide endpoint mode functionality 161 library to provide endpoint mode functionality.
162 162
163 EPF APIs for the PCI Endpoint Function Driver !! 163 APIs for the PCI Endpoint Function Driver
164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ !! 164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165 165
166 This section lists the APIs that the PCI Endpo 166 This section lists the APIs that the PCI Endpoint core provides to be used
167 by the PCI endpoint function driver. 167 by the PCI endpoint function driver.
168 168
169 * pci_epf_register_driver() 169 * pci_epf_register_driver()
170 170
171 The PCI Endpoint Function driver should imp 171 The PCI Endpoint Function driver should implement the following ops:
172 * bind: ops to perform when a EPC dev 172 * bind: ops to perform when a EPC device has been bound to EPF device
173 * unbind: ops to perform when a bindi 173 * unbind: ops to perform when a binding has been lost between a EPC
174 device and EPF device 174 device and EPF device
175 * add_cfs: optional ops to create fun !! 175 * linkup: ops to perform when the EPC device has established a
176 attributes !! 176 connection with a host system
177 177
178 The PCI Function driver can then register th 178 The PCI Function driver can then register the PCI EPF driver by using
179 pci_epf_register_driver(). 179 pci_epf_register_driver().
180 180
181 * pci_epf_unregister_driver() 181 * pci_epf_unregister_driver()
182 182
183 The PCI Function driver can unregister the P 183 The PCI Function driver can unregister the PCI EPF driver by using
184 pci_epf_unregister_driver(). 184 pci_epf_unregister_driver().
185 185
186 * pci_epf_alloc_space() 186 * pci_epf_alloc_space()
187 187
188 The PCI Function driver can allocate space f 188 The PCI Function driver can allocate space for a particular BAR using
189 pci_epf_alloc_space(). 189 pci_epf_alloc_space().
190 190
191 * pci_epf_free_space() 191 * pci_epf_free_space()
192 192
193 The PCI Function driver can free the allocat 193 The PCI Function driver can free the allocated space
194 (using pci_epf_alloc_space) by invoking pci_ 194 (using pci_epf_alloc_space) by invoking pci_epf_free_space().
195 195
196 APIs for the PCI Endpoint Controller Library 196 APIs for the PCI Endpoint Controller Library
197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198 198
199 This section lists the APIs that the PCI Endpo 199 This section lists the APIs that the PCI Endpoint core provides to be used
200 by the PCI endpoint controller library. 200 by the PCI endpoint controller library.
201 201
202 * pci_epf_linkup() 202 * pci_epf_linkup()
203 203
204 The PCI endpoint controller library invokes 204 The PCI endpoint controller library invokes pci_epf_linkup() when the
205 EPC device has established the connection t 205 EPC device has established the connection to the host.
206 206
207 Other EPF APIs !! 207 Other APIs
208 ~~~~~~~~~~~~~~ !! 208 ~~~~~~~~~~
209 209
210 There are other APIs provided by the EPF libra 210 There are other APIs provided by the EPF library. These are used to notify
211 the function driver when the EPF device is bou 211 the function driver when the EPF device is bound to the EPC device.
212 pci-ep-cfs.c can be used as reference for usin 212 pci-ep-cfs.c can be used as reference for using these APIs.
213 213
214 * pci_epf_create() 214 * pci_epf_create()
215 215
216 Create a new PCI EPF device by passing the 216 Create a new PCI EPF device by passing the name of the PCI EPF device.
217 This name will be used to bind the EPF devi !! 217 This name will be used to bind the the EPF device to a EPF driver.
218 218
219 * pci_epf_destroy() 219 * pci_epf_destroy()
220 220
221 Destroy the created PCI EPF device. 221 Destroy the created PCI EPF device.
222 222
223 * pci_epf_bind() 223 * pci_epf_bind()
224 224
225 pci_epf_bind() should be invoked when the E 225 pci_epf_bind() should be invoked when the EPF device has been bound to
226 a EPC device. 226 a EPC device.
227 227
228 * pci_epf_unbind() 228 * pci_epf_unbind()
229 229
230 pci_epf_unbind() should be invoked when the 230 pci_epf_unbind() should be invoked when the binding between EPC device
231 and EPF device is lost. 231 and EPF device is lost.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.