From f776fe6591c58054fa4f22794e5665b271ff3706 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 14 Jul 2017 07:52:21 +0200 Subject: c-user: Fix interrupt lock documentation Update #3075. --- c-user/interrupt_manager.rst | 52 +++++++++++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 17 deletions(-) (limited to 'c-user') diff --git a/c-user/interrupt_manager.rst b/c-user/interrupt_manager.rst index f7c1ce8..868dbc6 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: acquires an 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 an 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. In SMP configurations, this directive acquires an 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. 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 -- cgit v1.2.3