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 120Other EPC APIs 121~~~~~~~~~~~~~~ 122 123There are other APIs provided by the EPC library. These are used for binding 124the EPF device with EPC device. pci-ep-cfs.c can be used as reference for 125using these APIs. 126 127* pci_epc_get() 128 129 Get a reference to the PCI endpoint controller based on the device name of 130 the controller. 131 132* pci_epc_put() 133 134 Release the reference to the PCI endpoint controller obtained using 135 pci_epc_get() 136 137* pci_epc_add_epf() 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 142* pci_epc_remove_epf() 143 144 Remove the PCI endpoint function from PCI endpoint controller. 145 146* pci_epc_start() 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 151* pci_epc_stop() 152 153 The PCI endpoint function driver should invoke pci_epc_stop() to stop 154 the PCI LINK. 155 156 157PCI Endpoint Function(EPF) Library 158---------------------------------- 159 160The EPF library provides APIs to be used by the function driver and the EPC 161library to provide endpoint mode functionality. 162 163EPF APIs for the PCI Endpoint Function Driver 164~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 165 166This section lists the APIs that the PCI Endpoint core provides to be used 167by the PCI endpoint function driver. 168 169* pci_epf_register_driver() 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 181* pci_epf_unregister_driver() 182 183 The PCI Function driver can unregister the PCI EPF driver by using 184 pci_epf_unregister_driver(). 185 186* pci_epf_alloc_space() 187 188 The PCI Function driver can allocate space for a particular BAR using 189 pci_epf_alloc_space(). 190 191* pci_epf_free_space() 192 193 The PCI Function driver can free the allocated space 194 (using pci_epf_alloc_space) by invoking pci_epf_free_space(). 195 196APIs for the PCI Endpoint Controller Library 197~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 198 199This section lists the APIs that the PCI Endpoint core provides to be used 200by the PCI endpoint controller library. 201 202* pci_epf_linkup() 203 204 The PCI endpoint controller library invokes pci_epf_linkup() when the 205 EPC device has established the connection to the host. 206 207Other EPF APIs 208~~~~~~~~~~~~~~ 209 210There are other APIs provided by the EPF library. These are used to notify 211the function driver when the EPF device is bound to the EPC device. 212pci-ep-cfs.c can be used as reference for using these APIs. 213 214* pci_epf_create() 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 EPF device to a EPF driver. 218 219* pci_epf_destroy() 220 221 Destroy the created PCI EPF device. 222 223* pci_epf_bind() 224 225 pci_epf_bind() should be invoked when the EPF device has been bound to 226 a EPC device. 227 228* pci_epf_unbind() 229 230 pci_epf_unbind() should be invoked when the binding between EPC device 231 and EPF device is lost. 232