path: root/test/tx/regression/threadx_mutex_misra_prioritize_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 two mutex put release loops round a second time.

   Under TX_MISRA_ENABLE the mutex put calls the prioritize processing through a
   loop rather than once, so that the call's result is read and the rule about
   discarding a return value is met. The prioritize processing sets its status to
   success and passes it through a shim function that discards its argument and
   returns success, so the loop's test can only ever be false on the first pass
   and the arm that goes round again is never taken. The other six build
   configurations compile a plain call with no loop and no branch at all.

   The shim is the only thing in the construct that is not a constant, and on
   this port the prioritize processing is its only caller. The test therefore
   defines the shim itself. The kernel is built shared and every internal call to
   the shim goes through the procedure linkage table, so the definition in this
   executable is the one the kernel reaches, and a shim that fails once and
   succeeds on the next call sends each loop round exactly twice and leaves the
   mutex, the suspension list and the priorities as the kernel expects them.

   Read the coverage this contributes with that in mind: it is coverage of a
   kernel whose MISRA shim is the test's rather than the library's. Nothing else
   in the kernel is replaced, the prioritize processing runs unaltered and is
   idempotent, and the shim's own body is covered by the other tests, which call
   it through the same loops.

   The two loops sit on different paths through a single put -- one restores the
   releasing thread's priority while two or more threads are still suspended, the
   other runs after the first of them has been taken off the list. One release of
   a mutex with priority inheritance and two suspended waiters reaches both. The
   scenario runs in every configuration; only the assertions about the shim are
   specific to the MISRA builds.  */


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


/* The priorities the test runs at. Both waiters are above the test thread, and
   the second is above the first, so that each of them in turn preempts the
   thread holding the mutex and suspends on it.  */

#define TEST_PRIORITY               16
#define FIRST_WAITER_PRIORITY       9
#define SECOND_WAITER_PRIORITY      8

#define SCRATCH_STACK_SIZE          TEST_STACK_SIZE_PRINTF


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 unsigned long   thread_2_counter =  0;
static TX_THREAD       thread_2;

static TX_MUTEX        mutex_0;

static UINT            waiter_status =  TX_SUCCESS;


#ifdef TX_MISRA_ENABLE

/* While this is set the shim below refuses every other call.  */

static volatile UINT   shim_armed =  TX_FALSE;

/* Alternates, so that a loop calling the shim until it succeeds goes round
   exactly twice however many loops the release runs.  */

static volatile UINT   shim_refuse_next =  TX_TRUE;

/* How many times the shim has refused, which is how many times a loop has gone
   round again.  */

static volatile ULONG  shim_refusals =  0;


/* The MISRA status shim, defined here so that it is this one the kernel calls.
   The library's returns the status it is given; this one withholds success on
   alternate calls while it is armed.  */

UINT  _tx_misra_status_get(UINT status)
{

    if (shim_armed == TX_TRUE)
    {

        if (shim_refuse_next == TX_TRUE)
        {

            shim_refuse_next =  TX_FALSE;
            shim_refusals++;

            return(TX_NOT_DONE);
        }

        shim_refuse_next =  TX_TRUE;
    }

    return(status);
}
#endif


/* Define thread prototypes.  */

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


/* Prototype for test control return.  */

void  test_control_return(UINT status);


/* Each waiter takes the mutex, gives it straight back and suspends, so that the
   release under test hands the mutex on and the test thread gets the processor
   back with both waiters off the ready list.  */

static void    waiter_entry(TX_THREAD *thread_ptr, unsigned long *counter)
{

UINT    status;


    while (1)
    {

        (*counter)++;

        status =  tx_mutex_get(&mutex_0, TX_WAIT_FOREVER);

        if (status != TX_SUCCESS)
        {
            waiter_status =  status;
        }

        status =  tx_mutex_put(&mutex_0);

        if (status != TX_SUCCESS)
        {
            waiter_status =  status;
        }

        tx_thread_suspend(thread_ptr);
    }
}


static void    thread_1_entry(ULONG thread_input)
{

    waiter_entry(&thread_1, &thread_1_counter);
}


static void    thread_2_entry(ULONG thread_input)
{

    waiter_entry(&thread_2, &thread_2_counter);
}


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 Mutex MISRA Prioritize Test................................ ");

    status =  tx_mutex_get(&mutex_0, TX_NO_WAIT);

    if (status != TX_SUCCESS)
    {

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

    /* The lower of the two waiters first, so that the higher one preempts the
       inherited priority the first leaves behind.  */
    status =  tx_thread_resume(&thread_1);

    if (status != TX_SUCCESS)
    {

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

    status =  tx_thread_resume(&thread_2);

    if (status != TX_SUCCESS)
    {

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

    /* Both waiters are now suspended on the mutex.  */
    if (mutex_0.tx_mutex_suspended_count != ((UINT) 2))
    {

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

#ifdef TX_MISRA_ENABLE
    shim_armed =  TX_TRUE;
#endif

    /* The release. It restores this thread's own priority with both waiters
       still suspended, and then takes the first of them off the list with the
       second still on it, which are the two loops.  */
    status =  tx_mutex_put(&mutex_0);

#ifdef TX_MISRA_ENABLE
    shim_armed =  TX_FALSE;
#endif

    if (status != TX_SUCCESS)
    {

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

    if (waiter_status != TX_SUCCESS)
    {

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

    /* Both waiters ran, so the mutex was handed on twice.  */
    if ((thread_1_counter != ((unsigned long) 1)) || (thread_2_counter != ((unsigned long) 1)))
    {

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

    /* The release left nothing suspended and nobody owning the mutex.  */
    if ((mutex_0.tx_mutex_suspended_count != ((UINT) 0)) || (mutex_0.tx_mutex_ownership_count != ((UINT) 0)))
    {

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

    /* The inherited priority was given back.  */
    if (thread_0.tx_thread_priority != ((UINT) TEST_PRIORITY))
    {

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

#ifdef TX_MISRA_ENABLE

    /* Both loops went round again, which is what the shim was armed for. A
       refusal count below two means the kernel reached the library's shim rather
       than this one and the arm under test was not taken.  */
    if (shim_refusals < ((ULONG) 2))
    {

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

    /* 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_mutex_misra_prioritize_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;

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

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

        printf("Running Mutex MISRA Prioritize Test................................ ERROR #1\n");
        test_control_return(1);
    }

    status =  tx_thread_create(&thread_1, "thread 1", thread_1_entry, 1,
            pointer, SCRATCH_STACK_SIZE,
            FIRST_WAITER_PRIORITY, FIRST_WAITER_PRIORITY, TX_NO_TIME_SLICE, TX_DONT_START);
    pointer =  pointer + SCRATCH_STACK_SIZE;

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

        printf("Running Mutex MISRA Prioritize Test................................ ERROR #1\n");
        test_control_return(1);
    }

    status =  tx_thread_create(&thread_2, "thread 2", thread_2_entry, 2,
            pointer, SCRATCH_STACK_SIZE,
            SECOND_WAITER_PRIORITY, SECOND_WAITER_PRIORITY, TX_NO_TIME_SLICE, TX_DONT_START);
    pointer =  pointer + SCRATCH_STACK_SIZE;

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

        printf("Running Mutex MISRA Prioritize Test................................ ERROR #1\n");
        test_control_return(1);
    }

    /* Priority inheritance, which is what puts the two release loops on the
       path.  */
    status =  tx_mutex_create(&mutex_0, "mutex 0", TX_INHERIT);

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

        printf("Running Mutex MISRA Prioritize Test................................ ERROR #1\n");
        test_control_return(1);
    }
}