8250 Serial Driver

This chapter includes:

Creating a serial driver

The Character DDK currently includes the source code for the 8250 serial driver. You may not have to change much:

Registers

You'll find the register addresses defined in ddk_working_dir/ddk-char/src/hardware/devc/public/hw/8250.h.

The <8250.h> file defines:

See the documentation for your hardware for information about its registers and bit definitions.

Source code

The source code for the 8250 serial driver is in ddk_working_dir/ddk-char/src/hardware/devc/ser8250. This directory includes:

externs.c
Defines the global data.
externs.h
Includes the required headers and declares the global data.
init.c
Initialization code.
intr.c
Interrupt handler routines.
main.c
The main part of the driver.
options.c
Parses the driver's command-line arguments.
proto.h
Prototypes for the driver's interface routines.
query_defdev.c
Queries the default devices. Note that there's a special version of this routine for x86 desktop systems in x86/query_defdev.c. For other platforms, there aren't any default devices.
tedit.c
The tiny edit-mode routine.
tto.c
A routine to transmit up to the TX FIFO SIZE worth of data, called by io-char. It also provides support to control and read hardware-control lines status, and provides support for the stty utility. If there's no TX FIFO, tto() writes only a single character.
variant.h
A header file that defines the two macros to read/write the 8250. This file can be overwritten for different boards with their own read/write macros.

There are also platform-specific directories, each of which includes:

<sys_ttyinit.c>
Initialize the tty structure that the driver passes to io-char.

Note: Change as little of the given source code as possible, because it's easy to mess things up.

The most important parts of the code are those associated with output and interrupts.

Interrupts

Different chips use interrupts in different ways. Typically, interrupts occurs when:

The driver code adds characters only to the Input queue/buffer. The Canonical buffer is handled by io-char and is manipulated when the client read request is handled.

Functions

The ser8250 driver includes the following functions, defined in proto.h:

The driver's main() routine (defined in main.c) calls:

create_device()

This function is defined in init.c and is called by options(). The prototype is:

DEV_8250 *create_device(TTYINIT *dip, 
                        unsigned unit);

This function gets a device entry and its input/output buffers and creates a new device based on the options passed in.

enable_device()

This function is defined in init.c. The prototype is:

int enable_device( DEV_8250 *dev)

This function enables all the serial ports. You must call it for each port before returning from options() to complete the port initialization.

options()

This function is defined in options.c. The prototype is:

unsigned options( int argc,
                  char *argv[] )

This function parses the driver's command-line arguments. For information about the arguments, see devc-ser8250 in the Utilities Reference.

Depending on the options specified, this function may call:

The options() function returns the number of ports that are enabled.

query_default_device()

This function is defined in query_defdev.c. The prototype is:

void *query_default_device(TTYINIT *dip,
                           void *link )

This function returns a placeholder that's used for overwrites in the platform directory.

ser_intr()

This function is defined in intr.c. The prototype is:

const struct sigevent *ser_intr( void *area,
                                 int id )

The ser_attach_intr() function, which is called by create_device(), calls InterruptAttach() (see the QNX Neutrino Library Reference) to attach ser_intr() to the first handler. If you don't want to transmit at interrupt time, then you can set the EVENT_TTO event and return. This will trigger io-char's tte() function to call into tto() at thread time rather then interrupt time.

The ser_intr() function calls:

ser_stty()

This function is defined in tto.c. The prototype is:

void ser_stty( DEV_8250 *dev )

This function configures registers that can be changed dynamically at runtime (baud, parity, stop bits, etc.). Don't use this function for any initialization that you need to do when first setting up the driver; use create_device() instead.

set_port()

This function is defined in <init.c>. The prototype is:

void set_port( unsigned port,
               unsigned mask,
               unsigned data )

This function sets the specified bit(s) of the UART port to the given value (0 or 1). The arguments are:

port
The port you want to write the value to.
mask
The mask for the bit or bits that you want to set.
data
The value that you want to set.

sys_ttyinit()

This function is defined in <sys_ttyinit.c> in the platform-specific directories under ddk_working_dir/ddk-char/src/hardware/devc/ser8250.

The prototype is:

void sys_ttyinit( TTYINIT *dip )

This function initializes the TTYINIT clock and divisor default as appropriate for the platform.

tto()

This function is defined in tto.c. The prototype is:

int tto( TTYDEV *ttydev,
         int action,
         int arg1 )

This function takes data from io-char's output buffer and gives it to the hardware. It also deals with stty commands, by calling ser_stty(), and provides line control and line status information.

The arguments are:

ttydev
A pointer to the driver's TTYDEV structure.
action
One of:
arg1
A data value which has different meanings for different actions. It's used to pass flags that modify the action.