path: root/spec/bsp/req/interrupt-handler-dispatch-unchecked.yml

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
copyrights:
- Copyright (C) 2021, 2023 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
functional-type: action
links:
- role: interface-function
  uid: ../if/interrupt-handler-dispatch-unchecked
post-conditions:
- name: Result
  states:
  - name: FatalError
    test-code: |
      T_eq_u32( ctx->entry_counter, 0 );
      T_eq_u32( ctx->fatal_counter, 1 );
    text: |
      A fatal error shall occur.
  - name: Dispatch
    test-code: |
      T_eq_u32( ctx->entry_counter, 1 );
      T_eq_u32( ctx->fatal_counter, 0 );
    text: |
      The interrupt entries installed at the interrupt vector specified by the
      ``vector`` parameter shall be dispatched.
  test-epilogue: null
  test-prologue: null
- name: FatalSource
  states:
  - name: SpuriousInterrupt
    test-code: |
      T_eq_int( ctx->fatal_source, RTEMS_FATAL_SOURCE_SPURIOUS_INTERRUPT );
    text: |
      The fatal source shall be equal to
      ${/score/interr/if/source-spurious-interrupt:/name}.
  test-epilogue: null
  test-prologue: null
- name: FatalCode
  states:
  - name: Vector
    test-code: |
      T_eq_ulong( ctx->fatal_code, ctx->test_vector );
    text: |
      The fatal code shall be equal to the ``vector`` parameter.
  test-epilogue: null
  test-prologue: null
pre-conditions:
- name: LoadFirst
  states:
  - name: 'Null'
    test-code: |
      *ctx->first = NULL;
    text: |
      While the first loaded value of the pointer to the first interrupt entry
      of the interrupt vector specified by the ``vector`` parameter is equal to
      ${/c/if/null:/name}.
  - name: Entry
    test-code: |
      *ctx->first = &ctx->entry;
    text: |
      While the first loaded value of the pointer to the first interrupt entry
      of the interrupt vector specified by the ``vector`` parameter references
      an object of type ${/rtems/intr/if/entry:/name}.
  test-epilogue: null
  test-prologue: null
- name: LoadFirstAgain
  states:
  - name: 'Null'
    test-code: |
      ctx->first_again = NULL;
    text: |
      While the second loaded value of the pointer to the first interrupt entry
      of the interrupt vector specified by the ``vector`` parameter is equal to
      ${/c/if/null:/name}.
  - name: Entry
    test-code: |
      ctx->first_again = &ctx->entry;
    text: |
      While the second loaded value of the pointer to the first interrupt entry
      of the interrupt vector specified by the ``vector`` parameter references
      an object of type ${/rtems/intr/if/entry:/name}.
  test-epilogue: null
  test-prologue: null
rationale: null
references: []
requirement-type: functional
skip-reasons: {}
test-action: |
  ctx->interrupt_occurred = false;
  ctx->entry_counter = 0;
  ctx->fatal_counter = 0;
  ctx->fatal_source = RTEMS_FATAL_SOURCE_LAST;
  ctx->fatal_code = UINT32_MAX;

  (void) rtems_interrupt_vector_enable( ctx->test_vector );

  CallWithinISRRaise();

  while ( !ctx->interrupt_occurred ) {
    /* Wait */
  }

  Disable( ctx );
test-brief: null
test-cleanup: null
test-context:
- brief: |
    This member references the interrupt entry to restore during test case
    teardown.
  description: null
  member: |
    rtems_interrupt_entry *entry_to_restore
- brief: |
    This member provides a jump buffer to return from the fatal error.
  description: null
  member: |
    jmp_buf before_call
- brief: |
    This member provides an interrupt entry to be dispatched.
  description: null
  member: |
    rtems_interrupt_entry entry
- brief: |
    This member is true, then an interrupt occurred.
  description: null
  member: |
    volatile bool interrupt_occurred
- brief: |
    This member provides an entry dispatch counter.
  description: null
  member: |
    uint32_t entry_counter
- brief: |
    This member provides a fatal error counter.
  description: null
  member: |
    uint32_t fatal_counter
- brief: |
    This member contains the fatal source.
  description: null
  member: |
    rtems_fatal_source fatal_source
- brief: |
    This member contains a fatal code.
  description: null
  member: |
    rtems_fatal_code fatal_code
- brief: |
    This member contains the vector number of a testable interrupt.
  description: null
  member: |
    rtems_vector_number test_vector
