Research note: Eclipse ThreadX

Kind: Read-only source analysis, 2026-10-07, on a sparse shallow clone of eclipse-threadx/threadx at commit 93387b0a6038 (common/, ports/cortex_m4/gnu, ports/cortex_m33/gnu, docs/). Version string “ThreadX Cortex-M4/GNU 6.5.2.202603” (ports/cortex_m4/gnu/inc/tx_port.h:706). Abbreviations: C = common/src, I = common/inc, M4 = ports/cortex_m4/gnu, M33 = ports/cortex_m33/gnu. The clone has no common_modules/, utility/, or tests. Line numbers drift; paths and symbols are the durable reference. Synthesized in R-001.

Q1 Scheduler

  • Priority 0 is highest; TX_MAX_PRIORITIES defaults to 32 and must be a multiple of 32 (M4/inc/tx_port.h:114; I/tx_api.h:2111). State: _tx_thread_priority_maps[TX_MAX_PRIORITIES/32] (I/tx_thread.h:333), _tx_thread_priority_map_active only above 32 (:341), the per-priority head array _tx_thread_priority_list[] (:377), cached _tx_thread_highest_priority (:369), _tx_thread_execute_ptr versus _tx_thread_current_ptr (:299, 306).

  • Highest ready is the lowest set bit: generic TX_LOWEST_SET_BIT_CALCULATE isolates m & (~m+1) then shifts (I/tx_thread.h:141-200); M4 overrides with RBIT plus CLZ (M4/inc/tx_port.h:518).

  • The ready list per priority is a self-linked circular doubly linked list: the first thread becomes the head pointing to itself (C/tx_thread_system_resume.c:189-196), later ones append at the tail (:383-387), the bit is OR’d (:209-210), highest and execute updated (:213-230). Suspend unlinks and clears the bit when empty, then recomputes highest from the maps, NULL execute when none (C/tx_thread_system_suspend.c:198-263, 311-331).

  • Round robin: per-thread tx_thread_time_slice and new_time_slice (I/tx_api.h:436-437) mirrored into the global _tx_timer_time_slice on switch (M4/src/tx_thread_schedule.S:173-184, 214-221); on expiry _tx_thread_time_slice rotates the head to ready_next only if priority equals threshold (“Preemption-threshold overrides time-slicing”, C/tx_thread_time_slice.c:116-128); relinquish does the same (C/tx_thread_relinquish.c:106-113).

  • Preemption threshold: tx_thread_preempt_threshold is at most the priority (I/tx_api.h:455; C/txe_thread_create.c:252). A newly ready thread displaces the execute thread only if priority < execute_ptr->tx_thread_preempt_threshold (resume.c:238). If a thread whose threshold differs from its priority is preempted, its priority bit is recorded in _tx_thread_preempted_maps (resume.c:244-259; I/tx_thread.h:353). When the running thread suspends, suspend.c:403-477 finds the lowest set preempted priority and, if _tx_thread_highest_priority >= that thread's threshold, re-selects the preempted thread instead of the highest ready one; interrupts are briefly re-enabled there “to keep the interrupt lockout time deterministic” (:412-424). Bits are cleared when the thread leaves the ready list (:226-231) or raises its threshold (C/tx_thread_preemption_change.c:167-212). Net effect: threads in [threshold, priority) cannot preempt, so fewer context switches; threshold 0 is a non-preemptible section. With TX_DISABLE_PREEMPTION_THRESHOLD any threshold collapses to 0 (:88-98).

  • _tx_thread_preempt_disable (I/tx_thread.h:384) is an internal counter; TX_THREAD_SYSTEM_RETURN_CHECK ORs it with system_state (:117); the Cortex-M port drops system_state from the check (M4/inc/tx_port.h:499). Non-zero also forbids blocking inside services (C/tx_queue_send.c:282 returns TX_QUEUE_FULL; C/tx_event_flags_get.c:269).

  • No idle thread: PendSV __tx_ts_wait spins with interrupts masked, optional WFI under TX_ENABLE_WFI and TX_LOW_POWER hooks (M4/src/tx_thread_schedule.S:251-296).

  • _tx_thread_system_state (I/tx_thread.h:325): 0xF0F0F0F0 during init (I/tx_initialize.h:48; C/tx_initialize_kernel_enter.c:99, 137), 0 is thread level; Cortex-M ORs IPSR for ISR detection (M4/inc/tx_port.h:478). TX_DISABLE and TX_RESTORE save PRIMASK and CPSID i, or BASEPRI with TX_PORT_USE_BASEPRI (M4/inc/tx_port.h:139, 564-600).

