util/spd_tools: Document adding support for a new memory technology

Add documentation describing how to add support for a new memory
technology to spd_tools:
- Add a section to the README.
- Document the memTech interface in spd_gen.go.

BUG=b:191776301
TEST=None

Signed-off-by: Reka Norman <rekanorman@google.com>
Change-Id: Ie710c1c686ddf5288db35cf43e5f1ac9b1974305
Reviewed-on: https://review.coreboot.org/c/coreboot/+/59005
Reviewed-by: Karthik Ramasubramanian <kramasub@google.com>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>

2 files changed, 72 insertions, 0 deletions

diff --git a/util/spd_tools/README.md b/util/spd_tools/README.md
index a422017581..3a1342c85a 100644
--- a/util/spd_tools/README.md
+++ b/util/spd_tools/README.md
@@ -590,3 +590,48 @@ util/spd_tools/bin/part_id_gen \
         `dram_id.generated.txt` with the new part.
     *   Upload the changes to `Makefile.inc` and `dram_id.generated.txt` for
         review.
+
+## How to add support for a new memory technology
+
+### 1. Gather the SPD requirements
+
+To generate SPDs for the new memory technology, information is needed about the
+list of bytes in the SPD and how the value of each byte should be determined.
+This information usually comes from a combination of:
+
+*   The JEDEC spec for the memory technology, e.g. JESD209-5B for LPDDR5.
+*   The JEDEC SPD spec for the memory technology, e.g. SPD4.1.2.M-2 for LPDDR3/4
+    (also used for LP4x and LP5).
+*   Platform-specific requirements. SoC vendors often don't follow the JEDEC
+    specs exactly. E.g. the memory training code may expect certain SPD bytes to
+    encode a different value to what is stated in the spec. So for each SoC
+    platform using the new memory technology, any platform-specific requirements
+    need to be gathered.
+
+### 2. Implement support in spd_tools
+
+Support for the new memory technology needs to be added to both the `spd_gen`
+and `part_id_gen` tools.
+
+#### `spd_gen`
+
+Adding support to `spd_gen` requires implementing the logic to generate SPDs for
+the new memory technology. The changes required are:
+
+*   Add the new memory technology to the `memTechMap` in `spd_gen/spd_gen.go`.
+*   Add a new file `spd_gen/<mem_tech>.go`. This file will contain all the logic
+    for generating SPDs for the new memory technology. It needs to implement the
+    `memTech` interface defined in `spd_gen/spd_gen.go`. The interface functions
+    are documented inline. Examples of how the interface is implemented for
+    existing memory technologies can be found in the `spd_gen/` directory, e.g.
+    `lp4x.go`, `ddr4.go`, `lp5.go`. While not strictly necessary, it is
+    recommended to follow the overall structure of these existing files when
+    adding a new memory technology.
+
+#### `part_id_gen`
+
+The `part_id_gen` tool is memory technology-agnostic, so the only change
+required is:
+
+*   Add the new memory technology to the `supportedMemTechs` list in
+    `part_id_gen/part_id_gen.go`.
diff --git a/util/spd_tools/src/spd_gen/spd_gen.go b/util/spd_tools/src/spd_gen/spd_gen.go
index fa6549262d..6cc910272f 100644
--- a/util/spd_tools/src/spd_gen/spd_gen.go
+++ b/util/spd_tools/src/spd_gen/spd_gen.go
@@ -28,10 +28,37 @@ type memPart struct {
 }
 
 type memTech interface {
+	/*
+	 * Returns the set -> platform mapping for the memory technology. Platforms with the
+	 * same SPD requirements should be grouped together into a single set.
+	 */
 	getSetMap() map[int][]int
+
+	/*
+	 * Takes the name and attributes of a part, as read from the memory_parts JSON file.
+	 * Validates the attributes, returning an error if any attribute has an invalid value.
+	 * Stores the name and attributes internally to be used later.
+	 */
 	addNewPart(string, interface{}) error
+
+	/*
+	 * Takes the name of a part and a set number.
+	 * Retrieves the part's attributes which were stored by addNewPart(). Updates them by
+	 * setting any optional attributes which weren't specified in the JSON file to their
+	 * default values.
+	 * Returns these updated attributes.
+	 */
 	getSPDAttribs(string, int) (interface{}, error)
+
+	/*
+	 * Returns the size of an SPD file for this memory technology.
+	 */
 	getSPDLen() int
+
+	/*
+	 * Takes an SPD byte index and the attributes of a part.
+	 * Returns the value which that SPD byte should be set to based on the attributes.
+	 */
 	getSPDByte(int, interface{}) byte
 }