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* devm_pci_epc_destroy()/pci_epc_destroy()
61
62   The PCI controller driver can destroy the EPC device created by either
63   devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
64   pci_epc_destroy().
65
66* pci_epc_linkup()
67
68   In order to notify all the function devices that the EPC device to which
69   they are linked has established a link with the host, the PCI controller
70   driver should invoke pci_epc_linkup().
71
72* pci_epc_mem_init()
73
74   Initialize the pci_epc_mem structure used for allocating EPC addr space.
75
76* pci_epc_mem_exit()
77
78   Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
79
80
81EPC APIs for the PCI Endpoint Function Driver
82~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
83
84This section lists the APIs that the PCI Endpoint core provides to be used
85by the PCI endpoint function driver.
86
87* pci_epc_write_header()
88
89   The PCI endpoint function driver should use pci_epc_write_header() to
90   write the standard configuration header to the endpoint controller.
91
92* pci_epc_set_bar()
93
94   The PCI endpoint function driver should use pci_epc_set_bar() to configure
95   the Base Address Register in order for the host to assign PCI addr space.
96   Register space of the function driver is usually configured
97   using this API.
98
99* pci_epc_clear_bar()
100
101   The PCI endpoint function driver should use pci_epc_clear_bar() to reset
102   the BAR.
103
104* pci_epc_raise_irq()
105
106   The PCI endpoint function driver should use pci_epc_raise_irq() to raise
107   Legacy Interrupt, MSI or MSI-X Interrupt.
108
109* pci_epc_mem_alloc_addr()
110
111   The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
112   allocate memory address from EPC addr space which is required to access
113   RC's buffer
114
115* pci_epc_mem_free_addr()
116
117   The PCI endpoint function driver should use pci_epc_mem_free_addr() to
118   free the memory space allocated using pci_epc_mem_alloc_addr().
119
120Other EPC APIs
121~~~~~~~~~~~~~~
122
123There are other APIs provided by the EPC library. These are used for binding
124the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
125using these APIs.
126
127* pci_epc_get()
128
129   Get a reference to the PCI endpoint controller based on the device name of
130   the controller.
131
132* pci_epc_put()
133
134   Release the reference to the PCI endpoint controller obtained using
135   pci_epc_get()
136
137* pci_epc_add_epf()
138
139   Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
140   can have up to 8 functions according to the specification.
141
142* pci_epc_remove_epf()
143
144   Remove the PCI endpoint function from PCI endpoint controller.
145
146* pci_epc_start()
147
148   The PCI endpoint function driver should invoke pci_epc_start() once it
149   has configured the endpoint function and wants to start the PCI link.
150
151* pci_epc_stop()
152
153   The PCI endpoint function driver should invoke pci_epc_stop() to stop
154   the PCI LINK.
155
156
157PCI Endpoint Function(EPF) Library
158----------------------------------
159
160The EPF library provides APIs to be used by the function driver and the EPC
161library to provide endpoint mode functionality.
162
163EPF APIs for the PCI Endpoint Function Driver
164~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
165
166This section lists the APIs that the PCI Endpoint core provides to be used
167by the PCI endpoint function driver.
168
169* pci_epf_register_driver()
170
171   The PCI Endpoint Function driver should implement the following ops:
172	 * bind: ops to perform when a EPC device has been bound to EPF device
173	 * unbind: ops to perform when a binding has been lost between a EPC
174	   device and EPF device
175	 * linkup: ops to perform when the EPC device has established a
176	   connection with a host system
177
178  The PCI Function driver can then register the PCI EPF driver by using
179  pci_epf_register_driver().
180
181* pci_epf_unregister_driver()
182
183  The PCI Function driver can unregister the PCI EPF driver by using
184  pci_epf_unregister_driver().
185
186* pci_epf_alloc_space()
187
188  The PCI Function driver can allocate space for a particular BAR using
189  pci_epf_alloc_space().
190
191* pci_epf_free_space()
192
193  The PCI Function driver can free the allocated space
194  (using pci_epf_alloc_space) by invoking pci_epf_free_space().
195
196APIs for the PCI Endpoint Controller Library
197~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198
199This section lists the APIs that the PCI Endpoint core provides to be used
200by the PCI endpoint controller library.
201
202* pci_epf_linkup()
203
204   The PCI endpoint controller library invokes pci_epf_linkup() when the
205   EPC device has established the connection to the host.
206
207Other EPF APIs
208~~~~~~~~~~~~~~
209
210There are other APIs provided by the EPF library. These are used to notify
211the function driver when the EPF device is bound to the EPC device.
212pci-ep-cfs.c can be used as reference for using these APIs.
213
214* pci_epf_create()
215
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 device to a EPF driver.
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 EPF device has been bound to
226   a EPC device.
227
228* pci_epf_unbind()
229
230   pci_epf_unbind() should be invoked when the binding between EPC device
231   and EPF device is lost.
232