[alert_handler] Add register file template
diff --git a/hw/ip/alert_handler/doc/alert_handler.tpl.hjson b/hw/ip/alert_handler/doc/alert_handler.tpl.hjson
new file mode 100644
index 0000000..471ff43
--- /dev/null
+++ b/hw/ip/alert_handler/doc/alert_handler.tpl.hjson
@@ -0,0 +1,393 @@
+// 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
+ ],
+}
