path: root/test/tx/regression/threadx_queue_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 every queue service with event tracing enabled.

   Each service carries one in-line trace insert, and that insert behaves
   differently according to the system state it runs in, whether its event is
   filtered, whether it is the entry that wraps the trace buffer, and whether a
   buffer-full notification is registered. The test walks the queue services
   once per combination, so every service's insert is driven through all of
   them.

   Without event tracing compiled in the inserts expand to nothing, so the test
   only checks that the trace 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);


/* Define the queue services, in the order the test drives them. The scratch
   queue is created by the first and deleted by the last, so a pass over the
   whole list leaves the system as it found it.  */

#define QUEUE_SERVICE_CREATE        0
#define QUEUE_SERVICE_SEND          1
#define QUEUE_SERVICE_FRONT_SEND    2
#define QUEUE_SERVICE_RECEIVE       3
#define QUEUE_SERVICE_FLUSH         4
#define QUEUE_SERVICE_PRIORITIZE    5
#define QUEUE_SERVICE_INFO_GET      6
#define QUEUE_SERVICE_SEND_NOTIFY   7
#define QUEUE_SERVICE_DELETE        8
#define QUEUE_SERVICES              9

/* The services an ISR is allowed to call. Create and delete are rejected by the
   error checking shell from any non-thread caller.  */

#define QUEUE_ISR_FIRST_SERVICE     QUEUE_SERVICE_SEND
#define QUEUE_ISR_LAST_SERVICE      QUEUE_SERVICE_SEND_NOTIFY


static unsigned long   thread_0_counter =  0;
static TX_THREAD       thread_0;

static TX_QUEUE        queue_0;
static TX_QUEUE        queue_1;
static ULONG           queue_0_area[4];
static ULONG           queue_1_area[4];

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 queue service through its published entry point.  */

static UINT  queue_service(UINT service)
{

UINT    status;
ULONG   message =  0x12345678UL;
ULONG   received;


    switch (service)
    {

    case QUEUE_SERVICE_CREATE:
        status =  tx_queue_create(&queue_1, "queue 1", TX_1_ULONG, queue_1_area, sizeof(queue_1_area));
        break;

    case QUEUE_SERVICE_SEND:
        status =  tx_queue_send(&queue_0, &message, TX_NO_WAIT);
        break;

    case QUEUE_SERVICE_FRONT_SEND:
        status =  tx_queue_front_send(&queue_0, &message, TX_NO_WAIT);
        break;

    case QUEUE_SERVICE_RECEIVE:
        status =  tx_queue_receive(&queue_0, &received, TX_NO_WAIT);
        break;

    case QUEUE_SERVICE_FLUSH:
        status =  tx_queue_flush(&queue_0);
        break;

    case QUEUE_SERVICE_PRIORITIZE:
        status =  tx_queue_prioritize(&queue_0);
        break;

    case QUEUE_SERVICE_INFO_GET:
        status =  tx_queue_info_get(&queue_0, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL);
        break;

    case QUEUE_SERVICE_SEND_NOTIFY:
        status =  tx_queue_send_notify(&queue_0, TX_NULL);
        break;

    default:
        status =  tx_queue_delete(&queue_1);
        break;
    }

    return(status);
}


/* The status a service returns when the pass above is run to completion. Send
   and front send fill the queue that receive empties and flush clears, so the
   pass is repeatable.  */

static UINT  queue_service_expected(UINT service)
{

UINT    expected;


#ifdef TX_DISABLE_NOTIFY_CALLBACKS
    if (service == QUEUE_SERVICE_SEND_NOTIFY)
    {
        expected =  TX_FEATURE_NOT_ENABLED;
    }
    else
    {
        expected =  TX_SUCCESS;
    }
#else
    expected =  TX_SUCCESS;
#endif

    return(expected);
}


#ifdef TX_ENABLE_EVENT_TRACE

/* Drive one queue service through its internal entry point. The error checking
   shell rejects a create or a delete from any caller that is not a thread, so
   the inserts inside those two services cannot be reached from a forced system
   state through the published entry points. The shell itself is covered by its
   own tests; what is under test here is the insert behind it.  */

