8250 Serial Driver

This chapter includes:

• Creating a serial driver
• Registers
• Source code

Creating a serial driver

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

• If your serial hardware is completely compatible with the 8250, you might not have to change anything.
• If your hardware is almost compatible with the 8250, you might have to change the register addresses. See “Registers,” below.
• If compatibility is in question, you may have to change the source code. See “Source code,” below.

---

On a modem disconnect, libio-char.a triggers an io_read for every client blocked on a read() call. The client's read() call returns with 0 (EOF). Make sure that your clients explicitly check for a return of EOF, instead of simply calling read() repeatedly if the number of bytes is less than expected.

---

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:

• the register addresses, specified as offsets from the port address that you set when you start the devc-ser8250 driver
• bit definitions for the registers.

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 a byte, called by io-char. It also provides support to control and read hardware control lines status, and provides support for the stty utility. io-char down call that uses the stty command to send output such as line ctrl and line status to the hardware.

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

<sys_ttyinit.c>

Initialize the tty structure that the driver passes to io-char.

---

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:

• A character arrives at the chip. This character is added to the input queue.

  If the device is in edited mode, the character is also added to the canonical queue. Typically, the driver doesn't worry about raw and edited modes; io-char handles them.

• The chip's transmission buffer is ready for a character.
• A modem-control signal (e.g. hardware flow control) is received.
• An error (e.g. line status, parity error, or framing error) occurs.

Functions

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

• create_device()
• options()
• query_default_device()
• ser_intr()
• ser_stty()
• sys_ttyinit()
• tto()

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

• ttc() with an argument of TTC_INIT_PROC to allocate and configure the resources shared by all devices, e.g. the resource manager.
• ttc() with an argument of TTC_INIT_START to allow the driver to start accepting messages, i.e. work.
• options() to parse the driver's command-line options.

create_device()

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

void create_device( TTYINIT *dip,
                    unsigned unit )

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

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:

• ttc() with an argument of TTC_INIT_RAW to configure the terminal to RAW mode.
• sys_ttyinit() to initialize the tty as appropriate for the CPU platform.
• ttc() with an argument of TTC_SET_OPTION to pass standard terminal configuration options to <libio-char.a> to be executed.
• create_device() to create a device.
• query_default_device() to query the default devices if none is specified on the command line.

The options() function returns the number of ports.

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 Library Reference) to attach ser_intr() to the first handler.

The ser_intr() function calls:

• tti() to pass a character of data received by the hardware to the io-char library.
• tto() to transmit a character by taking the next available byte in the io-char lib output buffer and writing it to the hardware.

ser_stty()

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

void ser_stty( DEV_8250 *dev )

This function configures hardware registers and settings such as baud rate, parity, etc.

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 ctrl and line status information.

The arguments are:

ttydev

A pointer to the driver's TTYDEV structure.

action

One of:

• TTO_STTY — an stty command was received. It's called by io-char when the stty command is performed on the device. This action calls ser_stty(); the argument is ignored.
• TTO_CTRL — set the characteristics of the port i.e. control RS-232 modem lines.
  • arg1 _SERCTL_BRK_CHG — called by io-char when the application requests a break such as tcsendbreak() to be sent
  • arg1 _SERCTL_DTR_CHG — changes the DTR line
  • arg1 _SERCTL_RTS_CHG — used to change the RTS line; io-char calls this to assert hardware flow control when the input buffer is filling up (based on the high-water level)
• TTO_LINESTATUS — a request for line status. Returns the status of the Modem Status and Modem Control registers when the user performs a devctl() with DCMD_CHR_LINESTATUS; the argument is ignored.
• TTO_DATA — output transmit data.
• TTO_EVENT — ignored.

arg1

A data value which has different meanings for different actions. It's used to pass flags that modify the action.