tx-thread-queue.h

Go to the documentation of this file.

/* SPDX-License-Identifier: BSD-2-Clause */
 
/*
 * 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
 
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 {
  TQDiscipline discipline;
 
  TQWait wait;
 
  TQEnqueueVariant enqueue_variant;
 
  TQDeadlock deadlock;
 
  rtems_id runner_id;
 
  rtems_tcb *runner_tcb;
 
  rtems_id worker_id[ TQ_WORKER_COUNT ];
 
  rtems_tcb *worker_tcb[ TQ_WORKER_COUNT ];
 
  volatile bool event_received[ TQ_WORKER_COUNT ];
 
  volatile bool busy_wait[ TQ_WORKER_COUNT ];
 
  volatile bool done[ TQ_WORKER_COUNT ];
 
  Atomic_Uint counter;
 
  uint32_t worker_counter[ TQ_WORKER_COUNT ];
 
  Status_Control status[ TQ_WORKER_COUNT ];
 
  union {
    rtems_id thread_queue_id;
 
    void *thread_queue_object;
  };
 
  rtems_id mutex_id[ TQ_MUTEX_COUNT ];
 
  T_scheduler_log_40 scheduler_log;
 
  void ( *get_properties )( struct TQContext *, TQWorkerKind );
 
  Status_Control ( *convert_status )( Status_Control );
 
  uint32_t how_many;
 
  uint32_t flush_count;
 
  jmp_buf before_enqueue;
 
  void ( *enqueue_prepare )( struct TQContext * );
 
  Status_Control ( *enqueue )( struct TQContext *, TQWait );
 
  void ( *enqueue_done )( struct TQContext * );
 
  Status_Control ( *surrender )( struct TQContext * );
 
  uint32_t ( *flush )( struct TQContext *, uint32_t, bool );
 
  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 {
  TQContext base;
 
  TQSemVariant variant;
 
  uint32_t ( *get_count )( struct TQSemContext * );
 
  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 {
  TQContext base;
 
  TQMtxProtocol protocol;
 
  TQMtxRecursive recursive;
 
  TQMtxOwnerCheck owner_check;
 
  rtems_task_priority priority_ceiling;
} TQMtxContext;
 
#ifdef __cplusplus
}
#endif
 
#endif /* _TX_THREAD_QUEUE_H */