SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2021 embedded brains GmbH & Co. KG
enabled-by: true
functional-type: action
links:
- role: interface-function
  uid: ../if/futex-wait
- role: function-implementation
  uid: /score/tq/req/enqueue-fifo
- role: requirement-refinement
  uid: futex
post-conditions:
- name: Result
  states:
  - name: Zero
    test-code: |
      /* This result is checked by Enqueue() */
    text: |
      The return status of ${../if/futex-wait:/name} shall be zero.
  - name: EAGAIN
    test-code: |
      eno = _Futex_Wait( &ctx->futex, &ctx->state, ctx->expected_value );
      T_eq_int( eno, EAGAIN );
    text: |
      The return status of ${../if/futex-wait:/name} shall be
      ${/c/if/eagain:/name}.
  test-epilogue: null
  test-prologue: |
    int eno;
- name: Enqueue
  states:
  - name: 'No'
    test-code: |
      /* The runner would block forever */
    text: |
      The calling thread shall not be enqueued on the thread queue of the futex
      object.
  - name: 'Yes'
    test-code: |
      ${/score/tq/req/enqueue-fifo:/test-run}( &ctx->tq_ctx );
    text: |
      The calling thread shall be enqueued in FIFO order on the thread queue of
      the futex object.
  test-epilogue: null
  test-prologue: null
pre-conditions:
- name: State
  states:
  - name: Equal
    test-code: |
      ctx->expected_value = 0;
    text: |
      While the expected futex state value is equal to the actual futex state
      value.
  - name: NotEqual
    test-code: |
      ctx->expected_value = 1;
    text: |
      While the expected futex state value is not equal to the actual futex
      state value.
  test-epilogue: null
  test-prologue: null
rationale: null
references: []
requirement-type: functional
skip-reasons: {}
test-action: |
  /* The action is performed in the post-conditions. */
test-brief: null
test-cleanup:
  _Futex_Destroy( &ctx->futex );
test-context:
- brief: |
    This member contains the thread queue test context.
  description: null
  member: |
    TQContext tq_ctx;
- brief: |
    This member specifies the expected futex state value.
  description: null
  member: |
    int expected_value
- brief: |
    This member provides the futex object.
  description: null
  member: |
    struct _Futex_Control futex
- brief: |
    This member provides the futex state.
  description: null
  member: |
    int state
test-context-support: null
test-description: null
test-header: null
test-includes:
- sys/lock.h
- limits.h
- rtems.h
test-local-includes:
- tx-thread-queue.h
- tr-tq-enqueue-fifo.h
test-prepare: |
  _Futex_Initialize( &ctx->futex );
  ctx->state = 0;
test-setup:
  brief: null
  code: |
    memset( ctx, 0, sizeof( *ctx ) );
    ctx->tq_ctx.discipline = TQ_FIFO;
    ctx->tq_ctx.wait = TQ_WAIT_FOREVER;
    ctx->tq_ctx.enqueue_prepare = TQDoNothing;
    ctx->tq_ctx.enqueue = Enqueue;
    ctx->tq_ctx.enqueue_done = EnqueueDone;
    ctx->tq_ctx.surrender = TQDoNothingSuccessfully;
    ctx->tq_ctx.convert_status = TQConvertStatusPOSIX;
    TQInitialize( &ctx->tq_ctx );
  description: null
test-stop: null
test-support: |
  typedef ${.:/test-context-type} Context;

  static Context *ToContext( TQContext *tq_ctx )
  {
    return RTEMS_CONTAINER_OF( tq_ctx, Context, tq_ctx );
  }

  static Status_Control Enqueue( TQContext *tq_ctx, TQWait wait )
  {
    Context *ctx;
    int      eno;

    ctx = ToContext( tq_ctx );
    eno = _Futex_Wait( &ctx->futex, &ctx->state, ctx->expected_value );
    T_eq_int( eno, 0 );

    return STATUS_BUILD( 0, eno );
  }

  static void EnqueueDone( TQContext *tq_ctx )
  {
    Context *ctx;
    int      count;

    ctx = ToContext( tq_ctx );
    count = _Futex_Wake( &ctx->futex, INT_MAX );
    T_eq_int( count, (int) ctx->tq_ctx.how_many );
  }
test-target: testsuites/validation/tc-futex-wait.c
test-teardown:
  brief: null
  code: |
    TQDestroy( &ctx->tq_ctx );
  description: null
text: ${.:text-template}
transition-map:
- enabled-by: true
  post-conditions:
    Result: EAGAIN
    Enqueue: 'No'
  pre-conditions:
    State:
    - NotEqual
- enabled-by: true
  post-conditions:
    Result: Zero
    Enqueue: 'Yes'
  pre-conditions:
    State:
    - Equal
type: requirement