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