rstmgr.hjson

// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
//
// ------------------- W A R N I N G: A U T O - G E N E R A T E D   C O D E !! -------------------//
// PLEASE DO NOT HAND-EDIT THIS FILE. IT HAS BEEN AUTO-GENERATED WITH THE FOLLOWING COMMAND:
// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0



# RSTMGR register template
#
{
  name:               "rstmgr",
  human_name:         "Reset Manager",
  one_line_desc:      "Controls the on-chip reset signals, records reset cause and CPU crash dump for software",
  one_paragraph_desc: '''
  Reset Manager controls the on-chip reset.
  It receives one root power-on reset signal for each power domain from AST and feeds one reset signal for each on-chip reset domain to the OpenTitan hardware blocks.
  Resets can be requested by Power Manager, which internally arbitrates peripheral resets, e.g., from AON Timer and Alert Handler, RISC-V Debug Module, and to a limited extent by software.
  Through always-on registers, software can get information on the reset cause, as well as alert and CPU status prior to a triggered reset (crash dump).
  To deter fault injection (FI) attacks, several countermeasures are implemented, including consistency checks of leaf resets and support for shadow resets.
  '''
  // Unique comportable IP identifier defined under KNOWN_CIP_IDS in the regtool.
  cip_id:             "22",
  design_spec:        "../doc",
  dv_doc:             "../doc/dv",
  hw_checklist:       "../doc/checklist",
  sw_checklist:       "/sw/device/lib/dif/dif_rstmgr",
  revisions: [
    {
      version:            "1.0.0",
      life_stage:         "L1",
      design_stage:       "D2S",
      verification_stage: "V2S",
      dif_stage:          "S2",
    }
  ]
  clocking: [
    {clock: "clk_i", reset: "rst_ni", primary: true},
    {clock: "clk_aon_i"},
    {clock: "clk_io_div4_i"},
    {clock: "clk_main_i"},
    {clock: "clk_io_i"},
    {clock: "clk_io_div2_i"},
    {clock: "clk_usb_i"},
    {clock: "clk_por_i", reset: "rst_por_ni"},
  ]
  bus_interfaces: [
    { protocol: "tlul", direction: "device" }
  ],
  alert_list: [
    { name: "fatal_fault",
      desc: '''
        This fatal alert is triggered when a fatal structural fault is detected.
        Structural faults include errors such as sparse fsm errors and tlul integrity errors.
      '''
    }
    { name: "fatal_cnsty_fault",
      desc: '''
        This fatal alert is triggered when a reset consistency fault is detected.
        It is separated from the category above for clearer error collection and debug.
      '''
    }
  ],
  countermeasures: [
    { name: "BUS.INTEGRITY",
      desc: "End-to-end bus integrity scheme."
    }
    { name: "SCAN.INTERSIG.MUBI",
      desc: "scan control signals are multibit"
    }
    { name: "LEAF.RST.BKGN_CHK",
      desc: "Background consistency checks for each leaf reset."
    }
    { name: "LEAF.RST.SHADOW",
      desc: "Leaf resets to blocks containing shadow registers are shadowed"
    }
    { name: "LEAF.FSM.SPARSE",
      desc: "Sparsely encoded fsm for each leaf rst check. The Hamming delta is only 3 as there are a significant number of leaf resets"
    }
    { name: "SW_RST.CONFIG.REGWEN",
      desc: "Software reset controls are protected by regwen"
    }
    { name: "DUMP_CTRL.CONFIG.REGWEN",
      desc: "Crash dump controls are protected by regwen"
    }
  ]
  regwidth: "32",
  scan: "true",
  scan_reset: "true",
  param_list: [
    { name: "RdWidth",
      desc: "Read width for crash info",
      type: "int",
      default: "32",
      local: "true"
    },

    { name: "IdxWidth",
      desc: "Index width for crash info",
      type: "int",
      default: "4",
      local: "true"
    },

    { name: "NumHwResets",
      desc: "Number of hardware reset requests, inclusive of debug resets and pwrmgr's internal resets ",
      type: "int",
      default: "5",
      local: "true"
    },

    { name: "NumSwResets",
      desc: "Number of software resets",
      type: "int",
      default: "8",
      local: "true"
    },

    { name: "NumTotalResets",
      desc: "Number of total reset requests, inclusive of hw/sw, por and low power exit",
      type: "int",
      default: "8",
      local: "true"
    },

    { name:    "SecCheck",
      type:    "bit",
      default: "1'b1",
      desc:    '''
        When 1, enable rstmgr reset consistency checks.
        When 0, there are no consistency checks.
      '''
      local:   "false",
      expose:  "true"
    },

    { name:    "SecMaxSyncDelay",
      type:    "int",
      default: "2",
      desc:    '''
        The maximum synchronization delay for parent / child reset checks.
      '''
      local:   "false",
      expose:  "true"
    },
  ],

  // Define rstmgr struct package
  inter_signal_list: [
    { struct:  "logic",
      type:    "uni",
      name:    "por_n",
      act:     "rcv",
      width:   "2"
      desc:    '''
        Root power on reset signals from ast.
        There is one root reset signal for each core power domain.
      '''
    },

    { struct:  "pwr_rst",    // pwr_rst_req_t, pwr_rst_rsp_t
      type:    "req_rsp",
      name:    "pwr",        // resets_o (req), resets_i (rsp)
      act:     "rsp",
      desc:    '''
         Reset request signals from power manager.
         Power manager can request for specific domains of the lc/sys reset tree to assert.
      '''
    },

    { struct:  "rstmgr_out",
      type:    "uni",
      name:    "resets",
      act:     "req",
      package: "rstmgr_pkg", // Origin package (only needs for the req)
      desc:    '''
        Leaf resets fed to the system.
      '''
    },

    { struct:  "rstmgr_rst_en",
      type:    "uni",
      name:    "rst_en",
      act:     "req",
      package: "rstmgr_pkg", // Origin package (only needs for the req)
      desc:    '''
        Low-power-group outputs used by alert handler.
      '''
    },

    { struct:  "alert_crashdump",
      type:    "uni",
      name:    "alert_dump",
      act:     "rcv",
      package: "alert_pkg",
      desc:    '''
        Alert handler crash dump information.
      '''
    },

    { struct:  "cpu_crash_dump",
      type:    "uni",
      name:    "cpu_dump",
      act:     "rcv",
      package: "rv_core_ibex_pkg",
      desc:    '''
        Main processing element crash dump information.
      '''
    },

    { struct:  "mubi4",
      type:    "uni",
      name:    "sw_rst_req",
      act:     "req",
      package: "prim_mubi_pkg",
      desc:    '''
        Software requested system reset to pwrmgr.
      '''
    },

    // Exported resets
  ],

  registers: [

    { name: "RESET_REQ",
      desc: '''
        Software requested system reset.
      ''',
      swaccess: "rw",
      hwaccess: "hrw",
      fields: [
        { bits: "3:0",
          mubi: true
          name: "VAL",
          desc: '''
            When set to kMultiBitBool4True, a reset to power manager is requested.
            Upon completion of reset, this bit is automatically cleared by hardware.
          '''
          resval: false
        },
      ],
      tags: [// This register will cause a system reset, directed test only
        "excl:CsrAllTests:CsrExclWrite"]
    },

    { name: "RESET_INFO",
      desc: '''
            Device reset reason.
            ''',
      swaccess: "rw1c",
      hwaccess: "hwo",
      sync: "clk_por_i",
      fields: [
        { bits: "0",
          hwaccess: "none",
          name: "POR",
          desc: '''
            Indicates when a device has reset due to power up.
            '''
          resval: "1"
        },

        { bits: "1",
          name: "LOW_POWER_EXIT",
          desc: '''
            Indicates when a device has reset due low power exit.
            '''
          resval: "0"
        },

        { bits: "2",
          hwaccess: "hrw",
          name: "SW_RESET",
          desc: '''
            Indicates when a device has reset due to !!RESET_REQ.
            '''
          resval: "0"
        },

        // reset requests include escalation reset, main power glitch,
        // ndm reset request + other peripheral requests
        { bits: "7:3",
          hwaccess: "hrw",
          name: "HW_REQ",
          desc: '''
            Indicates when a device has reset due to a hardware requested reset.
            The bit mapping is as follows:
            b3: sysrst_ctrl_aon: OpenTitan reset request to `rstmgr` (running on AON clock).
            b4: aon_timer_aon: watchdog reset requestt
            b5: pwrmgr_aon: main power glitch reset request
            b6: alert_handler: escalation reset request
            b7: rv_dm: non-debug-module reset request
            '''
          resval: "0"
        },
      ]
    },

    { name: "ALERT_REGWEN",
      desc: "Alert write enable",
      swaccess: "rw0c",
      hwaccess: "none",
      fields: [
        { bits: "0",
          name: "EN",
          resval: "1"
          desc: '''
            When 1, !!ALERT_INFO_CTRL can be modified.
          '''
        },
      ]
    }

    { name: "ALERT_INFO_CTRL",
      desc: '''
            Alert info dump controls.
            ''',
      swaccess: "rw",
      hwaccess: "hro",
      sync: "clk_por_i",
      regwen: "ALERT_REGWEN",
      fields: [
        { bits: "0",
          name: "EN",
          hwaccess: "hrw",
          desc: '''
            Enable alert dump to capture new information.
            This field is automatically set to 0 upon system reset (even if rstmgr is not reset).
            '''
          resval: "0"
        },

        { bits: "4+IdxWidth-1:4",
          name: "INDEX",
          desc: '''
            Controls which 32-bit value to read.
            '''
          resval: "0"
        },
      ]
    },

    { name: "ALERT_INFO_ATTR",
      desc: '''
            Alert info dump attributes.
            ''',
      swaccess: "ro",
      hwaccess: "hwo",
      sync: "clk_por_i",
      hwext: "true",
      fields: [
        { bits: "IdxWidth-1:0",
          name: "CNT_AVAIL",
          swaccess: "ro",
          hwaccess: "hwo",
          desc: '''
            The number of 32-bit values contained in the alert info dump.
            '''
          resval: "0",
          tags: [// This field is tied to a design constant, thus the
                 // default value is never 0.  Since there is not a way
                 // to express this behavior at the moment, exclude from automated checks.
                 "excl:CsrAllTests:CsrExclCheck"]
        },
      ]
    },

    { name: "ALERT_INFO",
      desc: '''
              Alert dump information prior to last reset.
              Which value read is controlled by the !!ALERT_INFO_CTRL register.
            ''',
      swaccess: "ro",
      hwaccess: "hwo",
      sync: "clk_por_i",
      hwext: "true",
      fields: [
        { bits: "31:0",
          name: "VALUE",
          desc: '''
            The current 32-bit value of crash dump.
            '''
          resval: "0",
        },
      ]
    },
    { name: "CPU_REGWEN",
      desc: "Cpu write enable",
      swaccess: "rw0c",
      hwaccess: "none",
      fields: [
        { bits: "0",
          name: "EN",
          resval: "1"
          desc: '''
            When 1, !!CPU_INFO_CTRL can be modified.
          '''
        },
      ]
    }

    { name: "CPU_INFO_CTRL",
      desc: '''
            Cpu info dump controls.
            ''',
      swaccess: "rw",
      hwaccess: "hro",
      sync: "clk_por_i",
      regwen: "CPU_REGWEN",
      fields: [
        { bits: "0",
          name: "EN",
          hwaccess: "hrw",
          desc: '''
            Enable cpu dump to capture new information.
            This field is automatically set to 0 upon system reset (even if rstmgr is not reset).
            '''
          resval: "0"
        },

        { bits: "4+IdxWidth-1:4",
          name: "INDEX",
          desc: '''
            Controls which 32-bit value to read.
            '''
          resval: "0"
        },
      ]
    },

    { name: "CPU_INFO_ATTR",
      desc: '''
            Cpu info dump attributes.
            ''',
      swaccess: "ro",
      hwaccess: "hwo",
      sync: "clk_por_i",
      hwext: "true",
      fields: [
        { bits: "IdxWidth-1:0",
          name: "CNT_AVAIL",
          swaccess: "ro",
          hwaccess: "hwo",
          desc: '''
            The number of 32-bit values contained in the cpu info dump.
            '''
          resval: "0",
          tags: [// This field is tied to a design constant, thus the
                 // default value is never 0.  Since there is not a way
                 // to express this behavior at the moment, exclude from automated checks.
                 "excl:CsrAllTests:CsrExclCheck"]
        },
      ]
    },

    { name: "CPU_INFO",
      desc: '''
              Cpu dump information prior to last reset.
              Which value read is controlled by the !!CPU_INFO_CTRL register.
            ''',
      swaccess: "ro",
      hwaccess: "hwo",
      sync: "clk_por_i",
      hwext: "true",
      fields: [
        { bits: "31:0",
          name: "VALUE",
          desc: '''
            The current 32-bit value of crash dump.
            '''
          resval: "0",
        },
      ]
    },


    # Templated registers for software control

    { multireg: {
        cname: "RSTMGR_SW_RST",
        name:  "SW_RST_REGWEN",
        desc:  '''
          Register write enable for software controllable resets.
          When a particular bit value is 0, the corresponding value in !!SW_RST_CTRL_N can no longer be changed.
          When a particular bit value is 1, the corresponding value in !!SW_RST_CTRL_N can be changed.
        ''',
        count: "NumSwResets",
        swaccess: "rw0c",
        hwaccess: "none",
        compact: false,
        fields: [
          {
            bits: "0",
            name: "EN",
            desc: "Register write enable for software controllable resets",
            resval: "1",
          },
        ],
      }
    }

    { multireg: {
        cname: "RSTMGR_SW_RST",
        name:  "SW_RST_CTRL_N",
        desc:  '''
          Software controllable resets.
          When a particular bit value is 0, the corresponding module is held in reset.
          When a particular bit value is 1, the corresponding module is not held in reset.
        ''',
        count: "NumSwResets",
        swaccess: "rw",
        hwaccess: "hro",
        regwen: "SW_RST_REGWEN",
        regwen_multi: true,
        fields: [
          {
            bits: "0",
            name: "VAL",
            desc: "Software reset value",
            resval: "1",
          },
        ],
        tags: [// Don't reset other IPs as it will affect CSR access on these IPs.
               // In addition, rapid flips of these bits can occasionally cause the reset
               // consistency checkers to trigger alerts, which also update err_code bits.
               "excl:CsrAllTests:CsrExclWrite"]
      }
    }

    { name: "ERR_CODE",
      desc: '''
        A bit vector of all the errors that have occurred in reset manager
      ''',
      swaccess: "ro",
      hwaccess: "hrw",
      fields: [
        { bits: "0",
          name: "REG_INTG_ERR",
          desc: '''
            The register file has experienced an integrity error.
          '''
          resval: "0"
        },

        { bits: "1",
          name: "RESET_CONSISTENCY_ERR",
          desc: '''
            A inconsistent parent / child reset was observed.
          '''
          resval: "0"
        },

        { bits: "2",
          name: "FSM_ERR",
          desc: '''
            Sparsely encoded fsm error.
          '''
          resval: "0"
        },

      ]
    },
  ]
}