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 //@}