xref: /freebsd/share/man/man4/imcsmb.4 (revision 3cbb4cc200f8a0ad7ed08233425ea54524a21f1c)
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
39Alternatively, to load the driver as a module at boot time, place the following
40line in
41.Xr loader.conf 5 :
42.Bd -literal -offset indent
43imcsmb_load="YES"
44.Ed
45.Sh DESCRIPTION
46The
47.Nm
48driver provides
49.Xr smbus 4
50support for the SMBus controller functionality in the integrated Memory
51Controllers (iMCs) embedded in Intel Sandybridge-Xeon, Ivybridge-Xeon,
52Haswell-Xeon, and Broadwell-Xeon CPUs.
53Each CPU implements one or more iMCs, depending on the number of cores;
54each iMC implements two SMBus controllers (iMC-SMBs).
55The iMC-SMBs are used by the iMCs to read configuration information from the
56DIMMs during POST.
57They may also be used, by motherboard firmware or a BMC, to monitor the
58temperature of the DIMMs.
59.Pp
60The iMC-SMBs are
61.Sy not
62general-purpose SMBus controllers.
63By their nature, they are only ever attached to DIMMs, so they implement only
64the SMBus operations need for communicating with DIMMs.
65Specifically:
66.Pp
67.Bl -dash -offset indent -compact
68.It
69READB
70.It
71READW
72.It
73WRITEB
74.It
75WRITEW
76.El
77.Pp
78A more detailed discussion of the hardware and driver architecture can be found
79at the top of
80.Pa sys/dev/imcsmb/imcsmb_pci.c .
81.Sh WARNINGS
82As mentioned above, firmware might use the iMC-SMBs to read DIMM temperatures.
83The public iMC documentation does not describe any sort of coordination
84mechanism to prevent requests from different sources -- such as the motherboard
85firmware, a BMC, or the operating system -- from interfering with each other.
86.Pp
87.Bf Sy
88Therefore, it is highly recommended that developers contact the motherboard
89vendor for any board-specific instructions on how to disable and re-enable DIMM
90temperature monitoring.
91.Ef
92.Pp
93DIMM temperature monitoring should be disabled before returning from
94.Fn imcsmb_pci_request_bus ,
95and re-enabled before returning from
96.Fn imcsmb_pci_release_bus .
97The driver includes comments to that effect at the appropriate locations.
98The driver has been tested and shown to work, with only that type of
99modification, on certain motherboards from Intel.
100.Po
101Unfortunately, those modifications were based on material covered under a
102non-disclosure agreement, and therefore are not included in this driver.
103.Pc
104The driver has also been tested and shown to work as-is on various motherboards
105from SuperMicro.
106.Pp
107The
108.Xr smb 4
109driver will connect to the
110.Xr smbus 4
111instances created by
112.Nm .
113However, since the IMC-SMBs are not general-purpose SMBus controllers, using
114.Xr smbmsg 8
115with those
116.Xr smb 4
117devices is not supported.
118.Sh SEE ALSO
119.Xr jedec_dimm 4 ,
120.Xr smbus 4
121.Sh HISTORY
122The
123.Nm
124driver first appeared in
125.Fx 12.0 .
126.Sh AUTHORS
127The
128.Nm
129driver was originally written for Panasas by
130.An Joe Kloss .
131It was substantially refactored, and this manual page was written, by
132.An Ravi Pokala Aq Mt rpokala@freebsd.org
133