path: root/test/smp/regression/threadx_byte_pool_owner_change_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 pool search's retry after the pool changes owner.

   The SMP search claims the pool, walks it holding the protection, and gives
   the protection up every TX_BYTE_POOL_MULTIPLE_BLOCK_SEARCH blocks so that a
   long walk does not lock the other cores out for its whole duration. Each time
   it takes the protection back it checks whether the pool is still its own. If
   another core claimed it in the meantime, the search delays briefly to avoid
   thrashing, resets its walk and claims the pool again.

   That region exists only in common_smp -- the monoprocessor search gives the
   protection up on every block and has neither the counter nor the delay -- so
   there is no monoprocessor test shape to port.

   The arrangement it needs was derived from the sources rather than guessed.
   tx_byte_pool_owner is written in six places and all six are kernel services:
   the allocate, the release, the search itself and the create. None of them can
   run on the searching thread's own core while that thread is inside the
   search, because the walk calls nothing and yields to nothing. So the only
   agent is another core, and this is the arrangement that supplies one: the
   test thread keeps the core it was created on and the claim thread below is
   excluded from every core but the next, where it makes the same unsatisfiable
   request and so walks the same pool.

   The window is also gated behind the block limit. It opens only where the
   search gives the protection up, which is once per limit's worth of blocks, so
   a pool with fewer fragments than the limit never opens it at all -- which is
   why the existing contention test, on a pool of 108 bytes, does not reach this
   and why the pool below is broken into many more fragments than that.

   What the test asserts is the arrangement, because the retry itself leaves
   nothing behind that a test can read: it restores the pool's owner to the
   searching thread, which is what the walk had already set it to. The
   assertions are therefore that the pool is fragmented past the limit, that the
   claim thread ran on a core other than the test thread's, that it was already
   claiming before the first walk, and that it went on claiming while the walks
   ran. Whether the retry is reached is a measurement over the eight
   configurations rather than something this file can check, and it is recorded
   in the step note.

   The test thread decides how long the run lasts: it makes a fixed number of
   walks and then stands the claim thread down, so the claims cover the whole of
   the searching and none of the time before it. The two threads thrash each
   other's walks, which is what the kernel's own delay is there to damp, so the
   walk count is kept low and is what bounds the run.  */


#include   <stdio.h>
#include   "tx_api.h"


/* The pool is sized so that fragments of BYTE_CHUNK_SIZE break it into
   comfortably more than the search limit, which is what makes the walk long
   enough to give the protection up several times.  */

#define BYTE_POOL_SIZE                  2048
#define BYTE_CHUNK_SIZE                 24
#define BYTE_CHUNKS_MAX                 64

#define BYTE_CHUNKS_REQUIRED            (2 * TX_BYTE_POOL_MULTIPLE_BLOCK_SEARCH)

/* One claim thread, on the core next to the test thread's. One is all the
   construct needs -- it asks whether the pool can change hands under a walk, and
   a single other core answers that -- and one is what keeps the arrangement
   honest on a machine with fewer processors than the port simulates cores. Every
   claim thread walks the pool holding the protection, so a second and a third
   would spend most of their time contending with each other rather than with the
   thread under test.  */

#define CLAIM_THREADS                   1
#define CLAIM_CORE                      1

/* The claim thread runs until the test thread stands it down. The cap only
   guarantees termination if that never happens.  */

#define CLAIMS_CAP                      10000000

/* Each round is one full walk of the pool, which gives the protection up once
   per limit's worth of blocks. The count is what decides how many contended
   windows the run offers.  */

#define SEARCH_ROUNDS                   20

/* How long the test thread will wait for the core rebalance to map the claim
   threads, and then for each of them to make its first claim. Both are waited
   out rather than slept through, so the searching starts with every claim
   thread already claiming whatever the configuration costs in scheduling
   latency.  */

#define SETTLE_TICKS_MAX                200


static unsigned long   thread_0_counter =  0;
static TX_THREAD       thread_0;

static TX_THREAD       claim_threads[CLAIM_THREADS];
static volatile ULONG  claim_counts[CLAIM_THREADS];
static ULONG           claim_cores[CLAIM_THREADS];
static volatile ULONG  claim_started[CLAIM_THREADS];

