Documentation/PCI/endpoint/pci-endpoint.txt

   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.