Skip to content

Remove the stale system stack switch pseudo-code comments from the ARMv7-A ports #734

Description

@fdesbiens

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

  • No ARMv7-A file mentions _tx_thread_system_stack_ptr in pseudo-code unless the adjacent instructions actually reference it.
  • The ARMv8-A, ARC and MIPS SMP ports are untouched.
  • scripts/check_ports.sh reports no new divergence.
  • The full tx and smp regression suites still pass.

Follows up on #240.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions