/** \file */
/** \defgroup avr_stdio <stdio.h>: Standard IO facilities
\code #include <stdio.h> \endcode
<h3>Introduction to the Standard IO facilities</h3>
This file declares the standard IO facilities that are implemented
in \c avr-libc. Due to the nature of the underlying hardware,
only a limited subset of standard IO is implemented. There is no
actual file implementation available, so only device IO can be
performed. Since there's no operating system, the application
needs to provide enough details about their devices in order to
make them usable by the standard IO facilities.
Due to space constraints, some functionality has not been
implemented at all (like some of the \c printf conversions that
have been left out). Nevertheless, potential users of this
implementation should be warned: the \c printf and \c scanf families of functions, although
usually associated with presumably simple things like the
famous "Hello, world!" program, are actually fairly complex
which causes their inclusion to eat up a fair amount of code space.
Also, they are not fast due to the nature of interpreting the
format string at run-time. Whenever possible, resorting to the
(sometimes non-standard) predetermined conversion facilities that are
offered by avr-libc will usually cost much less in terms of speed
and code size.
<h3>Tunable options for code size vs. feature set</h3>
In order to allow programmers a code size vs. functionality tradeoff,
the function vfprintf() which is the heart of the printf family can be
selected in different flavours using linker options. See the
documentation of vfprintf() for a detailed description. The same
applies to vfscanf() and the \c scanf family of functions.
<h3>Outline of the chosen API</h3>
The standard streams \c stdin, \c stdout, and \c stderr are
provided, but contrary to the C standard, since avr-libc has no
knowledge about applicable devices, these streams are not already
pre-initialized at application startup. Also, since there is no
notion of "file" whatsoever to avr-libc, there is no function
\c fopen() that could be used to associate a stream to some device.
(See \ref stdio_note1 "note 1".) Instead, the function \c fdevopen()
is provided to associate a stream to a device, where the device
needs to provide a function to send a character, to receive a
character, or both. There is no differentiation between "text" and
"binary" streams inside avr-libc. Character \c \\n is sent
literally down to the device's \c put() function. If the device
requires a carriage return (\c \\r) character to be sent before
the linefeed, its \c put() routine must implement this (see
\ref stdio_note2 "note 2").
As an alternative method to fdevopen(), the macro
fdev_setup_stream() might be used to setup a user-supplied FILE
structure.
It should be noted that the automatic conversion of a newline
character into a carriage return - newline sequence breaks binary
transfers. If binary transfers are desired, no automatic
conversion should be performed, but instead any string that aims
to issue a CR-LF sequence must use <tt>"\r\n"</tt> explicitly.
For convenience, the first call to \c fdevopen() that opens a
stream for reading will cause the resulting stream to be aliased
to \c stdin. Likewise, the first call to \c fdevopen() that opens
a stream for writing will cause the resulting stream to be aliased
to both, \c stdout, and \c stderr. Thus, if the open was done
with both, read and write intent, all three standard streams will
be identical. Note that these aliases are indistinguishable from
each other, thus calling \c fclose() on such a stream will also
effectively close all of its aliases (\ref stdio_note3 "note 3").
It is possible to tie additional user data to a stream, using
fdev_set_udata(). The backend put and get functions can then
extract this user data using fdev_get_udata(), and act
appropriately. For example, a single put function could be used
to talk to two different UARTs that way, or the put and get
functions could keep internal state between calls there.
<h3>Format strings in flash ROM</h3>
All the \c printf and \c scanf family functions come in two flavours: the
standard name, where the format string is expected to be in
SRAM, as well as a version with the suffix "_P" where the format
string is expected to reside in the flash ROM. The macro
\c PSTR (explained in \ref avr_pgmspace) becomes very handy
for declaring these format strings.
\anchor stdio_without_malloc
<h3>Running stdio without malloc()</h3>
By default, fdevopen() requires malloc(). As this is often
not desired in the limited environment of a microcontroller, an
alternative option is provided to run completely without malloc().
The macro fdev_setup_stream() is provided to prepare a
user-supplied FILE buffer for operation with stdio.
<h4>Example</h4>
\code
#include <stdio.h>
static int uart_putchar(char c, FILE *stream);
static FILE mystdout = FDEV_SETUP_STREAM(uart_putchar, NULL,
_FDEV_SETUP_WRITE);
static int
uart_putchar(char c, FILE *stream)
{
if (c == '\n')
uart_putchar('\r', stream);
loop_until_bit_is_set(UCSRA, UDRE);
UDR = c;
return 0;
}
int
main(void)
{
init_uart();
stdout = &mystdout;
printf("Hello, world!\n");
return 0;
}
\endcode
This example uses the initializer form FDEV_SETUP_STREAM() rather
than the function-like fdev_setup_stream(), so all data
initialization happens during C start-up.
If streams initialized that way are no longer needed, they can be
destroyed by first calling the macro fdev_close(), and then
destroying the object itself. No call to fclose() should be
issued for these streams. While calling fclose() itself is
harmless, it will cause an undefined reference to free() and thus
cause the linker to link the malloc module into the application.
<h3>Notes</h3>
\anchor stdio_note1 \par Note 1:
It might have been possible to implement a device abstraction that
is compatible with \c fopen() but since this would have required
to parse a string, and to take all the information needed either
out of this string, or out of an additional table that would need to be
provided by the application, this approach was not taken.
\anchor stdio_note2 \par Note 2:
This basically follows the Unix approach: if a device such as a
terminal needs special handling, it is in the domain of the
terminal device driver to provide this functionality. Thus, a
simple function suitable as \c put() for \c fdevopen() that talks
to a UART interface might look like this:
\code
int
uart_putchar(char c, FILE *stream)
{
if (c == '\n')
uart_putchar('\r');
loop_until_bit_is_set(UCSRA, UDRE);
UDR = c;
return 0;
}
\endcode
\anchor stdio_note3 \par Note 3:
This implementation has been chosen because the cost of maintaining
an alias is considerably smaller than the cost of maintaining full
copies of each stream. Yet, providing an implementation that offers
the complete set of standard streams was deemed to be useful. Not
only that writing \c printf() instead of <tt>fprintf(mystream, ...)</tt>
saves typing work, but since avr-gcc needs to resort to pass all
arguments of variadic functions on the stack (as opposed to passing
them in registers for functions that take a fixed number of
parameters), the ability to pass one parameter less by implying
\c stdin will also save some execution time.
*/
심벌.dwg
IEC_규격_전선의_허용전류_산정방법.pdf
파나텀 Ver 3.7.zip
