hw/ip/alert_handler/doc/alert_handler.tpl.hjson

// Copyright lowRISC contributors.
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
//
# ALERT_HANDLER register template
#
# Parameter (given by python tool)
#  - n_alerts:    Number of alert sources
#  - esc_cnt_dw:  Width of escalation counter
#  - accu_cnt_dw: Width of accumulator
{
  name: "ALERT_HANDLER",
  clock_primary: "clk_fixed",
  bus_device: "tlul",
  regwidth: "32",

##############################################################################
# interrupt registers for the classes
  interrupt_list: [
% for c in ['A', 'B', 'C', 'D']:
    { name: "CLASS${c}",
      desc: '''
            Interrupt state bit of Class ${c}. Set by HW in case an alert within this class triggered. Defaults true, write one to clear.
            ''',
    },
% endfor
  ],

  registers: [
##############################################################################
# register locks for alerts and class configs
    { name: "REGEN",
      desc: '''
            Register write enable for all control registers.
            ''',
      swaccess: "rw1c",
      hwaccess: "hro",
      fields: [
        {
            bits:   "0",
            desc: ''' When true, the alert enable and escalation configuration registers can be modified.
            When false, they become read-only. Defaults true, write one to clear. Note that this needs to be
            cleared after initial configuration at boot in order to lock in the configuration and activate
            the ping testing.
            '''
            resval: 1,
        },
      ]
    },
    { name:     "PING_TIMEOUT_CYC",
      desc:     '''
                Ping timeout cycle count.
                '''
      swaccess: "rw",
      hwaccess: "hro",
      regwen:   "REGEN",
      fields: [
        { bits: "23:0",
          resval:   32,
          desc: '''Timeout value in cycles. If an alert receiver or an escalation sender does not
          respond to a ping within this timeout window, a pingfail alert will be raised.
          '''
        }
      ]
    }
##############################################################################
# all alerts
    { multireg: { name:     "ALERT_EN",
                  desc:     '''Enable register for alerts.
                  ''',
                  count:    ${n_alerts},
                  swaccess: "rw",
                  hwaccess: "hro",
                  regwen:   "REGEN",
                  cname:    "alert",
                  fields: [
                    { bits: "0",
                      name: "EN_A",
                      desc: "Alert enable "
                    }
                  ]
                }
    },
    { multireg: { name:     "ALERT_CLASS",
                  desc:     '''Class assignment of alerts.
                  ''',
                  count:    ${n_alerts},
                  swaccess: "rw",
                  hwaccess: "hro",
                  regwen:   "REGEN",
                  cname:    "alert",
                  fields: [
                    {
                      bits: "1:0",
                      name: "CLASS_A",
                      desc: "Classification ",
                      enum: [
                              { value: "0", name: "ClassA", desc: "" },
                              { value: "1", name: "ClassB", desc: "" },
                              { value: "2", name: "ClassC", desc: "" },
                              { value: "3", name: "ClassD", desc: "" }
                            ]
                    }
                  ]
                }
    },
    { multireg: {
      name: "ALERT_CAUSE",
      desc: "Alert Cause Register",
      count: ${n_alerts},
      cname: "ALERT",
      swaccess: "rw1c",
      hwaccess: "hwo",
      fields: [
        { bits: "0", name: "A", desc: "Cause bit " }
      ]
      }
    },
##############################################################################
# local alerts
    { multireg: { name:     "LOC_ALERT_EN",
                  desc:     '''Enable register for the aggregated local alerts "alert
                  pingfail" (0), "escalation pingfail" (1), "alert integfail" (2) and "escalation integfail" (3).
                  ''',
                  count:    4,
                  swaccess: "rw",
                  hwaccess: "hro",
                  regwen:   "REGEN",
                  cname:    "local alert",
                  fields: [
                    { bits: "0",
                      name: "EN_LA",
                      desc: "Alert enable "
                    }
                  ]
                }
    },
    { multireg: { name:     "LOC_ALERT_CLASS",
                  desc:     '''Class assignment of local alerts. "alert
                  pingfail" (0), "escalation pingfail" (1), "alert integfail" (2) and "escalation integfail" (3).
                  ''',
                  count:    4,
                  swaccess: "rw",
                  hwaccess: "hro",
                  regwen:   "REGEN",
                  cname:    "local alert",
                  fields: [
                    {
                      # reduce range to 2:1 once above TODO has been fixed
                      bits: "1:0",
                      name: "CLASS_LA",
                      desc: "Classification ",
                      enum: [
                              { value: "0", name: "ClassA", desc: "" },
                              { value: "1", name: "ClassB", desc: "" },
                              { value: "2", name: "ClassC", desc: "" },
                              { value: "3", name: "ClassD", desc: "" }
                            ]
                    }
                  ]
                }
    },
    { name:     "LOC_ALERT_CAUSE",
      desc:     "Alert Cause Register for Local Alerts",
      swaccess: "rw1c",
      hwaccess: "hwo",
      fields: [
        { bits: "0",
          name: "LA0",
          desc: "True when pingfail alert has been detected on an alert receiver. Cleared with write"
        }
        { bits: "1",
          name: "LA1",
          desc: "True when pingfail alert has been detected on an escalation sender. Cleared with write"
        }
        { bits: "2",
          name: "LA2",
          desc: "True when integfail alert has been detected on an alert receiver. Cleared with write"
        }
        { bits: "3",
          name: "LA3",
          desc: "True when integfail alert has been detected on an escalation sender. Cleared with write"
        }
      ]
    },
##############################################################################
# classes
% for c in ['A', 'B', 'C', 'D']:
    { name:     "CLASS${c}_CTRL",
      desc:     "Escalation control register for alert Class ${c}. Can not be modified if !!REGEN is false."
      swaccess: "rw",
      hwaccess: "hro",
      regwen:   "REGEN",
      fields: [
        { bits: "0",
          name: "EN",
          desc: '''
                Enable escalation mechanisms (accumulation and
                interrupt timeout) for Class ${c}. Note that interrupts can fire
                regardless of whether the escalation mechanisms are enabled for
                this class or not.
                ''',
        }
        { bits: "1",
          name: "LOCK",
          desc: '''
                Enable automatic locking of escalation counter for class ${c}.
                If true, there is no way to stop the escalation protocol for class ${c}
                once it has been triggered.
                '''
        }
        { bits: "2",
          name: "EN_E0",
          resval: 1,
          desc: "Enable escalation signal 0 for class ${c}",
        }
        { bits: "3",
          name: "EN_E1",
          resval: 1,
          desc: "Enable escalation signal 1 for class ${c}",
        }
        { bits: "4",
          name: "EN_E2",
          resval: 1,
          desc: "Enable escalation signal 2 for class ${c}",
        }
        { bits: "5",
          name: "EN_E3",
          resval: 1,
          desc: "Enable escalation signal 3 for class ${c}",
        }
        { bits: "7:6",
          name: "MAP_E0",
          resval: 0,
          desc: "Determines in which escalation phase escalation signal 0 shall be asserted.",
        }
        { bits: "9:8",
          name: "MAP_E1",
          resval: 1,
          desc: "Determines in which escalation phase escalation signal 1 shall be asserted.",
        }
        { bits: "11:10",
          name: "MAP_E2",
          resval: 2,
          desc: "Determine sin which escalation phase escalation signal 2 shall be asserted.",
        }
        { bits: "13:12",
          name: "MAP_E3",
          resval: 3,
          desc: "Determines in which escalation phase escalation signal 3 shall be asserted.",
        }
      ]
    },
    { name:     "CLASS${c}_CLREN",
      desc:     '''
                Clear enable for escalation protocol of class ${c} alerts.
                '''
      swaccess: "rw1c",
      hwaccess: "hwo",
      fields: [
      {   bits:   "0",
          desc:   '''Register defaults to true, can only be cleared. This register is set
          to false by the hardware if the escalation protocol has been triggered and the bit
          !!CLASS${c}_CTRL.LOCK is true.
          ''',
          resval: 1,
        }
      ]
    },
    { name:     "CLASS${c}_CLR",
      desc:     '''
                Clear for esclation protocol of class ${c}.
                '''
      swaccess: "wo",
      hwaccess: "hro",
      hwqe:     "true",
      regwen:   "CLASS${c}_CLREN",
      fields: [
        { bits: "0",
          desc: '''Writing to this register clears the accumulator and aborts escalation
          (if it has been triggered). This clear is disabled if !!CLASS${c}_CLREN is false.
          '''
        }
      ]
    },
    { name:     "CLASS${c}_ACCUM_CNT",
      desc:     '''
                Current accumulation value for alert Class ${c}. Software can clear this register
                with a write to !!CLASS${c}_CLR register unless !!CLASS${c}_CLREN is false.
                '''
      swaccess: "ro",
      hwaccess: "hwo",
      hwext:    "true",
      fields: [
        { bits: "${accu_cnt_dw - 1}:0" }
      ]
    },
    { name:     "CLASS${c}_ACCUM_THRESH",
      desc:     '''
                Accumulation threshold value for alert Class ${c}.
                '''
      swaccess: "rw",
      hwaccess: "hro",
      regwen:   "REGEN",
      fields: [
        { bits: "${accu_cnt_dw - 1}:0",
          desc: '''Once the accumulation value register is equal to the threshold escalation will
          be triggered on the next alert occurrence within this class ${c} begins. Note that this
          register can not be modified if !!REGEN is false.
          '''
        }
      ]
    },
    { name:     "CLASS${c}_TIMEOUT_CYC",
      desc:     '''
                Interrupt timeout in cycles.
                '''
      swaccess: "rw",
      hwaccess: "hro",
      regwen:   "REGEN",
      fields: [
        { bits: "${esc_cnt_dw - 1}:0",
          desc: '''If the interrupt corresponding to this class is not
          handled within the specified amount of cycles, escalation will be triggered.
          Set to a positive value to enable the interrupt timeout for Class ${c}. The timeout is set to zero
          by default, which disables this feature. Note that this register can not be modified if
          !!REGEN is false.
          '''
        }
      ]
    },
% for k in range(4):
    { name:     "CLASS${c}_PHASE${k}_CYC",
      desc:     '''
                Duration of escalation phase ${k} for class ${c}.
                '''
      swaccess: "rw",
      hwaccess: "hro",
      regwen:   "REGEN",
      fields: [
        { bits: "${esc_cnt_dw - 1}:0" ,
          desc: '''Escalation phase duration in cycles. Note that this register can not be
          modified if !!REGEN is false.'''
        }
      ]
    }
% endfor
    { name:     "CLASS${c}_ESC_CNT",
      desc:     '''
                Escalation counter in cycles for class ${c}.
                '''
      swaccess: "ro",
      hwaccess: "hwo",
      hwext:    "true",
      fields: [
        { bits: "${esc_cnt_dw - 1}:0",
          desc: '''Returns the current timeout or escalation count (depending on !!CLASS${c}_STATE).
          This register can not be directly cleared. However, SW can indirectly clear as follows.

          If the class is in the Timeout state, the timeout can be aborted by clearing the
          corresponding interrupt bit.

          If this class is in any of the escalation phases (e.g. Phase0), escalation protocol can be
          aborted by writing to !!CLASS${c}_CLR. Note however that has no effect if !!CLASS${c}_CLREN
          is set to false (either by SW or by HW via the !!CLASS${c}_CTRL.LOCK feature).
          '''
        }
      ]
    },
    { name:     "CLASS${c}_STATE",
      desc:     '''
                Current escalation state of Class ${c}. See also !!CLASS${c}_ESC_CNT.
                '''
      swaccess: "ro",
      hwaccess: "hwo",
      hwext:    "true",
      fields: [
        { bits: "2:0",
          enum: [
                  { value: "0b000", name: "Idle",     desc: "No timeout or escalation triggered." },
                  { value: "0b001", name: "Timeout",  desc: "IRQ timeout counter is active." },
                  { value: "0b011", name: "Terminal", desc: "Terminal state after escalation protocol." },
                  { value: "0b100", name: "Phase0",   desc: "Escalation Phase0 is active." },
                  { value: "0b101", name: "Phase1",   desc: "Escalation Phase1 is active." },
                  { value: "0b110", name: "Phase2",   desc: "Escalation Phase2 is active." },
                  { value: "0b111", name: "Phase3",   desc: "Escalation Phase3 is active." }
                ]
        }
      ]
    },
% endfor
  ],
}