\hypertarget{group__util__delay}{}\doxysubsection{$<$util/delay.h$>$\+: Convenience functions for busy-\/wait delay loops}
\label{group__util__delay}\index{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops@{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops}}
\doxysubsubsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define \mbox{\hyperlink{group__util__delay_ga43bafb28b29491ec7f871319b5a3b2f8}{F\+\_\+\+C\+PU}}~1000000\+UL
\end{DoxyCompactItemize}
\doxysubsubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
void \mbox{\hyperlink{group__util__delay_gad22e7a36b80e2f917324dc43a425e9d3}{\+\_\+delay\+\_\+ms}} (double \+\_\+\+\_\+ms)
\item 
void \mbox{\hyperlink{group__util__delay_gab20bfffeacc678cb960944f5519c0c4f}{\+\_\+delay\+\_\+us}} (double \+\_\+\+\_\+us)
\end{DoxyCompactItemize}


\doxysubsubsection{Detailed Description}

\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{preprocessor}{\#define F\_CPU 1000000UL  // 1 MHz}}
\DoxyCodeLine{\textcolor{comment}{//\#define F\_CPU 14.7456E6}}
\DoxyCodeLine{\textcolor{preprocessor}{\#include <\mbox{\hyperlink{delay_8h}{util/delay.h}}>}}
\end{DoxyCode}


\begin{DoxyNote}{Note}
As an alternative method, it is possible to pass the F\+\_\+\+C\+PU macro down to the compiler from the Makefile. Obviously, in that case, no {\ttfamily \#define} statement should be used.
\end{DoxyNote}
The functions in this header file are wrappers around the basic busy-\/wait functions from $<$\mbox{\hyperlink{delay__basic_8h}{util/delay\+\_\+basic.\+h}}$>$. 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 C\+PU frequency passed by the macro F\+\_\+\+C\+PU.

\begin{DoxyNote}{Note}
In order for these functions to work as intended, compiler optimizations {\itshape must} be enabled, and the delay time {\itshape must} 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.
\end{DoxyNote}
The functions available allow the specification of microsecond, and millisecond delays directly, using the application-\/supplied macro F\+\_\+\+C\+PU as the C\+PU clock frequency (in Hertz). 

\doxysubsubsection{Macro Definition Documentation}
\mbox{\Hypertarget{group__util__delay_ga43bafb28b29491ec7f871319b5a3b2f8}\label{group__util__delay_ga43bafb28b29491ec7f871319b5a3b2f8}} 
\index{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops@{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops}!F\_CPU@{F\_CPU}}
\index{F\_CPU@{F\_CPU}!$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops@{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops}}
\doxyparagraph{\texorpdfstring{F\_CPU}{F\_CPU}}
{\footnotesize\ttfamily \#define F\+\_\+\+C\+PU~1000000\+UL}



C\+PU frequency in Hz. 

The macro F\+\_\+\+C\+PU specifies the C\+PU frequency to be considered by the delay macros. This macro is normally supplied by the environment (e.\+g. from within a project header, or the project\textquotesingle{}s Makefile). The value 1 M\+Hz here is only provided as a \char`\"{}vanilla\char`\"{} fallback if no such user-\/provided definition could be found.

In terms of the delay functions, the C\+PU frequency can be given as a floating-\/point constant (e.\+g. 3.\+6864\+E6 for 3.\+6864 M\+Hz). However, the macros in $<$\mbox{\hyperlink{setbaud_8h}{util/setbaud.\+h}}$>$ require it to be an integer value. 

\doxysubsubsection{Function Documentation}
\mbox{\Hypertarget{group__util__delay_gad22e7a36b80e2f917324dc43a425e9d3}\label{group__util__delay_gad22e7a36b80e2f917324dc43a425e9d3}} 
\index{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops@{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops}!\_delay\_ms@{\_delay\_ms}}
\index{\_delay\_ms@{\_delay\_ms}!$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops@{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops}}
\doxyparagraph{\texorpdfstring{\_delay\_ms()}{\_delay\_ms()}}
{\footnotesize\ttfamily void \+\_\+delay\+\_\+ms (\begin{DoxyParamCaption}\item[{double}]{\+\_\+\+\_\+ms }\end{DoxyParamCaption})}

Perform a delay of {\ttfamily \+\_\+\+\_\+ms} milliseconds, using \mbox{\hyperlink{group__util__delay__basic_ga74a94fec42bac9f1ff31fd443d419a6a}{\+\_\+delay\+\_\+loop\+\_\+2()}}.

The macro F\+\_\+\+C\+PU is supposed to be defined to a constant defining the C\+PU clock frequency (in Hertz).

The maximal possible delay is 262.\+14 ms / F\+\_\+\+C\+PU in M\+Hz.

When the user request delay which exceed the maximum possible one, \mbox{\hyperlink{group__util__delay_gad22e7a36b80e2f917324dc43a425e9d3}{\+\_\+delay\+\_\+ms()}} provides a decreased resolution functionality. In this mode \mbox{\hyperlink{group__util__delay_gad22e7a36b80e2f917324dc43a425e9d3}{\+\_\+delay\+\_\+ms()}} will work with a resolution of 1/10 ms, providing delays up to 6.\+5535 seconds (independent from C\+PU frequency). The user will not be informed about decreased resolution.

If the avr-\/gcc toolchain has \+\_\+\+\_\+builtin\+\_\+avr\+\_\+delay\+\_\+cycles() support, maximal possible delay is 4294967.\+295 ms/ F\+\_\+\+C\+PU in M\+Hz. For values greater than the maximal possible delay, overflows results in no delay i.\+e., 0ms.

Conversion of {\ttfamily \+\_\+\+\_\+ms} 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 at least {\ttfamily \+\_\+\+\_\+ms} microseconds of delay.

Alternatively, by defining the macro {\ttfamily \+\_\+\+\_\+\+D\+E\+L\+A\+Y\+\_\+\+R\+O\+U\+N\+D\+\_\+\+D\+O\+W\+N\+\_\+\+\_\+}, or {\ttfamily \+\_\+\+\_\+\+D\+E\+L\+A\+Y\+\_\+\+R\+O\+U\+N\+D\+\_\+\+C\+L\+O\+S\+E\+S\+T\+\_\+\+\_\+}, before including this header file, the algorithm can be made to round down, or round to closest integer, respectively.

\begin{DoxyNote}{Note}

\end{DoxyNote}
The implementation of \mbox{\hyperlink{group__util__delay_gad22e7a36b80e2f917324dc43a425e9d3}{\+\_\+delay\+\_\+ms()}} based on \+\_\+\+\_\+builtin\+\_\+avr\+\_\+delay\+\_\+cycles() is not backward compatible with older implementations. In order to get functionality backward compatible with previous versions, the macro {\ttfamily \char`\"{}\+\_\+\+\_\+\+D\+E\+L\+A\+Y\+\_\+\+B\+A\+C\+K\+W\+A\+R\+D\+\_\+\+C\+O\+M\+P\+A\+T\+I\+B\+L\+E\+\_\+\+\_\+\char`\"{}} must be defined before including this header file. Also, the backward compatible algorithm will be chosen if the code is compiled in a {\itshape freestanding environment} (G\+CC option {\ttfamily -\/ffreestanding}), as the math functions required for rounding are not available to the compiler then. \mbox{\Hypertarget{group__util__delay_gab20bfffeacc678cb960944f5519c0c4f}\label{group__util__delay_gab20bfffeacc678cb960944f5519c0c4f}} 
\index{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops@{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops}!\_delay\_us@{\_delay\_us}}
\index{\_delay\_us@{\_delay\_us}!$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops@{$<$util/delay.h$>$: Convenience functions for busy-\/wait delay loops}}
\doxyparagraph{\texorpdfstring{\_delay\_us()}{\_delay\_us()}}
{\footnotesize\ttfamily void \+\_\+delay\+\_\+us (\begin{DoxyParamCaption}\item[{double}]{\+\_\+\+\_\+us }\end{DoxyParamCaption})}

Perform a delay of {\ttfamily \+\_\+\+\_\+us} microseconds, using \mbox{\hyperlink{group__util__delay__basic_ga4e3957917c4c447d0f9166dac881b4e3}{\+\_\+delay\+\_\+loop\+\_\+1()}}.

The macro F\+\_\+\+C\+PU is supposed to be defined to a constant defining the C\+PU clock frequency (in Hertz).

The maximal possible delay is 768 us / F\+\_\+\+C\+PU in M\+Hz.

If the user requests a delay greater than the maximal possible one, \mbox{\hyperlink{group__util__delay_gab20bfffeacc678cb960944f5519c0c4f}{\+\_\+delay\+\_\+us()}} will automatically call \mbox{\hyperlink{group__util__delay_gad22e7a36b80e2f917324dc43a425e9d3}{\+\_\+delay\+\_\+ms()}} instead. The user will not be informed about this case.

If the avr-\/gcc toolchain has \+\_\+\+\_\+builtin\+\_\+avr\+\_\+delay\+\_\+cycles() support, maximal possible delay is 4294967.\+295 us/ F\+\_\+\+C\+PU in M\+Hz. For values greater than the maximal possible delay, overflow results in no delay i.\+e., 0us.

Conversion of {\ttfamily \+\_\+\+\_\+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 at least {\ttfamily \+\_\+\+\_\+us} microseconds of delay.

Alternatively, by defining the macro {\ttfamily \+\_\+\+\_\+\+D\+E\+L\+A\+Y\+\_\+\+R\+O\+U\+N\+D\+\_\+\+D\+O\+W\+N\+\_\+\+\_\+}, or {\ttfamily \+\_\+\+\_\+\+D\+E\+L\+A\+Y\+\_\+\+R\+O\+U\+N\+D\+\_\+\+C\+L\+O\+S\+E\+S\+T\+\_\+\+\_\+}, before including this header file, the algorithm can be made to round down, or round to closest integer, respectively.

\begin{DoxyNote}{Note}

\end{DoxyNote}
The implementation of \mbox{\hyperlink{group__util__delay_gad22e7a36b80e2f917324dc43a425e9d3}{\+\_\+delay\+\_\+ms()}} based on \+\_\+\+\_\+builtin\+\_\+avr\+\_\+delay\+\_\+cycles() is not backward compatible with older implementations. In order to get functionality backward compatible with previous versions, the macro {\ttfamily \+\_\+\+\_\+\+D\+E\+L\+A\+Y\+\_\+\+B\+A\+C\+K\+W\+A\+R\+D\+\_\+\+C\+O\+M\+P\+A\+T\+I\+B\+L\+E\+\_\+\+\_\+} must be defined before including this header file. Also, the backward compatible algorithm will be chosen if the code is compiled in a {\itshape freestanding environment} (G\+CC option {\ttfamily -\/ffreestanding}), as the math functions required for rounding are not available to the compiler then. 