share/man/man7d/usbsprl.7d

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH USBSPRL 7D "Nov 23, 2006"
   7 .SH NAME
   8 usbsprl \- Prolific PL2303 USB to serial converter driver
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <fcntl.h>
  13 .fi
  14
  15 .LP
  16 .nf
  17 #include <sys/termio.h>
  18 .fi
  19
  20 .LP
  21 .nf
  22 usbsprl@unit
  23 .fi
  24
  25 .SH DESCRIPTION
  26 .sp
  27 .LP
  28 The \fBusbsprl\fR driver is a loadable \fBSTREAMS\fR and \fBUSBA\fR  (Solaris
  29 USB  architecture) compliant client driver that provides basic asynchronous
  30 communication support for Prolific PL2303 USB-to-serial converters. Supported
  31 devices include PL2303H, PL2303HX and PL2303X.  Serial device streams are built
  32 with appropriate modules that are pushed atop the \fBusbsprl\fR driver by the
  33 \fBautopush\fR(8) facility.
  34 .sp
  35 .LP
  36 The \fBusbsprl\fR module supports the \fBtermio\fR(7I) device control functions
  37 specified by flags in the \fBc_cflag\fR word of the termios structure, and by
  38 the IGNBRK,  IGNPAR,  PARMRK and INPCK flags in the \fBc_iflag\fR word of the
  39 termios structure. All other \fBtermio\fR(7I) functions must be performed by
  40 \fBSTREAMS\fR modules pushed atop the driver. When a device is opened, the
  41 \fBldterm\fR(7M) and \fBttcompat\fR(7M)  \fBSTREAMS\fR modules are
  42 automatically pushed on top of the stream, providing the standard
  43 \fBtermio\fR(7I) interface.
  44 .sp
  45 .LP
  46 Use device logical names \fB/dev/term/[0-9]\fR*  to  access  the serial ports.
  47 These names are typically used to provide a logical access point for a dial-in
  48 line that is used with a modem.
  49 .sp
  50 .LP
  51 A special feature (controlled by the minor device number) is available that
  52 enables a single tty line to be connected to a modem and used for incoming and
  53 outgoing calls. By accessing through device logical name \fB/dev/cua/[0-9]\fR*,
  54 you can open a port without  the carrier detect signal being asserted, either
  55 through hardware or an equivalent software mechanism. These devices are
  56 commonly known as  'dial-out' lines.
  57 .SH APPLICATION PROGRAMMING INTERFACE
  58 .sp
  59 .LP
  60 A dial-in line can be opened only if the corresponding dial-out line is closed.
  61 A blocking \fB/dev/term\fR open waits until the \fB/dev/cua\fR line is closed
  62 (which drops Data Terminal Ready, after which Carrier Detect usually drops as
  63 well) and carrier is detected again.  A non-blocking \fB/dev/term\fR open
  64 returns an error if the \fB/dev/cua\fR is open.
  65 .sp
  66 .LP
  67 If the \fB/dev/term\fR line is opened successfully  (usually  only when
  68 carrier is recognized on the modem), the corresponding \fB/dev/cua\fR line
  69 cannot be opened. This allows a modem and port to be used  for dial-in (by
  70 enabling the line for login in \fB/etc/inittab\fR) or dial-out (by
  71 \fBtip\fR(1)) when no one is logged in on the line.
  72 .sp
  73 .LP
  74 Device hot-removal  is functionally equivalent to a modem disconnect event, as
  75 defined in \fBtermio\fR(7I).
  76 .SH IOCTLS
  77 .sp
  78 .LP
  79 The  \fBusbsprl\fR driver supports the  standard set of \fBtermio\fR(7I) ioctl
  80 calls.
  81 .sp
  82 .LP
  83 Input and output line speeds can be set to the following baud rates:  75, 150,
  84 300, 600, 1200, 1800, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400 or
  85 460800.  Input and output line speeds cannot be set independently. For example,
  86 when the output speed is set, the input speed is automatically set to the same
  87 speed.
  88 .SH ERRORS
  89 .sp
  90 .LP
  91 An \fBopen()\fR fails under the following conditions:
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fBENXIO\fR\fR
  96 .ad
  97 .RS 9n
  98 The  unit being opened does not exist.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBEBUSY\fR\fR
 105 .ad
 106 .RS 9n
 107 The \fB/dev/cua\fR (dial-out) device is being opened while  the \fB/dev/term\fR
 108 (dial-in device) is open, or the dial-in device is being opened with a no-delay
 109 open while the dial-out device is open.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBEBUSY\fR\fR
 116 .ad
 117 .RS 9n
 118 The  unit has been marked as exclusive-use by another  process with a TIOCEXCL
 119 ioctl() call.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fBEIO\fR\fR
 126 .ad
 127 .RS 9n
 128 USB device I/O error.
 129 .RE
 130
 131 .SH FILES
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fB/kernel/drv/usbsprl\fR\fR
 136 .ad
 137 .sp .6
 138 .RS 4n
 139 32-bit x86 ELF kernel module.
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fB/kernel/drv/amd64/usbsprl\fR\fR
 146 .ad
 147 .sp .6
 148 .RS 4n
 149 64-bit x86 ELF kernel module.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fB/kernel/drv/sparcv9/usbsprl\fR\fR
 156 .ad
 157 .sp .6
 158 .RS 4n
 159 64-bit SPARC ELF kernel module.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fB/dev/cua/[0-9]*\fR\fR
 166 .ad
 167 .sp .6
 168 .RS 4n
 169 dial-out tty lines.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fB/dev/term/[0-9]*\fR\fR
 176 .ad
 177 .sp .6
 178 .RS 4n
 179 dial-in tty lines.
 180 .RE
 181
 182 .SH ATTRIBUTES
 183 .sp
 184 .LP
 185 See \fBattributes\fR(5) for descriptions of the following attributes:
 186 .sp
 187
 188 .sp
 189 .TS
 190 box;
 191 c | c
 192 l | l .
 193 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 194 _
 195 Architecture    SPARC, x86, PCI-based systems
 196 .TE
 197
 198 .SH SEE ALSO
 199 .sp
 200 .LP
 201 \fBstrconf\fR(1), \fBtip\fR(1), \fBautopush\fR(8),
 202 \fBioctl\fR(2), \fBopen\fR(2), \fBtermios\fR(3C), \fBattributes\fR(5),
 203 \fBusba\fR(7D), \fBtermio\fR(7I), \fBldterm\fR(7M), \fBttcompat\fR(7M)
 204 .SH DIAGNOSTICS
 205 .sp
 206 .LP
 207 In addition to being logged, the following messages may appear on the system
 208 console. All messages are formatted in the following manner:
 209 .sp
 210 .in +2
 211 .nf
 212 Warning: <device path> (usbsprl<instance num>): Error Message...
 213 .fi
 214 .in -2
 215 .sp
 216
 217 .sp
 218 .ne 2
 219 .na
 220 \fBDevice was disconnected while open. Data may have been lost.\fR
 221 .ad
 222 .sp .6
 223 .RS 4n
 224 The device has been hot-removed or powered off while it was open and a possible
 225 data transfer was in progress. The job may be aborted.
 226 .RE
 227
 228 .sp
 229 .ne 2
 230 .na
 231 \fBDevice is not identical to the previous one on this port. Please disconnect
 232 and reconnect.\fR
 233 .ad
 234 .sp .6
 235 .RS 4n
 236 The device was hot-removed while open. A new device  was hot-inserted which is
 237 not identical to the original device. Please disconnect the device and
 238 reconnect the original device to the same port.
 239 .RE
 240
 241 .sp
 242 .ne 2
 243 .na
 244 \fBDevice has been reconnected, but data may have been lost.\fR
 245 .ad
 246 .sp .6
 247 .RS 4n
 248 The device that was hot-removed from its USB port has been re-inserted again to
 249 the same port. It is available for access but data from a  previou transfer may
 250 be lost.
 251 .RE
 252
 253 .sp
 254 .ne 2
 255 .na
 256 \fBCannot access <\fR\fIdevice\fR\fB>. Please reconnect.\fR
 257 .ad
 258 .sp .6
 259 .RS 4n
 260 This device has been disconnected because a device other than the original one
 261 has been inserted. The driver informs you of this fact by displaying the name
 262 of  the original device.
 263 .RE
 264
 265 .sp
 266 .LP
 267 The following messages may be logged into the system log. They are formatted in
 268 the following manner:
 269 .sp
 270 .in +2
 271 .nf
 272 <device path><usbsprl<instance number>): message...
 273 .fi
 274 .in -2
 275 .sp
 276
 277 .sp
 278 .ne 2
 279 .na
 280 \fBInput overrun.\fR
 281 .ad
 282 .sp .6
 283 .RS 4n
 284 Data was lost.
 285 .RE
 286