Make some reorganizations in the chapeter. THe idea is to move anythi…

…ng from ABI to appendix
riscv · Sep 6, 2024 · b2b23ad · b2b23ad
1 parent b1092bc
commit b2b23ad
Showing 1 changed file with 146 additions and 131 deletions.
diff --git a/src/clic.adoc b/src/clic.adoc
@@ -2072,6 +2072,144 @@ For example, if `CLICINTCTLBITS` is 1 and `INTTHRESHBITS` is 2, interrupts can b
 
 == Interrupt Handling Software
 
+The CLIC supports multiple nested interrupt handlers, and each handler
+requires some working registers. To make registers available, each
+handler typically saves and restores registers from the interrupted
+context on a memory-resident stack.  Appendix are describing different methods
+to handle this handler SW supports.
+
+== Separating Stack per Interrupt Level
+
+Within a single privilege mode, it can be useful to separate interrupt
+handler tasks from application tasks to increase robustness, reduce
+space usage, and aid in system debugging.  Interrupt handler tasks
+have non-zero interrupt levels, while application tasks have an
+interrupt level of zero.
+
+
+
+== CLIC Interrupt ID ordering recommendations
+
+The specific numbering of interrupts is defined by the platform.  A
+platform definition will often be based on a specific RISC-V ISA
+profile, where RISC-V ISA profiles specify a common set of ISA choices
+that capture the most value for most users to enable software
+compatibility.
+
+Certain RISC-V profiles may include the CLIC as an option.
+
+Four different CLIC interrupt ID orderings are enumerated below for
+ease of reference in profile specifications.
+
+=== CLIC-mode interrupt-map for systems retaining interrupt ID compatible with CLINT mode:
+
+The CLINT-mode interrupts retain their interrupt ID in CLIC mode.
+The `clicintattr` settings are now used to delegate these interrupts as
+required.
+
+We recommend allocating an edge-triggered CLIC software interrupt bit
+(`csip`) with the lowest number (16) among the local interrupts to
+provide support for a local background interrupt thread, e.g. context
+switching.  By placing the `csip` interrupt at the lowest number among
+local interrupts, we avoid requiring another interrupt level to
+ensure this only runs when there are no other interrupts.
+
+The existing CLINT software interrupt bits are primarily intended for
+inter-hart interrupt signaling, and so are retained for that purpose.
+The software interrupts can have their priority changed using their
+`clicintctl` setting.
+
+CLIC interrupt inputs are allocated IDs beginning at interrupt ID 17.
+Any fast local interrupts that would have been connected at interrupt
+ID 16 and above should now be mapped into corresponding inputs of the
+CLIC.
+
+[source]
+----
+ID  Interrupt   Note
+
+ 0  usip        User software Interrupt
+ 1  ssip        Supervisor software Interrupt
+ 2  reserved
+ 3  msip        Machine software interrupt
+
+ 4  utip        User timer interrupt
+ 5  stip        Supervisor timer interrupt
+ 6  reserved
+ 7  mtip        Machine timer interrupt
+
+ 8  ueip        User external (PLIC/APLIC) interrupt
+ 9  seip        Supervisor external (PLIC/APLIC) interrupt
+10  reserved
+11  meip        Machine external (PLIC/APLIC) interrupt
+
+12  reserved
+13  reserved
+14  reserved
+15  reserved
+
+16  csip        CLIC software interrupt
+17+ inputs      CLIC local inputs
+----
+
+In CLINT mode, as stated in the RISC-V privilege specification, each
+individual bit in CSR register {ip} may be software writable or may be
+software read-only. When bit _i_ in {ip} is writable, a pending
+interrupt _i_ can be cleared by writing `0` to this bit. STIP is
+writable in `mip`, and may be written by M-mode software to deliver
+timer interrupts to S-mode.
+
+However, in CLIC mode, {ip} bits cannot be updated in software when
+they are in level-sensitive mode.  One possible equivalent
+implementation to deliver timer interrupts would be to hardwire the
+STIP input to 0 and then M-mode software can deliver timer interrupts to
+S-mode by setting `clicintattr[stip].trig` to `00`
+(positive-edge-triggered) and writing `clicintip[stip]` to `1`.
+
+The following optional recommendations remove unused interrupt inputs
+and compress the map to simplify hardware implementations.
+
+=== CLIC-mode interrupt-map recommendation for single-hart systems with PLIC/APLIC:
+
+[source]
+----
+ID  Interrupt
+0   S-mode software interrupt
+1   S-mode timer interrupt
+2   S-mode external (PLIC/APLIC) interrupt
+3   M-mode software interrupt
+4   M-mode timer interrupt
+5   M-mode external (PLIC/APLIC) interrupt
+6+  local
+----
+
+=== CLIC-mode interrupt-map recommendation for single-hart M/S/U systems without N-extension with no PLIC/APLIC:
+
+[source]
+----
+ID  Interrupt
+0   S-mode software interrupt
+1   S-mode timer interrupt
+2   M-mode software interrupt
+3   M-mode timer interrupt
+4+  other
+----
+
+=== CLIC-mode interrupt-map recommendation for single-hart M-mode only or M/U mode
+systems without N extension and no PLIC/APLIC:
+
+[source]
+----
+ID  Interrupt
+0   M-mode software interrupt
+1   M-mode timer interrupt
+2+  other
+----
+
+
+[appendix]
+== Appendix : Interrupt Handling Software
+
 === Interrupt Stack Software Conventions
 
 The CLIC supports multiple nested interrupt handlers, and each handler
