application: document RVV vector interrupt stack behavior and increase SMODE_STACK_SIZE

When compiled with RVV (e.g. -march=rv64imafdcv), __INTERRUPT or
__SUPERVISOR_INTERRUPT decorated vector interrupt handlers save context
on the current stack, NOT on the separated interrupt stack. For non-leaf
handlers (calling other functions), all 32 vector registers (v0-v31, each
vlenb bytes) are saved, consuming significant stack space (e.g. 512B for
VLEN=128, 16KB for VLEN=4096). For leaf handlers, only actually-used V
registers are saved, or none if no V instructions are used.

The compiler also saves all caller-saved GPR + FP registers + FCSR, plus
any callee-saved registers actually used by the handler (e.g. s0 as frame
base for non-leaf handlers using SAVE_IRQ_CSR_CONTEXT_S()).

Changes:
- Add comments in demo_eclic_stress, demo_sstc, and demo_smode_eclic
  explaining vector interrupt stack behavior, leaf vs non-leaf handler
  differences, and the risk of stack overflow with large vlen
- Increase SMODE_STACK_SIZE from 10240 to 20480 in demo_eclic_stress
- Increase SMODE_STACK_SIZE from 2048 to 20480 in demo_sstc
- Increase SMODE_STACK_SIZE from 2048 to 20480 in demo_smode_eclic
- Add corresponding notes in doc/source/design/app.rst for all three demos
- Update changelog.rst with the above changes

Signed-off-by: Huaqi Fang <578567190@qq.com>

Author: fanghuaqi

application/baremetal/demo_eclic_stress/main.c

@@ -204,6 +204,39 @@ uintptr_t mmode_int_sp = (uintptr_t)(mmode_int_stack + sizeof(mmode_int_stack));
 uint8_t smode_int_stack[INTERRUPT_STACK_SIZE] __attribute__((aligned(16)));
 uintptr_t smode_int_sp = (uintptr_t)(smode_int_stack + sizeof(smode_int_stack));
 
+/*
+ * NOTE: Vector interrupts decorated with __INTERRUPT or __SUPERVISOR_INTERRUPT
+ * are handled by compiler-generated prologue/epilogue code. Context saving
+ * (including the extra
+ * RVV vector registers when compiled with e.g. -march=rv64imafdcv) happens on
+ * the current stack, NOT on the separated interrupt stack (mmode_int_stack /
+ * smode_int_stack above). The separated interrupt stack only applies to
+ * non-vector interrupts.
+ *
+ * In M-Mode or S-Mode, vector interrupts therefore run on the background
+ * task's stack (main's stack or RTOS task stack for M-Mode; smode_stack for
+ * S-Mode), which must be large enough to accommodate the full context frame.
+ * See the disassembly of eclic_int37_handler (S-mode vector interrupt) for
+ * reference:
+ *   - All caller-saved GPR + FP registers + FCSR + callee-saved
+ *     registers used by the handler (e.g. s0 as frame base): ~304 bytes
+ *     (ra, t0-t6, a0-a7, ft0-ft11, fa0-fa7, fcsr; may include s0 if used)
+ *   - Vector registers (RVV only):
+ *     - Non-leaf interrupt handlers (e.g. eclic_int37_handler which calls
+ *       printf): ALL v0-v31 saved, 32 * vlenb bytes (e.g. 512B for VLEN=128,
+ *       2048B for VLEN=512)
+ *     - Leaf interrupt handlers: only registers actually used by the handler
+ *       body, or none if no V instructions are used
+ *   Note: scause/sepc/sstatus are NOT part of the compiler-generated context
+ *   frame. They are saved manually in the handler body via
+ *   SAVE_IRQ_CSR_CONTEXT_S() or equivalent code, and use additional local
+ *   stack space.
+ *
+ * WARNING: For non-leaf interrupt handlers compiled with RVV, the vector
+ * context alone can consume up to 32 * vlenb bytes (e.g. 16KB for VLEN=4096).
+ * Ensure the stack size is sufficient to avoid stack overflow, especially in
+ * RTOS tasks where stack sizes are typically limited.
+ */
 /* Create a stack for supervisor mode execution */
 #define SMODE_STACK_SIZE            20480
 uint8_t smode_stack[SMODE_STACK_SIZE] __attribute__((aligned(16)));

application/baremetal/demo_smode_eclic/demo_smode_eclic.c

@@ -26,8 +26,29 @@
 // 100ms
 #define TIMER_TICKS             (SOC_TIMER_FREQ / 10)
 
