[rtems-central commit] spec: Update /rtems/intr/* documentation
Sebastian Huber
sebh at rtems.org
Wed Apr 28 07:04:36 UTC 2021
Module: rtems-central
Branch: master
Commit: 1c036bbb871d2e1246ab7a84f814de1b6a6d38d2
Changeset: http://git.rtems.org/rtems-central/commit/?id=1c036bbb871d2e1246ab7a84f814de1b6a6d38d2
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Thu Apr 22 14:03:25 2021 +0200
spec: Update /rtems/intr/* documentation
---
spec-glossary/glossary/target-arch.yml | 14 +++++
spec/constraint/cpu-simple-vectored-interrupts.yml | 11 ++++
spec/constraint/interrupt-enable.yml | 13 +++++
spec/constraint/no-impl.yml | 10 ++++
spec/rtems/intr/constraint/no-smp.yml | 13 +++++
spec/rtems/intr/if/catch.yml | 56 +++++++++++++++---
spec/rtems/intr/if/cause.yml | 15 +++--
spec/rtems/intr/if/clear.yml | 15 +++--
spec/rtems/intr/if/disable.yml | 65 ++++++++++++++++++---
spec/rtems/intr/if/enable.yml | 35 ++++++++---
spec/rtems/intr/if/flash.yml | 33 ++++++++---
spec/rtems/intr/if/group.yml | 44 +++++++++++++-
spec/rtems/intr/if/header.yml | 2 +-
spec/rtems/intr/if/is-in-progress.yml | 22 +++++--
spec/rtems/intr/if/isr-entry.yml | 2 +-
spec/rtems/intr/if/isr.yml | 9 ++-
spec/rtems/intr/if/level.yml | 5 +-
spec/rtems/intr/if/local-disable.yml | 68 +++++++++++++++++++---
spec/rtems/intr/if/local-enable.yml | 33 ++++++++---
spec/rtems/intr/if/lock-acquire-isr.yml | 42 ++++++++++---
spec/rtems/intr/if/lock-acquire.yml | 54 ++++++++++++++---
spec/rtems/intr/if/lock-context.yml | 5 +-
spec/rtems/intr/if/lock-declare.yml | 17 ++++--
spec/rtems/intr/if/lock-define.yml | 24 +++++---
spec/rtems/intr/if/lock-destroy.yml | 22 +++++--
spec/rtems/intr/if/lock-initialize.yml | 18 ++++--
spec/rtems/intr/if/lock-initializer.yml | 13 +++--
spec/rtems/intr/if/lock-isr-disable.yml | 18 ++++--
spec/rtems/intr/if/lock-member.yml | 11 ++--
spec/rtems/intr/if/lock-reference.yml | 14 +++--
spec/rtems/intr/if/lock-release-isr.yml | 32 +++++++---
spec/rtems/intr/if/lock-release.yml | 34 ++++++++---
spec/rtems/intr/if/lock.yml | 5 +-
spec/rtems/intr/if/vector-number.yml | 5 +-
34 files changed, 632 insertions(+), 147 deletions(-)
diff --git a/spec-glossary/glossary/target-arch.yml b/spec-glossary/glossary/target-arch.yml
new file mode 100644
index 0000000..364ddfb
--- /dev/null
+++ b/spec-glossary/glossary/target-arch.yml
@@ -0,0 +1,14 @@
+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
+glossary-type: term
+links:
+- role: glossary-member
+ uid: ../glossary-general
+term: target architecture
+text: |
+ The target architecture is the instruction set architecture (ISA) of the
+ ${target:/term}. Some RTEMS features depend on the target architecture. For
+ the details consult the *RTEMS CPU Architecture Supplement*.
+type: glossary
diff --git a/spec/constraint/cpu-simple-vectored-interrupts.yml b/spec/constraint/cpu-simple-vectored-interrupts.yml
new file mode 100644
index 0000000..30878e5
--- /dev/null
+++ b/spec/constraint/cpu-simple-vectored-interrupts.yml
@@ -0,0 +1,11 @@
+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: []
+rationale: null
+scope: user
+text: |
+ The directive is only available where the ${/glossary/target-arch:/term}
+ support enabled simple vectored interrupts.
+type: constraint
diff --git a/spec/constraint/interrupt-enable.yml b/spec/constraint/interrupt-enable.yml
new file mode 100644
index 0000000..6766312
--- /dev/null
+++ b/spec/constraint/interrupt-enable.yml
@@ -0,0 +1,13 @@
+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: []
+rationale: null
+scope: user
+text: |
+ While at least one maskable interrupt is pending, when the directive enables
+ maskable interrupts, the pending interrupts are immediately serviced. The
+ interrupt service routines may unblock higher priority tasks which may
+ preempt the calling task.
+type: constraint
diff --git a/spec/constraint/no-impl.yml b/spec/constraint/no-impl.yml
new file mode 100644
index 0000000..338c1b9
--- /dev/null
+++ b/spec/constraint/no-impl.yml
@@ -0,0 +1,10 @@
+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: []
+rationale: null
+scope: user
+text: |
+ The directive is not implemented.
+type: constraint
diff --git a/spec/rtems/intr/constraint/no-smp.yml b/spec/rtems/intr/constraint/no-smp.yml
new file mode 100644
index 0000000..401d687
--- /dev/null
+++ b/spec/rtems/intr/constraint/no-smp.yml
@@ -0,0 +1,13 @@
+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: []
+rationale: null
+scope: user
+text: |
+ Where the system was built with SMP support enabled, the directive is not
+ available. Its use will result in compiler warnings and linker errors. The
+ ${../if/local-disable:/name} and ${../if/local-enable:/name} directives are
+ available in all build configurations.
+type: constraint
diff --git a/spec/rtems/intr/if/catch.yml b/spec/rtems/intr/if/catch.yml
index 8ab54be..14dd7fe 100644
--- a/spec/rtems/intr/if/catch.yml
+++ b/spec/rtems/intr/if/catch.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Establishes an interrupt service routine.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default:
@@ -13,28 +14,65 @@ definition:
- ${isr-entry:/name} *${.:/params[2]/name}
return: ${../../status/if/code:/name}
variants: []
-description: null
+description: |
+ This directive establishes an interrupt service routine (ISR) for the
+ interrupt specified by the ${.:/params[1]/name} number. The
+ ${.:/params[0]/name} parameter specifies the entry point of the ISR. The
+ entry point of the previous ISR for the specified vector is returned in
+ ${.:/params[2]/name}.
+
+ To release an interrupt vector, pass the old handler's address obtained when
+ the vector was first capture.
enabled-by: true
-index-entries: []
+index-entries:
+- establish an ISR
+- install an ISR
interface-type: function
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-isr
+- role: constraint
+ uid: /constraint/directive-ctx-devinit
+- role: constraint
+ uid: /constraint/directive-ctx-task
+- role: constraint
+ uid: /constraint/directive-no-preempt
+- role: constraint
+ uid: /constraint/cpu-simple-vectored-interrupts
name: rtems_interrupt_catch
notes: null
params:
-- description: '%'
+- description: |
+ is the new interrupt service routine.
dir: null
name: new_isr_handler
-- description: '%'
+- description: |
+ is the interrupt vector number.
dir: null
name: vector
-- description: '%'
- dir: null
+- description: |
+ is the pointer to an ${isr-entry:/name} variable. When the directive call
+ is successful, the previous interrupt service routine established for this
+ interrupt vector will be stored in this variable.
+ dir: out
name: old_isr_handler
return:
return: null
- return-values: []
+ return-values:
+ - description: |
+ The requested operation was successful.
+ value: ${../../status/if/successful:/name}
+ - description: |
+ The interrupt vector number was illegal.
+ value: ${../../status/if/invalid-number:/name}
+ - description: |
+ The ${.:/params[0]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
+ - description: |
+ The ${.:/params[2]/name} parameter was ${/c/if/null:/name}.
+ value: ${../../status/if/invalid-address:/name}
type: interface
diff --git a/spec/rtems/intr/if/cause.yml b/spec/rtems/intr/if/cause.yml
index f22feca..0ab332e 100644
--- a/spec/rtems/intr/if/cause.yml
+++ b/spec/rtems/intr/if/cause.yml
@@ -1,10 +1,12 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Causes the interrupt.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
- default: '%'
+ default: |
+ do { } while ( 0 )
variants: []
description: null
enabled-by: true
@@ -15,12 +17,15 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/no-impl
name: rtems_interrupt_cause
notes: null
params:
-- description: '%'
+- description: |
+ is the vector number of the interrupt to cause.
dir: null
- name: _interrupt_to_cause
+ name: _vector
return:
return: null
return-values: []
diff --git a/spec/rtems/intr/if/clear.yml b/spec/rtems/intr/if/clear.yml
index 3004ab2..f92bbed 100644
--- a/spec/rtems/intr/if/clear.yml
+++ b/spec/rtems/intr/if/clear.yml
@@ -1,10 +1,12 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Clears the interrupt.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
- default: '%'
+ default: |
+ do { } while ( 0 )
variants: []
description: null
enabled-by: true
@@ -15,12 +17,15 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/no-impl
name: rtems_interrupt_clear
notes: null
params:
-- description: '%'
+- description: |
+ is the vector number of the interrupt to clear.
dir: null
- name: _interrupt_to_clear
+ name: _vector
return:
return: null
return-values: []
diff --git a/spec/rtems/intr/if/disable.yml b/spec/rtems/intr/if/disable.yml
index 7285624..08208e7 100644
--- a/spec/rtems/intr/if/disable.yml
+++ b/spec/rtems/intr/if/disable.yml
@@ -1,26 +1,77 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Disables the maskable interrupts on the current processor.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/local-disable:/name}( ${.:/params[0]/name} )
variants: []
-description: null
+description: |
+ This directive disables all maskable interrupts on the current processor and
+ returns the previous interrupt level in ${.:/params[0]/name}.
enabled-by:
not: RTEMS_SMP
-index-entries: []
+index-entries:
+- disable interrupts
interface-type: macro
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
+- role: constraint
+ uid: ../constraint/no-smp
name: rtems_interrupt_disable
-notes: null
+notes: |
+ A later invocation of the ${enable:/name} directive should be used to restore
+ the previous interrupt level.
+
+ This directive is implemented as a macro which sets the ${.:/params[0]/name}
+ parameter.
+
+ .. code-block:: c
+ :linenos:
+
+ #include <rtems.h>
+
+ void local_critical_section( void )
+ {
+ rtems_interrupt_level level;
+
+ // Please note that the rtems_interrupt_disable() is a macro. The
+ // previous interrupt level (before the maskable interrupts are
+ // disabled) is returned here in the level macro parameter. This
+ // would be wrong:
+ //
+ // rtems_interrupt_disable( &level );
+ rtems_interrupt_disable( level );
+
+ // Here is the critical section: maskable interrupts are disabled
+
+ {
+ rtems_interrupt_level nested_level;
+
+ rtems_interrupt_disable( nested_level );
+
+ // Here is a nested critical section
+
+ rtems_interrupt_enable( nested_level );
+ }
+
+ // Maskable interrupts are still disabled
+
+ rtems_interrupt_enable( level );
+ }
params:
-- description: '%'
- dir: null
+- description: |
+ is a variable of type ${level:/name} which will be used to save the
+ previous interrupt level.
+ dir: out
name: _isr_cookie
return:
return: null
diff --git a/spec/rtems/intr/if/enable.yml b/spec/rtems/intr/if/enable.yml
index 49a6a02..97d7dbf 100644
--- a/spec/rtems/intr/if/enable.yml
+++ b/spec/rtems/intr/if/enable.yml
@@ -1,26 +1,47 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Restores the previous interrupt level on the current processor.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/local-enable:/name}( ${.:/params[0]/name} )
variants: []
-description: null
+description: |
+ This directive restores the interrupt level specified by
+ ${.:/params[0]/name} on the current processor.
enabled-by:
not: RTEMS_SMP
-index-entries: []
+index-entries:
+- enable interrupts
+- restore interrupt level
interface-type: macro
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
+- role: constraint
+ uid: /constraint/interrupt-enable
+- role: constraint
+ uid: ../constraint/no-smp
name: rtems_interrupt_enable
-notes: null
+notes: |
+ The ${.:/params[0]/name} parameter value must be obtained by a previous
+ call to ${disable:/name} or ${flash:/name}. Using an otherwise obtained
+ value is undefined behaviour.
+
+ This directive is unsuitable to enable particular interrupt sources, for
+ example in an interrupt controller.
params:
-- description: '%'
- dir: null
+- description: |
+ is the previous interrupt level to restore. The value must be obtained by
+ a previous call to ${disable:/name} or ${flash:/name}.
+ dir: in
name: _isr_cookie
return:
return: null
diff --git a/spec/rtems/intr/if/flash.yml b/spec/rtems/intr/if/flash.yml
index 2832326..05e8ef7 100644
--- a/spec/rtems/intr/if/flash.yml
+++ b/spec/rtems/intr/if/flash.yml
@@ -1,26 +1,45 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Flashes interrupts on the current processor.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/local-flash:/name}( ${.:/params[0]/name} )
variants: []
-description: null
+description: |
+ This directive is functionally equivalent to a calling ${enable:/name}
+ immediately followed by a ${disable:/name}. On some architectures it is
+ possible to provide an optimized implementation for this sequence.
enabled-by:
not: RTEMS_SMP
-index-entries: []
+index-entries:
+- flash interrupts
interface-type: macro
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
+- role: constraint
+ uid: ../constraint/no-smp
name: rtems_interrupt_flash
-notes: null
+notes: |
+ The ${.:/params[0]/name} parameter value must be obtained by a previous
+ call to ${disable:/name} or ${flash:/name}. Using an otherwise obtained
+ value is undefined behaviour.
+
+ Historically, the interrupt flash directive was heavily used in the
+ operating system implementation. However, this is no longer the case. The
+ interrupt flash directive is provided for backward compatibility reasons.
params:
-- description: '%'
- dir: null
+- description: |
+ is the previous interrupt level.
+ dir: inout
name: _isr_cookie
return:
return: null
diff --git a/spec/rtems/intr/if/group.yml b/spec/rtems/intr/if/group.yml
index 43c7651..22a0e22 100644
--- a/spec/rtems/intr/if/group.yml
+++ b/spec/rtems/intr/if/group.yml
@@ -7,7 +7,7 @@ brief: |
ability to alter task execution which allows a task to be preempted upon exit
from an ISR.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
description: null
enabled-by: true
@@ -19,6 +19,48 @@ links:
uid: header
- role: interface-ingroup
uid: ../../if/group
+- role: placement-order
+ uid: catch
+- role: placement-order
+ uid: disable
+- role: placement-order
+ uid: enable
+- role: placement-order
+ uid: flash
+- role: placement-order
+ uid: local-disable
+- role: placement-order
+ uid: local-enable
+- role: placement-order
+ uid: is-in-progress
+- role: placement-order
+ uid: cause
+- role: placement-order
+ uid: clear
+- role: placement-order
+ uid: lock-initialize
+- role: placement-order
+ uid: lock-destroy
+- role: placement-order
+ uid: lock-acquire
+- role: placement-order
+ uid: lock-release
+- role: placement-order
+ uid: lock-acquire-isr
+- role: placement-order
+ uid: lock-release-isr
+- role: placement-order
+ uid: lock-isr-disable
+- role: placement-order
+ uid: lock-declare
+- role: placement-order
+ uid: lock-define
+- role: placement-order
+ uid: lock-initializer
+- role: placement-order
+ uid: lock-member
+- role: placement-order
+ uid: lock-reference
name: Interrupt Manager
text: |
The Classic API shall provide an interface to the Interrupt Manager.
diff --git a/spec/rtems/intr/if/header.yml b/spec/rtems/intr/if/header.yml
index ce24f47..dd23f99 100644
--- a/spec/rtems/intr/if/header.yml
+++ b/spec/rtems/intr/if/header.yml
@@ -1,7 +1,7 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: This header file defines the Interrupt Manager API.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
enabled-by: true
index-entries: []
interface-type: header-file
diff --git a/spec/rtems/intr/if/is-in-progress.yml b/spec/rtems/intr/if/is-in-progress.yml
index 3d9ded0..0ced88d 100644
--- a/spec/rtems/intr/if/is-in-progress.yml
+++ b/spec/rtems/intr/if/is-in-progress.yml
@@ -1,24 +1,36 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Checks if an ISR is in progress on the current processor.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/is-in-progress:/name}()
variants: []
-description: null
+description: |
+ This directive returns ``true``, if the current processor is currently
+ servicing an interrupt, and ``false`` otherwise. A return value of ``true``
+ indicates that the caller is an interrupt service routine, **not** a task.
+ The directives available to an interrupt service routine are restricted.
enabled-by: true
-index-entries: []
+index-entries:
+- is interrupt in progress
interface-type: macro
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_interrupt_is_in_progress
notes: null
params: []
return:
- return: null
+ return: |
+ Returns true, if the current processor is currently servicing an interrupt,
+ otherwise false.
return-values: []
type: interface
diff --git a/spec/rtems/intr/if/isr-entry.yml b/spec/rtems/intr/if/isr-entry.yml
index 5f5b1d0..fa4c706 100644
--- a/spec/rtems/intr/if/isr-entry.yml
+++ b/spec/rtems/intr/if/isr-entry.yml
@@ -3,7 +3,7 @@ brief: |
Interrupt service routines installed by ${catch:/name} shall have this
function pointer type.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: void ( *${.:/name} )( void * )
diff --git a/spec/rtems/intr/if/isr.yml b/spec/rtems/intr/if/isr.yml
index e124765..e095224 100644
--- a/spec/rtems/intr/if/isr.yml
+++ b/spec/rtems/intr/if/isr.yml
@@ -1,12 +1,15 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This type defines the return type of interrupt service routines.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/handler:/name} ${.:/name}
variants: []
-description: null
+description: |
+ This type can be used to document interrupt service routines in the source
+ code.
enabled-by: true
index-entries: []
interface-type: typedef
diff --git a/spec/rtems/intr/if/level.yml b/spec/rtems/intr/if/level.yml
index d102f3e..0f69faf 100644
--- a/spec/rtems/intr/if/level.yml
+++ b/spec/rtems/intr/if/level.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This integer type represents interrupt levels.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/level:/name} ${.:/name}
diff --git a/spec/rtems/intr/if/local-disable.yml b/spec/rtems/intr/if/local-disable.yml
index 92826cc..baee153 100644
--- a/spec/rtems/intr/if/local-disable.yml
+++ b/spec/rtems/intr/if/local-disable.yml
@@ -1,25 +1,79 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Disables the maskable interrupts on the current processor.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/local-disable:/name}( ${.:/params[0]/name} )
variants: []
-description: null
+description: |
+ This directive disables all maskable interrupts on the current processor and
+ returns the previous interrupt level in ${.:/params[0]/name}.
enabled-by: true
-index-entries: []
+index-entries:
+- disable interrupts
interface-type: macro
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_interrupt_local_disable
-notes: null
+notes: |
+ A later invocation of the ${local-enable:/name} directive should be used to
+ restore the previous interrupt level.
+
+ This directive is implemented as a macro which sets the ${.:/params[0]/name}
+ parameter.
+
+ Where the system was built with SMP support enabled, this will not ensure
+ system wide mutual exclusion. Use interrupt locks instead, see
+ ${lock-acquire:/name}. Interrupt disabled critical sections may be used to
+ access processor-specific data structures or disable thread dispatching.
+
+ .. code-block:: c
+ :linenos:
+
+ #include <rtems.h>
+
+ void local_critical_section( void )
+ {
+ rtems_interrupt_level level;
+
+ // Please note that the rtems_interrupt_local_disable() is a macro.
+ // The previous interrupt level (before the maskable interrupts are
+ // disabled) is returned here in the level macro parameter. This would
+ // be wrong:
+ //
+ // rtems_interrupt_local_disable( &level );
+ rtems_interrupt_local_disable( level );
+
+ // Here is the critical section: maskable interrupts are disabled
+
+ {
+ rtems_interrupt_level nested_level;
+
+ rtems_interrupt_local_disable( nested_level );
+
+ // Here is a nested critical section
+
+ rtems_interrupt_local_enable( nested_level );
+ }
+
+ // Maskable interrupts are still disabled
+
+ rtems_interrupt_local_enable( level );
+ }
params:
-- description: '%'
- dir: null
+- description: |
+ is a variable of type ${level:/name} which will be used to save the
+ previous interrupt level.
+ dir: out
name: _isr_cookie
return:
return: null
diff --git a/spec/rtems/intr/if/local-enable.yml b/spec/rtems/intr/if/local-enable.yml
index 2091377..da08a12 100644
--- a/spec/rtems/intr/if/local-enable.yml
+++ b/spec/rtems/intr/if/local-enable.yml
@@ -1,25 +1,44 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Restores the previous interrupt level on the current processor.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/local-enable:/name}( ${.:/params[0]/name} )
variants: []
-description: null
+description: |
+ This directive restores the interrupt level specified by
+ ${.:/params[0]/name} on the current processor.
enabled-by: true
-index-entries: []
+index-entries:
+- enable interrupts
+- restore interrupt level
interface-type: macro
links:
- role: interface-placement
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
+- role: constraint
+ uid: /constraint/interrupt-enable
name: rtems_interrupt_local_enable
-notes: null
+notes: |
+ The ${.:/params[0]/name} parameter value must be obtained by a previous call
+ to ${local-disable:/name}. Using an otherwise obtained value is undefined
+ behaviour.
+
+ This directive is unsuitable to enable particular interrupt sources, for
+ example in an interrupt controller.
params:
-- description: '%'
- dir: null
+- description: |
+ is the previous interrupt level to restore. The value must be obtained by
+ a previous call to ${local-disable:/name}.
+ dir: in
name: _isr_cookie
return:
return: null
diff --git a/spec/rtems/intr/if/lock-acquire-isr.yml b/spec/rtems/intr/if/lock-acquire-isr.yml
index 5fb41dd..fe0e03d 100644
--- a/spec/rtems/intr/if/lock-acquire-isr.yml
+++ b/spec/rtems/intr/if/lock-acquire-isr.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Acquires the ISR lock from within an ISR.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: do { (void) ${.:/params[1]/name}; } while ( 0 )
@@ -12,7 +13,10 @@ definition:
&( ${.:/params[1]/name} )->Lock_context
)
enabled-by: defined(${/build-options/if/smp:/name})
-description: null
+description: |
+ This directive acquires the ISR lock specified by ${.:/params[0]/name} using
+ the lock context provided by ${.:/params[1]/name}. The interrupt level will
+ remain unchanged.
enabled-by: true
index-entries: []
interface-type: macro
@@ -21,14 +25,36 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_interrupt_lock_acquire_isr
-notes: null
+notes: |
+ A caller-specific lock context shall be provided for each acquire/release
+ pair, for example an automatic variable.
+
+ Where the system was built with SMP support enabled, this directive acquires
+ an SMP lock. An attempt to recursively acquire the lock may result in an
+ infinite loop.
+
+ This directive is intended for device drivers and should be called from the
+ corresponding interrupt service routine.
+
+ In case the corresponding interrupt service routine can be interrupted by
+ higher priority interrupts and these interrupts enter the critical section
+ protected by this lock, then the result is unpredictable. This directive may
+ be used under specific circumstances as an optimization. In doubt, use
+ ${lock-acquire:/name} and ${lock-release:/name}.
params:
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock to acquire within an ISR.
+ dir: inout
name: _lock
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock context. This lock context shall be used to release the
+ lock by calling ${lock-release-isr:/name}.
+ dir: out
name: _lock_context
return:
return: null
diff --git a/spec/rtems/intr/if/lock-acquire.yml b/spec/rtems/intr/if/lock-acquire.yml
index c4f7185..7c05fd9 100644
--- a/spec/rtems/intr/if/lock-acquire.yml
+++ b/spec/rtems/intr/if/lock-acquire.yml
@@ -1,13 +1,17 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Acquires the ISR lock.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: |
${/score/isr/if/lock-isr-disable-acquire:/name}( ${.:/params[0]/name}, ${.:/params[1]/name} )
variants: []
-description: null
+description: |
+ This directive acquires the ISR lock specified by ${.:/params[0]/name} using
+ the lock context provided by ${.:/params[1]/name}. Maskable interrupts will
+ be disabled on the current processor.
enabled-by: true
index-entries: []
interface-type: macro
@@ -16,14 +20,48 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_interrupt_lock_acquire
-notes: null
+notes: |
+ A caller-specific lock context shall be provided for each acquire/release
+ pair, for example an automatic variable.
+
+ Where the system was built with SMP support enabled, this directive acquires
+ an SMP lock. An attempt to recursively acquire the lock may result in an
+ infinite loop with maskable interrupts disabled.
+
+ This directive establishes a non-preemptive critical section with system wide
+ mutual exclusion on the local node in all RTEMS build configurations.
+
+ .. code-block:: c
+ :linenos:
+
+ #include <rtems.h>
+
+ void critical_section( rtems_interrupt_lock *lock )
+ {
+ rtems_interrupt_lock_context lock_context;
+
+ rtems_interrupt_lock_acquire( lock, &lock_context );
+
+ // Here is the critical section. Maskable interrupts are disabled.
+ // Where the system was built with SMP support enabled, this section
+ // is protected by an SMP lock.
+
+ rtems_interrupt_lock_release( lock, &lock_context );
+ }
params:
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock to acquire.
+ dir: inout
name: _lock
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock context. This lock context shall be used to release the
+ lock by calling ${lock-release:/name}.
+ dir: out
name: _lock_context
return:
return: null
diff --git a/spec/rtems/intr/if/lock-context.yml b/spec/rtems/intr/if/lock-context.yml
index d85e235..10ddbf7 100644
--- a/spec/rtems/intr/if/lock-context.yml
+++ b/spec/rtems/intr/if/lock-context.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This structure provides an ISR lock context for acquire and release pairs.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/lock-context:/name} ${.:/name}
diff --git a/spec/rtems/intr/if/lock-declare.yml b/spec/rtems/intr/if/lock-declare.yml
index 105ec99..3f42f2e 100644
--- a/spec/rtems/intr/if/lock-declare.yml
+++ b/spec/rtems/intr/if/lock-declare.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Declares an ISR lock object.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: |
@@ -17,12 +18,16 @@ links:
- role: interface-ingroup
uid: group
name: RTEMS_INTERRUPT_LOCK_DECLARE
-notes: null
+notes: |
+ Do not add a ";" after this macro.
params:
-- description: '%'
+- description: |
+ is the storage-class specifier for the ISR lock to declare, for example ``extern``
+ or ``static``.
dir: null
- name: _qualifier
-- description: '%'
+ name: _specifier
+- description: |
+ is the ISR lock object designator.
dir: null
name: _designator
return:
diff --git a/spec/rtems/intr/if/lock-define.yml b/spec/rtems/intr/if/lock-define.yml
index b45b5ec..378a102 100644
--- a/spec/rtems/intr/if/lock-define.yml
+++ b/spec/rtems/intr/if/lock-define.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Defines an ISR lock object.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: |
@@ -17,15 +18,24 @@ links:
- role: interface-ingroup
uid: group
name: RTEMS_INTERRUPT_LOCK_DEFINE
-notes: null
+notes: |
+ Do not add a ";" after this macro.
+
+ ISR locks may also be dynamically initialized by ${lock-initialize:/name} or
+ statically by ${lock-initializer:/name}.
params:
-- description: '%'
+- description: |
+ is the storage-class specifier for the ISR lock to declare, for example ``extern``
+ or ``static``.
dir: null
- name: _qualifier
-- description: '%'
+ name: _specifier
+- description: |
+ is the ISR lock object designator.
dir: null
name: _designator
-- description: '%'
+- description: |
+ is the ISR lock name. It shall be a string. The name is only used where
+ the system was built with profiling support enabled.
dir: null
name: _name
return:
diff --git a/spec/rtems/intr/if/lock-destroy.yml b/spec/rtems/intr/if/lock-destroy.yml
index e769dc4..d69da34 100644
--- a/spec/rtems/intr/if/lock-destroy.yml
+++ b/spec/rtems/intr/if/lock-destroy.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Destroys the ISR lock.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/lock-destroy:/name}( ${.:/params[0]/name} )
@@ -15,11 +16,22 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_interrupt_lock_destroy
-notes: null
+notes: |
+ The lock must have been dynamically initialized by ${lock-initialize:/name},
+ statically defined by ${lock-define:/name}, or statically initialized by
+ ${lock-initializer:/name}.
+
+ Concurrent lock use during the destruction or concurrent destruction leads to
+ unpredictable results.
params:
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock to destroy.
+ dir: inout
name: _lock
return:
return: null
diff --git a/spec/rtems/intr/if/lock-initialize.yml b/spec/rtems/intr/if/lock-initialize.yml
index 69a3a44..d9922e7 100644
--- a/spec/rtems/intr/if/lock-initialize.yml
+++ b/spec/rtems/intr/if/lock-initialize.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Initializes the ISR lock.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: |
@@ -17,12 +18,17 @@ links:
- role: interface-ingroup
uid: group
name: rtems_interrupt_lock_initialize
-notes: null
+notes: |
+ ISR locks may also be statically defined by ${lock-define:/name} or
+ statically initialized by ${lock-initializer:/name}.
params:
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock to initialize.
+ dir: out
name: _lock
-- description: '%'
+- description: |
+ is the ISR lock name. It shall be a string. The name is only used where
+ the system was built with profiling support enabled.
dir: null
name: _name
return:
diff --git a/spec/rtems/intr/if/lock-initializer.yml b/spec/rtems/intr/if/lock-initializer.yml
index c57b172..fb10054 100644
--- a/spec/rtems/intr/if/lock-initializer.yml
+++ b/spec/rtems/intr/if/lock-initializer.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Statically initializes an ISR lock object.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/lock-initializer:/name}( ${.:/params[0]/name} )
@@ -16,9 +17,13 @@ links:
- role: interface-ingroup
uid: group
name: RTEMS_INTERRUPT_LOCK_INITIALIZER
-notes: null
+notes: |
+ ISR locks may also be dynamically initialized by ${lock-initialize:/name} or
+ statically defined by ${lock-define:/name}.
params:
-- description: '%'
+- description: |
+ is the ISR lock name. It shall be a string. The name is only used where
+ the system was built with profiling support enabled.
dir: null
name: _name
return:
diff --git a/spec/rtems/intr/if/lock-isr-disable.yml b/spec/rtems/intr/if/lock-isr-disable.yml
index 088e00f..acf184b 100644
--- a/spec/rtems/intr/if/lock-isr-disable.yml
+++ b/spec/rtems/intr/if/lock-isr-disable.yml
@@ -1,12 +1,15 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Disables maskable interrupts on the current processor.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/lock-isr-disable:/name}( ${.:/params[0]/name} )
variants: []
-description: null
+description: |
+ This directive disables maskable interrupts on the current processor and
+ stores the previous interrupt level in ${.:/params[0]/name}.
enabled-by: true
index-entries: []
interface-type: macro
@@ -15,11 +18,16 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_interrupt_lock_interrupt_disable
notes: null
params:
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock context for an acquire and release pair.
+ dir: out
name: _lock_context
return:
return: null
diff --git a/spec/rtems/intr/if/lock-member.yml b/spec/rtems/intr/if/lock-member.yml
index 5a46373..a5035ef 100644
--- a/spec/rtems/intr/if/lock-member.yml
+++ b/spec/rtems/intr/if/lock-member.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Defines an ISR lock member.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/lock-member:/name}( ${.:/params[0]/name} )
@@ -16,9 +17,11 @@ links:
- role: interface-ingroup
uid: group
name: RTEMS_INTERRUPT_LOCK_MEMBER
-notes: null
+notes: |
+ Do not add a ";" after this macro.
params:
-- description: '%'
+- description: |
+ is the ISR lock member designator.
dir: null
name: _designator
return:
diff --git a/spec/rtems/intr/if/lock-reference.yml b/spec/rtems/intr/if/lock-reference.yml
index abc443a..3aa3f7e 100644
--- a/spec/rtems/intr/if/lock-reference.yml
+++ b/spec/rtems/intr/if/lock-reference.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Defines an ISR lock object reference.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: |
@@ -17,12 +18,15 @@ links:
- role: interface-ingroup
uid: group
name: RTEMS_INTERRUPT_LOCK_REFERENCE
-notes: null
+notes: |
+ Do not add a ";" after this macro.
params:
-- description: '%'
+- description: |
+ is the ISR lock reference designator.
dir: null
name: _designator
-- description: '%'
+- description: |
+ is the target object to reference.
dir: null
name: _target
return:
diff --git a/spec/rtems/intr/if/lock-release-isr.yml b/spec/rtems/intr/if/lock-release-isr.yml
index 647178d..d82a7d5 100644
--- a/spec/rtems/intr/if/lock-release-isr.yml
+++ b/spec/rtems/intr/if/lock-release-isr.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Releases the ISR lock from within an ISR.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: do { (void) ${.:/params[1]/name}; } while ( 0 )
@@ -12,7 +13,10 @@ definition:
&( ${.:/params[1]/name} )->Lock_context
)
enabled-by: defined(${/build-options/if/smp:/name})
-description: null
+description: |
+ This directive releases the ISR lock specified by ${.:/params[0]/name} using
+ the lock context provided by ${.:/params[1]/name}. The interrupt level will
+ remain unchanged.
enabled-by: true
index-entries: []
interface-type: macro
@@ -21,14 +25,26 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
name: rtems_interrupt_lock_release_isr
-notes: null
+notes: |
+ The lock context shall be the one used to acquire the lock, otherwise the
+ result is unpredictable.
+
+ Where the system was built with SMP support enabled, this directive releases
+ an SMP lock.
params:
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock to release within an ISR.
+ dir: inout
name: _lock
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock context. This lock context shall have been used to acquire
+ the lock by calling ${lock-acquire-isr:/name}.
+ dir: inout
name: _lock_context
return:
return: null
diff --git a/spec/rtems/intr/if/lock-release.yml b/spec/rtems/intr/if/lock-release.yml
index 39e5dfa..f407413 100644
--- a/spec/rtems/intr/if/lock-release.yml
+++ b/spec/rtems/intr/if/lock-release.yml
@@ -1,13 +1,17 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ Releases the ISR lock.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: |
${/score/isr/if/lock-release-isr-enable:/name}( ${.:/params[0]/name}, ${.:/params[1]/name} )
variants: []
-description: null
+description: |
+ This directive releases the ISR lock specified by ${.:/params[0]/name} using
+ the lock context provided by ${.:/params[1]/name}. The previous interrupt
+ level will be restored on the current processor.
enabled-by: true
index-entries: []
interface-type: macro
@@ -16,14 +20,28 @@ links:
uid: header
- role: interface-ingroup
uid: group
+- role: constraint
+ uid: /constraint/directive-ctx-any
+- role: constraint
+ uid: /constraint/directive-no-preempt
+- role: constraint
+ uid: /constraint/interrupt-enable
name: rtems_interrupt_lock_release
-notes: null
+notes: |
+ The lock context shall be the one used to acquire the lock, otherwise the
+ result is unpredictable.
+
+ Where the system was built with SMP support enabled, this directive releases
+ an SMP lock.
params:
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock to release.
+ dir: inout
name: _lock
-- description: '%'
- dir: null
+- description: |
+ is the ISR lock context. This lock context shall have been used to acquire
+ the lock by calling ${lock-acquire:/name}.
+ dir: inout
name: _lock_context
return:
return: null
diff --git a/spec/rtems/intr/if/lock.yml b/spec/rtems/intr/if/lock.yml
index 04148dd..3d30cca 100644
--- a/spec/rtems/intr/if/lock.yml
+++ b/spec/rtems/intr/if/lock.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This structure represents an ISR lock.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/lock-control:/name} ${.:/name}
diff --git a/spec/rtems/intr/if/vector-number.yml b/spec/rtems/intr/if/vector-number.yml
index 29808e0..5b7f5b2 100644
--- a/spec/rtems/intr/if/vector-number.yml
+++ b/spec/rtems/intr/if/vector-number.yml
@@ -1,7 +1,8 @@
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
-brief: '%'
+brief: |
+ This integer type represents interrupt vector numbers.
copyrights:
-- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+- Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
default: ${/score/isr/if/vector-number:/name} ${.:/name}
More information about the vc
mailing list