hw/ip/otp_ctrl/data/otp_ctrl_mmap.hjson

// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
//
// Use the gen-otp-mmap.py script to update dependent files (like documentation
// tables the comportable hjson and metadata SV package):
//
// $ ./util/design/gen-otp-mmap.py
//
// Make sure to regenerate the CSRs after converting the memory map:
//
// $ cd ${PROJ_ROOT}
// $ make -C hw regs
//

{
    // Seed to be used for generation of partition item default values.
    // Can be overridden on the command line with the --seed switch.
    seed: "10556718629619452145"

    otp: {
        width: "2", // bytes
        depth: "1024"
    }

    // Definition of scrambling and digest constants and keys.
    scrambling: {
        key_size:  "16",
        iv_size:   "8",
        cnst_size: "16",
        keys: [
            {
                name:  "Secret0Key",
                value: "<random>",
            }
            {
                name:  "Secret1Key",
                value: "<random>",
            }
            {
                name:  "Secret2Key",
                value: "<random>",
            }
        ]
        digests: [
            // This is the consistency digest used by all partitions.
            {
                name:       "CnstyDigest",
                iv_value:   "<random>",
                cnst_value: "<random>",
            }
            // The other digest configurations below are used for
            // key derivation and token hashing.
            {
                name:       "LcRawDigest",
                iv_value:   "<random>",
                cnst_value: "<random>",
            }
            {
                name:       "FlashDataKey",
                iv_value:   "<random>",
                cnst_value: "<random>",
            }
            {
                name:       "FlashAddrKey",
                iv_value:   "<random>",
                cnst_value: "<random>",
            }
            {
                name:       "SramDataKey",
                iv_value:   "<random>",
                cnst_value: "<random>",
            }
        ]
    }

    // The enumeration order below defines the address map of the OTP controller,
    // if the offsets are not defined explicitly via the "offset" key.
    // Note that the digest items are added automatically to the address map.
    partitions: [
        {
            name:       "CREATOR_SW_CFG",
            variant:    "Unbuffered",
            size:       "768", // in bytes
            secret:     "False",
            sw_digest:  "True",
            hw_digest:  "False",
            write_lock: "Digest",
            read_lock:  "CSR",
            key_sel:    "NoKey",
            bkout_type: "False", // Do not generate a breakout type for this partition.
            items: [
                {
                    name: "CREATOR_SW_CFG_CONTENT",
                    size: "760"
                }
            ],
            desc: '''Software configuration partition for
            device-specific calibration data (Clock, LDO,
            RNG, device identity).
            '''
        }
        {
            name:       "OWNER_SW_CFG",
            variant:    "Unbuffered",
            size:       "768", // in bytes
            secret:     "False",
            sw_digest:  "True",
            hw_digest:  "False",
            write_lock: "Digest",
            read_lock:  "CSR",
            key_sel:    "NoKey",
            bkout_type: "False",
            items: [
                {
                    name: "OWNER_SW_CFG_CONTENT",
                    size: "760"
                }
            ],
            desc: '''Software configuration partition for
            data that changes software behavior, specifically
            in the ROM. E.g., enabling defensive features in
            ROM or selecting failure modes if verification fails.
            '''
        }
        {
            name:       "HW_CFG",
            variant:    "Buffered",
            size:       "240", // in bytes
            secret:     "False",
            sw_digest:  "False",
            hw_digest:  "True",
            write_lock: "Digest",
            read_lock:  "None",
            key_sel:    "NoKey",
            bkout_type: "True",
            items: [
                {
                    name:    "DEVICE_ID",
                    size:    "32",
                    // Default value to be output in case partition has not
                    // initialized or is in error state. If not specified,
                    // a value of '0 will be used.
                    inv_default: "<random>",
                }
            ],
            desc: '''Hardware configuration bits used to hardwire
            specific hardware functionality. E.g., raw entropy
            accessibility or FLASH scrambling bypass range.
            '''
        }
        {
            name:       "SECRET0",
            variant:    "Buffered",
            size:       "40", // in bytes
            secret:     "True",
            sw_digest:  "False",
            hw_digest:  "True",
            write_lock: "Digest",
            read_lock:  "Digest",
            key_sel:    "Secret0Key",
            bkout_type: "False",
            items: [
                {
                    name: "TEST_UNLOCK_TOKEN",
                    // This will generate a random default to be output in
                    // case partition has not initialized or is in error state.
                    // If not specified, a value of '0 will be used.
                    inv_default: "<random>",
                    size: "16"
                }
                {
                    name: "TEST_EXIT_TOKEN",
                    inv_default: "<random>",
                    size: "16"
                }
            ],
            desc: '''Test unlock tokens.
            '''
        }
        {
            name:       "SECRET1",
            variant:    "Buffered",
            size:       "88", // in bytes
            secret:     "True",
            sw_digest:  "False",
            hw_digest:  "True",
            write_lock: "Digest",
            read_lock:  "Digest",
            key_sel:    "Secret1Key",
            bkout_type: "False",
            items: [
                {
                    name: "FLASH_ADDR_KEY_SEED",
                    inv_default: "<random>",
                    size: "32"
                }
                {
                    name: "FLASH_DATA_KEY_SEED",
                    inv_default: "<random>",
                    size: "32"
                }
                {
                    name: "SRAM_DATA_KEY_SEED",
                    inv_default: "<random>",
                    size: "16"
                }
            ],
            desc: '''SRAM and FLASH scrambling key roots
            used for scrambling key derivation.
            '''
        }
        {
            name:       "SECRET2",
            variant:    "Buffered",
            size:       "88", // in bytes
            secret:     "True",
            sw_digest:  "False",
            hw_digest:  "True",
            write_lock: "Digest",
            read_lock:  "Digest",
            key_sel:    "Secret2Key",
            bkout_type: "False",
            items: [
                {
                    name: "RMA_TOKEN",
                    inv_default: "<random>",
                    size: "16"
                }
                {
                    name: "CREATOR_ROOT_KEY_SHARE0",
                    inv_default: "<random>",
                    size: "32"
                }
                {
                    name: "CREATOR_ROOT_KEY_SHARE1",
                    inv_default: "<random>",
                    size: "32"
                }
            ],
            desc: '''RMA unlock token and creator root key.
            '''
        }
        {
            name:       "LIFE_CYCLE",
            variant:    "LifeCycle",
            size:       "56", // in bytes
            secret:     "False",
            sw_digest:  "False",
            hw_digest:  "False",
            write_lock: "None",
            read_lock:  "None",
            key_sel:    "NoKey",
            bkout_type: "False",
            items: [
                {
                    name: "LC_STATE",
                    size: "24"
                }
                {
                    name: "LC_TRANSITION_CNT",
                    size: "32"
                }
            ],
            desc: '''Life-cycle related bits. This
            partition cannot be locked as the life cycle
            state needs to be able to advance to RMA in-field.
            Note that while this partition is not marked secret
            (i.e. it is not scrambled) it is not readable
            nor writeable via the DAI. Only the LC controller
            can access this partition, and even via the LC
            controller it is not possible to read the
            raw manufacturing life cycle state in encoded form,
            since that encoding is considered a netlist secret.
            The LC controller only exposes a decoded version of
            this state.
            '''
        }
    ]
}