-// 2048 is enough
-#define SMODE_STACK_SIZE        2048
+/*
+ * NOTE: Vector interrupts decorated with __INTERRUPT or __SUPERVISOR_INTERRUPT
+ * are handled by compiler-generated prologue/epilogue code. When compiled with
+ * RVV (e.g. -march=rv64imafdcv), the compiler may additionally save vector
+ * registers (v0-v31, each taking vlenb bytes) on the current stack.
+ * Vector interrupts do NOT use the separated interrupt stack; they run on the
+ * background task's stack (here smode_stack for S-Mode, or the main/task
+ * stack for M-Mode vector interrupts).
+ *
+ * For non-leaf interrupt handlers (e.g. eclic_ssip_handler which calls
+ * printf), the compiler saves all caller-saved GPR + FP registers + FCSR
+ * (e.g. ra, t0-t6, a0-a7, ft0-ft11, fa0-fa7, fcsr) plus any callee-saved
+ * registers actually used by the handler (e.g. s0 as frame base). For non-
+ * leaf handlers, ALL v0-v31 are also saved (32 * vlenb bytes). For leaf
+ * handlers, only actually-used registers are saved, or none at all if no V
+ * instructions are used in the handler body.
+ *
+ * WARNING: For non-leaf interrupt handlers compiled with RVV, the vector
+ * context alone can consume up to 32 * vlenb bytes (e.g. 16KB for VLEN=4096).
+ * Ensure the stack size is sufficient to avoid stack overflow, especially in
+ * RTOS tasks where stack sizes are typically limited.
+ */
+#define SMODE_STACK_SIZE        20480
 
 // Execute Hart ID
 #define EXECUTE_HARTID          0

application/baremetal/demo_sstc/main.c

@@ -29,8 +29,33 @@
 // 100ms
 #define TIMER_TICKS             (SOC_TIMER_FREQ / 10)
 
-// 4096 is enough
-#define SMODE_STACK_SIZE        4096
+/*
+ * NOTE: Vector interrupts decorated with __INTERRUPT or __SUPERVISOR_INTERRUPT
+ * are handled by compiler-generated prologue/epilogue code
+ * (e.g. eclic_ssip_handler here).
+ * When compiled with RVV (e.g. -march=rv64imafdcv), the compiler may
+ * additionally save vector registers (v0-v31, each taking vlenb bytes) on
+ * the current stack.
+ * Vector interrupts do NOT use the separated interrupt stack; they run on the
+ * background task's stack (here smode_stack for S-Mode, or the main/task
+ * stack for M-Mode vector interrupts).
+ * Non-vector interrupts (e.g. eclic_stip_handler registered as
+ * ECLIC_NON_VECTOR_INTERRUPT) use the separated interrupt stack instead.
+ *
+ * For non-leaf interrupt handlers (e.g. eclic_ssip_handler which calls
+ * printf), the compiler saves all caller-saved GPR + FP registers + FCSR
+ * (e.g. ra, t0-t6, a0-a7, ft0-ft11, fa0-fa7, fcsr) plus any callee-saved
+ * registers actually used by the handler (e.g. s0 as frame base). For non-
+ * leaf handlers, ALL v0-v31 are also saved (32 * vlenb bytes). For leaf
+ * handlers, only actually-used registers are saved, or none at all if no V
+ * instructions are used in the handler body.
+ *
+ * WARNING: For non-leaf interrupt handlers compiled with RVV, the vector
+ * context alone can consume up to 32 * vlenb bytes (e.g. 16KB for VLEN=4096).
+ * Ensure the stack size is sufficient to avoid stack overflow, especially in
+ * RTOS tasks where stack sizes are typically limited.
+ */
+#define SMODE_STACK_SIZE        20480
 
 /* Create a stack for supervisor mode execution */
 uint8_t smode_stack[SMODE_STACK_SIZE] __attribute__((aligned(16)));

doc/source/changelog.rst

@@ -96,6 +96,9 @@ This is release version of ``0.9.0`` of Nuclei SDK.
   - Update ``demo_eclic_stress`` application to use ``__SMODE_PRESENT`` instead of ``__TEE_PRESENT`` and update npk.yml to remove TEE requirement
   - Update ``demo_smode_eclic`` application to use ``__SMODE_PRESENT`` instead of ``__TEE_PRESENT`` and add ``XLCFG_SMODE`` configuration variable
   - Update ``demo_sstc`` application to use ``__SMODE_PRESENT`` instead of ``__TEE_PRESENT`` and remove TEE requirement
