AVR Libc Home Page AVRs AVR Libc Development Pages
Main Page User Manual Library Reference FAQ Alphabetical Index Example Projects

setbaud.h

Go to the documentation of this file.
00001 /* Copyright (c) 2007  Cliff Lawson
00002    Copyright (c) 2007  Carlos Lamas
00003    All rights reserved.
00004 
00005    Redistribution and use in source and binary forms, with or without
00006    modification, are permitted provided that the following conditions are met:
00007 
00008    * Redistributions of source code must retain the above copyright
00009      notice, this list of conditions and the following disclaimer.
00010 
00011    * Redistributions in binary form must reproduce the above copyright
00012      notice, this list of conditions and the following disclaimer in
00013      the documentation and/or other materials provided with the
00014      distribution.
00015 
00016    * Neither the name of the copyright holders nor the names of
00017      contributors may be used to endorse or promote products derived
00018      from this software without specific prior written permission.
00019 
00020   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00021   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00022   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00023   ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00024   LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00025   CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00026   SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00027   INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00028   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00029   ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00030   POSSIBILITY OF SUCH DAMAGE. */
00031 
00032 /* $Id: setbaud.h 2134 2010-06-08 11:19:48Z joerg_wunsch $ */
00033 
00034 /**
00035    \file
00036 */
00037 
00038 /**
00039    \defgroup util_setbaud <util/setbaud.h>: Helper macros for baud rate calculations
00040    \code
00041    #define F_CPU 11059200
00042    #define BAUD 38400
00043    #include <util/setbaud.h>
00044    \endcode
00045 
00046    This header file requires that on entry values are already defined
00047    for F_CPU and BAUD.  In addition, the macro BAUD_TOL will define
00048    the baud rate tolerance (in percent) that is acceptable during
00049    the calculations.  The value of BAUD_TOL will default to 2 %.
00050 
00051    This header file defines macros suitable to setup the UART baud
00052    rate prescaler registers of an AVR.  All calculations are done
00053    using the C preprocessor.  Including this header file causes no
00054    other side effects so it is possible to include this file more than
00055    once (supposedly, with different values for the BAUD parameter),
00056    possibly even within the same function.
00057 
00058    Assuming that the requested BAUD is valid for the given F_CPU then
00059    the macro UBRR_VALUE is set to the required prescaler value.  Two
00060    additional macros are provided for the low and high bytes of the
00061    prescaler, respectively: UBRRL_VALUE is set to the lower byte of
00062    the UBRR_VALUE and UBRRH_VALUE is set to the upper byte.  An
00063    additional macro USE_2X will be defined.  Its value is set to 1 if
00064    the desired BAUD rate within the given tolerance could only be
00065    achieved by setting the U2X bit in the UART configuration.  It will
00066    be defined to 0 if U2X is not needed.
00067 
00068    Example usage:
00069 
00070    \code
00071    #include <avr/io.h>
00072 
00073    #define F_CPU 4000000
00074 
00075    static void
00076    uart_9600(void)
00077    {
00078    #define BAUD 9600
00079    #include <util/setbaud.h>
00080    UBRRH = UBRRH_VALUE;
00081    UBRRL = UBRRL_VALUE;
00082    #if USE_2X
00083    UCSRA |= (1 << U2X);
00084    #else
00085    UCSRA &= ~(1 << U2X);
00086    #endif
00087    }
00088 
00089    static void
00090    uart_38400(void)
00091    {
00092    #undef BAUD  // avoid compiler warning
00093    #define BAUD 38400
00094    #include <util/setbaud.h>
00095    UBRRH = UBRRH_VALUE;
00096    UBRRL = UBRRL_VALUE;
00097    #if USE_2X
00098    UCSRA |= (1 << U2X);
00099    #else
00100    UCSRA &= ~(1 << U2X);
00101    #endif
00102    }
00103    \endcode
00104 
00105    In this example, two functions are defined to setup the UART
00106    to run at 9600 Bd, and 38400 Bd, respectively.  Using a CPU
00107    clock of 4 MHz, 9600 Bd can be achieved with an acceptable
00108    tolerance without setting U2X (prescaler 25), while 38400 Bd
00109    require U2X to be set (prescaler 12).
00110 */
00111 
00112 #ifndef F_CPU
00113 #  error "setbaud.h requires F_CPU to be defined"
00114 #endif
00115 
00116 #ifndef BAUD
00117 #  error "setbaud.h requires BAUD to be defined"
00118 #endif
00119 
00120 #if !(F_CPU)
00121 #  error "F_CPU must be a constant value"
00122 #endif
00123 
00124 #if !(BAUD)
00125 #  error "BAUD must be a constant value"
00126 #endif
00127 
00128 #if defined(__DOXYGEN__)
00129 /**
00130    \def BAUD_TOL
00131    \ingroup util_setbaud
00132 
00133    Input and output macro for <util/setbaud.h>
00134 
00135    Define the acceptable baud rate tolerance in percent.  If not set
00136    on entry, it will be set to its default value of 2.
00137 */
00138 #define BAUD_TOL 2
00139 
00140 /**
00141    \def UBRR_VALUE
00142    \ingroup util_setbaud
00143 
00144    Output macro from <util/setbaud.h>
00145 
00146    Contains the calculated baud rate prescaler value for the UBRR
00147    register.
00148 */
00149 #define UBRR_VALUE
00150 
00151 /**
00152    \def UBRRL_VALUE
00153    \ingroup util_setbaud
00154 
00155    Output macro from <util/setbaud.h>
00156 
00157    Contains the lower byte of the calculated prescaler value
00158    (UBRR_VALUE).
00159 */
00160 #define UBRRL_VALUE
00161 
00162 /**
00163    \def UBRRH_VALUE
00164    \ingroup util_setbaud
00165 
00166    Output macro from <util/setbaud.h>
00167 
00168    Contains the upper byte of the calculated prescaler value
00169    (UBRR_VALUE).
00170 */
00171 #define UBRRH_VALUE
00172 
00173 /**
00174    \def USE_2X
00175    \ingroup util_setbaud
00176 
00177    Output bacro from <util/setbaud.h>
00178 
00179    Contains the value 1 if the desired baud rate tolerance could only
00180    be achieved by setting the U2X bit in the UART configuration.
00181    Contains 0 otherwise.
00182 */
00183 #define USE_2X 0
00184 
00185 #else /* !__DOXYGEN__ */
00186 
00187 #undef USE_2X
00188 
00189 /* Baud rate tolerance is 2 % unless previously defined */
00190 #ifndef BAUD_TOL
00191 #  define BAUD_TOL 2
00192 #endif
00193 
00194 #ifdef __ASSEMBLER__
00195 #define UBRR_VALUE (((F_CPU) + 8 * (BAUD)) / (16 * (BAUD)) -1)
00196 #else
00197 #define UBRR_VALUE (((F_CPU) + 8UL * (BAUD)) / (16UL * (BAUD)) -1UL)
00198 #endif
00199 
00200 #if 100 * (F_CPU) > \
00201   (16 * ((UBRR_VALUE) + 1)) * (100 * (BAUD) + (BAUD) * (BAUD_TOL))
00202 #  define USE_2X 1
00203 #elif 100 * (F_CPU) < \
00204   (16 * ((UBRR_VALUE) + 1)) * (100 * (BAUD) - (BAUD) * (BAUD_TOL))
00205 #  define USE_2X 1
00206 #else
00207 #  define USE_2X 0
00208 #endif
00209 
00210 #if USE_2X
00211 /* U2X required, recalculate */
00212 #undef UBRR_VALUE
00213 
00214 #ifdef __ASSEMBLER__
00215 #define UBRR_VALUE (((F_CPU) + 4 * (BAUD)) / (8 * (BAUD)) -1)
00216 #else
00217 #define UBRR_VALUE (((F_CPU) + 4UL * (BAUD)) / (8UL * (BAUD)) -1UL)
00218 #endif
00219 
00220 #if 100 * (F_CPU) > \
00221   (8 * ((UBRR_VALUE) + 1)) * (100 * (BAUD) + (BAUD) * (BAUD_TOL))
00222 #  warning "Baud rate achieved is higher than allowed"
00223 #endif
00224 
00225 #if 100 * (F_CPU) < \
00226   (8 * ((UBRR_VALUE) + 1)) * (100 * (BAUD) - (BAUD) * (BAUD_TOL))
00227 #  warning "Baud rate achieved is lower than allowed"
00228 #endif
00229 
00230 #endif /* USE_U2X */
00231 
00232 #ifdef UBRR_VALUE
00233 #  define UBRRL_VALUE (UBRR_VALUE & 0xff)
00234 #  define UBRRH_VALUE (UBRR_VALUE >> 8)
00235 #endif
00236 
00237 #endif /* __DOXYGEN__ */
00238 /* end of util/setbaud.h */

Automatically generated by Doxygen 1.7.3 on Thu May 19 2011.