Summary
Several ARMv7-A source files carry pseudo-code comments that describe a stack switch to _tx_thread_system_stack_ptr which the code does not perform, and never has. The comments are leftovers from an older generic port template. They are actively misleading: they have prompted at least one user to try to "restore" the missing code (#240), and they suggest a variable that is not even referenced by these ports.
Background
On ARMv7-A every processor mode has its own banked stack pointer. IRQ_Handler branches to _tx_thread_context_save while still in IRQ mode, so the ISR already runs on the per-core banked IRQ stack, and _tx_thread_context_restore switches to SVC mode only when preemption is required. No software stack switch is needed or wanted.
By contrast, the AArch64 (ARMv8-A) SMP ports do not bank a stack pointer per mode, so they keep _tx_thread_system_stack_ptr[] as a real array and reload it explicitly. In those ports the comments are accurate and must be left alone.
Scope
Comment-only changes. No functional change, no behavioural risk.
| Tree |
Files |
Offending text |
ports_smp/cortex_a5_smp, cortex_a7_smp, cortex_a9_smp, cortex_r8_smp |
21 |
sp = _tx_thread_system_stack_ptr; / sp = _tx_thread_system_stack_ptr[core]; in tx_thread_context_save, tx_thread_vectored_context_save and tx_thread_system_return |
ports/ and ports_arch/ARMv7-A/threadx (non-SMP ARMv7-A and Cortex-R) |
89 |
/* Save current stack and switch to system stack. */ in tx_thread_system_return, where no switch occurs |
Explicitly out of scope: every ports_smp/cortex_a3x_smp through cortex_a78_smp, cortex_a5x_smp, arc_hs_smp and mips32_interaptiv_smp file, plus ports_arch/ARMv8-A. Those comments match the code.
Proposed change
Replace the misleading lines with a short statement of what actually happens, for example:
- in the context save routines, note that the routine runs in IRQ mode on the per-core banked IRQ stack, which serves as the system stack on this architecture;
- in
tx_thread_system_return, replace "Save current stack and switch to system stack" with "Save the current stack pointer in the thread control block", which is all the following instruction does.
Notes for the implementer
ports_arch/ARMv7-A/threadx is the source of truth for the non-SMP ARMv7-A ports. Edit it first, then propagate with ports_arch/ARMv7-A/update.sh, and confirm the generated trees match.
- There is no
ports_arch source tree for the ARMv7-A SMP ports; those 21 files must be edited directly, and the ac5 and gnu variants of each port must stay in sync.
- Run
scripts/check_ports.sh afterwards. It requires a clean working tree and contains hard-coded literal strings in its divergence probe, so check whether any of them cover the text being changed.
- Keep the surrounding comment box formatting and column alignment intact.
Acceptance criteria
Follows up on #240.
Summary
Several ARMv7-A source files carry pseudo-code comments that describe a stack switch to
_tx_thread_system_stack_ptrwhich the code does not perform, and never has. The comments are leftovers from an older generic port template. They are actively misleading: they have prompted at least one user to try to "restore" the missing code (#240), and they suggest a variable that is not even referenced by these ports.Background
On ARMv7-A every processor mode has its own banked stack pointer.
IRQ_Handlerbranches to_tx_thread_context_savewhile still in IRQ mode, so the ISR already runs on the per-core banked IRQ stack, and_tx_thread_context_restoreswitches to SVC mode only when preemption is required. No software stack switch is needed or wanted.By contrast, the AArch64 (ARMv8-A) SMP ports do not bank a stack pointer per mode, so they keep
_tx_thread_system_stack_ptr[]as a real array and reload it explicitly. In those ports the comments are accurate and must be left alone.Scope
Comment-only changes. No functional change, no behavioural risk.
ports_smp/cortex_a5_smp,cortex_a7_smp,cortex_a9_smp,cortex_r8_smpsp = _tx_thread_system_stack_ptr;/sp = _tx_thread_system_stack_ptr[core];intx_thread_context_save,tx_thread_vectored_context_saveandtx_thread_system_returnports/andports_arch/ARMv7-A/threadx(non-SMP ARMv7-A and Cortex-R)/* Save current stack and switch to system stack. */intx_thread_system_return, where no switch occursExplicitly out of scope: every
ports_smp/cortex_a3x_smpthroughcortex_a78_smp,cortex_a5x_smp,arc_hs_smpandmips32_interaptiv_smpfile, plusports_arch/ARMv8-A. Those comments match the code.Proposed change
Replace the misleading lines with a short statement of what actually happens, for example:
tx_thread_system_return, replace "Save current stack and switch to system stack" with "Save the current stack pointer in the thread control block", which is all the following instruction does.Notes for the implementer
ports_arch/ARMv7-A/threadxis the source of truth for the non-SMP ARMv7-A ports. Edit it first, then propagate withports_arch/ARMv7-A/update.sh, and confirm the generated trees match.ports_archsource tree for the ARMv7-A SMP ports; those 21 files must be edited directly, and theac5andgnuvariants of each port must stay in sync.scripts/check_ports.shafterwards. It requires a clean working tree and contains hard-coded literal strings in its divergence probe, so check whether any of them cover the text being changed.Acceptance criteria
_tx_thread_system_stack_ptrin pseudo-code unless the adjacent instructions actually reference it.scripts/check_ports.shreports no new divergence.txandsmpregression suites still pass.Follows up on #240.