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