util_atomic(3avr)

💖 util_atomic — the manual, but make it make sense 💖

okay bestie, gather round, because this is util_atomic from the AVR-LibC manual (util_atomic(3avr), yes the whole manual page name is right there, iconic) and it's literally about making blocks of code run Atomically or Non-Atomically. like, util_atomic — <util/atomic.h> — Atomically and Non-Atomically Executed Code Blocks. periodt. 🫶

---

✨ NAME ✨

util_atomic — <util/atomic.h>, the header for Atomically and Non-Atomically Executed Code Blocks. 💅

---

🌸 SYNOPSIS 🌸

🎀 Macros

#define ATOMIC_BLOCK(type)
#define NONATOMIC_BLOCK(type)
#define ATOMIC_RESTORESTATE
#define ATOMIC_FORCEON
#define NONATOMIC_RESTORESTATE
#define NONATOMIC_FORCEOFF

🦋 Detailed Description

#include <util/atomic.h>

Note 📌 — bestie, the macros in this header file require the ISO/IEC 9899:1999 ("ISO C99") feature where for loop variables are declared inside the for loop itself. so like, this header file can only be used if the standard level of the compiler (the --std= option) is set to c99, gnu99, or higher. no cap. 🔥

These macros deal with code blocks that are guaranteed to be executed Atomically or Non-Atomically. and when we say "Atomic" in this context, we mean the inability of the respective code to be interrupted. it's giving untouchable, main character energy 👑

The way these macros work is by automatic manipulation of the Global Interrupt Status (I) bit of the SREG register. and the exit paths from both block types are all managed automatically, no special considerations needed — i.e. the interrupt status will be restored to the same value it had when entering the respective block (unless ATOMIC_FORCEON or NONATOMIC_FORCEOFF are used). slay, automatic cleanup 💅

Warning ⚠️ — the features in this header are implemented by means of a for loop. which means commands like break and continue that are located in an atomic block refer to the atomic for loop, not to a loop construct that hosts the atomic block. so if you break thinking you're breaking your outer loop... you're not. 💀

---

🍓 The classic example (aka why you even care)

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. declaring such a variable as volatile ensures the compiler won't optimize accesses to it away, but it does not guarantee atomic access to it. ngl that's the plot twist. 🙈

Assuming the following example:

#include <stdint.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. why?? 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 tests the low byte for 0, which succeeds. then it proceeds to test the high byte, but that moment the ISR triggers, and the main context is interrupted. the ISR decrements 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. literally gaslit by the scheduler 😭

Using the macros from this header file, the above code can be rewritten like:

#include <stdint.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. and 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. choose wisely bestie 🧚

See Problems with reordering code for things to be taken into account with respect to compiler optimizations. 👀

---

👑 Macro Definition Documentation 👑

💜 #define ATOMIC_BLOCK( type)

Creates a block of code that is guaranteed to be executed atomically. upon entering the block the Global Interrupt Status flag in SREG is disabled, and re-enabled upon exiting the block from any exit path. every door leads to the interrupt coming back on, we love to see it 🚪✨

Two possible macro parameters are permitted: ATOMIC_RESTORESTATE and ATOMIC_FORCEON.

💜 #define ATOMIC_FORCEON

This is a possible parameter for ATOMIC_BLOCK. when used, it will cause the ATOMIC_BLOCK to force the state of the SREG register on exit, enabling the Global Interrupt Status flag bit. this saves a small amount of flash space, a register, and one or more processor cycles, since the previous value of the SREG register does not need to be saved at the start of the block. efficient queen 💅

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. don't just yolo it 🙏

💜 #define ATOMIC_RESTORESTATE

This is a possible parameter for ATOMIC_BLOCK. when used, it will cause the ATOMIC_BLOCK to restore the previous state of the SREG register, saved before the Global Interrupt Status flag bit was disabled. the net effect is that the ATOMIC_BLOCK's contents are guaranteed atomic, without changing the state of the Global Interrupt Status flag when execution of the block completes. it puts everything back exactly how it found it, iconic behavior 🎀

💜 #define NONATOMIC_BLOCK( type)

Creates a block of code that is executed non-atomically. upon entering the block the Global Interrupt Status flag in SREG is enabled, and disabled upon exiting the block from any exit path. this is useful when nested inside ATOMIC_BLOCK sections, allowing for non-atomic execution of small blocks of code while maintaining the atomic access of the other sections of the parent ATOMIC_BLOCK. a little pocket of chaos inside the calm 🦋

Two possible macro parameters are permitted: NONATOMIC_RESTORESTATE and NONATOMIC_FORCEOFF.

💜 #define NONATOMIC_FORCEOFF

This is a possible parameter for NONATOMIC_BLOCK. when used, it will cause the NONATOMIC_BLOCK to force the state of the SREG register on exit, disabling the Global Interrupt Status flag bit. this saves a small amount of flash space, a register, and one or more processor cycles, since the previous value of the SREG register does not need to be saved at the start of the block. 🔥

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. like, know what you're doing, bestie 😌

💜 #define NONATOMIC_RESTORESTATE

This is a possible parameter for NONATOMIC_BLOCK. when used, it will cause the NONATOMIC_BLOCK to restore the previous state of the SREG register, saved before the Global Interrupt Status flag bit was enabled. the net effect is that the NONATOMIC_BLOCK's contents are guaranteed non-atomic, without changing the state of the Global Interrupt Status flag when execution of the block completes. she remembers where she came from 💖

---

🌈 Author 🌈

Generated automatically by Doxygen for AVR-LibC from the source code. (not a human writing poetry, just doxygen doing its thing, respect the grind 🤖)

---

and that's the whole page, bestie!! this was AVR-LibC, Version 2.2.1, util_atomic(3avr) — go forth and protect your 16-bit variables. mwah 💋 ✨🌸💅🫶