Date: Sun, 10 Jul 2016 10:17:38 +0000 (UTC) From: Alexander Motin <mav@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r302520 - head/share/man/man4 Message-ID: <201607101017.u6AAHcgR093795@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: mav Date: Sun Jul 10 10:17:38 2016 New Revision: 302520 URL: https://svnweb.freebsd.org/changeset/base/302520 Log: Replace NTB man page with more detailed and up to date. Sponsored by: iXsystems, Inc. Added: head/share/man/man4/if_ntb.4 (contents, props changed) head/share/man/man4/ntb_hw.4 (contents, props changed) head/share/man/man4/ntb_transport.4 (contents, props changed) Deleted: head/share/man/man4/ntb.4 Modified: head/share/man/man4/Makefile Modified: head/share/man/man4/Makefile ============================================================================== --- head/share/man/man4/Makefile Sun Jul 10 09:50:21 2016 (r302519) +++ head/share/man/man4/Makefile Sun Jul 10 10:17:38 2016 (r302520) @@ -374,7 +374,9 @@ MAN= aac.4 \ ng_vlan.4 \ nmdm.4 \ nsp.4 \ - ${_ntb.4} \ + ${_ntb_hw.4} \ + ${_ntb_transport.4} \ + ${_if_ntb.4} \ null.4 \ numa.4 \ ${_nvd.4} \ @@ -678,8 +680,7 @@ MLINKS+=netintro.4 net.4 \ netintro.4 networking.4 MLINKS+=${_nfe.4} ${_if_nfe.4} MLINKS+=nge.4 if_nge.4 -MLINKS+=${_ntb.4} ${_if_ntb.4} \ - ${_ntb.4} ${_ntb_hw.4} +MLINKS+=${_ntb_hw.4} ${_ntb.4} MLINKS+=${_nxge.4} ${_if_nxge.4} MLINKS+=ow.4 onewire.4 MLINKS+=patm.4 if_patm.4 @@ -820,6 +821,7 @@ _if_ntb.4= if_ntb.4 _ioat.4= ioat.4 _ntb.4= ntb.4 _ntb_hw.4= ntb_hw.4 +_ntb_transport.4=ntb_transport.4 _qlxge.4= qlxge.4 _qlxgb.4= qlxgb.4 _qlxgbe.4= qlxgbe.4 Added: head/share/man/man4/if_ntb.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/if_ntb.4 Sun Jul 10 10:17:38 2016 (r302520) @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 2016 Alexander Motin <mav@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 10, 2016 +.Dt IF_NTB 4 +.Os +.Sh NAME +.Nm if_ntb +.Nd Virtual Ethernet interface for Non-Transparent Bridges +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device if_ntb" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +if_ntb_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hw.if_ntb.num_queues +Number of transport queues to use per interface. +Default is 1. +.El +.Sh DESCRIPTION +The +.Nm +driver attaches on top of the +.Xr ntb_transport 4 +driver to utilize its resources to create virtual Ethernet interface between +the systems. +Interface capabilities depend on the underlying transport. +Typical MTU is about 64KB to reduce overhead. +By default one queue is used, but more may be configured. +The MAC address for interface is randomly generated. +.Pp +The +.Nm +driver does not implement any real hardware offload, but since PCIe link is +protected by CRC32, in some situations it may be possible to save some CPU +cycles by enabling fake checksum offload on both link sides via setting +.Cm rxcsum +and +.Cm txcsum +interface options. +.Sh SEE ALSO +.Xr ntb_transport 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Carl Delsey Aq Mt carl@FreeBSD.org . +Later improvements were done by +.An Conrad E. Meyer Aq Mt cem@FreeBSD.org +and +.An Alexander Motin Aq Mt mav@FreeBSD.org . Added: head/share/man/man4/ntb_hw.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/ntb_hw.4 Sun Jul 10 10:17:38 2016 (r302520) @@ -0,0 +1,103 @@ +.\" +.\" Copyright (c) 2016 Alexander Motin <mav@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 10, 2016 +.Dt NTB_HW 4 +.Os +.Sh NAME +.Nm ntb , +.Nm ntb_hw +.Nd Intel(R) Non-Transparent Bridge driver +.Sh SYNOPSIS +To compile this driver into your kernel, +place the following lines in your kernel configuration file: +.Bd -ragged -offset indent +.Cd "device ntb_hw" +.Ed +.Pp +Or, to load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ntb_hw_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hw.ntb.debug_level +Driver debug level. +The default value is 0, higher means more verbose. +.El +.Sh DESCRIPTION +The NTB allows you to connect two computer systems using a PCIe link if they +have the correct equipment and connectors. +The +.Nm ntb_hw +driver provides support for the Non-Transparent Bridge (NTB) in the Intel S1200 +and Xeon E3/E5 processor families. +The +.Nm +driver hides hardware details, exposing memory windows, scratchpads and +doorbells via hardware independent KPI. +.Pp +The hardware provides 2-3 memory windows to the other system's memory, +16 scratchpad registers and 14/34 doorbells to interrupt the other system. +On Xeon processors one of memory windows is typically consumed by the driver +to workaround multiple hardware erratas. +.Sh CONFIGURATION +Tne NTB configuration should be set by BIOS. +It includes enabling NTB, choosing between NTB-to-NTB or NTB-to-Root Port mode, +enabling split BAR mode (one of two 64-bit BARs can be split into two 32-bit +ones) and configuring BAR sizes in bits (from 12 to 29/39) for both NTB sides. +.Pp +The recommended configuration is NTB-to-NTB mode, split bar is enabled and +all BAR sizes are set to 20 (1 MiB). +This needs to be done on both systems. +.Sh SEE ALSO +.Xr ntb_transport 4 , +.Xr if_ntb 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Carl Delsey Aq Mt carl@FreeBSD.org . +Later improvements were done by +.An Conrad E. Meyer Aq Mt cem@FreeBSD.org +and +.An Alexander Motin Aq Mt mav@FreeBSD.org . +.Sh BUGS +NTB-to-Root Port mode is not yet supported, but it doesn't look very useful. +.Pp +On Xeon v2/v3/v4 processors split BAR mode should be enabled to allow +SB01BASE_LOCKUP errata workaround to be applied by the driver. +.Pp +There is no way to protect your system from malicious behavior on the other +system once the link is brought up. +Anyone with root or kernel access on the other system can read or write to +any location on your system. +In other words, only connect two systems that completely trust each other. Added: head/share/man/man4/ntb_transport.4 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man4/ntb_transport.4 Sun Jul 10 10:17:38 2016 (r302520) @@ -0,0 +1,74 @@ +.\" +.\" Copyright (c) 2016 Alexander Motin <mav@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 10, 2016 +.Dt NTB_TRANSPORT 4 +.Os +.Sh NAME +.Nm ntb_transport +.Nd Packet-oriented transport for Non-Transparent Bridges +.Sh SYNOPSIS +To load the driver as a module at boot, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +ntb_transport_load="YES" +.Ed +.Pp +The following tunables are settable from the +.Xr loader 8 : +.Bl -ohang +.It Va hw.ntb_transport.debug_level +Driver debug level. +The default value is 0, higher means more verbose. +.It Va hw.ntb_transport.max_num_clients +Number of bidirectional queues to setup. +The default value is 0, that means one queue per available memory window. +Maximal number is limited by number of doorbells. +.El +.Sh DESCRIPTION +The +.Nm +driver attaches on top of the +.Nm ntb +driver to utilize its resources to create set of bidirectional queues, +delivering packets between the systems. +The primary purpose of this is to be used by +.Nm if_ntb +network interface, but other consumers may also be developed using KPI. +.Sh SEE ALSO +.Xr if_ntb 4 , +.Xr ntb_hw 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +driver was developed by Intel and originally written by +.An Carl Delsey Aq Mt carl@FreeBSD.org . +Later improvements were done by +.An Conrad E. Meyer Aq Mt cem@FreeBSD.org +and +.An Alexander Motin Aq Mt mav@FreeBSD.org .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201607101017.u6AAHcgR093795>