<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> <title>avr-libc: <util/delay.h>: Convenience functions for busy-wait delay loops</title> <link href="dox.css" rel="stylesheet" type="text/css"> </head> <body> <center> <table width="80%"> <tr> <td align="left"><a href="http://www.nongnu.org/avr-libc/">AVR Libc Home Page</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/">AVR Libc Development Pages</a></td> </tr> <tr> <td align="center" width="13%"><a href="index.html">Main Page</a></td> <td align="center" width="13%"><a href="pages.html">User Manual</a></td> <td align="center" width="13%"><a href="modules.html">Library Reference</a></td> <td align="center" width="13%"><a href="FAQ.html">FAQ</a></td> <td align="center" width="13%"><a href="globals.html">Alphabetical Index</a></td> <td align="center" width="13%"><a href="group__demos.html">Example Projects</a></td> </tr> </table> </center> <hr width="80%"> <!-- Generated by Doxygen 1.7.2 --> <div class="header"> <div class="summary"> <a href="#func-members">Functions</a> </div> <div class="headertitle"> <h1><util/delay.h>: Convenience functions for busy-wait delay loops</h1> </div> </div> <div class="contents"> <table class="memberdecls"> <tr><td colspan="2"><h2><a name="func-members"></a> Functions</h2></td></tr> <tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__util__delay.html#gad22e7a36b80e2f917324dc43a425e9d3">_delay_ms</a> (double __ms)</td></tr> <tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__util__delay.html#gab20bfffeacc678cb960944f5519c0c4f">_delay_us</a> (double __us)</td></tr> </table> <hr/><a name="_details"></a><h2>Detailed Description</h2> <div class="fragment"><pre class="fragment"><span class="preprocessor"> #define F_CPU 1000000UL // 1 MHz</span> <span class="preprocessor"></span> <span class="comment">//#define F_CPU 14.7456E6</span> <span class="preprocessor"> #include <<a class="code" href="delay_8h.html">util/delay.h</a>></span> </pre></div><dl class="note"><dt><b>Note:</b></dt><dd>As an alternative method, it is possible to pass the F_CPU macro down to the compiler from the Makefile. Obviously, in that case, no <code>#define</code> statement should be used.</dd></dl> <p>The functions in this header file are wrappers around the basic busy-wait functions from <<a class="el" href="delay__basic_8h.html">util/delay_basic.h</a>>. They are meant as convenience functions where actual time values can be specified rather than a number of cycles to wait for. The idea behind is that compile-time constant expressions will be eliminated by compiler optimization so floating-point expressions can be used to calculate the number of delay cycles needed based on the CPU frequency passed by the macro F_CPU.</p> <dl class="note"><dt><b>Note:</b></dt><dd>In order for these functions to work as intended, compiler optimizations <em>must</em> be enabled, and the delay time <em>must</em> be an expression that is a known constant at compile-time. If these requirements are not met, the resulting delay will be much longer (and basically unpredictable), and applications that otherwise do not use floating-point calculations will experience severe code bloat by the floating-point library routines linked into the application.</dd></dl> <p>The functions available allow the specification of microsecond, and millisecond delays directly, using the application-supplied macro F_CPU as the CPU clock frequency (in Hertz). </p> <hr/><h2>Function Documentation</h2> <a class="anchor" id="gad22e7a36b80e2f917324dc43a425e9d3"></a><!-- doxytag: member="delay.h::_delay_ms" ref="gad22e7a36b80e2f917324dc43a425e9d3" args="(double __ms)" --> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">void _delay_ms </td> <td>(</td> <td class="paramtype">double </td> <td class="paramname"> <em>__ms</em> )</td> <td></td> </tr> </table> </div> <div class="memdoc"> <p>Perform a delay of <code>__ms</code> milliseconds, using <a class="el" href="group__util__delay__basic.html#ga74a94fec42bac9f1ff31fd443d419a6a">_delay_loop_2()</a>.</p> <p>The macro F_CPU is supposed to be defined to a constant defining the CPU clock frequency (in Hertz).</p> <p>The maximal possible delay is 262.14 ms / F_CPU in MHz.</p> <p>When the user request delay which exceed the maximum possible one, <a class="el" href="group__util__delay.html#gad22e7a36b80e2f917324dc43a425e9d3">_delay_ms()</a> provides a decreased resolution functionality. In this mode <a class="el" href="group__util__delay.html#gad22e7a36b80e2f917324dc43a425e9d3">_delay_ms()</a> will work with a resolution of 1/10 ms, providing delays up to 6.5535 seconds (independent from CPU frequency). The user will not be informed about decreased resolution.</p> <p>If the avr-gcc toolchain has __builtin_avr_delay_cycles(unsigned long) support, maximal possible delay is 4294967.295 ms/ F_CPU in MHz. For values greater than the maximal possible delay, overflows results in no delay i.e., 0ms.</p> <p>Conversion of __us into clock cycles may not always result in integer. By default, the clock cycles rounded up to next integer. This ensures that the user gets atleast __us microseconds of delay.</p> <p>Alternatively, user can define __DELAY_ROUND_DOWN__ and __DELAY_ROUND_CLOSEST__ to round down and round to closest integer.</p> <p>Note: The new implementation of <a class="el" href="group__util__delay.html#gad22e7a36b80e2f917324dc43a425e9d3">_delay_ms(double __ms)</a> with __builtin_avr_delay_cycles(unsigned long) support is not backward compatible. User can define __DELAY_BACKWARD_COMPATIBLE__ to get a backward compatible delay although this will be deprecated in future. </p> </div> </div> <a class="anchor" id="gab20bfffeacc678cb960944f5519c0c4f"></a><!-- doxytag: member="delay.h::_delay_us" ref="gab20bfffeacc678cb960944f5519c0c4f" args="(double __us)" --> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">void _delay_us </td> <td>(</td> <td class="paramtype">double </td> <td class="paramname"> <em>__us</em> )</td> <td></td> </tr> </table> </div> <div class="memdoc"> <p>Perform a delay of <code>__us</code> microseconds, using <a class="el" href="group__util__delay__basic.html#ga4e3957917c4c447d0f9166dac881b4e3">_delay_loop_1()</a>.</p> <p>The macro F_CPU is supposed to be defined to a constant defining the CPU clock frequency (in Hertz).</p> <p>The maximal possible delay is 768 us / F_CPU in MHz.</p> <p>If the user requests a delay greater than the maximal possible one, <a class="el" href="group__util__delay.html#gab20bfffeacc678cb960944f5519c0c4f">_delay_us()</a> will automatically call <a class="el" href="group__util__delay.html#gad22e7a36b80e2f917324dc43a425e9d3">_delay_ms()</a> instead. The user will not be informed about this case.</p> <p>If the avr-gcc toolchain has __builtin_avr_delay_cycles(unsigned long) support, maximal possible delay is 4294967.295 us/ F_CPU in MHz. For values greater than the maximal possible delay, overflow results in no delay i.e., 0us.</p> <p>Conversion of __us into clock cycles may not always result in integer. By default, the clock cycles rounded up to next integer. This ensures that the user gets atleast __us microseconds of delay.</p> <p>Alternatively, user can define __DELAY_ROUND_DOWN__ and __DELAY_ROUND_CLOSEST__ to round down and round to closest integer.</p> <p>Note: The new implementation of <a class="el" href="group__util__delay.html#gab20bfffeacc678cb960944f5519c0c4f">_delay_us(double __us)</a> with __builtin_avr_delay_cycles(unsigned long) support is not backward compatible. User can define __DELAY_BACKWARD_COMPATIBLE__ to get a backward compatible delay although this will be deprecated in future. </p> </div> </div> </div> <hr width="80%"> <p><center>Automatically generated by Doxygen 1.7.2 on Wed Feb 16 2011.</center></p> </body> </html>