RTEMS 4.9.2 On-Line Library

Console Driver Basics

BSP and Device Driver Development Guide

8.4.1: Basics

You need to include the following header files in your Termios device driver source file:

#include <unistd.h>
#include <termios.h>

#include <rtems.h>
#include <rtems/libio.h>
#include <rtems/console.h>

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 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 my_driver_poll_read and my_driver_poll_write functions described later in Console Driver Termios and Polled IO.

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

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 console_read call returns the contents of Termios input buffer. This buffer is filled in the driver interrupt subroutine, see also Console Driver Termios and Interrupt Driven IO. The driver is responsible for providing a pointer to the my_driver_interrupt_write function.

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

You can also provide callback functions for remote transmission control. This is not covered in this manual, so thay are set to 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.

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

BSP and Device Driver Development Guide