spec: Add interrupt entry directives

8 files changed, 365 insertions, 0 deletions

diff --git a/spec/rtems/intr/constraint/entry-initialized.yml b/spec/rtems/intr/constraint/entry-initialized.yml
new file mode 100644
index 00000000..918fcde3
--- /dev/null
+++ b/spec/rtems/intr/constraint/entry-initialized.yml
@@ -0,0 +1,12 @@
+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
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  The interrupt entry shall have been initialized by
+  ${../if/entry-initialize:/name} or ${../if/entry-initializer:/name}.
+type: constraint
diff --git a/spec/rtems/intr/constraint/entry-installed.yml b/spec/rtems/intr/constraint/entry-installed.yml
new file mode 100644
index 00000000..52bd52d1
--- /dev/null
+++ b/spec/rtems/intr/constraint/entry-installed.yml
@@ -0,0 +1,12 @@
+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
+links:
+- role: requirement-refinement
+  uid: /req/usage-constraints
+rationale: null
+text: |
+  The interrupt entry shall have been installed by
+  ${../if/entry-install:/name}.
+type: constraint
diff --git a/spec/rtems/intr/if/entry-initialize.yml b/spec/rtems/intr/if/entry-initialize.yml
new file mode 100644
index 00000000..df966948
--- /dev/null
+++ b/spec/rtems/intr/if/entry-initialize.yml
@@ -0,0 +1,58 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Initializes the interrupt entry.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: |
+      ${.:/params[0]/name}->handler = ${.:/params[1]/name};
+      ${.:/params[0]/name}->arg = ${.:/params[2]/name};
+      ${.:/params[0]/name}->next = ${/c/if/null:/name};
+      ${.:/params[0]/name}->info = ${.:/params[3]/name};
+    params:
+    - ${entry:/name} *${.:/params[0]/name}
+    - ${handler:/name} ${.:/params[1]/name}
+    - void *${.:/params[2]/name}
+    - const char *${.:/params[3]/name}
+    return: void
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header-2
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-any
+- role: constraint
+  uid: /constraint/directive-no-preempt
+name: rtems_interrupt_entry_initialize
+notes: |
+  Alternatively, ${entry-initializer:/name} may be used to statically
+  initialize an interrupt entry.
+params:
+- description: |
+    is the interrupt entry to initialize.
+  dir: out
+  name: entry
+- description: |
+    is the interrupt handler routine for the entry.
+  dir: null
+  name: routine
+- description: |
+    is the interrupt handler argument for the entry.
+  dir: null
+  name: arg
+- description: |
+    is the descriptive information for the entry.
+  dir: null
+  name: info
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/intr/if/entry-initializer.yml b/spec/rtems/intr/if/entry-initializer.yml
new file mode 100644
index 00000000..eadc174a
--- /dev/null
+++ b/spec/rtems/intr/if/entry-initializer.yml
@@ -0,0 +1,39 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Statically initializes an interrupt entry object.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default: |
+    { ${.:/params[0]/name},  ${.:/params[1]/name}, ${/c/if/null:/name}, ${.:/params[2]/name} }
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: macro
+links:
+- role: interface-placement
+  uid: header-2
+- role: interface-ingroup
+  uid: group
+name: RTEMS_INTERRUPT_ENTRY_INITIALIZER
+notes: |
+  Alternatively, ${entry-initialize:/name} may be used to dynamically
+  initialize an interrupt entry.
+params:
+- description: |
+    is the interrupt handler routine for the entry.
+  dir: null
+  name: _routine
+- description: |
+    is the interrupt handler argument for the entry.
+  dir: null
+  name: _arg
+- description: |
+    is the descriptive information for the entry.
+  dir: null
+  name: _info
+return:
+  return: null
+  return-values: []
+type: interface
diff --git a/spec/rtems/intr/if/entry-install.yml b/spec/rtems/intr/if/entry-install.yml
new file mode 100644
index 00000000..45711977
--- /dev/null
+++ b/spec/rtems/intr/if/entry-install.yml
@@ -0,0 +1,109 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Installs the interrupt entry at the interrupt vector.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - ${vector-number:/name} ${.:/params[0]/name}
+    - ${../../option/if/option:/name} ${.:/params[1]/name}
+    - ${entry:/name} *${.:/params[2]/name}
+    return: ${../../status/if/code:/name}
+  variants: []
+description: |
+  One of the following mutually exclusive options
+
+  * ${unique:/name}, and
+
+  * ${shared:/name}
+
+  shall be set in the ${.:/params[1]/name} parameter.
+
+  The handler routine of the entry specified by ${.:/params[2]/name} will be
+  called with the handler argument of the entry when dispatched.  The order in
+  which shared interrupt handlers are dispatched for one vector is defined by
+  the installation order.  The first installed handler is dispatched first.
+
+  If the option ${unique:/name} is set, then it will be ensured that the
+  handler will be the only one for the interrupt vector.
+
+  If the option ${shared:/name} is set, then multiple handler may be installed
+  for the interrupt vector.
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header-2
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../constraint/entry-initialized
+name: rtems_interrupt_entry_install
+notes: |
+  When the directive call was successful, the ownership of the interrupt entry
+  has been transferred from the caller to the interrupt service.  An installed
+  interrupt entry may be removed from the interrupt service by calling
+  ${entry-remove:/name}.
+params:
+- description: |
+    is the interrupt vector number.
+  dir: null
+  name: vector
+- description: |
+    is the interrupt entry install option set.
+  dir: null
+  name: options
+- description: |
+    is the interrupt entry to install
+  dir: null
+  name: entry
+return:
+  return: null
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      The service was not initialized.
+    value: ${../../status/if/incorrect-state:/name}
+  - description: |
+      The handler routine of the entry was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      There was no interrupt vector associated with the number specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The directive was called from within interrupt context.
+    value: ${../../status/if/called-from-isr:/name}
+  - description: |
+      An option specified by ${.:/params[1]/name} was not applicable.
+    value: ${../../status/if/invalid-number:/name}
+  - description: |
+      The ${unique:/name} option was set in ${.:/params[2]/name} and the
+      interrupt vector was already occupied by a handler.
+    value: ${../../status/if/resource-in-use:/name}
+  - description: |
+      The ${shared:/name} option was set in ${.:/params[2]/name} and the
+      interrupt vector was already occupied by a unique handler.
+    value: ${../../status/if/resource-in-use:/name}
+  - description: |
+      The handler routine of the entry specified by ${.:/params[2]/name} was
+      already installed for the interrupt vector specified by
+      ${.:/params[0]/name} with an argument equal to the handler argument of
+      the entry.
+    value: ${../../status/if/too-many:/name}
+type: interface
diff --git a/spec/rtems/intr/if/entry-remove.yml b/spec/rtems/intr/if/entry-remove.yml
new file mode 100644
index 00000000..83f4f157
--- /dev/null
+++ b/spec/rtems/intr/if/entry-remove.yml
@@ -0,0 +1,68 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  Removes the interrupt entry from the interrupt vector.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+  default:
+    attributes: null
+    body: null
+    params:
+    - ${vector-number:/name} ${.:/params[0]/name}
+    - ${entry:/name} *${.:/params[1]/name}
+    return: ${../../status/if/code:/name}
+  variants: []
+description: null
+enabled-by: true
+index-entries: []
+interface-type: function
+links:
+- role: interface-placement
+  uid: header-2
+- role: interface-ingroup
+  uid: group
+- role: constraint
+  uid: /constraint/directive-ctx-devinit
+- role: constraint
+  uid: /constraint/directive-ctx-task
+- role: constraint
+  uid: /constraint/object-allocator
+- role: constraint
+  uid: ../constraint/entry-installed
+name: rtems_interrupt_entry_remove
+notes: |
+  When the directive call was successful, the ownership of the interrupt entry
+  has been transferred from the interrupt service to the caller.
+params:
+- description: |
+    is the interrupt vector number.
+  dir: null
+  name: vector
+- description: |
+    is the interrupt entry to remove.
+  dir: null
+  name: entry
+return:
+  return: null
+  return-values:
+  - description: |
+      The requested operation was successful.
+    value: ${../../status/if/successful:/name}
+  - description: |
+      The service was not initialized.
+    value: ${../../status/if/incorrect-state:/name}
+  - description: |
+      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
+    value: ${../../status/if/invalid-address:/name}
+  - description: |
+      There was no interrupt vector associated with the number specified by
+      ${.:/params[0]/name}.
+    value: ${../../status/if/invalid-id:/name}
+  - description: |
+      The directive was called from within interrupt context.
+    value: ${../../status/if/called-from-isr:/name}
+  - description: |
+      The entry specified by ${.:/params[1]/name} was not installed at the
+      interrupt vector specified by ${.:/params[0]/name}.
+    value: ${../../status/if/unsatisfied:/name}
+type: interface
diff --git a/spec/rtems/intr/if/entry.yml b/spec/rtems/intr/if/entry.yml
new file mode 100644
index 00000000..d3e33410
--- /dev/null
+++ b/spec/rtems/intr/if/entry.yml
@@ -0,0 +1,57 @@
+SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
+brief: |
+  This structure represents an interrupt entry.
+copyrights:
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
+definition:
+- default:
+    brief: |
+      This member is the interrupt handler routine.
+    definition: ${handler:/name} ${.:name}
+    description: null
+    kind: member
+    name: handler
+  variants: []
+- default:
+    brief: |
+      This member is the interrupt handler argument.
+    definition: void *${.:name}
+    description: null
+    kind: member
+    name: arg
+  variants: []
+- default:
+    brief: |
+      This member is the reference to the next entry or ${/c/if/null:/name}.
+    definition: struct rtems_interrupt_entry *${.:name}
+    description: null
+    kind: member
+    name: next
+  variants: []
+- default:
+    brief: |
+      This member is the descriptive information of the entry
+    definition: const char *${.:name}
+    description: null
+    kind: member
+    name: info
+  variants: []
+definition-kind: typedef-and-struct
+description: null
+enabled-by: true
+index-entries: []
+interface-type: struct
+links:
+- role: interface-placement
+  uid: header-2
+- role: interface-ingroup
+  uid: group
+name: rtems_interrupt_entry
+notes: |
+  This structure shall be treated as an opaque data type from the
+  ${/glossary/api:/term} point of view.  Members shall not be accessed
+  directly.  An entry may be initialized by ${entry-initializer:/name} or
+  ${entry-initialize:/name}.  It may be installed for an interrupt vector with
+  ${entry-install:/name} and removed from an interrupt vector by
+  ${entry-remove:/name}.
+type: interface
diff --git a/spec/rtems/intr/if/group.yml b/spec/rtems/intr/if/group.yml
index 7bc0f387..975bd8ca 100644
--- a/spec/rtems/intr/if/group.yml
+++ b/spec/rtems/intr/if/group.yml
@@ -70,6 +70,16 @@ links:
 - role: placement-order
   uid: is-replace
 - role: placement-order
+  uid: entry
+- role: placement-order
+  uid: entry-initializer
+- role: placement-order
+  uid: entry-initialize
+- role: placement-order
+  uid: entry-install
+- role: placement-order
+  uid: entry-remove
+- role: placement-order
   uid: handler-install
 - role: placement-order
   uid: handler-remove