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