HDK Technical Reference

Serial port registration

The serial OSA (serialOsa in /usr/lib/scoadmin/netosa) in SVR5 allows the management of serial ports which have been registered using a stanza file in the directory /usr/lib/serial (see stanza(DSP/4dsp)). A stanza file can contain entries for several installed serial cards provided that they share the same driver. A separate stanza file is required for serial cards which use different drivers.

The Serial Manager uses the serialOsa to allow administrators to configure the settings on serial ports. The Serial Manager can be run directly from scoadmin or it can be invoked via the Network Configuration Manager and the Modem Manager. Third-party serial card drivers themselves must be managed via a configuration script as for other drivers.

Serial card registration

A third-party serial card is usually installed, reconfigured and removed using a configuration script. In addition, the configuration script should maintain a copy of the stanza file that is used to register serial ports with the serial OSA.

Format of the stanza file

The file is held in stanza format in the directory /usr/lib/serial. The name of the file is arbitrary except that it must be unique to the card and the vendor and it must have the extension ``.stz''.

The first section, CARDS, contains generic attributes for every instance of the serial card that is installed:

DESC=description: A description of the card to be displayed by the Serial Manager. This attribute is mandatory.
NODE=pathname: The pathname of the Node file for the card (see Node(DSP/4dsp)). This attribute is mandatory even if the OVERRIDE attribute is also specified.
DRIVER=module_name: The module name of the card driver as defined in System(DSP/4dsp) and Master(DSP/4dsp) files. This attribute is mandatory.
VENDOR=vendor_name: A name that can be used to uniquely identify a card from a vendor. This attribute is mandatory.
PROBE=boolean: Controls whether the serial OSA should try to open each port on a card to see if exists. By default, probing is performed for the standard serial ports controlled by the SCO-supplied serial driver but not for ports controlled by third-party drivers. Set boolean to 1 to turn on probing; set it to 0 to turn off probing.

Additional sections are named CARD_card_number where the integer card_number indexes the serial card being installed starting at 0 for the first card. Each section contains the following attributes that are specific to the physically installed serial card:

PORTS=number_of_ports

The number of serial ports provided by the card. This attribute is mandatory.

VEC=irq_number

The interrupt vector (IRQ) used by the serial card. This attribute is optional.

ADDR=base

The I/O base address in hexadecimal. This attribute is optional.

OVERRIDE="{device {{port number} {desc {description}} {type s|h|t|m}}}..."

A definition of the device nodes to be used if those defined in the Node file do not conform to the standard format. device is the pathname of the device node relative to /dev. number is the number of the port for this board (from 0 to number_of_ports-1). description is a description of the port that will be used by the scoadmin Serial Manager. The flow control type flags have the following meanings:

s: software flow control
h: hardware flow control
t: terminal port without flow control on first being opened
m: modem port without flow control on first being opened

This attribute is optional.

Naming conventions

The standard serial ports are specified in the file /etc/conf/node.d/iasy. The Serial Manager displays the device file nodes term/00, term/01, term/02, term/03 (relative to /dev) which correspond to COM1, COM2, COM3, and COM4. It does not display device nodes from /dev which are duplicates or which are provided for backward compatibility with SCO OpenServer 5 Release 5. The flow control used by a node is indicated by the description rather than by the name of the port that is displayed.

For third-party serial cards, either the NODE or the OVERRIDE attribute defines the device nodes that the serial OSA must display.

If the OVERRIDE attribute is provided, the serial OSA uses the vTcl keyed list specified as the value of OVERRIDE rather than the Node file specified by the NODE attribute.

If OVERRIDE is not specified, the NODE attribute defines the pathname of the Node file that contains the pathnames of the serial ports provided by each installed card. To be displayed by the Serial Manager, ports defined in the Node file must be named according to the following convention:

   term/vendor_name/card_number/nn[s|h|t|m]

vendor_name and card_number are derived from the attribute VENDOR and the CARD_ section number. The number of the port, nn, must be in the range 00 through number_of_ports-1 where the number of ports on the serial card is defined by the PORTS attribute for an instance of a card.

The single letter codes specify the type of flow control that will be used with the node (as determined by its minor number):

s: software flow control (this is the default behavior if the letter is omitted)
h: hardware flow control
t: terminal port without flow control on first being opened
m: modem port without flow control on first being opened

A node to be displayed by the Serial Manager should be specified without a letter, and it should default to software flow control.

Example stanza file entries

The following is an example stanza file, acmeACE.stz for a system that has installed two (fictitious) ACE 123 serial cards from the vendor Acme, Inc.:

   CARDS:
           VENDOR=acmeACE
           DESC="Acme ACE 12x serial card"
           DRIVER=ace
           NODE=/etc/conf/node.d/ace
   
   CARD_0:
           PORTS=16
           ADDR=0x280
   

   CARD_1:
           PORTS=16
           ADDR=0x380

Note that the attribute definition lines must be tab-indented. In this example, the device files for the eleventh port on the second installed ACE 123 serial card might be defined as following in the Node file (/etc/conf/node.d/acmeACE):

   ace	term/acmeACE/1/10	c	minor	0	0	666	4
   ace	term/acmeACE/1/10s	c       minor
   ace	term/acmeACE/1/10h	c       minor+1
   ace	term/acmeACE/1/10t	c       minor+2
   ace	term/acmeACE/1/10m	c       minor+3

The exact details of the minor numbering scheme would depend on the implementation of the driver. This is an example only. The Node file can also define nodes that conform to the vendor's own naming scheme to maintain backward compatibility. For more information about the format of this file, see Node(DSP/4dsp).

The following example shows how the OVERRIDE attribute may be used to define a non-standard serial port naming convention:

   CARDS:
           VENDOR=ridooRP
           DESC="Ridoo Pro serial board"
           DRIVER=rpxa
           NODE=/etc/conf/node.d/rpxa
   
   CARD_0:
           PORTS=4
           OVERRIDE="{term/a01s {{port 0} {desc {Port 1 Terminal}} {type t}}}
                     {term/a02s {{port 1} {desc {Port 2 Terminal}} {type t}}}
                     {term/a03s {{port 2} {desc {Port 3 Terminal}} {type t}}}
                     {term/a04s {{port 3} {desc {Port 4 Terminal}} {type t}}}
                     {term/a01m {{port 0} {desc {Port 1 Modem}} {type m}}}
                     {term/a02m {{port 1} {desc {Port 2 Modem}} {type m}}}
                     {term/a03m {{port 2} {desc {Port 3 Modem}} {type m}}}
                     {term/a04m {{port 3} {desc {Port 4 Modem}} {type m}}}"

Note that in this example, both terminal and modem devices are defined for each port.