\hypertarget{group__util__atomic}{}\doxysubsection{$<$util/atomic.h$>$ Atomically and Non-\/\+Atomically Executed Code Blocks}
\label{group__util__atomic}\index{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}}
\doxysubsubsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define \mbox{\hyperlink{group__util__atomic_gaaaea265b31dabcfb3098bec7685c39e4}{A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK}}(type)
\item 
\#define \mbox{\hyperlink{group__util__atomic_ga6e195ee2117559a25f77fbba9054674a}{N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK}}(type)
\item 
\#define \mbox{\hyperlink{group__util__atomic_ga362c18b15a09703e42e1c246c47420ef}{A\+T\+O\+M\+I\+C\+\_\+\+R\+E\+S\+T\+O\+R\+E\+S\+T\+A\+TE}}
\item 
\#define \mbox{\hyperlink{group__util__atomic_ga92b11103b4b3b000a3190f0d26ba7062}{A\+T\+O\+M\+I\+C\+\_\+\+F\+O\+R\+C\+E\+ON}}
\item 
\#define \mbox{\hyperlink{group__util__atomic_gab075653bf638fae9db049575741d3152}{N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+R\+E\+S\+T\+O\+R\+E\+S\+T\+A\+TE}}
\item 
\#define \mbox{\hyperlink{group__util__atomic_gafb959d7d00d2d790b58d0e9880ea255a}{N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+F\+O\+R\+C\+E\+O\+FF}}
\end{DoxyCompactItemize}


\doxysubsubsection{Detailed Description}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{atomic_8h}{util/atomic.h}}>}}
\end{DoxyCode}


