[PATCH 3/4] Re-write the interrupts and timer section


Anup Patel
 

We re-write the interrupts and timer section to align the
interrupts and timer table.

Signed-off-by: Anup Patel <anup.patel@...>
---
Makefile | 4 +-
riscv-platform-spec.adoc | 294 ++++++++++++++++++++++-----------------
riscv-platform-spec.yml | 8 ++
3 files changed, 175 insertions(+), 131 deletions(-)
create mode 100644 riscv-platform-spec.yml

diff --git a/Makefile b/Makefile
index 48e8fe9..ff8fbf6 100644
--- a/Makefile
+++ b/Makefile
@@ -22,8 +22,8 @@ $(PLATFORM_SPEC).md: $(PLATFORM_SPEC).xml
$(PLATFORM_SPEC).xml: $(PLATFORM_SPEC).adoc
$(ASCIIDOCTOR) -d book -b docbook $<

-$(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc $(IMAGES)
- $(ASCIIDOCTOR) -d book -r asciidoctor-pdf -b pdf $<
+$(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc $(IMAGES) $(PLATFORM_SPEC).yml
+ $(ASCIIDOCTOR) -d book -r asciidoctor-pdf -a pdf-style=$(PLATFORM_SPEC).yml -b pdf $<

$(PLATFORM_SPEC).html: $(PLATFORM_SPEC).adoc $(IMAGES)
$(ASCIIDOCTOR) -d book -b html $<
diff --git a/riscv-platform-spec.adoc b/riscv-platform-spec.adoc
index 2fee40b..7261704 100644
--- a/riscv-platform-spec.adoc
+++ b/riscv-platform-spec.adoc
@@ -13,6 +13,7 @@
:doctype: book
:sectnums:
:sectnumlevels: 5
+:xrefstyle: short
:toc: macro
:toclevels: 5

@@ -245,114 +246,168 @@ each must be 1
The default should allow code that's sensitive to these requirements to be
debugged.

-==== Interrupt Controller, Software Interrupt, and Timer Requirements
-In the following requirements,
-https://github.com/riscv/riscv-aia[*AIA*] refers to the Advanced Interrupt Architecture, https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[*ACLINT*]
-refers to the Advanced *CLINT*. AIA comprises two separate components: `IMSICs` and `APLICs`.
-If supported, there is an `IMSIC` device associated with each hart.
-If supported, *APLIC* devices are global to all harts, and there may be one or
-multiple in a system. *ACLINT* comprises three separate components: `MTIMER` for
-Timer support, and `MSWI` and `SSWI` for Machine-level and Supervisor-level
-Software Interrupt (IPI) support. +
-https://github.com/riscv/riscv-plic-spec/blob/master/riscv-plic.adoc[*PLIC*]
-refers to the legacy Platform-Level Interrupt Controller that provides
-facilities to route external interrupts to a hart context with a given privilege
-mode. The number of non-local interrupt sources supported by PLIC and how does
-each of them connect to the hart context is PLIC core implementation-specific. +
-*CLINT* is a legacy Core-Local Interrupt Controller that is a compatible subset of
-ACLINT which provides facilities to trigger Software (IPI) and Timer interrupts to
-hart.
+==== Interrupts and Timer
+
+===== Timer support
+
+* One or more ACLINT MTIMER devices are required for OS-A platform and each
+ hart must have an associated ACLINT MTIMER device
+* The update period of MTIME counter should be 10ns or less
+* The hardware clock that drives the MTIME counter is required to operate
+ at a minimum frequency of 10MHz
+* Platforms must provide a way to discover MTIME update frequency using
+ appropriate hardware discovery mechanism:
+** Platforms that use DT for hardware discovery are required to advertise the
+ timebase to the operating systems via the `timebase-frequency` property of
+ the "/cpus" node
+footnote:[https://elixir.bootlin.com/linux/latest/source/Documentation/devicetree/bindings/riscv/cpus.yaml].
+
+[sidebar]
+--
+[underline]*_Implementation Note_*
+
+For a counter with 10ns resolution the `timebase-frequency` value would be
+100000000 (100 MHz) which would also be the minimum possible value for
+`timebase-frequency`. From the software perspective a unit increment of the
+mtime value would correspond to a 10ns interval. However the hardware clock
+driving the counter could operate at a lower frequency, thereby incrementing
+the mtime value by more than one unit per clock tick.
+--

-.The following table summarizes what features are supported for four classes of OS/A platforms.
-[width="100%",cols="^,^,^,^,^,^,^,^,^,^,^,^,^"]
-|=======
-.2+|*OS-A Platform* 3+|*MSIs* 3+|*Wired Interrupts* 3+|*IPIs* 3+|*Timer*
-|M-level|S-level|VS-level|M-level|S-level|VS-level|M-level|S-level|VS-level|M-level|S-level|VS-level
-|Existing|NA|NA|NA|PLIC|PLIC|PLIC +
-_(Trap and emulate)_|MSWI +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-SBI IPI +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|SBI IPI +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|MTIMER +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|SBI Timer +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|SBI Timer +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]
-|Only Wired IRQs|NA|NA|NA|APLIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-_(Trap and emulate)_ +
-https://github.com/riscv/riscv-aia[`*AIA*`]|MSWI +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-SSWI +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-SBI IPI +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|MTIMER +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]
-|MSIs and Wired IRQs|IMSIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-_(Trap and emulate)_ +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-_(Trap and emulate)_ +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|SBI IPI +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|MTIMER +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]
-|MSIs, Virtual MSIs and Wired IRQs|IMSIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC VS-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-_(Trap and emulate)_ +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC VS-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|MTIMER +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]
-|=======
-
-* For Timer support, one or more ACLINT MTIMER devices are Required for OS-A platform.
-One MTIMER may be used for all harts, or multiple MTIMERs may be used with
-multiple topological groups of harts. The base address of MTIMER memory map registers
-is platform implementation-specific, however, the format of MTIMER operation parameters
-(`mtime` and `mtimecmp` registers) must be compliant with
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc#21-register-map[ACLINT MTIMER Register Map]
-
-* For Interrupt Controller and Software Interrupt support, one of the following three
-choices below is Required
- ** PLIC plus one or more ACLINT MSWI devices - DEPRECATED
- *** One MSWI may be used for all harts, or multiple MSWIs may be used with
-multiple topological groups of harts
- *** Only wired interrupts and M-mode IPIs are supported
- *** Virtualization is not supported
- *** This compatibly supports legacy PLIC + CLINT designs
- ** One or more AIA APLIC devices plus one or more pairs of ACLINT MSWI and ACLINT SSWI devices
- *** One MSWI/SSWI pair may be used for all harts, or multiple MSWI/SSWI
-pairs may be used with multiple topological groups of harts
- *** Only wired interrupts are supported
- *** Both M-mode and S-mode IPIs are supported
- *** Virtualization is not supported
- ** Zero, one, or more AIA APLIC devices plus per-hart AIA IMSIC devices
- *** Both wired and MSI external interrupts are supported
- *** Both M-mode and S-mode IPIs are supported via IMSICs
- *** Virtualization is supported
- *** Zero APLICs if there are no wired interrupts and only MSIs
+===== Interrupts support
+
+The OS/A platorms can comply with one of the following four categories for
+interrupts support:
+
+* *Legacy IRQs - DEPRECATED*
+** One PLIC device to support wired interrupts
+** One or more ACLINT MSWI devices to support M-mode software interrupts
+** Compatibile with legacy platforms having PLIC plus CLINT
+** MSI external interrupts not supported
+* *Only Wired IRQs*
+** One or more AIA APLIC devices to support wired interrupts
+** One or more ACLINT MSWI devices to support M-mode software interrupts
+** One or more ACLINT SSWI devices to support HS-mode software interrupts
+** MSI external interrupts not supported
+* *MSIs and Wired IRQs*
+** One, or more AIA APLIC devices to support wired interrupts
+** Per-hart AIA IMSIC devices to support MSIs for M-mode and HS-mode
+** Software interrupts for M-mode and HS-mode supported using AIA IMSIC devices
+** MSI virtualization is not supported
+* *MSIs, Virtual MSIs, and Wired IRQs*
+** One, or more AIA APLIC devices to support wired interrupts
+** Per-hart AIA IMSIC devices to support MSIs for M-mode, HS-mode and VS-mode
+** Software interrupts for M-mode, HS-mode and VS-mode supported using
+ AIA IMSIC devices
+** MSI virtualization is supported
+
+<<<
+
+===== Summary
+
+The <<table_interrutps_and_timer_osa_platforms>> below summarizes the four
+categores of timer and interrupt support allowed in a OS/A platorm.
+
+[#table_interrutps_and_timer_osa_platforms]
+.Interrupts and Timer support in OS/A platforms
+[stripes="none", width="100%", cols="^2s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s"]
+|===
+.2+|+++<font size=".8em">OS-A Platform</font>+++
+3+|+++<font size=".8em">MSIs</font>+++
+3+|+++<font size=".8em">Wired Interrupts</font>+++
+3+|+++<font size=".8em">Software Interrupts</font>+++
+3+|+++<font size=".8em">Timer</font>+++
+|+++<font size=".64em">M-mode</font>+++
+|+++<font size=".64em">S-mode</font>+++
+|+++<font size=".64em">VS-mode</font>+++
+|+++<font size=".64em">M-mode</font>+++
+|+++<font size=".64em">S-mode</font>+++
+|+++<font size=".64em">VS-mode</font>+++
+|+++<font size=".64em">M-mode</font>+++
+|+++<font size=".64em">S-mode</font>+++
+|+++<font size=".64em">VS-mode</font>+++
+|+++<font size=".64em">M-mode</font>+++
+|+++<font size=".64em">S-mode</font>+++
+|+++<font size=".64em">VS-mode</font>+++
+
+|+++<font size=".8em">Legacy IRQs</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">PLIC</font>+++^2^
+|+++<font size=".64em">PLIC</font>+++^2^
+|+++<font size=".64em">PLIC</font>+++^2,6^
+|+++<color rgb="#6aa84f"><font size=".64em">MSWI</font></color>+++^3^
+|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
+|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
+|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
+|+++<color rgb="#e06666"><font size=".64em">SBI Timer</font></color>+++^5^
+|+++<color rgb="#e06666"><font size=".64em">SBI Timer</font></color>+++^5^
+
+|+++<font size=".8em">Only Wired IRQs</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4,6^
+|+++<color rgb="#6aa84f"><font size=".64em">MSWI</font></color>+++^3^
+|+++<color rgb="#6aa84f"><font size=".64em">SSWI</font></color>+++^3^
+|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
+|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+
+|+++<font size=".8em">MSIs and Wired IRQs</font>+++
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4,6^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4,6^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
+|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+
+|+++<font size=".8em">MSIs, Virtual MSIs and Wired IRQs</font>+++
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4,6^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+
+13+s|
+
++++<font size=".64em"><color rgb="#e69138">
+1. RISC-V Privileged Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#000000">
+2. RISC-V PLIC Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#6aa84f">
+3. RISC-V ACLINT Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#738dc5">
+4. RISC-V AIA Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#e06666">
+5. RISC-V SBI Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#000000">
+6. Trapped and emulated by hypervisors
+</color></font>+++
+
+|===

==== System Peripherals
* UART/Serial Console
@@ -369,27 +424,6 @@ of the following:
** UART 16550 - _REQUIRED_
** UART 8250 - _DEPRECATED_

-* Clock and Timers
-** Platforms are required to provide an at least 10ns resolution 64-bit counter
-with strictly monotonic updates.
-** The hardware clock that drives the counter is required to operate at a minimum
-frequency of 10MHz.
-** Platforms that use DT for hardware discovery are required to advertise the
-timebase to the operating systems via the `timebase-frequency` property of the
-"/cpus" node
-footnote:[https://elixir.bootlin.com/linux/latest/source/Documentation/devicetree/bindings/riscv/cpus.yaml].
-
-[sidebar]
---
-[underline]*_Implementation Note_*
-
-For a counter with 10ns resolution the `timebase-frequency` value would be 100000000
-(100 MHz) which would also be the minimum possible value for `timebase-frequency`.
-From the software perspective a unit increment of the mtime value would correspond
-to a 10ns interval. However the hardware clock driving the counter could operate at a
-lower frequency, thereby incrementing the mtime value by more than one unit per
-clock tick.
---
==== Boot Process
- The base specification defines the interface between the firmware and the
operating system suitable for the RISC-V platforms with rich operating
@@ -499,7 +533,9 @@ above.
respect to all harts connected to the DM
* Rationale: Debuggers must be able to view memory coherently

-==== Interrupt Controller
+==== Interrupts and Timer
+
+TBD.

==== Boot and Runtime Requirements
===== Firmware
diff --git a/riscv-platform-spec.yml b/riscv-platform-spec.yml
new file mode 100644
index 0000000..ce00e22
--- /dev/null
+++ b/riscv-platform-spec.yml
@@ -0,0 +1,8 @@
+extends: default
+image:
+ align: center
+caption:
+ align: center
+table:
+ caption:
+ side: bottom
--
2.25.1


Heinrich Schuchardt
 

On 28.07.21 15:33, Anup Patel wrote:
We re-write the interrupts and timer section to align the
interrupts and timer table.

Signed-off-by: Anup Patel <anup.patel@...>
---
Makefile | 4 +-
riscv-platform-spec.adoc | 294 ++++++++++++++++++++++-----------------
riscv-platform-spec.yml | 8 ++
3 files changed, 175 insertions(+), 131 deletions(-)
create mode 100644 riscv-platform-spec.yml

diff --git a/Makefile b/Makefile
index 48e8fe9..ff8fbf6 100644
--- a/Makefile
+++ b/Makefile
@@ -22,8 +22,8 @@ $(PLATFORM_SPEC).md: $(PLATFORM_SPEC).xml
$(PLATFORM_SPEC).xml: $(PLATFORM_SPEC).adoc
$(ASCIIDOCTOR) -d book -b docbook $<

-$(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc $(IMAGES)
- $(ASCIIDOCTOR) -d book -r asciidoctor-pdf -b pdf $<
+$(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc $(IMAGES) $(PLATFORM_SPEC).yml
+ $(ASCIIDOCTOR) -d book -r asciidoctor-pdf -a pdf-style=$(PLATFORM_SPEC).yml -b pdf $<

$(PLATFORM_SPEC).html: $(PLATFORM_SPEC).adoc $(IMAGES)
$(ASCIIDOCTOR) -d book -b html $<
diff --git a/riscv-platform-spec.adoc b/riscv-platform-spec.adoc
index 2fee40b..7261704 100644
--- a/riscv-platform-spec.adoc
+++ b/riscv-platform-spec.adoc
@@ -13,6 +13,7 @@
:doctype: book
:sectnums:
:sectnumlevels: 5
+:xrefstyle: short
:toc: macro
:toclevels: 5

@@ -245,114 +246,168 @@ each must be 1
The default should allow code that's sensitive to these requirements to be
debugged.

-==== Interrupt Controller, Software Interrupt, and Timer Requirements
-In the following requirements,
-https://github.com/riscv/riscv-aia[*AIA*] refers to the Advanced Interrupt Architecture, https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[*ACLINT*]
-refers to the Advanced *CLINT*. AIA comprises two separate components: `IMSICs` and `APLICs`.
-If supported, there is an `IMSIC` device associated with each hart.
-If supported, *APLIC* devices are global to all harts, and there may be one or
-multiple in a system. *ACLINT* comprises three separate components: `MTIMER` for
-Timer support, and `MSWI` and `SSWI` for Machine-level and Supervisor-level
-Software Interrupt (IPI) support. +
-https://github.com/riscv/riscv-plic-spec/blob/master/riscv-plic.adoc[*PLIC*]
-refers to the legacy Platform-Level Interrupt Controller that provides
-facilities to route external interrupts to a hart context with a given privilege
-mode. The number of non-local interrupt sources supported by PLIC and how does
-each of them connect to the hart context is PLIC core implementation-specific. +
-*CLINT* is a legacy Core-Local Interrupt Controller that is a compatible subset of
-ACLINT which provides facilities to trigger Software (IPI) and Timer interrupts to
-hart.
+==== Interrupts and Timer
+
+===== Timer support
+
+* One or more ACLINT MTIMER devices are required for OS-A platform and each
%s/for OS-A/for the OS-A/

+ hart must have an associated ACLINT MTIMER device
Do you want to allow harts with further ACLINT MTIMER devices? Or is the
requirement that each hart must have exactly one ACLINT MTIMER device?

+* The update period of MTIME counter should be 10ns or less
+* The hardware clock that drives the MTIME counter is required to operate
+ at a minimum frequency of 10MHz
+* Platforms must provide a way to discover MTIME update frequency using
+ appropriate hardware discovery mechanism:
+** Platforms that use DT for hardware discovery are required to advertise the
+ timebase to the operating systems via the `timebase-frequency` property of
+ the "/cpus" node
+footnote:[https://elixir.bootlin.com/linux/latest/source/Documentation/devicetree/bindings/riscv/cpus.yaml].
+
+[sidebar]
+--
+[underline]*_Implementation Note_*
+
+For a counter with 10ns resolution the `timebase-frequency` value would be
+100000000 (100 MHz) which would also be the minimum possible value for
+`timebase-frequency`. From the software perspective a unit increment of the
+mtime value would correspond to a 10ns interval. However the hardware clock
+driving the counter could operate at a lower frequency, thereby incrementing
+the mtime value by more than one unit per clock tick.
An example would help:

If the timebase-frequency is 100 MHz and the hardware clock runs at 25
Mhz, we could get MTIME values 0, 4, 8, 12, ... corresponding to 0ns,
40ns, 80ns, 120ns, ...

Best regards

Heinrich

+--

-.The following table summarizes what features are supported for four classes of OS/A platforms.
-[width="100%",cols="^,^,^,^,^,^,^,^,^,^,^,^,^"]
-|=======
-.2+|*OS-A Platform* 3+|*MSIs* 3+|*Wired Interrupts* 3+|*IPIs* 3+|*Timer*
-|M-level|S-level|VS-level|M-level|S-level|VS-level|M-level|S-level|VS-level|M-level|S-level|VS-level
-|Existing|NA|NA|NA|PLIC|PLIC|PLIC +
-_(Trap and emulate)_|MSWI +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-SBI IPI +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|SBI IPI +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|MTIMER +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|SBI Timer +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|SBI Timer +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]
-|Only Wired IRQs|NA|NA|NA|APLIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-_(Trap and emulate)_ +
-https://github.com/riscv/riscv-aia[`*AIA*`]|MSWI +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-SSWI +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-SBI IPI +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|MTIMER +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]
-|MSIs and Wired IRQs|IMSIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-_(Trap and emulate)_ +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-_(Trap and emulate)_ +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|SBI IPI +
-https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|MTIMER +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]
-|MSIs, Virtual MSIs and Wired IRQs|IMSIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC VS-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
-_(Trap and emulate)_ +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC M-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC VS-level +
-https://github.com/riscv/riscv-aia[`*AIA*`]|MTIMER +
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]|
-Priv Sstc +
-https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]
-|=======
-
-* For Timer support, one or more ACLINT MTIMER devices are Required for OS-A platform.
-One MTIMER may be used for all harts, or multiple MTIMERs may be used with
-multiple topological groups of harts. The base address of MTIMER memory map registers
-is platform implementation-specific, however, the format of MTIMER operation parameters
-(`mtime` and `mtimecmp` registers) must be compliant with
-https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc#21-register-map[ACLINT MTIMER Register Map]
-
-* For Interrupt Controller and Software Interrupt support, one of the following three
-choices below is Required
- ** PLIC plus one or more ACLINT MSWI devices - DEPRECATED
- *** One MSWI may be used for all harts, or multiple MSWIs may be used with
-multiple topological groups of harts
- *** Only wired interrupts and M-mode IPIs are supported
- *** Virtualization is not supported
- *** This compatibly supports legacy PLIC + CLINT designs
- ** One or more AIA APLIC devices plus one or more pairs of ACLINT MSWI and ACLINT SSWI devices
- *** One MSWI/SSWI pair may be used for all harts, or multiple MSWI/SSWI
-pairs may be used with multiple topological groups of harts
- *** Only wired interrupts are supported
- *** Both M-mode and S-mode IPIs are supported
- *** Virtualization is not supported
- ** Zero, one, or more AIA APLIC devices plus per-hart AIA IMSIC devices
- *** Both wired and MSI external interrupts are supported
- *** Both M-mode and S-mode IPIs are supported via IMSICs
- *** Virtualization is supported
- *** Zero APLICs if there are no wired interrupts and only MSIs
+===== Interrupts support
+
+The OS/A platorms can comply with one of the following four categories for
+interrupts support:
+
+* *Legacy IRQs - DEPRECATED*
+** One PLIC device to support wired interrupts
+** One or more ACLINT MSWI devices to support M-mode software interrupts
+** Compatibile with legacy platforms having PLIC plus CLINT
+** MSI external interrupts not supported
+* *Only Wired IRQs*
+** One or more AIA APLIC devices to support wired interrupts
+** One or more ACLINT MSWI devices to support M-mode software interrupts
+** One or more ACLINT SSWI devices to support HS-mode software interrupts
+** MSI external interrupts not supported
+* *MSIs and Wired IRQs*
+** One, or more AIA APLIC devices to support wired interrupts
+** Per-hart AIA IMSIC devices to support MSIs for M-mode and HS-mode
+** Software interrupts for M-mode and HS-mode supported using AIA IMSIC devices
+** MSI virtualization is not supported
+* *MSIs, Virtual MSIs, and Wired IRQs*
+** One, or more AIA APLIC devices to support wired interrupts
+** Per-hart AIA IMSIC devices to support MSIs for M-mode, HS-mode and VS-mode
+** Software interrupts for M-mode, HS-mode and VS-mode supported using
+ AIA IMSIC devices
+** MSI virtualization is supported
+
+<<<
+
+===== Summary
+
+The <<table_interrutps_and_timer_osa_platforms>> below summarizes the four
+categores of timer and interrupt support allowed in a OS/A platorm.
+
+[#table_interrutps_and_timer_osa_platforms]
+.Interrupts and Timer support in OS/A platforms
+[stripes="none", width="100%", cols="^2s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s"]
+|===
+.2+|+++<font size=".8em">OS-A Platform</font>+++
+3+|+++<font size=".8em">MSIs</font>+++
+3+|+++<font size=".8em">Wired Interrupts</font>+++
+3+|+++<font size=".8em">Software Interrupts</font>+++
+3+|+++<font size=".8em">Timer</font>+++
+|+++<font size=".64em">M-mode</font>+++
+|+++<font size=".64em">S-mode</font>+++
+|+++<font size=".64em">VS-mode</font>+++
+|+++<font size=".64em">M-mode</font>+++
+|+++<font size=".64em">S-mode</font>+++
+|+++<font size=".64em">VS-mode</font>+++
+|+++<font size=".64em">M-mode</font>+++
+|+++<font size=".64em">S-mode</font>+++
+|+++<font size=".64em">VS-mode</font>+++
+|+++<font size=".64em">M-mode</font>+++
+|+++<font size=".64em">S-mode</font>+++
+|+++<font size=".64em">VS-mode</font>+++
+
+|+++<font size=".8em">Legacy IRQs</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">PLIC</font>+++^2^
+|+++<font size=".64em">PLIC</font>+++^2^
+|+++<font size=".64em">PLIC</font>+++^2,6^
+|+++<color rgb="#6aa84f"><font size=".64em">MSWI</font></color>+++^3^
+|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
+|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
+|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
+|+++<color rgb="#e06666"><font size=".64em">SBI Timer</font></color>+++^5^
+|+++<color rgb="#e06666"><font size=".64em">SBI Timer</font></color>+++^5^
+
+|+++<font size=".8em">Only Wired IRQs</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<font size=".64em">NA</font>+++
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4,6^
+|+++<color rgb="#6aa84f"><font size=".64em">MSWI</font></color>+++^3^
+|+++<color rgb="#6aa84f"><font size=".64em">SSWI</font></color>+++^3^
+|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
+|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+
+|+++<font size=".8em">MSIs and Wired IRQs</font>+++
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4,6^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4,6^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
+|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+
+|+++<font size=".8em">MSIs, Virtual MSIs and Wired IRQs</font>+++
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4,6^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
+|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
+
+13+s|
+
++++<font size=".64em"><color rgb="#e69138">
+1. RISC-V Privileged Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#000000">
+2. RISC-V PLIC Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#6aa84f">
+3. RISC-V ACLINT Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#738dc5">
+4. RISC-V AIA Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#e06666">
+5. RISC-V SBI Specification
+</color></font>+++ +
++++<font size=".64em"><color rgb="#000000">
+6. Trapped and emulated by hypervisors
+</color></font>+++
+
+|===

==== System Peripherals
* UART/Serial Console
@@ -369,27 +424,6 @@ of the following:
** UART 16550 - _REQUIRED_
** UART 8250 - _DEPRECATED_

-* Clock and Timers
-** Platforms are required to provide an at least 10ns resolution 64-bit counter
-with strictly monotonic updates.
-** The hardware clock that drives the counter is required to operate at a minimum
-frequency of 10MHz.
-** Platforms that use DT for hardware discovery are required to advertise the
-timebase to the operating systems via the `timebase-frequency` property of the
-"/cpus" node
-footnote:[https://elixir.bootlin.com/linux/latest/source/Documentation/devicetree/bindings/riscv/cpus.yaml].
-
-[sidebar]
---
-[underline]*_Implementation Note_*
-
-For a counter with 10ns resolution the `timebase-frequency` value would be 100000000
-(100 MHz) which would also be the minimum possible value for `timebase-frequency`.
-From the software perspective a unit increment of the mtime value would correspond
-to a 10ns interval. However the hardware clock driving the counter could operate at a
-lower frequency, thereby incrementing the mtime value by more than one unit per
-clock tick.
---
==== Boot Process
- The base specification defines the interface between the firmware and the
operating system suitable for the RISC-V platforms with rich operating
@@ -499,7 +533,9 @@ above.
respect to all harts connected to the DM
* Rationale: Debuggers must be able to view memory coherently

-==== Interrupt Controller
+==== Interrupts and Timer
+
+TBD.

==== Boot and Runtime Requirements
===== Firmware
diff --git a/riscv-platform-spec.yml b/riscv-platform-spec.yml
new file mode 100644
index 0000000..ce00e22
--- /dev/null
+++ b/riscv-platform-spec.yml
@@ -0,0 +1,8 @@
+extends: default
+image:
+ align: center
+caption:
+ align: center
+table:
+ caption:
+ side: bottom


Anup Patel
 

Please see inline below ...

Regards,
Anup

´╗┐On 29/07/21, 12:04 AM, "Heinrich Schuchardt" <xypron.glpk@...> wrote:



On 28.07.21 15:33, Anup Patel wrote:
> We re-write the interrupts and timer section to align the
> interrupts and timer table.
>
> Signed-off-by: Anup Patel <anup.patel@...>
> ---
> Makefile | 4 +-
> riscv-platform-spec.adoc | 294 ++++++++++++++++++++++-----------------
> riscv-platform-spec.yml | 8 ++
> 3 files changed, 175 insertions(+), 131 deletions(-)
> create mode 100644 riscv-platform-spec.yml
>
> diff --git a/Makefile b/Makefile
> index 48e8fe9..ff8fbf6 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -22,8 +22,8 @@ $(PLATFORM_SPEC).md: $(PLATFORM_SPEC).xml
> $(PLATFORM_SPEC).xml: $(PLATFORM_SPEC).adoc
> $(ASCIIDOCTOR) -d book -b docbook $<
>
> -$(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc $(IMAGES)
> - $(ASCIIDOCTOR) -d book -r asciidoctor-pdf -b pdf $<
> +$(PLATFORM_SPEC).pdf: $(PLATFORM_SPEC).adoc $(IMAGES) $(PLATFORM_SPEC).yml
> + $(ASCIIDOCTOR) -d book -r asciidoctor-pdf -a pdf-style=$(PLATFORM_SPEC).yml -b pdf $<
>
> $(PLATFORM_SPEC).html: $(PLATFORM_SPEC).adoc $(IMAGES)
> $(ASCIIDOCTOR) -d book -b html $<
> diff --git a/riscv-platform-spec.adoc b/riscv-platform-spec.adoc
> index 2fee40b..7261704 100644
> --- a/riscv-platform-spec.adoc
> +++ b/riscv-platform-spec.adoc
> @@ -13,6 +13,7 @@
> :doctype: book
> :sectnums:
> :sectnumlevels: 5
> +:xrefstyle: short
> :toc: macro
> :toclevels: 5
>
> @@ -245,114 +246,168 @@ each must be 1
> The default should allow code that's sensitive to these requirements to be
> debugged.
>
> -==== Interrupt Controller, Software Interrupt, and Timer Requirements
> -In the following requirements,
> -https://github.com/riscv/riscv-aia[*AIA*] refers to the Advanced Interrupt Architecture, https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[*ACLINT*]
> -refers to the Advanced *CLINT*. AIA comprises two separate components: `IMSICs` and `APLICs`.
> -If supported, there is an `IMSIC` device associated with each hart.
> -If supported, *APLIC* devices are global to all harts, and there may be one or
> -multiple in a system. *ACLINT* comprises three separate components: `MTIMER` for
> -Timer support, and `MSWI` and `SSWI` for Machine-level and Supervisor-level
> -Software Interrupt (IPI) support. +
> -https://github.com/riscv/riscv-plic-spec/blob/master/riscv-plic.adoc[*PLIC*]
> -refers to the legacy Platform-Level Interrupt Controller that provides
> -facilities to route external interrupts to a hart context with a given privilege
> -mode. The number of non-local interrupt sources supported by PLIC and how does
> -each of them connect to the hart context is PLIC core implementation-specific. +
> -*CLINT* is a legacy Core-Local Interrupt Controller that is a compatible subset of
> -ACLINT which provides facilities to trigger Software (IPI) and Timer interrupts to
> -hart.
> +==== Interrupts and Timer
> +
> +===== Timer support
> +
> +* One or more ACLINT MTIMER devices are required for OS-A platform and each

%s/for OS-A/for the OS-A/

[Anup] Okay, will update.

> + hart must have an associated ACLINT MTIMER device

Do you want to allow harts with further ACLINT MTIMER devices? Or is the
requirement that each hart must have exactly one ACLINT MTIMER device?

[Anup] I think we should just remove the second part of the sentence because
it is creating confusion.
[Anup] The ACLINT specification already mentions that a ACLINT MTIMER device
connects to a set of HARTs and we can have multiple ACLINT MTIMER devices
in a RISC-V platform.

> +* The update period of MTIME counter should be 10ns or less
> +* The hardware clock that drives the MTIME counter is required to operate
> + at a minimum frequency of 10MHz
> +* Platforms must provide a way to discover MTIME update frequency using
> + appropriate hardware discovery mechanism:
> +** Platforms that use DT for hardware discovery are required to advertise the
> + timebase to the operating systems via the `timebase-frequency` property of
> + the "/cpus" node
> +footnote:[https://elixir.bootlin.com/linux/latest/source/Documentation/devicetree/bindings/riscv/cpus.yaml].
> +
> +[sidebar]
> +--
> +[underline]*_Implementation Note_*
> +
> +For a counter with 10ns resolution the `timebase-frequency` value would be
> +100000000 (100 MHz) which would also be the minimum possible value for
> +`timebase-frequency`. From the software perspective a unit increment of the
> +mtime value would correspond to a 10ns interval. However the hardware clock
> +driving the counter could operate at a lower frequency, thereby incrementing
> +the mtime value by more than one unit per clock tick.

An example would help:

If the timebase-frequency is 100 MHz and the hardware clock runs at 25
Mhz, we could get MTIME values 0, 4, 8, 12, ... corresponding to 0ns,
40ns, 80ns, 120ns, ...

[Anup] Sure, let me add this example.

Best regards

Heinrich

> +--
>
> -.The following table summarizes what features are supported for four classes of OS/A platforms.
> -[width="100%",cols="^,^,^,^,^,^,^,^,^,^,^,^,^"]
> -|=======
> -.2+|*OS-A Platform* 3+|*MSIs* 3+|*Wired Interrupts* 3+|*IPIs* 3+|*Timer*
> -|M-level|S-level|VS-level|M-level|S-level|VS-level|M-level|S-level|VS-level|M-level|S-level|VS-level
> -|Existing|NA|NA|NA|PLIC|PLIC|PLIC +
> -_(Trap and emulate)_|MSWI +
> -https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
> -SBI IPI +
> -https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|SBI IPI +
> -https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|MTIMER +
> -https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|SBI Timer +
> -https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|SBI Timer +
> -https://github.com/riscv/riscv-sbi-doc[`*SBI*`]
> -|Only Wired IRQs|NA|NA|NA|APLIC M-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
> -_(Trap and emulate)_ +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|MSWI +
> -https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
> -SSWI +
> -https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
> -SBI IPI +
> -https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|MTIMER +
> -https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
> -Priv Sstc +
> -https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]|
> -Priv Sstc +
> -https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]
> -|MSIs and Wired IRQs|IMSIC M-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
> -_(Trap and emulate)_ +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC M-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
> -_(Trap and emulate)_ +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC M-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|SBI IPI +
> -https://github.com/riscv/riscv-sbi-doc[`*SBI*`]|MTIMER +
> -https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
> -Priv Sstc +
> -https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]|
> -Priv Sstc +
> -https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]
> -|MSIs, Virtual MSIs and Wired IRQs|IMSIC M-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC VS-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC M-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|APLIC S-level +
> -_(Trap and emulate)_ +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC M-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC S-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|IMSIC VS-level +
> -https://github.com/riscv/riscv-aia[`*AIA*`]|MTIMER +
> -https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc[`*ACLINT*`]|
> -Priv Sstc +
> -https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]|
> -Priv Sstc +
> -https://github.com/riscv/riscv-isa-manual/releases[`*Priv Spec*`]
> -|=======
> -
> -* For Timer support, one or more ACLINT MTIMER devices are Required for OS-A platform.
> -One MTIMER may be used for all harts, or multiple MTIMERs may be used with
> -multiple topological groups of harts. The base address of MTIMER memory map registers
> -is platform implementation-specific, however, the format of MTIMER operation parameters
> -(`mtime` and `mtimecmp` registers) must be compliant with
> -https://github.com/riscv/riscv-aclint/blob/main/riscv-aclint.adoc#21-register-map[ACLINT MTIMER Register Map]
> -
> -* For Interrupt Controller and Software Interrupt support, one of the following three
> -choices below is Required
> - ** PLIC plus one or more ACLINT MSWI devices - DEPRECATED
> - *** One MSWI may be used for all harts, or multiple MSWIs may be used with
> -multiple topological groups of harts
> - *** Only wired interrupts and M-mode IPIs are supported
> - *** Virtualization is not supported
> - *** This compatibly supports legacy PLIC + CLINT designs
> - ** One or more AIA APLIC devices plus one or more pairs of ACLINT MSWI and ACLINT SSWI devices
> - *** One MSWI/SSWI pair may be used for all harts, or multiple MSWI/SSWI
> -pairs may be used with multiple topological groups of harts
> - *** Only wired interrupts are supported
> - *** Both M-mode and S-mode IPIs are supported
> - *** Virtualization is not supported
> - ** Zero, one, or more AIA APLIC devices plus per-hart AIA IMSIC devices
> - *** Both wired and MSI external interrupts are supported
> - *** Both M-mode and S-mode IPIs are supported via IMSICs
> - *** Virtualization is supported
> - *** Zero APLICs if there are no wired interrupts and only MSIs
> +===== Interrupts support
> +
> +The OS/A platorms can comply with one of the following four categories for
> +interrupts support:
> +
> +* *Legacy IRQs - DEPRECATED*
> +** One PLIC device to support wired interrupts
> +** One or more ACLINT MSWI devices to support M-mode software interrupts
> +** Compatibile with legacy platforms having PLIC plus CLINT
> +** MSI external interrupts not supported
> +* *Only Wired IRQs*
> +** One or more AIA APLIC devices to support wired interrupts
> +** One or more ACLINT MSWI devices to support M-mode software interrupts
> +** One or more ACLINT SSWI devices to support HS-mode software interrupts
> +** MSI external interrupts not supported
> +* *MSIs and Wired IRQs*
> +** One, or more AIA APLIC devices to support wired interrupts
> +** Per-hart AIA IMSIC devices to support MSIs for M-mode and HS-mode
> +** Software interrupts for M-mode and HS-mode supported using AIA IMSIC devices
> +** MSI virtualization is not supported
> +* *MSIs, Virtual MSIs, and Wired IRQs*
> +** One, or more AIA APLIC devices to support wired interrupts
> +** Per-hart AIA IMSIC devices to support MSIs for M-mode, HS-mode and VS-mode
> +** Software interrupts for M-mode, HS-mode and VS-mode supported using
> + AIA IMSIC devices
> +** MSI virtualization is supported
> +
> +<<<
> +
> +===== Summary
> +
> +The <<table_interrutps_and_timer_osa_platforms>> below summarizes the four
> +categores of timer and interrupt support allowed in a OS/A platorm.
> +
> +[#table_interrutps_and_timer_osa_platforms]
> +.Interrupts and Timer support in OS/A platforms
> +[stripes="none", width="100%", cols="^2s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s,^1s"]
> +|===
> +.2+|+++<font size=".8em">OS-A Platform</font>+++
> +3+|+++<font size=".8em">MSIs</font>+++
> +3+|+++<font size=".8em">Wired Interrupts</font>+++
> +3+|+++<font size=".8em">Software Interrupts</font>+++
> +3+|+++<font size=".8em">Timer</font>+++
> +|+++<font size=".64em">M-mode</font>+++
> +|+++<font size=".64em">S-mode</font>+++
> +|+++<font size=".64em">VS-mode</font>+++
> +|+++<font size=".64em">M-mode</font>+++
> +|+++<font size=".64em">S-mode</font>+++
> +|+++<font size=".64em">VS-mode</font>+++
> +|+++<font size=".64em">M-mode</font>+++
> +|+++<font size=".64em">S-mode</font>+++
> +|+++<font size=".64em">VS-mode</font>+++
> +|+++<font size=".64em">M-mode</font>+++
> +|+++<font size=".64em">S-mode</font>+++
> +|+++<font size=".64em">VS-mode</font>+++
> +
> +|+++<font size=".8em">Legacy IRQs</font>+++
> +|+++<font size=".64em">NA</font>+++
> +|+++<font size=".64em">NA</font>+++
> +|+++<font size=".64em">NA</font>+++
> +|+++<font size=".64em">PLIC</font>+++^2^
> +|+++<font size=".64em">PLIC</font>+++^2^
> +|+++<font size=".64em">PLIC</font>+++^2,6^
> +|+++<color rgb="#6aa84f"><font size=".64em">MSWI</font></color>+++^3^
> +|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
> +|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
> +|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
> +|+++<color rgb="#e06666"><font size=".64em">SBI Timer</font></color>+++^5^
> +|+++<color rgb="#e06666"><font size=".64em">SBI Timer</font></color>+++^5^
> +
> +|+++<font size=".8em">Only Wired IRQs</font>+++
> +|+++<font size=".64em">NA</font>+++
> +|+++<font size=".64em">NA</font>+++
> +|+++<font size=".64em">NA</font>+++
> +|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4,6^
> +|+++<color rgb="#6aa84f"><font size=".64em">MSWI</font></color>+++^3^
> +|+++<color rgb="#6aa84f"><font size=".64em">SSWI</font></color>+++^3^
> +|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
> +|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
> +|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
> +|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
> +
> +|+++<font size=".8em">MSIs and Wired IRQs</font>+++
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4,6^
> +|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4,6^
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#e06666"><font size=".64em">SBI IPI</font></color>+++^5^
> +|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
> +|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
> +|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
> +
> +|+++<font size=".8em">MSIs, Virtual MSIs and Wired IRQs</font>+++
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">APLIC</font></color>+++^4,6^
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#738dc5"><font size=".64em">IMSIC</font></color>+++^4^
> +|+++<color rgb="#6aa84f"><font size=".64em">MTIMER</font></color>+++^3^
> +|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
> +|+++<color rgb="#e69138"><font size=".64em">Priv Sstc</font></color>+++^1^
> +
> +13+s|
> +
> ++++<font size=".64em"><color rgb="#e69138">
> +1. RISC-V Privileged Specification
> +</color></font>+++ +
> ++++<font size=".64em"><color rgb="#000000">
> +2. RISC-V PLIC Specification
> +</color></font>+++ +
> ++++<font size=".64em"><color rgb="#6aa84f">
> +3. RISC-V ACLINT Specification
> +</color></font>+++ +
> ++++<font size=".64em"><color rgb="#738dc5">
> +4. RISC-V AIA Specification
> +</color></font>+++ +
> ++++<font size=".64em"><color rgb="#e06666">
> +5. RISC-V SBI Specification
> +</color></font>+++ +
> ++++<font size=".64em"><color rgb="#000000">
> +6. Trapped and emulated by hypervisors
> +</color></font>+++
> +
> +|===
>
> ==== System Peripherals
> * UART/Serial Console
> @@ -369,27 +424,6 @@ of the following:
> ** UART 16550 - _REQUIRED_
> ** UART 8250 - _DEPRECATED_
>
> -* Clock and Timers
> -** Platforms are required to provide an at least 10ns resolution 64-bit counter
> -with strictly monotonic updates.
> -** The hardware clock that drives the counter is required to operate at a minimum
> -frequency of 10MHz.
> -** Platforms that use DT for hardware discovery are required to advertise the
> -timebase to the operating systems via the `timebase-frequency` property of the
> -"/cpus" node
> -footnote:[https://elixir.bootlin.com/linux/latest/source/Documentation/devicetree/bindings/riscv/cpus.yaml].
> -
> -[sidebar]
> ---
> -[underline]*_Implementation Note_*
> -
> -For a counter with 10ns resolution the `timebase-frequency` value would be 100000000
> -(100 MHz) which would also be the minimum possible value for `timebase-frequency`.
> -From the software perspective a unit increment of the mtime value would correspond
> -to a 10ns interval. However the hardware clock driving the counter could operate at a
> -lower frequency, thereby incrementing the mtime value by more than one unit per
> -clock tick.
> ---
> ==== Boot Process
> - The base specification defines the interface between the firmware and the
> operating system suitable for the RISC-V platforms with rich operating
> @@ -499,7 +533,9 @@ above.
> respect to all harts connected to the DM
> * Rationale: Debuggers must be able to view memory coherently
>
> -==== Interrupt Controller
> +==== Interrupts and Timer
> +
> +TBD.
>
> ==== Boot and Runtime Requirements
> ===== Firmware
> diff --git a/riscv-platform-spec.yml b/riscv-platform-spec.yml
> new file mode 100644
> index 0000000..ce00e22
> --- /dev/null
> +++ b/riscv-platform-spec.yml
> @@ -0,0 +1,8 @@
> +extends: default
> +image:
> + align: center
> +caption:
> + align: center
> +table:
> + caption:
> + side: bottom
>