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