1 files changed, 46 insertions, 8 deletions
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