Commit | Line | Data |
---|---|---|
d8946fc3 CD |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | :Author: Kishon Vijay Abraham I <kishon@ti.com> | |
a8a5be09 KVA |
4 | |
5 | This document is a guide to use the PCI Endpoint Framework in order to create | |
6 | endpoint controller driver, endpoint function driver, and using configfs | |
7 | interface to bind the function driver to the controller driver. | |
8 | ||
d8946fc3 CD |
9 | Introduction |
10 | ============ | |
a8a5be09 KVA |
11 | |
12 | Linux has a comprehensive PCI subsystem to support PCI controllers that | |
13 | operates in Root Complex mode. The subsystem has capability to scan PCI bus, | |
14 | assign memory resources and IRQ resources, load PCI driver (based on | |
15 | vendor ID, device ID), support other services like hot-plug, power management, | |
16 | advanced error reporting and virtual channels. | |
17 | ||
18 | However the PCI controller IP integrated in some SoCs is capable of operating | |
19 | either in Root Complex mode or Endpoint mode. PCI Endpoint Framework 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 cases from testing or | |
22 | validation, co-processor accelerator, etc. | |
23 | ||
d8946fc3 CD |
24 | PCI Endpoint Core |
25 | ================= | |
a8a5be09 KVA |
26 | |
27 | The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller | |
28 | library, the Endpoint Function library, and the configfs layer to bind the | |
29 | endpoint function with the endpoint controller. | |
30 | ||
d8946fc3 CD |
31 | PCI Endpoint Controller(EPC) Library |
32 | ------------------------------------ | |
a8a5be09 KVA |
33 | |
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 used by function driver/library | |
36 | in order to implement a particular endpoint function. | |
37 | ||
d8946fc3 CD |
38 | APIs for the PCI controller Driver |
39 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
a8a5be09 KVA |
40 | |
41 | This section lists the APIs that the PCI Endpoint core provides to be used | |
42 | by the PCI controller driver. | |
43 | ||
d8946fc3 | 44 | * devm_pci_epc_create()/pci_epc_create() |
a8a5be09 KVA |
45 | |
46 | The PCI controller driver should implement the following ops: | |
d8946fc3 | 47 | |
a8a5be09 KVA |
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 | |
c2e00e31 | 53 | * raise_irq: ops to raise a legacy, MSI or MSI-X interrupt |
a8a5be09 KVA |
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 | ||
d8946fc3 | 60 | * devm_pci_epc_destroy()/pci_epc_destroy() |
a8a5be09 KVA |
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 | ||
d8946fc3 | 66 | * pci_epc_linkup() |
a8a5be09 KVA |
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 | ||
d8946fc3 | 72 | * pci_epc_mem_init() |
a8a5be09 KVA |
73 | |
74 | Initialize the pci_epc_mem structure used for allocating EPC addr space. | |
75 | ||
d8946fc3 | 76 | * pci_epc_mem_exit() |
a8a5be09 KVA |
77 | |
78 | Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init(). | |
79 | ||
d8946fc3 CD |
80 | |
81 | APIs for the PCI Endpoint Function Driver | |
82 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
a8a5be09 KVA |
83 | |
84 | This section lists the APIs that the PCI Endpoint core provides to be used | |
85 | by the PCI endpoint function driver. | |
86 | ||
d8946fc3 | 87 | * pci_epc_write_header() |
a8a5be09 KVA |
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 | ||
d8946fc3 | 92 | * pci_epc_set_bar() |
a8a5be09 KVA |
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 | ||
d8946fc3 | 99 | * pci_epc_clear_bar() |
a8a5be09 KVA |
100 | |
101 | The PCI endpoint function driver should use pci_epc_clear_bar() to reset | |
102 | the BAR. | |
103 | ||
d8946fc3 | 104 | * pci_epc_raise_irq() |
a8a5be09 KVA |
105 | |
106 | The PCI endpoint function driver should use pci_epc_raise_irq() to raise | |
c2e00e31 | 107 | Legacy Interrupt, MSI or MSI-X Interrupt. |
a8a5be09 | 108 | |
d8946fc3 | 109 | * pci_epc_mem_alloc_addr() |
a8a5be09 KVA |
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 | ||
d8946fc3 | 115 | * pci_epc_mem_free_addr() |
a8a5be09 KVA |
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 | ||
d8946fc3 CD |
120 | Other APIs |
121 | ~~~~~~~~~~ | |
a8a5be09 KVA |
122 | |
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 can be used as reference for | |
125 | using these APIs. | |
126 | ||
d8946fc3 | 127 | * pci_epc_get() |
a8a5be09 KVA |
128 | |
129 | Get a reference to the PCI endpoint controller based on the device name of | |
130 | the controller. | |
131 | ||
d8946fc3 | 132 | * pci_epc_put() |
a8a5be09 KVA |
133 | |
134 | Release the reference to the PCI endpoint controller obtained using | |
135 | pci_epc_get() | |
136 | ||
d8946fc3 | 137 | * pci_epc_add_epf() |
a8a5be09 KVA |
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 | ||
d8946fc3 | 142 | * pci_epc_remove_epf() |
a8a5be09 KVA |
143 | |
144 | Remove the PCI endpoint function from PCI endpoint controller. | |
145 | ||
d8946fc3 | 146 | * pci_epc_start() |
a8a5be09 KVA |
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 | ||
d8946fc3 | 151 | * pci_epc_stop() |
a8a5be09 KVA |
152 | |
153 | The PCI endpoint function driver should invoke pci_epc_stop() to stop | |
154 | the PCI LINK. | |
155 | ||
d8946fc3 CD |
156 | |
157 | PCI Endpoint Function(EPF) Library | |
158 | ---------------------------------- | |
a8a5be09 KVA |
159 | |
160 | The EPF library provides APIs to be used by the function driver and the EPC | |
161 | library to provide endpoint mode functionality. | |
162 | ||
d8946fc3 CD |
163 | APIs for the PCI Endpoint Function Driver |
164 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
a8a5be09 KVA |
165 | |
166 | This section lists the APIs that the PCI Endpoint core provides to be used | |
167 | by the PCI endpoint function driver. | |
168 | ||
d8946fc3 | 169 | * pci_epf_register_driver() |
a8a5be09 KVA |
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 | ||
d8946fc3 | 181 | * pci_epf_unregister_driver() |
a8a5be09 KVA |
182 | |
183 | The PCI Function driver can unregister the PCI EPF driver by using | |
184 | pci_epf_unregister_driver(). | |
185 | ||
d8946fc3 | 186 | * pci_epf_alloc_space() |
a8a5be09 KVA |
187 | |
188 | The PCI Function driver can allocate space for a particular BAR using | |
189 | pci_epf_alloc_space(). | |
190 | ||
d8946fc3 | 191 | * pci_epf_free_space() |
a8a5be09 KVA |
192 | |
193 | The PCI Function driver can free the allocated space | |
194 | (using pci_epf_alloc_space) by invoking pci_epf_free_space(). | |
195 | ||
d8946fc3 CD |
196 | APIs for the PCI Endpoint Controller Library |
197 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
198 | ||
a8a5be09 KVA |
199 | This section lists the APIs that the PCI Endpoint core provides to be used |
200 | by the PCI endpoint controller library. | |
201 | ||
d8946fc3 | 202 | * pci_epf_linkup() |
a8a5be09 KVA |
203 | |
204 | The PCI endpoint controller library invokes pci_epf_linkup() when the | |
205 | EPC device has established the connection to the host. | |
206 | ||
d8946fc3 CD |
207 | Other APIs |
208 | ~~~~~~~~~~ | |
209 | ||
a8a5be09 KVA |
210 | There are other APIs provided by the EPF library. These are used to notify |
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 using these APIs. | |
213 | ||
d8946fc3 | 214 | * pci_epf_create() |
a8a5be09 KVA |
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 the EPF device to a EPF driver. | |
218 | ||
d8946fc3 | 219 | * pci_epf_destroy() |
a8a5be09 KVA |
220 | |
221 | Destroy the created PCI EPF device. | |
222 | ||
d8946fc3 | 223 | * pci_epf_bind() |
a8a5be09 KVA |
224 | |
225 | pci_epf_bind() should be invoked when the EPF device has been bound to | |
226 | a EPC device. | |
227 | ||
d8946fc3 | 228 | * pci_epf_unbind() |
a8a5be09 KVA |
229 | |
230 | pci_epf_unbind() should be invoked when the binding between EPC device | |
231 | and EPF device is lost. |