summaryrefslogtreecommitdiffstats
path: root/Documentation/PCI
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/PCI')
-rw-r--r--Documentation/PCI/endpoint/index.rst10
-rw-r--r--Documentation/PCI/endpoint/pci-endpoint.rst (renamed from Documentation/PCI/endpoint/pci-endpoint.txt)92
-rw-r--r--Documentation/PCI/index.rst1
3 files changed, 65 insertions, 38 deletions
diff --git a/Documentation/PCI/endpoint/index.rst b/Documentation/PCI/endpoint/index.rst
new file mode 100644
index 000000000000..0db4f2fcd7f0
--- /dev/null
+++ b/Documentation/PCI/endpoint/index.rst
@@ -0,0 +1,10 @@
1.. SPDX-License-Identifier: GPL-2.0
2
3======================
4PCI Endpoint Framework
5======================
6
7.. toctree::
8 :maxdepth: 2
9
10 pci-endpoint
diff --git a/Documentation/PCI/endpoint/pci-endpoint.txt b/Documentation/PCI/endpoint/pci-endpoint.rst
index e86a96b66a6a..0e2311b5617b 100644
--- a/Documentation/PCI/endpoint/pci-endpoint.txt
+++ b/Documentation/PCI/endpoint/pci-endpoint.rst
@@ -1,11 +1,13 @@
1 PCI ENDPOINT FRAMEWORK 1.. SPDX-License-Identifier: GPL-2.0
2 Kishon Vijay Abraham I <kishon@ti.com> 2
3:Author: Kishon Vijay Abraham I <kishon@ti.com>
3 4
4This document is a guide to use the PCI Endpoint Framework in order to create 5This document is a guide to use the PCI Endpoint Framework in order to create
5endpoint controller driver, endpoint function driver, and using configfs 6endpoint controller driver, endpoint function driver, and using configfs
6interface to bind the function driver to the controller driver. 7interface to bind the function driver to the controller driver.
7 8
81. Introduction 9Introduction
10============
9 11
10Linux has a comprehensive PCI subsystem to support PCI controllers that 12Linux has a comprehensive PCI subsystem to support PCI controllers that
11operates in Root Complex mode. The subsystem has capability to scan PCI bus, 13operates in Root Complex mode. The subsystem has capability to scan PCI bus,
@@ -19,26 +21,30 @@ add 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 21EP system which can have a wide variety of use cases from testing or
20validation, co-processor accelerator, etc. 22validation, co-processor accelerator, etc.
21 23
222. PCI Endpoint Core 24PCI Endpoint Core
25=================
23 26
24The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller 27The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
25library, the Endpoint Function library, and the configfs layer to bind the 28library, the Endpoint Function library, and the configfs layer to bind the
26endpoint function with the endpoint controller. 29endpoint function with the endpoint controller.
27 30
282.1 PCI Endpoint Controller(EPC) Library 31PCI Endpoint Controller(EPC) Library
32------------------------------------
29 33
30The EPC library provides APIs to be used by the controller that can operate 34The 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 35in endpoint mode. It also provides APIs to be used by function driver/library
32in order to implement a particular endpoint function. 36in order to implement a particular endpoint function.
33 37
342.1.1 APIs for the PCI controller Driver 38APIs for the PCI controller Driver
39~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
35 40
36This section lists the APIs that the PCI Endpoint core provides to be used 41This section lists the APIs that the PCI Endpoint core provides to be used
37by the PCI controller driver. 42by the PCI controller driver.
38 43
39*) devm_pci_epc_create()/pci_epc_create() 44* devm_pci_epc_create()/pci_epc_create()
40 45
41 The PCI controller driver should implement the following ops: 46 The PCI controller driver should implement the following ops:
47
42 * write_header: ops to populate configuration space header 48 * write_header: ops to populate configuration space header
43 * set_bar: ops to configure the BAR 49 * set_bar: ops to configure the BAR
44 * clear_bar: ops to reset the BAR 50 * clear_bar: ops to reset the BAR
@@ -51,110 +57,116 @@ by the PCI controller driver.
51 The PCI controller driver can then create a new EPC device by invoking 57 The PCI controller driver can then create a new EPC device by invoking
52 devm_pci_epc_create()/pci_epc_create(). 58 devm_pci_epc_create()/pci_epc_create().
53 59
54*) devm_pci_epc_destroy()/pci_epc_destroy() 60* devm_pci_epc_destroy()/pci_epc_destroy()
55 61
56 The PCI controller driver can destroy the EPC device created by either 62 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 63 devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
58 pci_epc_destroy(). 64 pci_epc_destroy().
59 65
60*) pci_epc_linkup() 66* pci_epc_linkup()
61 67
62 In order to notify all the function devices that the EPC device to which 68 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 69 they are linked has established a link with the host, the PCI controller
64 driver should invoke pci_epc_linkup(). 70 driver should invoke pci_epc_linkup().
65 71
66*) pci_epc_mem_init() 72* pci_epc_mem_init()
67 73
68 Initialize the pci_epc_mem structure used for allocating EPC addr space. 74 Initialize the pci_epc_mem structure used for allocating EPC addr space.
69 75
70*) pci_epc_mem_exit() 76* pci_epc_mem_exit()
71 77
72 Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init(). 78 Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
73 79
742.1.2 APIs for the PCI Endpoint Function Driver 80
81APIs for the PCI Endpoint Function Driver
82~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75 83
76This section lists the APIs that the PCI Endpoint core provides to be used 84This section lists the APIs that the PCI Endpoint core provides to be used
77by the PCI endpoint function driver. 85by the PCI endpoint function driver.
78 86
79*) pci_epc_write_header() 87* pci_epc_write_header()
80 88
81 The PCI endpoint function driver should use pci_epc_write_header() to 89 The PCI endpoint function driver should use pci_epc_write_header() to
82 write the standard configuration header to the endpoint controller. 90 write the standard configuration header to the endpoint controller.
83 91
84*) pci_epc_set_bar() 92* pci_epc_set_bar()
85 93
86 The PCI endpoint function driver should use pci_epc_set_bar() to configure 94 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. 95 the Base Address Register in order for the host to assign PCI addr space.
88 Register space of the function driver is usually configured 96 Register space of the function driver is usually configured
89 using this API. 97 using this API.
90 98
91*) pci_epc_clear_bar() 99* pci_epc_clear_bar()
92 100
93 The PCI endpoint function driver should use pci_epc_clear_bar() to reset 101 The PCI endpoint function driver should use pci_epc_clear_bar() to reset
94 the BAR. 102 the BAR.
95 103
96*) pci_epc_raise_irq() 104* pci_epc_raise_irq()
97 105
98 The PCI endpoint function driver should use pci_epc_raise_irq() to raise 106 The PCI endpoint function driver should use pci_epc_raise_irq() to raise
99 Legacy Interrupt, MSI or MSI-X Interrupt. 107 Legacy Interrupt, MSI or MSI-X Interrupt.
100 108
101*) pci_epc_mem_alloc_addr() 109* pci_epc_mem_alloc_addr()
102 110
103 The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to 111 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 112 allocate memory address from EPC addr space which is required to access
105 RC's buffer 113 RC's buffer
106 114
107*) pci_epc_mem_free_addr() 115* pci_epc_mem_free_addr()
108 116
109 The PCI endpoint function driver should use pci_epc_mem_free_addr() to 117 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(). 118 free the memory space allocated using pci_epc_mem_alloc_addr().
111 119
1122.1.3 Other APIs 120Other APIs
121~~~~~~~~~~
113 122
114There are other APIs provided by the EPC library. These are used for binding 123There 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 124the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
116using these APIs. 125using these APIs.
117 126
118*) pci_epc_get() 127* pci_epc_get()
119 128
120 Get a reference to the PCI endpoint controller based on the device name of 129 Get a reference to the PCI endpoint controller based on the device name of
121 the controller. 130 the controller.
122 131
123*) pci_epc_put() 132* pci_epc_put()
124 133
125 Release the reference to the PCI endpoint controller obtained using 134 Release the reference to the PCI endpoint controller obtained using
126 pci_epc_get() 135 pci_epc_get()
127 136
128*) pci_epc_add_epf() 137* pci_epc_add_epf()
129 138
130 Add a PCI endpoint function to a PCI endpoint controller. A PCIe device 139 Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
131 can have up to 8 functions according to the specification. 140 can have up to 8 functions according to the specification.
132 141
133*) pci_epc_remove_epf() 142* pci_epc_remove_epf()
134 143
135 Remove the PCI endpoint function from PCI endpoint controller. 144 Remove the PCI endpoint function from PCI endpoint controller.
136 145
137*) pci_epc_start() 146* pci_epc_start()
138 147
139 The PCI endpoint function driver should invoke pci_epc_start() once it 148 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. 149 has configured the endpoint function and wants to start the PCI link.
141 150
142*) pci_epc_stop() 151* pci_epc_stop()
143 152
144 The PCI endpoint function driver should invoke pci_epc_stop() to stop 153 The PCI endpoint function driver should invoke pci_epc_stop() to stop
145 the PCI LINK. 154 the PCI LINK.
146 155
1472.2 PCI Endpoint Function(EPF) Library 156
157PCI Endpoint Function(EPF) Library
158----------------------------------
148 159
149The EPF library provides APIs to be used by the function driver and the EPC 160The EPF library provides APIs to be used by the function driver and the EPC
150library to provide endpoint mode functionality. 161library to provide endpoint mode functionality.
151 162
1522.2.1 APIs for the PCI Endpoint Function Driver 163APIs for the PCI Endpoint Function Driver
164~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153 165
154This section lists the APIs that the PCI Endpoint core provides to be used 166This section lists the APIs that the PCI Endpoint core provides to be used
155by the PCI endpoint function driver. 167by the PCI endpoint function driver.
156 168
157*) pci_epf_register_driver() 169* pci_epf_register_driver()
158 170
159 The PCI Endpoint Function driver should implement the following ops: 171 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 172 * bind: ops to perform when a EPC device has been bound to EPF device
@@ -166,50 +178,54 @@ by the PCI endpoint function driver.
166 The PCI Function driver can then register the PCI EPF driver by using 178 The PCI Function driver can then register the PCI EPF driver by using
167 pci_epf_register_driver(). 179 pci_epf_register_driver().
168 180
169*) pci_epf_unregister_driver() 181* pci_epf_unregister_driver()
170 182
171 The PCI Function driver can unregister the PCI EPF driver by using 183 The PCI Function driver can unregister the PCI EPF driver by using
172 pci_epf_unregister_driver(). 184 pci_epf_unregister_driver().
173 185
174*) pci_epf_alloc_space() 186* pci_epf_alloc_space()
175 187
176 The PCI Function driver can allocate space for a particular BAR using 188 The PCI Function driver can allocate space for a particular BAR using
177 pci_epf_alloc_space(). 189 pci_epf_alloc_space().
178 190
179*) pci_epf_free_space() 191* pci_epf_free_space()
180 192
181 The PCI Function driver can free the allocated space 193 The PCI Function driver can free the allocated space
182 (using pci_epf_alloc_space) by invoking pci_epf_free_space(). 194 (using pci_epf_alloc_space) by invoking pci_epf_free_space().
183 195
1842.2.2 APIs for the PCI Endpoint Controller Library 196APIs for the PCI Endpoint Controller Library
197~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
198
185This section lists the APIs that the PCI Endpoint core provides to be used 199This section lists the APIs that the PCI Endpoint core provides to be used
186by the PCI endpoint controller library. 200by the PCI endpoint controller library.
187 201
188*) pci_epf_linkup() 202* pci_epf_linkup()
189 203
190 The PCI endpoint controller library invokes pci_epf_linkup() when the 204 The PCI endpoint controller library invokes pci_epf_linkup() when the
191 EPC device has established the connection to the host. 205 EPC device has established the connection to the host.
192 206
1932.2.2 Other APIs 207Other APIs
208~~~~~~~~~~
209
194There are other APIs provided by the EPF library. These are used to notify 210There 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. 211the 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. 212pci-ep-cfs.c can be used as reference for using these APIs.
197 213
198*) pci_epf_create() 214* pci_epf_create()
199 215
200 Create a new PCI EPF device by passing the name of the PCI EPF device. 216 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. 217 This name will be used to bind the the EPF device to a EPF driver.
202 218
203*) pci_epf_destroy() 219* pci_epf_destroy()
204 220
205 Destroy the created PCI EPF device. 221 Destroy the created PCI EPF device.
206 222
207*) pci_epf_bind() 223* pci_epf_bind()
208 224
209 pci_epf_bind() should be invoked when the EPF device has been bound to 225 pci_epf_bind() should be invoked when the EPF device has been bound to
210 a EPC device. 226 a EPC device.
211 227
212*) pci_epf_unbind() 228* pci_epf_unbind()
213 229
214 pci_epf_unbind() should be invoked when the binding between EPC device 230 pci_epf_unbind() should be invoked when the binding between EPC device
215 and EPF device is lost. 231 and EPF device is lost.
diff --git a/Documentation/PCI/index.rst b/Documentation/PCI/index.rst
index f54b65b1ca5f..f4c6121868c3 100644
--- a/Documentation/PCI/index.rst
+++ b/Documentation/PCI/index.rst
@@ -15,3 +15,4 @@ Linux PCI Bus Subsystem
15 acpi-info 15 acpi-info
16 pci-error-recovery 16 pci-error-recovery
17 pcieaer-howto 17 pcieaer-howto
18 endpoint/index
generated by cgit v1.2.2 (git 2.25.0) at 2025-10-14 22:40:46 -0400