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