share/man/man4/imcsmb.4

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2018 Panasas
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd March 2, 2018
  29 .Dt IMCSMB 4
  30 .Os
  31 .Sh NAME
  32 .Nm imcsmb
  33 .Nd Intel integrated Memory Controller (iMC) SMBus controller driver
  34 .Sh SYNOPSIS
  35 .Cd device pci
  36 .Cd device smbus
  37 .Cd device imcsmb
  38 .Pp
  39 Alternatively, to load the driver as a module at boot time, place the following
  40 line in
  41 .Xr loader.conf 5 :
  42 .Bd -literal -offset indent
  43 imcsmb_load="YES"
  44 .Ed
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 driver provides
  49 .Xr smbus 4
  50 support for the SMBus controller functionality in the integrated Memory
  51 Controllers (iMCs) embedded in Intel Sandybridge-Xeon, Ivybridge-Xeon,
  52 Haswell-Xeon, and Broadwell-Xeon CPUs.
  53 Each CPU implements one or more iMCs, depending on the number of cores;
  54 each iMC implements two SMBus controllers (iMC-SMBs).
  55 The iMC-SMBs are used by the iMCs to read configuration information from the
  56 DIMMs during POST.
  57 They may also be used, by motherboard firmware or a BMC, to monitor the
  58 temperature of the DIMMs.
  59 .Pp
  60 The iMC-SMBs are
  61 .Sy not
  62 general-purpose SMBus controllers.
  63 By their nature, they are only ever attached to DIMMs, so they implement only
  64 the SMBus operations need for communicating with DIMMs.
  65 Specifically:
  66 .Pp
  67 .Bl -dash -offset indent -compact
  68 .It
  69 READB
  70 .It
  71 READW
  72 .It
  73 WRITEB
  74 .It
  75 WRITEW
  76 .El
  77 .Pp
  78 A more detailed discussion of the hardware and driver architecture can be found
  79 at the top of
  80 .Pa sys/dev/imcsmb/imcsmb_pci.c .
  81 .Sh WARNINGS
  82 As mentioned above, firmware might use the iMC-SMBs to read DIMM temperatures.
  83 The public iMC documentation does not describe any sort of coordination
  84 mechanism to prevent requests from different sources -- such as the motherboard
  85 firmware, a BMC, or the operating system -- from interfering with each other.
  86 .Pp
  87 .Bf Sy
  88 Therefore, it is highly recommended that developers contact the motherboard
  89 vendor for any board-specific instructions on how to disable and re-enable DIMM
  90 temperature monitoring.
  91 .Ef
  92 .Pp
  93 DIMM temperature monitoring should be disabled before returning from
  94 .Fn imcsmb_pci_request_bus ,
  95 and re-enabled before returning from
  96 .Fn imcsmb_pci_release_bus .
  97 The driver includes comments to that effect at the appropriate locations.
  98 The driver has been tested and shown to work, with only that type of
  99 modification, on certain motherboards from Intel.
 100 .Po
 101 Unfortunately, those modifications were based on material covered under a
 102 non-disclosure agreement, and therefore are not included in this driver.
 103 .Pc
 104 The driver has also been tested and shown to work as-is on various motherboards
 105 from SuperMicro.
 106 .Pp
 107 The
 108 .Xr smb 4
 109 driver will connect to the
 110 .Xr smbus 4
 111 instances created by
 112 .Nm .
 113 However, since the IMC-SMBs are not general-purpose SMBus controllers, using
 114 .Xr smbmsg 8
 115 with those
 116 .Xr smb 4
 117 devices is not supported.
 118 .Sh SEE ALSO
 119 .Xr jedec_dimm 4 ,
 120 .Xr smbus 4
 121 .Sh HISTORY
 122 The
 123 .Nm
 124 driver first appeared in
 125 .Fx 12.0 .
 126 .Sh AUTHORS
 127 The
 128 .Nm
 129 driver was originally written for Panasas by
 130 .An Joe Kloss .
 131 It was substantially refactored, and this manual page was written, by
 132 .An Ravi Pokala Aq Mt rpokala@freebsd.org