path: root/test/tx/regression/threadx_trace_service_trace_test.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).
 * 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
 **************************************************************************/

/* This test drives the trace services that carry an in-line trace insert of
   their own.

   Every other subsystem's trace test walks services that are users of the
   tracing machinery. These four are part of it: the interrupt control the
   application calls to change the lockout posture, the two inserts a port's
   interrupt shim makes around an ISR, and the user event insert. Their inserts
   behave the same way as every other one, so the test walks them once per
   condition the insert distinguishes - the system state it runs in, whether its
   event is filtered, whether it is the entry that wraps the trace buffer,
   whether a buffer-full notification is registered, and whether tracing is
   enabled at all.

   Without event tracing compiled in the inserts expand to nothing, so the test
   only checks that the services report the feature as disabled.  */


#include   <stdio.h>
#include   "tx_api.h"
#define    TX_SOURCE_CODE
#include   "tx_trace.h"
#include   "tx_initialize.h"


/* Define the ISR dispatch.  */

extern VOID    (*test_isr_dispatch)(void);


/* The services the test drives, in the order it drives them. None of them owns
   an object, so a pass leaves the system exactly as it found it.  */

#define TRACE_SERVICE_INTERRUPT_CONTROL     0
#define TRACE_SERVICE_ISR_ENTER             1
#define TRACE_SERVICE_ISR_EXIT              2
#define TRACE_SERVICE_USER_EVENT            3
#define TRACE_SERVICES                      4

/* The event classes those services score against. The filtered pass has to
   filter all three, or the services whose class is still enabled take the
   unfiltered arm and the pass proves nothing.  */

#define TRACE_SERVICE_EVENT_CLASSES         (TX_TRACE_INTERNAL_EVENTS | \
                                             TX_TRACE_INTERRUPT_CONTROL_EVENT | \
                                             TX_TRACE_USER_EVENTS)

#define TRACE_TEST_ISR_ID                   0x5A
#define TRACE_TEST_USER_EVENT               TX_TRACE_USER_EVENT_START


static unsigned long   thread_0_counter =  0;
static TX_THREAD       thread_0;

static ULONG           buffer_full_count =  0;
static ULONG           isr_pass_done =  0;
static UINT            isr_status =  TX_SUCCESS;

/* The trace buffer is deliberately small. Several passes over the services fit
   in it many times over, so the wrap path is reached by ordinary use as well as
   by the positioned wrap below.  */

static UCHAR           trace_buffer[512];

#define TRACE_REGISTRY_ENTRIES      4


/* Define thread prototypes.  */

static void    thread_0_entry(ULONG thread_input);


/* Prototype for test control return.  */

void  test_control_return(UINT status);


/* Drive one service. The interrupt control is driven as the kernel's own
   lockout macros drive it - a disable whose returned posture is handed straight
   back - so the pair is balanced whatever posture it is called in, and the
   service's insert runs twice.  */

static UINT  trace_service(UINT service)
{

UINT    status =  TX_SUCCESS;
UINT    saved_posture;


    switch (service)
    {

    case TRACE_SERVICE_INTERRUPT_CONTROL:
        saved_posture =  tx_interrupt_control(TX_INT_DISABLE);
        tx_interrupt_control(saved_posture);
        break;

    case TRACE_SERVICE_ISR_ENTER:
        tx_trace_isr_enter_insert(TRACE_TEST_ISR_ID);
        break;

    case TRACE_SERVICE_ISR_EXIT:
        tx_trace_isr_exit_insert(TRACE_TEST_ISR_ID);
        break;

    default:
        status =  tx_trace_user_event_insert(TRACE_TEST_USER_EVENT, 1, 2, 3, 4);
        break;
    }

    return(status);
}


/* The status a service returns. Only the user event insert has one, and it
   reports that it has nothing to insert into when tracing is off.  */

static UINT  trace_service_expected(UINT service, UINT trace_enabled)
{

UINT    expected;


#ifdef TX_ENABLE_EVENT_TRACE
    if (service != TRACE_SERVICE_USER_EVENT)
    {
        expected =  TX_SUCCESS;
    }
    else if (trace_enabled == TX_TRUE)
    {
        expected =  TX_SUCCESS;
    }
    else
    {
        expected =  TX_NOT_DONE;
    }
#else
    if (service != TRACE_SERVICE_USER_EVENT)
    {
        expected =  TX_SUCCESS;
    }
    else
    {
        expected =  TX_FEATURE_NOT_ENABLED;
    }
#endif

    return(expected);
}


