You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
283 lines
17 KiB
HTML
283 lines
17 KiB
HTML
<!-- HTML header for doxygen 1.8.7-->
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.6.3"/>
|
|
<!--BEGIN PROJECT_NAME--><title>avr-libc: avr-libc: <util/atomic.h> Atomically and Non-Atomically Executed Code Blocks</title><!--END PROJECT_NAME-->
|
|
<!--BEGIN !PROJECT_NAME--><title>avr-libc: <util/atomic.h> Atomically and Non-Atomically Executed Code Blocks</title><!--END !PROJECT_NAME-->
|
|
<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="$relpath^jquery.js"></script>
|
|
<script type="text/javascript" src="$relpath^dynsections.js"></script>
|
|
$treeview
|
|
$search
|
|
$mathjax
|
|
<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
|
|
$extrastylesheet
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
|
|
<!--BEGIN TITLEAREA-->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr style="height: 56px;">
|
|
<!--BEGIN PROJECT_LOGO-->
|
|
<td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
|
|
<!--END PROJECT_LOGO-->
|
|
<!--BEGIN PROJECT_NAME-->
|
|
<td style="padding-left: 0.5em;">
|
|
<div id="projectname">avr-libc
|
|
<!--BEGIN PROJECT_NUMBER--> <span id="projectnumber">2.0.0</span><!--END PROJECT_NUMBER-->
|
|
</div>
|
|
<!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
|
|
</td>
|
|
<!--END PROJECT_NAME-->
|
|
<!--BEGIN !PROJECT_NAME-->
|
|
<!--BEGIN PROJECT_BRIEF-->
|
|
<td style="padding-left: 0.5em;">
|
|
<div id="projectbrief">$projectbrief</div>
|
|
</td>
|
|
<!--END PROJECT_BRIEF-->
|
|
<!--END !PROJECT_NAME-->
|
|
<!--BEGIN DISABLE_INDEX-->
|
|
<!--BEGIN SEARCHENGINE-->
|
|
<td>$searchbox</td>
|
|
<!--END SEARCHENGINE-->
|
|
<!--END DISABLE_INDEX-->
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<table>
|
|
<tr>
|
|
<td align="left"><a href="http://www.nongnu.org/avr-libc/"><h2>AVR Libc Home Page</h2></a></td>
|
|
<td align="center" colspan=4><img src="avrs.png" alt="AVRs" align="middle" border="0"></td>
|
|
<td align="right"><a href="https://savannah.nongnu.org/projects/avr-libc/"><h2>AVR Libc Development Pages</h2></a></td>
|
|
</tr>
|
|
<tr>
|
|
<td align="center" width="20%"><a href="index.html"><h2>Main Page</h2></a></td>
|
|
<td align="center" width="20%"><a href="pages.html"><h2>User Manual</h2></a></td>
|
|
<td align="center" width="20%"><a href="modules.html"><h2>Library Reference</h2></a></td>
|
|
<td align="center" width="20%"><a href="FAQ.html"><h2>FAQ</h2></a></td>
|
|
<td align="center" width="20%"><a href="group__demos.html"><h2>Example Projects</h2></a></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<!--END TITLEAREA-->
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.6.3 -->
|
|
<script type="text/javascript"><!--
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
--></script>
|
|
<div class="contents">
|
|
<h1><util/atomic.h> Atomically and Non-Atomically Executed Code Blocks</h1><table border="0" cellpadding="0" cellspacing="0">
|
|
<tr><td colspan="2"><h2>Defines</h2></td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__util__atomic.html#gaaaea265b31dabcfb3098bec7685c39e4">ATOMIC_BLOCK</a>(type)</td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__util__atomic.html#ga6e195ee2117559a25f77fbba9054674a">NONATOMIC_BLOCK</a>(type)</td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__util__atomic.html#ga362c18b15a09703e42e1c246c47420ef">ATOMIC_RESTORESTATE</a></td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__util__atomic.html#ga92b11103b4b3b000a3190f0d26ba7062">ATOMIC_FORCEON</a></td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__util__atomic.html#gab075653bf638fae9db049575741d3152">NONATOMIC_RESTORESTATE</a></td></tr>
|
|
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__util__atomic.html#gafb959d7d00d2d790b58d0e9880ea255a">NONATOMIC_FORCEOFF</a></td></tr>
|
|
</table>
|
|
<hr/><a name="_details"></a><h2>Detailed Description</h2>
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <<a class="code" href="atomic_8h.html">util/atomic.h</a>></span>
|
|
</pre></div><dl class="note"><dt><b>Note:</b></dt><dd>The macros in this header file require the ISO/IEC 9899:1999 ("ISO C99") 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 <code>c99</code> or <code>gnu99</code>.</dd></dl>
|
|
<p>The macros in this header file deal with code blocks that are guaranteed to be excuted Atomically or Non-Atmomically. The term "Atomic" in this context refers to the unability of the respective code to be interrupted.</p>
|
|
<p>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.</p>
|
|
<p>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:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="inttypes_8h.html">inttypes.h</a>></span>
|
|
<span class="preprocessor">#include <<a class="code" href="interrupt_8h.html">avr/interrupt.h</a>></span>
|
|
<span class="preprocessor">#include <<a class="code" href="io_8h.html">avr/io.h</a>></span>
|
|
|
|
<span class="keyword">volatile</span> <a class="code" href="group__avr__stdint.html#ga1f1825b69244eb3ad2c7165ddc99c956">uint16_t</a> ctr;
|
|
|
|
<a class="code" href="group__avr__interrupts.html#gad28590624d422cdf30d626e0a506255f">ISR</a>(TIMER1_OVF_vect)
|
|
{
|
|
ctr--;
|
|
}
|
|
|
|
...
|
|
int
|
|
main(<span class="keywordtype">void</span>)
|
|
{
|
|
...
|
|
ctr = 0x200;
|
|
start_timer();
|
|
<span class="keywordflow">while</span> (ctr != 0)
|
|
<span class="comment">// wait</span>
|
|
;
|
|
...
|
|
}
|
|
</pre></div><p>There is a chance where the main context will exit its wait loop when the variable <code>ctr</code> 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.</p>
|
|
<p>Using the macros from this header file, the above code can be rewritten like:</p>
|
|
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="inttypes_8h.html">inttypes.h</a>></span>
|
|
<span class="preprocessor">#include <<a class="code" href="interrupt_8h.html">avr/interrupt.h</a>></span>
|
|
<span class="preprocessor">#include <<a class="code" href="io_8h.html">avr/io.h</a>></span>
|
|
<span class="preprocessor">#include <<a class="code" href="atomic_8h.html">util/atomic.h</a>></span>
|
|
|
|
<span class="keyword">volatile</span> <a class="code" href="group__avr__stdint.html#ga1f1825b69244eb3ad2c7165ddc99c956">uint16_t</a> ctr;
|
|
|
|
<a class="code" href="group__avr__interrupts.html#gad28590624d422cdf30d626e0a506255f">ISR</a>(TIMER1_OVF_vect)
|
|
{
|
|
ctr--;
|
|
}
|
|
|
|
...
|
|
int
|
|
main(<span class="keywordtype">void</span>)
|
|
{
|
|
...
|
|
ctr = 0x200;
|
|
start_timer();
|
|
<a class="code" href="group__avr__interrupts.html#gaad5ebd34cb344c26ac87594f79b06b73">sei</a>();
|
|
<a class="code" href="group__avr__stdint.html#ga1f1825b69244eb3ad2c7165ddc99c956">uint16_t</a> ctr_copy;
|
|
<span class="keywordflow">do</span>
|
|
{
|
|
<a class="code" href="group__util__atomic.html#gaaaea265b31dabcfb3098bec7685c39e4">ATOMIC_BLOCK</a>(<a class="code" href="group__util__atomic.html#ga92b11103b4b3b000a3190f0d26ba7062">ATOMIC_FORCEON</a>)
|
|
{
|
|
ctr_copy = ctr;
|
|
}
|
|
}
|
|
<span class="keywordflow">while</span> (ctr_copy != 0);
|
|
...
|
|
}
|
|
</pre></div><p>This will install the appropriate interrupt protection before accessing variable <code>ctr</code>, 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.</p>
|
|
<p>See <a class="el" href="optimization.html#optim_code_reorder">Problems with reordering code</a> for things to be taken into account with respect to compiler optimizations. </p>
|
|
<hr/><h2>Define Documentation</h2>
|
|
<a class="anchor" id="gaaaea265b31dabcfb3098bec7685c39e4"></a><!-- doxytag: member="atomic.h::ATOMIC_BLOCK" ref="gaaaea265b31dabcfb3098bec7685c39e4" args="(type)" -->
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">#define ATOMIC_BLOCK</td>
|
|
<td>(</td>
|
|
<td class="paramtype">type </td>
|
|
<td class="paramname"></td>
|
|
<td> ) </td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="memdoc">
|
|
<p>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.</p>
|
|
<p>Two possible macro parameters are permitted, ATOMIC_RESTORESTATE and ATOMIC_FORCEON. </p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="ga92b11103b4b3b000a3190f0d26ba7062"></a><!-- doxytag: member="atomic.h::ATOMIC_FORCEON" ref="ga92b11103b4b3b000a3190f0d26ba7062" args="" -->
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">#define ATOMIC_FORCEON</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="memdoc">
|
|
<p>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 on flash space as the previous value of the SREG register does not need to be saved at the start of the block.</p>
|
|
<p>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. </p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="ga362c18b15a09703e42e1c246c47420ef"></a><!-- doxytag: member="atomic.h::ATOMIC_RESTORESTATE" ref="ga362c18b15a09703e42e1c246c47420ef" args="" -->
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">#define ATOMIC_RESTORESTATE</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="memdoc">
|
|
<p>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 of this is to make the ATOMIC_BLOCK's contents guaranteed atomic, without changing the state of the Global Interrupt Status flag when execution of the block completes. </p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="ga6e195ee2117559a25f77fbba9054674a"></a><!-- doxytag: member="atomic.h::NONATOMIC_BLOCK" ref="ga6e195ee2117559a25f77fbba9054674a" args="(type)" -->
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">#define NONATOMIC_BLOCK</td>
|
|
<td>(</td>
|
|
<td class="paramtype">type </td>
|
|
<td class="paramname"></td>
|
|
<td> ) </td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="memdoc">
|
|
<p>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.</p>
|
|
<p>Two possible macro parameters are permitted, NONATOMIC_RESTORESTATE and NONATOMIC_FORCEOFF. </p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="gafb959d7d00d2d790b58d0e9880ea255a"></a><!-- doxytag: member="atomic.h::NONATOMIC_FORCEOFF" ref="gafb959d7d00d2d790b58d0e9880ea255a" args="" -->
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">#define NONATOMIC_FORCEOFF</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="memdoc">
|
|
<p>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 on flash space as the previous value of the SREG register does not need to be saved at the start of the block.</p>
|
|
<p>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. </p>
|
|
|
|
</div>
|
|
</div>
|
|
<a class="anchor" id="gab075653bf638fae9db049575741d3152"></a><!-- doxytag: member="atomic.h::NONATOMIC_RESTORESTATE" ref="gab075653bf638fae9db049575741d3152" args="" -->
|
|
<div class="memitem">
|
|
<div class="memproto">
|
|
<table class="memname">
|
|
<tr>
|
|
<td class="memname">#define NONATOMIC_RESTORESTATE</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<div class="memdoc">
|
|
<p>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 of this is to make the NONATOMIC_BLOCK's contents guaranteed non-atomic, without changing the state of the Global Interrupt Status flag when execution of the block completes. </p>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<!--- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Defines</a></div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
<!-- HTML footer for doxygen 1.8.7-->
|
|
<!-- start footer part -->
|
|
<!--BEGIN GENERATE_TREEVIEW-->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
$navpath
|
|
<li class="footer">$generatedby
|
|
<a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/></a> 1.6.3 </li>
|
|
</ul>
|
|
</div>
|
|
<!--END GENERATE_TREEVIEW-->
|
|
<!--BEGIN !GENERATE_TREEVIEW-->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
$generatedby  <a href="http://www.doxygen.org/index.html">
|
|
<img class="footer" src="$relpath^doxygen.png" alt="doxygen"/>
|
|
</a> 1.6.3
|
|
</small></address>
|
|
<!--END !GENERATE_TREEVIEW-->
|
|
</body>
|
|
</html>
|