share/man/man8/ports.8

   1 '\" te
   2 .\" Copyright (c) 2002 Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH PORTS 8 "Nov 8, 2002"
   8 .SH NAME
   9 ports \- creates /dev entries and inittab entries for serial lines
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fB/usr/sbin/ports\fR [\fB-r\fR \fIrootdir\fR]
  14 .fi
  15
  16 .SH DESCRIPTION
  17 .sp
  18 .LP
  19 \fBdevfsadm\fR(8) is now the preferred command for \fB/dev\fR and
  20 \fB/devices\fR and should be used instead of \fBports\fR.
  21 .sp
  22 .LP
  23 The \fBports\fR command creates symbolic links in the \fB/dev/term\fR and
  24 \fB/dev/cua\fR directories to the serial-port character device files in
  25 \fB/devices\fR and adds new entries in \fB/etc/inittab\fR for non-system ports
  26 found. System-board ports are given single lower-case letters for names (such
  27 as \fBa\fR and \fBb\fR) while other ports are named numerically.
  28 .sp
  29 .LP
  30 \fBports\fR searches the kernel device tree to find the serial devices attached
  31 to the system. It also checks \fB/dev/term\fR and \fB/dev/cua\fR to see what
  32 symbolic links to serial devices already exist. \fBports\fR then performs the
  33 following:
  34 .RS +4
  35 .TP
  36 1.
  37 Assigns new numbers (or letters for system-board ports) to ports that are
  38 attached to the system but do not have \fB/dev/term\fR and \fB/dev/cua\fR
  39 entries. The numbers or letters assigned are the lowest-unused numbers or
  40 letters.
  41 .RE
  42 .RS +4
  43 .TP
  44 2.
  45 Removes dangling links: links from \fB/dev/term\fR and \fB/dev/cua\fR
  46 pointing to no-longer-existing ports.
  47 .RE
  48 .RS +4
  49 .TP
  50 3.
  51 Creates new \fB/dev/term\fR and \fB/dev/cua\fR links for new serial devices.
  52 .RE
  53 .RS +4
  54 .TP
  55 4.
  56 Invokes \fBsacadm\fR(8) to make new port monitor entries for the new
  57 devices. This is not done automatically for on-board ports; on workstations
  58 these ports are often not used for dial-in sessions, so a port-monitor for one
  59 of these ports must be created explicitly.
  60 .RE
  61 .sp
  62 .LP
  63 If the configuration has not changed, ports exits without doing anything.
  64 .SS "Notice to Driver Writers"
  65 .sp
  66 .LP
  67 \fBports\fR considers devices with a node type of \fBDDI_NT_SERIAL,\fR
  68 \fBDDI_NT_SERIAL_MB,\fR \fBDDI_NT_SERIAL_DO,\fR or \fBDDI_NT_SERIAL_MB_DO\fR to
  69 be serial port devices. Devices with one of these node types must create minor
  70 device names that obey the following conventions when calling
  71 \fBddi_create_minor_node\fR(9F).
  72 .RS +4
  73 .TP
  74 .ie t \(bu
  75 .el o
  76 The minor name for non-system port devices (\fBDDI_NT_SERIAL\fR) consists of an
  77 \fBASCII\fR numeric string, where the first port on the device is named
  78 \fB0\fR, the second named \fB1\fR, the third named \fB2\fR, up to the number of
  79 ports provided by the device.
  80 .RE
  81 .RS +4
  82 .TP
  83 .ie t \(bu
  84 .el o
  85 The minor name for non-system dialout devices (\fBDDI_NT_SERIAL_DO\fR) is the
  86 \fBASCII\fR numeric port name, concatenated with \fB,cu\fR. For example, the
  87 minor name for the first dialout port on the serial board is \fB0,cu\fR.
  88 .RE
  89 .RS +4
  90 .TP
  91 .ie t \(bu
  92 .el o
  93 The minor name for system-board port devices (\fBDDI_NT_SERIAL_MB\fR) consists
  94 of a string containing a single \fBASCII\fR lowercase character, where the
  95 first port on the device is named \fBa\fR, the second is named \fBb\fR, the
  96 third is named \fBc\fR, for all ports on the device (or up through port
  97 \fBz\fR).
  98 .RE
  99 .RS +4
 100 .TP
 101 .ie t \(bu
 102 .el o
 103 The minor name for system-board dialout devices (\fBDDI_NT_SERIAL_MB_DO\fR)
 104 consists of the lowercase character port name, concatenated with \fB,cu\fR. For
 105 example, the minor name for the first dialout port on the on-board serial
 106 device is \fBa,cu\fR.
 107 .RE
 108 .sp
 109 .LP
 110 To prevent \fBdisks\fR from attempting to automatically generate links for a
 111 device, drivers must specify a private node type and refrain from using one of
 112 the above node types when calling \fBddi_create_minor_node\fR(9F).
 113 .SH OPTIONS
 114 .sp
 115 .LP
 116 The following options are supported:
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fB-r\fR\fI rootdir\fR\fR
 121 .ad
 122 .RS 14n
 123 Causes \fBports\fR to presume that the \fB/dev/term\fR, \fB/dev/cua\fR, and
 124 \fB/devices\fR directories are found under \fIrootdir\fR, not directly under
 125 \fB/\fR. If this argument is specified, \fBsacadm\fR(8) is not invoked, since
 126 it would update terminal administration files under \fB/etc\fR without regard
 127 to the \fIrootdir\fR.
 128 .RE
 129
 130 .SH EXAMPLES
 131 .LP
 132 \fBExample 1 \fRCreating the Serial and Dialout Minor Device Nodes
 133 .sp
 134 .LP
 135 The following example creates the serial and dialout minor device nodes from
 136 the \fBxkserial\fR driver's \fBattach\fR(9E) function:
 137
 138 .sp
 139 .in +2
 140 .nf
 141 /*
 142 * Create the minor number by combining the instance number
 143 * with the port number.
 144 */ #define XKNUMPORTS           8
 145 #define XKMINORNUM(i, p)     ((i) << 4 | (p))
 146 #define XKMINORNUM_DO(i, p)  ((i) << 4 | (p) | 0x80)
 147 int
 148 xkserialattach(dev_info_t *dip, ddi_attach_cmd_t cmd)
 149 {
 150    int instance, portnum;
 151    char name[8];
 152        /* other stuff in attach... */
 153    instance = ddi_get_instance(dip);
 154    for (portnum = 0; portnum < XKNUMPORTS; portnum++) {
 155        /*
 156         * create the serial port device
 157         */
 158         sprintf(name, "%d", portnum);
 159         ddi_create_minor_node(dip, name, S_IFCHR,
 160            XKMINORNUM(instance, portnum), DDI_NT_SERIAL, 0);
 161
 162         /*
 163          * create the dialout device
 164          */
 165          sprintf(name,"%d,cu", portnum);
 166          ddi_create_minor_node(dip, name, S_IFCHR,
 167              XKMINORNUM_DO(instance, portnum), DDI_NT_SERIAL_DO, 0);
 168      }
 169 }
 170 .fi
 171 .in -2
 172 .sp
 173
 174 .LP
 175 \fBExample 2 \fRInstalling the \fBxkserial\fR Port Driver on a Sun Fire 4800
 176 .sp
 177 .LP
 178 The following example installs the \fBxkserial\fR port driver on a Sun Fire
 179 4800 (with the driver controlling the fictional XKSerial 8 port serial board),
 180 with these special files in \fB/devices\fR:
 181
 182 .sp
 183 .in +2
 184 .nf
 185 # ls -l /devices/ssm@0,0/pci@18,700000/pci@1/xkserial@f,800000/
 186 crw-r-----   1 root sys   32,  16 Aug 29 00:02 xkserial@2000:0
 187 crw-r-----   1 root sys   32, 144 Aug 29 00:02 xkserial@2000:0,cu
 188 crw-r-----   1 root sys   32,  17 Aug 29 00:02 xkserial@2000:1
 189 crw-r-----   1 root sys   32, 145 Aug 29 00:02 xkserial@2000:1,cu
 190 crw-r-----   1 root sys   32,  18 Aug 29 00:02 xkserial@2000:2
 191 crw-r-----   1 root sys   32, 146 Aug 29 00:02 xkserial@2000:2,cu
 192 crw-r-----   1 root sys   32,  19 Aug 29 00:02 xkserial@2000:3
 193 crw-r-----   1 root sys   32, 147 Aug 29 00:02 xkserial@2000:3,cu
 194 crw-r-----   1 root sys   32,  20 Aug 29 00:02 xkserial@2000:4
 195 crw-r-----   1 root sys   32, 148 Aug 29 00:02 xkserial@2000:4,cu
 196 crw-r-----   1 root sys   32,  21 Aug 29 00:02 xkserial@2000:5
 197 crw-r-----   1 root sys   32, 149 Aug 29 00:02 xkserial@2000:5,cu
 198 crw-r-----   1 root sys   32,  22 Aug 29 00:02 xkserial@2000:6
 199 crw-r-----   1 root sys   32, 150 Aug 29 00:02 xkserial@2000:6,cu
 200 crw-r-----   1 root sys   32,  23 Aug 29 00:02 xkserial@2000:7
 201 crw-r-----   1 root sys   32, 151 Aug 29 00:02 xkserial@2000:7,cu
 202 .fi
 203 .in -2
 204 .sp
 205
 206 .sp
 207 .LP
 208 \fB/dev/term\fR contain symbolic links to the serial port device nodes in
 209 \fB/devices\fR
 210
 211 .sp
 212 .in +2
 213 .nf
 214 # ls -l /dev/term
 215 /dev/term/0 -> ../../devices/[....]/xkserial@2000:0
 216 /dev/term/1 -> ../../devices/[....]/xkserial@2000:1
 217 /dev/term/2 -> ../../devices/[....]/xkserial@2000:2
 218 /dev/term/3 -> ../../devices/[....]/xkserial@2000:3
 219 /dev/term/4 -> ../../devices/[....]/xkserial@2000:4
 220 /dev/term/5 -> ../../devices/[....]/xkserial@2000:5
 221 /dev/term/6 -> ../../devices/[....]/xkserial@2000:6
 222 /dev/term/7 -> ../../devices/[....]/xkserial@2000:7
 223 .fi
 224 .in -2
 225 .sp
 226
 227 .sp
 228 .LP
 229 and \fB/dev/cua\fR contain symbolic links to the dialout port device nodes in
 230 \fB/devices\fR
 231
 232 .sp
 233 .in +2
 234 .nf
 235 # ls -l /dev/cua
 236
 237 /dev/cua/0 -> ../../devices/[....]/xkserial@2000:0,cu
 238 /dev/cua/1 -> ../../devices/[....]/xkserial@2000:1,cu
 239 /dev/cua/2 -> ../../devices/[....]/xkserial@2000:2,cu
 240 /dev/cua/3 -> ../../devices/[....]/xkserial@2000:3,cu
 241 /dev/cua/4 -> ../../devices/[....]/xkserial@2000:4,cu
 242 /dev/cua/5 -> ../../devices/[....]/xkserial@2000:5,cu
 243 /dev/cua/6 -> ../../devices/[....]/xkserial@2000:6,cu
 244 /dev/cua/7 -> ../../devices/[....]/xkserial@2000:7,cu
 245 .fi
 246 .in -2
 247 .sp
 248
 249 .SH FILES
 250 .sp
 251 .ne 2
 252 .na
 253 \fB\fB/dev/term/\fR\fIn\fR\fR
 254 .ad
 255 .RS 16n
 256 Logical serial port devices
 257 .RE
 258
 259 .sp
 260 .ne 2
 261 .na
 262 \fB\fB/dev/cua/\fR\fIn\fR\fR
 263 .ad
 264 .RS 16n
 265 Logical dialout port devices
 266 .RE
 267
 268 .sp
 269 .ne 2
 270 .na
 271 \fB\fB/etc/inittab\fR\fR
 272 .ad
 273 .RS 16n
 274
 275 .RE
 276
 277 .sp
 278 .ne 2
 279 .na
 280 \fB\fB/etc/saf/*\fR\fR
 281 .ad
 282 .RS 16n
 283
 284 .RE
 285
 286 .SH SEE ALSO
 287 .sp
 288 .LP
 289 \fBadd_drv\fR(8), \fBdevfsadm\fR(8), \fBdrvconfig\fR(8), \fBpmadm\fR(8),
 290 \fBsacadm\fR(8), \fBattributes\fR(5), \fBdevfs\fR(7FS), \fBattach\fR(9E),
 291 \fBddi_create_minor_node\fR(9F)
 292 .sp
 293 .LP
 294 \fI\fR