Q2 Context switch and interrupts

  • Cortex-M ISRs are ordinary handlers; _tx_thread_context_save and _restore are stubs that only call execution-profile hooks (“Context is already saved - just return”, M4/src/tx_thread_context_save.S:66-75; “only needed for legacy applications”, tx_thread_context_restore.S:46).

  • Rescheduling is setting ICSR.PENDSVSET: inline _tx_thread_system_return_inline (M4/inc/tx_port.h:578-600, 681); the assembly variant checks IPSR to skip the interrupt toggle when called from an ISR (M4/src/tx_thread_system_return.S:70-80). PendSV is lowest priority (M4/example_build/tx_initialize_low_level.S:127), so ISR-driven preemption is deferred until nesting unwinds.

  • PendSV body (schedule.S:121-245): save r4-r11, s16-s31 if EXC_RETURN bit 4 is clear, LR; PSP stored at TCB offset 8 (I/tx_api.h:432, assembly-fixed layout :425-442); run_count++ at offset 4 (:213-217); if execute is NULL go wait; __tx_ts_ready clears a redundant PendSV (:301-304).

  • Decision: _tx_thread_system_preempt_check (C/tx_thread_system_preempt_check.c:65-118): combined flags 0 and current differs from execute leads to system_return; services inline the same (resume.c:356-368). The tick ISR pends PendSV itself after a time slice if execute differs from current and preempt_disable is 0 (M4/src/tx_timer_interrupt.S:221-233).

  • Misuse rejection via TX_THREAD_GET_SYSTEM_STATE(): TX_WAIT_ERROR for blocking from an ISR, TX_CALLER_ERROR for ISR callers; the timer thread may not block (C/txe_mutex_get.c:111, 122-126, 146); tx_thread_sleep refuses when preempt is disabled (C/tx_thread_sleep.c:134).

  • tx_interrupt_control swaps PRIMASK or BASEPRI and returns the old posture (M4/src/tx_thread_interrupt_control.S:66-73); the trace build substitutes _tx_trace_interrupt_control (I/tx_api.h:1338-1341).

  • Low power and execution profile exist only as hooks (tx_low_power_enter and _exit, _tx_execution_*: schedule.S:33-35, 129-146, 223-228; C/tx_initialize_kernel_enter.c:144; TCB fields I/tx_api.h:578-581); implementations live in upstream utility/, absent here.

  • Initial frame: a 68-byte fake exception frame, EXC_RETURN 0xFFFFFFFD, xPSR T bit, poisoned LR (M4/src/tx_thread_stack_build.S:96-122). M33 uses 0xFFFFFFBC for the NS return (M33/src/tx_thread_stack_build.S:99-101).

