share/man/man4/ntb_hw_amd.4

   1 .\"
   2 .\" Copyright (c) 2019 Rajesh Kumar <rajesh1.kumar@amd.com>
   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 .\" $FreeBSD$
  27 .\"
  28 .Dd August 29, 2019
  29 .Dt NTB_HW_AMD 4
  30 .Os
  31 .Sh NAME
  32 .Nm ntb_hw_amd
  33 .Nd AMD Non-Transparent Bridge driver
  34 .Sh SYNOPSIS
  35 To compile this driver into your kernel,
  36 place the following lines in your kernel configuration file:
  37 .Bd -ragged -offset indent
  38 .Cd "device ntb"
  39 .Cd "device ntb_hw_amd"
  40 .Ed
  41 .Pp
  42 Or, to load the driver as a module at boot, place the following line in
  43 .Xr loader.conf 5 :
  44 .Bd -literal -offset indent
  45 ntb_hw_amd_load="YES"
  46 .Ed
  47 .Pp
  48 The following sysctls are supported in this driver
  49 .Bl -ohang
  50 .It Va dev.ntb_hw.X.info
  51 Reading this sysctl will give the basic details like the number of memory
  52 windows, scratchpads and doorbells exposed by the NTB on the local host to
  53 access the devices beyond the bridge.
  54 It also provides details about the masked doorbells, translation address and
  55 size limit of each exposed memory window and link status information.
  56 .El
  57 .Sh DESCRIPTION
  58 The
  59 .Nm ntb_hw_amd
  60 driver provides support for the Non-Transparent Bridge (NTB) hardware in
  61 AMD EPYC processor family.
  62 The Non-Transparent Bridge does not look as a regular PCI bridge, but as PCI
  63 endpoint device, hiding the devices behind it.
  64 The driver hides details of hardware on the other side, but exposes memory windows,
  65 scratchpads and doorbells to access the other side via hardware independent
  66 KPI to
  67 .Xr ntb 4
  68 subsystem.
  69 .Pp
  70 The hardware provides 2 (both 64-bit) or 3 (one 32-bit and two 64-bit) memory
  71 windows to the other system's memory, up to 16 scratchpad registers and 16
  72 doorbells to communicate with and interrupt the other system respectively.
  73 .Sh CONFIGURATION
  74 The NTB configuration should be set by BIOS.
  75 This includes enabling NTB, choosing topology (only NTB-to-Root Port
  76 mode is supported now), role of the host in the topology.
  77 This needs to be done on both systems.
  78 .Pp
  79 The BAR size for memory windows is configured to 1 MiB by default.
  80 .Sh SEE ALSO
  81 .Xr if_ntb 4 ,
  82 .Xr ntb 4 ,
  83 .Xr ntb_transport 4
  84 .Sh AUTHORS
  85 .An -nosplit
  86 The
  87 .Nm
  88 driver was developed by AMD and originally written by
  89 .An Rajesh Kumar Aq Mt rajesh1.kumar@amd.com .
  90 Reviewed by
  91 .An Alexander Motin Aq Mt mav@FreeBSD.org ,
  92 .An Conrad E. Meyer Aq Mt cem@FreeBSD.org
  93 and
  94 .An Warner Losh Aq Mt imp@FreeBSD.org .