DevTab Entry

The interface module contains the devtab entry (or entries if a single module supports more than one interface). This entry should have the form:

DEVTAB_ENTRY(<<module_name>>, 
             <<device_name>>,
             0,
             &serial_devio, 
             <<module_init>>, 
             <<module_lookup>>,
             &<<serial_channel>>
            );

Serial Channel Structure

Each serial device must have a “serial channel”. This is a set of data which describes all operations on the device. It also contains buffers, etc., if the device is to be buffered. The serial channel is created by the macro:

SERIAL_CHANNEL_USING_INTERRUPTS(l, funs, dev_priv, baud,stop, parity, word_length,
                                flags, out_buf, out_buflen, in_buf, in_buflen)

If either buffer length is zero, no buffering will take place in that direction and only polled mode functions will be used.

The interface from the hardware independent driver into the hardware interface module is contained in the funs table. This is defined by the macro:

Serial Functions Structure

SERIAL_FUNS(l, putc, getc, set_config, start_xmit, stop_xmit)

Callbacks

The device interface module can execute functions in the hardware independent driver via chan->callbacks. These functions are available:

void (*serial_init)( serial_channel *chan )

This function is used to initialize the serial channel. It is only required if the channel is being used in interrupt mode.

void (*xmt_char)( serial_channel *chan )

This function would be called from an interrupt handler after a transmit interrupt indicating that additional characters may be sent. The upper driver will call the putc function as appropriate to send more data to the device.

void (*rcv_char)( serial_channel *chan, unsigned char c )

This function is used to tell the driver that a character has arrived at the interface. This function is typically called from the interrupt handler.

Furthermore, if the device has a FIFO it should require the hardware independent driver to provide block transfer functionality (driver CDL should include "implements CYGINT_IO_SERIAL_BLOCK_TRANSFER"). In that case, the following functions are available as well:

xmt_req_reply_t (*data_xmt_req)(serial_channel *chan,
                     int space,
                     int* chars_avail,
                     unsigned char** chars)
void (*data_xmt_done)(serial_channel *chan, int chars_sent)

Instead of calling xmt_char() to get a single character for transmission at a time, the driver should call data_xmt_req() in a loop, requesting character blocks for transfer. Call with a space argument of how much space there is available in the FIFO.

If the call returns true, the driver can read chars_avail characters from chars and copy them into the FIFO.

If the call returns false, there are no more buffered characters and the driver should continue without filling up the FIFO.

When all data has been unloaded, the driver must call data_xmt_done().

rcv_req_reply_t (*data_rcv_req)(serial_channel *chan,
                     int avail,
                     int* space_avail,
                     unsigned char** space)
void (*data_rcv_done)(serial_channel *chan, int chars_rcvd)

Instead of calling rcv_char() with a single character at a time, the driver should call data_rcv_req() in a loop, requesting space to unload the FIFO to. avail is the number of characters the driver wishes to unload.

If the call returns true, the driver can copy space_avail characters to space.

If the call returns false, the input buffer is full. It is up to the driver to decide what to do in that case (callback functions for registering overflow are being planned for later versions of the serial driver).

When all data has been unloaded, the driver must call data_rcv_done().