1.\" 2.\" Copyright (c) 2017-2019 Alexander Motin <mav@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd November 9, 2019 27.Dt NTB_HW_PLX 4 28.Os 29.Sh NAME 30.Nm ntb_hw_plx 31.Nd PLX/Avago/Broadcom Non-Transparent Bridge driver 32.Sh SYNOPSIS 33To compile this driver into your kernel, 34place the following lines in your kernel configuration file: 35.Bd -ragged -offset indent 36.Cd "device ntb" 37.Cd "device ntb_hw_plx" 38.Ed 39.Pp 40Or, to load the driver as a module at boot, place the following line in 41.Xr loader.conf 5 : 42.Bd -literal -offset indent 43ntb_hw_plx_load="YES" 44.Ed 45.Pp 46The following tunables are settable from the 47.Xr loader 8 : 48.Bl -ohang 49.It Va hint.ntb_hw. Ns Ar X Ns Va .b2b 50Being set to 1 (default) tells the driver attached to Virtual Interface of the 51NTB that it works in NTB-to-NTB (back-to-back) mode, 0 -- NTB-to-Root Port. 52Driver attached to Link Interface (visible from Root Port side) switches to 53NTB-to-Root Port mode automatically, but one attached to Virtual Interface 54can't detect what is on the other side and require external knowledge. 55.It Va hint.ntb_hw. Ns Ar X Ns Va .split 56Being set above zero splits BAR2 into 2^x memory windows using Address 57Lookup Table (A-LUT). 58.El 59.Sh DESCRIPTION 60The 61.Nm 62driver provides support for the Non-Transparent Bridge (NTB) hardware in 63PLX PCIe bridge chips, which allow up to two of their PCIe ports to be 64switched from transparent to non-transparent bridge mode. 65In this mode bridge looks not as a PCI bridge, but as PCI endpoint device. 66The driver hides hardware details, exposing memory windows, scratchpads 67and doorbells of the other side via hardware independent KPI to 68.Xr ntb 4 69subsystem. 70.Pp 71Each PLX NTB provides up to 2 64-bit or 4 32-bit memory windows to the 72other system's memory, 6 or 12 scratchpad registers and 16 doorbells to 73interrupt the other system. 74If Address Lookup Table (A-LUT) is enabled, BAR2 can be split into several 75(up to 128) memory windows. 76In NTB-to-NTB mode one of memory windows (or half of it, if bigger then 1MB) 77is consumed by the driver itself to access scratchpad and doorbell registers 78of the other side. 79.Sh HARDWARE 80The following PLX/Avago/Broadcom chips are supported by the 81.Nm 82driver: 83.Pp 84.Bl -bullet -compact 85.It 86PEX 8713 87.It 88PEX 8717 89.It 90PEX 8725 91.It 92PEX 8733 93.It 94PEX 8749 95.El 96.Pp 97, but it may also work with other compatible ones. 98.Sh CONFIGURATION 99The basic chip configuration should be done by serial EEPROM or via i2c. 100It includes enabling NTB on one or both sides (choosing between NTB-to-NTB 101(back-to-back) and NTB-to-Root Port modes) and configuring BARs sizes. 102.Pp 103The recommended mode is NTB-to-NTB mode, since while NTB-to-Root Port is 104generally supported by the driver, it require PCI hotplug handling on the 105Root Port, that may be difficult or cause different kinds of problems. 106.Sh SEE ALSO 107.Xr if_ntb 4 , 108.Xr ntb 4 , 109.Xr ntb_transport 4 110.Sh AUTHORS 111.An -nosplit 112The 113.Nm 114driver was written by 115.An Alexander Motin Aq Mt mav@FreeBSD.org . 116.Sh BUGS 117There is no way to protect your system from malicious behavior on the other 118system once the link is brought up. 119Anyone with root or kernel access on the other system can read or write to 120any location on your system. 121In other words, only connect two systems that completely trust each other. 122