1.\" $NetBSD: ucom.9,v 1.4 2001/04/09 19:12:44 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 82.Bl -tag -width indent 83.It Dv int portno 84identifies the port if the devices should havce more than one 85.Nm 86attached. Use the value 87.Dv UCOM_UNK_PORTNO 88if there is only one port. 89.It Dv int bulkin 90the number of the bulk input pipe. 91.It Dv int bulkout 92the number of the bulk output pipe. 93.It Dv u_int ibufsize 94the size of the read requests on the bulk in pipe. 95.It Dv u_int ibufsizepad 96the size of the input buffer. This is usually the same 97as .Dv ibufsize. 98.It Dv u_int obufsize 99the size of the write requests on the bulk out pipe. 100.It Dv u_int ibufsizepad 101the size of the output buffer. This is usually the same 102as .Dv obufsize. 103.It Dv usbd_device_handle device 104a handle to the device. 105.It usbd_interface_handle iface 106a handle to the interface that should be used. 107.It struct ucom_methods *methods 108a pointer to the methods that the 109.Nm 110driver should use for further communication with the driver. 111.It void *arg 112the value that should be passed as first argument to each method. 113.El 114 115.Sh METHODS 116The 117.Dv ucom_methods 118struct contains a number of function pointers used by the 119.Nm 120driver at various stages. If the device is not interested 121in being called at a particular point it should just use a 122.Dv NULL 123pointer and the 124.Nm 125driver will use a sensible default. 126.Bd -literal 127struct ucom_methods { 128 void (*ucom_get_status)__P((void *sc, int portno, 129 u_char *lsr, u_char *msr)); 130 void (*ucom_set)__P((void *sc, int portno, int reg, int onoff)); 131#define UCOM_SET_DTR 1 132#define UCOM_SET_RTS 2 133#define UCOM_SET_BREAK 3 134 int (*ucom_param)__P((void *sc, int portno, struct termios *)); 135 int (*ucom_ioctl)__P((void *sc, int portno, u_long cmd, 136 caddr_t data, int flag, struct proc *p)); 137 int (*ucom_open)__P((void *sc, int portno)); 138 void (*ucom_close)__P((void *sc, int portno)); 139 void (*ucom_read)__P((void *sc, int portno, u_char **ptr, 140 u_int32_t *count)); 141 void (*ucom_write)__P((void *sc, int portno, u_char *to, 142 u_char *from, u_int32_t *count)); 143}; 144.Ed 145 146.Bl -tag -width indent 147.It Fn "void (*ucom_get_status)" "void *sc, int portno, u_char *lsr, u_char *msr" 148get the status of port 149.Fa portno . 150The status consists of the line status, 151.Fa lsr , 152and the modem status 153.Fa msr . 154The contents of these two bytes is exactly as for a 16550 UART. 155.It Fn "void (*ucom_set)" "void *sc, int portno, int reg, int onoff" 156Set (or unset) a particular feature of a port. 157.It Fn "int (*ucom_param)" "void *sc, int portno, struct termios *t" 158Set the speed, number of data bit, stop bits, and parity of a port 159according to the 160.Xr termios 4 161struct. 162.It Fn "int (*ucom_ioctl)" "void *sc, int portno, u_long cmd, caddr_t data, int flag, struct proc *p" 163implements any non-standard 164.Xr ioctl 2 165that a device needs. 166.It Fn "int (*ucom_open)" "void *sc, int portno" 167called just before the 168.Nm 169driver opens the bulk pipes for the port. 170.It Fn "void (*ucom_close)" "void *sc, int portno" 171called just after the 172.Nm 173driver closes the bulk pipes for the port. 174.It Fn "void (*ucom_read)" "void *sc, int portno, u_char **ptr, u_int32_t *count" 175if the data delivered on the bulk pipe is not just the raw input characters 176this routine needs to adjust 177.Fa ptr 178and 179.Fa count 180so that they tell where to find the given number of raw characters. 181.It Fn "void (*ucom_write)" "void *sc, int portno, u_char *dst, u_char *src, u_int32_t *count" 182if the data written to the bulk pipe is not just the raw characters then 183this routine needs to copy 184.Fa count 185raw characters from 186.Fa src 187into the buffer at 188.Fa dst 189and do the appropriate padding. The 190.Fa count 191should be updated to the new size. 192The buffer at 193.Fa src 194is at most 195.Va ibufsize 196bytes and the buffer 197at 198.Fa dst 199is 200.Va ibufsizepad 201bytes. 202.El 203.Pp 204Apart from these methods there is a function 205.Bl -tag -width indent 5n 206.It Fn "void ucom_status_change" "struct ucom_softc *" 207.El 208.Pp 209which should be called by the driver whenever it notices a status change. 210 211.Sh SEE ALSO 212.Xr tty 4 , 213.Xr uftdi 4 , 214.Xr umodem 4 , 215.Xr usb 4 , 216.Xr uvisor 4 217.Sh HISTORY 218This 219.Nm 220interface first appeared in 221.Nx 1.5 . 222