share/man/man4/jedec_dimm.4

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