util/spd_tools: Add README for unified spd_tools

Combine the existing lp4x and ddr4 READMEs into a single file, and
update it to reflect the new unified version of the tools.

BUG=b:191776301
TEST=None

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

1 files changed, 495 insertions, 0 deletions

diff --git a/util/spd_tools/README.md b/util/spd_tools/README.md
new file mode 100644
index 0000000000..5be666bde4
--- /dev/null
+++ b/util/spd_tools/README.md
@@ -0,0 +1,495 @@
+# SPD tools
+
+A set of tools to generate SPD files for platforms with memory down
+configurations.
+
+The memory technologies currently supported are:
+
+*   LPDDR4x - based on the JESD209-4C spec and Intel recommendations
+    (docs #616599, #610202, #634730).
+*   DDR4 - based on the JESD79-4C and Jedec 4.1.2.L-5 R29 v103 specs.
+
+There are two tools provided to assist with generating SPDs and Makefiles to
+integrate into the coreboot build. These tools can also be used to allocate DRAM
+IDs (configure DRAM hardware straps) for any memory part used by a board.
+
+*   `spd_gen`: This tool generates de-duplicated SPD files using a global memory
+    part list. It also generates a CSV manifest file which maps each memory part
+    in the global list to one of the generated SPD files. For each supported
+    memory technology, multiple sets of SPDs are generated. Each set corresponds
+    to a set of SoC platforms with different SPD requirements, e.g. due to
+    different expectations in the memory training code. Another CSV manifest
+    maps each supported platform to one of these sets.
+*   `part_id_gen`: This tool allocates DRAM strap IDs for the different memory
+    parts used by a board. It takes as input a CSV file of the memory parts used
+    with optional fixed IDs. It generates a Makefile.inc which is used to
+    integrate the SPD files generated by `spd_gen` into the coreboot build.
+
+## Tool 1 - `spd_gen`
+
+This program takes the following inputs:
+
+*   A JSON file containing a global list of memory parts with their attributes
+    as per the datasheet. This is the list of all known memory parts for the
+    given memory technology.
+*   The memory technology for which to generate the SPDs, e.g. "lp4x".
+
+The input JSON file requires the following two fields for every memory part:
+
+*   `name`: The name of the memory part.
+*   `attribs`: A list of the memory part's attributes, as per its datasheet.
+    These attributes match the part specifications and are independent of any
+    SoC expectations. The tool takes care of translating the physical attributes
+    of the memory part to match JEDEC spec and memory traning code expectations.
+
+The `attribs` field further contains two types of sub-field:
+
+*   Mandatory: These attributes must be provided for each memory part.
+*   Optional: These attributes may be provided for a memory part in order to
+    override the defaults.
+
+The attributes are different for each memory technology.
+
+### LP4x attributes
+
+#### Mandatory
+
+*   `densityPerChannelGb`: Density in Gb of the physical channel.
+
+*   `banks`: Number of banks per physical channel. This is typically 8 for
+    LPDDR4x memory parts.
+
+*   `channelsPerDie`: Number of physical channels per die. Valid values: `1, 2,
+    4`. For a part with x16 bit width, number of channels per die is 1 or 2. For
+    a part with x8 bit width, number of channels can be 2 or 4 (4 is basically
+    when two dual-channel byte mode devices are combined as shown in Figure 3 in
+    JESD209-4C).
+
+*   `diesPerPackage`: Number of physical dies in each SDRAM package. As per
+    JESD209-4C, "Standard LPDDR4 package ballmaps allocate one ZQ ball per die."
+    Thus, number of diesPerPackage is the number of ZQ balls on the package.
+
+*   `bitWidthPerChannel`: Width of each physical channel. Valid values: `8, 16`
+    bits.
+
+*   `ranksPerChannel`: Number of ranks per physical channel. Valid values: `1,
+    2`. If the channels across multiple dies share the same DQ/DQS pins but use
+    a separate CS, then ranks is 2 else it is 1.
+
+*   `speedMbps`: Maximum data rate supported by the part in Mbps. Valid values:
+    `3200, 3733, 4267` Mbps.
+
+#### Optional
+
+*   `trfcabNs`: Minimum Refresh Recovery Delay Time (tRFCab) for all banks in
+    nanoseconds. As per JESD209-4C, this is dependent on the density per
+    channel. Default values used:
+
+    *   6Gb : 280ns
+    *   8Gb : 280ns
+    *   12Gb: 380ns
+    *   16Gb: 380ns
+
+*   `trfcpbNs`: Minimum Refresh Recovery Delay Time (tRFCab) per bank in
+    nanoseconds. As per JESD209-4C, this is dependent on the density per
+    channel. Default values used:
+
+    *   6Gb : 140ns
+    *   8Gb : 140ns
+    *   12Gb: 190ns
+    *   16Gb: 190ns
+
+*   `trpabMinNs`: Minimum Row Precharge Delay Time (tRPab) for all banks in
+    nanoseconds. As per JESD209-4C, this is max(21ns, 4nck) which defaults to
+    `21ns`.
+
+*   `trppbMinNs`: Minimum Row Precharge Delay Time (tRPpb) per bank in
+    nanoseconds. As per JESD209-4C, this is max(18ns, 4nck) which defaults to
+    `18ns`.
+
+*   `tckMinPs`: SDRAM minimum cycle time (tckMin) value in picoseconds. This is
+    typically calculated based on the `speedMbps` attribute. `(1 / speedMbps) *
+    2`. Default values used(taken from JESD209-4C):
+
+    *   4267 Mbps: 468ps
+    *   3733 Mbps: 535ps
+    *   3200 Mbps: 625ps
+
+*   `tckMaxPs`: SDRAM maximum cycle time (tckMax) value in picoseconds. Default
+    value used: `31875ps`. As per JESD209-4C, TCKmax should be 100ns (100000ps)
+    for all speed grades. But the SPD byte to encode this field is only 1 byte.
+    Hence, the maximum value that can be encoded is 31875ps.
+
+*   `taaMinPs`: Minimum CAS Latency Time(taaMin) in picoseconds. This value
+    defaults to nck * tckMin, where nck is minimum CAS latency.
+
+*   `trcdMinNs`: Minimum RAS# to CAS# Delay Time (tRCDmin) in nanoseconds. As
+    per JESD209-4C, this is max(18ns, 4nck) which defaults to `18ns`.
+
+*   `casLatencies`: List of CAS latencies supported by the part. This is
+    dependent on the attrib `speedMbps`. Default values used:
+
+    *   4267: `"6 10 14 20 24 28 32 36"`.
+    *   3733: `"6 10 14 20 24 28 32"`.
+    *   3200: `"6 10 14 20 24 28"`.
+
+#### Example `memory_parts.json`
+
+```
+{
+    "parts": [
+        {
+            "name": "MT53D512M64D4NW-046 WT:F",
+            "attribs": {
+                "densityPerChannelGb": 8,
+                "banks": 8,
+                "channelsPerDie": 2,
+                "diesPerPackage": 2,
+                "bitWidthPerChannel": 16,
+                "ranksPerChannel": 1,
+                "speedMbps": 4267
+            }
+        },
+        {
+            "name": "NT6AP256T32AV-J1",
+            "attribs": {
+                "densityPerChannelGb": 4,
+                "banks": 8,
+                "channelsPerDie": 2,
+                "diesPerPackage": 1,
+                "bitWidthPerChannel": 16,
+                "ranksPerChannel": 1,
+                "speedMbps": 4267,
+                "tckMaxPs": 1250,
+                "casLatencies": "14 20 24 28 32 36"
+            }
+        },
+    ]
+}
+```
+
+### DDR4 attributes
+
+#### Mandatory
+
+*   `speedMTps`: Maximum rate supported by the part in MT/s. Valid values:
+    `1600, 1866, 2133, 2400, 2666, 2933, 3200` MT/s.
+
+*   `CL_nRCD_nRP`: Refers to CAS Latency specified for the part (find
+    "CL-nRCD-nRP" in the vendor spec for the DDR4 part).
+
+*   `capacityPerDieGb`: Capacity per die in gigabits. Valid values: `2, 4, 8,
+    16` Gb part.
+
+*   `diesPerPackage`: Number of dies on the part. Valid values: `1, 2` dies per
+    package.
+
+*   `packageBusWidth`: Number of bits of the device's address bus. Valid values:
+    `8, 16` bit-wide bus. NOTE: Width of x4 is not supported by this tool.
+
+*   `ranksPerPackage`: From Jedec doc 4_01_02_AnnexL-1R23: “Package ranks per
+    DIMM” refers to the collections of devices on the module sharing common chip
+    select signals (across the data width of the DIMM), either from the edge
+    connector for unbuffered modules or from the outputs of a registering clock
+    driver for RDIMMs and LRDIMMs.Number of bits of the device's address bus.
+    Valid values: `1, 2` package ranks.
+
+#### Optional
+
+The following options are calculated by the tool based on the mandatory
+attributes described for the part, but there may be cases where a default value
+must be overridden, such as when a device appears to be 3200AA, but does not
+support all of the CAS latencies typically supported by a speed bin 3200AA part.
+To deal with such a case, the variable can be overridden here and the tool will
+use this value instead of calculating one. All values must be defined in
+picosecond units, except for "CASLatencies", which would be represented as a
+string like "9 10 11 12 14".
+
+*   `TAAMinPs`: Defines the minimum CAS Latency. Table 48 of Jedec doc
+    4_01_02_AnnexL-5R29 lists tAAmin for each speed grade.
+
+*   `TRASMinPs`: Refers to the minimum active to precharge delay time. Table 55
+    of Jedec doc 4_01_02_AnnexL-5R29 lists tRPmin for each speed grade.
+
+*   `TCKMinPs`: Refers to the minimum clock cycle time. Table 42 of Jedec doc
+    4_01_02_AnnexL-5R29 lists tCKmin for each speed grade.
+
+*   `TCKMaxPs`:Refers to the minimum clock cycle time. Table 44 of Jedec doc
+    4_01_02_AnnexL-5R29 lists tCKmin for each speed grade.
+
+*   `TRFC1MinPs`: Refers to the minimum refresh recovery delay time. Table 59 of
+    Jedec doc 4_01_02_AnnexL-5R29 lists tRFC1min for each page size.
+
+*   `TRFC2MinPs`: Refers to the minimum refresh recovery delay time. Table 61 of
+    Jedec doc 4_01_02_AnnexL-5R29 lists tRFC2min for each page size.
+
+*   `TRFC4MinPs`: Refers to the minimum refresh recovery delay time. Table 63 of
+    Jedec doc 4_01_02_AnnexL-5R29 lists tRFC4min for each page size.
+
+*   `TFAWMinPs`:: Refers to the minimum four activate window delay time. Table
+    66 of Jedec doc 4_01_02_AnnexL-5R29 lists tFAWmin for each speed grade and
+    page size combination.
+
+*   `TRRDSMinPs`: Refers to the minimum activate to activate delay time to
+    different bank groups. Table 68 of Jedec doc 4_01_02_AnnexL-5R29 lists
+    tRRD_Smin for each speed grade and page size combination.
+
+*   `TRRDLMinPs`: Refers to the minimum activate to activate delay time to the
+    same bank group. Table 70 of Jedec doc 4_01_02_AnnexL-5R29 lists tRRD_Lmin
+    for each speed grade and page size combination.
+
+*   `TCCDLMinPs`: Refers to the minimum CAS to CAS delay time to same bank
+    group. Table 72 of Jedec doc 4_01_02_AnnexL-5R29 lists tCCD_Lmin for each
+    speed grade.
+
+*   `TWRMinPs`: Refers to the minimum write recovery time. Table 75 of Jedec doc
+    4_01_02_AnnexL-5R29 lists tWRmin for each ddr4 type.
+
+*   `TWTRSMinPs`: Refers to minimum write to read time to different bank group.
+    Table 78 of Jedec doc 4_01_02_AnnexL-5R29 lists tWTR_Smin for each ddr4
+    type.
+
+*   `TWTRLMinPs`: Refers to minimum write to read time to same bank group. Table
+    80 of Jedec doc 4_01_02_AnnexL-5R29 lists tWTR_Lmin for each ddr4 type.
+
+*   `CASLatencies`: Refers to the CAS latencies supported by the part. The speed
+    bin tables in the back of Jedec doc 4_01_02_AnnexL-5R29 define the standard
+    CAS latencies that a speed bin part is supposed to support. In cases where a
+    part does not support all of the CAS latencies listed in the speed bin
+    tables, this entry should be used to override the default settings.
+
+#### Example `memory_parts.json`
+
+```
+{
+    "parts": [
+        {
+            "name": "K4A8G165WC-BCWE",
+            "attribs": {
+                "speedMTps": 3200,
+                "CL_nRCD_nRP": 22,
+                "capacityPerDieGb": 8,
+                "diesPerPackage": 1,
+                "packageBusWidth": 16,
+                "ranksPerPackage": 1
+            }
+        },
+        {
+            "name": "MT40A1G16KD-062E:E",
+            "attribs": {
+                "speedMTps": 3200,
+                "CL_nRCD_nRP": 22,
+                "capacityPerDieGb": 16,
+                "diesPerPackage": 1,
+                "packageBusWidth": 16,
+                "ranksPerPackage": 1,
+                "TRFC1MinPs": 350000,
+                "TRFC2MinPs": 260000,
+                "TRFC4MinPs": 160000
+            }
+        },
+    ]
+}
+```
+
+### Output
+
+The `spd_gen` tool generates the directory structure shown below. The inputs to
+the tool are the `memory_parts.json` files, and all other files are generated.
+
+```
+    spd
+      |
+      |_ lp4x
+           |
+           |_ memory_parts.json
+           |_ platforms_manifest.generated.txt
+           |_ set-0
+                |_parts_spd_manifest.generated.txt
+                |_spd-1.hex
+                |_spd-2.hex
+                |_...
+           |_ set-1
+                |_...
+           |_...
+      |
+      |_ ddr4
+           |
+           |_ memory_parts.json
+           |_ platforms_manifest.generated.txt
+           |_ set-0
+                |_parts_spd_manifest.generated.txt
+                |_spd-1.hex
+                |_spd-2.hex
+                |_...
+           |_ set-1
+                |_...
+           |_...
+      |_...
+```
+
+The files generated are:
+
+*   `spd-X.hex`: Deduplicated SPDs for all the memory parts in the input JSON
+    file.
+
+*   `parts_spd_manifest.generated.txt`: A CSV file mapping each memory part to
+    one of the deduplicated SPD files. E.g.
+
+    ```
+    H9HCNNNBKMMLXR-NEE,spd-1.hex
+    H9HCNNNFAMMLXR-NEE,spd-2.hex
+    K4U6E3S4AA-MGCL,spd-1.hex
+    K4UBE3D4AA-MGCL,spd-3.hex
+    MT53E1G32D2NP-046 WT:A,spd-4.hex
+    ```
+
+*   `platforms_manifest.generated.txt`: A CSV file mapping each platform to the
+    SPD set used by that platform. E.g.
+
+    ```
+    TGL,set-0
+    ADL,set-0
+    JSL,set-1
+    CZN,set-1
+    ```
+
+## Tool 2 - `part_id_gen`
+
+This program takes the following inputs:
+
+*   The SoC platform which the board is based on, e.g. ADL.
+*   The memory technology used by the board, e.g. lp4x.
+*   The path to the directory where the generated Makefile.inc should be placed.
+*   A CSV file containing a list of the memory parts used by the board, with an
+    optional fixed ID for each part. NOTE: Only assign a fixed ID if required
+    for legacy reasons.
+
+Example of a CSV file using fixed IDs:
+
+```
+K4AAG165WA-BCWE,1
+MT40A512M16TB-062E:J
+MT40A1G16KD-062E:E
+K4A8G165WC-BCWE
+H5AN8G6NDJR-XNC,8
+H5ANAG6NCMR-XNC
+```
+
+Explanation: This will ensure that the SPDs for K4AAG165WA-BCWE and
+H5AN8G6NDJR-XNC are assigned to IDs 1 and 8 respectively. The SPDs for all other
+memory parts will be assigned to the first compatible ID. Assigning fixed IDs
+may result in duplicate SPD entries or gaps in the ID mapping.
+
+### Output
+
+The `part_id_gen` tool outputs the following:
+
+*   It prints the DRAM hardware strap ID which should be allocated to each
+    memory part in the input file.
+*   It generates a `Makefile.inc` in the given directory. This is used to
+    integrate the SPD files generated by `spd_gen` with the coreboot build for
+    the board.
+*   It generates a `dram_id.generated.txt` in the same directory as the
+    `Makefile.inc`. This lists the part IDs assigned to each memory part, and is
+    useful for itegration with the board schematics.
+
+Sample `Makefile.inc`:
+
+```
+# SPDX-License-Identifier: GPL-2.0-or-later
+# This is an auto-generated file. Do not edit!!
+# Generated by:
+# util/spd_tools/bin/part_id_gen ADL lp4x src/mainboard/google/brya/variants/felwinter/memory src/mainboard/google/brya/variants/felwinter/memory/mem_parts_used.txt
+
+SPD_SOURCES =
+SPD_SOURCES += spd/lp4x/set-0/spd-1.hex      # ID = 0(0b0000)  Parts = K4U6E3S4AA-MGCR, H9HCNNNBKMMLXR-NEE
+SPD_SOURCES += spd/lp4x/set-0/spd-3.hex      # ID = 1(0b0001)  Parts = K4UBE3D4AA-MGCR
+SPD_SOURCES += spd/lp4x/set-0/spd-4.hex      # ID = 2(0b0010)  Parts = MT53E1G32D2NP-046 WT:A
+```
+
+NOTE: Empty entries may be required if there is a gap created by a memory part
+with a fixed ID.
+
+Sample `dram_id.generated.txt`:
+
+```
+# SPDX-License-Identifier: GPL-2.0-or-later
+# This is an auto-generated file. Do not edit!!
+# Generated by:
+# util/spd_tools/bin/part_id_gen ADL lp4x src/mainboard/google/brya/variants/felwinter/memory src/mainboard/google/brya/variants/felwinter/memory/mem_parts_used.txt
+
+DRAM Part Name                 ID to assign
+K4U6E3S4AA-MGCR                0 (0000)
+K4UBE3D4AA-MGCR                1 (0001)
+H9HCNNNBKMMLXR-NEE             0 (0000)
+MT53E1G32D2NP-046 WT:A         2 (0010)
+```
+
+### Note of caution
+
+The `part_id_gen` tool assigns DRAM IDs based on the order of the part names in
+the input file. Thus, when adding a new memory part to the list, it should
+always go at the end of the file. This guarantees that the memory parts that
+were already assigned IDs do not change.
+
+## How to build the tools?
+
+```
+make clean -C util/spd_tools
+make -C util/spd_tools
+```
+
+## How to use the tools?
+
+### `spd_gen`
+
+Usage:
+
+```
+util/spd_tools/bin/spd_gen <mem_parts_list_json> <mem_technology>
+```
+
+Example:
+
+```
+util/spd_tools/bin/spd_gen spd/lp4x/memory_parts.json lp4x
+```
+
+### `part_id_gen`
+
+Usage:
+
+```
+util/spd_tools/bin/part_id_gen <platform> <mem_technology> <makefile_dir> <mem_parts_used_file>
+```
+
+Example:
+
+```
+util/spd_tools/bin/part_id_gen \
+  ADL \
+  lp4x \
+  src/mainboard/google/brya/variants/felwinter/memory \
+  src/mainboard/google/brya/variants/felwinter/memory/mem_parts_used.txt
+```
+
+### Need to add a new memory part for a board?
+
+*   If the memory part is not present in the global list of memory parts for
+    that memory technology (e.g. `spd/lp4x/memory_parts.json`), then add the
+    memory part name and attributes as per the datasheet.
+
+    *   Use `spd_gen` to regenerate all the SPD files and manifests for that
+        memory technology. Either a new SPD file will be generated for the new
+        part, or an existing one will be reused.
+    *   Upload the new SPD (if one is created) and the manifest changes for
+        review.
+
+*   Update the file containing the memory parts used by board (variant), by
+    adding the new memory part name at the end of the file.
+
+    *   Use `part_id_gen` to update the variant's `Makefile.inc` and
+        `dram_id.generated.txt` with the new part.
+    *   Upload the changes to `Makefile.inc` and `dram_id.generated.txt` for
+        review.