LXR 6.1/​testsuites/​validation/​tx-thread-queue.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:24:54

 /* SPDX-License-Identifier: BSD-2-Clause */
 
 /**
  * @file
  *
  * @ingroup RTEMSTestSuitesValidation
  *
  * @brief This header file provides the functions to test the
  *   @ref RTEMSScoreThreadQueue.
  */
 
 /*
  * Copyright (C) 2021 embedded brains GmbH & Co. KG
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
  * 2. Redistributions in binary form must reproduce the above copyright
  *    notice, this list of conditions and the following disclaimer in the
  *    documentation and/or other materials provided with the distribution.
  *
  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  */
 
 #ifndef _TX_THREAD_QUEUE_H
 #define _TX_THREAD_QUEUE_H
 
 #include "tx-support.h"
 
 #include <rtems/test-scheduler.h>
 #include <rtems/score/atomic.h>
 #include <rtems/score/status.h>
 
 #include <setjmp.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
  * @addtogroup RTEMSTestSuitesValidation
  *
  * @{
  */
 
 typedef enum {
   TQ_NODE_ONLY,
   TQ_NODE_VITAL,
   TQ_NODE_DISPENSABLE
 } TQNodeKind;
 
 typedef enum {
   TQ_WAIT_STATE_BLOCKED,
   TQ_WAIT_STATE_INTEND_TO_BLOCK,
   TQ_WAIT_STATE_READY_AGAIN
 } TQWaitState;
 
 typedef enum {
   TQ_BLOCKER_A,
   TQ_BLOCKER_B,
   TQ_BLOCKER_C,
   TQ_BLOCKER_D,
   TQ_BLOCKER_E,
   TQ_WORKER_F,
   TQ_HELPER_A,
   TQ_HELPER_B,
   TQ_HELPER_C,
   TQ_WORKER_COUNT
 } TQWorkerKind;
 
 typedef enum {
   TQ_MUTEX_A,
   TQ_MUTEX_B,
   TQ_MUTEX_C,
   TQ_MUTEX_D,
   TQ_MUTEX_NO_PROTOCOL,
   TQ_MUTEX_FIFO,
   TQ_MUTEX_COUNT
 } TQMutex;
 
 typedef enum {
   TQ_FIFO,
   TQ_PRIORITY
 } TQDiscipline;
 
 typedef enum {
   TQ_NO_WAIT,
   TQ_WAIT_FOREVER,
   TQ_WAIT_TIMED
 } TQWait;
 
 typedef enum {
   TQ_DEADLOCK_STATUS,
   TQ_DEADLOCK_FATAL
 } TQDeadlock;
 
 typedef enum {
   TQ_EVENT_ENQUEUE_PREPARE = RTEMS_EVENT_0,
   TQ_EVENT_ENQUEUE = RTEMS_EVENT_1,
   TQ_EVENT_ENQUEUE_DONE = RTEMS_EVENT_2,
   TQ_EVENT_SURRENDER = RTEMS_EVENT_3,
   TQ_EVENT_RUNNER_SYNC = RTEMS_EVENT_4,
   TQ_EVENT_RUNNER_SYNC_2 = RTEMS_EVENT_5,
   TQ_EVENT_HELPER_A_SYNC = RTEMS_EVENT_6,
   TQ_EVENT_HELPER_B_SYNC = RTEMS_EVENT_7,
   TQ_EVENT_MUTEX_A_OBTAIN = RTEMS_EVENT_8,
   TQ_EVENT_MUTEX_A_RELEASE = RTEMS_EVENT_9,
   TQ_EVENT_MUTEX_B_OBTAIN = RTEMS_EVENT_10,
   TQ_EVENT_MUTEX_B_RELEASE = RTEMS_EVENT_11,
   TQ_EVENT_BUSY_WAIT = RTEMS_EVENT_12,
   TQ_EVENT_FLUSH_ALL = RTEMS_EVENT_13,
   TQ_EVENT_FLUSH_PARTIAL = RTEMS_EVENT_14,
   TQ_EVENT_SCHEDULER_RECORD_START = RTEMS_EVENT_15,
   TQ_EVENT_SCHEDULER_RECORD_STOP = RTEMS_EVENT_16,
   TQ_EVENT_TIMEOUT = RTEMS_EVENT_17,
   TQ_EVENT_MUTEX_NO_PROTOCOL_OBTAIN = RTEMS_EVENT_18,
   TQ_EVENT_MUTEX_NO_PROTOCOL_RELEASE = RTEMS_EVENT_19,
   TQ_EVENT_ENQUEUE_FATAL = RTEMS_EVENT_20,
   TQ_EVENT_MUTEX_C_OBTAIN = RTEMS_EVENT_21,
   TQ_EVENT_MUTEX_C_RELEASE = RTEMS_EVENT_22,
   TQ_EVENT_MUTEX_FIFO_OBTAIN = RTEMS_EVENT_23,
   TQ_EVENT_MUTEX_FIFO_RELEASE = RTEMS_EVENT_24,
   TQ_EVENT_ENQUEUE_TIMED = RTEMS_EVENT_25,
   TQ_EVENT_MUTEX_D_OBTAIN = RTEMS_EVENT_26,
   TQ_EVENT_MUTEX_D_RELEASE = RTEMS_EVENT_27,
   TQ_EVENT_PIN = RTEMS_EVENT_28,
   TQ_EVENT_UNPIN = RTEMS_EVENT_29,
   TQ_EVENT_COUNT = RTEMS_EVENT_30
 } TQEvent;
 
 typedef enum {
   TQ_ENQUEUE_BLOCKS,
   TQ_ENQUEUE_STICKY
 } TQEnqueueVariant;
 
 typedef struct TQContext {
   /**
    * @brief This member defines the thread queue discipline.
    */
   TQDiscipline discipline;
 
   /**
    * @brief This member defines the enqueue wait behaviour.
    *
    * If TQ_NO_WAIT is used, then no thread queue enqueue shall be performed.
    */
   TQWait wait;
 
   /**
    * @brief This member defines the enqueue variant.
    */
   TQEnqueueVariant enqueue_variant;
 
   /**
    * @brief This member defines the deadlock enqueue behaviour.
    */
   TQDeadlock deadlock;
 
   /**
    * @brief This member contains the runner task identifier.
    */
   rtems_id runner_id;
 
   /**
    * @brief This member contains a reference to the runner task control block.
    */
   rtems_tcb *runner_tcb;
 
   /**
    * @brief This member contains the worker task identifiers.
    */
   rtems_id worker_id[ TQ_WORKER_COUNT ];
 
   /**
    * @brief This member contains references to the worker task control
    *   blocks.
    */
   rtems_tcb *worker_tcb[ TQ_WORKER_COUNT ];
 
   /**
    * @brief When a worker received an event, the corresponding element shall be
    *   set to true.
    */
   volatile bool event_received[ TQ_WORKER_COUNT ];
 
   /**
    * @brief If this member is true, then the worker shall busy wait on request.
    */
   volatile bool busy_wait[ TQ_WORKER_COUNT ];
 
   /**
    * @brief When a worker is done processing its current event set, the
    *   corresponding element shall be set to true.
    */
   volatile bool done[ TQ_WORKER_COUNT ];
 
   /**
    * @brief This member provides the counter used for the worker counters.
    */
   Atomic_Uint counter;
 
   /**
    * @brief When a worker returned from TQEnqueue() the counter is incremented
    * and stored in this member.
    */
   uint32_t worker_counter[ TQ_WORKER_COUNT ];
 
   /**
    * @brief This member contains the last return status of a TQEnqueue() of the
    *   corresponding worker.
    */
   Status_Control status[ TQ_WORKER_COUNT ];
 
   union {
     /**
      * @brief This member contains the identifier of an object providing the
      *   thread queue under test.
      */
     rtems_id thread_queue_id;
 
     /**
      * @brief This member contains the reference to object containing the
      *   thread queue under test.
      */
     void *thread_queue_object;
   };
 
   /**
    * @brief This member contains the identifier of priority inheritance
    *   mutexes.
    */
   rtems_id mutex_id[ TQ_MUTEX_COUNT ];
 
   /**
    * @brief This member provides the scheduler log.
    */
   T_scheduler_log_40 scheduler_log;
 
   /**
    * @brief This member provides the get properties handler.
    */
   void ( *get_properties )( struct TQContext *, TQWorkerKind );
 
   /**
    * @brief This member provides the status convert handler.
    */
   Status_Control ( *convert_status )( Status_Control );
 
   /**
    * @brief This this member specifies how many threads shall be enqueued.
    */
   uint32_t how_many;
 
   /**
    * @brief This this member contains the count of the least recently flushed
    *   threads.
    */
   uint32_t flush_count;
 
   /**
    * @brief This this member provides a context to jump back to before the
    *   enqueue.
    */
   jmp_buf before_enqueue;
 
   /**
    * @brief This member provides the thread queue enqueue prepare handler.
    */
   void ( *enqueue_prepare )( struct TQContext * );
 
   /**
    * @brief This member provides the thread queue enqueue handler.
    */
   Status_Control ( *enqueue )( struct TQContext *, TQWait );
 
   /**
    * @brief This member provides the thread queue enqueue done handler.
    */
   void ( *enqueue_done )( struct TQContext * );
 
   /**
    * @brief This member provides the thread queue surrender handler.
    */
   Status_Control ( *surrender )( struct TQContext * );
 
   /**
    * @brief This member provides the thread queue flush handler.
    *
    * The second parameter specifies the count of enqueued threads.  While the
    * third parameter is true, all enqueued threads shall be extracted,
    * otherwise the thread queue shall be partially flushed.  The handler shall
    * return the count of flushed threads.
    */
   uint32_t ( *flush )( struct TQContext *, uint32_t, bool );
 
   /**
    * @brief This member provides the get owner handler.
    */
   rtems_tcb *( *get_owner )( struct TQContext * );
 } TQContext;
 
 void TQSend(
   TQContext      *ctx,
   TQWorkerKind    worker,
   rtems_event_set events
 );
 
 void TQSendAndWaitForExecutionStop(
   TQContext      *ctx,
   TQWorkerKind    worker,
   rtems_event_set events
 );
 
 void TQSendAndWaitForIntendToBlock(
   TQContext      *ctx,
   TQWorkerKind    worker,
   rtems_event_set events
 );
 
 void TQSendAndWaitForExecutionStopOrIntendToBlock(
   TQContext      *ctx,
   TQWorkerKind    worker,
   rtems_event_set events
 );
 
 void TQSendAndSynchronizeRunner(
   TQContext      *ctx,
   TQWorkerKind    worker,
   rtems_event_set events
 );
 
 void TQWaitForEventsReceived( const TQContext *ctx, TQWorkerKind worker );
 
 void TQWaitForIntendToBlock( const TQContext *ctx, TQWorkerKind worker );
 
 void TQWaitForExecutionStop( const TQContext *ctx, TQWorkerKind worker );
 
 void TQClearDone( TQContext *ctx, TQWorkerKind worker );
 
 void TQWaitForDone( const TQContext *ctx, TQWorkerKind worker );
 
 void TQSynchronizeRunner( void );
 
 void TQSynchronizeRunner2( void );
 
 void TQResetCounter( TQContext *ctx );
 
 uint32_t TQGetCounter( const TQContext *ctx );
 
 uint32_t TQGetWorkerCounter( const TQContext *ctx, TQWorkerKind worker );
 
 void TQMutexObtain( const TQContext *ctx, TQMutex mutex );
 
 void TQMutexRelease( const TQContext *ctx, TQMutex mutex );
 
 void TQSetPriority(
   const TQContext *ctx,
   TQWorkerKind     worker,
   Priority         priority
 );
 
 Priority TQGetPriority( const TQContext *ctx, TQWorkerKind worker );
 
 void TQSetScheduler(
   const TQContext *ctx,
   TQWorkerKind     worker,
   rtems_id         scheduler_id,
   Priority         priority
 );
 
 void TQInitialize( TQContext *ctx );
 
 void TQDestroy( TQContext *ctx );
 
 void TQReset( TQContext *ctx );
 
 void TQSortMutexesByID( TQContext *ctx );
 
 void TQGetProperties( TQContext *ctx, TQWorkerKind enqueued_worker );
 
 Status_Control TQConvertStatus( TQContext *ctx, Status_Control status );
 
 void TQEnqueuePrepare( TQContext *ctx );
 
 Status_Control TQEnqueue( TQContext *ctx, TQWait wait );
 
 Status_Control TQEnqueueFatal( TQContext *ctx );
 
 void TQEnqueueDone( TQContext *ctx );
 
 Status_Control TQSurrender( TQContext *ctx );
 
 void TQFlush( TQContext *ctx, bool flush_all );
 
 rtems_tcb *TQGetOwner( TQContext *ctx );
 
 void TQSchedulerRecordStart( TQContext *ctx );
 
 void TQSchedulerRecordStop( TQContext *ctx );
 
 const T_scheduler_event *TQGetNextAny( TQContext *ctx, size_t *index );
 
 const T_scheduler_event *TQGetNextBlock( TQContext *ctx, size_t *index );
 
 const T_scheduler_event *TQGetNextUnblock( TQContext *ctx, size_t *index );
 
 const T_scheduler_event *TQGetNextUpdatePriority(
   TQContext *ctx,
   size_t    *index
 );
 
 const T_scheduler_event *TQGetNextAskForHelp( TQContext *ctx, size_t *index );
 
 void TQDoNothing( TQContext *ctx );
 
 Status_Control TQDoNothingSuccessfully( TQContext *ctx );
 
 Status_Control TQConvertStatusClassic( Status_Control status );
 
 Status_Control TQConvertStatusPOSIX( Status_Control status );
 
 void TQEnqueuePrepareDefault( TQContext *ctx );
 
 void TQEnqueueDoneDefault( TQContext *ctx );
 
 Status_Control TQEnqueueClassicSem( TQContext *ctx, TQWait wait );
 
 Status_Control TQSurrenderClassicSem( TQContext *ctx );
 
 rtems_tcb *TQGetOwnerClassicSem( TQContext *ctx );
 
 typedef enum {
   TQ_SEM_BINARY,
   TQ_SEM_COUNTING
 } TQSemVariant;
 
 typedef struct TQSemContext {
   /**
    * @brief This member contains the base thread queue test context.
    */
   TQContext base;
 
   /**
    * @brief This member defines the semaphore variant.
    */
   TQSemVariant variant;
 
   /**
    * @brief This member provides the semaphore get count handler.
    */
   uint32_t ( *get_count )( struct TQSemContext * );
 
   /**
    * @brief This member provides the semaphore set count handler.
    */
   void ( *set_count )( struct TQSemContext *, uint32_t );
 } TQSemContext;
 
 Status_Control TQSemSurrender( TQSemContext *ctx );
 
 uint32_t TQSemGetCount( TQSemContext *ctx );
 
 void TQSemSetCount( TQSemContext *ctx, uint32_t count );
 
 Status_Control TQSemSurrenderClassic( TQSemContext *ctx );
 
 uint32_t TQSemGetCountClassic( TQSemContext *ctx );
 
 void TQSemSetCountClassic( TQSemContext *ctx, uint32_t count );
 
 typedef enum {
   TQ_MTX_NO_PROTOCOL,
   TQ_MTX_PRIORITY_INHERIT,
   TQ_MTX_PRIORITY_CEILING,
   TQ_MTX_MRSP
 } TQMtxProtocol;
 
 typedef enum {
   TQ_MTX_RECURSIVE_ALLOWED,
   TQ_MTX_RECURSIVE_DEADLOCK,
   TQ_MTX_RECURSIVE_UNAVAILABLE
 } TQMtxRecursive;
 
 typedef enum {
   TQ_MTX_NO_OWNER_CHECK,
   TQ_MTX_CHECKS_OWNER
 } TQMtxOwnerCheck;
 
 typedef struct TQMtxContext {
   /**
    * @brief This member contains the base thread queue test context.
    */
   TQContext base;
 
   /**
    * @brief This member defines the locking protocol.
    */
   TQMtxProtocol protocol;
 
   /**
    * @brief This member defines the recursive seize behaviour.
    */
   TQMtxRecursive recursive;
 
   /**
    * @brief This member defines the owner check behaviour.
    */
   TQMtxOwnerCheck owner_check;
 
   /**
    * @brief This member defines the priority ceiling of the mutex.
    *
    * Use PRIO_INVALID to indicate that the mutex does not provide a priority
    * ceiling.
    */
   rtems_task_priority priority_ceiling;
 } TQMtxContext;
 
 /** @} */
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* _TX_THREAD_QUEUE_H */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team