Q3 Time

  • Timer wheel: _tx_timer_list[TX_TIMER_ENTRIES=32] of circular doubly linked TX_TIMER_INTERNAL lists (I/tx_timer.h:49, 95; struct I/tx_api.h:339-364 with remaining and reinit ticks, callback plus ULONG parameter, list_head back-pointer). _tx_timer_current_ptr advances one slot per tick with wrap (I/tx_timer.h:108; M4/src/tx_timer_interrupt.S:151-161).

  • Insertion at current + min(remaining, 32) - 1 (C/tx_timer_system_activate.c:100-119). Timers beyond 32 ticks are parked in the farthest slot; on “expiry” remaining -= 32 and they are re-queued without callback (C/tx_timer_thread_entry.c:184-215; “expiration adjust” performance counter).

  • The ISR does only: clock++, slice–, set _tx_timer_expired if the current slot is non-empty (tx_timer_interrupt.S:88-140); then _tx_timer_expiration_process resumes the system timer thread (C/tx_timer_expiration_process.c:120). With TX_TIMER_PROCESS_IN_ISR callbacks run inside the ISR guarded by _tx_timer_processing_active (:125-347, 146).

  • Timer thread “System Timer Thread”, priority TX_TIMER_THREAD_PRIORITY default 0, static stack (C/tx_timer_initialize.c:251-255; M4/inc/tx_port.h:134). Loop: detach the slot list, run callbacks with interrupts enabled (thread_entry.c:299), reload periodic timers from re_initialize_ticks (:264) and re-insert relative to the current slot (:408), self-suspend when nothing expired (:454). Because reinsertion is relative to the slot pointer at processing time, a late timer thread shifts subsequent periods (drift), not an absolute deadline.

  • Sleep: TX_SLEEP plus remaining_ticks (C/tx_thread_sleep.c:155, 176); system_suspend activates the TCB-embedded tx_thread_timer (I/tx_api.h:473; suspend.c:118-134) whose callback _tx_thread_timeout was bound at create (I/tx_thread.h:124-125); the timeout resumes a sleeper or calls the object cleanup (C/tx_thread_timeout.c:88, 149).

  • The tick is a 32-bit ULONG (I/tx_timer.h:77); tx_time_get reads it (C/tx_time_get.c:80); TX_WAIT_FOREVER is 0xFFFFFFFF and never enters the wheel (system_activate.c:88); 100 ticks per second by default (I/tx_api.h:272).

Q4 Blocking and waiting

  • The waiter list per object is a circular doubly linked list of TCBs (tx_thread_suspended_next and _previous, I/tx_api.h:481-483; for example tx_queue_suspension_list :952-954). A service stores tx_thread_suspend_cleanup, tx_thread_suspend_control_block, extra info, bumps tx_thread_suspension_sequence (I/tx_api.h:479-487, 585; C/tx_queue_send.c:302-314), sets the state code (I/tx_api.h:139-152), sets tx_thread_suspending, preempt_disable++, re-enables interrupts, then calls _tx_thread_system_suspend, which proceeds only if tx_thread_suspending is still TRUE (suspend.c:156). A resume that lands in that window clears the flag and the suspension evaporates (resume.c:401-431).

  • Timeout and wakeup race: cleanup functions re-validate cleanup pointer identity, sequence number, object id, and state before touching lists (C/tx_queue_cleanup.c:93-199; C/tx_mutex_cleanup.c:93, 176). Every waker nulls tx_thread_suspend_cleanup before resuming (tx_queue_send.c:221). Wait-abort reuses cleanup with TX_WAIT_ABORTED (C/tx_thread_wait_abort.c:113, 163).

  • Ordering is FIFO: new waiters append at the tail (tx_queue_send.c body; C/tx_mutex_get.c:240 region). Exceptions: tx_queue_front_send suspends at the head (C/tx_queue_front_send.c:317-342); explicit tx_*_prioritize moves the highest-priority waiter to the front (C/tx_mutex_prioritize.c:105-233, restarts if the list changed :167-177); a mutex put with TX_INHERIT calls prioritize automatically (C/tx_mutex_put.c:332-335, 587).

  • Delete with waiters resumes all with TX_DELETED (C/tx_queue_delete.c:153-154).

  • Event flags: AND or OR and clear options (C/tx_event_flags_get.c:121-245); tx_event_flags_group_delayed_clear defers clears while a set is walking the list (:245; I/tx_api.h:790); set nulls the head “to thwart manipulation” by ISRs, an ISR set marks reset_search to restart the walk (C/tx_event_flags_set.c:314, 583), satisfied threads are collected then resumed (:486). Event chaining is the tx_event_flags_set_notify callback (C/tx_event_flags_set_notify.c:92) invoked after every set (set.c:597); queue and semaphore have analogous *_send_notify and *_put_notify (I/tx_api.h:987, 1042).

  • No multi-object wait: the TCB holds exactly one cleanup and control-block pair (I/tx_api.h:479-480); notify callbacks forwarding into one event-flags group are the documented substitute.

