[rtems-central commit] spec: Add spec item for rtems_timer_reset()
Sebastian Huber
sebh at rtems.org
Mon May 17 06:10:56 UTC 2021
Module: rtems-central
Branch: master
Commit: 7dfb411db765fb536524d3ef572669cb38bfb1a2
Changeset: http://git.rtems.org/rtems-central/commit/?id=7dfb411db765fb536524d3ef572669cb38bfb1a2
Author: Frank Kühndel <frank.kuehndel at embedded-brains.de>
Date: Mon May 3 12:00:39 2021 +0200
spec: Add spec item for rtems_timer_reset()
Adding the specification item to rtems-central for the directive
rtems_timer_reset() of the timer manager. This item uses the
timer specific glossary terms, too.
---
spec/rtems/timer/req/reset.yml | 741 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 741 insertions(+)
diff --git a/spec/rtems/timer/req/reset.yml b/spec/rtems/timer/req/reset.yml
new file mode 100644
index 0000000..6df3b4f
--- /dev/null
+++ b/spec/rtems/timer/req/reset.yml
@@ -0,0 +1,741 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+enabled-by: true
+functional-type: action
+links:
+- role: interface-function
+ uid: ../if/reset
+post-conditions:
+- name: Status
+ states:
+ - name: Ok
+ test-code: |
+ T_rsc_success( ctx->status );
+ text: |
+ The return status of ${../if/reset:/name} shall be
+ ${../../status/if/successful:/name}.
+ - name: InvId
+ test-code: |
+ T_rsc( ctx->status, RTEMS_INVALID_ID );
+ text: |
+ The return status of ${../if/reset:/name} shall be
+ ${../../status/if/invalid-id:/name}.
+ - name: NotDef
+ test-code: |
+ T_rsc( ctx->status, RTEMS_NOT_DEFINED );
+ text: |
+ The return status of ${../if/reset:/name} shall be
+ ${../../status/if/not-defined:/name}
+ test-epilogue: null
+ test-prologue: null
+- name: Context
+ states:
+ - name: None
+ test-code: |
+ T_eq_int( class, TIMER_DORMANT );
+ text: |
+ The timer shall have never been ${../glossary/scheduled:/term}.
+ See also ${../glossary/none:/term}.
+ - name: Interrupt
+ test-code: |
+ T_eq_int( class & TIMER_CLASS_BIT_ON_TASK, 0 );
+ text: |
+ The timer shall be in ${../glossary/interruptcontext:/term}.
+ - name: Server
+ test-code: |
+ T_eq_int( class & TIMER_CLASS_BIT_ON_TASK, TIMER_CLASS_BIT_ON_TASK );
+ text: |
+ The timer shall be in ${../glossary/servercontext:/term}.
+ - name: Nop
+ test-code: |
+ T_eq_int( class, ctx->pre_class );
+ text: |
+ Objects referenced by the ${../if/reset:/params[0]/name}
+ parameter in past call to ${../if/reset:/name} shall not be
+ accessed by the ${../if/reset:/name} call.
+ See also ${../glossary/nop:/term}.
+ test-epilogue: null
+ test-prologue: |
+ Timer_Classes class;
+ class = GetTimerClass( ctx->timer_id );
+- name: Clock
+ states:
+ - name: None
+ test-code: |
+ T_eq_int( class, TIMER_DORMANT );
+ text: |
+ The timer shall have never been ${../glossary/scheduled:/term}.
+ - name: Ticks
+ test-code: |
+ T_eq_int( class & TIMER_CLASS_BIT_TIME_OF_DAY, 0 );
+ text: |
+ The timer shall use the ${../glossary/ticksbasedclock:/term}.
+ - name: Realtime
+ test-code: |
+ T_eq_int(
+ class & TIMER_CLASS_BIT_TIME_OF_DAY,
+ TIMER_CLASS_BIT_TIME_OF_DAY
+ );
+ text: |
+ The timer shall use the ${../glossary/realtimeclock:/term}.
+ - name: Nop
+ test-code: |
+ T_eq_int( class, ctx->pre_class );
+ text: |
+ Objects referenced by the ${../if/reset:/params[0]/name}
+ parameter in past call to ${../if/reset:/name} shall not be
+ accessed by the ${../if/reset:/name} call.
+ test-epilogue: null
+ test-prologue: |
+ Timer_Classes class;
+ class = GetTimerClass( ctx->timer_id );
+- name: State
+ states:
+ - name: Scheduled
+ test-code: |
+ ctx->ticks_till_fire = TriggerTimer( ctx );
+ T_eq_int( ctx->invocations_a + ctx->invocations_b, 1 );
+ text: |
+ The timer shall be in ${../glossary/scheduled:/term}
+ ${../glossary/state:/term}.
+ - name: Nop
+ test-code: |
+ T_eq_int( ctx->post_state, ctx->pre_state );
+ text: |
+ Objects referenced by the ${../if/reset:/params[0]/name}
+ parameter in past call to ${../if/reset:/name} shall not be
+ accessed by the ${../if/reset:/name} call.
+ test-epilogue: null
+ test-prologue: null
+- name: Interval
+ states:
+ - name: Last
+ test-code: |
+ T_eq_int( ctx->ticks_till_fire, ctx->scheduled_ticks_till_fire );
+ text: |
+ The ${../glossary/timerserviceroutine:/term} shall be invoked the same
+ number of ticks (see ${/glossary/tick:/term}), as defined by
+ the last ${../glossary/scheduled:/term} interval, after a point in time
+ during the execution of the ${../if/reset:/name} call.
+ - name: Nop
+ test-code: |
+ /*
+ * Whether the timer is scheduled has already been tested by the
+ * "Nop" "State" post-condition above.
+ */
+ T_eq_u32(
+ ctx->post_scheduling_data.interval,
+ ctx->pre_scheduling_data.interval
+ );
+ text: |
+ If and when the ${../glossary/timerserviceroutine:/term} will be invoked
+ shall not be changed by the past call to ${../if/reset:/name}.
+ test-epilogue: null
+ test-prologue: null
+- name: Routine
+ states:
+ - name: Last
+ test-code: |
+ T_eq_int( ctx->invocations_a, ctx->scheduled_invocations_a );
+ T_eq_int( ctx->invocations_b, ctx->scheduled_invocations_b );
+ text: |
+ The function reference used to invoke the
+ ${../glossary/timerserviceroutine:/term} when the timer will
+ ${../glossary/fire:/term} shall be the same one as the last one
+ ${../glossary/scheduled:/term}.
+ - name: Nop
+ test-code: |
+ T_eq_ptr(
+ ctx->post_scheduling_data.routine,
+ ctx->pre_scheduling_data.routine
+ );
+ text: |
+ The function reference used for any invocation of the
+ ${../glossary/timerserviceroutine:/term} shall not be changed
+ by the past call to ${../if/reset:/name}.
+ test-epilogue: null
+ test-prologue: null
+- name: UserData
+ states:
+ - name: Last
+ test-code: |
+ T_eq_ptr( ctx->routine_user_data, ctx->scheduled_user_data);
+ text: |
+ The user data argument for invoking the
+ ${../glossary/timerserviceroutine:/term} when the timer will
+ ${../glossary/fire:/term} shall be the same as the last
+ ${../glossary/scheduled:/term} user data argument.
+ - name: Nop
+ test-code: |
+ T_eq_ptr(
+ ctx->post_scheduling_data.user_data,
+ ctx->pre_scheduling_data.user_data
+ );
+ text: |
+ The user data argument used for any invocation of the
+ ${../glossary/timerserviceroutine:/term} shall not be changed
+ by the past call to ${../if/reset:/name}.
+ test-epilogue: null
+ test-prologue: null
+pre-conditions:
+- name: Id
+ states:
+ - name: Valid
+ test-code: |
+ ctx->id_param = ctx->timer_id;
+ text: |
+ While the ${../if/reset:/params[0]/name} parameter is valid.
+ - name: Invalid
+ test-code: |
+ ctx->id_param = RTEMS_ID_NONE;
+ text: |
+ While the ${../if/reset:/params[0]/name} parameter is invalid.
+ test-epilogue: null
+ test-prologue: null
+- name: Context
+ states:
+ - name: None
+ test-code: |
+ ctx->pre_cond_contex = PRE_NONE;
+ text: |
+ While the ${../glossary/timerserviceroutine:/term} has never been
+ ${../glossary/scheduled:/term} since creation of the timer.
+ See also ${../glossary/none:/term}.
+ - name: Interrupt
+ test-code: |
+ ctx->pre_cond_contex = PRE_INTERRUPT;
+ text: |
+ While the timer is in ${../glossary/interruptcontext:/term}.
+ - name: Server
+ test-code: |
+ ctx->pre_cond_contex = PRE_SERVER;
+ text: |
+ While the timer is in ${../glossary/servercontext:/term}.
+ test-epilogue: null
+ test-prologue: null
+- name: Clock
+ states:
+ - name: None
+ test-code: |
+ T_eq_int( ctx->pre_cond_contex, PRE_NONE );
+ text: |
+ While the timer has never been ${../glossary/scheduled:/term}
+ since creation of the timer.
+ - name: Ticks
+ test-code: |
+ rtems_status_code status;
+
+ if ( ctx->pre_cond_contex == PRE_INTERRUPT ) {
+ ctx->scheduled_ticks_till_fire = SCHEDULE_SOON;
+ ctx->scheduled_invocations_a = 1;
+ ctx->scheduled_user_data = &ctx->data_a;
+ status = rtems_timer_fire_after(
+ ctx->timer_id,
+ ctx->scheduled_ticks_till_fire,
+ TimerServiceRoutineA,
+ ctx->scheduled_user_data
+ );
+ } else {
+ ctx->scheduled_ticks_till_fire = SCHEDULE_LATER;
+ ctx->scheduled_invocations_b = 1;
+ ctx->scheduled_user_data = &ctx->data_b;
+ status = rtems_timer_server_fire_after(
+ ctx->timer_id,
+ ctx->scheduled_ticks_till_fire,
+ TimerServiceRoutineB,
+ ctx->scheduled_user_data
+ );
+ }
+ T_rsc_success( status );
+ text: |
+ While the ${../glossary/clock:/term} used to determine when the timer
+ will ${../glossary/fire:/term} is the
+ ${../glossary/ticksbasedclock:/term}.
+ - name: Realtime
+ test-code: |
+ rtems_status_code status;
+
+ if ( ctx->pre_cond_contex == PRE_INTERRUPT ) {
+ status = rtems_timer_fire_when(
+ ctx->timer_id,
+ &tod_schedule,
+ TimerServiceRoutineA,
+ &ctx->data_a
+ );
+ } else {
+ status = rtems_timer_server_fire_when(
+ ctx->timer_id,
+ &tod_schedule,
+ TimerServiceRoutineB,
+ &ctx->data_b
+ );
+ }
+ T_rsc_success( status );
+ text: |
+ While the ${../glossary/clock:/term} used to determine when the timer
+ will ${../glossary/fire:/term} is the ${../glossary/realtimeclock:/term}.
+ test-epilogue: null
+ test-prologue: null
+- name: State
+ states:
+ - name: Inactive
+ test-code: |
+ TriggerTimer( ctx );
+ T_eq_int(
+ ctx->invocations_a + ctx->invocations_b,
+ ( ctx->pre_cond_contex == PRE_NONE ) ? 0 : 1
+ );
+ ctx->invocations_a = 0;
+ ctx->invocations_b = 0;
+ ctx->pre_state = TIMER_INACTIVE;
+ text: |
+ While the timer is in ${../glossary/inactive:/term}
+ ${../glossary/state:/term}.
+ - name: Scheduled
+ test-code: |
+ /* The timer was already scheduled in the "Clock" pre-conditions. */
+ ctx->pre_state = TIMER_SCHEDULED;
+ text: |
+ While the timer is in ${../glossary/scheduled:/term}
+ ${../glossary/state:/term}.
+ - name: Pending
+ test-code: |
+ T_rsc_success( rtems_task_suspend( GetTimerServerTaskId() ) );
+ TriggerTimer( ctx );
+ T_eq_int( ctx->invocations_a + ctx->invocations_b, 0 );
+ ctx->pre_state = TIMER_PENDING;
+ text: |
+ While the timer is in ${../glossary/pending:/term}
+ ${../glossary/state:/term}.
+ test-epilogue: null
+ test-prologue: null
+rationale: null
+references: []
+requirement-type: functional
+skip-reasons:
+ NotExist: |
+ The pre-condition combination of ${../glossary/context:/term},
+ ${../glossary/clock:/term} and ${../glossary/state:/term} cannot be
+ produced and does therefore not exist.
+test-action: |
+ GetTimerSchedulingData( ctx->timer_id, &ctx->pre_scheduling_data );
+ ctx->pre_class = GetTimerClass( ctx->timer_id );
+ ctx->status = rtems_timer_reset( ctx->id_param );
+ ctx->post_state = GetTimerState( ctx->timer_id );
+ GetTimerSchedulingData( ctx->timer_id, &ctx->post_scheduling_data );
+ /* Ignoring return status: the timer server task may be suspended or not. */
+ rtems_task_resume( GetTimerServerTaskId() );
+test-brief: null
+test-cleanup: |
+ T_rsc_success( rtems_timer_delete( ctx->timer_id ) );
+test-context:
+- brief: |
+ This member contains a valid id of a timer.
+ description: null
+ member: |
+ rtems_id timer_id
+- brief: |
+ This member specifies the ${../if/reset:/params[0]/name} parameter for the
+ action.
+ description: null
+ member: |
+ rtems_id id_param
+- brief: |
+ This member contains the returned ${/glossary/statuscode:/term} of the action.
+ description: null
+ member: |
+ rtems_status_code status
+- brief: |
+ This member contains the user data for
+ ${../glossary/timerserviceroutine:/term} "A".
+ description: null
+ member: |
+ void *data_a
+- brief: |
+ This member contains the user data for
+ ${../glossary/timerserviceroutine:/term} "B".
+ description: null
+ member: |
+ void *data_b
+- brief: |
+ This member contains the counter for invocations of
+ ${../glossary/timerserviceroutine:/term} "A".
+ description: null
+ member: |
+ int invocations_a
+- brief: |
+ This member contains the counter for invocations of
+ ${../glossary/timerserviceroutine:/term} "B".
+ description: null
+ member: |
+ int invocations_b
+- brief: |
+ This member contains the number of ticks needed to
+ ${../glossary/fire:/term} the ${../glossary/timerserviceroutine:/term}.
+ description: null
+ member: |
+ Scheduling_Ticks ticks_till_fire
+- brief: |
+ This member identifier the user data given to the
+ ${../glossary/timerserviceroutine:/term} when called. It either the
+ address of member data_a or data_b.
+ description: null
+ member: |
+ void **routine_user_data
+- brief: |
+ This member contains a reference to the user data to be used
+ in the next call to the ${../glossary/timerserviceroutine:/term}.
+ description: null
+ member: |
+ void **scheduled_user_data;
+- brief: |
+ This member contains 1 if the ${../glossary/timerserviceroutine:/term}
+ "A" has been ${../glossary/scheduled:/term} otherwise 0.
+ description: null
+ member: |
+ int scheduled_invocations_a
+- brief: |
+ This member contains 1 if the ${../glossary/timerserviceroutine:/term}
+ "B" has been ${../glossary/scheduled:/term} otherwise 0.
+ description: null
+ member: |
+ int scheduled_invocations_b
+- brief: |
+ This member specifies the number of ticks till the
+ ${../glossary/scheduled:/term} ${../glossary/timerserviceroutine:/term}
+ should ${../glossary/fire:/term}.
+ description: null
+ member: |
+ Scheduling_Ticks scheduled_ticks_till_fire
+- brief: |
+ This member specifies which pre-condition ${../glossary/context:/term}
+ (${../glossary/none:/term}, ${../glossary/interruptcontext:/term},
+ ${../glossary/servercontext:/term}) must be created before the
+ ${../if/reset:/name} action gets executed.
+ description: null
+ member: |
+ PreConditionContext pre_cond_contex
+- brief: |
+ This member stores internal ${../glossary/clock:/term} and
+ ${../glossary/context:/term} settings of the timer before
+ the execution of the test action.
+ description: null
+ member: |
+ Timer_Classes pre_class
+- brief: |
+ This member stores the ${../glossary/state:/term} of the timer before
+ the execution of the test action.
+ description: null
+ member: |
+ Timer_States pre_state
+- brief: |
+ This member stores the ${../glossary/state:/term} of the timer after
+ the execution of the test action.
+ description: null
+ member: |
+ Timer_States post_state
+- brief: |
+ This member stores the scheduling data of the timer before
+ the execution of the test action.
+ description: null
+ member: |
+ Timer_Scheduling_Data pre_scheduling_data
+- brief: |
+ This member stores the scheduling data of the timer after
+ the execution of the test action.
+ description: null
+ member: |
+ Timer_Scheduling_Data post_scheduling_data
+test-context-support: |
+ typedef enum {
+ PRE_NONE = 0,
+ PRE_INTERRUPT = 1,
+ PRE_SERVER = 2
+ } PreConditionContext;
+
+ typedef enum {
+ SCHEDULE_NONE = 0,
+ SCHEDULE_SOON = 1,
+ SCHEDULE_LATER = 2,
+ SCHEDULE_MAX = 5
+ } Scheduling_Ticks;
+test-description: null
+test-header: null
+test-includes:
+- rtems.h
+test-local-includes:
+- tx-support.h
+test-prepare: |
+ rtems_status_code status;
+ status = rtems_timer_create(
+ rtems_build_name( 'T', 'I', 'M', 'E' ),
+ &ctx->timer_id
+ );
+ T_rsc_success( status );
+
+ ctx->data_a = ctx;
+ ctx->data_b = ctx;
+ ctx->invocations_a = 0;
+ ctx->invocations_b = 0;
+ ctx->ticks_till_fire = SCHEDULE_NONE;
+ ctx->routine_user_data = NULL;
+ ctx->scheduled_invocations_a = 0;
+ ctx->scheduled_invocations_b = 0;
+ ctx->scheduled_ticks_till_fire = SCHEDULE_NONE;
+ T_rsc_success( rtems_clock_set( &tod_now ) );
+test-setup:
+ brief: null
+ code: |
+ rtems_status_code status;
+ status = rtems_timer_initiate_server(
+ RTEMS_TIMER_SERVER_DEFAULT_PRIORITY,
+ RTEMS_MINIMUM_STACK_SIZE,
+ RTEMS_DEFAULT_ATTRIBUTES
+ );
+ T_rsc_success( status );
+ description: null
+test-stop: null
+test-support: |
+ static const rtems_time_of_day tod_now = { 2000, 1, 1, 0, 0, 0, 0 };
+ static const rtems_time_of_day tod_schedule = { 2000, 1, 1, 1, 0, 0, 0 };
+ static const rtems_time_of_day tod_fire = { 2000, 1, 2, 0, 0, 0, 0 };
+
+ static Scheduling_Ticks TriggerTimer( const RtemsTimerReqReset_Context *ctx )
+ {
+ int ticks_fired = SCHEDULE_NONE;
+ int invocations_old = ctx->invocations_a + ctx->invocations_b;
+
+ /* Fire the timer service routine for ticks and realtime clock */
+ int i;
+ for ( i = 1; i <= SCHEDULE_MAX; ++i ) {
+ ClockTick();
+ if ( ctx->invocations_a + ctx->invocations_b > invocations_old ) {
+ ticks_fired = i;
+ break;
+ }
+ }
+
+ T_rsc_success( rtems_clock_set( &tod_fire ) );
+
+ return ticks_fired;
+ }
+
+ RTEMS_INLINE_ROUTINE void TimerServiceRoutineA(
+ rtems_id timer_id,
+ void *user_data
+ )
+ {
+ RtemsTimerReqReset_Context *ctx =
+ *(RtemsTimerReqReset_Context **) user_data;
+ ++( ctx->invocations_a );
+ ctx->routine_user_data = user_data;
+ }
+
+ RTEMS_INLINE_ROUTINE void TimerServiceRoutineB(
+ rtems_id timer_id,
+ void *user_data
+ )
+ {
+ RtemsTimerReqReset_Context *ctx =
+ *(RtemsTimerReqReset_Context **) user_data;
+ ++( ctx->invocations_b );
+ ctx->routine_user_data = user_data;
+ }
+test-target: testsuites/validation/tc-timer-reset.c
+test-teardown:
+ brief: null
+ code: |
+ DeleteTimerServer();
+ description: null
+text: ${.:text-template}
+transition-map:
+- enabled-by: true
+ post-conditions:
+ Status: NotDef
+ Context: Nop
+ Clock: Nop
+ State: Nop
+ Interval: Nop
+ Routine: Nop
+ UserData: Nop
+ pre-conditions:
+ Id:
+ - Valid
+ Context:
+ - None
+ Clock:
+ - None
+ State:
+ - Inactive
+- enabled-by: true
+ post-conditions:
+ Status: Ok
+ Context: Server
+ Clock: Ticks
+ State: Scheduled
+ Interval: Last
+ Routine: Last
+ UserData: Last
+ pre-conditions:
+ Id:
+ - Valid
+ Context:
+ - Server
+ Clock:
+ - Ticks
+ State: all
+- enabled-by: true
+ post-conditions:
+ Status: NotDef
+ Context: Nop
+ Clock: Nop
+ State: Nop
+ Interval: Nop
+ Routine: Nop
+ UserData: Nop
+ pre-conditions:
+ Id:
+ - Valid
+ Context:
+ - Server
+ Clock:
+ - Realtime
+ State: all
+- enabled-by: true
+ post-conditions:
+ Status: Ok
+ Context: Interrupt
+ Clock: Ticks
+ State: Scheduled
+ Interval: Last
+ Routine: Last
+ UserData: Last
+ pre-conditions:
+ Id:
+ - Valid
+ Context:
+ - Interrupt
+ Clock:
+ - Ticks
+ State:
+ - Inactive
+ - Scheduled
+- enabled-by: true
+ post-conditions:
+ Status: NotDef
+ Context: Nop
+ Clock: Nop
+ State: Nop
+ Interval: Nop
+ Routine: Nop
+ UserData: Nop
+ pre-conditions:
+ Id:
+ - Valid
+ Context:
+ - Interrupt
+ Clock:
+ - Realtime
+ State:
+ - Inactive
+ - Scheduled
+- enabled-by: true
+ post-conditions: NotExist
+ pre-conditions:
+ Id: all
+ Context:
+ - None
+ Clock:
+ - None
+ State:
+ - Scheduled
+ - Pending
+- enabled-by: true
+ post-conditions: NotExist
+ pre-conditions:
+ Id: all
+ Context:
+ - None
+ Clock:
+ - Ticks
+ - Realtime
+ State: all
+- enabled-by: true
+ post-conditions: NotExist
+ pre-conditions:
+ Id: all
+ Context:
+ - Interrupt
+ - Server
+ Clock:
+ - None
+ State: all
+- enabled-by: true
+ post-conditions: NotExist
+ pre-conditions:
+ Id: all
+ Context:
+ - Interrupt
+ Clock:
+ - Ticks
+ - Realtime
+ State:
+ - Pending
+- enabled-by: true
+ post-conditions:
+ Status: InvId
+ Context: Nop
+ Clock: Nop
+ State: Nop
+ Interval: Nop
+ Routine: Nop
+ UserData: Nop
+ pre-conditions:
+ Id:
+ - Invalid
+ Context:
+ - None
+ Clock:
+ - None
+ State:
+ - Inactive
+- enabled-by: true
+ post-conditions:
+ Status: InvId
+ Context: Nop
+ Clock: Nop
+ State: Nop
+ Interval: Nop
+ Routine: Nop
+ UserData: Nop
+ pre-conditions:
+ Id:
+ - Invalid
+ Context:
+ - Server
+ Clock:
+ - Ticks
+ - Realtime
+ State: all
+- enabled-by: true
+ post-conditions:
+ Status: InvId
+ Context: Nop
+ Clock: Nop
+ State: Nop
+ Interval: Nop
+ Routine: Nop
+ UserData: Nop
+ pre-conditions:
+ Id:
+ - Invalid
+ Context:
+ - Interrupt
+ Clock:
+ - Ticks
+ - Realtime
+ State:
+ - Inactive
+ - Scheduled
+type: requirement
More information about the vc
mailing list