[doc/alert_handler] Make signal names consistent and fix waves
diff --git a/hw/ip/alert_handler/doc/index.md b/hw/ip/alert_handler/doc/index.md
index 094c43b..67ebe3f 100644
--- a/hw/ip/alert_handler/doc/index.md
+++ b/hw/ip/alert_handler/doc/index.md
@@ -203,19 +203,14 @@
### Differential Alert Signaling
-Each alert sender is connected to the corresponding alert receiver via the 3
-differential pairs `alert_p/n`, `ack_p/n` and `ping_p/n`, as illustrated below:
+Each alert sender is connected to the corresponding alert receiver via the 3 differential pairs `alert_p*/n*`, `ack_p*/n*` and `ping_p*/n*`, as illustrated below:
-Alerts are encoded differentially and signaled using a full handshake on the
-`alert_p/n` and `ack_p/n` wires. The use of a full handshake protocol allows
-this mechanism to be used with an asynchronous clocking strategy, where peripherals may
-reside in a different clock domain than the alert handler. The full handshake
-guarantees that alert messages are correctly back-pressured and no alert is
-"lost" at the asynchronous boundary due to (possibly variable) clock ratios
-greater or less than 1.0. The "native alert message" will be repeated on the
-output wires as long as the alert event is still true within the peripheral.
+Alerts are encoded differentially and signaled using a full handshake on the `alert_p*/n*` and `ack_p*/n*` wires.
+The use of a full handshake protocol allows this mechanism to be used with an asynchronous clocking strategy, where peripherals may reside in a different clock domain than the alert handler.
+The full handshake guarantees that alert messages are correctly back-pressured and no alert is "lost" at the asynchronous boundary due to (possibly variable) clock ratios greater or less than 1.0.
+The "native alert message" will be repeated on the output wires as long as the alert event is still true within the peripheral.
The wave pattern below illustrates differential full handshake mechanism.
@@ -224,17 +219,17 @@
signal: [
{ name: 'clk_i', wave: 'p...............' },
{ name: 'alert_i', wave: '01.|..|..|...|..' },
- { name: 'alert_p', wave: '01.|..|0.|..1|..' , node: '.a.....c....e'},
- { name: 'alert_n', wave: '10.|..|1.|..0|..' },
- { name: 'ack_p', wave: '0..|1.|..|0..|1.' , node: '....b.....d..'},
- { name: 'ack_n', wave: '1..|0.|..|1..|0.' },
+ { name: 'alert_po/pi', wave: '01.|..|0.|..1|..' , node: '.a.....c....e'},
+ { name: 'alert_no/ni', wave: '10.|..|1.|..0|..' },
+ { name: 'ack_pi/po', wave: '0..|1.|..|0..|1.' , node: '....b.....d..'},
+ { name: 'ack_ni/no', wave: '1..|0.|..|1..|0.' },
{ name: 'alert_o', wave: '0..|10|..|...|10' },
],
edge: [
- 'a~>b Phase 0->1'
- 'b~>c Phase 1->2'
- 'c~>d Phase 2->3'
- 'd~>e 2 Pause Cycles'
+ 'a~>b Phase 0/1',
+ 'b~>c Phase 1/2',
+ 'c~>d Phase 2/3',
+ 'd~>e 2 Pause Cycles',
],
head: {
text: 'Alert signaling and repeat pattern',
@@ -249,13 +244,9 @@
The handshake pattern is repeated as long as the alert is true. The sender will
wait for 2 cycles between handshakes.
-Note that the alert is immediately propagated to `alert_o` once the
-initial level change on `alert_p/n` has been received and synchronized to the
-local clock. This ensures that the first occurrence of an alert is always
-propagated - even if the handshake lines have been manipulated to emulate
-backpressure. (In such a scenario, all subsequent alerts would be back-pressured
-and eventually the ping testing mechanism described in the next subsection would
-detect that the wires have been tampered with.)
+Note that the alert is immediately propagated to `alert_o` once the initial level change on `alert_pi/ni` has been received and synchronized to the local clock on the receiver side.
+This ensures that the first occurrence of an alert is always propagated - even if the handshake lines have been manipulated to emulate backpressure.
+(In such a scenario, all subsequent alerts would be back-pressured and eventually the ping testing mechanism described in the next subsection would detect that the wires have been tampered with.)
The alert sender and receiver modules can either be used synchronously or
asynchronously. The signaling protocol remains the same in both cases, but the
@@ -270,18 +261,13 @@
appearance can not be predicted.
-The ping timing is generated by a central LFSR-based timer within the alert
-handler that randomly asserts the `ping_en_i` signal of a particular
-`prim_alert_receiver` module. Once `ping_en_i` is asserted, the
-receiver module encodes the ping message as a level change on the differential
-`ping_po/no` output, and waits until the sender responds with a full handshake on
-the `alert_pi/ni` and `ack_po/no` lines. Once that handshake is complete, the
-`ping_ok_o` signal is asserted. The LFSR timer has a programmable ping timeout,
-after which it will automatically assert a "pingfail" alert. That timeout is a
-function of the clock ratios present in the system, and has to be programmed
-accordingly at system startup (as explained later in the LFSR timer subsection).
+The ping timing is generated by a central LFSR-based timer within the alert handler that randomly asserts the `ping_en_i` signal of a particular `prim_alert_receiver` module.
+Once `ping_en_i` is asserted, the receiver module encodes the ping message as a level change on the differential `ping_po/no` output, and waits until the sender responds with a full handshake on the `alert_pi/ni` and `ack_po/no` lines.
+Once that handshake is complete, the `ping_ok_o` signal is asserted.
+The LFSR timer has a programmable ping timeout, after which it will automatically assert a "pingfail" alert.
+That timeout is a function of the clock ratios present in the system, and has to be programmed accordingly at system startup (as explained later in the LFSR timer subsection).
-The following wave diagram illustrates a correct ping sequences:
+The following wave diagram illustrates a correct ping sequence, viewed from the receiver side:
{{< wavejson >}}
{
@@ -289,17 +275,17 @@
{ name: 'clk_i', wave: 'p..............' },
{ name: 'ping_en_i', wave: '01.|..|..|..|.0' },
{ name: 'ping_ok_o', wave: '0..|..|..|..|10' , node: '.............e'},
- { name: 'ping_p', wave: '01.|..|..|..|..' , node: '.a'},
- { name: 'ping_n', wave: '10.|..|..|..|..' , node: '.b'},
- { name: 'alert_p', wave: '0..|1.|..|0.|..' , node: '....c'},
- { name: 'alert_n', wave: '1..|0.|..|1.|..' },
- { name: 'ack_p', wave: '0..|..|1.|..|0.' , node: '.............d'},
- { name: 'ack_n', wave: '1..|..|0.|..|1.' },
+ { name: 'ping_po', wave: '01.|..|..|..|..' , node: '.a'},
+ { name: 'ping_no', wave: '10.|..|..|..|..' , node: '.b'},
+ { name: 'alert_pi', wave: '0..|1.|..|0.|..' , node: '....c'},
+ { name: 'alert_ni', wave: '1..|0.|..|1.|..' },
+ { name: 'ack_po', wave: '0..|..|1.|..|0.' , node: '.............d'},
+ { name: 'ack_no', wave: '1..|..|0.|..|1.' },
],
edge: [
- 'a-b'
- 'b-~>c ping response'
- 'd->e response complete'
+ 'a-b',
+ 'b~>c ping response',
+ 'd->e response complete',
],
head: {
text: 'Ping testing',
@@ -332,13 +318,12 @@
alert via `integ_fail_o`. In particular, this covers the following failure
cases:
-1. The `alert_p/n` pair is not correctly encoded. This can be detected directly
-at the receiver side.
+1. The `alert_pi/ni` pair is not correctly encoded on the receiver side.
+This can be directly flagged as an integrity failure on the receiver side.
-2. The `ping_p/n` or the `ack_p/n` pairs are not correctly encoded. This is
-signaled to the receiver by setting the `alert_p/n` wires to the same value,
-and that value will be continuously toggled. This implicitly triggers a signal
-integrity alert on the receiver side.
+2. The `ping_pi/ni` or the `ack_pi/ni` pairs are not correctly encoded on the sender side.
+This is signaled to the receiver by setting the `alert_po/no` wires to the same value, and that value will be continuously toggled.
+This implicitly triggers a signal integrity alert on the receiver side.
Some of these failure patterns are illustrated in the wave diagram below:
@@ -346,16 +331,16 @@
{
signal: [
{ name: 'clk_i', wave: 'p..............' },
- { name: 'alert_p', wave: '0.1...|0..10101' , node: '..a.......d'},
- { name: 'alert_n', wave: '1.....|....0101' },
- { name: 'ack_p', wave: '0.....|.1......' , node: '........c'},
- { name: 'ack_n', wave: '1.....|........' },
+ { name: 'alert_pi', wave: '0.1...|0..10101' , node: '..a.......d'},
+ { name: 'alert_ni', wave: '1.....|....0101' },
+ { name: 'ack_pi', wave: '0.....|.1......' , node: '........c'},
+ { name: 'ack_ni', wave: '1.....|........' },
{ name: 'integ_fail_o', wave: '0...1.|0....1..' , node: '....b.......e'},
],
edge: [
- 'a~>b sigint issue detected'
- 'c~>d'
- 'd~>e indirect sigint issue detected'
+ 'a~>b sigint issue detected',
+ 'c~>d',
+ 'd~>e indirect sigint issue detected',
],
head: {
text: 'Detection of Signal Integrity Issues',
@@ -697,15 +682,15 @@
{ name: 'integ_fail_o', wave: '0........|..1010...' , node: '............b.d' },
{ name: 'ping_fail_o', wave: '0........|.........' },
{ name: 'esc_en_i', wave: '01....0..|.1....0..' },
- { name: 'resp_p', wave: '0.101010.|.........', node: '............a.c' },
- { name: 'resp_n', wave: '1.010101.|.........' },
- { name: 'esc_p', wave: '01.....0.|.1.....0.' },
- { name: 'esc_n', wave: '10.....1.|.0.....1.' },
+ { name: 'resp_pi/po', wave: '0.101010.|.........', node: '............a.c' },
+ { name: 'resp_ni/no', wave: '1.010101.|.........' },
+ { name: 'esc_po/pi', wave: '01.....0.|.1.....0.' },
+ { name: 'esc_no/ni', wave: '10.....1.|.0.....1.' },
{ name: 'esc_en_o', wave: '0.1....0.|..?....0.'},
],
edge: [
- 'a~>b missing response'
- 'c~>d'
+ 'a~>b missing response',
+ 'c~>d',
],
head: {
text: 'Escalation signaling and response',
@@ -717,12 +702,10 @@
}
{{< /wavejson >}}
-Further, any differential signal mismatch on both the `esc_p/n` and `resp_p/n`
-lines will trigger an `integ_fail_o` alert. Mismatches on `resp_p/n` can be
-directly detected at the sender. Mismatches on the `esc_p/n` line will be
-signaled back to the sender by setting both the positive and negative response
-wires to the same value - and that value is being toggled each cycle. This
-implicitly triggers a signal integrity alert on the sender side.
+Further, any differential signal mismatch on both the `esc_pi/ni` and `resp_pi/ni` lines will trigger an `integ_fail_o` alert.
+Mismatches on `resp_pi/ni` can be directly detected at the sender.
+Mismatches on the `esc_pi/ni` line will be signaled back to the sender by setting both the positive and negative response wires to the same value - and that value is being toggled each cycle.
+This implicitly triggers a signal integrity alert on the sender side.
This back-signaling mechanism can be leveraged to fast-track escalation and use
another countermeasure in case it is detected that a particular escalation
@@ -738,16 +721,16 @@
{ name: 'ping_ok_o', wave: '0....|......' },
{ name: 'integ_fail_o', wave: '0.1.0|.1....' , node: '..b....e' },
{ name: 'esc_en_i', wave: '0....|......' },
- { name: 'resp_p', wave: '0.1.0|..1010', node: '..a..' },
- { name: 'resp_n', wave: '1....|.01010', node: '.......d' },
- { name: 'esc_p', wave: '0....|1.....', node: '......c..' },
- { name: 'esc_n', wave: '1....|......' },
+ { name: 'resp_pi', wave: '0.1.0|..1010', node: '..a..' },
+ { name: 'resp_ni', wave: '1....|.01010', node: '.......d' },
+ { name: 'esc_pi', wave: '0....|1.....', node: '......c..' },
+ { name: 'esc_ni', wave: '1....|......' },
{ name: 'esc_en_o', wave: '0....|......'},
],
edge: [
- 'a~>b'
- 'c->d'
- 'd->e'
+ 'a~>b',
+ 'c->d',
+ 'd->e',
],
head: {
text: 'possible signal integrity failure cases',
@@ -762,16 +745,13 @@
### Ping Testing of the Escalation Signals
-Similarly to the alert signaling scheme, the escalation signaling lines can
-be pinged / line tested in order to test whether the escalation receiver has
-been tampered with. This is achieved by asserting ping_en_i at the escalation
-sender module. A ping request is encoded as a single cycle pulse on the
-`esc_po/no` outputs. Hence, the receiver module will not decode this single
-cycle pulse as an escalation enable message, but it will respond to it with a
-"1010" pattern on the `resp_p/n` lines. The escalation sender module will assert
-`ping_ok_o` if that pattern is received correctly after one cycle of latency.
-Otherwise the LFSR timer will raise a "pingfail" alert after the programmable
-timeout is reached.
+Similarly to the alert signaling scheme, the escalation signaling lines can be pinged / line tested in order to test whether the escalation receiver has been tampered with.
+This is achieved by asserting `ping_en_i` at the escalation sender module.
+A ping request is encoded as a single cycle pulse on the `esc_po/no` outputs.
+Hence, the receiver module will not decode this single cycle pulse as an escalation enable message, but it will respond to it with a "1010" pattern on the `resp_pi/ni` lines.
+The escalation sender module will assert `ping_ok_o` if that pattern is received correctly after one cycle of latency.
+Otherwise the LFSR timer will raise a "pingfail" alert after the programmable timeout is reached.
+This mechanism is illustrated below from the viewpoint of the sender module.
{{< wavejson >}}
{
@@ -781,17 +761,16 @@
{ name: 'ping_ok_o', wave: '0....10|.......' , node: '.....e....g'},
{ name: 'integ_fail_o', wave: '0......|.......' },
{ name: 'esc_en_i', wave: '0......|.......' },
- { name: 'resp_p', wave: '0.1010.|.......' , node: '..c..d....f'},
- { name: 'resp_n', wave: '1.0101.|.......' },
- { name: 'esc_p', wave: '010....|.10....' , node: '.b'},
- { name: 'esc_n', wave: '101....|.01....' },
- { name: 'esc_en_o', wave: '0......|.......' },
+ { name: 'resp_pi', wave: '0.1010.|.......' , node: '..c..d....f'},
+ { name: 'resp_ni', wave: '1.0101.|.......' },
+ { name: 'esc_po', wave: '010....|.10....' , node: '.b'},
+ { name: 'esc_no', wave: '101....|.01....' },
],
edge: [
- 'a->b'
- 'b->c'
- 'd->e correct response'
- 'f->g missing response'
+ 'a->b',
+ 'b->c',
+ 'd->e correct response',
+ 'f->g missing response',
],
head: {
text: 'ping testing of escalation lines',