Q5 Synchronization and priority inheritance

  • Mutex fields: recursive tx_mutex_ownership_count, owner, inherit flag, tx_mutex_highest_priority_waiting, owned_next and prev threaded into the owner’s tx_thread_owned_mutex_list (I/tx_api.h:857-888, 517-518); the TCB keeps tx_thread_user_priority, tx_thread_user_preempt_threshold, tx_thread_inherit_priority (:511-513).

  • Get: free leads to own and link (C/tx_mutex_get.c:159); re-get increments the count (:175). Contended with TX_INHERIT: record the highest waiter (:352), lower the owner’s inherit_priority (:360), raise the owner via _tx_mutex_priority_change (:369), which rewrites priority and threshold for a non-ready owner or suspend-plus-resumes a ready one to relocate it (C/tx_mutex_priority_change.c:97-105, 186, 215) and fixes the preempted map and execute pointer (:274).

  • Not transitive: only the direct owner is raised; if that owner is itself blocked on another mutex, nothing walks the chain (no loop in tx_mutex_get.c).

  • Put (C/tx_mutex_put.c): owner check skipped when preempt_disable is set (:139); when the count reaches 0 and inherit, scan all owned mutexes for the maximum highest_priority_waiting to get the new inherit_priority (:253-295), restore priority (:382 no waiters; :552 and 619 after prioritize :332-335 and 587 hands ownership to the highest waiter).

  • Owner death: _tx_thread_mutex_release (I/tx_thread.h:390) installed by C/tx_mutex_create.c:93 leads to _tx_mutex_thread_release, which forces count to 1 and puts every owned mutex (C/tx_mutex_cleanup.c:251-280); called on completion (C/tx_thread_shell_entry.c:118) and terminate (C/tx_thread_terminate.c:281).

  • Semaphore ceiling put returns TX_CEILING_EXCEEDED when the count is at or above the ceiling and nobody waits (C/tx_semaphore_ceiling_put.c:121).

Q6 IPC and memory

  • Queues: 1 to 16 ULONG messages (I/tx_api.h:109-113, 279), unrolled word copy TX_QUEUE_MESSAGE_COPY (I/tx_queue.h:83-94), ring start, end, read, write (I/tx_api.h:942-948); if a receiver waits, the message is copied straight into its buffer (C/tx_queue_send.c:222-227); front_send steps the read pointer backwards; a send-notify callback (:170).

  • Block pool: a singly linked free list, header word rewritten to point at the pool when allocated (C/tx_block_allocate.c:160), suspends with cleanup when empty (:238).

  • Byte pool: first-fit (C/tx_byte_pool_search.c:162) over an implicit list of [next][FREE 0xFFFFEEEE or pool pointer] headers (I/tx_byte_pool.h:51; minimum split 20 bytes :55); a rotating search pointer set to the first free block seen (:145), adjacent free blocks coalesced lazily during search (:182), split when the remainder is at least the minimum (:272), early reject by theoretical availability (:99). The search runs with interrupts periodically enabled; tx_byte_pool_owner detects preemption and restarts (:253; allocate retry loop C/tx_byte_allocate.c:150-171). Release moves the search pointer back (C/tx_byte_release.c:200). Fragmentation is possible; no size classes.

  • Static model: every control block and stack is caller memory; public structs expose the full layout (I/tx_api.h:423-599); the kernel allocates nothing, only passes _tx_initialize_unused_memory to tx_application_define (C/tx_initialize_kernel_enter.c:133). The only exception: M33 secure stacks use malloc (M33/src/tx_thread_secure_stack.c:253).

