tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

kernel / Documentation / PCI / endpoint / pci-endpoint.rst
at v6.14-rc2 260 lines 8.7 kB view raw
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 120* pci_epc_map_addr() 121 122 A PCI endpoint function driver should use pci_epc_map_addr() to map to a RC 123 PCI address the CPU address of local memory obtained with 124 pci_epc_mem_alloc_addr(). 125 126* pci_epc_unmap_addr() 127 128 A PCI endpoint function driver should use pci_epc_unmap_addr() to unmap the 129 CPU address of local memory mapped to a RC address with pci_epc_map_addr(). 130 131* pci_epc_mem_map() 132 133 A PCI endpoint controller may impose constraints on the RC PCI addresses that 134 can be mapped. The function pci_epc_mem_map() allows endpoint function 135 drivers to allocate and map controller memory while handling such 136 constraints. This function will determine the size of the memory that must be 137 allocated with pci_epc_mem_alloc_addr() for successfully mapping a RC PCI 138 address range. This function will also indicate the size of the PCI address 139 range that was actually mapped, which can be less than the requested size, as 140 well as the offset into the allocated memory to use for accessing the mapped 141 RC PCI address range. 142 143* pci_epc_mem_unmap() 144 145 A PCI endpoint function driver can use pci_epc_mem_unmap() to unmap and free 146 controller memory that was allocated and mapped using pci_epc_mem_map(). 147 148 149Other EPC APIs 150~~~~~~~~~~~~~~ 151 152There are other APIs provided by the EPC library. These are used for binding 153the EPF device with EPC device. pci-ep-cfs.c can be used as reference for 154using these APIs. 155 156* pci_epc_get() 157 158 Get a reference to the PCI endpoint controller based on the device name of 159 the controller. 160 161* pci_epc_put() 162 163 Release the reference to the PCI endpoint controller obtained using 164 pci_epc_get() 165 166* pci_epc_add_epf() 167 168 Add a PCI endpoint function to a PCI endpoint controller. A PCIe device 169 can have up to 8 functions according to the specification. 170 171* pci_epc_remove_epf() 172 173 Remove the PCI endpoint function from PCI endpoint controller. 174 175* pci_epc_start() 176 177 The PCI endpoint function driver should invoke pci_epc_start() once it 178 has configured the endpoint function and wants to start the PCI link. 179 180* pci_epc_stop() 181 182 The PCI endpoint function driver should invoke pci_epc_stop() to stop 183 the PCI LINK. 184 185 186PCI Endpoint Function(EPF) Library 187---------------------------------- 188 189The EPF library provides APIs to be used by the function driver and the EPC 190library to provide endpoint mode functionality. 191 192EPF APIs for the PCI Endpoint Function Driver 193~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 194 195This section lists the APIs that the PCI Endpoint core provides to be used 196by the PCI endpoint function driver. 197 198* pci_epf_register_driver() 199 200 The PCI Endpoint Function driver should implement the following ops: 201 * bind: ops to perform when a EPC device has been bound to EPF device 202 * unbind: ops to perform when a binding has been lost between a EPC 203 device and EPF device 204 * add_cfs: optional ops to create function specific configfs 205 attributes 206 207 The PCI Function driver can then register the PCI EPF driver by using 208 pci_epf_register_driver(). 209 210* pci_epf_unregister_driver() 211 212 The PCI Function driver can unregister the PCI EPF driver by using 213 pci_epf_unregister_driver(). 214 215* pci_epf_alloc_space() 216 217 The PCI Function driver can allocate space for a particular BAR using 218 pci_epf_alloc_space(). 219 220* pci_epf_free_space() 221 222 The PCI Function driver can free the allocated space 223 (using pci_epf_alloc_space) by invoking pci_epf_free_space(). 224 225APIs for the PCI Endpoint Controller Library 226~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 227 228This section lists the APIs that the PCI Endpoint core provides to be used 229by the PCI endpoint controller library. 230 231* pci_epf_linkup() 232 233 The PCI endpoint controller library invokes pci_epf_linkup() when the 234 EPC device has established the connection to the host. 235 236Other EPF APIs 237~~~~~~~~~~~~~~ 238 239There are other APIs provided by the EPF library. These are used to notify 240the function driver when the EPF device is bound to the EPC device. 241pci-ep-cfs.c can be used as reference for using these APIs. 242 243* pci_epf_create() 244 245 Create a new PCI EPF device by passing the name of the PCI EPF device. 246 This name will be used to bind the EPF device to a EPF driver. 247 248* pci_epf_destroy() 249 250 Destroy the created PCI EPF device. 251 252* pci_epf_bind() 253 254 pci_epf_bind() should be invoked when the EPF device has been bound to 255 a EPC device. 256 257* pci_epf_unbind() 258 259 pci_epf_unbind() should be invoked when the binding between EPC device 260 and EPF device is lost.