@@ -2209,7 +2347,8 @@ WARNING: This form cannot be used with CLINT mode,
 unless the original interrupt pending signal is cleared before
 re-enabling interrupts.
 
-== Calling C-ABI Functions as Interrupt Handlers
+[appendix]
+== Appendix : Calling C-ABI Functions as Interrupt Handlers
 
 An alternative model is where all interrupt handler routines use the
 standard C ABI.  In this case, the CLIC would use no hardware
@@ -2516,7 +2655,8 @@ pipeline model, `mret` adds an additional pipeline flush cycle, so the
 preemption latency is 20+5 cycles, which represents the worst-case for
 a preempting C-ABI interrupt handler.
 
-== Interrupt-Driven C-ABI Model
+[appendix]
+== Appendix : Interrupt-Driven C-ABI Model
 
 For many embedded systems, after initialization, essentially all code
 is run in response to an interrupt, interrupt levels are used to
@@ -2600,7 +2740,8 @@ SHV interrupts to preempt execution on the first instruction in
 This code does not increase worst-case interrupt latency over that of
 the C-ABI trampoline.
 
-== Alternate Interrupt Models for Software Vectoring
+[appendix]
+== Appendix : Alternate Interrupt Models for Software Vectoring
 
 Platforms may not implement the sclicshv extension, in which case, hardware vectoring can be emulated
 by a single software trampoline present at `NBASE` using the separate
@@ -2723,7 +2864,8 @@ handle_exc:
 This interrupt handler can be used together with the `wfi` sleep
 background routine shown above.
 
-== Managing Interrupt Stacks Across Privilege Modes
+[appendix]
+== Appendix : Managing Interrupt Stacks Across Privilege Modes
 
 Interrupt handlers need to have a place to save the previous context's
 state to provide working registers for the handler code.  If a handler
@@ -2911,133 +3053,6 @@ In all cases, conditionally swapping the stack to account for
 potential privilege-mode changes adds two extra instructions to all
 interrupt handlers.
 
