source: rtems/cpukit/score/include/rtems/score/isrlock.h @ 07e7a7f8

4.11
Last change on this file since 07e7a7f8 was 07e7a7f8, checked in by Sebastian Huber <sebastian.huber@…>, on May 7, 2014 at 6:13:44 AM

score: Documentation

  • Property mode set to 100644
File size: 5.2 KB
Line 
1/**
2 * @file
3 *
4 * @ingroup ScoreISRLocks
5 *
6 * @brief ISR Locks
7 */
8
9/*
10 * Copyright (c) 2013 embedded brains GmbH.  All rights reserved.
11 *
12 *  embedded brains GmbH
13 *  Dornierstr. 4
14 *  82178 Puchheim
15 *  Germany
16 *  <rtems@embedded-brains.de>
17 *
18 * The license and distribution terms for this file may be
19 * found in the file LICENSE in this distribution or at
20 * http://www.rtems.org/license/LICENSE.
21 */
22
23#ifndef _RTEMS_SCORE_ISR_LOCK_H
24#define _RTEMS_SCORE_ISR_LOCK_H
25
26#include <rtems/score/isrlevel.h>
27#include <rtems/score/smplock.h>
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33/**
34 * @defgroup ScoreISRLocks ISR Locks
35 *
36 * @ingroup ScoreISR
37 *
38 * @brief Low-level lock to protect critical sections accessed by threads and
39 * interrupt service routines.
40 *
41 * On single processor configurations the ISR locks degrade to simple ISR
42 * disable/enable sequences.  No additional storage or objects are required.
43 *
44 * This synchronization primitive is supported on SMP configurations.  Here SMP
45 * locks are used.
46 *
47 * @{
48 */
49
50/**
51 * @brief ISR lock control.
52 */
53typedef struct {
54#if defined( RTEMS_SMP )
55  SMP_lock_Control lock;
56#endif
57} ISR_lock_Control;
58
59/**
60 * @brief Local ISR lock context for acquire and release pairs.
61 */
62typedef struct {
63#if defined( RTEMS_SMP )
64  SMP_lock_Context lock_context;
65#else
66  ISR_Level isr_level;
67#endif
68} ISR_lock_Context;
69
70/**
71 * @brief Initializer for static initialization of ISR locks.
72 *
73 * @param _name The name for the interrupt lock.  It must be a string.  The
74 * name is only used if profiling is enabled.
75 */
76#if defined( RTEMS_SMP )
77  #define ISR_LOCK_INITIALIZER( name ) \
78    { SMP_LOCK_INITIALIZER( name ) }
79#else
80  #define ISR_LOCK_INITIALIZER( name ) \
81    { }
82#endif
83
84/**
85 * @brief Initializes an ISR lock.
86 *
87 * Concurrent initialization leads to unpredictable results.
88 *
89 * @param[in,out] lock The ISR lock control.
90 * @param[in] _name The name for the ISR lock.  This name must be a
91 * string persistent throughout the life time of this lock.  The name is only
92 * used if profiling is enabled.
93 */
94static inline void _ISR_lock_Initialize(
95  ISR_lock_Control *lock,
96  const char *name
97)
98{
99#if defined( RTEMS_SMP )
100  _SMP_lock_Initialize( &lock->lock, name );
101#else
102  (void) lock;
103  (void) name;
104#endif
105}
106
107/**
108 * @brief Destroys an ISR lock.
109 *
110 * Concurrent destruction leads to unpredictable results.
111 *
112 * @param[in,out] lock The ISR lock control.
113 */
114static inline void _ISR_lock_Destroy( ISR_lock_Control *lock )
115{
116#if defined( RTEMS_SMP )
117  _SMP_lock_Destroy( &lock->lock );
118#else
119  (void) lock;
120#endif
121}
122
123/**
124 * @brief Acquires an ISR lock.
125 *
126 * Interrupts will be disabled.  On SMP configurations this function acquires
127 * an SMP lock.
128 *
129 * This function can be used in thread and interrupt context.
130 *
131 * @param[in,out] lock The ISR lock control.
132 * @param[in,out] context The local ISR lock context for an acquire and release
133 * pair.
134 *
135 * @see _ISR_lock_Release_and_ISR_enable().
136 */
137static inline void _ISR_lock_ISR_disable_and_acquire(
138  ISR_lock_Control *lock,
139  ISR_lock_Context *context
140)
141{
142#if defined( RTEMS_SMP )
143  _SMP_lock_ISR_disable_and_acquire( &lock->lock, &context->lock_context );
144#else
145  (void) lock;
146  _ISR_Disable( context->isr_level );
147#endif
148}
149
150/**
151 * @brief Releases an ISR lock.
152 *
153 * The interrupt status will be restored.  On SMP configurations this function
154 * releases an SMP lock.
155 *
156 * This function can be used in thread and interrupt context.
157 *
158 * @param[in,out] lock The ISR lock control.
159 * @param[in,out] context The local ISR lock context for an acquire and release
160 * pair.
161 *
162 * @see _ISR_lock_ISR_disable_and_acquire().
163 */
164static inline void _ISR_lock_Release_and_ISR_enable(
165  ISR_lock_Control *lock,
166  ISR_lock_Context *context
167)
168{
169#if defined( RTEMS_SMP )
170  _SMP_lock_Release_and_ISR_enable( &lock->lock, &context->lock_context );
171#else
172  (void) lock;
173  _ISR_Enable( context->isr_level );
174#endif
175}
176
177/**
178 * @brief Acquires an ISR lock inside an ISR disabled section.
179 *
180 * The interrupt status will remain unchanged.  On SMP configurations this
181 * function acquires an SMP lock.
182 *
183 * In case the executing context can be interrupted by higher priority
184 * interrupts and these interrupts enter the critical section protected by this
185 * lock, then the result is unpredictable.
186 *
187 * @param[in,out] lock The ISR lock control.
188 * @param[in,out] context The local ISR lock context for an acquire and release
189 * pair.
190 *
191 * @see _ISR_lock_Release().
192 */
193static inline void _ISR_lock_Acquire(
194  ISR_lock_Control *lock,
195  ISR_lock_Context *context
196)
197{
198#if defined( RTEMS_SMP )
199  _SMP_lock_Acquire( &lock->lock, &context->lock_context );
200#else
201  (void) lock;
202  (void) context;
203#endif
204}
205
206/**
207 * @brief Releases an ISR lock inside an ISR disabled section.
208 *
209 * The interrupt status will remain unchanged.  On SMP configurations this
210 * function releases an SMP lock.
211 *
212 * @param[in,out] lock The ISR lock control.
213 * @param[in,out] context The local ISR lock context for an acquire and release
214 * pair.
215 *
216 * @see _ISR_lock_Acquire().
217 */
218static inline void _ISR_lock_Release(
219  ISR_lock_Control *lock,
220  ISR_lock_Context *context
221)
222{
223#if defined( RTEMS_SMP )
224  _SMP_lock_Release( &lock->lock, &context->lock_context );
225#else
226  (void) lock;
227  (void) context;
228#endif
229}
230
231/** @} */
232
233#ifdef __cplusplus
234}
235#endif
236
237#endif /* _RTEMS_SCORE_ISR_LOCK_H */
Note: See TracBrowser for help on using the repository browser.