path: root/test/tx/regression/threadx_byte_pool_trace_update_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 byte allocate service's trace update in place.

   The service records its event, remembers where the entry went and what its
   time stamp was, and comes back to write the address of the memory it handed
   out into that same entry once it knows it. It does so only if the entry is
   still the one it wrote, which it decides by comparing the time stamp. There
   are two of those regions: one on the path that finds memory immediately, and
   one on the path that suspends and is given memory by a later release.

   The test walks both, and then drives the suspending one a second time with
   the trace buffer deliberately written all the way round in between, so the
   entry the service comes back to is a different event and the update is
   correctly skipped.

   Without event tracing compiled in none of that code exists, so the test is
   then an ordinary allocate, suspend and release exercise.  */


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


/* The test thread takes a fragment large enough that what is left over cannot
   satisfy the helper thread's request, so the helper has to suspend. Releasing
   the large fragment merges the pool back together and the request then
   fits.  */

#define BYTE_POOL_SIZE                  1024
#define BYTE_SMALL_SIZE                 32
#define BYTE_HOG_SIZE                   800
#define BYTE_HELPER_SIZE                300

/* The helper thread makes one request per round: one that finds the entry
   unchanged, and one that finds it overwritten.  */

#define HELPER_ROUNDS                   2


static unsigned long   thread_0_counter =  0;
static TX_THREAD       thread_0;
static unsigned long   thread_1_counter =  0;
static TX_THREAD       thread_1;

static TX_BYTE_POOL    pool_0;
static UCHAR           pool_0_memory[BYTE_POOL_SIZE];

static VOID            *hog_ptr;
static VOID            *small_ptr;
static VOID            *helper_ptr;
static UINT            helper_status =  TX_SUCCESS;

/* The buffer is large enough to hold a whole suspension and resumption without
   coming round on itself, so the unchanged case is reached by the ordinary path
   and the overwritten case only when the test asks for it.  */

static UCHAR           trace_buffer[2048];

#define TRACE_REGISTRY_ENTRIES      4


/* Define thread prototypes.  */

static void    thread_0_entry(ULONG thread_input);
static void    thread_1_entry(ULONG thread_input);


/* Prototype for test control return.  */

void  test_control_return(UINT status);


/* Write one trace event into every slot of the buffer, so that whatever entry a
   suspended service is holding on to has been replaced by a later event. One
   pass of the buffer's own length is enough whatever position it starts from;
   the two extra entries keep it so if an interrupt inserts an event of its own
   while the loop runs.  */

static void  overwrite_trace_buffer(void)
{

#ifdef TX_ENABLE_EVENT_TRACE

ULONG   entries;


    entries =  (ULONG) (_tx_trace_buffer_end_ptr - _tx_trace_buffer_start_ptr);

    while (entries != ((ULONG) 0))
    {

        (VOID) tx_byte_pool_info_get(&pool_0, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL);
        entries--;
    }

    (VOID) tx_byte_pool_info_get(&pool_0, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL);
    (VOID) tx_byte_pool_info_get(&pool_0, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL, TX_NULL);

#endif
}


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

#ifdef CTEST
void test_application_define(void *first_unused_memory)
#else
void    threadx_byte_pool_trace_update_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 Byte Pool Trace Update Test................................ ERROR #1\n");
        test_control_return(1);
    }

    /* The helper thread runs at a higher priority than the test thread, so that
       it takes the processor the moment it is resumed and the moment memory is
       released to it. Every handover in the test is therefore a preemption
       rather than something that waits for a tick.  */
    status =  tx_thread_create(&thread_1, "thread 1", thread_1_entry, 1,
            pointer, TEST_STACK_SIZE_PRINTF,
            15, 15, TX_NO_TIME_SLICE, TX_DONT_START);
    pointer =  pointer + TEST_STACK_SIZE_PRINTF;

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

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

    /* Create the pool both threads allocate from.  */
    status =  tx_byte_pool_create(&pool_0, "pool 0", pool_0_memory, sizeof(pool_0_memory));

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

        printf("Running Byte Pool Trace Update Test................................ ERROR #3\n");
        test_control_return(1);
    }
}


