diff options
Diffstat (limited to 'test/freertos/regression/txfr_test_harness.h')
| -rw-r--r-- | test/freertos/regression/txfr_test_harness.h | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/test/freertos/regression/txfr_test_harness.h b/test/freertos/regression/txfr_test_harness.h new file mode 100644 index 00000000..ffb6db0e --- /dev/null +++ b/test/freertos/regression/txfr_test_harness.h @@ -0,0 +1,103 @@ +/*************************************************************************** + * 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 Component */ +/** */ +/** FreeRTOS compatibility layer test harness */ +/** */ +/**************************************************************************/ + +/* This harness lets a test force a ThreadX object creation call to fail and + then account for what the compatibility layer did with the resources it had + already taken. The creation entry points of the layer take a byte pool + allocation for the descriptor, sometimes a second one for backing storage, + and then create one or more kernel objects; an error path that forgets to + undo any of that is invisible to the caller, which only ever sees NULL. + + Interception is done with the linker's --wrap option rather than with hooks + in the layer itself, so tx_freertos.c is compiled exactly as it ships. Note + that tx_api.h maps the public API onto the error checking entry points, so + the symbols that exist at link time, and therefore the ones wrapped, are the + _txe_ variants. The wrap options live in the test CMakeLists. + + This mechanism is specific to GNU ld and lld, so the suite is Linux only. */ + +#ifndef TXFR_TEST_HARNESS_H +#define TXFR_TEST_HARNESS_H + +#include "FreeRTOS.h" + +/* Identifies the kernel creation call a test wants to fail. */ +typedef enum TXFR_INJECT_TARGET_ENUM +{ + TXFR_INJECT_NONE = 0, + TXFR_INJECT_SEMAPHORE_CREATE, + TXFR_INJECT_MUTEX_CREATE, + TXFR_INJECT_EVENT_FLAGS_CREATE, + TXFR_INJECT_TIMER_CREATE, + TXFR_INJECT_THREAD_CREATE, + TXFR_INJECT_THREAD_RESUME +} TXFR_INJECT_TARGET; + +/* Counts of the ThreadX primitives the layer reached for while accounting was + active. The byte pool counts stand in for txfr_malloc() and txfr_free(), + which cannot be wrapped: they are defined in tx_freertos.c and called from + within it, so the compiler resolves those calls internally. */ +typedef struct TXFR_COUNTERS_STRUCT +{ + int byte_allocate; + int byte_release; + int semaphore_create; + int semaphore_delete; + int mutex_create; + int mutex_delete; + int event_flags_create; + int event_flags_delete; + int timer_create; + int timer_delete; + int thread_create; + int thread_delete; + + /* Counted, but not part of the object totals checked below, since a + resume creates nothing. */ + int thread_resume; +} TXFR_COUNTERS; + +/* Start accounting. Pass TXFR_INJECT_NONE to only count, or a target together + with the 1 based index of the call to fail, counted from this call onward. */ +void txfr_test_account_start(TXFR_INJECT_TARGET target, int fail_on_call); + +/* Stop accounting and copy out what was counted. */ +void txfr_test_account_stop(TXFR_COUNTERS *p_counters); + +/* Record the outcome of one expectation. Prints a line per check and remembers + whether anything failed. */ +void txfr_test_check(const char *label, int condition); + +/* As above, with the observed and expected counts printed on a failure. */ +void txfr_test_check_counts(const char *label, const TXFR_COUNTERS *p_counters, + int expect_allocate, int expect_release, + int expect_object_create, int expect_object_delete); + +/* Number of failed checks so far. */ +int txfr_test_failures(void); + +/* Each test file defines this. It runs in thread context, since the byte pool + operations under test are not callable from initialization. */ +void txfr_test_body(void); + +#endif /* TXFR_TEST_HARNESS_H */ |