path: root/test/tx/cmake/module_qemu/src/harness.c

/***************************************************************************
 * 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.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                                                          */
/**                                                                       */
/**   Module execution harness: manager side                              */
/**                                                                       */
/**************************************************************************/
/**************************************************************************/

/* The part of every manager image that is not the test: startup into ThreadX,
   the Module Manager's memory, the fault notification, and reporting.

   Output and exit go through Arm semihosting rather than the board's UART, so
   the same image reports identically on any QEMU machine with semihosting
   enabled, and the simulation's exit status carries the verdict as well as the
   result line the runner matches.  Semihosting is only ever called from the
   privileged manager thread or from a fault handler, never from a module.

   MISRA C:2023 deviations, confined to this test scaffolding: Rule 1.2 and
   Directive 4.3 (inline assembly for the semihosting trap), and Rule 11.4
   (integer addresses of the shared area and of semihosting arguments).  */

#include "harness.h"
#include "module_shared.h"

#define HARNESS_STACK_SIZE          ((ULONG) 2048UL)

#define SEMIHOSTING_SYS_WRITE0      ((ULONG) 0x04UL)
#define SEMIHOSTING_SYS_EXIT        ((ULONG) 0x18UL)
#define SEMIHOSTING_EXIT_SUCCESS    ((ULONG) 0x20026UL)     /* ADP_Stopped_ApplicationExit  */
#define SEMIHOSTING_EXIT_FAILURE    ((ULONG) 0x20023UL)     /* ADP_Stopped_RunTimeErrorUnknown */

UCHAR                           harness_module_memory[HARNESS_MODULE_MEMORY_SIZE];
UCHAR                           harness_object_memory[HARNESS_OBJECT_MEMORY_SIZE];

volatile ULONG                  harness_fault_count;
TX_THREAD * volatile            harness_fault_thread;
TXM_MODULE_INSTANCE * volatile  harness_fault_module;
volatile ULONG                  harness_fault_address;
volatile ULONG                  harness_fault_status;

static TX_THREAD                harness_thread;
static ULONG                    harness_checks;
static ULONG                    harness_failures;

extern TXM_MODULE_MANAGER_MEMORY_FAULT_INFO _txm_module_manager_memory_fault_info;

int     main(void);
VOID    harness_hard_fault(VOID);
VOID    harness_unexpected_exception(VOID);


/* Issue a semihosting call.  */
static ULONG  harness_semihost(ULONG operation, ULONG parameter)
{
register ULONG r0 __asm__("r0") = operation;
register ULONG r1 __asm__("r1") = parameter;

    __asm__ volatile ("bkpt 0xab" : "+r"(r0) : "r"(r1) : "memory");
    return(r0);
}


VOID  harness_print(const CHAR *text)
{
    (VOID) harness_semihost(SEMIHOSTING_SYS_WRITE0, (ULONG) text);
}


VOID  harness_value(const CHAR *label, ULONG value)
{
static const CHAR   digits[] = "0123456789abcdef";
CHAR                text[11];
UINT                index;

    text[0] = '0';
    text[1] = 'x';
    for (index = 0U; index < 8U; index++)
    {
        text[2U + index] = digits[(value >> (28U - (index * 4U))) & 0xFUL];
    }
    text[10] = '\0';

    harness_print(label);
    harness_print(" = ");
    harness_print(text);
    harness_print("\n");
}


VOID  harness_expect(const CHAR *description, ULONG actual, ULONG expected)
{
    harness_checks++;

    if (actual != expected)
    {
        harness_failures++;
        harness_print("FAIL: ");
        harness_print(description);
        harness_print("\n");
        harness_value("    expected", expected);
        harness_value("    actual  ", actual);
    }
}


