spec: Add spec item rtems_timer_initiate_server()

Adding the specification item to rtems-central for the directive
rtems_timer_initiate_server() of the timer manager.

1 files changed, 452 insertions, 0 deletions

diff --git a/spec/rtems/timer/req/initiate-server.yml b/spec/rtems/timer/req/initiate-server.yml
new file mode 100644
index 00000000..13a9844d
--- /dev/null
+++ b/spec/rtems/timer/req/initiate-server.yml
@@ -0,0 +1,452 @@
+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/initiate-server
+post-conditions:
+- name: Status
+  states:
+  - name: Ok
+    test-code: |
+      T_rsc_success( ctx->status );
+    text: |
+      The return status of ${../if/initiate-server:/name} shall be
+      ${../../status/if/successful:/name}.
+  - name: IncStat
+    test-code: |
+      T_rsc( ctx->status, RTEMS_INCORRECT_STATE );
+    text: |
+      The return status of ${../if/initiate-server:/name} shall be
+      ${../../status/if/incorrect-state:/name}
+  - name: InvPrio
+    test-code: |
+      T_rsc( ctx->status, RTEMS_INVALID_PRIORITY );
+    text: |
+      The return status of ${../if/initiate-server:/name} shall be
+      ${../../status/if/invalid-priority:/name}.
+  - name: TooMany
+    test-code: |
+      T_rsc( ctx->status, RTEMS_TOO_MANY );
+    text: |
+      The return status of ${../if/initiate-server:/name} shall be
+      ${../../status/if/too-many:/name}.
+  - name: Unsat
+    test-code: |
+      T_rsc( ctx->status, RTEMS_UNSATISFIED  );
+    text: |
+      The return status of ${../if/initiate-server:/name} shall be
+      ${../../status/if/unsatisfied:/name}.
+  test-epilogue: null
+  test-prologue: null
+- name: Server
+  states:
+  - name: Running
+    test-code: |
+      T_true( ExistTimerServer() );
+    text: |
+      The Timer Server task shall be initialized and existing after the
+      ${../if/initiate-server:/name} call.
+  - name: NoExist
+    test-code: |
+      T_false( ExistTimerServer() );
+    text: |
+      The Timer Server task shall not exist.
+  test-epilogue: null
+  test-prologue: null
+- name: TaskPrio
+  states:
+  - name: Set
+    test-code: |
+      if ( RTEMS_TIMER_SERVER_DEFAULT_PRIORITY == ctx->priority ) {
+        T_eq_u32( GetTimerServerPriority(), 0 );
+      } else {
+        T_eq_u32( GetTimerServerPriority(), ctx->priority );
+      }
+    text: |
+      The Timer Server task shall have the priority
+      specified by the ${../if/initiate-server:/params[0]/name}
+      parameter in the ${../if/initiate-server:/name} call.
+  - name: Unchanged
+    test-code: |
+      T_eq_u32( GetTimerServerPriority(), ctx->before_priority );
+    text: |
+      The priority of the Timer Server task shall be unchanged
+      by the ${../if/initiate-server:/name} call.
+  test-epilogue: null
+  test-prologue: null
+- name: TaskStack
+  states:
+  - name: Set
+    test-code: |
+      T_ge_sz( GetTimerServertackSize(), ctx->stack_size );
+    text: |
+      The Timer Server task shall have the same or larger stack size
+      than specified by the ${../if/initiate-server:/params[1]/name}
+      parameter in the ${../if/initiate-server:/name} call.
+  - name: Unchanged
+    test-code: |
+      T_ge_sz( GetTimerServertackSize(), ctx->before_stack_size );
+    text: |
+      The stack size of the Timer Server task shall be unchanged
+      by the ${../if/initiate-server:/name} call.
+  test-epilogue: null
+  test-prologue: null
+- name: TaskAttr
+  states:
+  - name: NoFloat
+    test-code: |
+      T_true( HasTimerServerFloatingPoint() ==
+        ( 0 != ( ctx->attribute_set & RTEMS_FLOATING_POINT ) ) );
+    text: |
+      The task attribute ${../../attr/if/floating-point:/name}
+      shall be unset for the Timer Server task.
+  - name: Float
+    test-code: |
+      T_true( HasTimerServerFloatingPoint() ==
+        ( 0 != ( ctx->attribute_set & RTEMS_FLOATING_POINT ) ) );
+    text: |
+      The task attribute ${../../attr/if/floating-point:/name}
+      shall be set for the Timer Server task.
+  - name: Unchanged
+    test-code: |
+      T_true( HasTimerServerFloatingPoint() == ctx->before_has_floating_point );
+    text: |
+      The task attributes of the Timer Server task shall be unchanged
+      by the ${../if/initiate-server:/name} call.
+  test-epilogue: null
+  test-prologue: null
+pre-conditions:
+- name: Priority
+  states:
+  - name: Valid
+    test-code: |
+      ctx->priority = 13;
+    text: |
+      While the ${../if/initiate-server:/params[0]/name} parameter is valid.
+  - name: Default
+    test-code: |
+      ctx->priority = RTEMS_TIMER_SERVER_DEFAULT_PRIORITY;
+    text: |
+      While the ${../if/initiate-server:/params[0]/name} parameter has
+      the value ${../if/server-default-priority:/name}.
+  - name: Invalid
+    test-code: |
+      ctx->priority = PRIO_INVALID;
+    text: |
+      While the ${../if/initiate-server:/params[0]/name} parameter is invalid.
+  test-epilogue: null
+  test-prologue: null
+- name: Stack
+  states:
+  - name: RtemsMin
+    test-code: |
+      ctx->stack_size = RTEMS_MINIMUM_STACK_SIZE;
+    text: |
+      While the ${../if/initiate-server:/params[1]/name} parameter
+      has the value ${../../task/if/minimum-stack-size:/name}.
+  - name: TooLarge
+    test-code: |
+      ctx->stack_size = SIZE_MAX;
+    text: |
+      While the ${../if/initiate-server:/params[1]/name} parameter
+      has a value which exceeds the size of the available memory.
+  test-epilogue: null
+  test-prologue: null
+- name: Attr
+  states:
+  - name: Default
+    test-code: |
+      ctx->attribute_set = RTEMS_DEFAULT_ATTRIBUTES;
+    text: |
+      While the ${../if/initiate-server:/params[2]/name} parameter has
+      the value ${../../attr/if/default:/name}.
+  - name: Float
+    test-code: |
+      ctx->attribute_set = RTEMS_FLOATING_POINT;
+    text: |
+      While the ${../if/initiate-server:/params[2]/name} parameter has
+      the value ${../../attr/if/floating-point:/name}.
+  test-epilogue: null
+  test-prologue: null
+- name: Server
+  states:
+  - name: Running
+    test-code: |
+      rtems_status_code status;
+
+      if ( !ExistTimerServer() ) {
+        status = rtems_timer_initiate_server(
+          RTEMS_TIMER_SERVER_DEFAULT_PRIORITY,
+          RTEMS_MINIMUM_STACK_SIZE,
+          RTEMS_DEFAULT_ATTRIBUTES
+        );
+        T_rsc_success( status );
+      }
+    text: |
+      While the ${../if/initiate-server:/name} has been invoked before
+      (i.e. the time server task has already been started).
+  - name: NoExist
+    test-code: |
+      DeleteTimerServer();
+    text: |
+      While the ${../if/initiate-server:/name} has not been invoked
+      before.
+  test-epilogue: null
+  test-prologue: null
+- name: TaskObj
+  states:
+  - name: Available
+    test-code: |
+      /* The test clean up ensures that all tasks objects are free. */
+    text: |
+      While there is at least one free task object.
+  - name: Unavailable
+    test-code: |
+      ctx->task_objects = T_seize_objects(
+        AllocateTaskObject,
+        NULL
+      );
+    text: |
+      While there is no free task object.
+  test-epilogue: null
+  test-prologue: null
+rationale: null
+references: []
+requirement-type: functional
+skip-reasons: {}
+test-action: |
+  if ( ExistTimerServer() ) {
+    ctx->before_priority = GetTimerServerPriority();
+    ctx->before_stack_size = GetTimerServertackSize();
+    ctx->before_has_floating_point = HasTimerServerFloatingPoint();
+  }
+
+  ctx->status = rtems_timer_initiate_server(
+    ctx->priority,
+    ctx->stack_size,
+    ctx->attribute_set
+  );
+test-brief: null
+test-cleanup: |
+  T_surrender_objects( &ctx->task_objects, FreeTaskObject );
+test-context:
+- brief: |
+    If the Timer Server task exists before the action,
+    its priority before the action.
+  description: null
+  member: |
+    rtems_task_priority before_priority
+- brief: |
+    If the Timer Server task exists before the action,
+    its stack size before the action.
+  description: null
+  member: |
+    size_t before_stack_size
+- brief: |
+    If the Timer Server task exists before the action,
+    whether the floating point attribute is set before the action.
+  description: null
+  member: |
+    bool before_has_floating_point
+- brief: |
+    The ${../if/initiate-server:/params[0]/name}
+    parameter for the action.
+  description: null
+  member: |
+    rtems_task_priority priority
+- brief: |
+    The ${../if/initiate-server:/params[1]/name}
+    parameter for the action.
+  description: null
+  member: |
+    size_t stack_size
+- brief: |
+    The ${../if/initiate-server:/params[2]/name}
+    parameter for the action.
+  description: null
+  member: |
+    rtems_attribute attribute_set
+- brief: |
+    The status value returned by the action ${../if/initiate-server:/name}.
+  description: null
+  member: |
+    rtems_status_code status
+- brief: |
+    This member is used by the T_seize_objects() and T_surrender_objects()
+    support functions.
+  description: null
+  member: |
+    void *task_objects
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- rtems.h
+- rtems/rtems/timerimpl.h
+test-local-includes:
+- tx-support.h
+test-prepare: null
+test-setup:
+  brief: null
+  code: |
+    ctx->task_objects = NULL;
+  description: null
+test-stop: null
+test-support: |
+  static bool ExistTimerServer( void ) {
+    return NULL != _Timer_server;
+  }
+
+  static rtems_task_priority GetTimerServerPriority( void )
+  {
+    return GetPriority( _Timer_server->server_id );
+  }
+
+  static size_t GetTimerServertackSize( void ) {
+    rtems_tcb *tcb;
+    T_true( ExistTimerServer() );
+    tcb = GetThread( _Timer_server->server_id );
+    T_not_null( tcb );
+    return tcb->Start.Initial_stack.size;
+  }
+
+  static bool HasTimerServerFloatingPoint( void ) {
+    rtems_tcb *tcb;
+    T_true( ExistTimerServer() );
+    tcb = GetThread( _Timer_server->server_id );
+    T_not_null( tcb );
+    return tcb->is_fp;
+  }
+
+  static rtems_status_code AllocateTaskObject( void *arg, rtems_id *task_id ) {
+    static rtems_name task_name = rtems_build_name( 'T', 'A', ' ', 'N' );
+    (void) arg;
+
+    return rtems_task_create(
+      task_name,
+      PRIO_LOW,
+      RTEMS_MINIMUM_STACK_SIZE,
+      RTEMS_DEFAULT_MODES,
+      RTEMS_DEFAULT_ATTRIBUTES,
+      task_id
+    );
+  }
+
+  static rtems_status_code FreeTaskObject( rtems_id task_id ) {
+    return rtems_task_delete( task_id );
+  }
+
+test-target: testsuites/validation/tc-timer-initiate-server.c
+test-teardown:
+  brief: Make sure the time server in not running after this test.
+  code: |
+    DeleteTimerServer();
+  description: null
+text: ${.:text-template}
+transition-map:
+- enabled-by: true
+  post-conditions:
+    Status: Ok
+    Server: Running
+    TaskPrio: Set
+    TaskStack: Set
+    TaskAttr: NoFloat
+  pre-conditions:
+    Priority:
+      - Valid
+      - Default
+    Stack:
+      - RtemsMin
+    Attr:
+      - Default
+    Server:
+      - NoExist
+    TaskObj:
+      - Available
+- enabled-by: true
+  post-conditions:
+    Status: Ok
+    Server: Running
+    TaskPrio: Set
+    TaskStack: Set
+    TaskAttr: Float
+  pre-conditions:
+    Priority:
+      - Valid
+      - Default
+    Stack:
+      - RtemsMin
+    Attr:
+      - Float
+    Server:
+      - NoExist
+    TaskObj:
+      - Available
+- enabled-by: true
+  post-conditions:
+    Status: IncStat
+    Server: Running
+    TaskPrio: Unchanged
+    TaskStack: Unchanged
+    TaskAttr: Unchanged
+  pre-conditions:
+    Priority: all
+    Stack: all
+    Attr: all
+    Server:
+      - Running
+    TaskObj: all
+- enabled-by: true
+  post-conditions:
+    Status: InvPrio
+    Server: NoExist
+    TaskPrio: "N/A"
+    TaskStack: "N/A"
+    TaskAttr: "N/A"
+  pre-conditions:
+    Priority:
+      - Invalid
+    Stack: all
+    Attr: all
+    Server:
+      - NoExist
+    TaskObj: all
+- enabled-by: true
+  post-conditions:
+    Status: TooMany
+    Server: NoExist
+    TaskPrio: "N/A"
+    TaskStack: "N/A"
+    TaskAttr: "N/A"
+  pre-conditions:
+    Priority:
+      - Valid
+      - Default
+    Stack: all
+    Attr: all
+    Server:
+      - NoExist
+    TaskObj:
+      - Unavailable
+- enabled-by: true
+  post-conditions:
+    Status: Unsat
+    Server: NoExist
+    TaskPrio: "N/A"
+    TaskStack: "N/A"
+    TaskAttr: "N/A"
+  pre-conditions:
+    Priority:
+      - Valid
+      - Default
+    Stack:
+      - TooLarge
+    Attr: all
+    Server:
+      - NoExist
+    TaskObj:
+      - Available
+type: requirement