From b7af59ea5ca32fda80b3b5f597b1a2d09d9725bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Frank=20K=C3=BChndel?= Date: Mon, 26 Apr 2021 14:59:37 +0200 Subject: spec: Add spec item for rtems_timer_cancel() Adding the specification item to rtems-central for the directive rtems_timer_cancel() of the timer manager. --- spec/rtems/timer/req/cancel.yml | 521 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 521 insertions(+) create mode 100644 spec/rtems/timer/req/cancel.yml diff --git a/spec/rtems/timer/req/cancel.yml b/spec/rtems/timer/req/cancel.yml new file mode 100644 index 00000000..39b78edb --- /dev/null +++ b/spec/rtems/timer/req/cancel.yml @@ -0,0 +1,521 @@ +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/cancel +post-conditions: +- name: Status + states: + - name: Ok + test-code: | + T_rsc_success( ctx->status ); + text: | + The return status of ${../if/cancel:/name} shall be + ${../../status/if/successful:/name}. + - name: InvId + test-code: | + T_rsc( ctx->status, RTEMS_INVALID_ID ); + text: | + The return status of ${../if/cancel:/name} shall be + ${../../status/if/invalid-id:/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 scheduled. + - name: Interrupt + test-code: | + T_eq_int( class & TIMER_CLASS_BIT_ON_TASK, 0 ); + text: | + The timer context shall be: "at the last time scheduled + in interrupt context". + - name: Server + test-code: | + T_eq_int( class & TIMER_CLASS_BIT_ON_TASK, TIMER_CLASS_BIT_ON_TASK ); + text: | + The timer context shall be: "at the last time scheduled + in timer server task context". + - name: Nop + test-code: | + T_eq_int( class, ctx->pre_class ); + text: | + Objects referenced by the ${../if/cancel:/params[0]/name} + parameter in past call to ${../if/cancel:/name} shall not be + accessed by the ${../if/cancel:/name} call. + 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 scheduled. + - name: Ticks + test-code: | + T_eq_int( class & TIMER_CLASS_BIT_TIME_OF_DAY, 0 ); + text: | + The timer clock-state shall be: "at the last time scheduled using the + ${/glossary/clock-tick:/term} based clock". + - name: Realtime + test-code: | + T_eq_int( + class & TIMER_CLASS_BIT_TIME_OF_DAY, + TIMER_CLASS_BIT_TIME_OF_DAY + ); + text: | + The timer clock-state shall be: "at the last time scheduled using the + ${/glossary/clock-realtime:/term}". + - name: Nop + test-code: | + T_eq_int( class, ctx->pre_class ); + text: | + Objects referenced by the ${../if/cancel:/params[0]/name} + parameter in past call to ${../if/cancel:/name} shall not be + accessed by the ${../if/cancel:/name} call. + test-epilogue: null + test-prologue: | + Timer_Classes class; + class = GetTimerClass( ctx->timer_id ); +- name: State + states: + - name: Inactive + test-code: | + /* Try to fire the timer service routine - which should not fire. */ + TriggerTimer(); + T_eq_int( ctx->invocations, 0 ); + text: | + The timer service routine shall neither be executed by + ${../if/cancel:/name} nor be executed until the timer is scheduled again. + - name: Nop + test-code: | + T_eq_int( ctx->post_state, ctx->pre_state ); + text: | + Objects referenced by the ${../if/cancel:/params[0]/name} + parameter in past call to ${../if/cancel:/name} shall not be + accessed by the ${../if/cancel:/name} call. + 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/cancel:/params[0]/name} parameter is valid. + - name: Invalid + test-code: | + ctx->id_param = RTEMS_ID_NONE; + text: | + While the ${../if/cancel:/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 timer service routine has never been + scheduled since creation. + - name: Interrupt + test-code: | + ctx->pre_cond_contex = PRE_INTERRUPT; + text: | + While the timer service routine was at the last time executed or is + scheduled to be executed in interrupt context. + - name: Server + test-code: | + ctx->pre_cond_contex = PRE_SERVER; + text: | + While the timer service routine was at the last time executed or is + scheduled to be executed in timer server task context. + 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 scheduled since creation. + - name: Ticks + test-code: | + rtems_status_code status; + + if ( ctx->pre_cond_contex == PRE_INTERRUPT ) { + status = rtems_timer_fire_after( + ctx->timer_id, + 1, + TimerServiceRoutine, + ctx + ); + } else { + status = rtems_timer_server_fire_after( + ctx->timer_id, + 1, + TimerServiceRoutine, + ctx + ); + } + T_rsc_success( status ); + text: | + While the timer has at the last time been scheduled before using the + ${/glossary/clock-tick:/term} based clock. + - name: Realtime + test-code: | + rtems_status_code status; + rtems_time_of_day tod_schedule_not_const = tod_schedule; + + if ( ctx->pre_cond_contex == PRE_INTERRUPT ) { + status = rtems_timer_fire_when( + ctx->timer_id, + &tod_schedule_not_const, + TimerServiceRoutine, + ctx + ); + } else { + status = rtems_timer_server_fire_when( + ctx->timer_id, + &tod_schedule_not_const, + TimerServiceRoutine, + ctx + ); + } + T_rsc_success( status ); + text: | + While the timer has at the last time been scheduled before using the + ${/glossary/clock-realtime:/term}. + test-epilogue: null + test-prologue: null +- name: State + states: + - name: Inactive + test-code: | + TriggerTimer(); + T_eq_int( + ctx->invocations, + ( ctx->pre_cond_contex == PRE_NONE ) ? 0 : 1 + ); + ctx->invocations = 0; + ctx->pre_state = TIMER_INACTIVE; + text: | + While the timer is not scheduled. + - name: Scheduled + test-code: | + /* The timer was already scheduled in the "Clock" pre-conditions. */ + ctx->pre_state = TIMER_SCHEDULED; + text: | + While the timer is scheduled. + - name: Pending + test-code: | + T_rsc_success( rtems_task_suspend( GetTimerServerTaskId() ) ); + TriggerTimer(); + T_eq_int( ctx->invocations, 0 ); + ctx->pre_state = TIMER_PENDING; + text: | + While the timer is scheduled and the specified point in time + has been reached without the timer service routine execution + has been started yet. + test-epilogue: null + test-prologue: null +rationale: | + Pending + The timers using the server directives have a third state *Pending*. + Timer in state Pending have reached the time at which they are scheduled + but the timer service routine has not been invoked yet (for example + because other tasks with higher priority are active). + + None + Newly created timers have no context or clock associated until they are + used in one of the directives ${../if/fire-after:/name}, + ${../if/fire-when:/name}, ${../if/server-fire-after:/name} or + ${../if/server-fire-when:/name}. + + The table below lists the directives which schedule a single timer service + routine. The table states the context in which the timer service routine + will be invoked and the clock which is used to trigger the execution. + + ================================ ================= ================================= + Directive Execution Context Clock Used + ================================ ================= ================================= + ${../if/fire-after:/name} Interrupt ${/glossary/clock-tick:/term} + ${../if/fire-when:/name} Interrupt ${/glossary/clock-realtime:/term} + ${../if/server-fire-after:/name} Server task ${/glossary/clock-tick:/term} + ${../if/server-fire-when:/name} Server task ${/glossary/clock-realtime:/term} + ================================ ================= ================================= +references: [] +requirement-type: functional +skip-reasons: + NotExist: | + The pre-condition combination of Context, Clock and State cannot be + produced and does therefore not exist. +test-action: | + ctx->pre_class = GetTimerClass( ctx->timer_id ); + ctx->status = rtems_timer_cancel( ctx->id_param ); + ctx->post_state = GetTimerState( ctx->timer_id ); + /* 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/cancel:/params[0]/name} parameter for the + action. + description: null + member: | + rtems_id id_param +- brief: | + This member contains the return status of the action. + description: null + member: | + rtems_status_code status +- brief: | + This member contains the counter for invocations of the + timer service routine. + description: null + member: | + int invocations +- brief: | + This member specifies which pre-condition context + (none, interrupt, server) must be created before the cancel action + gets executed. + description: null + member: | + PreConditionContext pre_cond_contex +- brief: | + This member stores internal clock and context settings of the timer before + the execution of the action. + description: null + member: | + Timer_Classes pre_class +- brief: | + This member stores the state of the timer before the execution of the action. + description: null + member: | + Timer_States pre_state +- brief: | + This member stores the state of the timer after the execution of the action. + description: null + member: | + Timer_States post_state +test-context-support: | + typedef enum { + PRE_NONE = 0, + PRE_INTERRUPT = 1, + PRE_SERVER = 2 + } PreConditionContext; +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->invocations = 0; + 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 void TriggerTimer( void ) + { + /* Fire the timer service routine for ticks and realtime clock */ + int i; + for ( i = 0; i < 5; i++ ) { + ClockTick(); + } + T_rsc_success( rtems_clock_set( &tod_fire ) ); + } + + RTEMS_INLINE_ROUTINE void TimerServiceRoutine( + rtems_id timer_id, + void *user_data + ) + { + RtemsTimerReqCancel_Context *ctx = user_data; + ++( ctx->invocations ); + } +test-target: testsuites/validation/tc-timer-cancel.c +test-teardown: + brief: null + code: | + DeleteTimerServer(); + description: null +text: ${.:text-template} +transition-map: +- enabled-by: true + post-conditions: + Status: Ok + Context: None + Clock: None + State: Inactive + pre-conditions: + Id: + - Valid + Context: + - None + Clock: + - None + State: + - Inactive +- enabled-by: true + post-conditions: + Status: Ok + Context: Server + Clock: + - specified-by: Clock + State: Inactive + pre-conditions: + Id: + - Valid + Context: + - Server + Clock: + - Ticks + - Realtime + State: all +- enabled-by: true + post-conditions: + Status: Ok + Context: Interrupt + Clock: + - specified-by: Clock + State: Inactive + pre-conditions: + Id: + - Valid + Context: + - Interrupt + Clock: + - Ticks + - 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 + pre-conditions: + Id: + - Invalid + Context: + - None + Clock: + - None + State: + - Inactive +- enabled-by: true + post-conditions: + Status: InvId + Context: Nop + Clock: Nop + State: 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 + pre-conditions: + Id: + - Invalid + Context: + - Interrupt + Clock: + - Ticks + - Realtime + State: + - Inactive + - Scheduled +type: requirement -- cgit v1.2.3