- brief: |
    This member references the pointer to the first entry of the interrupt
    vector.
  description: null
  member: |
    rtems_interrupt_entry **first
- brief: |
    This member references an interrupt entry for the first entry of the
    interrupt vector or is NULL.
  description: null
  member: |
    rtems_interrupt_entry *first_again
test-context-support: null
test-description: null
test-header: null
test-includes:
- bsp/irq-generic.h
- setjmp.h
test-local-includes:
- tx-support.h
test-prepare: null
test-setup:
  brief: null
  code: |
    ctx->first = NULL;
    ctx->test_vector = CallWithinISRGetVector();
    T_assert_lt_u32( ctx->test_vector, BSP_INTERRUPT_VECTOR_COUNT );
    ctx->first = &bsp_interrupt_dispatch_table[
      bsp_interrupt_dispatch_index( ctx->test_vector )
    ];
    ctx->entry_to_restore = *ctx->first;

    rtems_interrupt_entry_initialize( &ctx->entry, EntryRoutine, ctx, "Info" );
    test_case_active = true;
    SetFatalHandler( Fatal, ctx );
  description: null
test-stop: null
test-support: |
  typedef ${.:/test-context-type} Context;

  static bool test_case_active;

  static void Disable( const Context *ctx )
  {
    (void) rtems_interrupt_vector_disable( ctx->test_vector );
  }

  static void ProcessInterrupt( Context *ctx )
  {
    ctx->interrupt_occurred = true;
    CallWithinISRClear();
    Disable( ctx );
  }

  static void EntryRoutine( void *arg )
  {
    Context *ctx;

    ctx = arg;
    ++ctx->entry_counter;
    ProcessInterrupt( ctx );
  }

  static void Fatal(
    rtems_fatal_source source,
    rtems_fatal_code   code,
    void              *arg
  )
  {
    Context *ctx;

    ctx = arg;
    ctx->fatal_source = source;
    ctx->fatal_code = code;
    ++ctx->fatal_counter;
    longjmp( ctx->before_call, 1 );
  }

  void __real_bsp_interrupt_handler_default( rtems_vector_number vector );

  void __wrap_bsp_interrupt_handler_default( rtems_vector_number vector );

  void __wrap_bsp_interrupt_handler_default( rtems_vector_number vector )
  {
    if ( test_case_active ) {
      Context *ctx;

      ctx = T_fixture_context();
      ProcessInterrupt( ctx );

      if ( setjmp( ctx->before_call ) == 0 ) {
        __real_bsp_interrupt_handler_default( vector );
      }
    } else {
      __real_bsp_interrupt_handler_default( vector );
    }
  }

  #if defined(RTEMS_SMP)
  void __real_bsp_interrupt_spurious( rtems_vector_number vector );

  void __wrap_bsp_interrupt_spurious( rtems_vector_number vector );

  void __wrap_bsp_interrupt_spurious( rtems_vector_number vector )
  {
    if ( test_case_active ) {
      Context *ctx;

      ctx = T_fixture_context();
      *ctx->first = ctx->first_again;
    }

    __real_bsp_interrupt_spurious( vector );
  }
  #endif
test-target: testsuites/validation/tc-bsp-interrupt-handler-dispatch-unchecked.c
test-teardown:
  brief: null
  code: |
    SetFatalHandler( NULL, NULL );
    test_case_active = false;

    if ( ctx->first != NULL ) {
      *ctx->first = ctx->entry_to_restore;
    }
  description: null
text: ${.:text-template}
transition-map:
- enabled-by: true
  post-conditions:
    Result: FatalError
    FatalSource: SpuriousInterrupt
    FatalCode: Vector
  pre-conditions:
    LoadFirst:
    - 'Null'
    LoadFirstAgain: N/A
- enabled-by: true
  post-conditions:
    Result: Dispatch
    FatalSource: N/A
    FatalCode: N/A
  pre-conditions:
    LoadFirst:
    - Entry
    LoadFirstAgain: N/A
- enabled-by: RTEMS_SMP
  post-conditions:
    Result: FatalError
    FatalSource: SpuriousInterrupt
    FatalCode: Vector
  pre-conditions:
    LoadFirst:
    - 'Null'
    LoadFirstAgain:
    - 'Null'
- enabled-by: RTEMS_SMP
  post-conditions:
    Result: Dispatch
    FatalSource: N/A
    FatalCode: N/A
  pre-conditions:
    LoadFirst:
    - 'Null'
    LoadFirstAgain:
    - Entry
type: requirement