Context Navigation

← Previous Changeset
Next Changeset →

Changeset 87894c0 in rtems

Timestamp:

07/11/14 11:29:53 (9 years ago)

Author:

Sebastian Huber <sebastian.huber@…>

Branches:

4.11, 5, master

Children:

6b0a7efc

Parents:

742402b5

git-author:

Sebastian Huber <sebastian.huber@…> (07/11/14 11:29:53)

git-committer:

Sebastian Huber <sebastian.huber@…> (07/21/14 15:43:11)

Message:

doc: Update console driver documentation

File:

: 1 edited

doc/bsp_howto/console.t (modified) (19 diffs)

Legend:

: Unmodified
: Added
: Removed

doc/bsp_howto/console.t

-                      r742402b5
+                      r87894c0
 @section Introduction
 This chapter describes the operation of a console driver using
+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
 …
 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:
+@code{read} or @code{write} system calls.
+There are two main functioning modes:
 @itemize @bullet
 …
 line, tabulations, etc.) recognition and processing,
 @item raw: permits raw data 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.
+of data, but Termios permits having only one driver.
 @section Termios
 …
 Open Group has the termios portion of the POSIX standard online
 at @uref{http://opengroup.org/onlinepubs/007908775/xbd/termios.html
 ,http://opengroup.org/onlinepubs/007908775/xbd/termios.html}.
+,http://opengroup.org/onlinepubs/007908775/xbd/termios.html}.
 The requirements for the @code{<termios.h>} file are also provided
 and are at @uref{http://opengroup.org/onlinepubs/007908775/xsh/termios.h.html,
 …
 @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.
+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.
+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:
+Termios support includes:
 @itemize @bullet
 …
 @item blocking or non-blocking characters receive, with or without
 Timeout.
+Timeout.
 @end itemize
 …
 @section Driver Functioning Modes
 There are generally two main functioning modes for an UART (Universal
 Asynchronous Receiver-Transmitter, i.e. the serial chip):
+There are generally three main functioning modes for an UART (Universal
+Asynchronous Receiver-Transmitter, i.e. the serial chip):
 @itemize @bullet
 …
 @item polled mode
 @item interrupt driven mode
+@item task 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
+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
 …
 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
+of the UART is idle, it is typically necessary to prime the transmitter
 before the first interrupt will occur.
+The task driven mode is similar to interrupt driven mode, but the actual data
+processing is done in dedicated tasks instead of interrupt routines.
 @section Serial Driver Functioning Overview
 The following Figure shows how a Termios driven serial driver works:
+The following Figure shows how a Termios driven serial driver works:
 @ifset use-ascii
 …
 scanf, read, write, etc.),
 @item C library (e.g. RedHat (formerly Cygnus) Newlib) calls
+@item C library (ctx.g. RedHat (formerly Cygnus) Newlib) calls
 the RTEMS system call interface.  This code can be found in the
 @code{cpukit/libcsupport/src} directory.
 @item Glue code calls the serial driver entry routines.
+@file{cpukit/libcsupport/src} directory.
+@item Glue code calls the serial driver entry routines.
 @end itemize
 …
 @subsection Basics
+You need to include the following header files in your Termios device driver
+source file:
+@example
+@group
+#include <unistd.h>
+#include <termios.h>
+#include <rtems.h>
+#include <rtems/libio.h>
+#include <rtems/console.h>
+@end group
+@end example
+You need to provide a data structure for the Termios driver interface.  The
+functions are described later in this chapter.  The functions should return
+zero on succes and minus one in case of an error.  Currently the return value
+will be not checked from the Termios infrastructure in most cases.  One notable
+exception is the polled read function, here is the return value important.
+If you want to use polled IO it should look like the following.  You may also
+have a look at @code{c/src/lib/libbsp/shared/console-polled.c} for a shared
+implementation of the basic framework.  Termios must be told the addresses of
+the functions that are to be used for simple character IO, i.e. pointers to the
+@code{my_driver_poll_read} and @code{my_driver_poll_write} functions described
+later in @ref{Console Driver Termios and Polled IO}.
+@example
+@group
+static const rtems_termios_callbacks my_driver_callbacks_polled = @{
+    .firstOpen = my_driver_first_open,
+    .lastClose = my_driver_last_close,
+    .pollRead = my_driver_poll_read,
+    .write = my_driver_poll_write,
+    .setAttributes = my_driver_set_attributes,
+    .stopRemoteTx = NULL,
+    .startRemoteTx = NULL,
+    .outputUsesInterrupts = TERMIOS_POLLED
+@};
+The low-level driver API changed between RTEMS 4.10 and RTEMS 4.11.  The legacy
+callback API is still supported, but its use is discouraged.  The following
+functions are deprecated:
+@itemize @bullet
+@item @code{rtems_termios_open()} - use @code{rtems_termios_device_open()} in
+combination with @code{rtems_termios_device_install()} instead.
+@item @code{rtems_termios_close()} - use @code{rtems_termios_device_close()}
+instead.
+@end itemize
+This manual describes the new API.  A new console driver should consist of
+three parts.
+@enumerate
+@item The basic console driver functions using the Termios support.  Add this
+the BSPs Makefile.am:
+@example
+@group
+[...]
+libbsp_a_SOURCES += ../../shared/console-termios.c
+[...]
+@end group
+@end example
+@item A general serial module specific low-level driver providing the handler
+table for the Termios @code{rtems_termios_device_install()} function.  This
+low-level driver could be used for more than one BSP.
+@item A BSP specific initialization routine @code{console_initialize()}, that
+calls @code{rtems_termios_device_install()} providing a low-level driver
+context for each installed device.
+@end enumerate
+You need to provide a device handler structure for the Termios device
+interface.  The functions are described later in this chapter.  The first open
+and set attributes handler return a boolean status to indicate success (true)
+or failure (false).  The polled read function returns an unsigned character in
+case one is available or minus one otherwise.
+If you want to use polled IO it should look like the following.  Termios must
+be told the addresses of the handler that are to be used for simple character
+IO, i.e. pointers to the @code{my_driver_poll_read()} and
+@code{my_driver_poll_write()} functions described later in @ref{Console Driver
+Termios and Polled IO}.
+@example
+@group
+const rtems_termios_handler my_driver_handler_polled = @{
+  .first_open = my_driver_first_open,
+  .last_close = my_driver_last_close,
+  .poll_read = my_driver_poll_read,
+  .write = my_driver_poll_write,
+  .set_attributes = my_driver_set_attributes,
+  .stop_remote_tx = NULL,
+  .start_remote_tx = NULL,
+  .mode = TERMIOS_POLLED
+@}
 @end group
 @end example
 …
 For an interrupt driven implementation you need the following.  The driver
 functioning is quite different in this mode.  There is no device driver read
+function to be passed to Termios.  Indeed a @code{console_read} call returns
 the contents of Termios input buffer.  This buffer is filled in the driver
 interrupt subroutine, see also
+@ref{Console Driver Termios and Interrupt Driven IO}.
+The driver is responsible for providing a pointer to the
+@code{my_driver_interrupt_write} function.
 @example
+@group
+static const rtems_termios_callbacks my_driver_callbacks_interrupt = @{
     .firstOpen = my_driver_first_open,
     .lastClose = my_driver_last_close,
     .pollRead = NULL,
     .write = my_driver_interrupt_write,
     .setAttributes = my_driver_set_attributes,
     .stopRemoteTx = NULL,
     .startRemoteTx = NULL,
     .outputUsesInterrupts = TERMIOS_IRQ_DRIVEN
+handler to be passed to Termios.  Indeed a @code{console_read()} call returns the
+contents of Termios input buffer.  This buffer is filled in the driver
+interrupt subroutine, see also @ref{Console Driver Termios and Interrupt Driven
+IO}.  The driver is responsible for providing a pointer to the
+@code{my_driver_interrupt_write()} function.
+@example
+@group
+const rtems_termios_handler my_driver_handler_interrupt = @{
+  .first_open = my_driver_first_open,
+  .last_close = my_driver_last_close,
+  .poll_read = NULL,
+  .write = my_driver_interrupt_write,
+  .set_attributes = my_driver_set_attributes,
+  .stopRemoteTx = NULL,
+  .stop_remote_tx = NULL,
+  .start_remote_tx = NULL,
+  .mode = TERMIOS_IRQ_DRIVEN
 @};
 @end group
 @end example
 You can also provide callback functions for remote transmission control.  This
 is not covered in this manual, so thay are set to @code{NULL} in the above
+You can also provide hander for remote transmission control.  This
+is not covered in this manual, so they are set to @code{NULL} in the above
 examples.
+Normally the device specific data structures are stored in a table which is
+indexed by the minor number.  You may need an entry for the Termios handler
+pointer in your data structure.  For simplicity of the console initialization
+example the device name is also present.
+@example
+@group
+/* Driver specific data structure */
+The low-level driver should provide a data structure for its device context.
+The initialization routine must provide a context for each installed device via
+@code{rtems_termios_device_install()}.  For simplicity of the console
+initialization example the device name is also present.  Her is an example header file.
+@example
+@group
+#ifndef MY_DRIVER_H
+#define MY_DRIVER_H
+#include <rtems/termiostypes.h>
+#include <some-chip-header.h>
+/* Low-level driver specific data structure */
 typedef struct @{
+    const char *device_name;
+    struct rtems_termios_tty *tty;
+@} my_driver_entry;
+/*
+ * This table contains the driver specific data.  It is later
+ * indexed by the minor number.
+ */
+static my_driver_entry my_driver_table [MY_DRIVER_DEVICE_NUMBER];
+  const char *device_name;
+  volatile module_register_block *regs;
+  /* More stuff */
+@} my_driver_context;
+extern const rtems_termios_handler my_driver_handler_polled;
+extern const rtems_termios_handler my_driver_handler_interrupt;
+#endif /* MY_DRIVER_H */
 @end group
 @end example
 …
 @subsection Termios and Polled IO
 The following functions are provided by the driver and invoked by
+The following handler are provided by the low-level driver and invoked by
 Termios for simple character IO.
+The @code{my_driver_poll_write} routine is responsible for writing @code{n}
+characters from @code{buf} to the serial device specified by @code{minor}.
+On success, the number of bytes written is returned (zero indicates nothing
+was written).  On error, @code{-1} is returned.
+NOTE: Due to the current implementation of termios, any data passed into
+  the write function will be lost.
+@example
+@group
+static ssize_t my_driver_poll_write(int minor, const char *buf, size_t n)
+@{
+    my_driver_entry *e = &my_driver_table [minor];
+    int i = 0;
+    /*
+     * There is no need to check the minor number since it is derived
+     * from a file descriptor.  The upper layer takes care that it is
+     * in a valid range.
+     */
+    /* Write */
+    for (i = 0; i < n; ++i) @{
+        my_driver_write_char(e, buf [i]);
+    @}
+    return n;
+The @code{my_driver_poll_write()} routine is responsible for writing @code{n}
+characters from @code{buf} to the serial device specified by @code{tty}.
+@example
+@group
+static void my_driver_poll_write(
+  rtems_termios_tty *tty,
+  const char        *buf,
+  size_t             n
+)
+@{
+  my_driver_context *ctx = rtems_termios_get_device_context(tty);
+  size_t i;
+  /* Write */
+  for (i = 0; i < n; ++i) @{
+    my_driver_write_char(ctx, buf[i]);
+  @}
 @}
 @end group
 …
 The @code{my_driver_poll_read} routine is responsible for reading a single
 character from the serial device specified by @code{minor}.  If no character is
+character from the serial device specified by @code{tty}.  If no character is
 available, then the routine should return minus one.
 @example
 @group
+static int my_driver_poll_read(int minor)
+@{
+    my_driver_entry *e = &my_driver_table [minor];
+    /*
+     * There is no need to check the minor number since it is derived
+     * from a file descriptor.  The upper layer takes care that it is
+     * in a valid range.
+     */
+    /* Check if a character is available */
+    if (my_driver_can_read_char(e)) @{
+        /* Return the character */
+        return my_driver_read_char(e);
+    @} else @{
+        /* Return an error status */
+        return -1;
+    @}
+static int my_driver_poll_read(rtems_termios_tty *tty)
+@{
+  my_driver_context *ctx = rtems_termios_get_device_context(tty);
+  /* Check if a character is available */
+  if (my_driver_can_read_char(ctx)) @{
+    /* Return the character */
+    return my_driver_read_char(ctx);
+  @} else @{
+    /* Return an error status */
+    return -1;
+  @}
 @}
 @end group
 …
 the driver.
 The @code{my_driver_interrupt_handler} is responsible for processing
+The @code{my_driver_interrupt_handler()} is responsible for processing
 asynchronous interrupts from the UART.  There may be multiple interrupt
 handlers for a single UART.  Some UARTs can generate a unique interrupt vector
 …
 transmitter is ready for another character.
 In the simplest case, the @code{my_driver_interrupt_handler} will have to check
+In the simplest case, the @code{my_driver_interrupt_handler()} will have to check
 the status of the UART and determine what caused the interrupt.  The following
 describes the operation of an @code{my_driver_interrupt_handler} which has to
 …
 @group
 static void my_driver_interrupt_handler(
     rtems_vector_number vector,
     void *arg
+  rtems_vector_number  vector,
+  void                *arg
+)
 @{
+    my_driver_entry *e = (my_driver_entry *) arg;
+    char buf [N];
+    int n = 0;
+  rtems_termios_tty *tty = arg;
+  my_driver_context *ctx = rtems_termios_get_device_context(tty);
+  char buf[N];
+  size_t n;
+  /*
+   * Check if we have received something.  The function reads the
+   * received characters from the device and stores them in the
+   * buffer.  It returns the number of read characters.
+   */
+  n = my_driver_read_received_chars(ctx, buf, N);
+  if (n > 0) @{
+    /* Hand the data over to the Termios infrastructure */
+    rtems_termios_enqueue_raw_characters(tty, buf, n);
+  @}
+  /*
+   * Check if we have something transmitted.  The functions returns
+   * the number of transmitted characters since the last write to the
+   * device.
+   */
+  n = my_driver_transmitted_chars(ctx);
+  if (n > 0) @{
     /*
      * Check if we have received something.  The function reads the
      * received characters from the device and stores them in the
      * buffer.  It returns the number of read characters.
+     * Notify Termios that we have transmitted some characters.  It
+     * will call now the interrupt write function if more characters
+     * are ready for transmission.
      */
+    n = my_driver_read_received_chars(e, buf, N);
+    if (n > 0) @{
+        /* Hand the data over to the Termios infrastructure */
+        rtems_termios_enqueue_raw_characters(e->tty, buf, n);
+    @}
+    /*
+     * Check if we have something transmitted.  The functions returns
+     * the number of transmitted characters since the last write to the
+     * device.
+     */
+    n = my_driver_transmitted_chars(e);
+    if (n > 0) @{
+        /*
+         * Notify Termios that we have transmitted some characters.  It
+         * will call now the interrupt write function if more characters
+         * are ready for transmission.
+         */
+        rtems_termios_dequeue_characters(e->tty, n);
+    @}
+@}
+@end group
+@end example
+The @code{my_driver_interrupt_write} function is responsible for telling the
+device that the @code{n} characters at @code{buf} are to be transmitted.  The
+return value may be arbitrary since it is not checked from Termios.  It is
+guaranteed that @code{n} is greater than zero.  This routine is invoked either
+from task context with disabled interrupts to start a new transmission process
+with exactly one character in case of an idle output state or from the
+    rtems_termios_dequeue_characters(tty, n);
+  @}
+@}
+@end group
+@end example
+The @code{my_driver_interrupt_write()} function is responsible for telling the
+device that the @code{n} characters at @code{buf} are to be transmitted.  It
+the value @code{n} is zero to indicate that no more characters are to send.
+The driver can disable the transmit interrupts now.  This routine is invoked
+either from task context with disabled interrupts to start a new transmission
+process with exactly one character in case of an idle output state or from the
 interrupt handler to refill the transmitter.  If the routine is invoked to
 start the transmit process the output state will become busy and Termios starts
 …
 character.
+On error, the function should return @code{-1}. On success, it should return
+@code{0}, since it the interrupt handler will report the actual number of
+characters transmitted.
+@example
+@group
+static ssize_t my_driver_interrupt_write(int minor, const char *buf, size_t n)
+@{
+    my_driver_entry *e = &my_driver_table [minor];
+@example
+@group
+static void my_driver_interrupt_write(
+  rtems_termios_tty *tty,
+  const char        *buf,
+  size_t             n
+)
+@{
+  my_driver_context *ctx = rtems_termios_get_device_context(tty);
+  /*
+   * Tell the device to transmit some characters from buf (less than
+   * or equal to n).  When the device is finished it should raise an
+   * interrupt.  The interrupt handler will notify Termios that these
+   * characters have been transmitted and this may trigger this write
+   * function again.  You may have to store the number of outstanding
+   * characters in the device data structure.
+   */
+  /*
+   * Termios will set n to zero to indicate that the transmitter is
+   * now inactive.  The output buffer is empty in this case.  The
+   * driver may disable the transmit interrupts now.
+   */
+@}
+@end group
+@end example
+@subsection Initialization
+The BSP specific driver initialization is called once during the RTEMS
+initialization process.
+The @code{console_initialize()} function may look like this:
+@example
+@group
+#include <my-driver.h>
+#include <rtems/console.h>
+#include <bsp.h>
+#include <bsp/fatal.h>
+static my_driver_context driver_context_table[M] = @{ /* Some values */ @};
+rtems_device_driver console_initialize(
+  rtems_device_major_number  major,
+  rtems_device_minor_number  minor,
+  void                      *arg
+)
+@{
+  rtems_status_code sc;
+#ifdef SOME_BSP_USE_INTERRUPTS
+  const rtems_termios_handler *handler = &my_driver_handler_interrupt;
+#else
+  const rtems_termios_handler *handler = &my_driver_handler_polled;
+#endif
+  /*
+   * Initialize the Termios infrastructure.  If Termios has already
+   * been initialized by another device driver, then this call will
+   * have no effect.
+   */
+  rtems_termios_initialize();
+  /* Initialize each device */
+  for (
+    minor = 0;
+    minor < RTEMS_ARRAY_SIZE(driver_context_table);
+    ++minor
+  ) @{
+    my_driver_context *ctx = &driver_context_table[minor];
     /*
+     * There is no need to check the minor number since it is derived
+     * from a file descriptor.  The upper layer takes care that it is
+     * in a valid range.
+     * Install this device in the file system and Termios.  In order
+     * to use the console (i.e. being able to do printf, scanf etc.
+     * on stdin, stdout and stderr), one device must be registered as
+     * "/dev/console" (CONSOLE_DEVICE_NAME).
      */
     /*
      * Tell the device to transmit some characters from buf (less than
      * or equal to n).  When the device is finished it should raise an
      * interrupt.  The interrupt handler will notify Termios that these
      * characters have been transmitted and this may trigger this write
      * function again.  You may have to store the number of outstanding
      * characters in the device data structure.
      */
     /*
+     * Termios will set n to zero to indicate that the transmitter is
      * now inactive.  The output buffer is empty in this case.  The
+     * driver may disable the transmit interrupts now.
+     */
+    return 0;
 @}
+@end group
+@end example
 @subsection Initialization
+The driver initialization is called once during the RTEMS initialization
+process.
+The @code{console_initialize} function may look like this:
+@example
 @group
+rtems_device_driver console_initialize(
+    rtems_device_major_number major,
     rtems_device_minor_number minor,
     void *arg
+    sc = rtems_termios_device_install(
+      ctx->device_name,
+      major,
+      minor,
+      handler,
+      ctx
+    );
+    if (sc != RTEMS_SUCCESSFUL) @{
+      bsp_fatal(SOME_BSP_FATAL_CONSOLE_DEVICE_INSTALL);
+    @}
+  @}
+  return RTEMS_SUCCESSFUL;
+@}
+@end group
+@end example
+@subsection Opening a serial device
+The @code{console_open()} function provided by @file{console-termios.c} is
+called whenever a serial device is opened.  The device registered as
+@code{"/dev/console"} (@code{CONSOLE_DEVICE_NAME}) is opened automatically
+during RTEMS initialization.  For instance, if UART channel 2 is registered as
+@code{"/dev/tty1"}, the @code{console_open()} entry point will be called as the
+result of an @code{fopen("/dev/tty1", mode)} in the application.
+During the first open of the device Termios will call the
+@code{my_driver_first_open()} handler.
+@example
+@group
+static bool my_driver_first_open(
+  rtems_termios_tty             *tty,
+  rtems_libio_open_close_args_t *args
+)
 @{
+    rtems_status_code sc = RTEMS_SUCCESSFUL;
+    rtems_device_minor_number i = 0;
+    /*
+     * Initialize the Termios infrastructure.  If Termios has already
+     * been initialized by another device driver, then this call will
+     * have no effect.
+     */
+    rtems_termios_initialize();
+    /* Initialize each device */
+    for (i = 0; i < MY_DRIVER_DEVICE_NUMBER; ++i) @{
+        my_driver_entry *e = &my_driver_table [i];
+        /*
+         * Register this device in the file system.  In order to use the
+         * console (i.e. being able to do printf, scanf etc. on stdin,
+         * stdout and stderr), some device must be registered
+         * as "/dev/console" (CONSOLE_DEVICE_NAME).
+         */
+        sc = rtems_io_register_name (e->device_name, major, i);
+        RTEMS_CHECK_SC(sc, "Register IO device");
+        /*
+         * Initialize this device and install the interrupt handler if
+         * necessary.  You may also initialize the device in the first
+         * open call.
+         */
+    @}
+    return RTEMS_SUCCESSFUL;
+@}
+@end group
+@end example
+@subsection Opening a serial device
+The @code{console_open} function is called whenever a serial device is opened.
+The device registered as @code{"/dev/console"} (@code{CONSOLE_DEVICE_NAME}) is
+opened automatically during RTEMS initialization.  For instance, if UART
+channel 2 is registered as "/dev/tty1", the @code{console_open} entry point
+will be called as the result of an @code{fopen("/dev/tty1", mode)} in the
+application.
+The @code{console_open} function has to inform Termios of the low-level
+functions for serial line support.
+@example
+@group
+rtems_device_driver console_open(
+    rtems_device_major_number major,
+    rtems_device_minor_number minor,
+    void *arg
+  my_driver_context *ctx = rtems_termios_get_device_context(tty);
+  rtems_status_code sc;
+  bool ok;
+  /*
+   * You may add some initialization code here.
+   */
+  /*
+   * Sets the initial baud rate.  This should be set to the value of
+   * the boot loader.  This function accepts only exact Termios baud
+   * values.
+   */
+  sc = rtems_termios_set_initial_baud(tty, MY_DRIVER_BAUD_RATE);
+  if (sc != RTEMS_SUCCESSFUL) @{
+    /* Not a valid Termios baud */
+  @}
+  /*
+   * Alternatively you can set the best baud.
+   */
+  rtems_termios_set_best_baud(tty, MY_DRIVER_BAUD_RATE);
+  /*
+   * To propagate the initial Termios attributes to the device use
+   * this.
+   */
+  ok = my_driver_set_attributes(tty, rtems_termios_get_termios(tty));
+  if (!ok) @{
+    /* This is bad */
+  @}
+  /*
+   * Return true to indicate a successful set attributes, and false
+   * otherwise.
+   */
+  return true;
+@}
+@end group
+@end example
+@subsection Closing a Serial Device
+The @code{console_close()} provided by @file{console-termios.c} is invoked when
+the serial device is to be closed.  This entry point corresponds to the device
+driver close entry point.
+Termios will call the @code{my_driver_last_close()} handler if the last close
+happens on the device.
+@example
+@group
+static void my_driver_last_close(
+  rtems_termios_tty             *tty,
+  rtems_libio_open_close_args_t *args
+)
 @{
+    struct rtems_termios_callbacks *callbacks =
+        &my_driver_callbacks_polled;
+    /*
+     * Check the minor number.  Termios does currently not check
+     * the return value of the first open call so the minor
+     * number must be checked here.
+     */
+    if (MY_DRIVER_IS_MINOR_INVALID(minor)) @{
+        return RTEMS_INVALID_NUMBER;
+    @}
+    /*
+     * Depending on the IO mode you need to pass a different set of
+     * callback functions to Termios.
+     */
+    if (MY_DRIVER_USES_INTERRUPTS(minor)) @{
+        callbacks = &my_driver_callbacks_interrupt;
+    @}
+    return rtems_termios_open(major, minor, arg, callbacks);
+@}
+@end group
+@end example
+During the first open of the device Termios will call @code{my_driver_first_open}.
+@example
+@group
+static int my_driver_first_open(int major, int minor, void *arg)
+@{
+    my_driver_entry *e = &my_driver_table [minor];
+    struct rtems_termios_tty *tty =
+        ((rtems_libio_open_close_args_t *) arg)->iop->data1;
+    /* Check minor number */
+    if (MY_DRIVER_IS_MINOR_INVALID(minor)) @{
+        return -1;
+    @}
+    /* Connect the TTY data structure */
+    e->tty = tty;
+    /*
+     * You may add some initialization code here.
+     */
+    /*
+     * Sets the inital baud rate.  This should be set to the value of
+     * the boot loader.
+     */
+    return rtems_termios_set_initial_baud(e->tty, MY_DRIVER_BAUD_RATE);
+@}
+@end group
+@end example
+@subsection Closing a Serial Device
+The @code{console_close} is invoked when the serial device is to be closed.
+This entry point corresponds to the device driver close entry point.
+This routine is responsible for notifying Termios that the serial device was
+closed.  This is done with a call to @code{rtems_termios_close}.
+@example
+@group
+rtems_device_driver console_close(
+    rtems_device_major_number major,
+    rtems_device_minor_number minor,
+    void *arg
+  my_driver_context *ctx = rtems_termios_get_device_context(tty);
+  /*
+   * The driver may do some cleanup here.
+   */
+@}
+@end group
+@end example
+@subsection Reading Characters from a Serial Device
+The @code{console_read()} provided by @file{console-termios.c} is invoked when
+the serial device is to be read from.  This entry point corresponds to the
+device driver read entry point.
+@subsection Writing Characters to a Serial Device
+The @code{console_write()} provided by @file{console-termios.c} is invoked when
+the serial device is to be written to.  This entry point corresponds to the
+device driver write entry point.
+@subsection Changing Serial Line Parameters
+The @code{console_control()} provided by @file{console-termios.c} is invoked
+when the line parameters for a particular serial device are to be changed.
+This entry point corresponds to the device driver IO control entry point.
+The application writer is able to control the serial line configuration with
+Termios calls (such as the @code{ioctl()} command, see the Termios
+documentation for more details).  If the driver is to support dynamic
+configuration, then it must have the @code{console_control()} piece of code.
+Basically @code{ioctl()} commands call @code{console_control()} with the serial
+line configuration in a Termios defined data structure.
+The driver is responsible for reinitializing the device with the correct
+settings.  For this purpose Termios calls the @code{my_driver_set_attributes()}
+handler.
+@example
+@group
+static bool my_driver_set_attributes(
+  rtems_termios_tty    *tty,
+  const struct termios *term
+)
 @{
+    return rtems_termios_close(arg);
+@}
+@end group
+@end example
+Termios will call the @code{my_driver_last_close} function if the last close
+happens on the device.
+@example
+@group
+static int my_driver_last_close(int major, int minor, void *arg)
+@{
+    my_driver_entry *e = &my_driver_table [minor];
+    /*
+     * There is no need to check the minor number since it is derived
+     * from a file descriptor.  The upper layer takes care that it is
+     * in a valid range.
+     */
+    /* Disconnect the TTY data structure */
+    e->tty = NULL;
+    /*
+     * The driver may do some cleanup here.
+     */
+    return 0;
+@}
+@end group
+@end example
+@subsection Reading Characters from a Serial Device
+The @code{console_read} is invoked when the serial device is to be read from.
+This entry point corresponds to the device driver read entry point.
+This routine is responsible for returning the content of the Termios input
+buffer.  This is done by invoking the @code{rtems_termios_read} routine.
+@example
+@group
+rtems_device_driver console_read(
+    rtems_device_major_number major,
+    rtems_device_minor_number minor,
+    void *arg
+)
+@{
+    return rtems_termios_read(arg);
+@}
+@end group
+@end example
+@subsection Writing Characters to a Serial Device
+The @code{console_write} is invoked when the serial device is to be written to.
+This entry point corresponds to the device driver write entry point.
+This routine is responsible for adding the requested characters to the Termios
+output queue for this device.  This is done by calling the routine
+@code{rtems_termios_write} to add the characters at the end of the Termios
+output buffer.
+@example
+@group
+rtems_device_driver console_write(
+    rtems_device_major_number major,
+    rtems_device_minor_number minor,
+    void *arg
+)
+@{
+    return rtems_termios_write(arg);
+@}
+@end group
+@end example
+@subsection Changing Serial Line Parameters
+The @code{console_control} is invoked when the line parameters for a particular
+serial device are to be changed.  This entry point corresponds to the device
+driver io_control entry point.
+The application writer is able to control the serial line configuration with
+Termios calls (such as the @code{ioctl} command, see the Termios documentation
+for more details).  If the driver is to support dynamic configuration, then it
+must have the @code{console_control} piece of code.  Basically @code{ioctl}
+commands call @code{console_control} with the serial line configuration in a
+Termios defined data structure.
+@example
+@group
+rtems_device_driver console_control(
+    rtems_device_major_number major,
+    rtems_device_minor_number minor,
+    void *arg
+)
+@{
+    return rtems_termios_ioctl(arg);
+@}
+@end group
+@end example
+The driver is responsible for reinitializing the device with the correct
+settings.  For this purpuse Termios calls the @code{my_driver_set_attributes}
+function.
+@example
+@group
+static int my_driver_set_attributes(
+    int minor,
+    const struct termios *t
+)
+@{
+    my_driver_entry *e = &my_driver_table [minor];
+    /*
+     * There is no need to check the minor number since it is derived
+     * from a file descriptor.  The upper layer takes care that it is
+     * in a valid range.
+     */
+    /*
+     * Inspect the termios data structure and configure the device
+     * appropriately.  The driver should only be concerned with the
+     * parts of the structure that specify hardware setting for the
+     * communications channel such as baud, character size, etc.
+     */
+    return 0;
+@}
+@end group
+@end example
+  my_driver_context *ctx = rtems_termios_get_device_context(tty);
+  /*
+   * Inspect the termios data structure and configure the device
+   * appropriately.  The driver should only be concerned with the
+   * parts of the structure that specify hardware setting for the
+   * communications channel such as baud, character size, etc.
+   */
+  /*
+   * Return true to indicate a successful set attributes, and false
+   * otherwise.
+   */
+  return true;
+@}
+@end group
+@end example

Note: See TracChangeset for help on using the changeset viewer.

Context Navigation

Changeset 87894c0 in rtems

Legend:

doc/bsp_howto/console.t

Download in other formats: