validation: Add comments to signal tests

2 files changed, 184 insertions, 0 deletions

diff --git a/testsuites/validation/tc-signal-catch.c b/testsuites/validation/tc-signal-catch.c
index 9c14cc93a3..7c3292ba71 100644
--- a/testsuites/validation/tc-signal-catch.c
+++ b/testsuites/validation/tc-signal-catch.c
@@ -251,11 +251,17 @@ static void RtemsSignalReqCatch_Pre_Handler_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Pre_Handler_Invalid: {
+      /*
+       * The ``asr_handler`` parameter shall be NULL.
+       */
       ctx->handler = NULL;
       break;
     }
 
     case RtemsSignalReqCatch_Pre_Handler_Valid: {
+      /*
+       * The ``asr_handler`` parameter shall be a valid ASR handler.
+       */
       ctx->handler = SignalHandler;
       break;
     }
@@ -272,6 +278,10 @@ static void RtemsSignalReqCatch_Pre_Preempt_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Pre_Preempt_Yes: {
+      /*
+       * The ``mode_set`` parameter shall specify that
+       * preemption is enabled.
+       */
       #if defined(RTEMS_SMP)
       if ( rtems_configuration_get_maximum_processors() == 1 ) {
         ctx->normal_mode |= RTEMS_NO_PREEMPT;
@@ -283,6 +293,10 @@ static void RtemsSignalReqCatch_Pre_Preempt_Prepare(
     }
 
     case RtemsSignalReqCatch_Pre_Preempt_No: {
+      /*
+       * The ``mode_set`` parameter shall specify that
+       * preemption is disabled.
+       */
       ctx->mode |= RTEMS_NO_PREEMPT;
       break;
     }
@@ -299,11 +313,19 @@ static void RtemsSignalReqCatch_Pre_Timeslice_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Pre_Timeslice_Yes: {
+      /*
+       * The ``mode_set`` parameter shall specify that
+       * timeslicing is enabled.
+       */
       ctx->mode |= RTEMS_TIMESLICE;
       break;
     }
 
     case RtemsSignalReqCatch_Pre_Timeslice_No: {
+      /*
+       * The ``mode_set`` parameter shall specify that
+       * timeslicing is disabled.
+       */
       ctx->normal_mode |= RTEMS_TIMESLICE;
       break;
     }
@@ -320,11 +342,19 @@ static void RtemsSignalReqCatch_Pre_ASR_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Pre_ASR_Yes: {
+      /*
+       * The ``mode_set`` parameter shall specify that
+       * ASR processing is enabled.
+       */
       /* We cannot disable ASR processing at normal task level for this test */
       break;
     }
 
     case RtemsSignalReqCatch_Pre_ASR_No: {
+      /*
+       * The ``mode_set`` parameter shall specify that
+       * ASR processing is disabled.
+       */
       ctx->mode |= RTEMS_NO_ASR;
       break;
     }
@@ -341,6 +371,10 @@ static void RtemsSignalReqCatch_Pre_IntLvl_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Pre_IntLvl_Zero: {
+      /*
+       * The ``mode_set`` parameter shall specify an interrupt
+       * level of zero.
+       */
       #if !defined(RTEMS_SMP) && CPU_ENABLE_ROBUST_THREAD_DISPATCH == FALSE
       ctx->normal_mode |= RTEMS_INTERRUPT_LEVEL( 1 );
       #endif
@@ -348,6 +382,10 @@ static void RtemsSignalReqCatch_Pre_IntLvl_Prepare(
     }
 
     case RtemsSignalReqCatch_Pre_IntLvl_Positive: {
+      /*
+       * The ``mode_set`` parameter shall specify a positive
+       * interrupt level.
+       */
       ctx->mode |= RTEMS_INTERRUPT_LEVEL( 1 );
       break;
     }
@@ -364,11 +402,21 @@ static void RtemsSignalReqCatch_Post_Status_Check(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Post_Status_Ok: {
+      /*
+       * The return status of rtems_signal_catch() shall be
+       * RTEMS_SUCCESSFUL.
+       */
       T_rsc_success( ctx->catch_status );
       break;
     }
 
     case RtemsSignalReqCatch_Post_Status_NotImplNoPreempt: {
+      /*
+       * Where the system is configured with SMP support, if the scheduler does
+       * not support the no-preempt mode, then the return status of
+       * rtems_signal_catch() shall be RTEMS_NOT_IMPLEMENTED,
+       * otherwise the return status shall be RTEMS_SUCCESSFUL.
+       */
       #if defined(RTEMS_SMP)
       if ( rtems_configuration_get_maximum_processors() > 1 ) {
         T_rsc( ctx->catch_status, RTEMS_NOT_IMPLEMENTED );
@@ -382,6 +430,13 @@ static void RtemsSignalReqCatch_Post_Status_Check(
     }
 
     case RtemsSignalReqCatch_Post_Status_NotImplIntLvl: {
+      /*
+       * Where the system is configured with SMP support and the configured
+       * processor maximum is greater than one, or the CPU port enabled robust
+       * thread dispatching, the return status of rtems_signal_catch() shall be
+       * RTEMS_NOT_IMPLEMENTED, otherwise the return status
+       * shall be RTEMS_SUCCESSFUL.
+       */
       #if CPU_ENABLE_ROBUST_THREAD_DISPATCH == TRUE
       T_rsc( ctx->catch_status, RTEMS_NOT_IMPLEMENTED );
       #elif defined(RTEMS_SMP)
@@ -408,6 +463,11 @@ static void RtemsSignalReqCatch_Post_Send_Check(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Post_Send_New: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call was successful, the ASR processing shall be done with the specified
+       * handler, otherwise the ASR information of the caller shall be unchanged.
+       */
       T_rsc_success( ctx->send_status );
 
       if ( ctx->catch_status == RTEMS_SUCCESSFUL ) {
@@ -423,6 +483,12 @@ static void RtemsSignalReqCatch_Post_Send_Check(
     }
 
     case RtemsSignalReqCatch_Post_Send_NotDef: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call was successful, the ASR processing shall be deactivated and all
+       * pending signals shall be cleared, otherwise the ASR information of the
+       * caller shall be unchanged.
+       */
       if ( ctx->catch_status == RTEMS_SUCCESSFUL ) {
         T_rsc( ctx->send_status, RTEMS_NOT_DEFINED );
         T_eq_u32( ctx->default_handler_calls, 0 );
@@ -449,11 +515,21 @@ static void RtemsSignalReqCatch_Post_Preempt_Check(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Post_Preempt_Yes: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call with a valid handler was successful, the ASR processing shall be
+       * done with preemption enabled.
+       */
       CheckHandlerMode( ctx, RTEMS_PREEMPT_MASK, RTEMS_PREEMPT );
       break;
     }
 
     case RtemsSignalReqCatch_Post_Preempt_No: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call with a valid handler was successful, the ASR processing shall be
+       * done with preemption disabled.
+       */
       CheckHandlerMode( ctx, RTEMS_PREEMPT_MASK, RTEMS_NO_PREEMPT );
       break;
     }
@@ -470,11 +546,21 @@ static void RtemsSignalReqCatch_Post_Timeslice_Check(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Post_Timeslice_Yes: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call with a valid handler was successful, the ASR processing shall be
+       * done with timeslicing enabled.
+       */
       CheckHandlerMode( ctx, RTEMS_TIMESLICE_MASK, RTEMS_TIMESLICE );
       break;
     }
 
     case RtemsSignalReqCatch_Post_Timeslice_No: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call with a valid handler was successful, the ASR processing shall be
+       * done with timeslicing disabled.
+       */
       CheckHandlerMode( ctx, RTEMS_TIMESLICE_MASK, RTEMS_NO_TIMESLICE );
       break;
     }
@@ -491,11 +577,21 @@ static void RtemsSignalReqCatch_Post_ASR_Check(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Post_ASR_Yes: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call with a valid handler was successful, the ASR processing shall be
+       * done with ASR processing enabled.
+       */
       CheckHandlerMode( ctx, RTEMS_ASR_MASK, RTEMS_ASR );
       break;
     }
 
     case RtemsSignalReqCatch_Post_ASR_No: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call with a valid handler was successful, the ASR processing shall be
+       * done with ASR processing disabled.
+       */
       CheckHandlerMode( ctx, RTEMS_ASR_MASK, RTEMS_NO_ASR );
       break;
     }
@@ -512,11 +608,21 @@ static void RtemsSignalReqCatch_Post_IntLvl_Check(
 {
   switch ( state ) {
     case RtemsSignalReqCatch_Post_IntLvl_Zero: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call with a valid handler was successful, the ASR processing shall be
+       * done with interrupts enabled.
+       */
       CheckHandlerMode( ctx, RTEMS_INTERRUPT_MASK, RTEMS_INTERRUPT_LEVEL( 0 ) );
       break;
     }
 
     case RtemsSignalReqCatch_Post_IntLvl_Positive: {
+      /*
+       * When a signal set is sent to the caller of rtems_signal_catch() and the
+       * call with a valid handler was successful, the ASR processing shall be
+       * done with interrupts disabled according to the specified interrupt level.
+       */
       CheckHandlerMode( ctx, RTEMS_INTERRUPT_MASK, RTEMS_INTERRUPT_LEVEL( 1 ) );
       break;
     }
diff --git a/testsuites/validation/tc-signal-send.c b/testsuites/validation/tc-signal-send.c
index a4232efbae..cf5235f752 100644
--- a/testsuites/validation/tc-signal-send.c
+++ b/testsuites/validation/tc-signal-send.c
@@ -371,16 +371,27 @@ static void RtemsSignalReqSend_Pre_Task_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqSend_Pre_Task_NoObj: {
+      /*
+       * The ``id`` parameter shall be invalid.
+       */
       ctx->id = 0xffffffff;
       break;
     }
 
     case RtemsSignalReqSend_Pre_Task_Self: {
+      /*
+       * The ``id`` parameter shall be associated with
+       * the calling task.
+       */
       ctx->id = RTEMS_SELF;
       break;
     }
 
     case RtemsSignalReqSend_Pre_Task_Other: {
+      /*
+       * The ``id`` parameter shall be associated with a
+       * task other than the calling task.
+       */
       ctx->id = ctx->worker_id;
       break;
     }
@@ -397,11 +408,17 @@ static void RtemsSignalReqSend_Pre_Set_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqSend_Pre_Set_Zero: {
+      /*
+       * The ``signal_set`` parameter shall be zero.
+       */
       ctx->signal_set = 0;
       break;
     }
 
     case RtemsSignalReqSend_Pre_Set_NonZero: {
+      /*
+       * The ``signal_set`` parameter shall be non-zero.
+       */
       ctx->signal_set = 0xdeadbeef;
       break;
     }
@@ -418,11 +435,19 @@ static void RtemsSignalReqSend_Pre_Handler_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqSend_Pre_Handler_Invalid: {
+      /*
+       * When the target task has no valid ASR handler installed, the
+       * rtems_signal_send() directive shall be called.
+       */
       ctx->handler = NULL;
       break;
     }
 
     case RtemsSignalReqSend_Pre_Handler_Valid: {
+      /*
+       * When the target task has a valid ASR handler installed, the
+       * rtems_signal_send() directive shall be called.
+       */
       ctx->handler = SignalHandler;
       break;
     }
@@ -439,11 +464,19 @@ static void RtemsSignalReqSend_Pre_ASR_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqSend_Pre_ASR_Enabled: {
+      /*
+       * When the target task has ASR processing enabled, the rtems_signal_send()
+       * directive shall be called.
+       */
       ctx->mode = RTEMS_DEFAULT_MODES;
       break;
     }
 
     case RtemsSignalReqSend_Pre_ASR_Disabled: {
+      /*
+       * When the target task has ASR processing disabled, the rtems_signal_send()
+       * directive shall be called.
+       */
       ctx->mode = RTEMS_NO_ASR;
       break;
     }
@@ -460,11 +493,19 @@ static void RtemsSignalReqSend_Pre_Nested_Prepare(
 {
   switch ( state ) {
     case RtemsSignalReqSend_Pre_Nested_Yes: {
+      /*
+       * When the target task processes an asynchronous signal set, the
+       * rtems_signal_send() directive shall be called.
+       */
       ctx->nested = 1;
       break;
     }
 
     case RtemsSignalReqSend_Pre_Nested_No: {
+      /*
+       * When the target task does not process an asynchronous signal set, the
+       * rtems_signal_send() directive shall be called.
+       */
       ctx->nested = 0;
       break;
     }
@@ -481,21 +522,37 @@ static void RtemsSignalReqSend_Post_Status_Check(
 {
   switch ( state ) {
     case RtemsSignalReqSend_Post_Status_Ok: {
+      /*
+       * The return status of rtems_signal_send() shall be
+       * RTEMS_SUCCESSFUL.
+       */
       T_rsc_success( ctx->status );
       break;
     }
 
     case RtemsSignalReqSend_Post_Status_InvNum: {
+      /*
+       * The return status of rtems_signal_send() shall be
+       * RTEMS_INVALID_NUMBER.
+       */
       T_rsc( ctx->status, RTEMS_INVALID_NUMBER );
       break;
     }
 
     case RtemsSignalReqSend_Post_Status_InvId: {
+      /*
+       * The return status of rtems_signal_send() shall be
+       * RTEMS_INVALID_ID.
+       */
       T_rsc( ctx->status, RTEMS_INVALID_ID );
       break;
     }
 
     case RtemsSignalReqSend_Post_Status_NotDef: {
+      /*
+       * The return status of rtems_signal_send() shall be
+       * RTEMS_NOT_DEFINED.
+       */
       T_rsc( ctx->status, RTEMS_NOT_DEFINED );
       break;
     }
@@ -516,6 +573,10 @@ static void RtemsSignalReqSend_Post_Handler_Check(
 
   switch ( state ) {
     case RtemsSignalReqSend_Post_Handler_NoCall: {
+      /*
+       * While the ASR processing is disabled, the ASR handler shall not be
+       * called.
+       */
       T_eq_sz( ctx->calls_after_send, ctx->nested );
       T_eq_sz( ctx->calls_after_dispatch, ctx->nested );
       T_eq_sz( ctx->calls_after_enable, ctx->nested );
@@ -523,6 +584,9 @@ static void RtemsSignalReqSend_Post_Handler_Check(
     }
 
     case RtemsSignalReqSend_Post_Handler_DuringSend: {
+      /*
+       * The ASR handler shall be called during the rtems_signal_send() call.
+       */
       ++expected_calls;
       T_eq_sz( ctx->calls_after_send, ctx->nested + 1 );
       T_eq_sz( ctx->calls_after_dispatch, ctx->nested + 1 );
@@ -531,6 +595,10 @@ static void RtemsSignalReqSend_Post_Handler_Check(
     }
 
     case RtemsSignalReqSend_Post_Handler_AfterDispatch: {
+      /*
+       * When the next thread dispatch of the target task of the
+       * rtems_signal_send() call takes place, the ASR handler shall be called.
+       */
       ++expected_calls;
       T_eq_sz( ctx->calls_after_send, ctx->nested );
       T_eq_sz( ctx->calls_after_dispatch, ctx->nested + 1 );
@@ -539,6 +607,10 @@ static void RtemsSignalReqSend_Post_Handler_Check(
     }
 
     case RtemsSignalReqSend_Post_Handler_AfterEnable: {
+      /*
+       * When the target task of the rtems_signal_send() call re-enables ASR
+       * processing, the ASR handler shall be called.
+       */
       ++expected_calls;
       T_eq_sz( ctx->calls_after_send, ctx->nested );
       T_eq_sz( ctx->calls_after_dispatch, ctx->nested );
@@ -568,6 +640,9 @@ static void RtemsSignalReqSend_Post_Recursive_Check(
 {
   switch ( state ) {
     case RtemsSignalReqSend_Post_Recursive_Yes: {
+      /*
+       * The ASR handler shall be called recursively.
+       */
       T_eq_sz( ctx->handler_calls, 2 );
       T_ne_uptr( ctx->stack_pointers[ 0 ], 0 );
       T_ne_uptr( ctx->stack_pointers[ 1 ], 0 );
@@ -576,6 +651,9 @@ static void RtemsSignalReqSend_Post_Recursive_Check(
     }
 
     case RtemsSignalReqSend_Post_Recursive_No: {
+      /*
+       * The ASR handler shall not be called recursively.
+       */
       if ( ctx->handler_calls == 2 ) {
         T_ne_uptr( ctx->stack_pointers[ 0 ], 0 );
         T_ne_uptr( ctx->stack_pointers[ 1 ], 0 );