[rtems-central commit] spec: Add interrupt entry directives
Sebastian Huber
sebh at rtems.org
Mon Jul 12 12:57:20 UTC 2021
Module: rtems-central
Branch: master
Commit: b04d86d96cccca4e8008c5818b448d88409e5969
Changeset: http://git.rtems.org/rtems-central/commit/?id=b04d86d96cccca4e8008c5818b448d88409e5969
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Thu Jun 17 14:20:07 2021 +0200
spec: Add interrupt entry directives
---
spec/rtems/intr/constraint/entry-initialized.yml | 12 +++
spec/rtems/intr/constraint/entry-installed.yml | 12 +++
spec/rtems/intr/if/entry-initialize.yml | 58 ++++++++++++
spec/rtems/intr/if/entry-initializer.yml | 39 ++++++++
spec/rtems/intr/if/entry-install.yml | 109 +++++++++++++++++++++++
spec/rtems/intr/if/entry-remove.yml | 68 ++++++++++++++
spec/rtems/intr/if/entry.yml | 57 ++++++++++++
spec/rtems/intr/if/group.yml | 10 +++
8 files changed, 365 insertions(+)
diff --git a/spec/rtems/intr/constraint/entry-initialized.yml b/spec/rtems/intr/constraint/entry-initialized.yml
new file mode 100644
index 0000000..918fcde
--- /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 0000000..52bd52d
--- /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 0000000..df96694
--- /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 0000000..eadc174
--- /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 0000000..4571197
--- /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 0000000..83f4f15
--- /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 0000000..d3e3341
--- /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 7bc0f38..975bd8c 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
More information about the vc
mailing list