static TX_BYTE_POOL    pool_0;
static UCHAR           pool_0_memory[BYTE_POOL_SIZE];

/* One spare slot: the fill loop can use every one of BYTE_CHUNKS_MAX, and the
   request that follows it needs somewhere to point.  */

static VOID            *chunks[BYTE_CHUNKS_MAX + 1];

/* The claim threads wait for this before claiming anything, so that no claim is
   spent during the ticks the core rebalance takes to map them.  */

static volatile ULONG  claims_enabled =  0;

/* Set when the test thread has finished searching, so the claim threads stand
   down and the test can read their counters.  */

static volatile ULONG  claims_stopped =  0;


/* Define thread prototypes.  */

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


/* How many claim threads have reached their entry point, and how many have made
   a claim. The test thread waits on both before it starts searching.  */

static UINT  claim_threads_started(void)
{

UINT    index;
UINT    count =  0;


    for (index = 0; index < CLAIM_THREADS; index++)
    {

        if (claim_started[index] != ((ULONG) 0))
        {
            count++;
        }
    }

    return(count);
}


static ULONG  claims_total(void)
{

UINT    index;
ULONG   total =  0;


    for (index = 0; index < CLAIM_THREADS; index++)
    {

        total =  total + claim_counts[index];
    }

    return(total);
}


static UINT  claim_threads_claiming(void)
{

UINT    index;
UINT    count =  0;


    for (index = 0; index < CLAIM_THREADS; index++)
    {

        if (claim_counts[index] != ((ULONG) 0))
        {
            count++;
        }
    }

    return(count);
}


/* Prototype for test control return.  */

void  test_control_return(UINT status);


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

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

UINT    status;
UINT    i;
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, 0,
            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 Owner Change Test................................ ERROR #1\n");
        test_control_return(1);
    }

    /* The claim thread is created stopped, at the test thread's own priority so
       that neither side preempts the other, and started once the pool has been
       fragmented.  */
    for (i = 0; i < CLAIM_THREADS; i++)
    {

        status =  tx_thread_create(&claim_threads[i], "claim thread", claim_thread_entry, (ULONG) i,
                pointer, TEST_STACK_SIZE_PRINTF,
                16, 16, TX_NO_TIME_SLICE, TX_DONT_START);
        pointer =  pointer + TEST_STACK_SIZE_PRINTF;

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

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

    /* Create the pool both sides work on.  */
    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 Owner Change Test................................ ERROR #3\n");
        test_control_return(1);
    }
}


/* Define the test thread.  */