Q7 Isolation

  • Modules: sources absent; README.md:15, 28 lists common_modules and ports_modules and :105-106 describes dynamically loaded modules in one paragraph. No MPU code in the base kernel.

  • M33 TrustZone: the NS kernel calls secure CMSE entry functions (M33/src/tx_thread_secure_stack.c:103, 200, 347, 452, 545) that manage a fixed table of TX_MAX_SECURE_CONTEXTS=32 (:49); secure stacks of 256 to 1024 bytes are malloc’d with seal 0xFEF5EDA5 (:36, 40, 45, 253); index+1 kept in the TCB extension tx_thread_secure_stack_context (M33/inc/tx_port.h:240, 251), read by assembly at offset 0x90 (M33/src/tx_thread_schedule.S:162); PendSV calls save and restore which load and zero PSP_S and PSPLIM_S (:166, 235; secure_stack.c:126, 495). NS requests go through SVC 1, 2, 3 (M33/src/tx_thread_secure_stack_allocate.S:73; SVC_Handler schedule.S:334-358). The timer thread gets a 256-byte secure stack (tx_port.h:310-311); freed at delete (:302).

  • PSPLIM: the scheduler loads PSPLIM from tx_thread_stack_start before restoring (schedule.S:242); the UsageFault handler checks STKOF and calls _tx_thread_stack_error_handler (M33/example_build/tx_initialize_low_level.S:199-221; TX_PORT_THREAD_STACK_ERROR_HANDLING tx_port.h:134). M4 has no hardware limit.

  • Software stack checking: fill 0xEFEFEFEF or random (I/tx_api.h:131-133; C/tx_thread_create.c:106, 123), guard words at both ends checked on every suspend, resume, and slice (I/tx_thread.h:210-236), binary-search high-water (C/tx_thread_stack_analyze.c:116-132), application handler (C/tx_thread_stack_error_handler.c:80); minimum stack 200 (M4/inc/tx_port.h:122).

Q8 Observability

  • TraceX: one caller buffer with header, object registry, and a circular event ring (I/tx_trace.h:30-40; header :74; registry entry with 32-character name :93, 106-115; event: thread pointer, priority with threshold<<16, id, timestamp, 4 info words :242-257). TX_TRACE_IN_LINE_INSERT is inlined into every service (:295-329); wrap-around invokes the buffer-full callback (:493-499; C/tx_trace_buffer_full_notify.c:75); class filter bits (C/tx_trace_event_filter.c:72); registry slots reused by object pointer (C/tx_trace_object_register.c:123-125); enable registers all live objects (C/tx_trace_enable.c:235). Scheduling code patches the “next thread” field after the decision if the timestamp is unchanged (resume.c:325-338). The M4 timestamp is DWT CYCCNT at 0xE0001004 (M4/inc/tx_port.h:161). ISR enter and exit events are application-inserted.

  • Performance info: global and per-TCB counters (I/tx_thread.h:439-515 including an 8-entry execute log; I/tx_api.h:520-555), read via C/tx_thread_performance_info_get.c:79+; tx_thread_info_get returns user priority and threshold, run count (incremented in PendSV schedule.S:213-217), created and suspended-list neighbours (C/tx_thread_info_get.c:122-150).

  • Error layer: 68 txe_* shells; tx_api.h maps names to _txe_ by default, _tx_ under TX_DISABLE_ERROR_CHECKING, _txr_ under TX_ENABLE_MULTI_ERROR_CHECKING (I/tx_api.h:1057-1065, 1191). Shells check NULL, id magic (C/txe_mutex_get.c:92), caller context (:111, 146), control-block size via a sizeof macro (I/tx_api.h:1266, 1377; C/txe_thread_create.c:116), stack overlap against all created threads (:166-182), minimum stack (:232). Internals never call txe.

Q9 Configuration, portability, quality

  • tx_user.h via TX_INCLUDE_USER_DEFINE_FILE; I/tx_user_sample.h:89-302 enumerates options, :55-76 gives “max speed” and “min size” recipes (TX_NOT_INTERRUPTABLE selects _ni_ variants, resume.c:533-615; TX_INLINE_THREAD_RESUME_SUSPEND, TX_TIMER_PROCESS_IN_ISR, TX_REACTIVATE_INLINE, TX_NO_TIMER, TX_DISABLE_NOTIFY_CALLBACKS). _tx_build_options records the build (I/tx_thread.h:393-426). TX_SAFETY_CRITICAL forbids disabling error checks, ISR timers, inline reactivation, stack checking (I/tx_api.h:2103-2140) and raises an exception if the scheduler ever returns (:2221-2222; C/tx_initialize_kernel_enter.c:150-153).

  • Port contract: tx_port.h supplies types, TX_MAX_PRIORITIES, TX_MINIMUM_STACK, timer-thread defaults, TX_DISABLE, TX_RESTORE, TX_SAVE_AREA, TX_THREAD_GET_SYSTEM_STATE, optional TX_LOWEST_SET_BIT_CALCULATE, object *_EXTENSION and create, delete, completed, terminated hooks (M4/inc/tx_port.h:216-400), TX_PORT_SPECIFIC_* init hooks (I/tx_initialize.h); assembly: schedule, stack_build, system_return, context_save and restore, interrupt_control, disable, restore, timer_interrupt, plus the example low_level (M4/src file list). TCB words 0 to 9 are assembly-fixed (I/tx_api.h:425-442).

  • MISRA: TX_MISRA_ENABLE routes casts, memset, pointer math, and message copy through 70 assembly shims (M4/src/tx_misra.S:131-237; C fallback C/tx_misra.c:50-121); the revision history records “modified code for MISRA compliance” across files (docs/revision_history.txt:39-270). File headers carry component, release, author only (C/tx_mutex_get.c:35-44).

  • Certification: no IEC 61508 or ISO 26262 text in the repository; only CONTRIBUTING.md:7 “safety-certified OS” and “safety critical exception logic” (revision_history.txt:350-460). Supporting artifacts: the TX_SAFETY_CRITICAL gate, the MISRA shims, the txe layer.

  • Tests: none in the clone; README.md:31 points to utility/ “Test cases and utilities”; CMakeLists.txt:27-32 enables ctest for port example builds; build-all.log and ctest-all.log are artifacts only.

