LXR 6.1/​testsuites/​validation/​tx-support.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 support functions for the validation
  *   test cases.
  */
 
 /*
  * 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_SUPPORT_H
 #define _TX_SUPPORT_H
 
 #include <rtems.h>
 #include <rtems/irq-extension.h>
 #include <rtems/score/atomic.h>
 #include <rtems/score/threadq.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
  * @addtogroup RTEMSTestSuitesValidation
  *
  * @{
  */
 
 typedef enum {
   PRIO_PSEUDO_ISR,
   PRIO_VERY_ULTRA_HIGH,
   PRIO_ULTRA_HIGH,
   PRIO_VERY_HIGH,
   PRIO_HIGH,
   PRIO_NORMAL,
   PRIO_LOW,
   PRIO_VERY_LOW,
   PRIO_ULTRA_LOW
 } Priority;
 
 /**
  * @brief This constants represents the default priority of the runner task.
  */
 #define PRIO_DEFAULT 1
 
 /**
  * @brief This constants represents an invalid RTEMS task priority value.
  *
  * It should be an invalid priority value which is not equal to
  * RTEMS_CURRENT_PRIORITY and RTEMS_TIMER_SERVER_DEFAULT_PRIORITY.
  */
 #define PRIO_INVALID 0xfffffffe
 
 /**
  * @brief This constants represents a priority which is close to the priority
  *   of the idle thread.
  *
  * It may be used for the runner thread together with PRIO_FLEXIBLE for worker
  * threads.
  */
 #define PRIO_NEARLY_IDLE 126
 
 /**
  * @brief This constants represents a priority with a wider range of higher and
  *   lower priorities around it.
  *
  * It may be used for the worker threads together with PRIO_NEARLY_IDLE for the
  * runner thread.
  */
 #define PRIO_FLEXIBLE 64
 
 /**
  * @brief This constants represents an invalid RTEMS object identifier.
  */
 #define INVALID_ID 0xfffffffd
 
 /**
  * @brief This constants represents an object name for tests.
  */
 #define OBJECT_NAME rtems_build_name( 'T', 'E', 'S', 'T' )
 
 #define CreateTask( name, priority ) \
   DoCreateTask( \
     rtems_build_name( name[ 0 ], name[ 1 ], name[ 2 ], name[ 3 ] ), \
     priority \
   )
 
 #define SCHEDULER_A_ID 0xf010001
 
 #define SCHEDULER_B_ID 0xf010002
 
 #define SCHEDULER_C_ID 0xf010003
 
 #define SCHEDULER_D_ID 0xf010004
 
 rtems_id DoCreateTask( rtems_name name, rtems_task_priority priority );
 
 void StartTask( rtems_id id, rtems_task_entry entry, void *arg );
 
 void DeleteTask( rtems_id id );
 
 void SuspendTask( rtems_id id );
 
 void SuspendSelf( void );
 
 void ResumeTask( rtems_id id );
 
 bool IsTaskSuspended( rtems_id id );
 
 rtems_event_set QueryPendingEvents( void );
 
 rtems_event_set PollAnyEvents( void );
 
 rtems_event_set ReceiveAnyEvents( void );
 
 rtems_event_set ReceiveAnyEventsTimed( rtems_interval ticks );
 
 void ReceiveAllEvents( rtems_event_set events );
 
 void SendEvents( rtems_id id, rtems_event_set events );
 
 rtems_mode GetMode( void );
 
 rtems_mode SetMode( rtems_mode set, rtems_mode mask );
 
 rtems_task_priority GetPriority( rtems_id id );
 
 rtems_task_priority GetPriorityByScheduler(
   rtems_id task_id,
   rtems_id scheduler_id
 );
 
 rtems_task_priority SetPriority( rtems_id id, rtems_task_priority priority );
 
 rtems_task_priority GetSelfPriority( void );
 
 rtems_task_priority SetSelfPriority( rtems_task_priority priority );
 
 rtems_task_priority SetSelfPriorityNoYield( rtems_task_priority priority );
 
 rtems_id GetScheduler( rtems_id id );
 
 rtems_id GetSelfScheduler( void );
 
 void SetScheduler(
   rtems_id            task_id,
   rtems_id            scheduler_id,
   rtems_task_priority priority
 );
 
 void SetSelfScheduler( rtems_id scheduler_id, rtems_task_priority priority );
 
 void GetAffinity( rtems_id id, cpu_set_t *set );
 
 void GetSelfAffinity( cpu_set_t *set );
 
 void SetAffinity( rtems_id id, const cpu_set_t *set );
 
 void SetSelfAffinity( const cpu_set_t *set );
 
 void SetAffinityOne( rtems_id id, uint32_t cpu_index );
 
 void SetSelfAffinityOne( uint32_t cpu_index );
 
 void SetAffinityAll( rtems_id id );
 
 void SetSelfAffinityAll( void );
 
 void Yield( void );
 
 void YieldTask( rtems_id id );
 
 void AddProcessor( rtems_id scheduler_id, uint32_t cpu_index );
 
 void RemoveProcessor( rtems_id scheduler_id, uint32_t cpu_index );
 
 rtems_id CreateMutex( void );
 
 rtems_id CreateMutexNoProtocol( void );
 
 rtems_id CreateMutexFIFO( void );
 
 bool IsMutexOwner( rtems_id id );
 
 void DeleteMutex( rtems_id id );
 
 void ObtainMutex( rtems_id id );
 
 void ObtainMutexTimed( rtems_id id, rtems_interval ticks );
 
 void ObtainMutexDeadlock( rtems_id id );
 
 void ReleaseMutex( rtems_id id );
 
 struct Thread_queue_Queue;
 
 struct Thread_queue_Queue *GetMutexThreadQueue( rtems_id id );
 
 void RestoreRunnerASR( void );
 
 void RestoreRunnerMode( void );
 
 void RestoreRunnerPriority( void );
 
 void RestoreRunnerScheduler( void );
 
 struct _Thread_Control;
 
 struct _Thread_Control *GetThread( rtems_id id );
 
 struct _Thread_Control *GetExecuting( void );
 
 void KillZombies( void );
 
 void WaitForExecutionStop( rtems_id task_id );
 
 void WaitForIntendToBlock( rtems_id task_id );
 
 void WaitForHeir( uint32_t cpu_index, rtems_id task_id );
 
 void WaitForNextTask( uint32_t cpu_index, rtems_id task_id );
 
 typedef enum {
   TASK_TIMER_INVALID,
   TASK_TIMER_INACTIVE,
   TASK_TIMER_TICKS,
   TASK_TIMER_REALTIME,
   TASK_TIMER_MONOTONIC
 } TaskTimerState;
 
 typedef struct {
   TaskTimerState state;
   uint64_t expire_ticks;
   struct timespec expire_timespec;
 } TaskTimerInfo;
 
 void GetTaskTimerInfo( rtems_id id, TaskTimerInfo *info );
 
 void GetTaskTimerInfoByThread(
   struct _Thread_Control *thread,
   TaskTimerInfo          *info
 );
 
 void ClockTick( void );
 
 /**
  * @brief Simulates a clock tick with the final expire time point of
  *   UINT64_MAX for all clocks.
  *
  * This function does not update the clock ticks counter.
  */
 void FinalClockTick( void );
 
 /**
  * @brief Simulates a single clock tick using the software timecounter.
  *
  * In contrast to ClockTick(), this function updates also CLOCK_MONOTONIC and
  * CLOCK_REALTIME to the next software timecounter clock tick time point.
  *
  * This function is designed for test suites not having a clock driver.
  */
 void TimecounterTick( void );
 
 typedef uint32_t ( *GetTimecountHandler )( void );
 
 /**
  * @brief Sets the get timecount handler.
  *
  * Using this function will replace the timecounter of the clock driver.
  *
  * @return Returns the previous get timecount handler.
  */
 GetTimecountHandler SetGetTimecountHandler( GetTimecountHandler handler );
 
 /**
  * @brief This constant represents the fake frequency of the software
  *   timecounter.
  */
 #define SOFTWARE_TIMECOUNTER_FREQUENCY 1000000
 
 /**
  * @brief Gets the software timecount counter value.
  *
  * @return Returns the current software timecounter counter value.
  */
 uint32_t GetTimecountCounter( void );
 
 /**
  * @brief Sets and gets the software timecount counter value.
  *
  * @param counter is the new software timecounter counter value.
  *
  * @return Returns the previous software timecounter counter value.
  */
 uint32_t SetTimecountCounter( uint32_t counter );
 
 /**
  * @brief Return the task id of the timer server task
  *
  * This function is an attempt to avoid using RTEMS internal global
  * _Timer_server throughout the validation test code.
  *
  * @return Returns the task id of the timer server task, if
  *   rtems_timer_initiate_server() has been invoked before,
  *   otherwise - if the timer server task does not exist -
  *   RTEMS_INVALID_ID is returned.
  */
 rtems_id GetTimerServerTaskId( void );
 
 /**
  * @brief Undo the effects of rtems_timer_initiate_server()
  *
  * If rtems_timer_initiate_server() was never called before,
  * nothing is done.
  *
  * If rtems_timer_initiate_server() was called before, the
  * created thread and other resources are freed so that
  * rtems_timer_initiate_server() can be called again.
  * There should be no pending timers which are not yet executed
  * by the server task. Naturally, there should be no
  * timer server timers scheduled for execution.
  *
  * @return Returns true, if rtems_timer_initiate_server() has been
  *   invoked before and the timer server task has indeed been deleted,
  *   otherwise false.
  */
 bool DeleteTimerServer( void );
 
 typedef struct {
   struct {
     const void *begin;
     void *free_begin;
     const void *end;
   } areas[ 2 ];
   size_t count;
 } MemoryContext;
 
 void MemorySave( MemoryContext *ctx );
 
 void MemoryRestore( const MemoryContext *ctx );
 
 /**
  * @brief Fails a dynamic memory allocation when the counter reaches zero.
  *
  * This function initializes an internal counter which is decremented before
  * each dynamic memory allocation though the rtems_malloc() directive.  When
  * the counter decrements from one to zero, the allocation fails and NULL will
  * be returned.
  *
  * @param counter is the initial counter value.
  */
 void MemoryAllocationFailWhen( uint32_t counter );
 
 typedef struct {
   Chain_Node node;
   void ( *handler )( void * );
   void *arg;
   Atomic_Uint done;
 } CallWithinISRRequest;
 
 void CallWithinISR( void ( *handler )( void * ), void *arg );
 
 void CallWithinISRSubmit( CallWithinISRRequest *request );
 
 void CallWithinISRWait( const CallWithinISRRequest *request );
 
 void CallWithinISRRaise( void );
 
 void CallWithinISRClear( void );
 
 rtems_vector_number CallWithinISRGetVector( void );
 
 rtems_vector_number GetSoftwareInterruptVector( void );
 
 typedef struct {
   Thread_queue_Operations        tq_ops;
   const Thread_queue_Operations *wrapped_ops;
   Thread_queue_Control           thread_queue;
   CallWithinISRRequest           isr_request;
 } WrapThreadQueueContext;
 
 void WrapThreadQueueInitialize(
   WrapThreadQueueContext *ctx,
   void                 ( *handler )( void * ),
   void                   *arg
 );
 
 void WrapThreadQueueExtract(
   WrapThreadQueueContext *ctx,
   struct _Thread_Control *thread
 );
 
 void WrapThreadQueueExtractDirect(
   WrapThreadQueueContext *ctx,
   Thread_Control         *thread
 );
 
 void WrapThreadQueueDestroy( WrapThreadQueueContext *ctx );
 
 struct Per_CPU_Control;
 
 void SetPreemptionIntervention(
   struct Per_CPU_Control *cpu,
   void                 ( *handler )( void * ),
   void                   *arg
 );
 
 rtems_vector_number GetValidInterruptVectorNumber(
   const rtems_interrupt_attributes *required
 );
 
 rtems_vector_number GetTestableInterruptVector(
   const rtems_interrupt_attributes *required
 );
 
 rtems_status_code RaiseSoftwareInterrupt( rtems_vector_number vector );
 
 rtems_status_code ClearSoftwareInterrupt( rtems_vector_number vector );
 
 bool HasInterruptVectorEntriesInstalled( rtems_vector_number vector );
 
 /**
  * @brief Get the clock and context of a timer from RTEMS internal data.
  *
  * With exception of TIMER_DORMANT, the return values are bits or-ed together.
  *
  * @param id The timer ID.
  *
  * @retval TIMER_DORMANT Either the id argument is invalid or the timer has
  *   never been used before.
  * @return The TIMER_CLASS_BIT_ON_TASK is set, if the timer server routine
  *   was or will be executed in task context, otherwise it was or will be
  *   executed in interrupt context.
  *
  *   The TIMER_CLASS_BIT_TIME_OF_DAY is set, if the clock used is or was the
  *   ${/glossary/clock-realtime:/term}, otherwise the
  *   ${/glossary/clock-tick:/term} based clock is or was used.
  */
 Timer_Classes GetTimerClass( rtems_id id );
 
 /**
  * @brief This structure provides data used by RTEMS to schedule a timer
  *   service routine.
  */
 typedef struct {
   /**
     * @brief This member contains a reference to the timer service routine.
     */
   rtems_timer_service_routine_entry routine;
   /**
    * @brief This member contains a reference to the user data to be provided
    * to the timer service routine.
    */
   void *user_data;
   /**
    * @brief This member contains the timer interval in ticks or seconds.
    */
   Watchdog_Interval interval;
 } Timer_Scheduling_Data;
 
 /**
  * @brief Get data related to scheduling a timer service routine
  *   from RTEMS internal structures.
  *
  * @param id The timer ID.
  * @param[out] data If the reference is not NULL, the data retrieved from
  *   internal RTEMS structures is stored here.
  */
 void GetTimerSchedulingData(
   rtems_id id,
   Timer_Scheduling_Data *data
 );
 
 /**
  * @brief The various states of a timer.
  */
 typedef enum {
   TIMER_INVALID,
   TIMER_INACTIVE,
   TIMER_SCHEDULED,
   TIMER_PENDING
 } Timer_States;
 
 /**
  * @brief Get the state of a timer from RTEMS internal data.
  *
  * @param id The timer ID.
  *
  * @retval TIMER_INVALID The id argument is invalid.
  * @retval TIMER_INACTIVE The timer is not scheduled (i.e. it is
  *   new, run off, or canceled).
  * @retval TIMER_SCHEDULED The timer is scheduled.
  * @retval TIMER_PENDING The timer is pending.
  */
 Timer_States GetTimerState( rtems_id id );
 
 /**
  * @brief Mark the realtime clock as never set.
  *
  * This function manipulates RTEMS internal data structures to undo the
  * effect of rtems_clock_set(). If the clock is not set, the function has no
  * effect.
  */
 void UnsetClock( void );
 
 void FatalInitialExtension(
   rtems_fatal_source source,
   bool               always_set_to_false,
   rtems_fatal_code   code
 );
 
 typedef void ( *FatalHandler )(
   rtems_fatal_source source,
   rtems_fatal_code   code,
   void              *arg
 );
 
 void SetFatalHandler( FatalHandler fatal, void *arg );
 
 void SetTaskSwitchExtension( rtems_task_switch_extension task_switch );
 
 typedef struct {
   uint32_t fatal;
   uint32_t thread_begin;
   uint32_t thread_create;
   uint32_t thread_delete;
   uint32_t thread_exitted;
   uint32_t thread_restart;
   uint32_t thread_start;
   uint32_t thread_switch;
   uint32_t thread_terminate;
 } ExtensionCalls;
 
 void ClearExtensionCalls( ExtensionCalls *calls );
 
 void CopyExtensionCalls( const ExtensionCalls *from, ExtensionCalls *to );
 
 void SetIORelaxHandler( void ( *handler )( void * ), void *arg );
 
 void StartDelayThreadDispatch( uint32_t cpu_index );
 
 void StopDelayThreadDispatch( uint32_t cpu_index );
 
 bool AreInterruptsEnabled( void );
 
 bool IsWhiteSpaceOnly( const char *s );
 
 bool IsEqualIgnoreWhiteSpace( const char *a, const char *b );
 
 #if defined(RTEMS_SMP)
 bool TicketLockIsAvailable( const SMP_ticket_lock_Control *lock );
 
 void TicketLockWaitForOwned( const SMP_ticket_lock_Control *lock );
 
 void TicketLockWaitForOthers(
   const SMP_ticket_lock_Control *lock,
   unsigned int                   others
 );
 
 typedef struct {
   const SMP_ticket_lock_Control *lock;
   unsigned int                   next_ticket;
 } TicketLockState;
 
 void TicketLockGetState(
   const SMP_ticket_lock_Control *lock,
   TicketLockState               *state
 );
 
 void TicketLockWaitForAcquires(
   const TicketLockState *state,
   unsigned int           acquire_count
 );
 
 void TicketLockWaitForReleases(
   const TicketLockState *state,
   unsigned int           release_count
 );
 
 static inline bool ISRLockIsAvailable( const ISR_lock_Control *lock )
 {
   return TicketLockIsAvailable( &lock->Lock.Ticket_lock );
 }
 
 static inline void ISRLockWaitForOwned( const ISR_lock_Control *lock )
 {
   TicketLockWaitForOwned( &lock->Lock.Ticket_lock );
 }
 
 static inline void ISRLockWaitForOthers(
   const ISR_lock_Control *lock,
   unsigned int            others
 )
 {
   TicketLockWaitForOthers( &lock->Lock.Ticket_lock, others );
 }
 #endif
 
 void *IdleBody( uintptr_t ignored );
 
 /**
  * @brief This task configurations may be used to construct a task during
  *   tests.
  *
  * Only one task shall use this configuration at a time, otherwise two tasks
  * would share a stack.
  */
 extern const rtems_task_config DefaultTaskConfig;
 
 /** @} */
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif /* _TX_SUPPORT_H */

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