Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
1 PCI ENDPOINT FRAMEWORK 2 Kishon Vijay Abraham I <kishon@ti.com> 3 4 This document is a guide to use the PCI Endpoint Framework in order to create 5 endpoint controller driver, endpoint function driver, and using configfs 6 interface to bind the function driver to the controller driver. 7 8 1. Introduction 9 10 Linux has a comprehensive PCI subsystem to support PCI controllers that 11 operates in Root Complex mode. The subsystem has capability to scan PCI bus, 12 assign memory resources and IRQ resources, load PCI driver (based on 13 vendor ID, device ID), support other services like hot-plug, power management, 14 advanced error reporting and virtual channels. 15 16 However the PCI controller IP integrated in some SoCs is capable of operating 17 either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will 18 add endpoint mode support in Linux. This will help to run Linux in an 19 EP system which can have a wide variety of use cases from testing or 20 validation, co-processor accelerator, etc. 21 22 2. PCI Endpoint Core 23 24 The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller 25 library, the Endpoint Function library, and the configfs layer to bind the 26 endpoint function with the endpoint controller. 27 28 2.1 PCI Endpoint Controller(EPC) Library 29 30 The EPC library provides APIs to be used by the controller that can operate 31 in endpoint mode. It also provides APIs to be used by function driver/library 32 in order to implement a particular endpoint function. 33 34 2.1.1 APIs for the PCI controller Driver 35 36 This section lists the APIs that the PCI Endpoint core provides to be used 37 by 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 74 2.1.2 APIs for the PCI Endpoint Function Driver 75 76 This section lists the APIs that the PCI Endpoint core provides to be used 77 by 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 112 2.1.3 Other APIs 113 114 There are other APIs provided by the EPC library. These are used for binding 115 the EPF device with EPC device. pci-ep-cfs.c can be used as reference for 116 using 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 147 2.2 PCI Endpoint Function(EPF) Library 148 149 The EPF library provides APIs to be used by the function driver and the EPC 150 library to provide endpoint mode functionality. 151 152 2.2.1 APIs for the PCI Endpoint Function Driver 153 154 This section lists the APIs that the PCI Endpoint core provides to be used 155 by 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 184 2.2.2 APIs for the PCI Endpoint Controller Library 185 This section lists the APIs that the PCI Endpoint core provides to be used 186 by 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 193 2.2.2 Other APIs 194 There are other APIs provided by the EPF library. These are used to notify 195 the function driver when the EPF device is bound to the EPC device. 196 pci-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.