path: root/test/smp/regression/threadx_thread_time_slice_walk_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 walks the whole of the ready list in the time-slice rebalance.

   When a thread's time slice expires, the kernel moves it to the end of the
   ready list at its priority and then looks for another thread at that same
   priority to give the core to. It walks the list from the next thread round to
   the thread it started with, and stops early on the first candidate it can
   use. The walk only runs to the end -- back round to the thread it started
   from -- when every other thread at that priority is already the thread its
   own core is executing, so there is nothing to hand the core to.

   That needs more than one core in use. With every thread mapped to core 0 only
   there is a single executing thread, so the first thread the walk looks at is
   not executing and the walk stops there. The workers below have their core
   exclusions cleared and run one to a core, which is the arrangement the walk
   needs and the only one that reaches it.

   The arrangement is asserted rather than waited for. Two of the three ways out
   of the walk are ruled out before it runs -- no worker has preemption
   threshold set, and none is excluded from the core whose slice expires -- so
   the only early exit left is the one that hands the core over, and that one
   overwrites the core's entry in the execution list. The entry still holding
   the same thread afterwards therefore means the walk ran to the end. The whole
   arrangement, the expiry and the check are held under one SMP protection, so
   nothing can move between them.

   How many cores the machine has does not matter. The execution list is the
   kernel's own, so a worker is the thread its core is executing whether or not
   that core is running at this instant.  */


#include   <stdio.h>
#include   "tx_api.h"
#define    TX_SOURCE_CODE
#define    TX_THREAD_SMP_SOURCE_CODE
#include   "tx_thread.h"
#include   "tx_timer.h"


/* The control thread keeps the core it is created on -- it is the only thread
   here that keeps the suite's default of core 0 alone -- and the workers take
   the rest.  */

#define CONTROL_PRIORITY            16
#define WORKER_PRIORITY             20
#define WORKERS                     (TX_THREAD_SMP_MAX_CORES - 1)

/* Long enough that the tick never expires a worker's slice while an attempt is
   being set up.  */

#define WORKER_SLICE                ((ULONG) 100)

/* The workers have to be mapped one to a core before the arrangement exists,
   which takes a few ticks after they are created. This is a bound, so a
   rebalance that never happens fails the test rather than hanging it.  */

#define ATTEMPTS                    ((UINT) 200)


static unsigned long   thread_0_counter =  0;
static TX_THREAD       thread_0;

static TX_THREAD       workers[WORKERS];
static volatile ULONG  worker_counter[WORKERS];

/* The workers spin while this is set. They must not block: a worker that
   suspends stops being the thread its core is executing, which is the whole of
   the arrangement.  */

static volatile UINT   workers_running =  TX_TRUE;


/* Define thread prototypes.  */

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


/* Prototype for test control return.  */

void  test_control_return(UINT status);


static void    worker_entry(ULONG thread_input)
{

    while (workers_running == TX_TRUE)
    {

        worker_counter[thread_input]++;
    }
}


/* The index of a worker, or WORKERS if the thread is not one.  */

static UINT  worker_index(TX_THREAD *thread_ptr)
{

UINT    i;


    for (i = ((UINT) 0); i < ((UINT) WORKERS); i++)
    {

        if (thread_ptr == &workers[i])
        {

            break;
        }
    }

    return(i);
}


/* Test for the arrangement the walk needs, and name the worker whose slice
   should expire. Called with the SMP protection held.

   Everything the walk tests is checked here, so that what the walk then does is
   decided rather than observed: the ready list at this priority holds the
   workers and nothing else, each worker is the thread its own core is
   executing, no two share a core, none has preemption threshold set, and none
   is excluded from any core. The named worker is not the tail of the list,
   because the kernel does not enter the walk at all for a thread already at the
   end.  */

static UINT  arrangement_holds(UINT *target_core, TX_THREAD **target)
{

UINT        i;
UINT        count;
ULONG       core;
ULONG       cores_seen;
TX_THREAD  *head_ptr;
TX_THREAD  *tail_ptr;
TX_THREAD  *thread_ptr;
UINT        holds =  TX_TRUE;


    head_ptr =  _tx_thread_priority_list[WORKER_PRIORITY];

    if (head_ptr == TX_NULL)
    {

        return(TX_FALSE);
    }

    tail_ptr =  head_ptr -> tx_thread_ready_previous;

    /* The ready list at this priority has to hold the workers and nothing
       else, or the walk has a thread in it this test knows nothing about.  */
    count =       ((UINT) 0);
    thread_ptr =  head_ptr;

    do
    {

        if (worker_index(thread_ptr) == ((UINT) WORKERS))
        {

            holds =  TX_FALSE;
        }

        count++;

        if (count > ((UINT) WORKERS))
        {

            holds =  TX_FALSE;
        }

        thread_ptr =  thread_ptr -> tx_thread_ready_next;

    } while ((thread_ptr != head_ptr) && (holds == TX_TRUE));

    if (count != ((UINT) WORKERS))
    {

        holds =  TX_FALSE;
    }

    /* Every worker has to be the thread its own core is executing, and no two
       of them may claim the same core.  */
    cores_seen =  ((ULONG) 0);

    for (i = ((UINT) 0); (i < ((UINT) WORKERS)) && (holds == TX_TRUE); i++)
    {

        core =  (ULONG) workers[i].tx_thread_smp_core_mapped;

        if ((workers[i].tx_thread_state != TX_READY) ||
            (workers[i].tx_thread_preempt_threshold != workers[i].tx_thread_priority) ||
            (workers[i].tx_thread_smp_cores_excluded != ((ULONG) 0)) ||
            (core >= ((ULONG) TX_THREAD_SMP_MAX_CORES)))
        {

            holds =  TX_FALSE;
        }
        else if ((_tx_thread_execute_ptr[core] != &workers[i]) ||
                 (_tx_thread_current_ptr[core] != &workers[i]))
        {

            holds =  TX_FALSE;
        }
        else if ((cores_seen & (((ULONG) 1) << core)) != ((ULONG) 0))
        {

            holds =  TX_FALSE;
        }
        else
        {

            cores_seen =  cores_seen | (((ULONG) 1) << core);
        }
    }

    /* Name a worker that is not already at the end of the list.  */
    if (holds == TX_TRUE)
    {

        holds =  TX_FALSE;

        for (i = ((UINT) 0); i < ((UINT) WORKERS); i++)
        {

            if (&workers[i] != tail_ptr)
            {

                *target =       &workers[i];
                *target_core =  (UINT) workers[i].tx_thread_smp_core_mapped;
                holds =         TX_TRUE;
                break;
            }
        }
    }

    return(holds);
}


