'\" te
.\" Copyright (c) 2002 Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PORTS 1M "Nov 8, 2002"
.SH NAME
ports \- creates /dev entries and inittab entries for serial lines
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/ports\fR [\fB-r\fR \fIrootdir\fR]
.fi

.SH DESCRIPTION
.sp
.LP
\fBdevfsadm\fR(1M) is now the preferred command for \fB/dev\fR and
\fB/devices\fR and should be used instead of \fBports\fR.
.sp
.LP
The \fBports\fR command creates symbolic links in the \fB/dev/term\fR and
\fB/dev/cua\fR directories to the serial-port character device files in
\fB/devices\fR and adds new entries in \fB/etc/inittab\fR for non-system ports
found. System-board ports are given single lower-case letters for names (such
as \fBa\fR and \fBb\fR) while other ports are named numerically.
.sp
.LP
\fBports\fR searches the kernel device tree to find the serial devices attached
to the system. It also checks \fB/dev/term\fR and \fB/dev/cua\fR to see what
symbolic links to serial devices already exist. \fBports\fR then performs the
following:
.RS +4
.TP
1.
Assigns new numbers (or letters for system-board ports) to ports that are
attached to the system but do not have \fB/dev/term\fR and \fB/dev/cua\fR
entries. The numbers or letters assigned are the lowest-unused numbers or
letters.
.RE
.RS +4
.TP
2.
Removes dangling links: links from \fB/dev/term\fR and \fB/dev/cua\fR
pointing to no-longer-existing ports.
.RE
.RS +4
.TP
3.
Creates new \fB/dev/term\fR and \fB/dev/cua\fR links for new serial devices.
.RE
.RS +4
.TP
4.
Invokes \fBsacadm\fR(1M) to make new port monitor entries for the new
devices. This is not done automatically for on-board ports; on workstations
these ports are often not used for dial-in sessions, so a port-monitor for one
of these ports must be created explicitly.
.RE
.sp
.LP
If the configuration has not changed, ports exits without doing anything.
.SS "Notice to Driver Writers"
.sp
.LP
\fBports\fR considers devices with a node type of \fBDDI_NT_SERIAL,\fR
\fBDDI_NT_SERIAL_MB,\fR \fBDDI_NT_SERIAL_DO,\fR or \fBDDI_NT_SERIAL_MB_DO\fR to
be serial port devices. Devices with one of these node types must create minor
device names that obey the following conventions when calling
\fBddi_create_minor_node\fR(9F).
.RS +4
.TP
.ie t \(bu
.el o
The minor name for non-system port devices (\fBDDI_NT_SERIAL\fR) consists of an
\fBASCII\fR numeric string, where the first port on the device is named
\fB0\fR, the second named \fB1\fR, the third named \fB2\fR, up to the number of
ports provided by the device.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The minor name for non-system dialout devices (\fBDDI_NT_SERIAL_DO\fR) is the
\fBASCII\fR numeric port name, concatenated with \fB,cu\fR. For example, the
minor name for the first dialout port on the serial board is \fB0,cu\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The minor name for system-board port devices (\fBDDI_NT_SERIAL_MB\fR) consists
of a string containing a single \fBASCII\fR lowercase character, where the
first port on the device is named \fBa\fR, the second is named \fBb\fR, the
third is named \fBc\fR, for all ports on the device (or up through port
\fBz\fR).
.RE
.RS +4
.TP
.ie t \(bu
.el o
The minor name for system-board dialout devices (\fBDDI_NT_SERIAL_MB_DO\fR)
consists of the lowercase character port name, concatenated with \fB,cu\fR. For
example, the minor name for the first dialout port on the on-board serial
device is \fBa,cu\fR.
.RE
.sp
.LP
To prevent \fBdisks\fR from attempting to automatically generate links for a
device, drivers must specify a private node type and refrain from using one of
the above node types when calling \fBddi_create_minor_node\fR(9F).
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-r\fR\fI rootdir\fR\fR
.ad
.RS 14n
Causes \fBports\fR to presume that the \fB/dev/term\fR, \fB/dev/cua\fR, and
\fB/devices\fR directories are found under \fIrootdir\fR, not directly under
\fB/\fR. If this argument is specified, \fBsacadm\fR(1M) is not invoked, since
it would update terminal administration files under \fB/etc\fR without regard
to the \fIrootdir\fR.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRCreating the Serial and Dialout Minor Device Nodes
.sp
.LP
The following example creates the serial and dialout minor device nodes from
the \fBxkserial\fR driver's \fBattach\fR(9E) function:

.sp
.in +2
.nf
/*
* Create the minor number by combining the instance number
* with the port number.
*/ #define XKNUMPORTS           8
#define XKMINORNUM(i, p)     ((i) << 4 | (p))
#define XKMINORNUM_DO(i, p)  ((i) << 4 | (p) | 0x80)
int
xkserialattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
{
   int instance, portnum;
   char name[8];
       /* other stuff in attach... */
   instance = ddi_get_instance(dip);
   for (portnum = 0; portnum < XKNUMPORTS; portnum++) {
       /*
        * create the serial port device
        */
        sprintf(name, "%d", portnum);
        ddi_create_minor_node(dip, name, S_IFCHR,
           XKMINORNUM(instance, portnum), DDI_NT_SERIAL, 0);

        /*
         * create the dialout device
         */
         sprintf(name,"%d,cu", portnum);
         ddi_create_minor_node(dip, name, S_IFCHR,
             XKMINORNUM_DO(instance, portnum), DDI_NT_SERIAL_DO, 0);
     }
}
.fi
.in -2
.sp

.LP
\fBExample 2 \fRInstalling the \fBxkserial\fR Port Driver on a Sun Fire 4800
.sp
.LP
The following example installs the \fBxkserial\fR port driver on a Sun Fire
4800 (with the driver controlling the fictional XKSerial 8 port serial board),
with these special files in \fB/devices\fR:

.sp
.in +2
.nf
# ls -l /devices/ssm@0,0/pci@18,700000/pci@1/xkserial@f,800000/
crw-r-----   1 root sys   32,  16 Aug 29 00:02 xkserial@2000:0
crw-r-----   1 root sys   32, 144 Aug 29 00:02 xkserial@2000:0,cu
crw-r-----   1 root sys   32,  17 Aug 29 00:02 xkserial@2000:1
crw-r-----   1 root sys   32, 145 Aug 29 00:02 xkserial@2000:1,cu
crw-r-----   1 root sys   32,  18 Aug 29 00:02 xkserial@2000:2
crw-r-----   1 root sys   32, 146 Aug 29 00:02 xkserial@2000:2,cu
crw-r-----   1 root sys   32,  19 Aug 29 00:02 xkserial@2000:3
crw-r-----   1 root sys   32, 147 Aug 29 00:02 xkserial@2000:3,cu
crw-r-----   1 root sys   32,  20 Aug 29 00:02 xkserial@2000:4
crw-r-----   1 root sys   32, 148 Aug 29 00:02 xkserial@2000:4,cu
crw-r-----   1 root sys   32,  21 Aug 29 00:02 xkserial@2000:5
crw-r-----   1 root sys   32, 149 Aug 29 00:02 xkserial@2000:5,cu
crw-r-----   1 root sys   32,  22 Aug 29 00:02 xkserial@2000:6
crw-r-----   1 root sys   32, 150 Aug 29 00:02 xkserial@2000:6,cu
crw-r-----   1 root sys   32,  23 Aug 29 00:02 xkserial@2000:7
crw-r-----   1 root sys   32, 151 Aug 29 00:02 xkserial@2000:7,cu
.fi
.in -2
.sp

.sp
.LP
\fB/dev/term\fR contain symbolic links to the serial port device nodes in
\fB/devices\fR

.sp
.in +2
.nf
# ls -l /dev/term
/dev/term/0 -> ../../devices/[....]/xkserial@2000:0
/dev/term/1 -> ../../devices/[....]/xkserial@2000:1
/dev/term/2 -> ../../devices/[....]/xkserial@2000:2
/dev/term/3 -> ../../devices/[....]/xkserial@2000:3
/dev/term/4 -> ../../devices/[....]/xkserial@2000:4
/dev/term/5 -> ../../devices/[....]/xkserial@2000:5
/dev/term/6 -> ../../devices/[....]/xkserial@2000:6
/dev/term/7 -> ../../devices/[....]/xkserial@2000:7
.fi
.in -2
.sp

.sp
.LP
and \fB/dev/cua\fR contain symbolic links to the dialout port device nodes in
\fB/devices\fR

.sp
.in +2
.nf
# ls -l /dev/cua

/dev/cua/0 -> ../../devices/[....]/xkserial@2000:0,cu
/dev/cua/1 -> ../../devices/[....]/xkserial@2000:1,cu
/dev/cua/2 -> ../../devices/[....]/xkserial@2000:2,cu
/dev/cua/3 -> ../../devices/[....]/xkserial@2000:3,cu
/dev/cua/4 -> ../../devices/[....]/xkserial@2000:4,cu
/dev/cua/5 -> ../../devices/[....]/xkserial@2000:5,cu
/dev/cua/6 -> ../../devices/[....]/xkserial@2000:6,cu
/dev/cua/7 -> ../../devices/[....]/xkserial@2000:7,cu
.fi
.in -2
.sp

.SH FILES
.sp
.ne 2
.na
\fB\fB/dev/term/\fR\fIn\fR\fR
.ad
.RS 16n
Logical serial port devices
.RE

.sp
.ne 2
.na
\fB\fB/dev/cua/\fR\fIn\fR\fR
.ad
.RS 16n
Logical dialout port devices
.RE

.sp
.ne 2
.na
\fB\fB/etc/inittab\fR\fR
.ad
.RS 16n

.RE

.sp
.ne 2
.na
\fB\fB/etc/saf/*\fR\fR
.ad
.RS 16n

.RE

.SH SEE ALSO
.sp
.LP
\fBadd_drv\fR(1M), \fBdevfsadm\fR(1M), \fBdrvconfig\fR(1M), \fBpmadm\fR(1M),
\fBsacadm\fR(1M), \fBattributes\fR(5), \fBdevfs\fR(7FS), \fBattach\fR(9E),
\fBddi_create_minor_node\fR(9F)
.sp
.LP
\fI\fR