path: root/spec/rtems/sem/req/flush.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/flush
- role: function-implementation
  uid: /score/tq/req/flush-fifo
- role: function-implementation
  uid: /score/tq/req/flush-priority
- role: function-implementation
  uid: /score/tq/req/flush-priority-inherit
post-conditions:
- name: Action
  states:
  - name: InvId
    test-code: |
      sc = rtems_semaphore_flush( 0xffffffff );
      T_rsc( sc, RTEMS_INVALID_ID );
    text: |
      The return status of ${../if/flush:/name} shall be
      ${../../status/if/invalid-id:/name}.
  - name: NotDef
    test-code: |
      sc = rtems_semaphore_flush( ctx->tq_ctx.thread_queue_id );
      T_rsc( sc, RTEMS_NOT_DEFINED );
    text: |
      The return status of ${../if/flush:/name} shall be
      ${../../status/if/not-defined:/name}.
  - name: FlushFIFO
    test-code: |
      ${/score/tq/req/flush-fifo:/test-run}( &ctx->tq_ctx, false );
    text: |
      The calling task shall flush the semaphore as specified by
      ${/score/tq/req/flush-fifo:/spec}.
  - name: FlushPriority
    test-code: |
      ${/score/tq/req/flush-priority:/test-run}( &ctx->tq_ctx, true );
    text: |
      The calling task shall flush the semaphore as specified by
      ${/score/tq/req/flush-priority:/spec}.
  - name: FlushPriorityCeiling
    test-code: |
      ${/score/tq/req/flush-priority:/test-run}( &ctx->tq_ctx, false );
    text: |
      The calling task shall flush the semaphore as specified by
      ${/score/tq/req/flush-priority:/spec}.
  - name: FlushPriorityInherit
    test-code: |
      ${/score/tq/req/flush-priority-inherit:/test-run}( &ctx->tq_ctx );
    text: |
      The calling task shall flush the semaphore as specified by
      ${/score/tq/req/flush-priority-inherit:/spec}.
  test-epilogue: null
  test-prologue: |
    rtems_status_code sc;
pre-conditions:
- name: Class
  states:
  - name: Counting
    test-code: |
      ctx->attribute_set |= RTEMS_COUNTING_SEMAPHORE;
      ctx->initial_count = 0;
      ctx->tq_ctx.enqueue_prepare = TQDoNothing;
      ctx->tq_ctx.enqueue_done = TQDoNothing;
    text: |
      While the semaphore object is a counting semaphore.
  - name: Simple
    test-code: |
      ctx->attribute_set |= RTEMS_SIMPLE_BINARY_SEMAPHORE;
      ctx->initial_count = 0;
      ctx->tq_ctx.enqueue_prepare = TQDoNothing;
      ctx->tq_ctx.enqueue_done = TQDoNothing;
    text: |
      While the semaphore object is a simple binary semaphore.
  - name: Binary
    test-code: |
      ctx->attribute_set |= RTEMS_BINARY_SEMAPHORE;
      ctx->initial_count = 1;
      ctx->tq_ctx.enqueue_prepare = EnqueuePrepare;
      ctx->tq_ctx.enqueue_done = TQEnqueueDoneDefault;
    text: |
      While the semaphore object is a binary semaphore.
  - name: PrioCeiling
    test-code: |
      ctx->attribute_set |= RTEMS_BINARY_SEMAPHORE | RTEMS_PRIORITY_CEILING;
      ctx->initial_count = 1;
      ctx->tq_ctx.enqueue_prepare = EnqueuePrepare;
      ctx->tq_ctx.enqueue_done = TQEnqueueDoneDefault;
    text: |
      While the semaphore object is a priority ceiling semaphore.
  - name: PrioInherit
    test-code: |
      ctx->attribute_set |= RTEMS_BINARY_SEMAPHORE | RTEMS_INHERIT_PRIORITY;
      ctx->initial_count = 1;
      ctx->tq_ctx.enqueue_prepare = EnqueuePrepare;
      ctx->tq_ctx.enqueue_done = TQEnqueueDoneDefault;
    text: |
      While the semaphore object is a priority inheritance semaphore.
  - name: MrsP
    test-code: |
      ctx->attribute_set |= RTEMS_BINARY_SEMAPHORE |
        RTEMS_MULTIPROCESSOR_RESOURCE_SHARING;
      ctx->initial_count = 1;
      ctx->tq_ctx.enqueue_prepare = EnqueuePrepare;
      ctx->tq_ctx.enqueue_done = TQEnqueueDoneDefault;
    text: |
      While the semaphore object is a MrsP semaphore.
  test-epilogue: null
  test-prologue: null
- name: Discipline
  states:
  - name: FIFO
    test-code: |
      ctx->attribute_set |= RTEMS_FIFO;
      ctx->tq_ctx.discipline = TQ_FIFO;
    text: |
      While the semaphore uses the FIFO task wait queue discipline.
  - name: Priority
    test-code: |
      ctx->attribute_set |= RTEMS_PRIORITY;
      ctx->tq_ctx.discipline = TQ_PRIORITY;
    text: |
      While the semaphore uses the priority task wait queue discipline.
  test-epilogue: null
  test-prologue: null
