AVR-LibC  2.2.0
Standard C library for AVR-GCC
 

AVR-LibC Documentation

Logo

AVR-LibC Development Pages

Main Page

User Manual

Library Reference

FAQ

Example Projects

File List

Loading...
Searching...
No Matches
atomic.h
Go to the documentation of this file.
1/* Copyright (c) 2007 Dean Camera
2 All rights reserved.
3
4 Redistribution and use in source and binary forms, with or without
5 modification, are permitted provided that the following conditions are met:
6
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9
10 * Redistributions in binary form must reproduce the above copyright
11 notice, this list of conditions and the following disclaimer in
12 the documentation and/or other materials provided with the
13 distribution.
14
15 * Neither the name of the copyright holders nor the names of
16 contributors may be used to endorse or promote products derived
17 from this software without specific prior written permission.
18
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
23 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 POSSIBILITY OF SUCH DAMAGE.
30*/
31
32/* $Id$ */
33
34#ifndef _UTIL_ATOMIC_H_
35#define _UTIL_ATOMIC_H_ 1
36
37#include <avr/io.h>
38#include <avr/interrupt.h>
39
40#if !defined(__DOXYGEN__)
41/* Internal helper functions. */
42static __inline__ uint8_t __iSeiRetVal(void)
43{
44 sei();
45 return 1;
46}
47
48static __inline__ uint8_t __iCliRetVal(void)
49{
50 cli();
51 return 1;
52}
53
54static __inline__ void __iSeiParam(const uint8_t *__s)
55{
56 sei();
57 __asm__ volatile ("" ::: "memory");
58 (void)__s;
59}
60
61static __inline__ void __iCliParam(const uint8_t *__s)
62{
63 cli();
64 __asm__ volatile ("" ::: "memory");
65 (void)__s;
66}
67
68static __inline__ void __iRestore(const uint8_t *__s)
69{
70 SREG = *__s;
71 __asm__ volatile ("" ::: "memory");
72}
73#endif /* !__DOXYGEN__ */
74
75/** \file */
76/** \defgroup util_atomic <util/atomic.h> Atomically and Non-Atomically Executed Code Blocks
77
78 \code
79 #include <util/atomic.h>
80 \endcode
81
82 \note The macros in this header file require the ISO/IEC 9899:1999
83 ("ISO C99") feature of for loop variables that are declared inside
84 the for loop itself. For that reason, this header file can only
85 be used if the standard level of the compiler (option --std=) is
86 set to either \c c99, \c gnu99 or higher.
87
88 The macros in this header file deal with code blocks that are
89 guaranteed to be executed Atomically or Non-Atomically. The term
90 "Atomic" in this context refers to the inability of the respective
91 code to be interrupted.
92
93 These macros operate via automatic manipulation of the Global
94 Interrupt Status (I) bit of the SREG register. Exit paths from
95 both block types are all managed automatically without the need
96 for special considerations, i.e. the interrupt status will be
97 restored to the same value it had when entering the respective
98 block (unless ATOMIC_FORCEON or NONATOMIC_FORCEOFF are used).
99 \warning The features in this header are implemented by means of
100 a for loop. This means that commands like \c break and \c continue
101 that are located in an atomic block refer to the atomic for loop,
102 not to a loop construct that hosts the atomic block.
103
104 A typical example that requires atomic access is a 16 (or more)
105 bit variable that is shared between the main execution path and an
106 ISR. While declaring such a variable as volatile ensures that the
107 compiler will not optimize accesses to it away, it does not
108 guarantee atomic access to it. Assuming the following example:
109
110 \code
111#include <stdint.h>
112#include <avr/interrupt.h>
113#include <avr/io.h>
114
115volatile uint16_t ctr;
116
117ISR(TIMER1_OVF_vect)
118{
119 ctr--;
120}
121
122...
123int
124main(void)
125{
126 ...
127 ctr = 0x200;
128 start_timer();
129 while (ctr != 0)
130 // wait
131 ;
132 ...
133}
134 \endcode
135
136 There is a chance where the main context will exit its wait loop
137 when the variable \c ctr just reached the value 0xFF. This happens
138 because the compiler cannot natively access a 16-bit variable
139 atomically in an 8-bit CPU. So the variable is for example at
140 0x100, the compiler then tests the low byte for 0, which succeeds.
141 It then proceeds to test the high byte, but that moment the ISR
142 triggers, and the main context is interrupted. The ISR will
143 decrement the variable from 0x100 to 0xFF, and the main context
144 proceeds. It now tests the high byte of the variable which is
145 (now) also 0, so it concludes the variable has reached 0, and
146 terminates the loop.
147
148 Using the macros from this header file, the above code can be
149 rewritten like:
150
151 \code
152#include <stdint.h>
153#include <avr/interrupt.h>
154#include <avr/io.h>
155#include <util/atomic.h>
156
157volatile uint16_t ctr;
158
159ISR(TIMER1_OVF_vect)
160{
161 ctr--;
162}
163
164...
165int
166main(void)
167{
168 ...
169 ctr = 0x200;
170 start_timer();
171 sei();
172 uint16_t ctr_copy;
173 do
174 {
175 ATOMIC_BLOCK(ATOMIC_FORCEON)
176 {
177 ctr_copy = ctr;
178 }
179 }
180 while (ctr_copy != 0);
181 ...
182}
183 \endcode
184
185 This will install the appropriate interrupt protection before
186 accessing variable \c ctr, so it is guaranteed to be consistently
187 tested. If the global interrupt state were uncertain before
188 entering the #ATOMIC_BLOCK, it should be executed with the
189 parameter #ATOMIC_RESTORESTATE rather than #ATOMIC_FORCEON.
190
191 See \ref optim_code_reorder for things to be taken into account
192 with respect to compiler optimizations.
193*/
194
195/** \def ATOMIC_BLOCK(type)
196 \ingroup util_atomic
197
198 Creates a block of code that is guaranteed to be executed
199 atomically. Upon entering the block the Global Interrupt Status
200 flag in SREG is disabled, and re-enabled upon exiting the block
201 from any exit path.
202
203 Two possible macro parameters are permitted, #ATOMIC_RESTORESTATE
204 and #ATOMIC_FORCEON.
205*/
206#if defined(__DOXYGEN__)
207#define ATOMIC_BLOCK(type)
208#else
209#define ATOMIC_BLOCK(type) for ( type, __ToDo = __iCliRetVal(); \
210 __ToDo ; __ToDo = 0 )
211#endif /* __DOXYGEN__ */
212
213/** \def NONATOMIC_BLOCK(type)
214 \ingroup util_atomic
215
216 Creates a block of code that is executed non-atomically. Upon
217 entering the block the Global Interrupt Status flag in SREG is
218 enabled, and disabled upon exiting the block from any exit
219 path. This is useful when nested inside ATOMIC_BLOCK sections,
220 allowing for non-atomic execution of small blocks of code while
221 maintaining the atomic access of the other sections of the parent
222 ATOMIC_BLOCK.
223
224 Two possible macro parameters are permitted,
225 #NONATOMIC_RESTORESTATE and #NONATOMIC_FORCEOFF.
226*/
227#if defined(__DOXYGEN__)
228#define NONATOMIC_BLOCK(type)
229#else
230#define NONATOMIC_BLOCK(type) for ( type, __ToDo = __iSeiRetVal(); \
231 __ToDo ; __ToDo = 0 )
232#endif /* __DOXYGEN__ */
233
234/** \def ATOMIC_RESTORESTATE
235 \ingroup util_atomic
236
237 This is a possible parameter for #ATOMIC_BLOCK. When used, it will
238 cause the ATOMIC_BLOCK to restore the previous state of the SREG
239 register, saved before the Global Interrupt Status flag bit was
240 disabled. The net effect of this is to make the ATOMIC_BLOCK's
241 contents guaranteed atomic, without changing the state of the
242 Global Interrupt Status flag when execution of the block
243 completes.
244*/
245#if defined(__DOXYGEN__)
246#define ATOMIC_RESTORESTATE
247#else
248#define ATOMIC_RESTORESTATE uint8_t sreg_save \
249 __attribute__((__cleanup__(__iRestore))) = SREG
250#endif /* __DOXYGEN__ */
251
252/** \def ATOMIC_FORCEON
253 \ingroup util_atomic
254
255 This is a possible parameter for #ATOMIC_BLOCK. When used, it will
256 cause the ATOMIC_BLOCK to force the state of the SREG register on
257 exit, enabling the Global Interrupt Status flag bit. This saves a
258 small amount of flash space, a register, and one or more processor
259 cycles, since the previous value of the SREG register does not need
260 to be saved at the start of the block.
261
262 Care should be taken that ATOMIC_FORCEON is only used when it is
263 known that interrupts are enabled before the block's execution or
264 when the side effects of enabling global interrupts at the block's
265 completion are known and understood.
266*/
267#if defined(__DOXYGEN__)
268#define ATOMIC_FORCEON
269#else
270#define ATOMIC_FORCEON uint8_t sreg_save \
271 __attribute__((__cleanup__(__iSeiParam))) = 0
272#endif /* __DOXYGEN__ */
273
274/** \def NONATOMIC_RESTORESTATE
275 \ingroup util_atomic
276
277 This is a possible parameter for #NONATOMIC_BLOCK. When used, it
278 will cause the NONATOMIC_BLOCK to restore the previous state of
279 the SREG register, saved before the Global Interrupt Status flag
280 bit was enabled. The net effect of this is to make the
281 NONATOMIC_BLOCK's contents guaranteed non-atomic, without changing
282 the state of the Global Interrupt Status flag when execution of
283 the block completes.
284*/
285#if defined(__DOXYGEN__)
286#define NONATOMIC_RESTORESTATE
287#else
288#define NONATOMIC_RESTORESTATE uint8_t sreg_save \
289 __attribute__((__cleanup__(__iRestore))) = SREG
290#endif /* __DOXYGEN__ */
291
292/** \def NONATOMIC_FORCEOFF
293 \ingroup util_atomic
294
295 This is a possible parameter for #NONATOMIC_BLOCK. When used, it
296 will cause the NONATOMIC_BLOCK to force the state of the SREG
297 register on exit, disabling the Global Interrupt Status flag
298 bit. This saves a small amout of flash space, a register, and one
299 or more processor cycles, since the previous value of the SREG
300 register does not need to be saved at the start of the block.
301
302 Care should be taken that NONATOMIC_FORCEOFF is only used when it
303 is known that interrupts are disabled before the block's execution
304 or when the side effects of disabling global interrupts at the
305 block's completion are known and understood.
306*/
307#if defined(__DOXYGEN__)
308#define NONATOMIC_FORCEOFF
309#else
310#define NONATOMIC_FORCEOFF uint8_t sreg_save \
311 __attribute__((__cleanup__(__iCliParam))) = 0
312#endif /* __DOXYGEN__ */
313
314#endif
#define cli()
Definition: interrupt.h:90
#define sei()
Definition: interrupt.h:76
unsigned char uint8_t
Definition: stdint.h:83