cleanup: address RISC-V32 QEMU demo review feedback

Rework PR #513 according to reviewer feedback while keeping the QEMU
virt demo and GP relaxation pieces:

- Restore the RISC-V32 GNU port src/inc baseline to upstream style,
  removing the tx_port.h-based assembly macro abstraction.
- Revert the demo thread_2 priority back to (16, 16) and keep
  preemption verification in the Python runner instead of encoding it
  in demo priorities.
- Document the QEMU entry stub, linker layout, x3/gp initialization,
  and __global_pointer$ placement used by GP relaxation.
- Drop the tx_port.h dependency from the QEMU low-level init assembly.
- Move kernel.elf and check-functional-riscv32 CMake wiring out of the
  root CMakeLists.txt and into the RISC-V32 GNU port example_build tree.
- Document why -mrelax requires matching runtime gp setup and linker
  script support.

Author: Winstonllllai

CMakeLists.txt

@@ -69,49 +69,4 @@ set(CPACK_SOURCE_IGNORE_FILES
   ".*~$"
 )
 set(CPACK_VERBATIM_VARIABLES YES)
-include(CPack)
-
-# Enable the QEMU Virt demo application (Target: kernel.elf)
-set(QEMU_DEMO_DIR ${CMAKE_CURRENT_LIST_DIR}/ports/risc-v32/gnu/example_build/qemu_virt)
-
-add_executable(kernel.elf 
-    ${QEMU_DEMO_DIR}/demo_threadx.c
-    ${QEMU_DEMO_DIR}/entry.s
-    ${QEMU_DEMO_DIR}/uart.c
-    ${QEMU_DEMO_DIR}/plic.c
-    ${QEMU_DEMO_DIR}/hwtimer.c
-    ${QEMU_DEMO_DIR}/trap.c
-    ${QEMU_DEMO_DIR}/board.c
-    ${QEMU_DEMO_DIR}/tx_initialize_low_level.S
-)
-
-target_link_libraries(kernel.elf PRIVATE threadx)
-
-target_include_directories(kernel.elf PRIVATE 
-    ${CMAKE_CURRENT_LIST_DIR}/common/inc 
-    ${CMAKE_CURRENT_LIST_DIR}/ports/${THREADX_ARCH}/${THREADX_TOOLCHAIN}/inc
-    ${QEMU_DEMO_DIR}
-)
-
-# Linker options
-target_link_options(kernel.elf PRIVATE 
-    -T${QEMU_DEMO_DIR}/link.lds 
-    -nostartfiles
-    -Wl,-Map=kernel.map
-)
-
-# QEMU Test Runner Target
-find_package(Python3 COMPONENTS Interpreter)
-if(Python3_FOUND)
-    add_custom_target(check-functional-riscv32
-        COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_LIST_DIR}/test/ports/azrtos_test_tx_gnu_riscv32_qemu.py 
-            --elf $<TARGET_FILE:kernel.elf>
-            --qemu qemu-system-riscv32
-            --gdb gdb
-        DEPENDS kernel.elf
-        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
-        COMMENT "Running QEMU/GDB Test Runner..."
-    )
-else()
-    message(WARNING "Python3 not found, run_qemu_test target will not be available.")
-endif()
+include(CPack)

cmake/riscv32_gnu.cmake

@@ -4,6 +4,13 @@ set(CMAKE_SYSTEM_PROCESSOR risc-v32)
 
 set(THREADX_ARCH "risc-v32")
 set(THREADX_TOOLCHAIN "gnu")
+# -mrelax enables linker relaxation, in particular GP-relative
+# addressing for symbols within +/- 2 KiB of __global_pointer$ (small
+# data window). This requires the runtime to load the global pointer
+# explicitly under .option norelax (see entry.s in the QEMU virt demo)
+# and the linker script to PROVIDE __global_pointer$ centred in the
+# small-data window (see link.lds). Without those two pieces in place
+# -mrelax produces broken GP-relative loads on bare-metal targets.
 set(ARCH_FLAGS "-g -march=rv32gc -mabi=ilp32d -mcmodel=medany -mrelax")
 set(CFLAGS "${ARCH_FLAGS}")
 set(ASFLAGS "${ARCH_FLAGS}")

ports/risc-v32/gnu/CMakeLists.txt

@@ -17,3 +17,11 @@ target_include_directories(${PROJECT_NAME}
     PUBLIC
     ${CMAKE_CURRENT_LIST_DIR}/inc
 )
+
+# Optional: pull in the QEMU virt demo if its CMakeLists is present.
+# kernel.elf is EXCLUDE_FROM_ALL inside, so the default build is
+# unaffected; consumers opt in via `--target kernel.elf` or
+# `--target check-functional-riscv32`.
+if(EXISTS ${CMAKE_CURRENT_LIST_DIR}/example_build/qemu_virt/CMakeLists.txt)
+    add_subdirectory(${CMAKE_CURRENT_LIST_DIR}/example_build/qemu_virt)
+endif()

