Changeset 47eab0a in rtems


Ignore:
Timestamp:
Dec 11, 2008, 3:50:02 PM (11 years ago)
Author:
Joel Sherrill <joel.sherrill@…>
Branches:
4.9
Children:
f4b6dc0
Parents:
24df6dd
Message:

2008-12-11 Sebastian Huber <sebastian.huber@…>

Joel Sherrrill <joel.sherrill@…>

  • bsp_howto/Makefile.am, bsp_howto/console.t: Sebastian improved documentation for termios device drivers.
  • bsp_howto/TERMIOSFlow.eps, bsp_howto/TERMIOSFlow.png: New files. Joel added Termios Flow figure from RTEMS Open Class material.
Location:
doc
Files:
2 added
3 edited

Legend:

Unmodified
Added
Removed
  • doc/ChangeLog

    r24df6dd r47eab0a  
     12008-12-11      Sebastian Huber <sebastian.huber@embedded-brains.de>
     2                Joel Sherrrill <joel.sherrill@oarcorp.com>
     3
     4        * bsp_howto/Makefile.am, bsp_howto/console.t: Sebastian improved
     5         documentation for termios device drivers.
     6        * bsp_howto/TERMIOSFlow.eps, bsp_howto/TERMIOSFlow.png: New files.
     7        Joel added Termios Flow figure from RTEMS Open Class material.
     8
    192008-12-01      Joel Sherrill <joel.sherrill@OARcorp.com>
    210
  • doc/bsp_howto/Makefile.am

    r24df6dd r47eab0a  
    2020COMMON_FILES += $(top_srcdir)/common/cpright.texi
    2121
    22 PNG_FILES = Developer-User-Timeline.png BSPInitFlowchart-49.png
     22PNG_FILES = Developer-User-Timeline.png BSPInitFlowchart-49.png \
     23    TERMIOSFlow.png
    2324
    2425if USE_HTML
  • doc/bsp_howto/console.t

    r24df6dd r47eab0a  
    11@c
    2 @c  COPYRIGHT (c) 1988-2002.
     2@c  COPYRIGHT (c) 1988-2008.
    33@c  On-Line Applications Research Corporation (OAR).
    44@c  All rights reserved.
     
    3737@section Termios
    3838
    39 Termios is a standard for terminal management, included in the POSIX 1003.1b
    40 standard.  It is commonly provided on UNIX implementations. 
    41 Having RTEMS support for Termios is beneficial:
     39Termios is a standard for terminal management, included in the POSIX
     401003.1b standard.  As part of the POSIX and Open Group Single UNIX
     41Specification, is commonly provided on UNIX implementations.  The
     42Open Group has the termios portion of the POSIX standard online
     43at @uref{http://opengroup.org/onlinepubs/007908775/xbd/termios.html
     44,http://opengroup.org/onlinepubs/007908775/xbd/termios.html}.
     45The requirements for the @code{<termios.h>} file are also provided
     46and are at @uref{http://opengroup.org/onlinepubs/007908775/xsh/termios.h.html,
     47http://opengroup.org/onlinepubs/007908775/xsh/termios.h.html}.
     48
     49Having RTEMS support for Termios is beneficial because:
    4250
    4351@itemize @bullet
     
    5159Early RTEMS console device drivers also did their own special
    5260character processing.
     61
     62@item it is part of an internationally recognized standard.
     63
     64@item it makes porting code from other environments easier.
    5365
    5466@end itemize
     
    119131The following Figure shows how a Termios driven serial driver works:
    120132
    121 @example
    122 Figure not included in this draft
    123 @end example
     133@ifset use-ascii
     134@center Figure not included in ASCII version
     135@end ifset
     136
     137@ifset use-tex
     138@sp1
     139@center{@image{TERMIOSFlow,,6in}}
     140@end ifset
     141
     142@ifset use-html
     143@html
     144<P ALIGN="center"><IMG SRC="TERMIOSFlow.png"
     145     WIDTH=800 HEIGHT=610 ALT="Termios Flow"></P>
     146@end html
     147@end ifset
     148
     149The most significant five bits are the object class.  The next
     150three bits indicate the API to which the object class belongs.
    124151
    125152The following list describes the basic flow.
     
    130157scanf, read, write, etc.),
    131158
    132 @item C library (in fact that's Cygnus Newlib) calls RTEMS
    133 system call interface. This code can be found in the
    134 @code{c/src/lib/libc} directory.
     159@item C library (e.g. RedHat (formerly Cygnus) Newlib) calls
     160the RTEMS system call interface.  This code can be found in the
     161@code{cpukit/libcsupport/src} directory.
    135162
    136163@item Glue code calls the serial driver entry routines.
     
    138165@end itemize
    139166
    140 @subsection Termios and Polled I/O
     167@subsection Basics
     168
     169You need to include the following header files in your Termios device driver
     170source file:
     171@example
     172@group
     173#include <unistd.h>
     174#include <termios.h>
     175
     176#include <rtems.h>
     177#include <rtems/libio.h>
     178#include <rtems/console.h>
     179@end group
     180@end example
     181
     182You need to provide a data structure for the Termios driver interface.  The
     183functions are described later in this chapter.  The functions should return
     184zero on succes and minus one in case of an error.  Currently the return value
     185will be not checked from the Termios infrastructure in most cases.  One notable
     186exception is the polled read function, here is the return value important.
     187
     188If you want to use polled IO it should look like the following.  You may also
     189have a look at @code{c/src/lib/libbsp/shared/console-polled.c} for a shared
     190implementation of the basic framework.  Termios must be told the addresses of
     191the functions that are to be used for simple character IO, i.e. pointers to the
     192@code{my_driver_poll_read} and @code{my_driver_poll_write} functions described
     193later in @ref{Console Driver Termios and Polled IO}.
     194
     195@example
     196@group
     197static const rtems_termios_callbacks my_driver_callbacks_polled = @{
     198    .firstOpen = my_driver_first_open,
     199    .lastClose = my_driver_last_close,
     200    .pollRead = my_driver_poll_read,
     201    .write = my_driver_poll_write,
     202    .setAttributes = my_driver_set_attributes,
     203    .stopRemoteTx = NULL,
     204    .startRemoteTx = NULL,
     205    .outputUsesInterrupts = TERMIOS_POLLED
     206@};
     207@end group
     208@end example
     209
     210For an interrupt driven implementation you need the following.  The driver
     211functioning is quite different in this mode.  There is no device driver read
     212function to be passed to Termios.  Indeed a @code{console_read} call returns
     213the contents of Termios input buffer.  This buffer is filled in the driver
     214interrupt subroutine, see also
     215@ref{Console Driver Termios and Interrupt Driven IO}.
     216The driver is responsible for providing a pointer to the
     217@code{my_driver_interrupt_write} function.
     218
     219@example
     220@group
     221static const rtems_termios_callbacks my_driver_callbacks_interrupt = @{
     222    .firstOpen = my_driver_first_open,
     223    .lastClose = my_driver_last_close,
     224    .pollRead = NULL,
     225    .write = my_driver_interrupt_write,
     226    .setAttributes = my_driver_set_attributes,
     227    .stopRemoteTx = NULL,
     228    .startRemoteTx = NULL,
     229    .outputUsesInterrupts = TERMIOS_IRQ_DRIVEN
     230@};
     231@end group
     232@end example
     233
     234You can also provide callback functions for remote transmission control.  This
     235is not covered in this manual, so thay are set to @code{NULL} in the above
     236examples.
     237
     238Normally the device specific data structures are stored in a table which is
     239indexed by the minor number.  You may need an entry for the Termios handler
     240pointer in your data structure.  For simplicity of the console initialization
     241example the device name is also present.
     242
     243@example
     244@group
     245/* Driver specific data structure */
     246typedef struct @{
     247    const char *device_name;
     248    struct rtems_termios_tty *tty;
     249@} my_driver_entry;
     250
     251/*
     252 * This table contains the driver specific data.  It is later
     253 * indexed by the minor number.
     254 */
     255static my_driver_entry my_driver_table [MY_DRIVER_DEVICE_NUMBER];
     256@end group
     257@end example
     258
     259@subsection Termios and Polled IO
    141260
    142261The following functions are provided by the driver and invoked by
    143 Termios for simple character input/output.  The specific names of
    144 these routines are not important as Termios invokes them indirectly
    145 via function pointers.
    146 
    147 @subsubsection pollWrite
    148 
    149 The @code{pollWrite} routine is responsible for writing @code{len} characters
    150 from @code{buf} to the serial device specified by @code{minor}.
    151 
    152 @example
    153 @group
    154 int pollWrite (int minor, const char *buf, int len)
    155 @{
    156   for (i=0; i<len; i++) @{
    157      put buf[i] into the UART channel minor
    158      wait for the character to be transmitted
    159      on the serial line
    160   @}
    161   return 0
    162 @}
    163 @end group
    164 @end example
    165 
    166 @subsubsection pollRead
    167 
    168 The @code{pollRead} routine is responsible for reading a single character
    169 from the serial device specified by @code{minor}.  If no character is
    170 available, then the routine should return -1.
    171 
    172 @example
    173 @group
    174 int pollRead(int minor)
    175 @{
    176    read status of UART
    177    if status indicates a character is available
    178      return character
    179    return -1
    180 @}
    181 @end group
    182 @end example
    183 
    184 @subsection Termios and Interrupt Driven I/O
    185 
    186 The UART generally generates interrupts when it is ready to accept or to
    187 emit a number of characters. In this mode, the interrupt subroutine is the
    188 core of the driver.
    189 
    190 @subsubsection InterruptHandler
    191 
    192 The @code{InterruptHandler} is responsible for processing asynchronous
    193 interrupts from the UART.  There may be multiple interrupt handlers for
    194 a single UART.  Some UARTs can generate a unique interrupt vector for
    195 each interrupt source such as a character has been received or the
     262Termios for simple character IO.
     263
     264The @code{my_driver_poll_write} routine is responsible for writing @code{n}
     265characters from @code{buf} to the serial device specified by @code{minor}.
     266
     267@example
     268@group
     269static int my_driver_poll_write(int minor, const char *buf, int n)
     270@{
     271    my_driver_entry *e = &my_driver_table [minor];
     272    int i = 0;
     273   
     274    /*
     275     * There is no need to check the minor number since it is derived
     276     * from a file descriptor.  The upper layer takes care that it is
     277     * in a valid range.
     278     */
     279   
     280    /* Write */
     281    for (i = 0; i < n; ++i) @{
     282        my_driver_write_char(e, buf [i]);
     283    @}
     284   
     285    return 0;
     286@}
     287@end group
     288@end example
     289
     290The @code{my_driver_poll_read} routine is responsible for reading a single
     291character from the serial device specified by @code{minor}.  If no character is
     292available, then the routine should return minus one.
     293
     294@example
     295@group
     296static int my_driver_poll_read(int minor)
     297@{
     298    my_driver_entry *e = &my_driver_table [minor];
     299   
     300    /*
     301     * There is no need to check the minor number since it is derived
     302     * from a file descriptor.  The upper layer takes care that it is
     303     * in a valid range.
     304     */
     305
     306    /* Check if a character is available */
     307    if (my_driver_can_read_char(e)) @{
     308        /* Return the character */
     309        return my_driver_read_char(e);
     310    @} else @{
     311        /* Return an error status */
     312        return -1;
     313    @}
     314@}
     315@end group
     316@end example
     317
     318@subsection Termios and Interrupt Driven IO
     319
     320The UART generally generates interrupts when it is ready to accept or to emit a
     321number of characters.  In this mode, the interrupt subroutine is the core of
     322the driver.
     323
     324The @code{my_driver_interrupt_handler} is responsible for processing
     325asynchronous interrupts from the UART.  There may be multiple interrupt
     326handlers for a single UART.  Some UARTs can generate a unique interrupt vector
     327for each interrupt source such as a character has been received or the
    196328transmitter is ready for another character.
    197329
    198 In the simplest case, the @code{InterruptHandler} will have to check
    199 the status of the UART and determine what caused the interrupt.
    200 The following describes the operation of an @code{InterruptHandler}
    201 which has to do this:
    202 
    203 @example
    204 @group
    205 rtems_isr InterruptHandler (rtems_vector_number v)
    206 @{
    207   check whether there was an error
    208 
    209   if some characters were received:
    210      Ask Termios to put them on his input buffer
    211 
    212   if some characters have been transmitted
    213         (i.e. the UART output buffer is empty)
    214      Tell TERMIOS that the characters have been
    215      transmitted. The TERMIOS routine will call
    216      the InterruptWrite function with the number
    217      of characters not transmitted yet if it is
    218      not zero.
    219 @}
    220 @end group
    221 @end example
    222 
    223 @subsubsection InterruptWrite
    224 
    225 The @code{InterruptWrite} is responsible for telling the UART
    226 that the @code{len} characters at @code{buf} are to be transmitted.
    227 
    228 @example
    229 static int InterruptWrite(int minor, const char *buf, int len)
    230 @{
    231   tell the UART to transmit len characters from buf
    232   return 0
    233 @}
    234 @end example
    235 
    236 The driver has to put the @i{n} first buf characters in the UART channel minor
    237 buffer (@i{n} is the UART channel size, @i{n}=1 on the MC68640). Generally, an
    238 interrupt is raised after these @i{n} characters being transmitted. So
    239 UART interrupts may have to be enabled after putting the characters in the
    240 UART.
    241 
     330In the simplest case, the @code{my_driver_interrupt_handler} will have to check
     331the status of the UART and determine what caused the interrupt.  The following
     332describes the operation of an @code{my_driver_interrupt_handler} which has to
     333do this:
     334
     335@example
     336@group
     337static void my_driver_interrupt_handler(
     338    rtems_vector_number vector,
     339    void *arg
     340)
     341@{
     342    my_driver_entry *e = (my_driver_entry *) arg;
     343    char buf [N];
     344    int n = 0;
     345
     346    /*
     347     * Check if we have received something.  The function reads the
     348     * received characters from the device and stores them in the
     349     * buffer.  It returns the number of read characters.
     350     */
     351    n = my_driver_read_received_chars(e, buf, N);
     352    if (n > 0) @{
     353        /* Hand the data over to the Termios infrastructure */
     354        rtems_termios_enqueue_raw_characters(e->tty, buf, n);
     355    @}
     356
     357    /*
     358     * Check if we have something transmitted.  The functions returns
     359     * the number of transmitted characters since the last write to the
     360     * device.
     361     */
     362    n = my_driver_transmitted_chars(e);
     363    if (n > 0) @{
     364        /*
     365         * Notify Termios that we have transmitted some characters.  It
     366         * will call now the interrupt write function if more characters
     367         * are ready for transmission.
     368         */
     369        rtems_termios_dequeue_characters(e->tty, n);
     370    @}
     371@}
     372@end group
     373@end example
     374
     375The @code{my_driver_interrupt_write} function is responsible for telling the
     376device that the @code{n} characters at @code{buf} are to be transmitted.  The
     377return value may be arbitrary since it is not checked from Termios.
     378
     379@example
     380@group
     381static int my_driver_interrupt_write(int minor, const char *buf, int n)
     382@{
     383    my_driver_entry *e = &my_driver_table [minor];
     384   
     385    /*
     386     * There is no need to check the minor number since it is derived
     387     * from a file descriptor.  The upper layer takes care that it is
     388     * in a valid range.
     389     */
     390
     391    /*
     392     * Tell the device to transmit some characters from buf (less than
     393     * or equal to n).  If the device is finished it should raise an
     394     * interrupt.  The interrupt handler will notify Termios that these
     395     * characters have been transmitted and this may trigger this write
     396     * function again.  You may have to store the number of outstanding
     397     * characters in the device data structure.
     398     */
     399
     400    return 0;
     401@}
     402@end group
     403@end example
    242404
    243405@subsection Initialization
     
    246408process.
    247409
    248 The @code{console_initialize} function has to:
    249 
    250 @itemize @bullet
    251 
    252 @item initialize Termios support: call @code{rtems_termios_initialize()}.  If
    253 Termios has already been initialized by another device driver, then
    254 this call will have no effect.
    255 
    256 @item Initialize the UART: This procedure should
    257 be described in the UART manual.  This procedure @b{MUST} be
    258 followed precisely.  This procedure varies but
    259 usually consists of:
    260 
    261 @itemize @bullet
    262 @item reinitialize the UART channels
    263 
    264 @item set the channels configuration to the Termios default:
    265 9600 bauds, no parity, 1 stop bit, and 8 bits per character
    266 @end itemize
    267 
    268 @item If interrupt driven, register the console interrupt routine to RTEMS:
    269 
    270 @example
    271 rtems_interrupt_catch(
    272     InterruptHandler, CONSOLE_VECTOR, &old_handler);
    273 @end example
    274 
    275 @item enable the UART channels.
    276 
    277 @item register the device name: in order to use the console (i.e. being
    278 able to do printf/scanf on stdin, stdout, and stderr), some device
    279 must be registered as "/dev/console":
    280 
    281 @example
    282 rtems_io_register_name ("dev/console", major, i);
    283 @end example
    284 
    285 @end itemize
     410The @code{console_initialize} function may look like this:
     411
     412@example
     413@group
     414rtems_device_driver console_initialize(
     415    rtems_device_major_number major,
     416    rtems_device_minor_number minor,
     417    void *arg
     418)
     419@{
     420    rtems_status_code sc = RTEMS_SUCCESSFUL;
     421    rtems_device_minor_number i = 0;
     422
     423    /*
     424     * Initialize the Termios infrastructure.  If Termios has already
     425     * been initialized by another device driver, then this call will
     426     * have no effect.
     427     */
     428    rtems_termios_initialize();
     429   
     430    /* Initialize each device */
     431    for (i = 0; i < MY_DRIVER_DEVICE_NUMBER; ++i) @{
     432        my_driver_entry *e = &my_driver_table [i];
     433
     434        /*
     435         * Register this device in the file system.  In order to use the
     436         * console (i.e. being able to do printf, scanf etc. on stdin,
     437         * stdout and stderr), some device must be registered
     438         * as "/dev/console" (CONSOLE_DEVICE_NAME).
     439         */
     440        sc = rtems_io_register_name (e->device_name, major, i);
     441        RTEMS_CHECK_SC(sc, "Register IO device");
     442
     443        /*
     444         * Initialize this device and install the interrupt handler if
     445         * necessary.  You may also initialize the device in the first
     446         * open call.
     447         */
     448    @}
     449
     450    return RTEMS_SUCCESSFUL;
     451@}
     452@end group
     453@end example
    286454
    287455@subsection Opening a serial device
    288456
    289 The @code{console_open} function is called whenever a serial
    290 device is opened.  The device registered as @code{"/dev/console"}
    291 is opened automatically during RTEMS initialization.
    292 For instance, if UART channel 2 is registered as "/dev/tty1",
    293 the @code{console_open} entry point will be called as
    294 the result of an @code{fopen("/dev/tty1", mode)} in the
     457The @code{console_open} function is called whenever a serial device is opened.
     458The device registered as @code{"/dev/console"} (@code{CONSOLE_DEVICE_NAME}) is
     459opened automatically during RTEMS initialization.  For instance, if UART
     460channel 2 is registered as "/dev/tty1", the @code{console_open} entry point
     461will be called as the result of an @code{fopen("/dev/tty1", mode)} in the
    295462application.
    296463
    297464The @code{console_open} function has to inform Termios of the low-level
    298 functions for serial line support; the "callbacks".
    299 
    300 The gen68340 BSP defines two sets of callback tables:
    301 
    302 @itemize @bullet
    303 
    304 @item one with functions for polled input/output
    305 
    306 @item another with functions for interrupt driven input/output
    307 
    308 @end itemize
    309 
    310 This code can be found in the file @code{$BSPROOT/console/console.c}.
    311 
    312 @subsubsection Polled I/O
    313 
    314 Termios must be told the addresses of the functions that are to be
    315 used for simple character input/output, i.e. pointers to the
    316 @code{pollWrite} and @code{pollRead} functions
    317 defined earlier in @ref{Console Driver Termios and Polled I/O}.
    318 
    319 @subsubsection Interrupt Driven I/O
    320 
    321 Driver functioning is quite different in this mode.  There is no
    322 device driver read function to be passed to Termios. Indeed a
    323 @code{console_read} call returns the contents of Termios input buffer.
    324 This buffer is filled in the driver interrupt subroutine
    325 (see @ref{Console Driver Termios and Interrupt Driven I/O}).
    326 
    327 The driver is responsible for providing a pointer to the
    328 @code{InterruptWrite} function.
     465functions for serial line support.
     466
     467@example
     468@group
     469rtems_device_driver console_open(
     470    rtems_device_major_number major,
     471    rtems_device_minor_number minor,
     472    void *arg
     473)
     474@{
     475    struct rtems_termios_callbacks *callbacks =
     476        &my_driver_callbacks_polled;
     477
     478    /*
     479     * Check the minor number.  Termios does currently not check
     480     * the return value of the first open call so the minor
     481     * number must be checked here.
     482     */
     483    if (MY_DRIVER_IS_MINOR_INVALID(minor)) @{
     484        return RTEMS_INVALID_NUMBER;
     485    @}
     486
     487    /*
     488     * Depending on the IO mode you need to pass a different set of
     489     * callback functions to Termios.
     490     */
     491    if (MY_DRIVER_USES_INTERRUPTS(minor)) @{
     492        callbacks = &my_driver_callbacks_interrupt;
     493    @}
     494
     495    return rtems_termios_open(major, minor, arg, callbacks);
     496@}
     497@end group
     498@end example
     499
     500During the first open of the device Termios will call @code{my_driver_first_open}.
     501
     502@example
     503@group
     504static int my_driver_first_open(int major, int minor, void *arg)
     505@{
     506    my_driver_entry *e = &my_driver_table [minor];
     507    struct rtems_termios_tty *tty =
     508        ((rtems_libio_open_close_args_t *) arg)->iop->data1;
     509   
     510    /* Check minor number */
     511    if (MY_DRIVER_IS_MINOR_INVALID(minor)) @{
     512        return -1;
     513    @}
     514
     515    /* Connect the TTY data structure */
     516    e->tty = tty;
     517
     518    /*
     519     * You may add some initialization code here.
     520     */
     521
     522    /*
     523     * Sets the inital baud rate.  This should be set to the value of
     524     * the boot loader.
     525     */
     526    return rtems_termios_set_initial_baud(e->tty, MY_DRIVER_BAUD_RATE);
     527@}
     528@end group
     529@end example
    329530
    330531@subsection Closing a Serial Device
    331532
    332 The @code{console_close} is invoked when the serial device is to
    333 be closed.  This entry point corresponds to the device driver
    334 close entry point.
    335 
    336 This routine is responsible for notifying Termios that the serial
    337 device was closed.  This is done with a call to @code{rtems_termios_close}.
    338 
    339 @subsection Reading Characters From a Serial Device
    340 
    341 The @code{console_read} is invoked when the serial device is to
    342 be read from.  This entry point corresponds to the device driver
    343 read entry point.
    344 
    345 This routine is responsible for returning the content of the
    346 Termios input buffer.   This is done by invoking the
    347 @code{rtems_termios_read} routine.
     533The @code{console_close} is invoked when the serial device is to be closed.
     534This entry point corresponds to the device driver close entry point.
     535
     536This routine is responsible for notifying Termios that the serial device was
     537closed.  This is done with a call to @code{rtems_termios_close}.
     538
     539@example
     540@group
     541rtems_device_driver console_close(
     542    rtems_device_major_number major,
     543    rtems_device_minor_number minor,
     544    void *arg
     545)
     546@{
     547    return rtems_termios_close(arg);
     548@}
     549@end group
     550@end example
     551
     552Termios will call the @code{my_driver_last_close} function if the last close
     553happens on the device.
     554@example
     555@group
     556static int my_driver_last_close(int major, int minor, void *arg)
     557@{
     558    my_driver_entry *e = &my_driver_table [minor];
     559   
     560    /*
     561     * There is no need to check the minor number since it is derived
     562     * from a file descriptor.  The upper layer takes care that it is
     563     * in a valid range.
     564     */
     565
     566    /* Disconnect the TTY data structure */
     567    e->tty = NULL;
     568
     569    /*
     570     * The driver may do some cleanup here.
     571     */
     572
     573    return 0;
     574@}
     575@end group
     576@end example
     577
     578@subsection Reading Characters from a Serial Device
     579
     580The @code{console_read} is invoked when the serial device is to be read from.
     581This entry point corresponds to the device driver read entry point.
     582
     583This routine is responsible for returning the content of the Termios input
     584buffer.  This is done by invoking the @code{rtems_termios_read} routine.
     585
     586@example
     587@group
     588rtems_device_driver console_read(
     589    rtems_device_major_number major,
     590    rtems_device_minor_number minor,
     591    void *arg
     592)
     593@{
     594    return rtems_termios_read(arg);
     595@}
     596@end group
     597@end example
    348598
    349599@subsection Writing Characters to a Serial Device
    350600
    351 The @code{console_write} is invoked when the serial device is to
    352 be written to.  This entry point corresponds to the device driver
    353 write entry point.
    354 
    355 This routine is responsible for adding the requested characters to
    356 the Termios output queue for this device.  This is done by
    357 calling the routine @code{rtems_termios_write}
    358 to add the characters at the end of the Termios output
    359 buffer.
     601The @code{console_write} is invoked when the serial device is to be written to.
     602This entry point corresponds to the device driver write entry point.
     603
     604This routine is responsible for adding the requested characters to the Termios
     605output queue for this device.  This is done by calling the routine
     606@code{rtems_termios_write} to add the characters at the end of the Termios
     607output buffer.
     608
     609@example
     610@group
     611rtems_device_driver console_write(
     612    rtems_device_major_number major,
     613    rtems_device_minor_number minor,
     614    void *arg
     615)
     616@{
     617    return rtems_termios_write(arg);
     618@}
     619@end group
     620@end example
    360621
    361622@subsection Changing Serial Line Parameters
    362623
    363 The @code{console_control} is invoked when the line parameters
    364 for a particular serial device are to be changed.
    365 This entry point corresponds to the device driver
    366 io_control entry point.
    367 
    368 The application write is able to control the serial line configuration
    369 with Termios calls (such as the @code{ioctl} command, see
    370 the Termios documentation for
    371 more details). If the driver is to support dynamic configuration, then
    372 is must have the @code{console_control} piece of code. Refer to the gen68340
    373 BSP for an example of how it is done.  Basically @code{ioctl}
    374 commands call @code{console_control} with the serial line
    375 configuration in a Termios defined data structure. The driver
    376 is responsible for reinitializing the UART with the correct settings.
    377 
     624The @code{console_control} is invoked when the line parameters for a particular
     625serial device are to be changed.  This entry point corresponds to the device
     626driver io_control entry point.
     627
     628The application writer is able to control the serial line configuration with
     629Termios calls (such as the @code{ioctl} command, see the Termios documentation
     630for more details).  If the driver is to support dynamic configuration, then it
     631must have the @code{console_control} piece of code.  Basically @code{ioctl}
     632commands call @code{console_control} with the serial line configuration in a
     633Termios defined data structure.
     634
     635@example
     636@group
     637rtems_device_driver console_control(
     638    rtems_device_major_number major,
     639    rtems_device_minor_number minor,
     640    void *arg
     641)
     642@{
     643    return rtems_termios_ioctl(arg);
     644@}
     645@end group
     646@end example
     647
     648The driver is responsible for reinitializing the device with the correct
     649settings.  For this purpuse Termios calls the @code{my_driver_set_attributes}
     650function.
     651
     652@example
     653@group
     654static int my_driver_set_attributes(
     655    int minor,
     656    const struct termios *t
     657)
     658@{
     659    my_driver_entry *e = &my_driver_table [minor];
     660   
     661    /*
     662     * There is no need to check the minor number since it is derived
     663     * from a file descriptor.  The upper layer takes care that it is
     664     * in a valid range.
     665     */
     666
     667    /*
     668     * Inspect the termios data structure and configure the device
     669     * appropriately.  The driver should only be concerned with the
     670     * parts of the structure that specify hardware setting for the
     671     * communications channel such as baud, character size, etc.
     672     */
     673
     674    return 0;
     675@}
     676@end group
     677@end example
Note: See TracChangeset for help on using the changeset viewer.