hw/ip/rom_ctrl/data/rom_ctrl.hjson

// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
{
  name: "rom_ctrl"
  clocking: [{clock: "clk_i", reset: "rst_ni"}],
  regwidth: "32"
  bus_interfaces: [
    { protocol: "tlul", direction: "device", name: "regs" }
    { protocol: "tlul", direction: "device", name: "rom" },
  ],
  param_list: [
    { name:    "BootRomInitFile",
      type:    "",
      default: '""',
      desc:    "Contents of mask ROM"
      local:   "false",
      expose:  "true"
    }

    { name:      "RndCnstScrNonce",
      type:      "bit [63:0]",
      desc:      "Fixed nonce used for address / data scrambling"
      randcount: "64",
      randtype:  "data"
    }

    { name:      "RndCnstScrKey",
      type:      "bit [127:0]",
      desc:      "Randomised constant used as a scrambling key for ROM data"
      randcount: "128",
      randtype:  "data"
    }

    { name:      "SecDisableScrambling",
      type:      "bit",
      desc:      '''
        Disable scrambling and checking in rom_ctrl, turning the block into a
        simple ROM wrapper. This isn't intended for real chips, but is useful
        for small FPGA targets where there's not space for the PRINCE
        primitives.
      '''
      local:     "false",
      expose:    "true",
      default:   "1'b0"
    }
  ]
  alert_list: [
    { name: "fatal"
      desc: "A fatal error. Fatal alerts are non-recoverable and will be asserted until a hard reset."
    }
  ],
  inter_signal_list: [
    // Interface to memory configuration
    { name:    "rom_cfg",
      package: "prim_rom_pkg",
      struct:  "rom_cfg",
      act:     "rcv"
      type:    "uni",
    },

    // Power manager interface
    { name:    "pwrmgr_data"
      package: "rom_ctrl_pkg"
      struct:  "pwrmgr_data"
      act:     "req"
      type:    "uni"
    },

    // Keymgr interface
    { name:    "keymgr_data"
      package: "rom_ctrl_pkg"
      struct:  "keymgr_data"
      act:     "req"
      type:    "uni"
    },

    // KMAC interface
    { name:    "kmac_data"
      package: "kmac_pkg"
      struct:  "app"
      act:     "req"
      type:    "req_rsp"
    },
  ],
  countermeasures: [
    {
      name: "FSM.SPARSE",
      desc: "FSMs are sparsely encoded."
    },
    {
      name: "MEM.SCRAMBLE",
      desc: "The ROM is scrambled."
    },
    {
      name: "MEM.DIGEST",
      desc: "A cSHAKE digest is computed of the ROM contents."
    },
    {
      name: "BUS.MUBI",
      desc: "Checker FSM 'done' signal is multi-bit encoded when passed to pwrmgr."
    },
    {
      name: "BUS.INTEGRITY",
      desc: '''
        TL bus control and data signals are integrity protected (using the system-wide end-to-end
        integrity scheme).
      '''
    },
    {
      name: "MUX.MUBI",
      desc: "Checker/Bus mux is multi-bit encoded."
    },
    {
      name: "CTRL.REDUN",
      desc: '''
        Addresses from TL accesses are passed redundantly to the scrambled ROM module, to ensure the
        address lines are not independently faultable downstream of the bus integrity ECC check.
      '''
    },
    {
      name: "CTRL.CONSISTENCY",
      desc: '''
        There are simple checks to detect unexpected changes in the state of the checker, especially
        after it should have finished working (and the host processor is now accessing ROM to
        execute code).
      '''
    },
  ]
  regwidth: "32"
  registers: {
    regs: [
      { name: "FATAL_ALERT_CAUSE",
        desc: '''
          The cause of a fatal alert.

          The bits of this register correspond to errors that can cause a fatal
          alert. Software can read these bits to see what went wrong. Once set,
          these bits cannot be cleared.
        '''
        swaccess: "ro",
        hwaccess: "hwo",
        fields: [
          { bits: "0",
            name: "checker_error",
            resval: 0,
            desc: "Set on a fatal error detected by the ROM checker."
          }
          { bits: "1",
            name: "integrity_error",
            resval: 0,
            desc: "Set on an integrity error from the register interface."
          }
        ]
      }

      {
        multireg: {
          cname: "ROM_CTRL",
          name: "DIGEST",
          desc: "The digest computed from the contents of ROM"
          count: "8"
          swaccess: "ro"
          hwaccess: "hrw"
          fields: [
            {
              bits: "31:0"
              name: "DIGEST"
              desc: "32 bits of the digest"
            }
          ]
          // Disable CSR checks for digest registers, since their values will
          // change under the feet of the CSR package as the ROM checker computes
          // a digest. These values are checked instead by the rom_ctrl TB.
          tags: ["excl:CsrAllTests:CsrExclCheck"]
        }
      }
      {
        multireg: {
          cname: "ROM_CTRL",
          name: "EXP_DIGEST",
          desc: "The expected digest, stored in the top words of ROM"
          count: "8"
          swaccess: "ro"
          hwaccess: "hrw"
          fields: [
            {
              bits: "31:0"
              name: "DIGEST"
              desc: "32 bits of the digest"
            }
          ]
          // As with DIGEST, these values are checked by the rom_ctrl TB.
          tags: ["excl:CsrAllTests:CsrExclCheck"]
        }
      }
    ],

    rom: [
      // ROM size (given as `items` below) must be a power of two.
      //
      // NOTE: This number is replicated in ../util/scramble_image.py: keep the
      // two in sync.
      { window: {
          name: "ROM"
          items: "8192" // 32 KiB
          swaccess: "ro",
          data-intg-passthru: "true",
          desc: '''ROM data'''
        }
      }
    ]
  }
}