From 0b9b18ce30148d447535132deb295e5ce9c608fc Mon Sep 17 00:00:00 2001
From: Ian Moffett <ian@osmora.org>
Date: Fri, 2 Aug 2024 21:31:58 -0400
Subject: Add PIMC docs

Signed-off-by: Ian Moffett <ian@osmora.org>
---
 sv/soc/irq/irqchip.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 sv/soc/irq/irqchip.md

diff --git a/sv/soc/irq/irqchip.md b/sv/soc/irq/irqchip.md
new file mode 100644
index 0000000..5faf090
--- /dev/null
+++ b/sv/soc/irq/irqchip.md
@@ -0,0 +1,32 @@
+# Platform Interrupt Message Controller (PIMC)
+
+The PIMC is responsible for receiving Interrupt Requests (IRQs) from peripherals
+and routing them to a processor. There can be several peripherals in the system,
+each connected to their respective IRQ lines.
+
+## PIMC Signals
+
+| Signal      | Purpose                     |
+| ----------  | --------------------------- |
+| IRQACK      | Interrupt acknowledgement   |
+| LINENO[7:0] | IRQ line to be serviced     |
+| NOTIFY#     | Signals an active IRQ       |
+| CLK         | PIMC Clock                  |
+
+## PIMC Startup State
+
+| Signal      | State     |
+| ----------  | --------  |
+| IRQACK      | LOW (0)   |
+| LINENO[7:0] | UNDEFINED |
+| NOTIFY#     | UNDEFINED |
+
+## PIMC Initialization Process
+
+During system startup, LINENO[7:0] and NOTIFY# will be in an undefined state. Stage 1 firmware
+is responsible for initializing the PIMC before it is ready for operation. The PIMC is initialized
+by pulsing IRQACK high for exactly one clock cycle. It is recommended that IRQACK should be left high
+for at least 2 ms.
+
+As soon as a rising edge of the PIMC CLK signal occurs with IRQACK pulled high, NOTIFY# is pulled high
+and LINENO[7:0] becomes zero.
-- 
cgit v1.2.3