xref: /netbsd/share/man/man9/ucom.9 (revision c4a72b64) 
1.\"	$NetBSD: ucom.9,v 1.11 2002/10/14 13:43:35 wiz Exp $
2.\"
3.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Lennart Augustsson.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"        This product includes software developed by the NetBSD
20.\"        Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.Dd April 15, 2000
38.Dt UCOM 9
39.Os
40.Sh NAME
41.Nm ucom
42.Nd interface for USB tty like devices
43.Sh DESCRIPTION
44The
45.Nm
46driver is a (relatively) easy way to make a USB device look like
47a
48.Xr tty 4 .
49It basically takes two bulk pipes, input and output, and makes
50a tty out of them.
51This is useful for a number of device types, e.g., serial ports
52(see
53.Xr uftdi 4 ) ,
54modems (see
55.Xr umodem 4 ) ,
56and devices that traditionally look like a tty (see
57.Xr uvisor 4 ) .
58.Pp
59Communication between the real driver and the
60.Nm
61driver is via the attachment arguments (when attached) and
62via the
63.Va ucom_methods
64struct
65.Sh ATTACHMENT
66.Bd -literal
67struct ucom_attach_args {
68	int portno;
69	int bulkin;
70	int bulkout;
71	u_int ibufsize;
72	u_int ibufsizepad;
73	u_int obufsize;
74	u_int obufsizepad;
75	usbd_device_handle device;
76	usbd_interface_handle iface;
77	struct ucom_methods *methods;
78	void *arg;
79};
80.Ed
81.Pp
82.Bl -tag -width indent
83.It Dv int portno
84identifies the port if the devices should have more than one
85.Nm
86attached.
87Use the value
88.Dv UCOM_UNK_PORTNO
89if there is only one port.
90.It Dv int bulkin
91the number of the bulk input pipe.
92.It Dv int bulkout
93the number of the bulk output pipe.
94.It Dv u_int ibufsize
95the size of the read requests on the bulk in pipe.
96.It Dv u_int ibufsizepad
97the size of the input buffer.
98This is usually the same as
99.Dv ibufsize .
100.It Dv u_int obufsize
101the size of the write requests on the bulk out pipe.
102.It Dv u_int ibufsizepad
103the size of the output buffer.
104This is usually the same as
105.Dv obufsize .
106.It Dv usbd_device_handle device
107a handle to the device.
108.It usbd_interface_handle iface
109a handle to the interface that should be used.
110.It struct ucom_methods *methods
111a pointer to the methods that the
112.Nm
113driver should use for further communication with the driver.
114.It void *arg
115the value that should be passed as first argument to each method.
116.El
117.Sh METHODS
118The
119.Dv ucom_methods
120struct contains a number of function pointers used by the
121.Nm
122driver at various stages.
123If the device is not interested in being called at a particular point
124it should just use a
125.Dv NULL
126pointer and the
127.Nm
128driver will use a sensible default.
129.Bd -literal
130struct ucom_methods {
131	void (*ucom_get_status)(void *sc, int portno,
132				u_char *lsr, u_char *msr);
133	void (*ucom_set)(void *sc, int portno, int reg, int onoff);
134#define UCOM_SET_DTR 1
135#define UCOM_SET_RTS 2
136#define UCOM_SET_BREAK 3
137	int (*ucom_param)(void *sc, int portno, struct termios *);
138	int (*ucom_ioctl)(void *sc, int portno, u_long cmd,
139			  caddr_t data, int flag, struct proc *p);
140	int (*ucom_open)(void *sc, int portno);
141	void (*ucom_close)(void *sc, int portno);
142	void (*ucom_read)(void *sc, int portno, u_char **ptr,
143			  u_int32_t *count);
144	void (*ucom_write)(void *sc, int portno, u_char *to,
145			   u_char *from, u_int32_t *count);
146};
147.Ed
148.Pp
149.Bl -tag -width indent
150.It Fn "void (*ucom_get_status)" "void *sc, int portno, u_char *lsr, u_char *msr"
151get the status of port
152.Fa portno .
153The status consists of the line status,
154.Fa lsr ,
155and the modem status
156.Fa msr .
157The contents of these two bytes is exactly as for a 16550 UART.
158.It Fn "void (*ucom_set)" "void *sc, int portno, int reg, int onoff"
159Set (or unset) a particular feature of a port.
160.It Fn "int (*ucom_param)" "void *sc, int portno, struct termios *t"
161Set the speed, number of data bit, stop bits, and parity of a port
162according to the
163.Xr termios 4
164struct.
165.It Fn "int (*ucom_ioctl)" "void *sc, int portno, u_long cmd, caddr_t data, int flag, struct proc *p"
166implements any non-standard
167.Xr ioctl 2
168that a device needs.
169.It Fn "int (*ucom_open)" "void *sc, int portno"
170called just before the
171.Nm
172driver opens the bulk pipes for the port.
173.It Fn "void (*ucom_close)" "void *sc, int portno"
174called just after the
175.Nm
176driver closes the bulk pipes for the port.
177.It Fn "void (*ucom_read)" "void *sc, int portno, u_char **ptr, u_int32_t *count"
178if the data delivered on the bulk pipe is not just the raw input characters
179this routine needs to adjust
180.Fa ptr
181and
182.Fa count
183so that they tell where to find the given number of raw characters.
184.It Fn "void (*ucom_write)" "void *sc, int portno, u_char *dst, u_char *src, u_int32_t *count"
185if the data written to the bulk pipe is not just the raw characters then
186this routine needs to copy
187.Fa count
188raw characters from
189.Fa src
190into the buffer at
191.Fa dst
192and do the appropriate padding.
193The
194.Fa count
195should be updated to the new size.
196The buffer at
197.Fa src
198is at most
199.Va ibufsize
200bytes and the buffer
201at
202.Fa dst
203is
204.Va ibufsizepad
205bytes.
206.El
207.Pp
208Apart from these methods there is a function
209.Bl -tag -width 5n -offset 5n
210.It Fn "void ucom_status_change" "struct ucom_softc *"
211.El
212.Pp
213which should be called by the driver whenever it notices a status change.
214.Sh SEE ALSO
215.Xr tty 4 ,
216.Xr uftdi 4 ,
217.Xr umodem 4 ,
218.Xr usb 4 ,
219.Xr uvisor 4
220.Sh HISTORY
221This
222.Nm
223interface first appeared in
224.Nx 1.5 .
225