- name: Id
  states:
  - name: Valid
    test-code: |
      /* Nothing to prepare */
    text: |
      While the ${../if/flush:/params[0]/name} parameter is associated with
      the semaphore.
  - name: Invalid
    test-code: |
      /* Nothing to prepare */
    text: |
      While the ${../if/flush:/params[0]/name} parameter is not associated
      with a semaphore.
  test-epilogue: null
  test-prologue: null
rationale: null
references: []
requirement-type: functional
skip-reasons:
  NeedsPriorityDiscipline: |
    Binary semaphores with a locking protocol are required to use the priority
    task wait queue discipline.
  NoMrsP: |
    Where the system is build with SMP support disabled, the MrsP locking
    protocol is not available.
test-action: |
  rtems_status_code sc;

  sc = rtems_semaphore_create(
    NAME,
    ctx->initial_count,
    ctx->attribute_set,
    PRIO_ULTRA_HIGH,
    &ctx->tq_ctx.thread_queue_id
  );
  T_rsc_success( sc );
test-brief: null
test-cleanup:
  rtems_status_code sc;

  sc = rtems_semaphore_delete( ctx->tq_ctx.thread_queue_id );
  T_rsc_success( sc );
test-context:
- brief: |
    This member contains the thread queue test context.
  description: null
  member: |
    TQContext tq_ctx;
- brief: |
    This member specifies if the attribute set of the semaphore.
  description: null
  member: |
    rtems_attribute attribute_set
- brief: |
    This member specifies if the initial count of the semaphore.
  description: null
  member: |
    uint32_t initial_count
test-context-support: null
test-description: null
test-header: null
test-includes:
- rtems.h
- string.h
test-local-includes:
- tr-tq-flush-fifo.h
- tr-tq-flush-priority.h
- tr-tq-flush-priority-inherit.h
- tx-thread-queue.h
- tx-support.h
test-prepare: |
  ctx->attribute_set = RTEMS_DEFAULT_ATTRIBUTES;
test-setup:
  brief: null
  code: |
    memset( ctx, 0, sizeof( *ctx ) );
    ctx->tq_ctx.enqueue = Enqueue;
    ctx->tq_ctx.flush = Flush;
    ctx->tq_ctx.surrender = TQSurrenderClassicSem;
    ctx->tq_ctx.convert_status = TQConvertStatusClassic;
    TQInitialize( &ctx->tq_ctx );
  description: null
test-stop: null
test-support: |
  #define NAME rtems_build_name( 'T', 'E', 'S', 'T' )

  typedef ${.:/test-context-type} Context;

  static void EnqueuePrepare( TQContext *tq_ctx )
  {
    rtems_status_code sc;

    sc = rtems_semaphore_obtain(
      tq_ctx->thread_queue_id,
      RTEMS_WAIT,
      RTEMS_NO_TIMEOUT
    );
    T_rsc_success( sc );
  }

  static Status_Control Enqueue( TQContext *tq_ctx, TQWait wait )
  {
    rtems_status_code sc;

    (void) wait;
    sc = rtems_semaphore_obtain(
      tq_ctx->thread_queue_id,
      RTEMS_WAIT,
      RTEMS_NO_TIMEOUT
    );
    T_rsc( sc, RTEMS_UNSATISFIED );

    return STATUS_BUILD( STATUS_SUCCESSFUL, 0 );
  }

  static uint32_t Flush( TQContext *tq_ctx, uint32_t thread_count, bool all )
  {
    rtems_status_code sc;

    (void) all;

    sc = rtems_semaphore_flush( tq_ctx->thread_queue_id );
    T_rsc_success( sc );

    return thread_count;
  }
test-target: testsuites/validation/tc-sem-flush.c
test-teardown:
  brief: null
  code: |
    TQDestroy( &ctx->tq_ctx );
  description: null
text: ${.:text-template}
transition-map:
- enabled-by: true
  post-conditions:
    Action: InvId
  pre-conditions:
    Class: N/A
    Discipline: N/A
    Id:
    - Invalid
- enabled-by: true
  post-conditions:
    Action:
    - if:
        pre-conditions:
          Discipline: Priority
      then: FlushPriority
    - else: FlushFIFO
  pre-conditions:
    Class:
    - Binary
    - Counting
    - Simple
    Discipline: all
    Id:
    - Valid
- enabled-by: true
  post-conditions:
    Action: FlushPriorityCeiling
  pre-conditions:
    Class:
    - PrioCeiling
    Discipline:
    - Priority
    Id:
    - Valid
- enabled-by: true
  post-conditions:
    Action: FlushPriorityInherit
  pre-conditions:
    Class:
    - PrioInherit
    Discipline:
    - Priority
    Id:
    - Valid
- enabled-by: true
  post-conditions: NoMrsP
  pre-conditions:
    Class:
    - MrsP
    Discipline:
    - Priority
    Id:
    - Valid
- enabled-by: true
  post-conditions: NeedsPriorityDiscipline
  pre-conditions:
    Class:
    - PrioCeiling
    - PrioInherit
    - MrsP
    Discipline:
    - FIFO
    Id:
    - Valid
- enabled-by: RTEMS_SMP
  post-conditions:
    Action: NotDef
  pre-conditions:
    Class:
    - MrsP
    Discipline:
    - Priority
    Id:
    - Valid
type: requirement