static void    thread_0_entry(ULONG thread_input)
{

UINT    status;
UINT    chunk;
UINT    i;
UINT    allocated;
ULONG   rounds;
ULONG   claims_made;
ULONG   waited;
ULONG   test_core;


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

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

    /* Break the pool into fragments, one allocation at a time, until it has no
       room for another. Every block is then either in use or too small, so a
       further request walks all of them.  */
    allocated =  0;

    for (chunk = 0; chunk < BYTE_CHUNKS_MAX; chunk++)
    {

        if (tx_byte_allocate(&pool_0, &chunks[chunk], BYTE_CHUNK_SIZE, TX_NO_WAIT) != TX_SUCCESS)
        {

            /* The pool is full.  */
            break;
        }

        allocated++;
    }

    /* A pool with fewer fragments than the limit never gives the protection up
       inside the walk, so the window the claim threads aim at would not
       exist.  */
    if (allocated < BYTE_CHUNKS_REQUIRED)
    {

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

    /* Let the claim threads run on a core each. Every thread in this suite is
       created mapped to core 0 alone, and the test thread keeps that mapping,
       so excluding each claim thread from every core but its own puts one on
       each of the others and leaves the test thread's core to itself.  */
    status =  TX_SUCCESS;

    for (i = 0; i < CLAIM_THREADS; i++)
    {

        status +=  tx_thread_smp_core_exclude(&claim_threads[i],
                        ((((ULONG) 1) << TX_THREAD_SMP_MAX_CORES) - ((ULONG) 1)) &
                        (~(((ULONG) 1) << (i + ((UINT) CLAIM_CORE)))));
    }

    if (status != TX_SUCCESS)
    {

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

    test_core =  tx_thread_smp_core_get();

    for (i = 0; i < CLAIM_THREADS; i++)
    {

        status +=  tx_thread_resume(&claim_threads[i]);
    }

    if (status != TX_SUCCESS)
    {

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

    /* Wait for the rebalance to map it to its core. It records the core it
       lands on and says so on the way in, so this is the arrangement arriving
       rather than a fixed number of ticks guessed at.  */
    waited =  0;

    while ((claim_threads_started() < CLAIM_THREADS) && (waited < SETTLE_TICKS_MAX))
    {

        tx_thread_sleep(1);
        waited++;
    }

    if (claim_threads_started() < CLAIM_THREADS)
    {

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

    claims_enabled =  1;

    /* And wait for it to be claiming before any searching starts, so that the
       walks below are contended from the first one.  */
    waited =  0;

    while ((claim_threads_claiming() < CLAIM_THREADS) && (waited < SETTLE_TICKS_MAX))
    {

        tx_thread_sleep(1);
        waited++;
    }

    if (claim_threads_claiming() < CLAIM_THREADS)
    {

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

    /* Search the pool over and over while the claim threads take it away. Each
       request walks every fragment and gives the protection up once per limit's
       worth of blocks, which is the only moment at which the pool can change
       hands under it.  */
    claims_made =  claims_total();

    for (rounds = 0; rounds < ((ULONG) SEARCH_ROUNDS); rounds++)
    {

        status =  tx_byte_allocate(&pool_0, &chunks[allocated], BYTE_CHUNK_SIZE, TX_NO_WAIT);

        if (status != TX_NO_MEMORY)
        {

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

    /* Stand the claim thread down and wait for it to notice.  */
    claims_stopped =  1;

    tx_thread_sleep(SETTLE_TICKS_MAX);

    /* The claim thread has to have run somewhere other than the test thread's
       core, or nothing here was concurrent and the window was never contended.  */
    for (i = 0; i < CLAIM_THREADS; i++)
    {

        if (claim_counts[i] == ((ULONG) 0))
        {

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

        if (claim_cores[i] == test_core)
        {

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

    /* And it has to have gone on claiming while the searching was happening,
       rather than only before it: it is stood down after the last walk, so a
       total that did not move would mean the two sides never overlapped.  */
    if (claims_total() <= claims_made)
    {

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

    /* Give the pool back, so the test leaves the system as it found it.  */
    for (chunk = 0; chunk < allocated; chunk++)
    {

        if (tx_byte_release(chunks[chunk]) != TX_SUCCESS)
        {

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

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


/* Define the claim thread. It makes the same unsatisfiable request the test
   thread makes, so it claims the pool and then walks it, holding the protection
   for a limit's worth of blocks at a time.

   Walking is what makes the claim useful. A claim that only took the pool and
   returned would hold the protection for a few instructions, and the test
   thread would have to win the mutex against it in the gap between its own
   release and its immediate re-acquire -- a gap the releasing thread wins. A
   claim thread that walks is usually already holding the protection when the
   test thread reaches a window, which is the state the construct is written
   against.  */

static void    claim_thread_entry(ULONG thread_input)
{

UINT    index;
ULONG   claims;
VOID    *unused_ptr;


    index =  (UINT) thread_input;

    claim_cores[index] =  tx_thread_smp_core_get();
    claim_started[index] =  1;

    /* Stand by until the test thread is ready to search. Sleeping rather than
       spinning leaves the core to the rebalance while it settles.  */
    while (claims_enabled == ((ULONG) 0))
    {

        tx_thread_sleep(1);
    }

    claims =  0;

    while ((claims_stopped == ((ULONG) 0)) && (claims < ((ULONG) CLAIMS_CAP)))
    {

        (VOID) tx_byte_allocate(&pool_0, &unused_ptr, BYTE_CHUNK_SIZE, TX_NO_WAIT);

        claims++;
        claim_counts[index] =  claims;
    }
}