Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

rprintf.h

Go to the documentation of this file.
00001 /*! \file rprintf.h \brief printf routine and associated routines. */
00002 //****************************************************************************
00003 //
00004 // File Name    : 'rprintf.h'
00005 // Title        : printf routine and associated routines
00006 // Author       : Pascal Stang - Copyright (C) 2000-2002
00007 // Created      : 2000.12.26
00008 // Revised      : 2003.5.1
00009 // Version      : 1.0
00010 // Target MCU   : Atmel AVR series and other targets
00011 // Editor Tabs  : 4
00012 //
00013 // NOTE: This code is currently below version 1.0, and therefore is considered
00014 // to be lacking in some functionality or documentation, or may not be fully
00015 // tested.  Nonetheless, you can expect most functions to work.
00016 //
00017 // This code is distributed under the GNU Public License
00018 //      which can be found at http://www.gnu.org/licenses/gpl.txt
00019 //
00020 /// \ingroup general
00021 /// \defgroup rprintf printf() Function Library (rprintf.c)
00022 /// \code #include "rprintf.h" \endcode
00023 /// \par Overview
00024 ///     The rprintf function library provides a simplified (reduced) version of
00025 ///     the common C printf() function.  See the code files for details about
00026 ///     which printf features are supported.  Also in this library are a
00027 ///     variety of functions for fast printing of certain common data types
00028 ///     (variable types).  Functions include print string from RAM, print
00029 ///     string from ROM, print string snippet, print hex byte/short/long, and
00030 ///     a custom-formatted number print, as well as an optional floating-point
00031 ///     print routine.
00032 ///
00033 /// \note   All output from the rprintf library can be directed to any device
00034 ///     or software which accepts characters.  This means that rprintf output
00035 ///     can be sent to the UART (serial port) or can be used with the LCD
00036 ///     display libraries to print formatted text on the screen.
00037 //
00038 //****************************************************************************
00039 //@{
00040 
00041 #ifndef RPRINTF_H
00042 #define RPRINTF_H
00043 
00044 // needed for use of PSTR below
00045 #include <avr/pgmspace.h>
00046 
00047 // configuration
00048 // defining RPRINTF_SIMPLE will compile a smaller, simpler, and faster printf() function
00049 // defining RPRINTF_COMPLEX will compile a larger, more capable, and slower printf() function
00050 #ifndef RPRINTF_COMPLEX
00051     #define RPRINTF_SIMPLE
00052 #endif
00053 
00054 // Define RPRINTF_FLOAT to enable the floating-point printf function: rprintfFloat()
00055 // (adds +4600bytes or 2.2Kwords of code)
00056 
00057 // defines/constants
00058 #define STRING_IN_RAM   0
00059 #define STRING_IN_ROM   1
00060 
00061 // make a putchar for those that are used to using it
00062 //#define putchar(c)    rprintfChar(c);
00063 
00064 // functions
00065 
00066 //! Initializes the rprintf library for an output stream.
00067 /// You must call this initializer once before using any other rprintf function.
00068 /// The argument must be a character stream output function.
00069 void rprintfInit(void (*putchar_func)(unsigned char c));
00070 
00071 //! prints a single character to the current output device
00072 void rprintfChar(unsigned char c);
00073 
00074 //! prints a null-terminated string stored in RAM
00075 void rprintfStr(char str[]);
00076 
00077 //! Prints a section of a string stored in RAM.
00078 /// Begins printing at position indicated by <start>,
00079 /// and prints number of characters indicated by <len>.
00080 void rprintfStrLen(char str[], unsigned int start, unsigned int len);
00081 
00082 //! prints a string stored in program rom
00083 /// \note This function does not actually store your string in
00084 /// program rom, but merely reads it assuming you stored it properly.
00085 void rprintfProgStr(const prog_char str[]);
00086 
00087 //! Using the function rprintfProgStrM(...) automatically causes 
00088 /// your string to be stored in ROM, thereby not wasting precious RAM.
00089 /// Example usage:
00090 /// \code
00091 /// rprintfProgStrM("Hello, this string is stored in program rom");
00092 /// \endcode
00093 #define rprintfProgStrM(string)         (rprintfProgStr(PSTR(string)))
00094 
00095 //! Prints a carriage-return and line-feed.
00096 /// Useful when printing to serial ports/terminals.
00097 void rprintfCRLF(void);
00098 
00099 // Prints the number contained in "data" in hex format
00100 // u04,u08,u16,and u32 functions handle 4,8,16,or 32 bits respectively
00101 void rprintfu04(unsigned char data);    ///< Print 4-bit hex number. Outputs a single hex character.
00102 void rprintfu08(unsigned char data);    ///< Print 8-bit hex number. Outputs two hex characters.
00103 void rprintfu16(unsigned short data);   ///< Print 16-bit hex number. Outputs four hex characters.
00104 void rprintfu32(unsigned long data);    ///< Print 32-bit hex number. Outputs eight hex characters.
00105 
00106 //! A flexible integer-number printing routine.
00107 /// Print the number "n" in the given "base", using exactly "numDigits".
00108 /// Print +/- if signed flag "isSigned" is TRUE.
00109 /// The character specified in "padchar" will be used to pad extra characters.
00110 ///
00111 /// Examples:
00112 /// \code
00113 /// uartPrintfNum(10, 6,  TRUE, ' ',   1234);  -->  " +1234"
00114 /// uartPrintfNum(10, 6, FALSE, '0',   1234);  -->  "001234"
00115 /// uartPrintfNum(16, 6, FALSE, '.', 0x5AA5);  -->  "..5AA5"
00116 /// \endcode
00117 void rprintfNum(char base, char numDigits, char isSigned, char padchar, long n);
00118 
00119 #ifdef RPRINTF_FLOAT
00120     //! floating-point print routine
00121     void rprintfFloat(char numDigits, double x);
00122 #endif
00123 
00124 // NOTE: Below you'll see the function prototypes of rprintf1RamRom and 
00125 // rprintf2RamRom.  rprintf1RamRom and rprintf2RamRom are both reduced versions
00126 // of the regular C printf() command.  However, they are modified to be able
00127 // to read their text/format strings from RAM or ROM in the Atmel microprocessors.
00128 // Unless you really intend to, do not use the "RamRom" versions of the functions
00129 // directly.  Instead use the #defined function versions:
00130 //
00131 // printfx("text/format",args)    ...to keep your text/format string stored in RAM
00132 //      - or -
00133 // printfxROM("text/format",args) ...to keep your text/format string stored in ROM
00134 //
00135 // where x is either 1 or 2 for the simple or more powerful version of printf()
00136 //
00137 // Since there is much more ROM than RAM available in the Atmel microprocessors,
00138 // and nearly all text/format strings are constant (never change in the course
00139 // of the program), you should try to use the ROM printf version exclusively.
00140 // This will ensure you leave as much RAM as possible for program variables and
00141 // data.
00142 
00143 //! \fn int rprintf(const char *format, ...);
00144 /// A reduced substitute for the usual C printf() function.
00145 /// This function actually points to either rprintf1RamRom or rprintf2RamRom
00146 /// depending on the user's selection.  Rprintf1 is a simple small fast print
00147 /// routine while rprintf2 is larger and slower but more capable. To choose
00148 /// the routine you would like to use, define either RPRINTF_SIMPLE or
00149 /// RPRINTF_COMPLEX in global.h.
00150 
00151 #ifdef RPRINTF_SIMPLE
00152     //! A simple printf routine.
00153     /// Called by rprintf() - does a simple printf (supports %d, %x, %c).
00154     /// Supports:
00155     /// - %d - decimal
00156     /// - %x - hex
00157     /// - %c - character
00158     int rprintf1RamRom(unsigned char stringInRom, const char *format, ...);
00159     // #defines for RAM or ROM operation
00160     #define rprintf1(format, args...)       rprintf1RamRom(STRING_IN_ROM, PSTR(format), ## args)
00161     #define rprintf1RAM(format, args...)    rprintf1RamRom(STRING_IN_RAM, format, ## args)
00162 
00163     // *** Default rprintf(...) ***
00164     // this next line determines what the the basic rprintf() defaults to:
00165     #define rprintf(format, args...)        rprintf1RamRom(STRING_IN_ROM, PSTR(format), ## args)
00166 #endif
00167 
00168 #ifdef RPRINTF_COMPLEX
00169     //! A more powerful printf routine.
00170     /// Called by rprintf() - does a more powerful printf (supports %d, %u, %o, %x, %c, %s).
00171     /// Supports:
00172     /// - %d - decimal
00173     /// - %u - unsigned decimal
00174     /// - %o - octal
00175     /// - %x - hex
00176     /// - %c - character
00177     /// - %s - strings
00178     /// - and the width,precision,padding modifiers
00179     /// \note This printf does not support floating point numbers.
00180     int rprintf2RamRom(unsigned char stringInRom, const char *sfmt, ...);
00181     // #defines for RAM or ROM operation
00182     #define rprintf2(format, args...)       rprintf2RamRom(STRING_IN_ROM, format, ## args)
00183     #define rprintf2RAM(format, args...)    rprintf2RamRom(STRING_IN_RAM, format, ## args)
00184 
00185     // *** Default rprintf(...) ***
00186     // this next line determines what the the basic rprintf() defaults to:
00187     #define rprintf(format, args...)        rprintf2RamRom(STRING_IN_ROM, PSTR(format), ## args)
00188 #endif
00189 
00190 #endif
00191 //@}

Generated on Sun Oct 29 03:41:07 2006 for Procyon AVRlib by  doxygen 1.4.2