0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 :Author: Kishon Vijay Abraham I <kishon@ti.com>
0004
0005 This document is a guide to use the PCI Endpoint Framework in order to create
0006 endpoint controller driver, endpoint function driver, and using configfs
0007 interface to bind the function driver to the controller driver.
0008
0009 Introduction
0010 ============
0011
0012 Linux has a comprehensive PCI subsystem to support PCI controllers that
0013 operates in Root Complex mode. The subsystem has capability to scan PCI bus,
0014 assign memory resources and IRQ resources, load PCI driver (based on
0015 vendor ID, device ID), support other services like hot-plug, power management,
0016 advanced error reporting and virtual channels.
0017
0018 However the PCI controller IP integrated in some SoCs is capable of operating
0019 either in Root Complex mode or Endpoint mode. PCI Endpoint Framework will
0020 add endpoint mode support in Linux. This will help to run Linux in an
0021 EP system which can have a wide variety of use cases from testing or
0022 validation, co-processor accelerator, etc.
0023
0024 PCI Endpoint Core
0025 =================
0026
0027 The PCI Endpoint Core layer comprises 3 components: the Endpoint Controller
0028 library, the Endpoint Function library, and the configfs layer to bind the
0029 endpoint function with the endpoint controller.
0030
0031 PCI Endpoint Controller(EPC) Library
0032 ------------------------------------
0033
0034 The EPC library provides APIs to be used by the controller that can operate
0035 in endpoint mode. It also provides APIs to be used by function driver/library
0036 in order to implement a particular endpoint function.
0037
0038 APIs for the PCI controller Driver
0039 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0040
0041 This section lists the APIs that the PCI Endpoint core provides to be used
0042 by the PCI controller driver.
0043
0044 * devm_pci_epc_create()/pci_epc_create()
0045
0046 The PCI controller driver should implement the following ops:
0047
0048 * write_header: ops to populate configuration space header
0049 * set_bar: ops to configure the BAR
0050 * clear_bar: ops to reset the BAR
0051 * alloc_addr_space: ops to allocate in PCI controller address space
0052 * free_addr_space: ops to free the allocated address space
0053 * raise_irq: ops to raise a legacy, MSI or MSI-X interrupt
0054 * start: ops to start the PCI link
0055 * stop: ops to stop the PCI link
0056
0057 The PCI controller driver can then create a new EPC device by invoking
0058 devm_pci_epc_create()/pci_epc_create().
0059
0060 * devm_pci_epc_destroy()/pci_epc_destroy()
0061
0062 The PCI controller driver can destroy the EPC device created by either
0063 devm_pci_epc_create() or pci_epc_create() using devm_pci_epc_destroy() or
0064 pci_epc_destroy().
0065
0066 * pci_epc_linkup()
0067
0068 In order to notify all the function devices that the EPC device to which
0069 they are linked has established a link with the host, the PCI controller
0070 driver should invoke pci_epc_linkup().
0071
0072 * pci_epc_mem_init()
0073
0074 Initialize the pci_epc_mem structure used for allocating EPC addr space.
0075
0076 * pci_epc_mem_exit()
0077
0078 Cleanup the pci_epc_mem structure allocated during pci_epc_mem_init().
0079
0080
0081 EPC APIs for the PCI Endpoint Function Driver
0082 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0083
0084 This section lists the APIs that the PCI Endpoint core provides to be used
0085 by the PCI endpoint function driver.
0086
0087 * pci_epc_write_header()
0088
0089 The PCI endpoint function driver should use pci_epc_write_header() to
0090 write the standard configuration header to the endpoint controller.
0091
0092 * pci_epc_set_bar()
0093
0094 The PCI endpoint function driver should use pci_epc_set_bar() to configure
0095 the Base Address Register in order for the host to assign PCI addr space.
0096 Register space of the function driver is usually configured
0097 using this API.
0098
0099 * pci_epc_clear_bar()
0100
0101 The PCI endpoint function driver should use pci_epc_clear_bar() to reset
0102 the BAR.
0103
0104 * pci_epc_raise_irq()
0105
0106 The PCI endpoint function driver should use pci_epc_raise_irq() to raise
0107 Legacy Interrupt, MSI or MSI-X Interrupt.
0108
0109 * pci_epc_mem_alloc_addr()
0110
0111 The PCI endpoint function driver should use pci_epc_mem_alloc_addr(), to
0112 allocate memory address from EPC addr space which is required to access
0113 RC's buffer
0114
0115 * pci_epc_mem_free_addr()
0116
0117 The PCI endpoint function driver should use pci_epc_mem_free_addr() to
0118 free the memory space allocated using pci_epc_mem_alloc_addr().
0119
0120 Other EPC APIs
0121 ~~~~~~~~~~~~~~
0122
0123 There are other APIs provided by the EPC library. These are used for binding
0124 the EPF device with EPC device. pci-ep-cfs.c can be used as reference for
0125 using these APIs.
0126
0127 * pci_epc_get()
0128
0129 Get a reference to the PCI endpoint controller based on the device name of
0130 the controller.
0131
0132 * pci_epc_put()
0133
0134 Release the reference to the PCI endpoint controller obtained using
0135 pci_epc_get()
0136
0137 * pci_epc_add_epf()
0138
0139 Add a PCI endpoint function to a PCI endpoint controller. A PCIe device
0140 can have up to 8 functions according to the specification.
0141
0142 * pci_epc_remove_epf()
0143
0144 Remove the PCI endpoint function from PCI endpoint controller.
0145
0146 * pci_epc_start()
0147
0148 The PCI endpoint function driver should invoke pci_epc_start() once it
0149 has configured the endpoint function and wants to start the PCI link.
0150
0151 * pci_epc_stop()
0152
0153 The PCI endpoint function driver should invoke pci_epc_stop() to stop
0154 the PCI LINK.
0155
0156
0157 PCI Endpoint Function(EPF) Library
0158 ----------------------------------
0159
0160 The EPF library provides APIs to be used by the function driver and the EPC
0161 library to provide endpoint mode functionality.
0162
0163 EPF APIs for the PCI Endpoint Function Driver
0164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0165
0166 This section lists the APIs that the PCI Endpoint core provides to be used
0167 by the PCI endpoint function driver.
0168
0169 * pci_epf_register_driver()
0170
0171 The PCI Endpoint Function driver should implement the following ops:
0172 * bind: ops to perform when a EPC device has been bound to EPF device
0173 * unbind: ops to perform when a binding has been lost between a EPC
0174 device and EPF device
0175 * linkup: ops to perform when the EPC device has established a
0176 connection with a host system
0177
0178 The PCI Function driver can then register the PCI EPF driver by using
0179 pci_epf_register_driver().
0180
0181 * pci_epf_unregister_driver()
0182
0183 The PCI Function driver can unregister the PCI EPF driver by using
0184 pci_epf_unregister_driver().
0185
0186 * pci_epf_alloc_space()
0187
0188 The PCI Function driver can allocate space for a particular BAR using
0189 pci_epf_alloc_space().
0190
0191 * pci_epf_free_space()
0192
0193 The PCI Function driver can free the allocated space
0194 (using pci_epf_alloc_space) by invoking pci_epf_free_space().
0195
0196 APIs for the PCI Endpoint Controller Library
0197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0198
0199 This section lists the APIs that the PCI Endpoint core provides to be used
0200 by the PCI endpoint controller library.
0201
0202 * pci_epf_linkup()
0203
0204 The PCI endpoint controller library invokes pci_epf_linkup() when the
0205 EPC device has established the connection to the host.
0206
0207 Other EPF APIs
0208 ~~~~~~~~~~~~~~
0209
0210 There are other APIs provided by the EPF library. These are used to notify
0211 the function driver when the EPF device is bound to the EPC device.
0212 pci-ep-cfs.c can be used as reference for using these APIs.
0213
0214 * pci_epf_create()
0215
0216 Create a new PCI EPF device by passing the name of the PCI EPF device.
0217 This name will be used to bind the EPF device to a EPF driver.
0218
0219 * pci_epf_destroy()
0220
0221 Destroy the created PCI EPF device.
0222
0223 * pci_epf_bind()
0224
0225 pci_epf_bind() should be invoked when the EPF device has been bound to
0226 a EPC device.
0227
0228 * pci_epf_unbind()
0229
0230 pci_epf_unbind() should be invoked when the binding between EPC device
0231 and EPF device is lost.
