Documentation/PCI/endpoint/pci-endpoint-cfs.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =======================================
   4 Configuring PCI Endpoint Using CONFIGFS
   5 =======================================
   6
   7 :Author: Kishon Vijay Abraham I <kishon@ti.com>
   8
   9 The PCI Endpoint Core exposes configfs entry (pci_ep) to configure the
  10 PCI endpoint function and to bind the endpoint function
  11 with the endpoint controller. (For introducing other mechanisms to
  12 configure the PCI Endpoint Function refer to [1]).
  13
  14 Mounting configfs
  15 =================
  16
  17 The PCI Endpoint Core layer creates pci_ep directory in the mounted configfs
  18 directory. configfs can be mounted using the following command::
  19
  20         mount -t configfs none /sys/kernel/config
  21
  22 Directory Structure
  23 ===================
  24
  25 The pci_ep configfs has two directories at its root: controllers and
  26 functions. Every EPC device present in the system will have an entry in
  27 the *controllers* directory and every EPF driver present in the system
  28 will have an entry in the *functions* directory.
  29 ::
  30
  31         /sys/kernel/config/pci_ep/
  32                 .. controllers/
  33                 .. functions/
  34
  35 Creating EPF Device
  36 ===================
  37
  38 Every registered EPF driver will be listed in controllers directory. The
  39 entries corresponding to EPF driver will be created by the EPF core.
  40 ::
  41
  42         /sys/kernel/config/pci_ep/functions/
  43                 .. <EPF Driver1>/
  44                         ... <EPF Device 11>/
  45                         ... <EPF Device 21>/
  46                 .. <EPF Driver2>/
  47                         ... <EPF Device 12>/
  48                         ... <EPF Device 22>/
  49
  50 In order to create a <EPF device> of the type probed by <EPF Driver>, the
  51 user has to create a directory inside <EPF DriverN>.
  52
  53 Every <EPF device> directory consists of the following entries that can be
  54 used to configure the standard configuration header of the endpoint function.
  55 (These entries are created by the framework when any new <EPF Device> is
  56 created)
  57 ::
  58
  59                 .. <EPF Driver1>/
  60                         ... <EPF Device 11>/
  61                                 ... vendorid
  62                                 ... deviceid
  63                                 ... revid
  64                                 ... progif_code
  65                                 ... subclass_code
  66                                 ... baseclass_code
  67                                 ... cache_line_size
  68                                 ... subsys_vendor_id
  69                                 ... subsys_id
  70                                 ... interrupt_pin
  71                                 ... primary/
  72                                         ... <Symlink EPC Device1>/
  73                                 ... secondary/
  74                                         ... <Symlink EPC Device2>/
  75
  76 If an EPF device has to be associated with 2 EPCs (like in the case of
  77 Non-transparent bridge), symlink of endpoint controller connected to primary
  78 interface should be added in 'primary' directory and symlink of endpoint
  79 controller connected to secondary interface should be added in 'secondary'
  80 directory.
  81
  82 EPC Device
  83 ==========
  84
  85 Every registered EPC device will be listed in controllers directory. The
  86 entries corresponding to EPC device will be created by the EPC core.
  87 ::
  88
  89         /sys/kernel/config/pci_ep/controllers/
  90                 .. <EPC Device1>/
  91                         ... <Symlink EPF Device11>/
  92                         ... <Symlink EPF Device12>/
  93                         ... start
  94                 .. <EPC Device2>/
  95                         ... <Symlink EPF Device21>/
  96                         ... <Symlink EPF Device22>/
  97                         ... start
  98
  99 The <EPC Device> directory will have a list of symbolic links to
 100 <EPF Device>. These symbolic links should be created by the user to
 101 represent the functions present in the endpoint device.
 102
 103 The <EPC Device> directory will also have a *start* field. Once
 104 "1" is written to this field, the endpoint device will be ready to
 105 establish the link with the host. This is usually done after
 106 all the EPF devices are created and linked with the EPC device.
 107 ::
 108
 109                          | controllers/
 110                                 | <Directory: EPC name>/
 111                                         | <Symbolic Link: Function>
 112                                         | start
 113                          | functions/
 114                                 | <Directory: EPF driver>/
 115                                         | <Directory: EPF device>/
 116                                                 | vendorid
 117                                                 | deviceid
 118                                                 | revid
 119                                                 | progif_code
 120                                                 | subclass_code
 121                                                 | baseclass_code
 122                                                 | cache_line_size
 123                                                 | subsys_vendor_id
 124                                                 | subsys_id
 125                                                 | interrupt_pin
 126                                                 | function
 127
 128 [1] Documentation/PCI/endpoint/pci-endpoint.rst