path: root/test/smp/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.

   The SMP insert reads the system state and the current thread of the core it
   is running on rather than a single global, so the passes below that force a
   system state write the entry of the core this test is running on. Every
   thread in this suite is created mapped to core 0 alone, but the core is read
   rather than assumed.

   The interrupt control is driven differently from the other three, and the
   difference is this port's rather than this test's. TX_DISABLE on SMP is
   _tx_thread_smp_protect, not tx_interrupt_control, and the two are not
   interchangeable. _tx_thread_interrupt_control takes the Linux critical
   section on every call and hands it back only on an enable, and then in full
   rather than by one level, so what a disable-and-restore pair does depends on
   the posture it was called in. Called where the section is already held, the
   restore is itself a disable - the posture the first call reports is the one
   it found - and the pair leaves the section two levels deeper than it found
   it, which is never made up and locks the process. Called where the section is
   free, the restore is an enable and the pair balances, which is how an
   application uses it.

   So the interrupt control is driven at the outermost level only. Its disable
   half runs inside the SMP protection, which is where the insert is, and its
   enable half runs once the protection has been released, which is what hands
   the section back; and it is left out of the pass that runs from interrupt
   context, where the section is held by the interrupt path and there is no
   later point at which the enable could be completed. Its own forced-state
   passes reach the two arms that pass would have covered. The other three
   services write a trace entry and nothing else, and are driven everywhere.

   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

/* The system state is per core on SMP, and tx_thread.h remaps the name to a
   function call returning the running core's entry unless this macro says the
   file wants the array itself. The forced-state pass below has to write it, so
   it needs the array.  */

#define    TX_THREAD_SMP_SOURCE_CODE
#include   "tx_trace.h"
#include   "tx_thread.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 ULONG           trace_buffer[128];

#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, in a context that holds no SMP protection of its own. The
   interrupt control is driven as a balanced disable and restore, which is what
   an application does with it.  */

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

/* Drive one service with the SMP protection already held by the caller. The
   interrupt control takes only the disable half of its pair here; the enable
   half is owed to the caller and is completed by the function below, once the
   protection has been released. See the note at the head of the file.  */

static UINT  service_under_protection(UINT service)
{

UINT    status =  TX_SUCCESS;


    if (service == TRACE_SERVICE_INTERRUPT_CONTROL)
    {
        tx_interrupt_control(TX_INT_DISABLE);
    }
    else
    {
        status =  trace_service(service);
    }

    return(status);
}


/* Complete what the call above left owed. The enable is what hands the Linux
   critical section back, so it has to run with no protection held; it also
   clears the lockout flag the disable set, which on this port is read by the
   scheduler.  */

static VOID  service_after_protection(UINT service)
{

    if (service == TRACE_SERVICE_INTERRUPT_CONTROL)
    {
        tx_interrupt_control(TX_INT_ENABLE);
    }
}


/* Position the trace buffer one entry short of its end.  */

static void  position_at_buffer_end(void)
{

    _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;
}


/* Run a pass with the system state forced to the value the insert has to see.
   One SMP protection covers the write, the service and the restore, so nothing
   else observes the forced value: every trace insert in the kernel is written
   inside that same protection, and the tick cannot run while it is held.

   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    service;
UINT    core;
UINT    status =  TX_SUCCESS;
ULONG   saved_system_state;


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

        TX_DISABLE
        core =  tx_thread_smp_core_get();
        saved_system_state =  _tx_thread_system_state[core];
        _tx_thread_system_state[core] =  system_state;

        if (service_under_protection(service) != TX_SUCCESS)
        {
            status =  TX_NOT_DONE;
        }

        _tx_thread_system_state[core] =  saved_system_state;
        TX_RESTORE

        service_after_protection(service);
    }

    return(status);
}


/* Run a pass over the services, wrapping the trace buffer on every one of
   them. The positioning and the call are held under one SMP protection, so the
   boundary entry is the service's own by construction.

   Once a notification is registered, every service in the pass has to report a
   wrap of its own. Checking that per service rather than in total is what makes
   the positioning prove itself: a service whose boundary entry was taken by
   something else fails here instead of quietly losing coverage.  */

static UINT  pass_with_buffer_wrap(UINT check_wraps)
{

TX_INTERRUPT_SAVE_AREA

UINT    service;
UINT    status =  TX_SUCCESS;
ULONG   before;


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

        before =  buffer_full_count;

        TX_DISABLE
        position_at_buffer_end();

        if (service_under_protection(service) != TX_SUCCESS)
        {
            status =  TX_NOT_DONE;
        }
        TX_RESTORE

        service_after_protection(service);

        if ((check_wraps == TX_TRUE) && (buffer_full_count == before))
        {
            status =  TX_NOT_DONE;
        }
    }

    return(status);
}


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

static VOID  trace_buffer_full(void *buffer)
{

    buffer_full_count++;
}


/* Drive the services an interrupt may call, from interrupt context, where the
   system state is already the value an interrupt presents. The interrupt
   control is not one of them - see the note at the head of the file.  */

static void  test_isr(void)
{

UINT    service;


    if (isr_pass_done == 0)
    {

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

            if (service == TRACE_SERVICE_INTERRUPT_CONTROL)
            {
                continue;
            }

            if (trace_service(service) != trace_service_expected(service, TX_TRUE))
            {
                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, forced rather than arrived at, so
       that the arm is covered even in a run where the ISR pass above was
       starved of a tick.  */
    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_FALSE) != 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_TRUE) != TX_SUCCESS)
    {

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

    status =  tx_trace_buffer_full_notify(TX_NULL);

    if (status != TX_SUCCESS)
    {

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

    status =  tx_trace_disable();

    if (status != TX_SUCCESS)
    {

        printf("ERROR #18\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 #19\n");
        test_control_return(1);
    }

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

#endif
}