/* Walk the service list once.  */

static UINT  pass_over_services(UINT trace_enabled)
{

UINT    service;
UINT    status =  TX_SUCCESS;


    for (service = 0; service < TRACE_SERVICES; service++)
    {

        if (trace_service(service) != trace_service_expected(service, trace_enabled))
        {
            status =  TX_NOT_DONE;
        }
    }

    return(status);
}


#ifdef TX_ENABLE_EVENT_TRACE

/* Run a pass with the system state forced to the value the insert has to see.
   Interrupts are held off across the pass, so the timer thread cannot observe
   the forced value, and the interrupt nesting count the same variable carries is
   restored before anything else reads it.

   None of these four services has an error checking shell in front of it and
   none of them refuses a caller on the strength of the system state, so the
   published entry points reach the inserts in every state.  */

static UINT  pass_with_system_state(ULONG system_state)
{

TX_INTERRUPT_SAVE_AREA

UINT    status;
ULONG   saved_system_state;


    TX_DISABLE
    saved_system_state =  _tx_thread_system_state;
    _tx_thread_system_state =  system_state;

    status =  pass_over_services(TX_TRUE);

    _tx_thread_system_state =  saved_system_state;
    TX_RESTORE

    return(status);
}


/* Position the trace buffer one entry short of its end and drive one service,
   with interrupts held off across both. A wrap reached by filling the buffer
   lands on whichever entry happens to be last, and the tick's own ISR inserts
   would take the boundary instead; positioning under lockout puts each service's
   own insert on it in turn.  */

static UINT  pass_with_buffer_wrap(void)
{

TX_INTERRUPT_SAVE_AREA

UINT    service;
UINT    status =  TX_SUCCESS;


    for (service = 0; service < TRACE_SERVICES; service++)
    {

        TX_DISABLE

        _tx_trace_buffer_current_ptr =  _tx_trace_buffer_end_ptr - 1;
        _tx_trace_header_ptr -> tx_trace_header_buffer_current_pointer =  (ULONG) _tx_trace_buffer_current_ptr;

        if (trace_service(service) != trace_service_expected(service, TX_TRUE))
        {
            status =  TX_NOT_DONE;
        }

        TX_RESTORE
    }

    return(status);
}


/* Count the trace buffer wraps the kernel reports.  */

static VOID  trace_buffer_full(void *buffer)
{

    buffer_full_count++;
}


/* Drive the services from interrupt context.  */

static void  test_isr(void)
{

    if (isr_pass_done == 0)
    {

        if (pass_over_services(TX_TRUE) != TX_SUCCESS)
        {
            isr_status =  TX_NOT_DONE;
        }

        isr_pass_done =  1;
    }
}

#endif


/* Define what the initial system looks like.  */

#ifdef CTEST
void test_application_define(void *first_unused_memory)
#else
void    threadx_trace_service_trace_application_define(void *first_unused_memory)
#endif
{

UINT    status;
CHAR    *pointer;


    /* Put first available memory address into a character pointer.  */
    pointer =  (CHAR *) first_unused_memory;

    /* Put system definition stuff in here, e.g. thread creates and other assorted
       create information.  */
    status =  tx_thread_create(&thread_0, "thread 0", thread_0_entry, 1,
            pointer, TEST_STACK_SIZE_PRINTF,
            16, 16, TX_NO_TIME_SLICE, TX_AUTO_START);
    pointer =  pointer + TEST_STACK_SIZE_PRINTF;

    /* Check for status.  */
    if (status != TX_SUCCESS)
    {

        printf("Running Trace Service Trace Test................................... ERROR #1\n");
        test_control_return(1);
    }
}


/* Define the test thread.  */

