From c7bc6d44cbd563c72afb7e9355c7350c16acb27b Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.huber@embedded-brains.de>
Date: Mon, 10 Jun 2013 11:14:35 +0200
Subject: rtems: Add interrupt locks

Interrupt locks are low-level lock to protect critical sections accessed
by threads and interrupt service routines.
---
 doc/user/intr.t | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 170 insertions(+)

(limited to 'doc')

diff --git a/doc/user/intr.t b/doc/user/intr.t
index dd5c9c80d5..b6a58dcb1f 100644
--- a/doc/user/intr.t
+++ b/doc/user/intr.t
@@ -21,6 +21,11 @@ directive:
 @item @code{@value{DIRPREFIX}interrupt_disable} - Disable Interrupts
 @item @code{@value{DIRPREFIX}interrupt_enable} - Enable Interrupts
 @item @code{@value{DIRPREFIX}interrupt_flash} - Flash Interrupt
+@item @code{@value{DIRPREFIX}interrupt_lock_initialize} - Initialize an ISR Lock
+@item @code{@value{DIRPREFIX}interrupt_lock_acquire} - Acquire an ISR Lock
+@item @code{@value{DIRPREFIX}interrupt_lock_release} - Release an ISR Lock
+@item @code{@value{DIRPREFIX}interrupt_lock_acquire_isr} - Acquire an ISR Lock from ISR
+@item @code{@value{DIRPREFIX}interrupt_lock_release_isr} - Release an ISR Lock from ISR
 @item @code{@value{DIRPREFIX}interrupt_is_in_progress} - Is an ISR in Progress
 @end itemize
 
@@ -194,6 +199,10 @@ implementation error to use RTEMS_SELF from an ISR.
 @item rtems_interrupt_enable
 @item rtems_interrupt_disable
 @item rtems_interrupt_flash
+@item rtems_interrupt_lock_acquire
+@item rtems_interrupt_lock_release
+@item rtems_interrupt_lock_acquire_isr
+@item rtems_interrupt_lock_release_isr
 @item rtems_interrupt_is_in_progress
 @item rtems_interrupt_catch
 @end itemize
@@ -453,6 +462,167 @@ and will be redisabled when this directive returns to the caller.
 
 This directive will not cause the calling task to be preempted.
 
+@c
+@c
+@c
+@page
+@subsection INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C 
+@findex rtems_interrupt_lock_initialize
+@example
+void rtems_interrupt_lock_initialize(
+  rtems_interrupt_lock *lock
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+Initializes an interrupt lock.
+
+@subheading NOTES:
+
+Concurrent initialization leads to unpredictable results.
+
+@c
+@c
+@c
+@page
+@subsection INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C 
+@findex rtems_interrupt_lock_acquire
+@example
+void rtems_interrupt_lock_acquire(
+  rtems_interrupt_lock *lock,
+  rtems_interrupt_level level
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+Interrupts will be disabled.  On SMP configurations this directive acquires a
+SMP lock.
+
+@subheading NOTES:
+
+This directive will not cause the calling thread to be preempted.  This
+directive can be used in thread and interrupt context.
+
+@c
+@c
+@c
+@page
+@subsection INTERRUPT_LOCK_RELEASE - Release an ISR Lock
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C 
+@findex rtems_interrupt_lock_release
+@example
+void rtems_interrupt_lock_release(
+  rtems_interrupt_lock *lock,
+  rtems_interrupt_level level
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+The interrupt status will be restored.  On SMP configurations this directive
+releases a SMP lock.
+
+@subheading NOTES:
+
+This directive will not cause the calling thread to be preempted.  This
+directive can be used in thread and interrupt context.
+
+@c
+@c
+@c
+@page
+@subsection INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C 
+@findex rtems_interrupt_lock_acquire_isr
+@example
+void rtems_interrupt_lock_acquire_isr(
+  rtems_interrupt_lock *lock,
+  rtems_interrupt_level level
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+The interrupt status will remain unchanged.  On SMP configurations this
+directive acquires a SMP lock.
+
+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.
+
+@subheading NOTES:
+
+This directive should be called from the corresponding interrupt service
+routine.
+
+@c
+@c
+@c
+@page
+@subsection INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C 
+@findex rtems_interrupt_lock_release_isr
+@example
+void rtems_interrupt_lock_release_isr(
+  rtems_interrupt_lock *lock,
+  rtems_interrupt_level level
+);
+@end example
+@end ifset
+
+@subheading DIRECTIVE STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+The interrupt status will remain unchanged.  On SMP configurations this
+directive releases a SMP lock.
+
+@subheading NOTES:
+
+This directive should be called from the corresponding interrupt service
+routine.
+
 @c
 @c
 @c
-- 
cgit v1.2.3