[sensor_ctrl, ast] Preparation for sensor_ctrl d2
- Add sensor_ctrl doc and prj.hjson
- Update ast title header
- Minor fix for sensor_ctrl alert clearing
Signed-off-by: Timothy Chen <timothytim@google.com>
diff --git a/hw/top_earlgrey/ip/ast/doc/_index.md b/hw/top_earlgrey/ip/ast/doc/_index.md
index c847d1c..8e3ff57 100644
--- a/hw/top_earlgrey/ip/ast/doc/_index.md
+++ b/hw/top_earlgrey/ip/ast/doc/_index.md
@@ -1,3 +1,7 @@
+---
+title: "Analog Sensor Top Technical Specification"
+---
+
# Overview
AST, also known as the analog sensor top, is the OpenTitan analog and
diff --git a/hw/top_earlgrey/ip/sensor_ctrl/data/sensor_ctrl.prj.hjson b/hw/top_earlgrey/ip/sensor_ctrl/data/sensor_ctrl.prj.hjson
new file mode 100644
index 0000000..ab9982e
--- /dev/null
+++ b/hw/top_earlgrey/ip/sensor_ctrl/data/sensor_ctrl.prj.hjson
@@ -0,0 +1,19 @@
+// Copyright lowRISC contributors.
+// Licensed under the Apache License, Version 2.0, see LICENSE for details.
+// SPDX-License-Identifier: Apache-2.0
+
+{
+ name: "sensor_ctrl",
+ design_spec: "../doc",
+ dv_doc: "../doc/dv",
+ hw_checklist: "../doc/checklist",
+ revisions: [
+ {
+ version: "0.1",
+ life_stage: "L1",
+ design_stage: "D1",
+ verification_stage: "V0",
+ //notes: ""
+ }
+ ]
+}
diff --git a/hw/top_earlgrey/ip/sensor_ctrl/doc/_index.md b/hw/top_earlgrey/ip/sensor_ctrl/doc/_index.md
new file mode 100644
index 0000000..9c58f0f
--- /dev/null
+++ b/hw/top_earlgrey/ip/sensor_ctrl/doc/_index.md
@@ -0,0 +1,71 @@
+---
+title: "Sensor Control Technical Specification"
+---
+
+# Overview
+
+This document specifies the functionality of the sensor control module.
+The sensor control module is a comportable front-end to the [analog sensor top]({{< relref "hw/top_earlgrey/ip/ast/doc" >}}).
+
+It provides basic alert functionality, pad debug hook ups, and a small amount of open source visible status readback.
+Long term, this is a module that can be absorbed directly into the `analog sensor top`.
+
+## Features
+
+- Alert hand-shake with `analog sensor top`
+- Alert forwarding to `alert handler`
+- Status readback for `analog sensor top`
+- Pad debug hook up for `analog sensor top`
+
+# Theory of Operations
+
+## Block Diagram
+
+The diagram below shows how `sensor control` helps `analog sensor top` integration into the overall design.
+
+## Alert Handshake
+
+The `analog sensor top` sends alert requests in independent, differential form to the `sensor control`.
+Each alert request consists of a pair of signals, one active high and one active low.
+The active polarity of each signal is independent. This is due to the imprecise timing sensor that drives the alert.
+This means that the `sensor control` recognizes an active alert as long as one of the lines is active, and not the pair of signals being in a particular state.
+Each signal in the differential pair is thus a separate dedicated alert indicator.
+
+Once an alert request is detected as active, the `sensor control` then formulates a proper alert event through the `prim_alert_sender` and sends a notification to the `alert handler`.
+
+The `sensor control` can optionally generate alert acknowledgements back to the `analog sensor top`.
+When an alert request is detected as active, the `sensor control` has 3 options after sending out the alert:
+
+- Do not acknowledge: Allow alerts to be continually triggered.
+- Software acknowledge: Let software decide whether an alert should stop triggering.
+- Hardware acknowledge. Let hardware immediately acknowledge the alert.
+
+Once the `analog sensor top` receives the acknowledgment, it then drops the corresponding alert request.
+
+## Hardware Interfaces
+
+### Signals
+
+{{< incGenFromIpDesc "../data/sensor_ctrl.hjson" "hwcfg" >}}
+
+The table below lists other signals.
+
+Signal | Direction | Type | Description
+---------------------|------------------|----------------------------------------|---------------
+`ast_alert_i` | `input` | `ast_pkg::ast_alert_req_t` | Incoming alert requests from `analog sensor top`
+`ast_alert_o` | `output` | `ast_pkg::ast_alert_rsp_t` | Outgoing alert acknowledgments to `analog sensor top`
+`status_i` | `input` | `ast_pkg::ast_status_t` | Incoming `analog sensor top` status
+`ast2pinmux_i` | `input` | `logic [ast_pkg::Ast2PadOutWidth-1:0]` | Incoming `analog sensor top` debug output signals
+`cio_ast_debug_out` | `output` | `logic [ast_pkg::Ast2PadOutWidth-1:0]` | Outgoing `analog sensor top` debug output signals to `pinmux`
+
+# Programmer's Guide
+
+Each available alert has a corresponding acknowledgment control.
+Program {{< regref "ACK_MODE.VAL" >}} to the appropriate value for no acknowledgment, software acknowledgment or hardware acknowledgment.
+
+If software acknowledge is selected, {{< regref "ALERT_STATE" >}} can be used to determine the current state of an alert.
+When the alert state is cleared (`rw1c`), the `analog sensor top` alert will also be acknowledged.
+
+## Register Table
+
+{{< incGenFromIpDesc "../data/sensor_ctrl.hjson" "registers" >}}
diff --git a/hw/top_earlgrey/ip/sensor_ctrl/rtl/sensor_ctrl.sv b/hw/top_earlgrey/ip/sensor_ctrl/rtl/sensor_ctrl.sv
index 8b23b8a..06f3fbb 100644
--- a/hw/top_earlgrey/ip/sensor_ctrl/rtl/sensor_ctrl.sv
+++ b/hw/top_earlgrey/ip/sensor_ctrl/rtl/sensor_ctrl.sv
@@ -143,7 +143,7 @@
);
assign alerts_clr[i] = no_ack_mode[i] ? '0 :
- sw_ack_mode[i] ? ~reg2hw.alert_state[i].q & reg2hw.alert_state[i].qe :
+ sw_ack_mode[i] ? reg2hw.alert_state[i].q & reg2hw.alert_state[i].qe :
alert_req & alert_ack;
end
diff --git a/util/build_docs.py b/util/build_docs.py
index 99972e8..c56f40f 100755
--- a/util/build_docs.py
+++ b/util/build_docs.py
@@ -77,6 +77,7 @@
"hw/top_earlgrey/ip/clkmgr/data/autogen/clkmgr.hjson",
"hw/top_earlgrey/ip/pwrmgr/data/autogen/pwrmgr.hjson",
"hw/top_earlgrey/ip/rstmgr/data/autogen/rstmgr.hjson",
+ "hw/top_earlgrey/ip/sensor_ctrl/data/sensor_ctrl.hjson",
"hw/top_earlgrey/ip/rv_plic/data/autogen/rv_plic.hjson",
"hw/ip/rv_timer/data/rv_timer.hjson",
"hw/ip/spi_host/data/spi_host.hjson",
@@ -92,6 +93,7 @@
"dashboard_definitions": {
"comportable": [
"hw/ip",
+ "hw/top_earlgrey/ip/sensor_ctrl"
],
},
