path: root/spec/rtems/timer/req/initiate-server.yml

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
- role: interface-function
  uid: ../if/server-default-priority
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 ( ctx->priority == RTEMS_TIMER_SERVER_DEFAULT_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( GetTimerServerStackSize(), 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( GetTimerServerStackSize(), 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() ==
        ( ( ctx->attribute_set & RTEMS_FLOATING_POINT ) != 0 ) );
    text: |
      The task attribute ${../../attr/if/floating-point:/name}
      shall be unset for the Timer Server task.
  - name: Float
    test-code: |
      T_true( HasTimerServerFloatingPoint() ==
        ( ( ctx->attribute_set & RTEMS_FLOATING_POINT ) != 0 ) );
    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 = GetTimerServerStackSize();
    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, rtems_task_delete );
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 GetTimerServerTaskId() != RTEMS_INVALID_ID;
  }

  static rtems_task_priority GetTimerServerPriority( void )
  {
    return GetPriority( GetTimerServerTaskId() );
  }

  static size_t GetTimerServerStackSize( void )
  {
    rtems_tcb *tcb;
    rtems_id server_task_id;
    server_task_id = GetTimerServerTaskId();
    T_ne_u32( server_task_id, RTEMS_INVALID_ID );
    tcb = GetThread( server_task_id );
    T_not_null( tcb );
    return tcb->Start.Initial_stack.size;
  }

  static bool HasTimerServerFloatingPoint( void )
  {
    rtems_tcb *tcb;
    rtems_id server_task_id;
    server_task_id = GetTimerServerTaskId();
    T_ne_u32( server_task_id, RTEMS_INVALID_ID );
    tcb = GetThread( server_task_id );
    T_not_null( tcb );
    return tcb->is_fp;
  }

  static rtems_status_code AllocateTaskObject( void *arg, rtems_id *task_id )
  {
    (void) arg;

    return rtems_task_create(
      rtems_build_name( 'T', 'A', ' ', 'N' ),
      PRIO_LOW,
      RTEMS_MINIMUM_STACK_SIZE,
      RTEMS_DEFAULT_MODES,
      RTEMS_DEFAULT_ATTRIBUTES,
      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