Defines | |
#define | ATOMIC_BLOCK(type) |
#define | NONATOMIC_BLOCK(type) |
#define | ATOMIC_RESTORESTATE |
#define | ATOMIC_FORCEON |
#define | NONATOMIC_RESTORESTATE |
#define | NONATOMIC_FORCEOFF |
#include <util/atomic.h>
c99
or gnu99
.These macros operate via automatic manipulation of the Global Interrupt Status (I) bit of the SREG register. Exit paths from both block types are all managed automatically without the need for special considerations, i. e. the interrupt status will be restored to the same value it has been when entering the respective block.
A typical example that requires atomic access is a 16 (or more) bit variable that is shared between the main execution path and an ISR. While declaring such a variable as volatile ensures that the compiler will not optimize accesses to it away, it does not guarantee atomic access to it. Assuming the following example:
#include <inttypes.h> #include <avr/interrupt.h> #include <avr/io.h> volatile uint16_t ctr; ISR(TIMER1_OVF_vect) { ctr--; } ... int main(void) { ... ctr = 0x200; start_timer(); while (ctr != 0) // wait ; ... }
There is a chance where the main context will exit its wait loop when the variable ctr
just reached the value 0xFF. This happens because the compiler cannot natively access a 16-bit variable atomically in an 8-bit CPU. So the variable is for example at 0x100, the compiler then tests the low byte for 0, which succeeds. It then proceeds to test the high byte, but that moment the ISR triggers, and the main context is interrupted. The ISR will decrement the variable from 0x100 to 0xFF, and the main context proceeds. It now tests the high byte of the variable which is (now) also 0, so it concludes the variable has reached 0, and terminates the loop.
Using the macros from this header file, the above code can be rewritten like:
#include <inttypes.h> #include <avr/interrupt.h> #include <avr/io.h> #include <util/atomic.h> volatile uint16_t ctr; ISR(TIMER1_OVF_vect) { ctr--; } ... int main(void) { ... ctr = 0x200; start_timer(); sei(); uint16_t ctr_copy; do { ATOMIC_BLOCK(ATOMIC_FORCEON) { ctr_copy = ctr; } } while (ctr_copy != 0); ... }
This will install the appropriate interrupt protection before accessing variable ctr
, so it is guaranteed to be consistently tested. If the global interrupt state were uncertain before entering the ATOMIC_BLOCK, it should be executed with the parameter ATOMIC_RESTORESTATE rather than ATOMIC_FORCEON.
#define ATOMIC_BLOCK | ( | type | ) |
Value:
for ( type, __ToDo = __iCliRetVal(); \
__ToDo ; __ToDo = 0 )
Two possible macro parameters are permitted, ATOMIC_RESTORESTATE and ATOMIC_FORCEON.
#define ATOMIC_FORCEON |
Value:
uint8_t sreg_save \ __attribute__((__cleanup__(__iSeiParam))) = 0
Care should be taken that ATOMIC_FORCEON is only used when it is known that interrupts are enabled before the block's execution or when the side effects of enabling global interrupts at the block's completion are known and understood.
#define ATOMIC_RESTORESTATE |
Value:
uint8_t sreg_save \ __attribute__((__cleanup__(__iRestore))) = SREG
#define NONATOMIC_BLOCK | ( | type | ) |
Value:
for ( type, __ToDo = __iSeiRetVal(); \
__ToDo ; __ToDo = 0 )
Two possible macro parameters are permitted, NONATOMIC_RESTORESTATE and NONATOMIC_FORCEOFF.
#define NONATOMIC_FORCEOFF |
Value:
uint8_t sreg_save \ __attribute__((__cleanup__(__iCliParam))) = 0
Care should be taken that NONATOMIC_FORCEOFF is only used when it is known that interrupts are disabled before the block's execution or when the side effects of disabling global interrupts at the block's completion are known and understood.
#define NONATOMIC_RESTORESTATE |
Value:
uint8_t sreg_save \ __attribute__((__cleanup__(__iRestore))) = SREG