SS(7) RISC/os Reference Manual SS(7)
NAME
ss - common streams serial device interface
DESCRIPTION
This is the common upper level code for serial devices.
These upper level routines will handle line discipline,
ioctl, handshaking whether hardware (RTS/CTS, DTR) or
software (XON/XOFF), parsing ioctl commands, and most other
functionality that is common to all serial devices. The
driver provides entry points for device specific functions
such as outputting and inputting characters, and performing
modem control. This document is meant as a guide on how to
create a device driver that will interface to the common
streams device interface.
By moving much of the code common to most serial devices out
of the device drivers, the amount of device dependent code
has been greatly reduced. Drivers no longer have to imple-
ment line discipline, ioctls, or signal handling. The
driver is also (hopefully) easier to implement.
The ss subsystem provides common data structures to use for
each serial line and controller. ss also provides pointers
within the common line data structures to point to whatever
device-specific data is needed by each particular port.
The following relevant structures are found in ss.h and
stream.h:
Driver entry points:
The ss_devdep_info structure provides ss with entry points
into the driver. Not all entry points are required since
the functionality can be achieved through combinations of
calls to other entry points. Entries that are not provided
must be set to NULL.
struct ss_devdep_info XXdd = {
char *ssdd_devname; /* Name of the device, for interest */
int ssdd_dev_type; /* SS_TTY, SS_OTHER... */
int ssdd_maxboards; /* MAX number of this type of board */
int ssdd_maxlines; /* # of ports on per board */
int ssdd_maxoutc; /* max chars that outc can take at one time */
int (*ssdd_act)(); /* Hardware, activate line */
int (*ssdd_zap)(); /* Hardware, deactivate line */
int (*ssdd_outc)(); /* Hardware, output characters */
int (*ssdd_setline)();/* Hardware, set line params */
int (*ssdd_modem_control)(); /* modem control operations */
int (*ssdd_driver_control)(); /* driver control operations */
};
Printed 11/19/92 Page 1
SS(7) RISC/os Reference Manual SS(7)
int XXXact(ssl)
struct ssline *ssl;
Activate a specific line and set modem status bits in
ss_modem_state. This is an optional entry point. ss
will first call this function, if it exists, and then
unconditionally call
XXX_driver_control(ssl,SS_DC_ENABLE_LINE,0). If the
function does not exist (i.e. *ssdd_act == NULL) the
SS_DC_ENABLE_LINE functionality must leave the port in
a usable state. In either case, ss_modem_state must be
set to contain the current modem status of the port on
return from the SS_DC_ENABLE_LINE command.
int XXXzap(ssl)
struct ssline *ssl;
Close a port. This is an optional entry point. If it
does not exist (i.e. *ssdd_zap == NULL), ss will call
XXX_modem_control(SS_MC_STOPBREAK),
XXX_modem_control(SS_MC_DISABLE_DTR) and
XXX_driver_control(SS_DC_DISABLELINE) in that order.
int XXXoutc(ssl, s, len)
struct ssline *ssl;
char *s;
int len;
Output len characters pointed to by s on line ssl. len
is guaranteed to be <= ssdd_maxoutc.
int XXXsetline(ssl,cflag,termio)
struct ssline *ssl;
int cflag;
struct termio *termio;
Responsible for all settings in the termio.cflag field.
The target cflag is passed in. The termio struct is
also passed in, but may be ignored. Any return status
other than 0 is passed back to the user as an error.
int XXXmodemcontrol(ssl,command,value)
struct ssline *ssl;
int command;
int value;
Handle modem control commands. One of these parameters
will be passed in:
SS_MC_STARTBREAK Start sending break
SS_MC_STOPBREAK Stop sending break
SS_MC_ENABLEFLOW Turn on RTS
Page 2 Printed 11/19/92
SS(7) RISC/os Reference Manual SS(7)
SS_MC_DISABLEFLOW
Turn off RTS
SS_MC_ENABLEDTR Turn on DTR
SS_MC_DISABLEDTR Turn off DTR
The value field is not currently used.
int XXXdrivercontrol(ssl,command,value)
struct ssline *ssl;
int command;
int value;
Handle driver control commands. One of these parame-
ters will be passed in:
SS_DC_SDRVFLUSH flush all output. This
includes any data still in
hardware and software buffers.
SS_DC_DRAINOUTPUT flush all output, may sleep
SS_DC_TIOCSWINSZ
SS_DC_TIOCOUTQ return number of chars queued
for output
SS_DC_STOP tell hardware to stop
transmitting
SS_DC_SUSPEND_OUTPUT
stop transmitting
SS_DC_DISABLELINE unconfigure this line, drop
modem signals, stop polling
etc.
SS_DC_ENABLELINE turn on a line, set
modem_state
SS_DC_RESUME_OUTPUT resume output
SS_DC_M_IOCTL a device specific ioctl.
SS_DC_FLOWCNTL passes termio structure to
driver for changes to the
iflag word if the hardware
device supports flow control.
ENTRY POINTS
These are the entry points provided by ss. They are grouped
according to which driver functionality usually uses them.
open routine
ssopen (ssl, rq, dev, flag, sflag, cflag)
This is called from the device driver open routine.
ss_open will call the drivers' modem_control and
driver_control routines to set up default tty settings.
transmit interrupt routine
sstx(ssl)
Should be called from the transmit interrupt routine of
the driver. This starts transmission of the next
Printed 11/19/92 Page 3
SS(7) RISC/os Reference Manual SS(7)
character.
receive interrupt routine
The receive interrupt routine is responsible for error
checking (i.e. parity, buffer overflow, framing etc), and
simple XON-XOFF checking.
ssstartstop (ssl, c)
Handles incoming XON and XOFF characters. ss_startstop
returns false if the character was a start or stop
character; the character can then be ignored. This
should be called prior to any character manipulation by
the driver.
ssslowr (ssl, c)
Used to insert artificial characters into the input
stream. Its only current use is to insert a 0377 and
'0' byte into the input stream when PARMRK is set to
mark parity errors, which the driver must do.
ssinc (ssl, c)
Enqueues the received character onto the input queue.
ssmksig(ssl, signal)
Called to send a signal to the user process (i.e. when
a break is detected and user has the BRKINT bit of
termio.iflags set).
ssctson(ssl)
Called when Clear To Send changes to true.
ssctsoff(ssl)
Called when Clear To Send changes to false.
sscon(ssl)
Called when Carrier Detect changes to true.
sscoff(ssl)
Called when Carrier Detect changes to false.
miscellaneous
sswaitfornotbusy(ssl)
Sleeps until the port is no longer busy (i.e. ss_state
& SS_BUSY == 0). Useful when flushing a port.
FLOW CONTROL
All hardware flow control is handled by ss. The driver is
responsible for informing ss of modem status changes through
ss_con, ss_coff, ss_cts_on, and ss_cts_off.
Software flow control (XON/XOFF) is done by ss but the
driver needs to be aware of it. When ss sends an XON or
Page 4 Printed 11/19/92
SS(7) RISC/os Reference Manual SS(7)
XOFF, it is not sent in the streams write buffer. Therefore
the driver should not increment its character counts or
advance its buffer pointers if the sent characters were XON
or XOFF. The driver should check this by checking the
SS_XBUSY bit.
All input characters must be handled by the ss_startstop()
routine.
LINE DISCIPLINE AND SIGNAL HANDLING
All line discipline and signal handling is handled by ss.
REQUIRED DATA STRUCTURES
The following structures are required to properly initialize
ss and streams.
/* Initialize read side stream */
static struct qinit XX_rinit = {
NULL;
ss_rsrv; /* ss service procedure */
XX_open; /* your open procedure */
ss_close; /* ss finish procedure */
NULL;
&XX_str_info;/* module information structure */
NULL;
};
/* Initialize write side stream */
static struct qinit XX_winit = {
ss_wput; /* ss put procedure */
NULL; NULL;
NULL; NULL;
&XX_str_info;/* module information structure */
NULL;
};
/* Tie the two together */
struct streamtab XXinfo = {
&XX_rinit;
&XX_winit;
NULL;
NULL;
};
static struct module_info XX_str_info = {
int, /* system unique module ID, defined in sys/strids.h */
"XX_string",/* module name */
0, /* minimum packet size */
1024, /* maximum packet size */
128, /* high water mark */
16, /* low water mark */
Printed 11/19/92 Page 5
SS(7) RISC/os Reference Manual SS(7)
};
FILES
/usr/include/sys/ss.h
/usr/include/sys/stream.h
$ROOT/usr/src/uts/mips/io/ss.c
Page 6 Printed 11/19/92