spec: Specify rtems_interrupt_cause_on()

1 files changed, 454 insertions, 0 deletions

diff --git a/spec/rtems/intr/req/cause-on.yml b/spec/rtems/intr/req/cause-on.yml
new file mode 100644
index 00000000..c6a9b3dd
--- /dev/null
+++ b/spec/rtems/intr/req/cause-on.yml
@@ -0,0 +1,454 @@
+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/cause-on
+post-conditions:
+- name: Status
+  states:
+  - name: Ok
+    test-code: |
+      /* Validation is done by CheckCauseOn() for each interrupt vector */
+    text: |
+      The return status of ${../if/cause-on:/name} shall be
+      ${../../status/if/successful:/name}.
+  - name: InvId
+    test-code: |
+      T_rsc( ctx->status, RTEMS_INVALID_ID );
+    text: |
+      The return status of ${../if/cause-on:/name} shall be
+      ${../../status/if/invalid-id:/name}.
+  - name: NotConf
+    test-code: |
+      T_rsc( ctx->status, RTEMS_NOT_CONFIGURED );
+    text: |
+      The return status of ${../if/cause-on:/name} shall be
+      ${../../status/if/not-configured:/name}.
+  - name: IncStat
+    test-code: |
+      T_rsc( ctx->status, RTEMS_INCORRECT_STATE );
+    text: |
+      The return status of ${../if/cause-on:/name} shall be
+      ${../../status/if/incorrect-state:/name}.
+  - name: Unsat
+    test-code: |
+      /* Validation is done by CheckCauseOn() for each interrupt vector */
+    text: |
+      The return status of ${../if/cause-on:/name} shall be
+      ${../../status/if/unsatisfied:/name}.
+  test-epilogue: null
+  test-prologue: null
+- name: Pending
+  states:
+  - name: 'Yes'
+    test-code: |
+      /* Validation is done by CheckCauseOn() for each interrupt vector */
+    text: |
+      The interrupt associated with the interrupt vector specified by
+      ${../if/cause-on:/params[0]/name} shall be made pending by the
+      ${../if/cause-on:/name} call.
+  - name: 'No'
+    test-code: |
+      /* Validation is done by CheckCauseOn() for each interrupt vector */
+    text: |
+      The interrupt associated with the interrupt vector specified by
+      ${../if/cause-on:/params[0]/name} shall not be made pending by the
+      ${../if/cause-on:/name} call.
+  test-epilogue: null
+  test-prologue: null
+pre-conditions:
+- name: Vector
+  states:
+  - name: Valid
+    test-code: |
+      ctx->valid_vector = true;
+    text: |
+      While the ${../if/cause-on:/params[0]/name} parameter is
+      associated with an interrupt vector.
+  - name: Invalid
+    test-code: |
+      ctx->valid_vector = false;
+    text: |
+      While the ${../if/cause-on:/params[0]/name} parameter is
+      not associated with an interrupt vector.
+  test-epilogue: null
+  test-prologue: null
+- name: CPU
+  states:
+  - name: Online
+    test-code: |
+      ctx->cpu_index = 0;
+    text: |
+      While the ${../if/cause-on:/params[1]/name} parameter is associated with
+      a configured processor,
+      while the processor specified by ${../if/cause-on:/params[1]/name} is not
+      online.
+  - name: NotOnline
+    test-code: |
+      ctx->cpu_index = 4;
+    text: |
+      While the ${../if/cause-on:/params[1]/name} parameter is associated with
+      a configured processor,
+      while the processor specified by ${../if/cause-on:/params[1]/name} is not
+      online.
+  - name: NotConf
+    test-code: |
+      ctx->cpu_index = 5;
+    text: |
+      While the ${../if/cause-on:/params[1]/name} parameter is not associated
+      with a configured processor.
+  test-epilogue: null
+  test-prologue: null
+- name: CanCauseOn
+  states:
+  - name: 'Yes'
+    test-code: |
+      /*
+       * This pre-condition depends on the attributes of an interrupt vector,
+       * see CheckCauseOn().
+       */
+    text: |
+      While the interrupt vector associated with the
+      ${../if/cause-on:/params[0]/name} parameter can be caused on a processor.
+  - name: 'No'
+    test-code: |
+      /*
+       * This pre-condition depends on the attributes of an interrupt vector,
+       * see CheckCauseOn().
+       */
+    text: |
+      While the interrupt vector associated with the
+      ${../if/cause-on:/params[0]/name} parameter cannot be caused on a
+      processor.
+  test-epilogue: null
+  test-prologue: null
+rationale: null
+references: []
+requirement-type: functional
+skip-reasons:
+  OnlyOneCPU: |
+    Where the system is build with SMP support disabled, the system has exactly
+    one processor and its processor is always online.
+test-action: |
+  if ( ctx->valid_vector && ctx->cpu_index == 0 ) {
+    for (
+      ctx->vector = 0;
+      ctx->vector < BSP_INTERRUPT_VECTOR_COUNT;
+      ++ctx->vector
+    ) {
+      rtems_status_code          sc;
+      rtems_interrupt_attributes attr;
+      bool                       has_installed_entries;
+
+      memset( &attr, 0, sizeof( attr ) );
+      sc = rtems_interrupt_get_attributes( ctx->vector, &attr );
+
+      if ( sc == RTEMS_INVALID_ID ) {
+        continue;
+      }
+
+      T_rsc_success( sc );
+
+      has_installed_entries = HasInterruptVectorEntriesInstalled( ctx->vector );
+      CheckCauseOn( ctx, &attr, has_installed_entries );
+    }
+  } else {
+    if ( ctx->valid_vector ) {
+      ctx->vector = ctx->some_vector;
+    } else {
+      ctx->vector = BSP_INTERRUPT_VECTOR_COUNT;
+    }
+
+    ctx->status = rtems_interrupt_cause_on( ctx->vector, ctx->cpu_index );
+  }
+test-brief: null
+test-cleanup: null
+test-context:
+- brief: |
+    This member contains the count of serviced interrupts.
+  description: null
+  member: |
+    volatile uint32_t interrupt_count
+- brief: |
+    If this member is true, then the interrupt shall be cleared.
+  description: null
+  member: |
+    bool do_clear
+- brief: |
+    This member contains the current vector number.
+  description: null
+  member: |
+    rtems_vector_number vector
+- brief: |
+    This member contains some valid vector number.
+  description: null
+  member: |
+    rtems_vector_number some_vector
+- brief: |
+    If this member is true, then the ${../if/cause-on:/params[0]/name}
+    parameter shall be valid.
+  description: null
+  member: |
+    bool valid_vector
+- brief: |
+    This member specifies the ${../if/cause-on:/params[1]/name} parameter.
+  description: null
+  member: |
+    uint32_t cpu_index
+- brief: |
+    This member contains the return value of the ${../if/cause-on:/name}
+    call.
+  description: null
+  member: |
+    rtems_status_code status
+test-context-support: null
+test-description: null
+test-header: null
+test-includes:
+- rtems/irq-extension.h
+- bsp/irq-generic.h
+- string.h
+test-local-includes:
+- tx-support.h
+test-prepare: null
+test-setup:
+  brief: null
+  code: |
+    ctx->some_vector = GetValidInterruptVectorNumber( NULL );
+  description: null
+test-stop: null
+test-support: |
+  typedef RtemsIntrReqCauseOn_Context Context;
+
+  static bool IsEnabled( const Context *ctx )
+  {
+    rtems_status_code sc;
+    bool              enabled;
+
+    enabled = false;
+    sc = rtems_interrupt_vector_is_enabled( ctx->vector, &enabled );
+    T_rsc_success( sc );
+
+    return enabled;
+  }
+
+  static bool IsPending( const Context *ctx )
+  {
+    rtems_status_code sc;
+    bool              pending;
+
+    pending = false;
+    sc = rtems_interrupt_is_pending( ctx->vector, &pending );
+    T_rsc_success( sc );
+
+    return pending;
+  }
+
+  static void Disable( const Context *ctx )
+  {
+    rtems_status_code sc;
+
+    sc = rtems_interrupt_vector_disable( ctx->vector );
+    T_rsc_success( sc );
+  }
+
+  static void CauseOn( const Context *ctx )
+  {
+    rtems_status_code sc;
+
+    sc = rtems_interrupt_cause_on( ctx->vector, ctx->cpu_index );
+    T_rsc_success( sc );
+  }
+
+  static void EntryRoutine( void *arg )
+  {
+    Context *ctx;
+    uint32_t count;
+
+    (void) arg;
+    ctx = T_fixture_context();
+
+    count = ctx->interrupt_count;
+    ctx->interrupt_count = count + 1;
+
+    if ( ctx->do_clear ) {
+      rtems_status_code sc;
+
+      sc = rtems_interrupt_clear( ctx->vector );
+      T_rsc_success( sc );
+    }
+
+    if ( count > 2 ) {
+      /* Some interrupts are probably cased by a peripheral */
+      Disable( ctx );
+    }
+  }
+
+  static void CheckUnsatisfied( const Context *ctx )
+  {
+    rtems_status_code sc;
+    bool              pending_before;
+    bool              pending_after;
+
+    pending_before = true;
+    sc = rtems_interrupt_is_pending( ctx->vector, &pending_before );
+    T_rsc_success( sc );
+
+    sc = rtems_interrupt_cause_on( ctx->vector, ctx->cpu_index );
+    T_rsc( sc, RTEMS_UNSATISFIED );
+
+    pending_after = !pending_before;
+    sc = rtems_interrupt_is_pending( ctx->vector, &pending_after );
+    T_rsc_success( sc );
+
+    T_eq( pending_before, pending_after );
+  }
+
+  static void CheckCauseOn(
+    Context                          *ctx,
+    const rtems_interrupt_attributes *attr,
+    bool                              has_installed_entries
+  )
+  {
+    rtems_status_code sc;
+
+    if ( !attr->can_cause_on ) {
+      CheckUnsatisfied( ctx );
+    } else if ( has_installed_entries ) {
+      /* We cannot test this vector, since it is used by a device driver */
+    } else if ( !attr->is_maskable ) {
+      /* We can only safely test maskable interrupts */
+    } else if ( IsPending( ctx ) ) {
+      /*
+       * If there is already an interrupt pending, then it is probably caused
+       * by a peripheral which we cannot control.
+       */
+    } else if (
+      ( attr->always_enabled || attr->can_disable ) &&
+      ( attr->can_clear || attr->cleared_by_acknowledge )
+    ) {
+      rtems_interrupt_entry entry;
+      rtems_interrupt_level level;
+
+      ctx->interrupt_count = 0;
+      ctx->do_clear = attr->can_clear && !attr->cleared_by_acknowledge;
+      rtems_interrupt_entry_initialize( &entry, EntryRoutine, ctx, "Info" );
+      sc = rtems_interrupt_entry_install(
+        ctx->vector,
+        RTEMS_INTERRUPT_UNIQUE,
+        &entry
+      );
+      T_rsc_success( sc );
+
+      if ( !IsPending( ctx) && ( attr->can_enable || IsEnabled( ctx ) ) ) {
+        T_false( IsPending( ctx ) );
+
+        if ( attr->can_disable ) {
+          Disable( ctx );
+          CauseOn( ctx );
+          T_true( IsPending( ctx ) );
+
+          sc = rtems_interrupt_vector_enable( ctx->vector );
+          T_rsc_success( sc );
+
+          while ( ctx->interrupt_count < 1 ) {
+            /* Wait */
+          }
+        } else {
+          ++ctx->interrupt_count;
+        }
+
+        T_false( IsPending( ctx ) );
+
+        rtems_interrupt_local_disable( level );
+        CauseOn( ctx );
+        T_true( IsPending( ctx ) );
+        rtems_interrupt_local_enable( level );
+
+        while ( ctx->interrupt_count < 2 ) {
+          /* Wait */
+        }
+
+        T_false( IsPending( ctx ) );
+      }
+
+      sc = rtems_interrupt_entry_remove( ctx->vector, &entry );
+      T_rsc_success( sc );
+    }
+  }
+test-target: testsuites/validation/tc-intr-cause-on.c
+test-teardown: null
+text: ${.:text-template}
+transition-map:
+- enabled-by: true
+  post-conditions:
+    Status: Ok
+    Pending: 'Yes'
+  pre-conditions:
+    Vector:
+    - Valid
+    CPU:
+    - Online
+    CanCauseOn:
+    - 'Yes'
+- enabled-by: true
+  post-conditions:
+    Status: InvId
+    Pending: N/A
+  pre-conditions:
+    Vector:
+    - Invalid
+    CPU: all
+    CanCauseOn: N/A
+- enabled-by: true
+  post-conditions:
+    Status: NotConf
+    Pending: 'No'
+  pre-conditions:
+    Vector:
+    - Valid
+    CPU:
+    - NotConf
+    CanCauseOn: all
+- enabled-by: true
+  post-conditions:
+    Status: Unsat
+    Pending: 'No'
+  pre-conditions:
+    Vector:
+    - Valid
+    CPU:
+    - Online
+    CanCauseOn:
+    - 'No'
+- enabled-by: true
+  post-conditions: OnlyOneCPU
+  pre-conditions:
+    Vector: all
+    CPU:
+    - NotOnline
+    CanCauseOn: all
+- enabled-by: RTEMS_SMP
+  post-conditions:
+    Status: InvId
+    Pending: N/A
+  pre-conditions:
+    Vector:
+    - Invalid
+    CPU:
+    - NotOnline
+    CanCauseOn: N/A
+- enabled-by: RTEMS_SMP
+  post-conditions:
+    Status: IncStat
+    Pending: 'No'
+  pre-conditions:
+    Vector:
+    - Valid
+    CPU:
+    - NotOnline
+    CanCauseOn: all
+type: requirement