+  - Add comments in ``demo_eclic_stress`` to document that ``__INTERRUPT`` vector interrupts save RVV context on the background stack, not on the separated interrupt stack, and increase ``SMODE_STACK_SIZE`` from 10240 to 20480 to accommodate RVV vector register saving overhead
+  - Add comments in ``demo_sstc`` to document RVV vector interrupt stack behavior and increase ``SMODE_STACK_SIZE`` from 2048 to 20480 to accommodate RVV vector register saving overhead
+  - Add comments in ``demo_smode_eclic`` to document RVV vector interrupt stack behavior and increase ``SMODE_STACK_SIZE`` from 2048 to 20480 to accommodate RVV vector register saving overhead
   - Update ``demo_smode_plic`` application to add ``XLCFG_PLIC`` configuration variable
   - Update ``demo_plic`` application to add ``XLCFG_PLIC`` configuration variable
   - Update ``demo_cidu`` application to add ``XLCFG_CIDU`` configuration variable

doc/source/design/app.rst

@@ -581,6 +581,7 @@ This `demo_eclic_stress application`_ is used to validate the functionality of t
 
     - This demo requires ECLIC, System Timer, and optional TEE (Trusted Execution Environment) and SSTC extension to be present. When TEE and SSTC is present, both M-Mode and S-Mode interrupts are tested. When TEE is not present, only M-Mode interrupts are tested.
     - It can also work with ECLICv2, see :ref:`design_soc_evalsoc_eclicv2`
+    - **Vector interrupt stack behavior**: When compiled with RVV (e.g. ``-march=rv64imafdcv``), `__INTERRUPT` decorated vector interrupt handlers save context on the current stack, NOT on the separated interrupt stack. For non-leaf handlers (which call other functions), the compiler saves all caller-saved GPR + FP registers + FCSR plus any callee-saved registers actually used, and ALL 32 vector registers (v0-v31, each `vlenb` bytes) are also saved (e.g. 512B for VLEN=128, 16KB for VLEN=4096). For leaf handlers, only actually-used registers are saved. In M-Mode or S-Mode, vector interrupts run on the background task stack (main stack for M-Mode, `SMODE_STACK_SIZE` for S-Mode), which must be large enough to accommodate the context.
 
 **How to run this application:**
 
@@ -1701,6 +1702,7 @@ the ECLIC API and Interrupt in supervisor mode with TEE.
     * In this application's Makefile, we provided comments in Makefile about optimization
       for code size, please refer to chapter :ref:`design_app_demo_eclic` for details.
     * Need to enable TEE in <Device.h> if TEE present in CPU.
+    * **Vector interrupt stack behavior**: When compiled with RVV, `__INTERRUPT` or `__SUPERVISOR_INTERRUPT` decorated vector interrupt handlers save context on the current stack, NOT on the separated interrupt stack. For non-leaf handlers, the compiler saves all caller-saved GPR + FP registers + FCSR plus any callee-saved registers actually used, and ALL 32 vector registers are also saved (32 * `vlenb` bytes). For leaf handlers, only actually-used registers are saved. Ensure the background stack (`SMODE_STACK_SIZE`) is large enough to accommodate vector context.
 
 * The timer interrupt and timer software interrupt are used
 * The timer interrupt is registered as non-vector interrupt
@@ -1913,6 +1915,7 @@ This demo is similar with :ref:`design_app_demo_smode_eclic`
 
     * It doesn't work with gd32vf103 processor.
     * It needs Nuclei CPU configured with TEE feature and S-Mode ECLIC and SSTC feature
+    * **Vector interrupt stack behavior**: When compiled with RVV, `__INTERRUPT` decorated vector interrupt handlers (e.g. `eclic_ssip_handler`) save context on the current stack, NOT on the separated interrupt stack. For non-leaf handlers, the compiler saves all caller-saved GPR + FP registers + FCSR plus any callee-saved registers actually used, and ALL 32 vector registers are also saved (32 * `vlenb` bytes). For leaf handlers, only actually-used registers are saved. Non-vector interrupts (e.g. `eclic_stip_handler`) use the separated interrupt stack. In S-Mode, vector interrupts run on `smode_stack`; in M-Mode, they run on the main/task stack. Ensure the background stack is large enough to accommodate vector context.
 
 **How to run this application:**