8. Console Driver¶

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
}

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
};

#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 {
  rtems_termios_device_context base;
  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 */

static void my_driver_poll_write(
  rtems_termios_device_context *base,
  const char                   *buf,
  size_t                        n
)
{
  my_driver_context *ctx = (my_driver_context *) base;
  size_t i;
  /* Write */
  for (i = 0; i < n; ++i) {
    my_driver_write_char(ctx, buf[i]);
  }
}

static int my_driver_poll_read(rtems_termios_device_context *base)
{
  my_driver_context *ctx = (my_driver_context *) base;
  /* 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;
  }
}

static void my_driver_interrupt_handler(
  rtems_vector_number  vector,
  void                *arg
)
{
  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) {
    /*
     * 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(tty, n);
  }
}

static void my_driver_interrupt_write(
  rtems_termios_device_context  *base,
  const char                    *buf,
  size_t                         n
)
{
  my_driver_context *ctx = (my_driver_context *) base;

  /*
   * 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.
   */
}

#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];

    /*
     * 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).
     */
    sc = rtems_termios_device_install(
      ctx->device_name,
      major,
      minor,
      handler,
      NULL,
      ctx
    );
    if (sc != RTEMS_SUCCESSFUL) {
      bsp_fatal(SOME_BSP_FATAL_CONSOLE_DEVICE_INSTALL);
    }
  }

  return RTEMS_SUCCESSFUL;
}

static bool my_driver_first_open(
  rtems_termios_tty             *tty,
  rtems_termios_device_context  *base,
  struct termios                *term,
  rtems_libio_open_close_args_t *args
)
{
  my_driver_context *ctx = (my_driver_context *) base;
  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(term, MY_DRIVER_BAUD_RATE);

  /*
   * To propagate the initial Termios attributes to the device use
   * this.
  */
  ok = my_driver_set_attributes(base, term);
  if (!ok) {
    /* This is bad */
  }

  /*
   * Return true to indicate a successful set attributes, and false
   * otherwise.
   */
  return true;
}

static void my_driver_last_close(
  rtems_termios_tty             *tty,
  rtems_termios_device_context  *base,
  rtems_libio_open_close_args_t *args
)
{
  my_driver_context *ctx = (my_driver_context *) base;

  /*
   * The driver may do some cleanup here.
  */
}

static bool my_driver_set_attributes(
  rtems_termios_device_context *base,
  const struct termios         *term
)
{
  my_driver_context *ctx = (my_driver_context *) base;

  /*
   * 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;
}