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.
96 lines
6.0 KiB
Groff
96 lines
6.0 KiB
Groff
4 years ago
|
.TH "<util/delay.h>: Convenience functions for busy-wait delay loops" 3 "24 Jun 2019" "Version 2.0.0" "avr-libc" \" -*- nroff -*-
|
||
|
|
.ad l
|
||
|
|
.nh
|
||
|
|
.SH NAME
|
||
|
|
<util/delay.h>: Convenience functions for busy-wait delay loops \-
|
||
|
|
.SS "Defines"
|
||
|
|
|
||
|
|
.in +1c
|
||
|
|
.ti -1c
|
||
|
|
.RI "#define \fBF_CPU\fP 1000000UL"
|
||
|
|
.br
|
||
|
|
.in -1c
|
||
|
|
.SS "Functions"
|
||
|
|
|
||
|
|
.in +1c
|
||
|
|
.ti -1c
|
||
|
|
.RI "void \fB_delay_ms\fP (double __ms)"
|
||
|
|
.br
|
||
|
|
.ti -1c
|
||
|
|
.RI "void \fB_delay_us\fP (double __us)"
|
||
|
|
.br
|
||
|
|
.in -1c
|
||
|
|
.SH "Detailed Description"
|
||
|
|
.PP
|
||
|
|
.PP
|
||
|
|
.nf
|
||
|
|
#define F_CPU 1000000UL // 1 MHz
|
||
|
|
//#define F_CPU 14.7456E6
|
||
|
|
#include <util/delay.h>
|
||
|
|
.fi
|
||
|
|
.PP
|
||
|
|
.PP
|
||
|
|
\fBNote:\fP
|
||
|
|
.RS 4
|
||
|
|
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 \fC#define\fP statement should be used.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
The functions in this header file are wrappers around the basic busy-wait functions from <\fButil/delay_basic.h\fP>. 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.
|
||
|
|
.PP
|
||
|
|
\fBNote:\fP
|
||
|
|
.RS 4
|
||
|
|
In order for these functions to work as intended, compiler optimizations \fImust\fP be enabled, and the delay time \fImust\fP 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.
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
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).
|
||
|
|
.SH "Define Documentation"
|
||
|
|
.PP
|
||
|
|
.SS "#define F_CPU 1000000UL"
|
||
|
|
.PP
|
||
|
|
CPU frequency in Hz. The macro F_CPU specifies the CPU 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's Makefile). The value 1 MHz here is only provided as a 'vanilla' fallback if no such user-provided definition could be found.
|
||
|
|
.PP
|
||
|
|
In terms of the delay functions, the CPU frequency can be given as a floating-point constant (e.g. 3.6864E6 for 3.6864 MHz). However, the macros in <\fButil/setbaud.h\fP> require it to be an integer value.
|
||
|
|
.SH "Function Documentation"
|
||
|
|
.PP
|
||
|
|
.SS "void _delay_ms (double __ms)"Perform a delay of \fC__ms\fP milliseconds, using \fB_delay_loop_2()\fP.
|
||
|
|
.PP
|
||
|
|
The macro F_CPU is supposed to be defined to a constant defining the CPU clock frequency (in Hertz).
|
||
|
|
.PP
|
||
|
|
The maximal possible delay is 262.14 ms / F_CPU in MHz.
|
||
|
|
.PP
|
||
|
|
When the user request delay which exceed the maximum possible one, \fB_delay_ms()\fP provides a decreased resolution functionality. In this mode \fB_delay_ms()\fP 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.
|
||
|
|
.PP
|
||
|
|
If the avr-gcc toolchain has __builtin_avr_delay_cycles() 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.
|
||
|
|
.PP
|
||
|
|
Conversion of \fC__ms\fP 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 \fC__ms\fP microseconds of delay.
|
||
|
|
.PP
|
||
|
|
Alternatively, by defining the macro \fC__DELAY_ROUND_DOWN__\fP, or \fC__DELAY_ROUND_CLOSEST__\fP, before including this header file, the algorithm can be made to round down, or round to closest integer, respectively.
|
||
|
|
.PP
|
||
|
|
\fBNote:\fP
|
||
|
|
.RS 4
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
The implementation of \fB_delay_ms()\fP 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 \fC'__DELAY_BACKWARD_COMPATIBLE__'\fP must be defined before including this header file. Also, the backward compatible algorithm will be chosen if the code is compiled in a \fIfreestanding environment\fP (GCC option \fC-ffreestanding\fP), as the math functions required for rounding are not available to the compiler then.
|
||
|
|
.SS "void _delay_us (double __us)"Perform a delay of \fC__us\fP microseconds, using \fB_delay_loop_1()\fP.
|
||
|
|
.PP
|
||
|
|
The macro F_CPU is supposed to be defined to a constant defining the CPU clock frequency (in Hertz).
|
||
|
|
.PP
|
||
|
|
The maximal possible delay is 768 us / F_CPU in MHz.
|
||
|
|
.PP
|
||
|
|
If the user requests a delay greater than the maximal possible one, \fB_delay_us()\fP will automatically call \fB_delay_ms()\fP instead. The user will not be informed about this case.
|
||
|
|
.PP
|
||
|
|
If the avr-gcc toolchain has __builtin_avr_delay_cycles() 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.
|
||
|
|
.PP
|
||
|
|
Conversion of \fC__us\fP 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 \fC__us\fP microseconds of delay.
|
||
|
|
.PP
|
||
|
|
Alternatively, by defining the macro \fC__DELAY_ROUND_DOWN__\fP, or \fC__DELAY_ROUND_CLOSEST__\fP, before including this header file, the algorithm can be made to round down, or round to closest integer, respectively.
|
||
|
|
.PP
|
||
|
|
\fBNote:\fP
|
||
|
|
.RS 4
|
||
|
|
.RE
|
||
|
|
.PP
|
||
|
|
The implementation of \fB_delay_ms()\fP 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 \fC__DELAY_BACKWARD_COMPATIBLE__\fP must be defined before including this header file. Also, the backward compatible algorithm will be chosen if the code is compiled in a \fIfreestanding environment\fP (GCC option \fC-ffreestanding\fP), as the math functions required for rounding are not available to the compiler then.
|
||
|
|
.SH "Author"
|
||
|
|
.PP
|
||
|
|
Generated automatically by Doxygen for avr-libc from the source code.
|