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 In order to configure NTB specific attributes, a new sub-directory to func1
  88 should be created::
  89
  90         # mkdir functions/pci_epf_vntb/func1/pci_epf_vntb.0/
  91
  92 The NTB function driver will populate this directory with various attributes
  93 that can be configured by the user::
  94
  95         # ls functions/pci_epf_vntb/func1/pci_epf_vntb.0/
  96         db_count    mw1         mw2         mw3         mw4         num_mws
  97         spad_count
  98
  99 A sample configuration for NTB function is given below::
 100
 101         # echo 4 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/db_count
 102         # echo 128 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/spad_count
 103         # echo 1 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/num_mws
 104         # echo 0x100000 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/mw1
 105
 106 A sample configuration for virtual NTB driver for virutal PCI bus::
 107
 108         # echo 0x1957 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/vntb_vid
 109         # echo 0x080A > functions/pci_epf_vntb/func1/pci_epf_vntb.0/vntb_pid
 110         # echo 0x10 > functions/pci_epf_vntb/func1/pci_epf_vntb.0/vbus_number
 111
 112 Binding pci-epf-ntb Device to EP Controller
 113 --------------------------------------------
 114
 115 NTB function device should be attached to PCI endpoint controllers
 116 connected to the host.
 117
 118         # ln -s controllers/5f010000.pcie_ep functions/pci-epf-ntb/func1/primary
 119
 120 Once the above step is completed, the PCI endpoint controllers are ready to
 121 establish a link with the host.
 122
 123
 124 Start the Link
 125 --------------
 126
 127 In order for the endpoint device to establish a link with the host, the _start_
 128 field should be populated with '1'. For NTB, both the PCI endpoint controllers
 129 should establish link with the host (imx8 don't need this steps)::
 130
 131         # echo 1 > controllers/5f010000.pcie_ep/start
 132
 133 RootComplex Device
 134 ==================
 135
 136 lspci Output at Host side
 137 -------------------------
 138
 139 Note that the devices listed here correspond to the values populated in
 140 "Creating pci-epf-ntb Device" section above::
 141
 142         # lspci
 143         00:00.0 PCI bridge: Freescale Semiconductor Inc Device 0000 (rev 01)
 144         01:00.0 RAM memory: Freescale Semiconductor Inc Device 0809
 145
 146 Endpoint Device / Virtual PCI bus
 147 =================================
 148
 149 lspci Output at EP Side / Virtual PCI bus
 150 -----------------------------------------
 151
 152 Note that the devices listed here correspond to the values populated in
 153 "Creating pci-epf-ntb Device" section above::
 154
 155         # lspci
 156         10:00.0 Unassigned class [ffff]: Dawicontrol Computersysteme GmbH Device 1234 (rev ff)
 157
 158 Using ntb_hw_epf Device
 159 -----------------------
 160
 161 The host side software follows the standard NTB software architecture in Linux.
 162 All the existing client side NTB utilities like NTB Transport Client and NTB
 163 Netdev, NTB Ping Pong Test Client and NTB Tool Test Client can be used with NTB
 164 function device.
 165
 166 For more information on NTB see
 167 :doc:`Non-Transparent Bridge <../../driver-api/ntb>`