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