spec: Update /rtems/intr/* documentation

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 00000000..364ddfb5
--- /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 00000000..30878e5f
--- /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 00000000..67663129
--- /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 00000000..338c1b99
--- /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 00000000..401d6875
--- /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 8ab54be6..14dd7feb 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 f22fecac..0ab332e8 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 3004ab2d..f92bbede 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 72856248..08208e7d 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 49a6a024..97d7dbf4 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 2832326a..05e8ef76 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 43c7651a..22a0e229 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 ce24f473..dd23f997 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 3d9ded00..0ced88d1 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 5f5b1d0b..fa4c706a 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 e1247657..e0952248 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 d102f3ef..0f69faf6 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 92826ccf..baee1537 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 2091377b..da08a124 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 5fb41dd9..fe0e03d4 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 c4f7185a..7c05fd94 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 d85e2354..10ddbf7d 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 105ec99e..3f42f2ea 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 b45b5ecc..378a1026 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 e769dc4d..d69da341 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 69a3a443..d9922e7f 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 c57b1729..fb100549 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 088e00f8..acf184b3 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 5a463730..a5035ef5 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 abc443af..3aa3f7e9 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 647178d8..d82a7d52 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 39e5dfa0..f407413a 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 04148dd6..3d30cca3 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 29808e01..5b7f5b29 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}