Ideas to borrow

  1. Preemption threshold with the preempted-map bookkeeping (resume.c:238-259; suspend.c:403-477): a cheap bounded-preemption band that doubles as a non-preemptible section.

  2. Suspension sequence number plus cleanup-pointer identity checks to make timeout, wakeup, and abort races idempotent (I/tx_api.h:585; tx_queue_cleanup.c:93-199).

  3. A timer wheel with lazy “more than 32 ticks” re-queue plus processing in a dedicated thread with interrupts enabled around callbacks (thread_entry.c:184-299).

  4. The txe, tx, txr name mapping: a zero-cost removable validation layer, with sizeof(control block) passed by macro to catch ABI mismatches (I/tx_api.h:1057-1065, 1266).

  5. Event chaining via per-object notify callbacks as a lightweight multi-source wait (set.c:597).

  6. An inline trace macro with post-hoc “next thread” patching and per-class filters (I/tx_trace.h:295-329; resume.c:325-338).

  7. The byte-pool “owner token” to allow interrupt windows inside a long search (tx_byte_pool_search.c:253).

  8. The TX_SAFETY_CRITICAL compile-time gate rejecting unsafe option combinations (I/tx_api.h:2103-2140).

Weaknesses

  1. Public control-block layouts are the ABI; assembly hard-codes TCB offsets (I/tx_api.h:425-442; schedule.S:174, 213; M33 schedule.S:162 offset 0x90), and tx_thread_create must pass sizeof(TX_THREAD) to detect drift (txe_thread_create.c:116).

  2. FIFO-only waiter order by default; priority order requires explicit *_prioritize calls or TX_INHERIT mutexes (tx_mutex_prioritize.c; tx_queue_send.c tail append).

  3. Priority inheritance is single-level, not transitive (tx_mutex_get.c:360-369 touches only the direct owner).

  4. No multi-object wait; notify callbacks run in the setter’s context and are one per object (I/tx_api.h:479-480, 987).

  5. The timer wheel is a 32-slot circular array: long timers are re-queued every 32 ticks and periodic reload is relative to processing time, so a delayed timer thread drifts (thread_entry.c:184-215, 408).

  6. The timer thread runs at priority 0 and all callbacks share one stack and priority; TX_TIMER_PROCESS_IN_ISR moves callbacks into the ISR (expiration_process.c:125-347).

  7. Isolation is thin in the base kernel: no MPU, Modules absent here, M33 secure stacks rely on malloc and a fixed 32-context table (secure_stack.c:49, 253).

  8. The byte pool is first-fit with lazy coalescing and no free list; worst-case search is O(fragments) under interrupt windows (tx_byte_pool_search.c:99-272).

  9. Idle is a busy loop unless TX_ENABLE_WFI or TX_LOW_POWER is defined (schedule.S:251-296); low-power and execution-profile code are external hooks only.

  10. Certification and MISRA claims are not substantiated inside the repository (no test suite, no certificate artifacts; CONTRIBUTING.md:7 only).