Subversion Repositories svnkaklik

Rev

Go to most recent revision | Details | Last modification | View Log

Rev Author Line No. Line
507 kaklik 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
// NOTE: Below you'll see the function prototypes of rprintf1RamRom and 
125
// rprintf2RamRom.  rprintf1RamRom and rprintf2RamRom are both reduced versions
126
// of the regular C printf() command.  However, they are modified to be able
127
// to read their text/format strings from RAM or ROM in the Atmel microprocessors.
128
// Unless you really intend to, do not use the "RamRom" versions of the functions
129
// directly.  Instead use the #defined function versions:
130
//
131
// printfx("text/format",args)    ...to keep your text/format string stored in RAM
132
//		- or -
133
// printfxROM("text/format",args) ...to keep your text/format string stored in ROM
134
//
135
// where x is either 1 or 2 for the simple or more powerful version of printf()
136
//
137
// Since there is much more ROM than RAM available in the Atmel microprocessors,
138
// and nearly all text/format strings are constant (never change in the course
139
// of the program), you should try to use the ROM printf version exclusively.
140
// This will ensure you leave as much RAM as possible for program variables and
141
// data.
142
 
143
//! \fn int rprintf(const char *format, ...);
144
/// A reduced substitute for the usual C printf() function.
145
/// This function actually points to either rprintf1RamRom or rprintf2RamRom
146
/// depending on the user's selection.  Rprintf1 is a simple small fast print
147
/// routine while rprintf2 is larger and slower but more capable. To choose
148
/// the routine you would like to use, define either RPRINTF_SIMPLE or
149
/// RPRINTF_COMPLEX in global.h.
150
 
151
#ifdef RPRINTF_SIMPLE
152
	//! A simple printf routine.
153
	/// Called by rprintf() - does a simple printf (supports %d, %x, %c).
154
	/// Supports:
155
	/// - %d - decimal
156
	/// - %x - hex
157
	/// - %c - character
158
	int rprintf1RamRom(unsigned char stringInRom, const char *format, ...);
159
	// #defines for RAM or ROM operation
160
	#define rprintf1(format, args...)  		rprintf1RamRom(STRING_IN_ROM, PSTR(format), ## args)
161
	#define rprintf1RAM(format, args...)	rprintf1RamRom(STRING_IN_RAM, format, ## args)
162
 
163
	// *** Default rprintf(...) ***
164
	// this next line determines what the the basic rprintf() defaults to:
165
	#define rprintf(format, args...)  		rprintf1RamRom(STRING_IN_ROM, PSTR(format), ## args)
166
#endif
167
 
168
#ifdef RPRINTF_COMPLEX
169
	//! A more powerful printf routine.
170
	/// Called by rprintf() - does a more powerful printf (supports %d, %u, %o, %x, %c, %s).
171
	/// Supports:
172
	/// - %d - decimal
173
	/// - %u - unsigned decimal
174
	/// - %o - octal
175
	/// - %x - hex
176
	/// - %c - character
177
	/// - %s - strings
178
	/// - and the width,precision,padding modifiers
179
	/// \note This printf does not support floating point numbers.
180
	int rprintf2RamRom(unsigned char stringInRom, const char *sfmt, ...);
181
	// #defines for RAM or ROM operation
182
	#define rprintf2(format, args...)		rprintf2RamRom(STRING_IN_ROM, format, ## args)
183
	#define rprintf2RAM(format, args...)	rprintf2RamRom(STRING_IN_RAM, format, ## args)
184
 
185
	// *** Default rprintf(...) ***
186
	// this next line determines what the the basic rprintf() defaults to:
187
	#define rprintf(format, args...)  		rprintf2RamRom(STRING_IN_ROM, PSTR(format), ## args)
188
#endif
189
 
190
#endif
191
//@}