share/man/man4/jedec_dimm.4

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2016 Andriy Gapon <avg@FreeBSD.org>
   5 .\" Copyright (c) 2018 Ravi Pokala <rpokala@freebsd.org>
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd February 22, 2018
  31 .Dt JEDEC_DIMM 4
  32 .Os
  33 .Sh NAME
  34 .Nm jedec_dimm
  35 .Nd report asset information and temperatures for JEDEC DDR3 / DDR4 DIMMs
  36 .Sh SYNOPSIS
  37 .Bd -ragged -offset indent
  38 .Cd "device jedec_dimm"
  39 .Cd "device smbus"
  40 .Ed
  41 .Pp
  42 Alternatively, to load the driver as a module at boot time, place the following
  43 line in
  44 .Xr loader.conf 5 :
  45 .Bd -literal -offset indent
  46 jedec_dimm_load="YES"
  47 .Ed
  48 .Pp
  49 Addressing information must be manually specified in
  50 .Pa /boot/device.hints :
  51 .Bd -literal -offset indent
  52 .Cd hint.jedec_dimm.0.at="smbus0"
  53 .Cd hint.jedec_dimm.0.addr="0xa0"
  54 .Cd hint.jedec_dimm.0.slotid="Silkscreen"
  55 .Ed
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 driver reports asset information (Part Number, Serial Number) encoded in the
  60 .Dq Serial Presence Detect
  61 (SPD) data on JEDEC DDR3 and DDR4 DIMMs.
  62 It also calculates and reports the memory capacity of the DIMM, in megabytes.
  63 If the DIMM includes a
  64 .Dq Thermal Sensor On DIMM
  65 (TSOD), the temperature is also reported.
  66 .Pp
  67 The
  68 .Nm
  69 driver accesses the SPD and TSOD over the
  70 .Xr smbus 4 .
  71 .Pp
  72 The data is reported via a
  73 .Xr sysctl 8
  74 interface; all values are read-only:
  75 .Bl -tag -width "dev.jedec_dimm.X.capacity"
  76 .It Va dev.jedec_dimm.X.%desc
  77 a string description of the DIMM, including TSOD and slotid info if present.
  78 .It Va dev.jedec_dimm.X.capacity
  79 the DIMM's memory capacity, in megabytes
  80 .It Va dev.jedec_dimm.X.part
  81 the manufacturer's part number of the DIMM
  82 .It Va dev.jedec_dimm.X.serial
  83 the manufacturer's serial number of the DIMM
  84 .It Va dev.jedec_dimm.X.slotid
  85 a copy of the corresponding hint, if set
  86 .It Va dev.jedec_dimm.X.temp
  87 if a TSOD is present, the reported temperature
  88 .It Va dev.jedec_dimm.X.type
  89 the DIMM type (DDR3 or DDR4)
  90 .El
  91 .Pp
  92 These values are configurable for
  93 .Nm
  94 via
  95 .Xr device.hints 5 :
  96 .Bl -tag -width "hint.jedec_dimm.X.slotid"
  97 .It Va hint.jedec_dimm.X.at
  98 the
  99 .Xr smbus 4
 100 to which the DIMM is connected
 101 .It Va hint.jedec_dimm.X.addr
 102 the SMBus address of the SPD.
 103 JEDEC specifies that the four most-significant bits of the address are the
 104 .Dq Device Type Identifier
 105 (DTI), and that the DTI of the SPD is 0xa.
 106 Since the least-significant bit of an SMBus address is the read/write bit, and
 107 is always written as 0, that means the four least-significant bits of the
 108 address must be even.
 109 .It Va hint.jedec_dimm.X.slotid
 110 optional slot identifier.
 111 If populated with the DIMM slot name silkscreened on the motherboard, this
 112 provides a mapping between the DIMM slot name and the DIMM serial number.
 113 That mapping is useful for detailed asset tracking, and makes it easier to
 114 physically locate a specific DIMM when doing a replacement.
 115 This is useful when assembling multiple identical systems, as might be done by
 116 a system vendor.
 117 The mapping between bus/address and DIMM slot must first be determined, either
 118 through motherboard documentation or trial-and-error.
 119 .El
 120 .Pp
 121 If the DIMMs are on an I2C bus behind an
 122 .Xr iicbus 4
 123 controller, then the
 124 .Xr iicsmb 4
 125 bridge driver can be used to attach the
 126 .Xr smbus 4 .
 127 .Sh EXAMPLES
 128 Consider two DDR4 DIMMs with the following hints:
 129 .Bd -literal -offset indent
 130 hint.jedec_dimm.0.at="smbus0"
 131 hint.jedec_dimm.0.addr="0xa0"
 132 hint.jedec_dimm.0.slotid="A1"
 133
 134 hint.jedec_dimm.6.at="smbus1"
 135 hint.jedec_dimm.6.addr="0xa8"
 136 .Ed
 137 .Pp
 138 Their
 139 .Xr sysctl 8
 140 output (sorted):
 141 .Bd -literal -offset indent
 142 dev.jedec_dimm.0.%desc: DDR4 DIMM w/ Atmel TSOD (A1)
 143 dev.jedec_dimm.0.%driver: jedec_dimm
 144 dev.jedec_dimm.0.%location: addr=0xa0
 145 dev.jedec_dimm.0.%parent: smbus0
 146 dev.jedec_dimm.0.%pnpinfo:
 147 dev.jedec_dimm.0.capacity: 16384
 148 dev.jedec_dimm.0.part: 36ASF2G72PZ-2G1A2
 149 dev.jedec_dimm.0.serial: 0ea815de
 150 dev.jedec_dimm.0.slotid: A1
 151 dev.jedec_dimm.0.temp: 32.7C
 152 dev.jedec_dimm.0.type: DDR4
 153
 154 dev.jedec_dimm.6.%desc: DDR4 DIMM w/ TSE2004av compliant TSOD
 155 dev.jedec_dimm.6.%driver: jedec_dimm
 156 dev.jedec_dimm.6.%location: addr=0xa8
 157 dev.jedec_dimm.6.%parent: smbus1
 158 dev.jedec_dimm.6.%pnpinfo:
 159 dev.jedec_dimm.6.capacity: 8192
 160 dev.jedec_dimm.6.part: VRA9MR8B2H1603
 161 dev.jedec_dimm.6.serial: 0c4c46ad
 162 dev.jedec_dimm.6.temp: 43.1C
 163 dev.jedec_dimm.6.type: DDR4
 164 .Ed
 165 .Sh COMPATIBILITY
 166 Hints for
 167 .Xr jedec_ts 4
 168 can be mechanically converted for use with
 169 .Nm .
 170 Two changes are required:
 171 .Bl -enum
 172 .It
 173 In all
 174 .Xr jedec_ts 4
 175 hints, replace
 176 .Dq jedec_ts
 177 with
 178 .Dq jedec_dimm
 179 .It
 180 In
 181 .Xr jedec_ts 4
 182 .Dq addr
 183 hints, replace the TSOD DTI
 184 .Dq 0x3
 185 with the SPD DTI
 186 .Dq 0xa
 187 .El
 188 .Pp
 189 The following
 190 .Xr sed 1
 191 script will perform the necessary changes:
 192 .Bd -literal -offset indent
 193 sed -i ".old" -e 's/jedec_ts/jedec_dimm/' \\
 194     -e '/jedec_dimm/s/addr="0x3/addr="0xa/' /boot/device.hints
 195 .Ed
 196 .Sh SEE ALSO
 197 .Xr iicbus 4 ,
 198 .Xr iicsmb 4 ,
 199 .Xr jedec_ts 4 ,
 200 .Xr smbus 4 ,
 201 .Xr sysctl 8
 202 .Sh STANDARDS
 203 .Rs
 204 (DDR3 SPD)
 205 .%A JEDEC
 206 .%T Standard 21-C, Annex K
 207 .Re
 208 .Pp
 209 .Rs
 210 (DDR3 TSOD)
 211 .%A JEDEC
 212 .%T Standard 21-C, TSE2002av
 213 .Re
 214 .Pp
 215 .Rs
 216 (DDR4 SPD)
 217 .%A JEDEC
 218 .%T Standard 21-C, Annex L
 219 .Re
 220 .Pp
 221 .Rs
 222 (DDR4 TSOD)
 223 .%A JEDEC
 224 .%T Standard 21-C, TSE2004av
 225 .Re
 226 .Sh HISTORY
 227 The
 228 .Nm
 229 driver first appeared in
 230 .Fx 12.0 .
 231 .Sh AUTHORS
 232 .An -nosplit
 233 The
 234 .Nm
 235 driver and this manual page were written by
 236 .An Ravi Pokala Aq Mt rpokala@freebsd.org .
 237 They are both based in part on the
 238 .Xr jedec_ts 4
 239 driver and manual page, written by
 240 .An Andriy Gapon Aq Mt avg@FreeBSD.org .