ports/risc-v32/gnu/example_build/qemu_virt/CMakeLists.txt

@@ -0,0 +1,61 @@
+# ThreadX RISC-V32 GNU port: QEMU virt demo build.
+#
+# This subdirectory is opted-in by ports/risc-v32/gnu/CMakeLists.txt when
+# the consumer is building the threadx library for the risc-v32/gnu port.
+#
+# kernel.elf is marked EXCLUDE_FROM_ALL so that:
+#   - The default `cmake --build .` (which builds the threadx library
+#     and any tests the consumer wires up) is unaffected by the demo.
+#   - Users who explicitly want the demo can `cmake --build .
+#     --target kernel.elf` or `cmake --build . --target
+#     check-functional-riscv32` to also drive the QEMU/GDB test runner.
+#
+# This avoids touching the root CMakeLists.txt while still keeping the
+# build-system entry point for the demo discoverable next to the demo
+# sources themselves.
+
+set(QEMU_DEMO_DIR ${CMAKE_CURRENT_LIST_DIR})
+
+add_executable(kernel.elf EXCLUDE_FROM_ALL
+    ${QEMU_DEMO_DIR}/demo_threadx.c
+    ${QEMU_DEMO_DIR}/entry.s
+    ${QEMU_DEMO_DIR}/uart.c
+    ${QEMU_DEMO_DIR}/plic.c
+    ${QEMU_DEMO_DIR}/hwtimer.c
+    ${QEMU_DEMO_DIR}/trap.c
+    ${QEMU_DEMO_DIR}/board.c
+    ${QEMU_DEMO_DIR}/tx_initialize_low_level.S
+)
+
+target_link_libraries(kernel.elf PRIVATE threadx)
+
+target_include_directories(kernel.elf PRIVATE
+    ${CMAKE_SOURCE_DIR}/common/inc
+    ${CMAKE_SOURCE_DIR}/ports/${THREADX_ARCH}/${THREADX_TOOLCHAIN}/inc
+    ${QEMU_DEMO_DIR}
+)
+
+target_link_options(kernel.elf PRIVATE
+    -T${QEMU_DEMO_DIR}/link.lds
+    -nostartfiles
+    -Wl,-Map=kernel.map
+)
+
+# QEMU/GDB functional test runner.  Optional: skipped silently if the
+# host has no Python 3 interpreter on PATH.
+find_package(Python3 COMPONENTS Interpreter)
+if(Python3_FOUND)
+    add_custom_target(check-functional-riscv32
+        COMMAND ${Python3_EXECUTABLE}
+            ${QEMU_DEMO_DIR}/test/azrtos_test_tx_gnu_riscv32_qemu.py
+            --elf $<TARGET_FILE:kernel.elf>
+            --qemu qemu-system-riscv32
+            --gdb gdb
+        DEPENDS kernel.elf
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Running RISC-V32 QEMU/GDB functional test runner..."
+    )
+else()
+    message(STATUS
+        "Python3 not found; check-functional-riscv32 target unavailable.")
+endif()

ports/risc-v32/gnu/example_build/qemu_virt/demo_threadx.c

@@ -10,6 +10,9 @@
 #define     DEMO_BLOCK_POOL_SIZE    100
 #define     DEMO_QUEUE_SIZE         100
 
+/* Shared FPU register exercised by thread_6/7 to validate FP context save/restore.  */
+float           fpu_test_val = 0.0f;
+
 char *_to_str(ULONG val)
 {
     static char buf[11];     /* 10 digits max + '\0' */
@@ -112,7 +115,7 @@ void    tx_application_define(void *first_unused_memory)
 
     tx_thread_create(&thread_2, "thread 2", thread_2_entry, 2,
             pointer, DEMO_STACK_SIZE,
-            10, 10, 4, TX_AUTO_START);
+            16, 16, 4, TX_AUTO_START);
 
     /* Allocate the stack for thread 3.  */
     tx_byte_allocate(&byte_pool_0, (VOID **) &pointer, DEMO_STACK_SIZE, TX_NO_WAIT);
@@ -337,8 +340,6 @@ ULONG   actual_flags;
     }
 }
 
