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 // configuration
    00045 // defining RPRINTF_SIMPLE will compile a smaller, simpler, and faster printf() function
    00046 // defining RPRINTF_COMPLEX will compile a larger, more capable, and slower printf() function
    00047 #ifndef RPRINTF_COMPLEX
    00048     #define RPRINTF_SIMPLE
    00049 #endif
    00050
    00051 // Define RPRINTF_FLOAT to enable the floating-point printf function: rprintfFloat()
    00052 // (adds +4600bytes or 2.2Kwords of code)
    00053
    00054 // defines/constants
    00055 #define STRING_IN_RAM   0
    00056 #define STRING_IN_ROM   1
    00057
    00058 // make a putchar for those that are used to using it
    00059 //#define putchar(c)    rprintfChar(c);
    00060
    00061 // functions
    00062
    00063 //! initializes the rprintf library for an output stream
    00064 // you must call this initializer once before using any other rprintf function
    00065 // the argument must be a single-character stream output function
    00066 void rprintfInit(void (*putchar_func)(unsigned char c));
    00067
    00068 //! prints a single character to the current output device
    00069 void rprintfChar(unsigned char c);
    00070
    00071 //! prints a null-terminated string stored in RAM
    00072 void rprintfStr(char str[]);
    00073
    00074 //! prints a section of a string stored in RAM
    00075 // begins printing at position indicated by <start>
    00076 // prints number of characters indicated by <len>
    00077 void rprintfStrLen(char str[], unsigned char start, unsigned char len);
    00078
    00079 //! prints a string stored in program rom
    00080 // NOTE: this function does not actually store your string in
    00081 // program rom, but merely reads it assuming you stored it properly.
    00082 void rprintfProgStr(char str[]);
    00083 // Using the function rprintfProgStrM(...) automatically causes
    00084 // your string to be stored in ROM, thereby not wasting precious RAM
    00085 // Example usage:
    00086 // rprintfProgStrM("Hello, this string is stored in program rom");
    00087 //#define rprintfProgStrM(string)           (rprintfProgStr(PSTR(string)))
    00088 #define rprintfProgStrM(string)         (rprintfStr(string))
    00089
    00090 //! prints a carriage return and line feed
    00091 // useful when printing to serial ports/terminals
    00092 void rprintfCRLF(void);
    00093
    00094 // prints the number contained in "data" in hex format
    00095 // u04,u08,u16,and u32 functions handle 4,8,16,or 32 bits respectively
    00096 void rprintfu04(unsigned char data);    ///< print 4-bit hex number
    00097 void rprintfu08(unsigned char data);    ///< print 8-bit hex number
    00098 void rprintfu16(unsigned short data);   ///< print 16-bit hex number
    00099 void rprintfu32(unsigned long data);    ///< print 32-bit hex number
    00100
    00101 //! a flexible integer number printing routine
    00102 void rprintfNum(char base, char numDigits, char isSigned, char padchar, long n);
    00103
    00104 #ifdef RPRINTF_FLOAT
    00105     //! floating-point print routine
    00106     void rprintfFloat(char numDigits, double x);
    00107 #endif
    00108
    00109 // NOTE: Below you'll see the function prototypes of rprintf1RamRom and
    00110 // rprintf2RamRom.  rprintf1RamRom and rprintf2RamRom are both reduced versions
    00111 // of the regular C printf() command.  However, they are modified to be able
    00112 // to read their text/format strings from RAM or ROM in the Atmel microprocessors.
    00113 // Unless you really intend to, do not use the "RamRom" versions of the functions
    00114 // directly.  Instead use the #defined function versions:
    00115 //
    00116 // printfx("text/format",args)    ...to keep your text/format string stored in RAM
    00117 //      - or -
    00118 // printfxROM("text/format",args) ...to keep your text/format string stored in ROM
    00119 //
    00120 // where x is either 1 or 2 for the simple or more powerful version of printf()
    00121 //
    00122 // Since there is much more ROM than RAM available in the Atmel microprocessors,
    00123 // and nearly all text/format strings are constant (never change in the course
    00124 // of the program), you should try to use the ROM printf version exclusively.
    00125 // This will ensure you leave as much RAM as possible for program variables and
    00126 // data.
    00127
    00128 #ifdef RPRINTF_SIMPLE
    00129     // a simple printf routine
    00130     int rprintf1RamRom(unsigned char stringInRom, const char *format, ...);
    00131     // #defines for RAM or ROM operation
    00132     #define rprintf1(format, args...)       rprintf1RamRom(STRING_IN_ROM, PSTR(format), ## args)
    00133     #define rprintf1RAM(format, args...)    rprintf1RamRom(STRING_IN_RAM, format, ## args)
    00134
    00135     // *** Default rprintf(...) ***
    00136     // this next line determines what the the basic rprintf() defaults to:
    00137     #define rprintf(format, args...)        rprintf1RamRom(STRING_IN_RAM, format, ## args)
    00138 #endif
    00139
    00140 #ifdef RPRINTF_COMPLEX
    00141     // a more powerful printf routine
    00142     int rprintf2RamRom(unsigned char stringInRom, const char *sfmt, ...);
    00143     // #defines for RAM or ROM operation
    00144     #define rprintf2(format, args...)       rprintf2RamRom(STRING_IN_ROM, format, ## args)
    00145     #define rprintf2RAM(format, args...)    rprintf2RamRom(STRING_IN_RAM, format, ## args)
    00146
    00147     // *** Default rprintf(...) ***
    00148     // this next line determines what the the basic rprintf() defaults to:
    00149     #define rprintf(format, args...)        rprintf2RamRom(STRING_IN_RAM, format, ## args)
    00150 #endif
    00151
    00152 #endif
    00153 //@}