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