-float   fpu_test_val = 0.0f;
-
 void    thread_6_and_7_entry(ULONG thread_input)
 {
 

ports/risc-v32/gnu/example_build/qemu_virt/entry.s

@@ -1,3 +1,30 @@
+/**************************************************************************/
+/*                                                                        */
+/*       Copyright (c) Microsoft Corporation. All rights reserved.        */
+/*                                                                        */
+/*       This software is licensed under the Microsoft Software License   */
+/*       Terms for Microsoft Azure RTOS. Full text of the license can be  */
+/*       found in the LICENSE file at https://aka.ms/AzureRTOS_EULA       */
+/*       and in the root directory of this software.                      */
+/*                                                                        */
+/**************************************************************************/
+
+/*
+ *  ThreadX RISC-V32 GNU port: QEMU virt machine reset/entry stub.
+ *
+ *  Linked at the load address of the QEMU `virt` machine (see link.lds).
+ *  Placed in the .init section so the linker keeps it at the very start
+ *  of the image regardless of file ordering during link, matching the
+ *  PC value QEMU uses on reset.
+ *
+ *  Responsibilities:
+ *    1. Park secondary harts on `wfi` (single-hart bring-up only; SMP TBD).
+ *    2. Zero the integer register file on the boot hart, including x3
+ *       (the global pointer) which we load explicitly with the linker
+ *       symbol `__global_pointer$` below, with relaxation disabled so
+ *       the `la gp, ...` itself is not subject to GP-relative rewriting.
+ *    3. Set up the system stack and clear .bss before calling main().
+ */
 
 .section .init
 .align 4
@@ -9,11 +36,13 @@
 _start:
 	csrr t0, mhartid
 	bne  t0, zero, 1f
+
+	/* Zero general purpose registers (x3/gp handled by the la below). */
 	li x1, 0
 	li x2, 0
 .option push
 .option norelax
-	la gp, __global_pointer$
+	la gp, __global_pointer$        /* x3 = gp; norelax keeps this load absolute */
 .option pop
 	li x4, 0
 	li x5, 0
@@ -43,19 +72,24 @@ _start:
 	li x29, 0
 	li x30, 0
 	li x31, 0
-	la t0, _sysstack_start
-	li t1, 0x1000
+
+	/* Set up the system stack: top-of-stack = _sysstack_start + 0x1000. */
+	la  t0, _sysstack_start
+	li  t1, 0x1000
 	add sp, t0, t1
+
+	/* Clear .bss [_bss_start, _bss_end). */
 	la  t0, _bss_start
 	la  t1, _bss_end
 _bss_clean_start:
 	bgeu t0, t1, _bss_clean_end
-	sb zero, 0(t0)
+	sb   zero, 0(t0)
 	addi t0, t0, 1
-	j _bss_clean_start
+	j    _bss_clean_start
 _bss_clean_end:
 	call main
+
 1:
-	/* todo smp */
+	/* Secondary harts: park here. SMP bring-up is not yet supported. */
 	wfi
 	j 1b

ports/risc-v32/gnu/example_build/qemu_virt/link.lds

@@ -1,14 +1,31 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the Microsoft Software License Terms for Microsoft
+ * Azure RTOS. Full text of the license can be found in the LICENSE
+ * file at https://aka.ms/AzureRTOS_EULA.
+ *
+ * ThreadX RISC-V32 GNU port: linker script for the QEMU `virt` machine.
+ *
+ *   - Image base 0x80000000 matches the PC QEMU sets when launched with
+ *     `-machine virt -kernel kernel.elf` (DRAM start on this machine).
+ *   - .init is placed first so entry.s / _start is the very first
+ *     instruction the CPU executes after reset.
+ *   - __global_pointer$ is provided at the start of .data + 0x800 so
+ *     that GP-relative loads/stores reach symbols in [GP-0x800, GP+0x7FF],
+ *     the standard small-data window that `-mrelax` uses (see entry.s
+ *     for the matching `la gp, __global_pointer$` initialization).
+ *   - A 4 KiB system stack is reserved after .bss, with _sysstack_start
+ *     consumed by entry.s as the boot stack base.
+ */
+
 OUTPUT_ARCH( "riscv" )
 ENTRY( _start )
 
 SECTIONS
 {
-  /*
-   * ensure that entry.S / _entry is at 0x80000000,
-   * where qemu's -kernel jumps.
-   */
+  /* QEMU virt: -kernel jumps to 0x80000000 (DRAM start). */
   . = 0x80000000;
-  
+
   .init : {
     KEEP (*(.init))
   }
@@ -28,6 +45,8 @@ SECTIONS
 
   .data : {
     . = ALIGN(16);
+    /* Centre __global_pointer$ in the small-data window so the +/-2 KiB
+       reach of GP-relative addressing covers the .sdata/.sbss area. */
     PROVIDE( __global_pointer$ = . + 0x800 );
     *(.sdata .sdata.*) /* do not need to distinguish this from .data */
     . = ALIGN(16);
@@ -36,7 +55,7 @@ SECTIONS
 
   .bss : {
     . = ALIGN(16);
-    _bss_start = .;
+    _bss_start = .;        /* consumed by entry.s for .bss zero-init */
     *(.sbss .sbss.*) /* do not need to distinguish this from .bss */
     . = ALIGN(16);
     *(.bss .bss.*)
@@ -45,8 +64,8 @@ SECTIONS
 
   .stack : {
     . = ALIGN(4096);
-    _sysstack_start = .;
-    . += 0x1000;
+    _sysstack_start = .;   /* boot stack base used by entry.s */
+    . += 0x1000;           /* 4 KiB system stack */
     _sysstack_end = .;
   }