Documentation/PCI/endpoint/pci-vntb-howto.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===================================================================
   4 PCI Non-Transparent Bridge (NTB) Endpoint Function (EPF) User Guide
   5 ===================================================================
   6
   7 :Author: Frank Li <Frank.Li@nxp.com>
   8
   9 This document is a guide to help users use pci-epf-vntb function driver
  10 and ntb_hw_epf host driver for NTB functionality. The list of steps to
  11 be followed in the host side and EP side is given below. For the hardware
  12 configuration and internals of NTB using configurable endpoints see
  13 Documentation/PCI/endpoint/pci-vntb-function.rst
  14
  15 Endpoint Device
  16 ===============
  17
  18 Endpoint Controller Devices
  19 ---------------------------
  20
  21 To find the list of endpoint controller devices in the system::
  22
  23         # ls /sys/class/pci_epc/
  24           5f010000.pcie_ep
  25
  26 If PCI_ENDPOINT_CONFIGFS is enabled::
  27
  28         # ls /sys/kernel/config/pci_ep/controllers
  29           5f010000.pcie_ep
  30
  31 Endpoint Function Drivers
  32 -------------------------
  33
  34 To find the list of endpoint function drivers in the system::
  35
  36         # ls /sys/bus/pci-epf/drivers
  37         pci_epf_ntb  pci_epf_test  pci_epf_vntb
  38
  39 If PCI_ENDPOINT_CONFIGFS is enabled::
  40
  41         # ls /sys/kernel/config/pci_ep/functions
  42         pci_epf_ntb  pci_epf_test  pci_epf_vntb
  43
  44
  45 Creating pci-epf-vntb Device
  46 ----------------------------
  47
  48 PCI endpoint function device can be created using the configfs. To create
  49 pci-epf-vntb device, the following commands can be used::
  50
  51         # mount -t configfs none /sys/kernel/config
  52         # cd /sys/kernel/config/pci_ep/
  53         # mkdir functions/pci_epf_vntb/func1
  54
  55 The "mkdir func1" above creates the pci-epf-ntb function device that will
  56 be probed by pci_epf_vntb driver.
  57
  58 The PCI endpoint framework populates the directory with the following
  59 configurable fields::
  60
  61         # ls functions/pci_epf_ntb/func1
  62         baseclass_code    deviceid          msi_interrupts    pci-epf-ntb.0
  63         progif_code       secondary         subsys_id         vendorid
  64         cache_line_size   interrupt_pin     msix_interrupts   primary
  65         revid             subclass_code     subsys_vendor_id
  66
  67 The PCI endpoint function driver populates these entries with default values
  68 when the device is bound to the driver. The pci-epf-vntb driver populates
  69 vendorid with 0xffff and interrupt_pin with 0x0001::
  70
  71         # cat functions/pci_epf_vntb/func1/vendorid
  72         0xffff
  73         # cat functions/pci_epf_vntb/func1/interrupt_pin
  74         0x0001
  75
  76
  77 Configuring pci-epf-vntb Device
  78 -------------------------------
  79
  80 The user can configure the pci-epf-vntb device using its configfs entry. In order
  81 to change the vendorid and the deviceid, the following
  82 commands can be used::
  83
  84         # echo 0x1957 > functions/pci_epf_vntb/func1/vendorid
  85         # echo 0x0809 > functions/pci_epf_vntb/func1/deviceid
  86
  87 The PCI endpoint framework also automatically creates a sub-directory in the
  88 function attribute directory. This sub-directory has the same name as the name
  89 of the function device and is populated with the following NTB specific
  90 attributes that can be configured by the user::
  91
  92         # ls functions/pci_epf_vntb/func1/pci_epf_vntb.0/
  93         db_count    mw1         mw2         mw3         mw4         num_mws
  94         spad_count
  95
  96 A sample configuration for NTB function is given below::
  97
  98         # echo 4 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/db_count
  99         # echo 128 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/spad_count
 100         # echo 1 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/num_mws
 101         # echo 0x100000 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/mw1
 102
 103 A sample configuration for virtual NTB driver for virtual PCI bus::
 104
 105         # echo 0x1957 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/vntb_vid
 106         # echo 0x080A > functions/pci_epf_vntb/func1/pci_epf_vntb.0/vntb_pid
 107         # echo 0x10 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/vbus_number
 108
 109 Binding pci-epf-ntb Device to EP Controller
 110 --------------------------------------------
 111
 112 NTB function device should be attached to PCI endpoint controllers
 113 connected to the host.
 114
 115         # ln -s controllers/5f010000.pcie_ep functions/pci-epf-ntb/func1/primary
 116
 117 Once the above step is completed, the PCI endpoint controllers are ready to
 118 establish a link with the host.
 119
 120
 121 Start the Link
 122 --------------
 123
 124 In order for the endpoint device to establish a link with the host, the _start_
 125 field should be populated with '1'. For NTB, both the PCI endpoint controllers
 126 should establish link with the host (imx8 don't need this steps)::
 127
 128         # echo 1 > controllers/5f010000.pcie_ep/start
 129
 130 RootComplex Device
 131 ==================
 132
 133 lspci Output at Host side
 134 -------------------------
 135
 136 Note that the devices listed here correspond to the values populated in
 137 "Creating pci-epf-ntb Device" section above::
 138
 139         # lspci
 140         00:00.0 PCI bridge: Freescale Semiconductor Inc Device 0000 (rev 01)
 141         01:00.0 RAM memory: Freescale Semiconductor Inc Device 0809
 142
 143 Endpoint Device / Virtual PCI bus
 144 =================================
 145
 146 lspci Output at EP Side / Virtual PCI bus
 147 -----------------------------------------
 148
 149 Note that the devices listed here correspond to the values populated in
 150 "Creating pci-epf-ntb Device" section above::
 151
 152         # lspci
 153         10:00.0 Unassigned class [ffff]: Dawicontrol Computersysteme GmbH Device 1234 (rev ff)
 154
 155 Using ntb_hw_epf Device
 156 -----------------------
 157
 158 The host side software follows the standard NTB software architecture in Linux.
 159 All the existing client side NTB utilities like NTB Transport Client and NTB
 160 Netdev, NTB Ping Pong Test Client and NTB Tool Test Client can be used with NTB
 161 function device.
 162
 163 For more information on NTB see
 164 :doc:`Non-Transparent Bridge <../../driver-api/ntb>`