[src/trunk]: src/share/man/man4/man4.x86 Add the man page for new imcsmb driver

[pgoyette <pgoyette%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/08efe6e53c15
branches:  trunk
changeset: 830068:08efe6e53c15
user:      pgoyette <pgoyette%NetBSD.org@localhost>
date:      Sun Feb 25 08:22:53 2018 +0000

description:
Add the man page for new imcsmb driver

diffstat:

 share/man/man4/man4.x86/Makefile |    4 +-
 share/man/man4/man4.x86/imcsmb.4 |  147 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 149 insertions(+), 2 deletions(-)

diffs (164 lines):

diff -r f048ec4c88c1 -r 08efe6e53c15 share/man/man4/man4.x86/Makefile
--- a/share/man/man4/man4.x86/Makefile  Sun Feb 25 08:21:57 2018 +0000
+++ b/share/man/man4/man4.x86/Makefile  Sun Feb 25 08:22:53 2018 +0000
@@ -1,7 +1,7 @@
-#      $NetBSD: Makefile,v 1.17 2018/01/25 01:25:39 christos Exp $
+#      $NetBSD: Makefile,v 1.18 2018/02/25 08:22:53 pgoyette Exp $
 
 MAN=   amdpcib.4 apic.4 balloon.4 coretemp.4 est.4 fdc.4 \
-       fwhrng.4 hpet.4 ichlpcib.4 lpt.4 mem.4 odcm.4 powernow.4 \
+       fwhrng.4 hpet.4 ichlpcib.4 imcsmb.4 lpt.4 mem.4 odcm.4 powernow.4 \
        soekrisgpio.4 tco.4 tprof_amdpmi.4 tprof_pmi.4 vmt.4 vmx.4 \
        amdsmn.4 amdzentemp.4
 
diff -r f048ec4c88c1 -r 08efe6e53c15 share/man/man4/man4.x86/imcsmb.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/man4.x86/imcsmb.4  Sun Feb 25 08:22:53 2018 +0000
@@ -0,0 +1,147 @@
+.\"
+.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
+.\"
+.\" Copyright (c) 2018 Panasas
+.\" 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 ``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 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 February 24, 2018
+.Dt IMCSMB 4
+.Os
+.Sh NAME
+.Nm imcsmb
+.Nd Intel integrated Memory Controller (iMC) SMBus controller driver
+.Sh SYNOPSIS
+.Cd imc* at pci? dev ? func ?
+.Cd imcsmb* at imc?
+.Cd iic* at i2cbus?
+.Pp
+Alternatively, to load the driver as a module at boot time, place the following
+line in
+.Xr boot.cfg :
+.Bd -literal -offset indent
+load=imcsmb
+.Ed
+or add the following line to your /etc/modules file:
+.Bd -literal -offset indent
+imcsmb
+.Ed
+.Sh DESCRIPTION
+The
+.Nm
+driver provides
+.Xr iic 4
+support for the SMBus controller functionality in the integrated Memory
+Controllers (iMCs) embedded in Intel Sandybridge-Xeon, Ivybridge-Xeon,
+Haswell-Xeon, and Broadwell-Xeon CPUs.
+Each CPU implements one or more iMCs, depending on the number of cores; each
+iMC implements two SMBus controllers (iMC-SMBs).
+The iMC-SMBs are used by the iMCs to read configuration information from the
+DIMMs during POST.
+They may also be used, by motherboard firmware or a BMC, to monitor the
+temperature of the DIMMs.
+.Pp
+The iMC-SMBs are
+.Sy not
+general-purpose SMBus controllers.
+By their nature, they are only ever attached to DIMMs, so they implement only
+the SMBus operations need for communicating with DIMMs.
+Specifically:
+.Pp
+.Bl -dash -offset indent -compact
+.It
+READB
+.It
+READW
+.It
+WRITEB
+.It
+WRITEW
+.El
+.Pp
+A more detailed discussion of the hardware and driver architecture can be found
+at the top of
+.Pa sys/dev/imcsmb/imc.c .
+.Sh WARNINGS
+As mentioned above, firmware might use the iMC-SMBs to read DIMM temperatures.
+The public iMC documentation does not describe any sort of coordination
+mechanism to prevent requests from different sources -- such as the motherboard
+firmware, a BMC, or the operating system -- from interfering with each other.
+.Pp
+.Bf Sy
+Therefore, it is highly recommended that developers contact the motherboard
+vendor for any board-specific instructions on how to disable and re-enable DIMM
+temperature monitoring.
+.Ef
+.Pp
+DIMM temperature monitoring should be disabled before returning from
+.Fn imcsmb_pci_request_bus ,
+and re-enabled before returning from
+.Fn imcsmb_pci_release_bus .
+The driver includes comments to that effect at the appropriate locations.
+The driver has been tested and shown to work, with only that type of
+modification, on certain motherboards from Intel.
+.Po
+Unfortunately, those modifications were based on material covered under a
+non-disclosure agreement, and therefore are not included in this driver.
+.Pc
+The driver has also been tested and shown to work as-is on various motherboards
+from SuperMicro.
+.Pp
+Because of the above, the
+.Nm
+driver is not included in the default
+.Dv GENERIC
+kernel.
+In order to use the
+.Nm
+driver, you must compile a custom kernel, or load the driver using
+.Xr modload 8 .
+.Pp
+The
+.Xr iic 4
+driver will connect to the i2cbus instances created by
+.Nm .
+.Sh SEE ALSO
+.Xr i2c 4
+.Sh HISTORY
+The
+.Nm
+driver first appeared in
+.Fx 12.0 .
+It was later ported to
+.Nx 9.0 .
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+driver was originally written for Panasas by
+.An Joe Kloss .
+It was substantially refactored, and this manual page was written, by
+.An Ravi Pokala Aq Mt rpokala%freebsd.org@localhost .
+It was adapted to
+.Nx
+by
+.An Paul Goyette Aq Mt pgoyette%netbsd.org@localhost .
+