@c @c COPYRIGHT (c) 1988-2002. @c On-Line Applications Research Corporation (OAR). @c All rights reserved. @c @c $Id$ @c @chapter Console Driver @section Introduction This chapter describes the operation of a console driver using the RTEMS POSIX Termios support. Traditionally RTEMS has referred to all serial device drivers as console device drivers. A console driver can be used to do raw data processing in addition to the "normal" standard input and output device functions required of a console. The serial driver may be called as the consequence of a C Library call such as @code{printf} or @code{scanf} or directly via the @code{read} or @code{write} system calls. There are two main functioning modes: @itemize @bullet @item console: formatted input/output, with special characters (end of line, tabulations, etc.) recognition and processing, @item raw: permits raw data processing. @end itemize One may think that two serial drivers are needed to handle these two types of data, but Termios permits having only one driver. @section Termios Termios is a standard for terminal management, included in the POSIX 1003.1b standard. It is commonly provided on UNIX implementations. Having RTEMS support for Termios is beneficial: @itemize @bullet @item from the user's side because it provides standard primitive operations to access the terminal and change configuration settings. These operations are the same under Unix and Rtems. @item from the BSP developer's side because it frees the developer from dealing with buffer states and mutual exclusions on them. Early RTEMS console device drivers also did their own special character processing. @end itemize Termios support includes: @itemize @bullet @item raw and console handling, @item blocking or non-blocking characters receive, with or without Timeout. @end itemize At this time, RTEMS documentation does not include a thorough discussion of the Termios functionality. For more information on Termios, type @code{man termios} on a Unix box or point a web browser at @uref{http://www.freebsd.org/cgi/man.cgi}. @section Driver Functioning Modes There are generally two main functioning modes for an UART (Universal Asynchronous Receiver-Transmitter, i.e. the serial chip): @itemize @bullet @item polled mode @item interrupt driven mode @end itemize In polled mode, the processor blocks on sending/receiving characters. This mode is not the most efficient way to utilize the UART. But polled mode is usually necessary when one wants to print an error message in the event of a fatal error such as a fatal error in the BSP. This is also the simplest mode to program. Polled mode is generally preferred if the serial port is to be used primarily as a debug console. In a simple polled driver, the software will continuously check the status of the UART when it is reading or writing to the UART. Termios improves on this by delaying the caller for 1 clock tick between successive checks of the UART on a read operation. In interrupt driven mode, the processor does not block on sending/receiving characters. Data is buffered between the interrupt service routine and application code. Two buffers are used to insulate the application from the relative slowness of the serial device. One of the buffers is used for incoming characters, while the other is used for outgoing characters. An interrupt is raised when a character is received by the UART. The interrupt subroutine places the incoming character at the end of the input buffer. When an application asks for input, the characters at the front of the buffer are returned. When the application prints to the serial device, the outgoing characters are placed at the end of the output buffer. The driver will place one or more characters in the UART (the exact number depends on the UART) An interrupt will be raised when all the characters have been transmitted. The interrupt service routine has to send the characters remaining in the output buffer the same way. When the transmitting side of the UART is idle, it is typically necessary to prime the transmitter before the first interrupt will occur. @section Serial Driver Functioning Overview The following Figure shows how a Termios driven serial driver works: @example Figure not included in this draft @end example The following list describes the basic flow. @itemize @bullet @item the application programmer uses standard C library call (printf, scanf, read, write, etc.), @item C library (in fact that's Cygnus Newlib) calls RTEMS system call interface. This code can be found in the @code{c/src/lib/libc} directory. @item Glue code calls the serial driver entry routines. @end itemize @subsection Termios and Polled I/O The following functions are provided by the driver and invoked by Termios for simple character input/output. The specific names of these routines are not important as Termios invokes them indirectly via function pointers. @subsubsection pollWrite The @code{pollWrite} routine is responsible for writing @code{len} characters from @code{buf} to the serial device specified by @code{minor}. @example @group int pollWrite (int minor, const char *buf, int len) @{ for (i=0; i