static UINT  queue_service_internal(UINT service)
{

UINT    status;
ULONG   message =  0x12345678UL;
ULONG   received;


    switch (service)
    {

    case QUEUE_SERVICE_CREATE:
        status =  _tx_queue_create(&queue_1, "queue 1", TX_1_ULONG, queue_1_area, sizeof(queue_1_area));
        break;

    case QUEUE_SERVICE_SEND:
        status =  _tx_queue_send(&queue_0, &message, TX_NO_WAIT);
        break;

    case QUEUE_SERVICE_FRONT_SEND:
        status =  _tx_queue_front_send(&queue_0, &message, TX_NO_WAIT);
        break;

    case QUEUE_SERVICE_RECEIVE:
        status =  _tx_queue_receive(&queue_0, &received, TX_NO_WAIT);
        break;

    case QUEUE_SERVICE_FLUSH:
        status =  _tx_queue_flush(&queue_0);
        break;

    case QUEUE_SERVICE_PRIORITIZE:
        status =  _tx_queue_prioritize(&queue_0);
        break;

    case QUEUE_SERVICE_INFO_GET:
        status =  _tx_queue_info_get(&queue_0, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL);
        break;

    case QUEUE_SERVICE_SEND_NOTIFY:
        status =  _tx_queue_send_notify(&queue_0, TX_NULL);
        break;

    default:
        status =  _tx_queue_delete(&queue_1);
        break;
    }

    return(status);
}


/* Run a pass over the services 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 state and the interrupt nesting count the
   same variable carries is restored before anything else reads it.  */

static UINT  pass_with_system_state(ULONG system_state)
{

TX_INTERRUPT_SAVE_AREA

UINT    service;
UINT    status =  TX_SUCCESS;
ULONG   saved_system_state;


    TX_DISABLE
    saved_system_state =  _tx_thread_system_state;
    _tx_thread_system_state =  system_state;

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

        if (queue_service_internal(service) != queue_service_expected(service))
        {
            status =  TX_NOT_DONE;
        }
    }

    _tx_thread_system_state =  saved_system_state;
    TX_RESTORE

    return(status);
}


/* Position the trace buffer one entry short of its end, so that the next event
   inserted is the one that wraps it. A wrap reached by filling the buffer lands
   on whichever service happens to write the last entry; positioning puts each
   service's own insert on the boundary in turn.  */

static void  position_at_buffer_end(void)
{

TX_INTERRUPT_SAVE_AREA


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


/* Run a pass over the services, wrapping the trace buffer on every one of
   them.  */

static UINT  pass_with_buffer_wrap(void)
{

UINT    service;
UINT    status =  TX_SUCCESS;


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

        position_at_buffer_end();

        if (queue_service(service) != queue_service_expected(service))
        {
            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 ISR may call, once, from interrupt context.  */

static void  test_isr(void)
{

UINT    service;


    if (isr_pass_done == 0)
    {

        for (service = QUEUE_ISR_FIRST_SERVICE; service <= QUEUE_ISR_LAST_SERVICE; service++)
        {

            if (queue_service(service) != queue_service_expected(service))
            {
                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_queue_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 Queue Trace Test........................................... ERROR #1\n");
        test_control_return(1);
    }

    /* Create the queue the services are driven against.  */
    status =  tx_queue_create(&queue_0, "queue 0", TX_1_ULONG, queue_0_area, sizeof(queue_0_area));

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

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


/* Define the test thread.  */

static void    thread_0_entry(ULONG thread_input)
{

UINT    status;
UINT    service;
#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 Queue Trace Test........................................... ");

    /* 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);
    }

    /* One pass over the services, so the test still exercises them.  */
    for (service = 0; service < QUEUE_SERVICES; service++)
    {

        if (queue_service(service) != queue_service_expected(service))
        {

            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.  */
    for (service = 0; service < QUEUE_SERVICES; service++)
    {

        if (queue_service(service) != queue_service_expected(service))
        {

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

    /* Queue events filtered out: the insert is reached and declines to record
       anything.  */
    status =  tx_trace_event_filter(TX_TRACE_QUEUE_EVENTS);

    if (status != TX_SUCCESS)
    {

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

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

        if (queue_service(service) != queue_service_expected(service))
        {

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

    status =  tx_trace_event_unfilter(TX_TRACE_QUEUE_EVENTS);

    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 ISR presents, for the two services an ISR may not
       call.  */
    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 < QUEUE_SERVICES)
    {

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

    status =  tx_trace_disable();

    if (status != TX_SUCCESS)
    {

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

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

#endif
}