include: Update dimm_info documentation

Reference the JEDEC SPD spec and clarify some comments.

BRANCH=dimm-info
BUG=b:65403853
TEST=Documentation change only

Signed-off-by: Raul E Rangel <rrangel@chromium.org>
Change-Id: I1f2a3a70919c34f17472904323ec5accdfc876be
Reviewed-on: https://review.coreboot.org/25301
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Aaron Durbin <adurbin@chromium.org>

1 files changed, 52 insertions, 3 deletions

diff --git a/src/include/memory_info.h b/src/include/memory_info.h
index a1b3553a7775..4613015d750e 100644
--- a/src/include/memory_info.h
+++ b/src/include/memory_info.h
@@ -23,24 +23,73 @@
 #define DIMM_INFO_PART_NUMBER_SIZE	19
 #define DIMM_INFO_TOTAL			8	/* Maximum num of dimm is 8 */
 
-/*
+/**
  * If this table is filled and put in CBMEM,
  * then these info in CBMEM will be used to generate smbios type 17 table
+ *
+ * Values are specified according to the JEDEC SPD Standard.
  */
 struct dimm_info {
+	/*
+	 * Size of the module in MiB.
+	 */
 	uint32_t dimm_size;
+	/*
+	 * SMBIOS (not SPD) device type.
+	 *
+	 * See the smbios.h smbios_memory_device_type enum.
+	 */
 	uint16_t ddr_type;
 	uint16_t ddr_frequency;
 	uint8_t rank_per_dimm;
 	uint8_t channel_num;
 	uint8_t dimm_num;
 	uint8_t bank_locator;
-	/* The last byte is '\0' for the end of string */
+	/*
+	 * The last byte is '\0' for the end of string.
+	 *
+	 * Even though the SPD spec defines this field as a byte array the value
+	 * is passed directly to SMBIOS as a string, and thus must be printable
+	 * ASCII.
+	 */
 	uint8_t serial[DIMM_INFO_SERIAL_SIZE];
-	/* The last byte is '\0' for the end of string */
+	/*
+	 * The last byte is '\0' for the end of string
+	 *
+	 * Must contain only printable ASCII.
+	 */
 	uint8_t module_part_number[DIMM_INFO_PART_NUMBER_SIZE];
+	/*
+	 * SPD Manufacturer ID
+	 */
 	uint16_t mod_id;
+	/*
+	 * SPD Module Type.
+	 *
+	 * See spd.h for valid values.
+	 *
+	 * e.g., SPD_RDIMM, SPD_SODIMM, SPD_MICRO_DIMM
+	 */
 	uint8_t mod_type;
+	/*
+	 * SPD bus width.
+	 *
+	 * Bits 0 - 2 encode the primary bus width:
+	 *   0b000 = 8 bit width
+	 *   0b001 = 16 bit width
+	 *   0b010 = 32 bit width
+	 *   0b011 = 64 bit width
+	 *
+	 * Bits 3 - 4 encode the extension bits (ECC):
+	 *   0b00 = 0 extension bits
+	 *   0b01 = 8 bit of ECC
+	 *
+	 * e.g.,
+	 *   64 bit bus with 8 bits of ECC (72 bits total): 0b1011
+	 *   64 bit bus with 0 bits of ECC (64 bits total): 0b0011
+	 *
+	 * See the smbios.h smbios_memory_bus_width enum.
+	 */
 	uint8_t bus_width;
 } __packed;