[rtems-docs commit] c-user: Fix interrupt lock documentation

[Sebastian Huber]

Module:    rtems-docs
Branch:    4.11
Commit:    eecec5f9d8cbc78c42f2065a39cad2c2d58a5836
Changeset: http://git.rtems.org/rtems-docs/commit/?id=eecec5f9d8cbc78c42f2065a39cad2c2d58a5836

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri Jul 14 07:52:21 2017 +0200

c-user: Fix interrupt lock documentation

Close #3075.

---

 c-user/interrupt_manager.rst | 56 +++++++++++++++++++++++++++++---------------
 1 file changed, 37 insertions(+), 19 deletions(-)

diff --git a/c-user/interrupt_manager.rst b/c-user/interrupt_manager.rst
index 529e896..c553649 100644
--- a/c-user/interrupt_manager.rst
+++ b/c-user/interrupt_manager.rst
@@ -494,14 +494,16 @@ CALLING SEQUENCE:
     .. code-block:: c
 
         void rtems_interrupt_lock_initialize(
-            rtems_interrupt_lock *lock
+            rtems_interrupt_lock *lock,
+            const char           *name
         );
 
 DIRECTIVE STATUS CODES:
     NONE
 
 DESCRIPTION:
-    Initializes an interrupt lock.
+    Initializes an interrupt lock.  The name must be persistent throughout the
+    lifetime of the lock.
 
 NOTES:
     Concurrent initialization leads to unpredictable results.
@@ -520,8 +522,8 @@ CALLING SEQUENCE:
     .. code-block:: c
 
         void rtems_interrupt_lock_acquire(
-            rtems_interrupt_lock *lock,
-            rtems_interrupt_level level
+            rtems_interrupt_lock         *lock,
+            rtems_interrupt_lock_context *lock_context
         );
 
 DIRECTIVE STATUS CODES:
@@ -532,6 +534,12 @@ DESCRIPTION:
     a SMP lock.
 
 NOTES:
+    A separate lock context must be provided for each acquire/release pair, for
+    example an automatic variable.
+
+    An attempt to recursively acquire the lock may result in an infinite loop
+    with interrupts disabled.
+
     This directive will not cause the calling thread to be preempted.  This
     directive can be used in thread and interrupt context.
 
@@ -549,8 +557,8 @@ CALLING SEQUENCE:
     .. code-block:: c
 
         void rtems_interrupt_lock_release(
-            rtems_interrupt_lock *lock,
-            rtems_interrupt_level level
+            rtems_interrupt_lock         *lock,
+            rtems_interrupt_lock_context *lock_context
         );
 
 DIRECTIVE STATUS CODES:
@@ -561,6 +569,9 @@ DESCRIPTION:
     directive releases a SMP lock.
 
 NOTES:
+    The lock context must be the one used to acquire the lock, otherwise the
+    result is unpredictable.
+
     This directive will not cause the calling thread to be preempted.  This
     directive can be used in thread and interrupt context.
 
@@ -578,8 +589,8 @@ CALLING SEQUENCE:
     .. code-block:: c
 
         void rtems_interrupt_lock_acquire_isr(
-            rtems_interrupt_lock *lock,
-            rtems_interrupt_level level
+            rtems_interrupt_lock         *lock,
+            rtems_interrupt_lock_context *lock_context
         );
 
 DIRECTIVE STATUS CODES:
@@ -589,14 +600,19 @@ DESCRIPTION:
     The interrupt status will remain unchanged.  On SMP configurations this
     directive acquires a SMP lock.
 
+NOTES:
+    A separate lock context must be provided for each acquire/release pair, for
+    example an automatic variable.
+
+    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.
 
-NOTES:
-    This directive should be called from the corresponding interrupt service
-    routine.
-
 .. raw:: latex
 
    \clearpage
@@ -611,21 +627,23 @@ CALLING SEQUENCE:
     .. code-block:: c
 
         void rtems_interrupt_lock_release_isr(
-            rtems_interrupt_lock *lock,
-            rtems_interrupt_level level
+            rtems_interrupt_lock         *lock,
+            rtems_interrupt_lock_context *lock_context
         );
 
 DIRECTIVE STATUS CODES:
     NONE
 
 DESCRIPTION:
-
-    The interrupt status will remain unchanged.  On SMP configurations this
-    directive releases a SMP lock.
+    The interrupt status will remain unchanged.  In SMP configurations, this
+    directive releases an SMP lock.
 
 NOTES:
-    This directive should be called from the corresponding interrupt service
-    routine.
+    The lock context must be the one used to acquire the lock, otherwise the
+    result is unpredictable.
+
+    This directive is intended for device drivers and should be called from the
+    corresponding interrupt service routine.
 
 .. raw:: latex