-== Separating Stack per Interrupt Level
-
-Within a single privilege mode, it can be useful to separate interrupt
-handler tasks from application tasks to increase robustness, reduce
-space usage, and aid in system debugging.  Interrupt handler tasks
-have non-zero interrupt levels, while application tasks have an
-interrupt level of zero.
-
-
-
-== CLIC Interrupt ID ordering recommendations
-
-The specific numbering of interrupts is defined by the platform.  A
-platform definition will often be based on a specific RISC-V ISA
-profile, where RISC-V ISA profiles specify a common set of ISA choices
-that capture the most value for most users to enable software
-compatibility.
-
-Certain RISC-V profiles may include the CLIC as an option.
-
-Four different CLIC interrupt ID orderings are enumerated below for
-ease of reference in profile specifications.
-
-=== CLIC-mode interrupt-map for systems retaining interrupt ID compatible with CLINT mode:
-
-The CLINT-mode interrupts retain their interrupt ID in CLIC mode.
-The `clicintattr` settings are now used to delegate these interrupts as
-required.
-
-We recommend allocating an edge-triggered CLIC software interrupt bit
-(`csip`) with the lowest number (16) among the local interrupts to
-provide support for a local background interrupt thread, e.g. context
-switching.  By placing the `csip` interrupt at the lowest number among
-local interrupts, we avoid requiring another interrupt level to
-ensure this only runs when there are no other interrupts.
-
-The existing CLINT software interrupt bits are primarily intended for
-inter-hart interrupt signaling, and so are retained for that purpose.
-The software interrupts can have their priority changed using their
-`clicintctl` setting.
-
-CLIC interrupt inputs are allocated IDs beginning at interrupt ID 17.
-Any fast local interrupts that would have been connected at interrupt
-ID 16 and above should now be mapped into corresponding inputs of the
-CLIC.
-
-[source]
-----
-ID  Interrupt   Note
-
- 0  usip        User software Interrupt
- 1  ssip        Supervisor software Interrupt
- 2  reserved
- 3  msip        Machine software interrupt
-
- 4  utip        User timer interrupt
- 5  stip        Supervisor timer interrupt
- 6  reserved
- 7  mtip        Machine timer interrupt
-
- 8  ueip        User external (PLIC/APLIC) interrupt
- 9  seip        Supervisor external (PLIC/APLIC) interrupt
-10  reserved
-11  meip        Machine external (PLIC/APLIC) interrupt
-
-12  reserved
-13  reserved
-14  reserved
-15  reserved
-
-16  csip        CLIC software interrupt
-17+ inputs      CLIC local inputs
-----
-
-In CLINT mode, as stated in the RISC-V privilege specification, each
-individual bit in CSR register {ip} may be software writable or may be
-software read-only. When bit _i_ in {ip} is writable, a pending
-interrupt _i_ can be cleared by writing `0` to this bit. STIP is
-writable in `mip`, and may be written by M-mode software to deliver
-timer interrupts to S-mode.
-
-However, in CLIC mode, {ip} bits cannot be updated in software when
-they are in level-sensitive mode.  One possible equivalent
-implementation to deliver timer interrupts would be to hardwire the
-STIP input to 0 and then M-mode software can deliver timer interrupts to
-S-mode by setting `clicintattr[stip].trig` to `00`
-(positive-edge-triggered) and writing `clicintip[stip]` to `1`.
-
-The following optional recommendations remove unused interrupt inputs
-and compress the map to simplify hardware implementations.
-
-=== CLIC-mode interrupt-map recommendation for single-hart systems with PLIC/APLIC:
-
-[source]
-----
-ID  Interrupt
-0   S-mode software interrupt
-1   S-mode timer interrupt
-2   S-mode external (PLIC/APLIC) interrupt
-3   M-mode software interrupt
-4   M-mode timer interrupt
-5   M-mode external (PLIC/APLIC) interrupt
-6+  local
-----
-
-=== CLIC-mode interrupt-map recommendation for single-hart M/S/U systems without N-extension with no PLIC/APLIC:
-
-[source]
-----
-ID  Interrupt
-0   S-mode software interrupt
-1   S-mode timer interrupt
-2   M-mode software interrupt
-3   M-mode timer interrupt
-4+  other
-----
-
-=== CLIC-mode interrupt-map recommendation for single-hart M-mode only or M/U mode
-systems without N extension and no PLIC/APLIC:
-
-[source]
-----
-ID  Interrupt
-0   M-mode software interrupt
-1   M-mode timer interrupt
-2+  other
-----
 
 [[bibliography]]
 == Bibliography