[doc] Completely replace docgen with hugo
This change completely replaces docgen and replaces or removes
docgen-specific markdown in documentation. It also does the following:
* Updates all local links to use hugo relative references so that a
broken link is a broken build.
* Uses upstream wavedrom, which breaks at least one page that depends
on local modifications.
* Renames most hw/ip/**/ip_name.doc and dv_plan documents for a more
aesthetic document tree layout.
* Moves some doc/ pages into their own page bundle.
* Updates util/build_docs.py to pre-generate registers, hwcfg, and
dashboard fragments and invoke hugo.
diff --git a/hw/ip/rv_plic/doc/rv_plic.md b/hw/ip/rv_plic/doc/index.md
similarity index 79%
rename from hw/ip/rv_plic/doc/rv_plic.md
rename to hw/ip/rv_plic/doc/index.md
index 1158f0e..4e0e6fa 100644
--- a/hw/ip/rv_plic/doc/rv_plic.md
+++ b/hw/ip/rv_plic/doc/index.md
@@ -1,39 +1,39 @@
-{{% lowrisc-doc-hdr Interrupt Controller Technical Specification }}
-{{% regfile ../data/rv_plic.hjson }}
+---
+title: "Interrupt Controller Technical Specification"
+---
-{{% section1 Overview }}
+# Overview
This document specifies the Interrupt Controller (RV_PLIC) functionality. This
module conforms to the
-[Comportable guideline for peripheral functionality.](../../../../doc/rm/comportability_specification.md)
+[Comportable guideline for peripheral functionality.]({{< relref "doc/rm/comportability_specification" >}})
See that document for integration overview within the broader top level system.
-{{% toc 3 }}
-{{% section2 Features }}
+## Features
- RISC-V Platform-Level Interrupt Controller (PLIC) compliant interrupt controller
- Support arbitrary number of interrupt vectors (up to 256) and targets
- Support interrupt enable, interrupt status registers
- Memory-mapped MSIP register per HART for software interrupt control.
-{{% section2 Description }}
+## Description
The RV_PLIC module is designed to manage various interrupt sources from the
peripherals. It receives interrupt events as either edge or level of the
incoming interrupt signals (``intr_src_i``) and can notify multiple targets.
-{{% section2 Compatibility }}
+## Compatibility
The RV_PLIC is compatible with any RISC-V core implementing the RISC-V privilege specification.
-{{% section1 Theory of Operations }}
+# Theory of Operations
-{{% section2 Block Diagram }}
+## Block Diagram
-{{% section2 Details }}
+## Details
### Identifier
@@ -47,7 +47,7 @@
Interrupt sources have configurable priority values. The maximum value of the
priority is configurable through the localparam `MAX_PRIO` in the rv_plic
-top-level module. For each target there is a threshold value (!!THRESHOLD0 for
+top-level module. For each target there is a threshold value ({{< regref "THRESHOLD0" >}} for
target 0). RV_PLIC notifies a target of an interrupt only if it's priority is
strictly greater than the target's threshold. Note this means an interrupt with
a priority is 0 is effectively prevented from causing an interrupt at any target
@@ -66,25 +66,25 @@
level basis (where the signal remains at **1**).
When the gateway detects an interrupt event it raises the interrupt pending bit
-(!!IP) for that interrupt source. When an interrupt is claimed by a target the
-relevant bit of !!IP is cleared. A bit in !!IP will be not reasserted until the
+({{< regref "IP" >}}) for that interrupt source. When an interrupt is claimed by a target the
+relevant bit of {{< regref "IP" >}} is cleared. A bit in {{< regref "IP" >}} will be not reasserted until the
target signals completion of the interrupt. Any new interrupt event between a
-bit in !!IP asserting and completing that interrupt is ignored. In particular
+bit in {{< regref "IP" >}} asserting and completing that interrupt is ignored. In particular
this means that for edge triggered interrupts if a new edge is seen after the
-source's !!IP bit is asserted and before completion that edge will be ignored
+source's {{< regref "IP" >}} bit is asserted and before completion that edge will be ignored
(counting missed edges as discussed in the RISC-V PLIC specification is not
supported).
Note that there is no ability for a level triggered interrupt to be cancelled.
-If the interrupt drops after the gateway has set a bit in !!IP, the bit will
+If the interrupt drops after the gateway has set a bit in {{< regref "IP" >}}, the bit will
remain set until the interrupt is completed. The SW handler should be conscious
of this and check the interrupt still requires handling in the handler if this
behaviour is possible.
### Interrupt Enables
-Each target has a set of Interrupt Enable (!!IE0 for target 0) registers. Each
-bit in the !!IE0 registers controls the corresponding interrupt source. If an
+Each target has a set of Interrupt Enable ({{< regref "IE0" >}} for target 0) registers. Each
+bit in the {{< regref "IE0" >}} registers controls the corresponding interrupt source. If an
interrupt source is disabled for a target, then interrupt events from that
source won't trigger an interrupt at the target. RV_PLIC doesn't have a global
interrupt disable feature.
@@ -92,23 +92,23 @@
### Interrupt Claims
"Claiming" an interrupt is done by a target reading the associated
-Claim/Completion register for the target (!!CC0 for target 0). The return value
-of the !!CC0 read represents the ID of the pending interrupt that has the
+Claim/Completion register for the target ({{< regref "CC0" >}} for target 0). The return value
+of the {{< regref "CC0" >}} read represents the ID of the pending interrupt that has the
highest priority. If two or more pending interrupts have the same priority,
RV_PLIC chooses the one with lowest ID. Only interrupts that that are enabled
for the target can be claimed. The target priority threshold doesn't matter
(this only factors into whether an interrupt is signalled to the target) so
-lower priority interrupt IDs can be returned on a read from !!CC0. If no
+lower priority interrupt IDs can be returned on a read from {{< regref "CC0" >}}. If no
interrupt is pending (or all pending interrupts are disabled for the target) a
-read of !!CC0 returns an ID of 0.
+read of {{< regref "CC0" >}} returns an ID of 0.
### Interrupt Completion
-After an interrupt is claimed, the relevant bit of interrupt pending (!!IP) is
+After an interrupt is claimed, the relevant bit of interrupt pending ({{< regref "IP" >}}) is
cleared, regardless of the status of the `intr_src_i` input value. Until a
target "completes" the interrupt, it won't be re-asserted if a new event for the
interrupt occurs. A target completes the interrupt by writing the ID of the
-interrupt to the Claim/Complete register (!!CC0 for target 0). The write event
+interrupt to the Claim/Complete register ({{< regref "CC0" >}} for target 0). The write event
is forwarded to the Gateway logic, which resets the interrupt status to accept a
new interrupt event. The assumption is that the processor has cleaned up the
originating interrupt event during the time between claim and complete such that
@@ -140,23 +140,23 @@
asserted. At g the interrupt is completed (by writing `i+1` to it's
Claim/Complete register) so at h `irq_o` is asserted due to the new interrupt.
-{{% section2 Hardware Interfaces }}
+## Hardware Interfaces
-{{% hwcfg rv_plic }}
+{{< hwcfg "hw/ip/rv_plic/data/rv_plic.hjson" >}}
-{{% section1 Programmers Guide }}
+# Programmers Guide
-{{% section2 Initialization }}
+## Initialization
After reset, RV_PLIC doesn't generate any interrupts to any targets even if
interrupt sources are set, as all priorities and thresholds are 0 by default and
all ``IE`` values are 0. Software should configure the above three registers and the
-interrupt source type !!LE .
+interrupt source type {{< regref "LE" >}} .
-!!LE and !!PRIO0 .. !!PRIO31 registers are unique. So, only one of the targets
+{{< regref "LE" >}} and {{< regref "PRIO0" >}} .. {{< regref "PRIO31" >}} registers are unique. So, only one of the targets
shall configure them.
-~~~~c
+```c
// Pseudo-code below
void plic_init() {
// Set to level-triggered for interrupt sources
@@ -179,19 +179,19 @@
*(IE+offset) = *(IE+offset) | (1<<(iid%32));
}
-~~~~
+```
-{{% section2 Handling Interrupt Request Events }}
+## Handling Interrupt Request Events
If software receives an interrupt request, it is recommended to follow the steps
-shown below (assuming target 0 which uses !!CC0 for claim/complete).
+shown below (assuming target 0 which uses {{< regref "CC0" >}} for claim/complete).
1. Claim the interrupts right after entering to the interrupt service routine
- by reading the !!CC0 register.
+ by reading the {{< regref "CC0" >}} register.
2. Determine which interrupt should be serviced based on the values read from
- the !!CC0 register.
+ the {{< regref "CC0" >}} register.
3. Execute ISR, clearing the originating peripheral interrupt.
-4. Write Interrupt ID to !!CC0
+4. Write Interrupt ID to {{< regref "CC0" >}}
5. Repeat as necessary for other pending interrupts.
It is possible to have multiple interrupt events claimed. If software claims one
@@ -222,7 +222,7 @@
}
~~~~
-{{% section2 Registers }}
+## Registers
The register description can be generated with `reg_rv_plic.py` script. The reason
another script for register generation is that RV_PLIC is configurable to the
@@ -251,5 +251,5 @@
- CC: N_TARGET
Claim by read, complete by write
-{{% registers x }}
+{{< registers "hw/ip/rv_plic/data/rv_plic.hjson" >}}