/* Build the arrangement, expire one worker's slice, and check what the walk
   did -- all under one SMP protection, so the tick cannot move a thread
   between the three.

   The slice is armed through the published service rather than by writing the
   countdown, which is what sets it on SMP for a thread running on its mapped
   core. The expiry itself is driven by calling the routine the timer interrupt
   calls, inside the protection the timer interrupt holds when it calls it.  */

static UINT  attempt_walk(void)
{

TX_INTERRUPT_SAVE_AREA

UINT        i;
UINT        core =  ((UINT) 0);
TX_THREAD  *target =  TX_NULL;
TX_THREAD  *head_ptr;
ULONG       old_slice;
UINT        status =  TX_NOT_DONE;


    TX_DISABLE

    if (arrangement_holds(&core, &target) == TX_TRUE)
    {

        /* Push the other workers' slices out of reach, so exactly one expires
           in this pass and the walk it runs is the one being measured.  */
        for (i = ((UINT) 0); i < ((UINT) WORKERS); i++)
        {

            if (&workers[i] != target)
            {

                (VOID) tx_thread_time_slice_change(&workers[i], WORKER_SLICE, &old_slice);
            }
        }

        (VOID) tx_thread_time_slice_change(target, ((ULONG) 1), &old_slice);

        /* One pass takes the armed slice to zero and runs the walk.  */
        _tx_thread_time_slice();

        head_ptr =  _tx_thread_priority_list[WORKER_PRIORITY];

        /* The expiry ran: the thread was given a fresh slice and moved to the
           end of the ready list.  */
        if ((_tx_timer_time_slice[core] == ((ULONG) 1)) &&
            (head_ptr != TX_NULL) &&
            (head_ptr -> tx_thread_ready_previous == target))
        {

            /* And the walk ran to the end: the only early exit left would have
               handed this core to another thread, which overwrites this
               entry.  */
            if (_tx_thread_execute_ptr[core] == target)
            {

                status =  TX_SUCCESS;
            }
        }

        /* Put the slice back, whatever happened.  */
        (VOID) tx_thread_time_slice_change(target, WORKER_SLICE, &old_slice);
    }

    TX_RESTORE

    return(status);
}


static void    thread_0_entry(ULONG thread_input)
{

UINT    i;
UINT    status;
UINT    attempt;


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

    /* Inform user of success getting to this test.  */
    printf("Running Thread Time Slice Walk Test............................... ");

    /* Let the workers run on any core. Every thread in this suite is created
       mapped to core 0 alone, and the arrangement needs them spread.  */
    status =  TX_SUCCESS;

    for (i = ((UINT) 0); i < ((UINT) WORKERS); i++)
    {

        status +=  tx_thread_smp_core_exclude(&workers[i], ((ULONG) 0));
    }

    if (status != TX_SUCCESS)
    {

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

    /* The rebalance takes a few ticks to map them one to a core.  */
    status =  TX_NOT_DONE;

    for (attempt = ((UINT) 0); attempt < ATTEMPTS; attempt++)
    {

        status =  attempt_walk();

        if (status == TX_SUCCESS)
        {

            break;
        }

        tx_thread_sleep(((ULONG) 1));
    }

    workers_running =  TX_FALSE;

    if (status != TX_SUCCESS)
    {

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

    /* The workers were running rather than merely ready, which is what made
       them the threads their cores were executing.  */
    for (i = ((UINT) 0); i < ((UINT) WORKERS); i++)
    {

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

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

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


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

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

UINT    i;
UINT    status;
CHAR    *pointer;


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

    status =  tx_thread_create(&thread_0, "thread 0", thread_0_entry, 0,
            pointer, TEST_STACK_SIZE_PRINTF,
            CONTROL_PRIORITY, CONTROL_PRIORITY, TX_NO_TIME_SLICE, TX_AUTO_START);
    pointer =  pointer + TEST_STACK_SIZE_PRINTF;

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

        printf("Running Thread Time Slice Walk Test............................... ERROR #1\n");
        test_control_return(1);
    }

    /* The workers, all at one priority, all with a time slice, and with
       preemption threshold equal to their priority so that none of them stops
       the walk on its first test.  */
    for (i = ((UINT) 0); i < ((UINT) WORKERS); i++)
    {

        status =  tx_thread_create(&workers[i], "worker", worker_entry, (ULONG) i,
                pointer, TEST_STACK_SIZE_PRINTF,
                WORKER_PRIORITY, WORKER_PRIORITY, WORKER_SLICE, TX_AUTO_START);
        pointer =  pointer + TEST_STACK_SIZE_PRINTF;

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

            printf("Running Thread Time Slice Walk Test............................... ERROR #1\n");
            test_control_return(1);
        }
    }
}