static void    thread_0_entry(ULONG thread_input)
{

UINT    status;
#ifdef TX_ENABLE_EVENT_TRACE
ULONG   wait;
#endif


    /* Increment thread 0 counter.  */
    thread_0_counter++;

    /* Inform user of success getting to this test.  */
    printf("Running Trace Service Trace Test................................... ");

    /* Tracing is not enabled yet, so every insert below finds no buffer to
       write into.  */
    if (pass_over_services(TX_FALSE) != TX_SUCCESS)
    {

        printf("ERROR #2\n");
        test_control_return(1);
    }

    /* Enable event tracing.  */
    status =  tx_trace_enable(trace_buffer, sizeof(trace_buffer), TRACE_REGISTRY_ENTRIES);

#ifndef TX_ENABLE_EVENT_TRACE

    /* Without tracing compiled in the inserts expand to nothing, so there is
       nothing here to drive. Check that the service says so and finish.  */
    if (status != TX_FEATURE_NOT_ENABLED)
    {

        printf("ERROR #3\n");
        test_control_return(1);
    }

    if (pass_over_services(TX_FALSE) != TX_SUCCESS)
    {

        printf("ERROR #4\n");
        test_control_return(1);
    }

    printf("SUCCESS!\n");
    test_control_return(0);

#else

    if (status != TX_SUCCESS)
    {

        printf("ERROR #5\n");
        test_control_return(1);
    }

    /* Thread context, every event enabled: the insert runs and takes the
       current thread's priority.  */
    if (pass_over_services(TX_TRUE) != TX_SUCCESS)
    {

        printf("ERROR #6\n");
        test_control_return(1);
    }

    /* The services' event classes filtered out: the insert is reached and
       declines to record anything.  */
    status =  tx_trace_event_filter(TRACE_SERVICE_EVENT_CLASSES);

    if (status != TX_SUCCESS)
    {

        printf("ERROR #7\n");
        test_control_return(1);
    }

    if (pass_over_services(TX_TRUE) != TX_SUCCESS)
    {

        printf("ERROR #8\n");
        test_control_return(1);
    }

    status =  tx_trace_event_unfilter(TRACE_SERVICE_EVENT_CLASSES);

    if (status != TX_SUCCESS)
    {

        printf("ERROR #9\n");
        test_control_return(1);
    }

    /* Interrupt context: the insert records the interrupted thread instead of a
       priority. Bounded, so a tick that never arrives fails the test rather than
       hanging it.  */
    test_isr_dispatch =  test_isr;

    wait =  0;
    while ((isr_pass_done == 0) && (wait < 100))
    {

        tx_thread_sleep(1);
        wait++;
    }

    test_isr_dispatch =  TX_NULL;

    if (isr_pass_done == 0)
    {

        printf("ERROR #10\n");
        test_control_return(1);
    }

    if (isr_status != TX_SUCCESS)
    {

        printf("ERROR #11\n");
        test_control_return(1);
    }

    /* Initialization context: the insert has no thread to record at all.  */
    if (pass_with_system_state(TX_INITIALIZE_IN_PROGRESS) != TX_SUCCESS)
    {

        printf("ERROR #12\n");
        test_control_return(1);
    }

    /* The same state an interrupt presents.  */
    if (pass_with_system_state((ULONG) 1) != TX_SUCCESS)
    {

        printf("ERROR #13\n");
        test_control_return(1);
    }

    /* Wrap the trace buffer on every service with no notification registered,
       then again with one.  */
    if (pass_with_buffer_wrap() != TX_SUCCESS)
    {

        printf("ERROR #14\n");
        test_control_return(1);
    }

    status =  tx_trace_buffer_full_notify(trace_buffer_full);

    if (status != TX_SUCCESS)
    {

        printf("ERROR #15\n");
        test_control_return(1);
    }

    if (pass_with_buffer_wrap() != TX_SUCCESS)
    {

        printf("ERROR #16\n");
        test_control_return(1);
    }

    /* Every service in the last pass wrapped the buffer, so the notification
       has to have been called once for each of them.  */
    if (buffer_full_count < TRACE_SERVICES)
    {

        printf("ERROR #17\n");
        test_control_return(1);
    }

    status =  tx_trace_buffer_full_notify(TX_NULL);

    if (status != TX_SUCCESS)
    {

        printf("ERROR #18\n");
        test_control_return(1);
    }

    status =  tx_trace_disable();

    if (status != TX_SUCCESS)
    {

        printf("ERROR #19\n");
        test_control_return(1);
    }

    /* Tracing off again: the inserts find no buffer, and the user event insert
       reports that it has nothing to insert into.  */
    if (pass_over_services(TX_FALSE) != TX_SUCCESS)
    {

        printf("ERROR #20\n");
        test_control_return(1);
    }

    printf("SUCCESS!\n");
    test_control_return(0);

#endif
}