char OsFPrintfLite( UInt8T stream, rom char * format, ... );
Function OsFPrintfLite() should be called by the client application to send formatted output to a stream. The function arguments are the stream identifier, the format string and data values exactly matching format specifiers in the format string. The return value is the total number of characters written to the stream. If an invalid stream identifier is supplied, the function does nothing and returns zero.
The general form of this function is the same as the ANSI standard C library function fprintf(). However, the following differences must be noted:
Important: due to a limitation of ZiLOG's ZDS II for Z8 Encore! (as of version 4.7.0), it is not possible to place the format string directly in the function argument list as is customary. The compiler does not look at the storage qualifier in the type of the formal argument. As a result, format strings placed in the argument list are stored in RAM instead of ROM and the function does not work. Instead, format strings must be defined outside the argument list as in the example, below. The storage qualifier is then effective and the string is stored in ROM. The alternative design of OsFPrintfLite() in which the format string is stored in RAM is not considered acceptable for moderate to large systems. RAM should be preserved for variable data, not filled with lots of constant strings. Initialized strings have to be stored in ROM anyway so their initial value can be copied to RAM when the program starts. Why have them in two places? In the opinion of ECROS Technology, ZiLOG's implementation of the printf() family of library functions in which format strings are stored in RAM is fundamentally flawed. The published workaround of copying format strings from ROM to RAM at runtime cannot be taken seriously. The ECROS stream I/O system is offered as a superior option. Now, if only ZiLOG would fix the compiler ...
The example below shows formatted output being sent to the display.
static rom char fmt[] = "\fString: %s\nNumber: %u";
static char buf[16] = "Hello world!";
int num = 2004;
OsFPrintfLite( OS_DISPLAY, fmt, buf, num );
The '\f' and '\n' in the format string clear the display and advance to the start of the next display line respectively. The %s format specifier causes the output of a zero-terminated string stored in RAM. The address of this string, buf, is placed in the argument list. The %u format specifier causes the output of an unsigned (16-bit) integer in decimal format. The value of this integer, num, is placed in the argument list.
The 'Lite' in OsFPrintfLite() is intended to indicate that the full functionality of printf() is not supported. This is to improve the performance of formatted output and reduce the amount of program memory consumed. For example, just replacing OsFPrintfLite() with sprintf() in the example above results in the program size increasing by more than 6 kbytes. The absent functionality is support of format specifiers that are rarely used in real-time embedded systems. If your system is non-real-time and you need, for example, the floating point specifiers, you can use ZiLOG's printf() family of functions to generate formatted output in a RAM string and then send that string to the ECROS stream.
%c - a 16-bit integer is removed from the argument list and the least significant byte is output to the stream as a single character (note that when a character variable or constant is placed in the argument list, the compiler automatically converts it to an integer).
%s - a far (16-bit) pointer to RAM is removed from the argument list and the zero-terminated character string to which it points is output to the stream.
%S - as for %s, but the string pointer is interpreted as an address in ROM, not RAM
%u - a 16-bit integer is removed from the argument list and is output to the stream formated as an unsigned decimal number. <<<to do - document modifiers, flags, etc.>>>
%x - a 16-bit integer is removed from the argument list and is output to the stream formated as a hexadecimal number using lower case a through f <<<not implemented yet>>>.
%X - as for %x, but using upper case A through F.
Individual characters are sent to the specified stream using OsFPutC(). Therefore, the effect of non-printing characters is as documented for that function.