| blob | d555c086230b4585298094ea2e2d513dc6d778bb |
1 '\" te
2 .\" Copyright (c) 2009, 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
4 .\" 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
5 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH USBFTDI 7D "Apr 13, 2009"
7 .SH NAME
8 usbftdi \- FTDI USB to serial converter driver
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB#include <fcntl.h>\fR
13 \fB#include <sys/termio.h>\fR
14 \fBusbftdi@unit\fR
15 .fi
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The \fBusbftdi\fR driver is a loadable STREAMS and USBA (Solaris USB
21 Architecture) compliant client driver that provides basic asynchronous
22 communication support for FTDI USB-to-serial converters. Serial device streams
23 are built with appropriate modules that are pushed atop the \fBusbftdi\fR
24 driver by the \fBautopush\fR(1M) facility.
25 .SS "Application Programming Interface"
26 .sp
27 .LP
28 The \fBusbftdi\fR module supports the \fBtermio\fR(7I) device control functions
29 specified by flags in the \fBc_cflag\fR word of the \fBtermios\fR structure,
30 and by the \fBIGNBRK, IGNPAR, PARMRK\fR, and \fBINPCK\fR flags in the
31 \fBc_iflag\fR word of the \fBtermios\fR structure. All other \fBtermio\fR(7I)
32 functions must be performed by STREAMS modules pushed atop the driver. When a
33 device is opened, the , \fBldterm\fR(7M) and \fBttcompat\fR(7M) STREAMS modules
34 are automatically pushed on top of the stream, providing the standard
35 \fBtermio\fR(7I) interface.
36 .sp
37 .LP
38 Use device logical names \fB/dev/term/[0-9]*\fR to access the serial ports for
39 a dial-in line that is used with a modem.
40 .sp
41 .LP
42 Use device logical names \fB/dev/cua/[0-9]*\fR to access the serial ports for
43 other applications. These names are also used to provide a logical access point
44 for a dial-out line.
45 .sp
46 .LP
47 Device hot-removal is functionally equivalent to a modem disconnect event, as
48 defined in \fBtermio\fR(7I).
49 .sp
50 .LP
51 Input and output line speeds can be set to the following baud rates: 300, 600,
52 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, 230400, 460800 or 921600.
53 Input and output line speeds can not be set independently. For example, when
54 the output speed is set, the input speed is automatically set to the same
55 speed.
56 .SS "Soft Carrier Capabilities"
57 .sp
58 .LP
59 Many devices that use this USB serial interface component are not, in fact
60 dial-in lines connected to carefully configured RS-232 modems. They are often
61 intelligent peripherals whose manufacturers want to present a serial port
62 interface to application software. Some applications use only three wire
63 connections, or are otherwise somewhat casual about the state of the Carrier
64 Detect (electrical) signal, and the other modem control lines.
65 .sp
66 .LP
67 The configuration file delivered with this driver, \fBusbftdi.conf\fR,
68 acknowledges this by setting the driver property \fBignore-cd\fR to 1. This
69 enables \fBsoft carrier\fR mode where the kernel does \fBnot\fR block opens
70 waiting for DCD to be asserted.
71 .sp
72 .LP
73 This behavior also matches the default \fBignore carrier detect\fR behavior of
74 the onboard serial ports of machines that have them. See \fBeeprom\fR(1M) for
75 further details.
76 .sp
77 .LP
78 The \fBhardware carrier\fR behavior (the driver's internal default) can be
79 selected by either unsetting (commenting out) the \fBignore-cd\fR property, or
80 by setting the value of the property to zero.
81 .sp
82 .LP
83 More sophisticated selection of which devicesl ignore or obey the DCD signal
84 can be effected using \fBport-%d-ignore-cd\fR properties.
85 .SS "Dial-In and Dial-Out Support"
86 .sp
87 .LP
88 A related feature is available for traditional usage that enables a single tty
89 line to be connected to a modem and used for incoming and outgoing calls. By
90 accessing through device logical name \fB/dev/cua/[0-9]*\fR, you can open a
91 port without the carrier detect signal being asserted, either through hardware
92 or an equivalent software mechanism. These devices are commonly known as
93 dial-out lines.
94 .sp
95 .LP
96 A dial-in line can be opened only if the corresponding dial-out line is closed.
97 A blocking \fB/dev/term\fR open waits until the \fB/dev/cua\fR line is closed,
98 which drops Data Terminal Ready, after which Carrier Detect usually drops as
99 well. When the carrier is detected again with the \fB/dev/cua\fR device
100 remaining closed, this indicates an incoming call and the blocking open seizes
101 exclusive use of the line.
102 .sp
103 .LP
104 A non-blocking \fB/dev/term\fR open returns an error if the \fB/dev/cua\fR
105 device is open.
106 .sp
107 .LP
108 If the \fB/dev/term\fR line is opened successfully (usually only when carrier
109 is recognized on the modem, though see \fBSoft Carrier Capabilities\fR section
110 of this manual page), the corresponding \fB/dev/cua\fR line can not be opened.
111 This allows a modem and port to be used for dial-in (enabling the line for
112 login in \fB/etc/inittab\fR) or dial-out (using \fBtip\fR(1) or \fBuucp\fR(1C))
113 when no-one is logged in on the line.
114 .SH ERRORS
115 .sp
116 .LP
117 An \fBopen()\fR fails under the following conditions:
118 .sp
119 .ne 2
120 .na
121 \fB\fBENXIO\fR\fR
122 .ad
123 .RS 9n
124 The unit being opened does not exist.
125 .RE
127 .sp
128 .ne 2
129 .na
130 \fB\fBEBUSY\fR\fR
131 .ad
132 .RS 9n
133 The \fB/dev/cua\fR (dial-out) device is being opened while the \fB/dev/term\fR
134 (dial-in device) is open, or the dial-in device is being opened with a no-delay
135 open while the dial-out device is open.
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fBEBUSY\fR\fR
142 .ad
143 .RS 9n
144 The unit has been marked as exclusive-use by another process with a
145 \fBTIOCEXCL\fR \fBioctl()\fR call.
146 .RE
148 .sp
149 .ne 2
150 .na
151 \fB\fBEIO\fR\fR
152 .ad
153 .RS 9n
154 USB device I/O error.
155 .RE
157 .SH FILES
158 .sp
159 .ne 2
160 .na
161 \fB\fB/usr/kernel/drv/usbftdi\fR\fR
162 .ad
163 .sp .6
164 .RS 4n
165 32-bit x86 ELF kernel module
166 .RE
168 .sp
169 .ne 2
170 .na
171 \fB\fB/usr/kernel/drv/usbftdi.conf\fR\fR
172 .ad
173 .sp .6
174 .RS 4n
175 Kernel module configuration file
176 .RE
178 .sp
179 .ne 2
180 .na
181 \fB\fB/usr/kernel/drv/amd64/usbftdi\fR\fR
182 .ad
183 .sp .6
184 .RS 4n
185 64-bit x86 ELF kernel module
186 .RE
188 .sp
189 .ne 2
190 .na
191 \fB\fB/usr/kernel/drv/sparcv9/usbftdi\fR\fR
192 .ad
193 .sp .6
194 .RS 4n
195 64-bit SPARC ELF kernel module
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fB/dev/cua/[0-9]*\fR\fR
202 .ad
203 .sp .6
204 .RS 4n
205 Dial-out tty lines
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fB/dev/term/[0-9]*\fR\fR
212 .ad
213 .sp .6
214 .RS 4n
215 Dial-in tty lines
216 .RE
218 .SH ATTRIBUTES
219 .sp
220 .LP
221 See \fBattributes\fR(5) for a description of the following attribute:
222 .sp
224 .sp
225 .TS
226 box;
227 l | l
228 l | l .
229 ATTRIBUTE TYPE ATTRIBUTE VALUE
230 _
231 Architecture SPARC, x86, PCI-based systems
232 .TE
234 .SH SEE ALSO
235 .sp
236 .LP
237 \fBstrconf\fR(1), \fBtip\fR(1), \fBuucp\fR(1C), \fBautopush\fR(1M),
238 \fBeeprom\fR(1M), \fBioctl\fR(2), \fBopen\fR(2), \fBtermios\fR(3C),
239 \fBusba\fR(7D), \fBtermio\fR(7I), \fBldterm\fR(7M), \fBttcompat\fR(7M),
240 \fBeeprom\fR(1M), \fBattributes\fR(5),
241 .SH DIAGNOSTICS
242 .sp
243 .LP
244 In addition to being logged, the following messages might appear on the system
245 console. All messages are formatted in the following manner:
246 .sp
247 .in +2
248 .nf
249 Warning: \fIdevice_path\fR usbftdi\fIinstance num\fR): Error Message ...
250 .fi
251 .in -2
252 .sp
254 .sp
255 .ne 2
256 .na
257 \fB\fBDevice was disconnected while open. Data may have been lost.\fR\fR
258 .ad
259 .sp .6
260 .RS 4n
261 The device has been hot-removed or powered off while it was open and a possible
262 data transfer was in progress. The job might be aborted.
263 .RE
265 .sp
266 .ne 2
267 .na
268 \fB\fBDevice is not identical to the previous one on this port. Please
269 disconnect and reconnect.\fR\fR
270 .ad
271 .sp .6
272 .RS 4n
273 The device was hot-removed while open. A new device was hot-inserted which is
274 not identical to the original device. Please disconnect the device and
275 reconnect the original device to the same port.
276 .RE
278 .sp
279 .ne 2
280 .na
281 \fB\fBDevice has been reconnected, but data may have been lost.\fR\fR
282 .ad
283 .sp .6
284 .RS 4n
285 The device that was hot-removed from its USB port has been re-inserted again to
286 the same port. It is available for access but data from a previous transfer
287 might be lost.
288 .RE
290 .sp
291 .ne 2
292 .na
293 \fB\fBCannot access \fIdevice\fR. Please reconnect.\fR\fR
294 .ad
295 .sp .6
296 .RS 4n
297 This device has been disconnected because a device other than the original one
298 has been inserted. The driver informs you of this fact by displaying the name
299 of the original device.
300 .RE
302 .sp
303 .LP
304 The following messages might be logged into the system log. They are formatted
305 in the following manner:
306 .sp
307 .in +2
308 .nf
309 \fIdevice_path\fR usbftdi\fIiinstance number\fR): message ...
310 .fi
311 .in -2
312 .sp
314 .sp
315 .ne 2
316 .na
317 \fB\fBInput overrun.\fR\fR
318 .ad
319 .RS 18n
320 Data was lost.
321 .RE