Documentation/PCI/endpoint/pci-endpoint.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 :Author: Kishon Vijay Abraham I <kishon@ti.com>
   4
   5 This document is a guide to use the PCI Endpoint Framework in order to create
   6 endpoint controller driver, endpoint function driver, and using configfs
   7 interface to bind the function driver to the controller driver.
   8
   9 Introduction
  10 ============
  11
  12 Linux has a comprehensive PCI subsystem to support PCI controllers that
  13 operates in Root Complex mode. The subsystem has capability to scan PCI bus,
  14 assign memory resources and IRQ resources, load PCI driver (based on
  15 vendor ID, device ID), support other services like hot-plug, power management,
  16 advanced error reporting and virtual channels.
  17
  18 However the PCI controller IP integrated in some SoCs is capable of operating
  19 either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will
  20 add endpoint mode support in Linux. This will help to run Linux in an
  21 EP system which can have a wide variety of use cases from testing or
  22 validation, co-processor accelerator, etc.
  23
  24 PCI Endpoint Core
  25 =================
  26
  27 The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
  28 library, the Endpoint Function library, and the configfs layer to bind the
  29 endpoint function with the endpoint controller.
  30
  31 PCI Endpoint Controller(EPC) Library
  32 ------------------------------------
  33
  34 The EPC library provides APIs to be used by the controller that can operate
  35 in endpoint mode. It also provides APIs to be used by function driver/library
  36 in order to implement a particular endpoint function.
  37
  38 APIs for the PCI controller Driver
  39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  40
  41 This section lists the APIs that the PCI Endpoint core provides to be used
  42 by 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
  81 EPC APIs for the PCI Endpoint Function Driver
  82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  83
  84 This section lists the APIs that the PCI Endpoint core provides to be used
  85 by 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
 149 Other EPC APIs
 150 ~~~~~~~~~~~~~~
 151
 152 There are other APIs provided by the EPC library. These are used for binding
 153 the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
 154 using 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
 186 PCI Endpoint Function(EPF) Library
 187 ----------------------------------
 188
 189 The EPF library provides APIs to be used by the function driver and the EPC
 190 library to provide endpoint mode functionality.
 191
 192 EPF APIs for the PCI Endpoint Function Driver
 193 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 194
 195 This section lists the APIs that the PCI Endpoint core provides to be used
 196 by 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
 225 APIs for the PCI Endpoint Controller Library
 226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 227
 228 This section lists the APIs that the PCI Endpoint core provides to be used
 229 by 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
 236 Other EPF APIs
 237 ~~~~~~~~~~~~~~
 238
 239 There are other APIs provided by the EPF library. These are used to notify
 240 the function driver when the EPF device is bound to the EPC device.
 241 pci-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.