0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===================================================================
0004 PCI Non-Transparent Bridge (NTB) Endpoint Function (EPF) User Guide
0005 ===================================================================
0006
0007 :Author: Kishon Vijay Abraham I <kishon@ti.com>
0008
0009 This document is a guide to help users use pci-epf-ntb function driver
0010 and ntb_hw_epf host driver for NTB functionality. The list of steps to
0011 be followed in the host side and EP side is given below. For the hardware
0012 configuration and internals of NTB using configurable endpoints see
0013 Documentation/PCI/endpoint/pci-ntb-function.rst
0014
0015 Endpoint Device
0016 ===============
0017
0018 Endpoint Controller Devices
0019 ---------------------------
0020
0021 For implementing NTB functionality at least two endpoint controller devices
0022 are required.
0023
0024 To find the list of endpoint controller devices in the system::
0025
0026 # ls /sys/class/pci_epc/
0027 2900000.pcie-ep 2910000.pcie-ep
0028
0029 If PCI_ENDPOINT_CONFIGFS is enabled::
0030
0031 # ls /sys/kernel/config/pci_ep/controllers
0032 2900000.pcie-ep 2910000.pcie-ep
0033
0034
0035 Endpoint Function Drivers
0036 -------------------------
0037
0038 To find the list of endpoint function drivers in the system::
0039
0040 # ls /sys/bus/pci-epf/drivers
0041 pci_epf_ntb pci_epf_ntb
0042
0043 If PCI_ENDPOINT_CONFIGFS is enabled::
0044
0045 # ls /sys/kernel/config/pci_ep/functions
0046 pci_epf_ntb pci_epf_ntb
0047
0048
0049 Creating pci-epf-ntb Device
0050 ----------------------------
0051
0052 PCI endpoint function device can be created using the configfs. To create
0053 pci-epf-ntb device, the following commands can be used::
0054
0055 # mount -t configfs none /sys/kernel/config
0056 # cd /sys/kernel/config/pci_ep/
0057 # mkdir functions/pci_epf_ntb/func1
0058
0059 The "mkdir func1" above creates the pci-epf-ntb function device that will
0060 be probed by pci_epf_ntb driver.
0061
0062 The PCI endpoint framework populates the directory with the following
0063 configurable fields::
0064
0065 # ls functions/pci_epf_ntb/func1
0066 baseclass_code deviceid msi_interrupts pci-epf-ntb.0
0067 progif_code secondary subsys_id vendorid
0068 cache_line_size interrupt_pin msix_interrupts primary
0069 revid subclass_code subsys_vendor_id
0070
0071 The PCI endpoint function driver populates these entries with default values
0072 when the device is bound to the driver. The pci-epf-ntb driver populates
0073 vendorid with 0xffff and interrupt_pin with 0x0001::
0074
0075 # cat functions/pci_epf_ntb/func1/vendorid
0076 0xffff
0077 # cat functions/pci_epf_ntb/func1/interrupt_pin
0078 0x0001
0079
0080
0081 Configuring pci-epf-ntb Device
0082 -------------------------------
0083
0084 The user can configure the pci-epf-ntb device using its configfs entry. In order
0085 to change the vendorid and the deviceid, the following
0086 commands can be used::
0087
0088 # echo 0x104c > functions/pci_epf_ntb/func1/vendorid
0089 # echo 0xb00d > functions/pci_epf_ntb/func1/deviceid
0090
0091 In order to configure NTB specific attributes, a new sub-directory to func1
0092 should be created::
0093
0094 # mkdir functions/pci_epf_ntb/func1/pci_epf_ntb.0/
0095
0096 The NTB function driver will populate this directory with various attributes
0097 that can be configured by the user::
0098
0099 # ls functions/pci_epf_ntb/func1/pci_epf_ntb.0/
0100 db_count mw1 mw2 mw3 mw4 num_mws
0101 spad_count
0102
0103 A sample configuration for NTB function is given below::
0104
0105 # echo 4 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/db_count
0106 # echo 128 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/spad_count
0107 # echo 2 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/num_mws
0108 # echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw1
0109 # echo 0x100000 > functions/pci_epf_ntb/func1/pci_epf_ntb.0/mw2
0110
0111 Binding pci-epf-ntb Device to EP Controller
0112 --------------------------------------------
0113
0114 NTB function device should be attached to two PCI endpoint controllers
0115 connected to the two hosts. Use the 'primary' and 'secondary' entries
0116 inside NTB function device to attach one PCI endpoint controller to
0117 primary interface and the other PCI endpoint controller to the secondary
0118 interface::
0119
0120 # ln -s controllers/2900000.pcie-ep/ functions/pci-epf-ntb/func1/primary
0121 # ln -s controllers/2910000.pcie-ep/ functions/pci-epf-ntb/func1/secondary
0122
0123 Once the above step is completed, both the PCI endpoint controllers are ready to
0124 establish a link with the host.
0125
0126
0127 Start the Link
0128 --------------
0129
0130 In order for the endpoint device to establish a link with the host, the _start_
0131 field should be populated with '1'. For NTB, both the PCI endpoint controllers
0132 should establish link with the host::
0133
0134 # echo 1 > controllers/2900000.pcie-ep/start
0135 # echo 1 > controllers/2910000.pcie-ep/start
0136
0137
0138 RootComplex Device
0139 ==================
0140
0141 lspci Output
0142 ------------
0143
0144 Note that the devices listed here correspond to the values populated in
0145 "Creating pci-epf-ntb Device" section above::
0146
0147 # lspci
0148 0000:00:00.0 PCI bridge: Texas Instruments Device b00d
0149 0000:01:00.0 RAM memory: Texas Instruments Device b00d
0150
0151
0152 Using ntb_hw_epf Device
0153 -----------------------
0154
0155 The host side software follows the standard NTB software architecture in Linux.
0156 All the existing client side NTB utilities like NTB Transport Client and NTB
0157 Netdev, NTB Ping Pong Test Client and NTB Tool Test Client can be used with NTB
0158 function device.
0159
0160 For more information on NTB see
0161 :doc:`Non-Transparent Bridge <../../driver-api/ntb>`