/* Define the test thread.  */

static void    thread_0_entry(ULONG thread_input)
{

UINT    status;


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

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

    /* Enable event tracing. Without it compiled in the service reports the
       feature as disabled and the rest of the test runs unchanged.  */
    status =  tx_trace_enable(trace_buffer, sizeof(trace_buffer), TRACE_REGISTRY_ENTRIES);

#ifdef TX_ENABLE_EVENT_TRACE
    if (status != TX_SUCCESS)
#else
    if (status != TX_FEATURE_NOT_ENABLED)
#endif
    {

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

    /* Memory is available, so the service finds it immediately and comes back
       to the entry it has just written.  */
    status =  tx_byte_allocate(&pool_0, &small_ptr, BYTE_SMALL_SIZE, TX_NO_WAIT);

    if (status != TX_SUCCESS)
    {

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

    status =  tx_byte_release(small_ptr);

    if (status != TX_SUCCESS)
    {

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

    /* Take most of the pool, so that the helper thread's request has to
       suspend.  */
    status =  tx_byte_allocate(&pool_0, &hog_ptr, BYTE_HOG_SIZE, TX_NO_WAIT);

    if (status != TX_SUCCESS)
    {

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

    /* First round: the helper suspends, the large fragment is released to it,
       and the entry it wrote on the way in is still there.  */
    status =  tx_thread_resume(&thread_1);

    if (status != TX_SUCCESS)
    {

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

    status =  tx_byte_release(hog_ptr);

    if (status != TX_SUCCESS)
    {

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

    /* The helper took its memory, gave it back and suspended itself, so the
       pool is whole again. Take the large fragment once more for the second
       round.  */
    status =  tx_byte_allocate(&pool_0, &hog_ptr, BYTE_HOG_SIZE, TX_NO_WAIT);

    if (status != TX_SUCCESS)
    {

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

    /* Second round: the same handover, but this time the trace buffer is
       written all the way round while the helper is suspended, so the entry it
       comes back to belongs to a later event.  */
    status =  tx_thread_resume(&thread_1);

    if (status != TX_SUCCESS)
    {

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

    overwrite_trace_buffer();

    status =  tx_byte_release(hog_ptr);

    if (status != TX_SUCCESS)
    {

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

    /* Both rounds have to have succeeded from the helper's side. A failure
       there means the handover did not happen the way the test assumes, which
       would leave the regions above undriven.  */
    if (helper_status != TX_SUCCESS)
    {

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

    if (thread_1_counter != HELPER_ROUNDS)
    {

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

    status =  tx_trace_disable();

#ifdef TX_ENABLE_EVENT_TRACE
    if (status != TX_SUCCESS)
#else
    if (status != TX_FEATURE_NOT_ENABLED)
#endif
    {

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

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


/* Define the helper thread. Each round suspends on a pool with no fragment
   large enough, takes the memory the test thread releases to it, gives it
   straight back, and then stands down until the test thread wants it again.  */

static void    thread_1_entry(ULONG thread_input)
{

UINT    round;


    for (round = 0; round < HELPER_ROUNDS; round++)
    {

        if (tx_byte_allocate(&pool_0, &helper_ptr, BYTE_HELPER_SIZE, TX_WAIT_FOREVER) != TX_SUCCESS)
        {
            helper_status =  TX_NOT_DONE;
        }
        else if (tx_byte_release(helper_ptr) != TX_SUCCESS)
        {
            helper_status =  TX_NOT_DONE;
        }
        else
        {

            /* Round complete.  */
            thread_1_counter++;
        }

        (VOID) tx_thread_suspend(&thread_1);
    }
}