\begin{DoxyNote}{Note}
The macros in this header file require the I\+S\+O/\+I\+EC 9899\+:1999 (\char`\"{}\+I\+S\+O C99\char`\"{}) feature of for loop variables that are declared inside the for loop itself. For that reason, this header file can only be used if the standard level of the compiler (option --std=) is set to either {\ttfamily c99} or {\ttfamily gnu99}.
\end{DoxyNote}
The macros in this header file deal with code blocks that are guaranteed to be excuted Atomically or Non-\/\+Atmomically. The term \char`\"{}\+Atomic\char`\"{} in this context refers to the unability of the respective code to be interrupted.

These macros operate via automatic manipulation of the Global Interrupt Status (I) bit of the S\+R\+EG 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 I\+SR. 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\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{inttypes_8h}{inttypes.h}}>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{interrupt_8h}{avr/interrupt.h}}>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{io_8h}{avr/io.h}}>}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keyword}{volatile} \mbox{\hyperlink{group__avr__stdint_ga1f1825b69244eb3ad2c7165ddc99c956}{uint16\_t}} ctr;}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__avr__interrupts_gad28590624d422cdf30d626e0a506255f}{ISR}}(TIMER1\_OVF\_vect)}
\DoxyCodeLine{\{}
\DoxyCodeLine{  ctr-\/-\/;}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{...}
\DoxyCodeLine{int}
\DoxyCodeLine{main(\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{   ...}
\DoxyCodeLine{   ctr = 0x200;}
\DoxyCodeLine{   start\_timer();}
\DoxyCodeLine{   \textcolor{keywordflow}{while} (ctr != 0)}
\DoxyCodeLine{     \textcolor{comment}{// wait}}
\DoxyCodeLine{       ;}
\DoxyCodeLine{   ...}
\DoxyCodeLine{\}}
\end{DoxyCode}


There is a chance where the main context will exit its wait loop when the variable {\ttfamily ctr} just reached the value 0x\+FF. This happens because the compiler cannot natively access a 16-\/bit variable atomically in an 8-\/bit C\+PU. 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 I\+SR triggers, and the main context is interrupted. The I\+SR will decrement the variable from 0x100 to 0x\+FF, 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\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{inttypes_8h}{inttypes.h}}>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{interrupt_8h}{avr/interrupt.h}}>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{io_8h}{avr/io.h}}>}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{atomic_8h}{util/atomic.h}}>}}
\DoxyCodeLine{}
\DoxyCodeLine{\textcolor{keyword}{volatile} \mbox{\hyperlink{group__avr__stdint_ga1f1825b69244eb3ad2c7165ddc99c956}{uint16\_t}} ctr;}
\DoxyCodeLine{}
\DoxyCodeLine{\mbox{\hyperlink{group__avr__interrupts_gad28590624d422cdf30d626e0a506255f}{ISR}}(TIMER1\_OVF\_vect)}
\DoxyCodeLine{\{}
\DoxyCodeLine{  ctr-\/-\/;}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{...}
\DoxyCodeLine{int}
\DoxyCodeLine{main(\textcolor{keywordtype}{void})}
\DoxyCodeLine{\{}
\DoxyCodeLine{   ...}
\DoxyCodeLine{   ctr = 0x200;}
\DoxyCodeLine{   start\_timer();}
\DoxyCodeLine{   \mbox{\hyperlink{group__avr__interrupts_gaad5ebd34cb344c26ac87594f79b06b73}{sei}}();}
\DoxyCodeLine{   \mbox{\hyperlink{group__avr__stdint_ga1f1825b69244eb3ad2c7165ddc99c956}{uint16\_t}} ctr\_copy;}
\DoxyCodeLine{   \textcolor{keywordflow}{do}}
\DoxyCodeLine{   \{}
\DoxyCodeLine{     \mbox{\hyperlink{group__util__atomic_gaaaea265b31dabcfb3098bec7685c39e4}{ATOMIC\_BLOCK}}(\mbox{\hyperlink{group__util__atomic_ga92b11103b4b3b000a3190f0d26ba7062}{ATOMIC\_FORCEON}})}
\DoxyCodeLine{     \{}
\DoxyCodeLine{       ctr\_copy = ctr;}
\DoxyCodeLine{     \}}
\DoxyCodeLine{   \}}
\DoxyCodeLine{   \textcolor{keywordflow}{while} (ctr\_copy != 0);}
\DoxyCodeLine{   ...}
\DoxyCodeLine{\}}
\end{DoxyCode}


This will install the appropriate interrupt protection before accessing variable {\ttfamily ctr}, so it is guaranteed to be consistently tested. If the global interrupt state were uncertain before entering the A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK, it should be executed with the parameter A\+T\+O\+M\+I\+C\+\_\+\+R\+E\+S\+T\+O\+R\+E\+S\+T\+A\+TE rather than A\+T\+O\+M\+I\+C\+\_\+\+F\+O\+R\+C\+E\+ON.

See \mbox{\hyperlink{optimization_optim_code_reorder}{Problems with reordering code}} for things to be taken into account with respect to compiler optimizations. 

\doxysubsubsection{Macro Definition Documentation}
\mbox{\Hypertarget{group__util__atomic_gaaaea265b31dabcfb3098bec7685c39e4}\label{group__util__atomic_gaaaea265b31dabcfb3098bec7685c39e4}} 
\index{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}!ATOMIC\_BLOCK@{ATOMIC\_BLOCK}}
\index{ATOMIC\_BLOCK@{ATOMIC\_BLOCK}!$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}}
\doxyparagraph{\texorpdfstring{ATOMIC\_BLOCK}{ATOMIC\_BLOCK}}
{\footnotesize\ttfamily \#define A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK(\begin{DoxyParamCaption}\item[{}]{type }\end{DoxyParamCaption})}

Creates a block of code that is guaranteed to be executed atomically. Upon entering the block the Global Interrupt Status flag in S\+R\+EG is disabled, and re-\/enabled upon exiting the block from any exit path.

Two possible macro parameters are permitted, A\+T\+O\+M\+I\+C\+\_\+\+R\+E\+S\+T\+O\+R\+E\+S\+T\+A\+TE and A\+T\+O\+M\+I\+C\+\_\+\+F\+O\+R\+C\+E\+ON. \mbox{\Hypertarget{group__util__atomic_ga92b11103b4b3b000a3190f0d26ba7062}\label{group__util__atomic_ga92b11103b4b3b000a3190f0d26ba7062}} 
\index{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}!ATOMIC\_FORCEON@{ATOMIC\_FORCEON}}
\index{ATOMIC\_FORCEON@{ATOMIC\_FORCEON}!$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}}
\doxyparagraph{\texorpdfstring{ATOMIC\_FORCEON}{ATOMIC\_FORCEON}}
{\footnotesize\ttfamily \#define A\+T\+O\+M\+I\+C\+\_\+\+F\+O\+R\+C\+E\+ON}

This is a possible parameter for A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK. When used, it will cause the A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK to force the state of the S\+R\+EG register on exit, enabling the Global Interrupt Status flag bit. This saves on flash space as the previous value of the S\+R\+EG register does not need to be saved at the start of the block.

Care should be taken that A\+T\+O\+M\+I\+C\+\_\+\+F\+O\+R\+C\+E\+ON is only used when it is known that interrupts are enabled before the block\textquotesingle{}s execution or when the side effects of enabling global interrupts at the block\textquotesingle{}s completion are known and understood. \mbox{\Hypertarget{group__util__atomic_ga362c18b15a09703e42e1c246c47420ef}\label{group__util__atomic_ga362c18b15a09703e42e1c246c47420ef}} 
\index{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}!ATOMIC\_RESTORESTATE@{ATOMIC\_RESTORESTATE}}
\index{ATOMIC\_RESTORESTATE@{ATOMIC\_RESTORESTATE}!$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}}
\doxyparagraph{\texorpdfstring{ATOMIC\_RESTORESTATE}{ATOMIC\_RESTORESTATE}}
{\footnotesize\ttfamily \#define A\+T\+O\+M\+I\+C\+\_\+\+R\+E\+S\+T\+O\+R\+E\+S\+T\+A\+TE}

This is a possible parameter for A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK. When used, it will cause the A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK to restore the previous state of the S\+R\+EG register, saved before the Global Interrupt Status flag bit was disabled. The net effect of this is to make the A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK\textquotesingle{}s contents guaranteed atomic, without changing the state of the Global Interrupt Status flag when execution of the block completes. \mbox{\Hypertarget{group__util__atomic_ga6e195ee2117559a25f77fbba9054674a}\label{group__util__atomic_ga6e195ee2117559a25f77fbba9054674a}} 
\index{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}!NONATOMIC\_BLOCK@{NONATOMIC\_BLOCK}}
\index{NONATOMIC\_BLOCK@{NONATOMIC\_BLOCK}!$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}}
\doxyparagraph{\texorpdfstring{NONATOMIC\_BLOCK}{NONATOMIC\_BLOCK}}
{\footnotesize\ttfamily \#define N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK(\begin{DoxyParamCaption}\item[{}]{type }\end{DoxyParamCaption})}

Creates a block of code that is executed non-\/atomically. Upon entering the block the Global Interrupt Status flag in S\+R\+EG is enabled, and disabled upon exiting the block from any exit path. This is useful when nested inside A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK sections, allowing for non-\/atomic execution of small blocks of code while maintaining the atomic access of the other sections of the parent A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK.

Two possible macro parameters are permitted, N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+R\+E\+S\+T\+O\+R\+E\+S\+T\+A\+TE and N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+F\+O\+R\+C\+E\+O\+FF. \mbox{\Hypertarget{group__util__atomic_gafb959d7d00d2d790b58d0e9880ea255a}\label{group__util__atomic_gafb959d7d00d2d790b58d0e9880ea255a}} 
\index{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}!NONATOMIC\_FORCEOFF@{NONATOMIC\_FORCEOFF}}
\index{NONATOMIC\_FORCEOFF@{NONATOMIC\_FORCEOFF}!$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}}
\doxyparagraph{\texorpdfstring{NONATOMIC\_FORCEOFF}{NONATOMIC\_FORCEOFF}}
{\footnotesize\ttfamily \#define N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+F\+O\+R\+C\+E\+O\+FF}

This is a possible parameter for N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK. When used, it will cause the N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK to force the state of the S\+R\+EG register on exit, disabling the Global Interrupt Status flag bit. This saves on flash space as the previous value of the S\+R\+EG register does not need to be saved at the start of the block.

Care should be taken that N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+F\+O\+R\+C\+E\+O\+FF is only used when it is known that interrupts are disabled before the block\textquotesingle{}s execution or when the side effects of disabling global interrupts at the block\textquotesingle{}s completion are known and understood. \mbox{\Hypertarget{group__util__atomic_gab075653bf638fae9db049575741d3152}\label{group__util__atomic_gab075653bf638fae9db049575741d3152}} 
\index{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}!NONATOMIC\_RESTORESTATE@{NONATOMIC\_RESTORESTATE}}
\index{NONATOMIC\_RESTORESTATE@{NONATOMIC\_RESTORESTATE}!$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks@{$<$util/atomic.h$>$ Atomically and Non-\/Atomically Executed Code Blocks}}
\doxyparagraph{\texorpdfstring{NONATOMIC\_RESTORESTATE}{NONATOMIC\_RESTORESTATE}}
{\footnotesize\ttfamily \#define N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+R\+E\+S\+T\+O\+R\+E\+S\+T\+A\+TE}

This is a possible parameter for N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK. When used, it will cause the N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK to restore the previous state of the S\+R\+EG register, saved before the Global Interrupt Status flag bit was enabled. The net effect of this is to make the N\+O\+N\+A\+T\+O\+M\+I\+C\+\_\+\+B\+L\+O\+CK\textquotesingle{}s contents guaranteed non-\/atomic, without changing the state of the Global Interrupt Status flag when execution of the block completes. 