[avr-libc-dev] minor avr libc documentation gripe (fwd)

[Theodore A. Roth]

---------- Forwarded message ----------
Date: Tue, 20 Jul 2004 07:38:20 -0400 (EDT)
From: Sean Midthun Pieper <address@hidden>
To: address@hidden
Subject: minor avr libc documentation gripe

Hi,

        I'm starting to use your avr libc package-- looks pretty nice so
far. I'm in the process of creating the necessary support functions for
stdio.h (putchar etc.), and I noticed a minor documentation bug. The .h
file has the following text:


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").


    \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)
    {

      if (c == '\n')
        uart_putchar('\r');
      loop_until_bit_is_set(UCSRA, UDRE);
      UDR = c;
      return 0;
    }
    \endcode


putc() written this way will break binary data transfers (attempt to
transfer 0xa becomes transfer of 0xd 0xa. Hilarity ensues). Because putc()
is frequently used for binary data transfers, in every other development
enviroment for microcontrollers that I've used, it's been the user's
responsibility to insert the \r if necessary (this changes in large part
depending on the terminal being used and how it is configured). I think
that the benefit of being able to make binary transfers outweighs the
minor inconvenience of potentially needing to terminate a string with
\r\n. If you really want to avoid forcing the user to add the carriage
return, perhaps a more effective solution would be to place this parsing
into printf, perhaps as an option switched by a #define?

-sean