/*************************************************************************** * Copyright (c) 2026 Eclipse ThreadX contributors * * This program and the accompanying materials are made available under the * terms of the MIT License which is available at * https://opensource.org/licenses/MIT. * * AI Disclosure: This file was largely AI-generated by Claude Code (Opus 5). * The AI-generated portions may be considered public domain (CC0-1.0) * and not subject to the project's licence. The human contributor has * reviewed and verified that the code is correct. * * SPDX-License-Identifier: MIT and CC0-1.0 **************************************************************************/ /**************************************************************************/ /**************************************************************************/ /** */ /** ThreadX Test */ /** */ /** Thread lifecycle transition configuration coverage */ /** */ /**************************************************************************/ /**************************************************************************/ /* The two configurations that matter to this change and that neither regression tree builds are TX_NOT_INTERRUPTABLE and TX_DISABLE_ERROR_CHECKING. This executable is built once for each combination of them, against the four sources that change, and drives the completion and termination transitions directly. Why each one needs its own build rather than a case in the in-tree test: - TX_NOT_INTERRUPTABLE selects a different transition. There the exit notification callback runs with interrupts still disabled and the interruptable suspension path -- which is what sets and clears the transition marker in the configurations the trees do build -- is not used at all, so the marker is set and cleared by explicit stores that exist only in this configuration. A marker left set there would make a normally completed thread permanently undeletable, which is the failure mode worth more than a compile. - TX_DISABLE_ERROR_CHECKING removes the _txe_ wrappers, so the public names bind straight to the core services. The refusal has to live in the core services for exactly that reason, and the way to demonstrate it is to call the public names in a build that has no wrappers. The scheduler is not linked. _tx_thread_system_ni_suspend and _tx_thread_system_suspend are recorders, which is what makes the marker's value at the moment of detachment directly observable -- and, in the TX_NOT_INTERRUPTABLE completion path, the reason the marker has to be cleared before the call rather than after it: on a real port that call returns to the scheduler and never comes back. Everything here is straight-line: there are no threads, no timers and no waits, so there is nothing that can hang. */ #include #include /* tx_api.h is included without TX_SOURCE_CODE, so that the public service names are mapped the way an application sees them: to the _txe_ wrappers with error checking on, and straight to the core services with it off. Letting the header make that choice is the point -- the refusal has to survive the choice. Only then is TX_SOURCE_CODE defined, for the internal declarations the recorders below implement. */ #include "tx_api.h" /* tx_thread_entry_exit_notify is both a service name and a TX_THREAD field name, and it is the only name in this file that is both, so the mapping above would rewrite the field assignment further down into a member that does not exist. Dropping just that one mapping keeps the mapping that matters -- the one on the three services this test calls -- while leaving the field reachable. The test never calls the notify service; it plants the callback in the control block directly, because the create path that would otherwise do it is not linked. */ #undef tx_thread_entry_exit_notify #define TX_SOURCE_CODE #include "tx_thread.h" /* Counters the force-included port shim's macros drive. */ unsigned int test_interrupt_disable_depth = 0; unsigned int test_interrupt_disable_max_depth = 0; unsigned int test_interrupt_restore_underflows = 0; unsigned int test_delete_port_completion_count = 0; unsigned int test_reset_port_completion_count = 0; #define TEST_STACK_BYTES 512 static TX_THREAD victim; static TX_THREAD other; static UCHAR victim_stack[TEST_STACK_BYTES]; /* What the recorders saw. */ static unsigned int ni_suspend_calls = 0; static UINT ni_suspend_suspending = 0xFFFFFFFFU; static UINT ni_suspend_state = 0xFFFFFFFFU; static unsigned int ni_suspend_depth = 0xFFFFFFFFU; static unsigned int suspend_calls = 0; static UINT suspend_suspending = 0xFFFFFFFFU; static unsigned int stack_build_calls = 0; static unsigned int preempt_check_calls = 0; static unsigned int timer_deactivate_calls = 0; /* What the exit callback saw. */ static unsigned int callback_calls = 0; static UINT callback_state = 0xFFFFFFFFU; static UINT callback_suspending = 0xFFFFFFFFU; static unsigned int callback_depth = 0xFFFFFFFFU; static UINT callback_delete_status = 0xFFFFFFFFU; static UINT callback_reset_status = 0xFFFFFFFFU; static UINT callback_delete_completions = 0xFFFFFFFFU; static UINT callback_reset_completions = 0xFFFFFFFFU; static unsigned int entry_calls = 0; static unsigned long expectations_checked = 0; static unsigned long expectations_failed = 0; static void expect(int condition, const char *what) { expectations_checked++; if (condition == 0) { expectations_failed++; printf(" FAILED: %s\n", what); } } static void expect_uint(UINT actual, UINT wanted, const char *what) { expectations_checked++; if (actual != wanted) { expectations_failed++; printf(" FAILED: %s (got %lu, wanted %lu)\n", what, (unsigned long) actual, (unsigned long) wanted); } } /* ------------------------------------------------------------------------ */ /* Recorders standing in for the scheduler. */ /* ------------------------------------------------------------------------ */ VOID _tx_thread_system_ni_suspend(TX_THREAD *thread_ptr, ULONG wait_option) { (void) wait_option; ni_suspend_calls++; ni_suspend_suspending = thread_ptr -> tx_thread_suspending; ni_suspend_state = thread_ptr -> tx_thread_state; ni_suspend_depth = test_interrupt_disable_depth; } VOID _tx_thread_system_suspend(TX_THREAD *thread_ptr) { suspend_calls++; suspend_suspending = thread_ptr -> tx_thread_suspending; /* The interruptable suspension path is where the marker is cleared in the configurations the regression trees build, so the recorder clears it as the real one does, on the same condition. */ if (thread_ptr -> tx_thread_suspending == TX_TRUE) { thread_ptr -> tx_thread_suspending = TX_FALSE; } /* It also decrements the preemption disable count, which its callers have raised on its behalf. The recorder has to do the same, or the balance this test asserts across the whole transition would be off by one for a reason that belongs to the recorder rather than to the code under test. */ _tx_thread_preempt_disable--; } VOID _tx_thread_stack_build(TX_THREAD *thread_ptr, VOID (*function_ptr)(VOID)) { (void) thread_ptr; (void) function_ptr; stack_build_calls++; } VOID _tx_thread_system_preempt_check(VOID) { preempt_check_calls++; } /* _tx_thread_terminate deactivates the target's timeout timer, and _txe_thread_reset refuses a call made from the timer thread. Neither the timer component nor the timer thread is linked, so both are supplied here: the deactivation as a recorder, and the timer thread as a control block that is never the current thread, so the wrapper's check is exercised and takes the not-the-timer-thread branch. */ VOID _tx_timer_system_deactivate(TX_TIMER_INTERNAL *timer_ptr) { (void) timer_ptr; timer_deactivate_calls++; } TX_THREAD _tx_timer_thread; /* ------------------------------------------------------------------------ */ /* The thread under test. */ /* ------------------------------------------------------------------------ */ static void reset_records(void) { ni_suspend_calls = 0; ni_suspend_suspending = 0xFFFFFFFFU; ni_suspend_state = 0xFFFFFFFFU; ni_suspend_depth = 0xFFFFFFFFU; suspend_calls = 0; suspend_suspending = 0xFFFFFFFFU; stack_build_calls = 0; preempt_check_calls = 0; timer_deactivate_calls = 0; callback_calls = 0; callback_state = 0xFFFFFFFFU; callback_suspending = 0xFFFFFFFFU; callback_depth = 0xFFFFFFFFU; callback_delete_status = 0xFFFFFFFFU; callback_reset_status = 0xFFFFFFFFU; callback_delete_completions = 0xFFFFFFFFU; callback_reset_completions = 0xFFFFFFFFU; entry_calls = 0; test_interrupt_disable_depth = 0; test_interrupt_disable_max_depth = 0; test_interrupt_restore_underflows = 0; test_delete_port_completion_count = 0; test_reset_port_completion_count = 0; } static VOID victim_entry(ULONG input) { (void) input; entry_calls++; } static VOID exit_notify(TX_THREAD *thread_ptr, UINT type) { if (type != TX_THREAD_EXIT) { return; } callback_calls++; callback_state = thread_ptr -> tx_thread_state; callback_suspending = thread_ptr -> tx_thread_suspending; callback_depth = test_interrupt_disable_depth; /* The public names. With error checking on these are the _txe_ wrappers; with it off they are the core services. Either way the refusal has to come back. */ callback_delete_status = tx_thread_delete(thread_ptr); callback_reset_status = tx_thread_reset(thread_ptr); /* A refused delete or reset must not have run the port's completion processing, which on a real port tears the thread's port resources down. */ callback_delete_completions = test_delete_port_completion_count; callback_reset_completions = test_reset_port_completion_count; } /* Put the victim's control block into the shape the kernel would have left it in after tx_thread_create, for the fields the four sources under test read. tx_thread_create itself is not linked, because the scheduler it resumes into is not linked either. */ static void make_victim(UINT state) { memset(&victim, 0, sizeof(victim)); memset(victim_stack, 0xEF, sizeof(victim_stack)); victim.tx_thread_id = TX_THREAD_ID; victim.tx_thread_state = state; victim.tx_thread_suspending = TX_FALSE; victim.tx_thread_entry = victim_entry; victim.tx_thread_entry_parameter = 0; #ifndef TX_DISABLE_NOTIFY_CALLBACKS /* The field itself does not exist when notification is compiled out. */ victim.tx_thread_entry_exit_notify = exit_notify; #endif victim.tx_thread_stack_start = victim_stack; victim.tx_thread_stack_size = sizeof(victim_stack); victim.tx_thread_priority = 16; victim.tx_thread_preempt_threshold = 16; victim.tx_thread_suspend_cleanup = TX_NULL; /* A created list with the victim and one other thread on it, so that delete takes the link-up-the-neighbours branch rather than the only-thread branch. */ memset(&other, 0, sizeof(other)); other.tx_thread_id = TX_THREAD_ID; other.tx_thread_state = TX_SUSPENDED; other.tx_thread_created_next = &victim; other.tx_thread_created_previous = &victim; victim.tx_thread_created_next = &other; victim.tx_thread_created_previous = &other; _tx_thread_created_ptr = &victim; _tx_thread_created_count = 2; _tx_thread_current_ptr = &victim; _tx_thread_execute_ptr = &victim; _tx_thread_preempt_disable = 0; _tx_thread_system_state = 0; } static void scenario_completion(void) { printf("Completion transition:\n"); reset_records(); make_victim(TX_SUSPENDED); /* _tx_thread_shell_entry picks the thread up from the current pointer, calls its entry function, and then runs the completion transition. */ _tx_thread_shell_entry(); expect_uint((UINT) entry_calls, 1, "the entry function ran exactly once"); #ifndef TX_DISABLE_NOTIFY_CALLBACKS expect_uint((UINT) callback_calls, 1, "the exit callback ran exactly once"); /* The terminal state is published before the callback. */ expect_uint(callback_state, TX_COMPLETED, "the callback saw TX_COMPLETED"); /* And the transition is marked while the callback runs, in this configuration as in the interruptable one. */ expect_uint(callback_suspending, TX_TRUE, "the callback saw the transition marked"); #ifdef TX_NOT_INTERRUPTABLE /* In this configuration the callback runs inside the interrupt lock. */ expect(callback_depth > 0, "the callback ran with interrupts disabled"); #else expect_uint((UINT) callback_depth, 0, "the callback ran with interrupts enabled"); #endif /* The two refusals, from whichever of the wrapper and the core service this build binds the public name to. */ expect_uint(callback_delete_status, TX_DELETE_ERROR, "the callback's delete was refused"); expect_uint(callback_reset_status, TX_NOT_DONE, "the callback's reset was refused"); /* A refused delete or reset ran no port completion processing. */ expect_uint(callback_delete_completions, 0, "the refused delete ran no port completion"); expect_uint(callback_reset_completions, 0, "the refused reset ran no port completion"); #endif /* The detachment saw the marker in the state that keeps the thread deletable afterwards. This is the failure mode the configuration exists to catch: on a real port the suspension call below returns to the scheduler and does not come back, so a marker cleared after it rather than before it would stay set for ever and the completed thread could never be deleted. */ #ifdef TX_NOT_INTERRUPTABLE expect_uint((UINT) ni_suspend_calls, 1, "the non-interruptable suspension ran once"); expect_uint(ni_suspend_state, TX_COMPLETED, "it was entered with the terminal state"); expect_uint(ni_suspend_suspending, TX_FALSE, "the marker was already cleared when the suspension was entered"); expect(ni_suspend_depth > 0, "the suspension was entered with interrupts disabled"); expect_uint((UINT) suspend_calls, 0, "the interruptable suspension was not used"); #else expect_uint((UINT) suspend_calls, 1, "the interruptable suspension ran once"); expect_uint(suspend_suspending, TX_TRUE, "the marker was still set when the suspension was entered, for it to clear"); expect_uint((UINT) ni_suspend_calls, 0, "the non-interruptable suspension was not used"); #endif /* Either way the thread is deletable once the transition has finished. */ expect_uint(victim.tx_thread_suspending, TX_FALSE, "the marker is clear afterwards"); expect_uint(tx_thread_delete(&victim), TX_SUCCESS, "the completed thread deletes afterwards"); expect_uint((UINT) test_delete_port_completion_count, 1, "the successful delete ran the port completion once"); /* And the interrupt lock is balanced across the whole transition. */ expect_uint((UINT) test_interrupt_disable_depth, 0, "the interrupt lock is balanced"); expect_uint((UINT) test_interrupt_restore_underflows, 0, "no unmatched interrupt restore"); } static void scenario_terminate_ready(void) { printf("Termination of a ready thread:\n"); reset_records(); make_victim(TX_READY); /* Terminate a target that is not the current thread, so that the reset the callback attempts is refused by the transition check alone rather than by the current-thread rule. */ _tx_thread_current_ptr = &other; expect_uint(tx_thread_terminate(&victim), TX_SUCCESS, "the termination succeeded"); #ifndef TX_DISABLE_NOTIFY_CALLBACKS expect_uint((UINT) callback_calls, 1, "the exit callback ran exactly once"); expect_uint(callback_state, TX_TERMINATED, "the callback saw TX_TERMINATED"); expect_uint(callback_suspending, TX_TRUE, "the callback saw the transition marked"); expect_uint(callback_delete_status, TX_DELETE_ERROR, "the callback's delete was refused"); expect_uint(callback_reset_status, TX_NOT_DONE, "the callback's reset was refused"); expect_uint(callback_reset_completions, 0, "the refused reset ran no port completion"); expect_uint((UINT) stack_build_calls, 0, "the refused reset rebuilt no stack"); #endif #ifdef TX_NOT_INTERRUPTABLE expect_uint((UINT) ni_suspend_calls, 1, "the non-interruptable suspension ran once"); expect(callback_depth > 0, "the callback ran with interrupts disabled"); #else expect_uint((UINT) suspend_calls, 1, "the interruptable suspension ran once"); #endif /* The marker is cleared in the common tail, after the callback and after the mutex-release processing. */ expect_uint(victim.tx_thread_suspending, TX_FALSE, "the marker is clear afterwards"); expect_uint(victim.tx_thread_state, TX_TERMINATED, "the state is terminal afterwards"); expect_uint((UINT) _tx_thread_preempt_disable, 0, "the preempt disable count is balanced"); expect_uint((UINT) test_interrupt_disable_depth, 0, "the interrupt lock is balanced"); expect_uint((UINT) test_interrupt_restore_underflows, 0, "no unmatched interrupt restore"); expect_uint(tx_thread_delete(&victim), TX_SUCCESS, "the terminated thread deletes afterwards"); } static void scenario_terminate_suspended(void) { UINT reset_status; printf("Termination of a suspended thread:\n"); reset_records(); make_victim(TX_SUSPENDED); _tx_thread_current_ptr = &other; expect_uint(tx_thread_terminate(&victim), TX_SUCCESS, "the termination succeeded"); #ifndef TX_DISABLE_NOTIFY_CALLBACKS expect_uint((UINT) callback_calls, 1, "the exit callback ran exactly once"); expect_uint(callback_state, TX_TERMINATED, "the callback saw TX_TERMINATED"); /* The non-ready branch used to clear the marker before this point. */ expect_uint(callback_suspending, TX_TRUE, "the callback saw the transition marked"); expect_uint(callback_delete_status, TX_DELETE_ERROR, "the callback's delete was refused"); expect_uint(callback_reset_status, TX_NOT_DONE, "the callback's reset was refused"); expect_uint((UINT) stack_build_calls, 0, "the refused reset rebuilt no stack"); #endif /* This branch never calls a suspension routine: the thread was already off the ready list. */ expect_uint((UINT) ni_suspend_calls, 0, "no non-interruptable suspension on this branch"); expect_uint((UINT) suspend_calls, 0, "no interruptable suspension on this branch"); expect_uint(victim.tx_thread_suspending, TX_FALSE, "the marker is clear afterwards"); expect_uint((UINT) _tx_thread_preempt_disable, 0, "the preempt disable count is balanced"); expect_uint((UINT) test_interrupt_disable_depth, 0, "the interrupt lock is balanced"); expect_uint((UINT) test_interrupt_restore_underflows, 0, "no unmatched interrupt restore"); /* The documented lifecycle is available afterwards, on this branch too. */ reset_status = tx_thread_reset(&victim); expect_uint(reset_status, TX_SUCCESS, "the terminated thread resets afterwards"); expect_uint(victim.tx_thread_state, TX_SUSPENDED, "the reset left it suspended"); expect_uint((UINT) stack_build_calls, 1, "the successful reset rebuilt the stack once"); expect_uint((UINT) test_reset_port_completion_count, 1, "the successful reset ran the port completion once"); expect_uint(tx_thread_delete(&victim), TX_DELETE_ERROR, "a reset thread is not deletable"); expect_uint(tx_thread_terminate(&victim), TX_SUCCESS, "it terminates again"); expect_uint(tx_thread_delete(&victim), TX_SUCCESS, "and then deletes"); } static void scenario_marker_not_set_outside_transition(void) { printf("Outside a transition:\n"); reset_records(); make_victim(TX_SUSPENDED); _tx_thread_current_ptr = &other; /* Neither state is terminal, so both services refuse for the reason they always did, and the marker plays no part. */ expect_uint(victim.tx_thread_suspending, TX_FALSE, "the marker is clear on a live thread"); expect_uint(tx_thread_delete(&victim), TX_DELETE_ERROR, "delete refuses a suspended thread"); expect_uint(tx_thread_reset(&victim), TX_NOT_DONE, "reset refuses a suspended thread"); /* A terminal state with the marker clear is the ordinary deletable case, which is what the refusal must not have broken. */ victim.tx_thread_state = TX_COMPLETED; victim.tx_thread_suspending = TX_FALSE; expect_uint(tx_thread_reset(&victim), TX_SUCCESS, "reset accepts a settled completed thread"); victim.tx_thread_state = TX_TERMINATED; expect_uint(tx_thread_delete(&victim), TX_SUCCESS, "delete accepts a settled terminated thread"); /* And a terminal state with the marker set is the new refusal, tested directly rather than through a transition, so that both services are covered on both terminal states. */ make_victim(TX_COMPLETED); victim.tx_thread_suspending = TX_TRUE; _tx_thread_current_ptr = &other; expect_uint(tx_thread_delete(&victim), TX_DELETE_ERROR, "delete refuses a marked completed thread"); expect_uint(tx_thread_reset(&victim), TX_NOT_DONE, "reset refuses a marked completed thread"); victim.tx_thread_state = TX_TERMINATED; expect_uint(tx_thread_delete(&victim), TX_DELETE_ERROR, "delete refuses a marked terminated thread"); expect_uint(tx_thread_reset(&victim), TX_NOT_DONE, "reset refuses a marked terminated thread"); /* Clearing the marker makes both available again, which is the whole claim about the refusal being transient. */ victim.tx_thread_suspending = TX_FALSE; expect_uint(tx_thread_reset(&victim), TX_SUCCESS, "clearing the marker restores reset"); victim.tx_thread_state = TX_TERMINATED; expect_uint(tx_thread_delete(&victim), TX_SUCCESS, "clearing the marker restores delete"); } int main(void) { printf("Thread lifecycle transition configuration test: "); #ifdef TX_NOT_INTERRUPTABLE printf("TX_NOT_INTERRUPTABLE "); #else printf("interruptable "); #endif #ifdef TX_DISABLE_ERROR_CHECKING printf("TX_DISABLE_ERROR_CHECKING "); #else printf("error checking "); #endif #ifdef TX_DISABLE_NOTIFY_CALLBACKS printf("TX_DISABLE_NOTIFY_CALLBACKS"); #else printf("notify callbacks"); #endif printf("\n"); scenario_completion(); scenario_terminate_ready(); scenario_terminate_suspended(); scenario_marker_not_set_outside_transition(); printf("%lu of %lu expectations passed.\n", expectations_checked - expectations_failed, expectations_checked); if (expectations_failed != 0) { printf("FAILED: %lu expectations.\n", expectations_failed); return(1); } printf("SUCCESS!\n"); return(0); }