Rev Author Line No. Line
1269 kakl 1 /*! \file rprintf.h \brief printf routine and associated routines. */
2 //****************************************************************************
3 //
4 // File Name : 'rprintf.h'
5 // Title : printf routine and associated routines
6 // Author : Pascal Stang - Copyright (C) 2000-2002
7 // Created : 2000.12.26
8 // Revised : 2003.5.1
9 // Version : 1.0
10 // Target MCU : Atmel AVR series and other targets
11 // Editor Tabs : 4
12 //
13 // NOTE: This code is currently below version 1.0, and therefore is considered
14 // to be lacking in some functionality or documentation, or may not be fully
15 // tested. Nonetheless, you can expect most functions to work.
16 //
17 // This code is distributed under the GNU Public License
18 // which can be found at http://www.gnu.org/licenses/gpl.txt
19 //
20 /// \ingroup general
21 /// \defgroup rprintf printf() Function Library (rprintf.c)
22 /// \code #include "rprintf.h" \endcode
23 /// \par Overview
24 /// The rprintf function library provides a simplified (reduced) version of
25 /// the common C printf() function.  See the code files for details about
26 /// which printf features are supported.  Also in this library are a
27 /// variety of functions for fast printing of certain common data types
28 /// (variable types).  Functions include print string from RAM, print
29 /// string from ROM, print string snippet, print hex byte/short/long, and
30 /// a custom-formatted number print, as well as an optional floating-point
31 /// print routine.
32 ///
33 /// \note All output from the rprintf library can be directed to any device
34 /// or software which accepts characters.  This means that rprintf output
35 /// can be sent to the UART (serial port) or can be used with the LCD
36 /// display libraries to print formatted text on the screen.
37 //
38 //****************************************************************************
39 //@{
40  
41 #ifndef RPRINTF_H
42 #define RPRINTF_H
43  
44 // needed for use of PSTR below
45 #include <avr/pgmspace.h>
46  
47 // configuration
48 // defining RPRINTF_SIMPLE will compile a smaller, simpler, and faster printf() function
49 // defining RPRINTF_COMPLEX will compile a larger, more capable, and slower printf() function
50 #ifndef RPRINTF_COMPLEX
51 #define RPRINTF_SIMPLE
52 #endif
53  
54 // Define RPRINTF_FLOAT to enable the floating-point printf function: rprintfFloat()
55 // (adds +4600bytes or 2.2Kwords of code)
56  
57 // defines/constants
58 #define STRING_IN_RAM 0
59 #define STRING_IN_ROM 1
60  
61 // make a putchar for those that are used to using it
62 //#define putchar(c) rprintfChar(c);
63  
64 // functions
65  
66 //! Initializes the rprintf library for an output stream.
67 /// You must call this initializer once before using any other rprintf function.
68 /// The argument must be a character stream output function.
69 void rprintfInit(void (*putchar_func)(unsigned char c));
70  
71 //! prints a single character to the current output device
72 void rprintfChar(unsigned char c);
73  
74 //! prints a null-terminated string stored in RAM
75 void rprintfStr(char str[]);
76  
77 //! Prints a section of a string stored in RAM.
78 /// Begins printing at position indicated by <start>,
79 /// and prints number of characters indicated by <len>.
80 void rprintfStrLen(char str[], unsigned int start, unsigned int len);
81  
82 //! prints a string stored in program rom
83 /// \note This function does not actually store your string in
84 /// program rom, but merely reads it assuming you stored it properly.
85 void rprintfProgStr(const prog_char str[]);
86  
87 //! Using the function rprintfProgStrM(...) automatically causes
88 /// your string to be stored in ROM, thereby not wasting precious RAM.
89 /// Example usage:
90 /// \code
91 /// rprintfProgStrM("Hello, this string is stored in program rom");
92 /// \endcode
93 #define rprintfProgStrM(string) (rprintfProgStr(PSTR(string)))
94  
95 //! Prints a carriage-return and line-feed.
96 /// Useful when printing to serial ports/terminals.
97 void rprintfCRLF(void);
98  
99 // Prints the number contained in "data" in hex format
100 // u04,u08,u16,and u32 functions handle 4,8,16,or 32 bits respectively
101 void rprintfu04(unsigned char data); ///< Print 4-bit hex number. Outputs a single hex character.
102 void rprintfu08(unsigned char data); ///< Print 8-bit hex number. Outputs two hex characters.
103 void rprintfu16(unsigned short data); ///< Print 16-bit hex number. Outputs four hex characters.
104 void rprintfu32(unsigned long data); ///< Print 32-bit hex number. Outputs eight hex characters.
105  
106 //! A flexible integer-number printing routine.
107 /// Print the number "n" in the given "base", using exactly "numDigits".
108 /// Print +/- if signed flag "isSigned" is TRUE.
109 /// The character specified in "padchar" will be used to pad extra characters.
110 ///
111 /// Examples:
112 /// \code
113 /// uartPrintfNum(10, 6, TRUE, ' ', 1234); --> " +1234"
114 /// uartPrintfNum(10, 6, FALSE, '0', 1234); --> "001234"
115 /// uartPrintfNum(16, 6, FALSE, '.', 0x5AA5); --> "..5AA5"
116 /// \endcode
117 void rprintfNum(char base, char numDigits, char isSigned, char padchar, long n);
118  
119 #ifdef RPRINTF_FLOAT
120 //! floating-point print routine
121 void rprintfFloat(char numDigits, double x);
122 #endif
123  
124 void rprintfFloatMy(char numDigits, double x);
125  
126 // NOTE: Below you'll see the function prototypes of rprintf1RamRom and
127 // rprintf2RamRom. rprintf1RamRom and rprintf2RamRom are both reduced versions
128 // of the regular C printf() command. However, they are modified to be able
129 // to read their text/format strings from RAM or ROM in the Atmel microprocessors.
130 // Unless you really intend to, do not use the "RamRom" versions of the functions
131 // directly. Instead use the #defined function versions:
132 //
133 // printfx("text/format",args) ...to keep your text/format string stored in RAM
134 // - or -
135 // printfxROM("text/format",args) ...to keep your text/format string stored in ROM
136 //
137 // where x is either 1 or 2 for the simple or more powerful version of printf()
138 //
139 // Since there is much more ROM than RAM available in the Atmel microprocessors,
140 // and nearly all text/format strings are constant (never change in the course
141 // of the program), you should try to use the ROM printf version exclusively.
142 // This will ensure you leave as much RAM as possible for program variables and
143 // data.
144  
145 //! \fn int rprintf(const char *format, ...);
146 /// A reduced substitute for the usual C printf() function.
147 /// This function actually points to either rprintf1RamRom or rprintf2RamRom
148 /// depending on the user's selection. Rprintf1 is a simple small fast print
149 /// routine while rprintf2 is larger and slower but more capable. To choose
150 /// the routine you would like to use, define either RPRINTF_SIMPLE or
151 /// RPRINTF_COMPLEX in global.h.
152  
153 #ifdef RPRINTF_SIMPLE
154 //! A simple printf routine.
155 /// Called by rprintf() - does a simple printf (supports %d, %x, %c).
156 /// Supports:
157 /// - %d - decimal
158 /// - %x - hex
159 /// - %c - character
160 int rprintf1RamRom(unsigned char stringInRom, const char *format, ...);
161 // #defines for RAM or ROM operation
162 #define rprintf1(format, args...) rprintf1RamRom(STRING_IN_ROM, PSTR(format), ## args)
163 #define rprintf1RAM(format, args...) rprintf1RamRom(STRING_IN_RAM, format, ## args)
164  
165 // *** Default rprintf(...) ***
166 // this next line determines what the the basic rprintf() defaults to:
167 #define rprintf(format, args...) rprintf1RamRom(STRING_IN_ROM, PSTR(format), ## args)
168 #endif
169  
170 #ifdef RPRINTF_COMPLEX
171 //! A more powerful printf routine.
172 /// Called by rprintf() - does a more powerful printf (supports %d, %u, %o, %x, %c, %s).
173 /// Supports:
174 /// - %d - decimal
175 /// - %u - unsigned decimal
176 /// - %o - octal
177 /// - %x - hex
178 /// - %c - character
179 /// - %s - strings
180 /// - and the width,precision,padding modifiers
181 /// \note This printf does not support floating point numbers.
182 int rprintf2RamRom(unsigned char stringInRom, const char *sfmt, ...);
183 // #defines for RAM or ROM operation
184 #define rprintf2(format, args...) rprintf2RamRom(STRING_IN_ROM, format, ## args)
185 #define rprintf2RAM(format, args...) rprintf2RamRom(STRING_IN_RAM, format, ## args)
186  
187 // *** Default rprintf(...) ***
188 // this next line determines what the the basic rprintf() defaults to:
189 #define rprintf(format, args...) rprintf2RamRom(STRING_IN_ROM, PSTR(format), ## args)
190 #endif
191  
192 #endif
193 //@}