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 Other EPC APIs
 121 ~~~~~~~~~~~~~~
 122
 123 There are other APIs provided by the EPC library. These are used for binding
 124 the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
 125 using 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
 157 PCI Endpoint Function(EPF) Library
 158 ----------------------------------
 159
 160 The EPF library provides APIs to be used by the function driver and the EPC
 161 library to provide endpoint mode functionality.
 162
 163 EPF APIs for the PCI Endpoint Function Driver
 164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 165
 166 This section lists the APIs that the PCI Endpoint core provides to be used
 167 by 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
 196 APIs for the PCI Endpoint Controller Library
 197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 198
 199 This section lists the APIs that the PCI Endpoint core provides to be used
 200 by 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
 207 Other EPF APIs
 208 ~~~~~~~~~~~~~~
 209
 210 There are other APIs provided by the EPF library. These are used to notify
 211 the function driver when the EPF device is bound to the EPC device.
 212 pci-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.