VOID  harness_finish(VOID)
{
    harness_value("checks", harness_checks);
    harness_value("failures", harness_failures);

    if ((harness_failures == 0UL) && (harness_checks != 0UL))
    {
        harness_print("ALL CHECKS PASSED\n");
        (VOID) harness_semihost(SEMIHOSTING_SYS_EXIT, SEMIHOSTING_EXIT_SUCCESS);
    }
    else
    {
        harness_print("RESULT: FAILED\n");
        (VOID) harness_semihost(SEMIHOSTING_SYS_EXIT, SEMIHOSTING_EXIT_FAILURE);
    }

    for (;;)
    {
    }
}


/* A fault the module port does not handle is a harness failure, whatever the
   test was doing.  */
VOID  harness_hard_fault(VOID)
{
    harness_print("[FAULT] HardFault\n");
    harness_print("RESULT: FAILED\n");
    (VOID) harness_semihost(SEMIHOSTING_SYS_EXIT, SEMIHOSTING_EXIT_FAILURE);
    for (;;)
    {
    }
}


VOID  harness_unexpected_exception(VOID)
{
    harness_print("[FAULT] unexpected exception\n");
    harness_print("RESULT: FAILED\n");
    (VOID) harness_semihost(SEMIHOSTING_SYS_EXIT, SEMIHOSTING_EXIT_FAILURE);
    for (;;)
    {
    }
}


/* Called by the Module Manager after it has terminated a faulting module thread.  */
VOID  harness_fault_notify(TX_THREAD *thread_ptr, TXM_MODULE_INSTANCE *module_instance)
{
    harness_fault_thread =   thread_ptr;
    harness_fault_module =   module_instance;
    harness_fault_address =  _txm_module_manager_memory_fault_info.txm_module_manager_memory_fault_info_mmfar;
    harness_fault_status =   _txm_module_manager_memory_fault_info.txm_module_manager_memory_fault_info_cfsr;
    harness_fault_count++;
}


VOID  harness_shared_clear(VOID)
{
ULONG   index;

    for (index = 0UL; index < MODULE_SHARED_WORDS; index++)
    {
        MODULE_SHARED[index] = 0UL;
    }
}


UINT  harness_shared_grant(TXM_MODULE_INSTANCE *module_instance)
{
    return(txm_module_manager_external_memory_enable(module_instance, (VOID *) MODULE_SHARED_BASE,
                                                     MODULE_SHARED_SIZE, TXM_MODULE_MANAGER_SHARED_ATTRIBUTE_WRITE));
}


UINT  harness_wait_for_module(ULONG limit_ticks)
{
ULONG   start;
UINT    done;

    start = tx_time_get();
    done =  TX_FALSE;
    while ((done == TX_FALSE) && ((tx_time_get() - start) < limit_ticks))
    {
        if (MODULE_SHARED[MODULE_DONE] == MODULE_DONE_MAGIC)
        {
            done = TX_TRUE;
        }
        else
        {
            tx_thread_sleep(1);
        }
    }

    return(done);
}


static VOID  harness_thread_entry(ULONG thread_input)
{
    (VOID) thread_input;

    harness_expect("txm_module_manager_initialize",
                   (ULONG) txm_module_manager_initialize((VOID *) harness_module_memory, HARNESS_MODULE_MEMORY_SIZE),
                   (ULONG) TX_SUCCESS);
    harness_expect("txm_module_manager_object_pool_create",
                   (ULONG) txm_module_manager_object_pool_create(harness_object_memory, HARNESS_OBJECT_MEMORY_SIZE),
                   (ULONG) TX_SUCCESS);
    harness_expect("txm_module_manager_memory_fault_notify",
                   (ULONG) txm_module_manager_memory_fault_notify(harness_fault_notify),
                   (ULONG) TX_SUCCESS);

    harness_test();
    harness_finish();
}


int  main(void)
{
    tx_kernel_enter();
    return(0);
}


VOID  tx_application_define(VOID *first_unused_memory)
{
    (VOID) tx_thread_create(&harness_thread, "Module Manager Thread", harness_thread_entry, 0UL,
                            first_unused_memory, HARNESS_STACK_SIZE, 1U, 1U, TX_NO_TIME_SLICE, TX_AUTO_START);
}