1.\" $NetBSD: ucom.9,v 1.19 2016/10/12 21:18:46 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.\" 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 September 12, 2016 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 ucaa_portno; 62 int ucaa_bulkin; 63 int ucaa_bulkout; 64 u_int ucaa_ibufsize; 65 u_int ucaa_ibufsizepad; 66 u_int ucaa_obufsize; 67 u_int ucaa_opkthdrlen; 68 const char *ucaa_info; 69 struct usbd_device *ucaa_device; 70 struct usbd_interface *ucaa_iface; 71 const struct ucom_methods *ucaa_methods; 72 void *ucaa_arg; 73}; 74.Ed 75.Pp 76.Bl -tag -width indent 77.It Dv int ucaa_portno 78identifies the port if the devices should have more than one 79.Nm 80attached. 81Use the value 82.Dv UCOM_UNK_PORTNO 83if there is only one port. 84.It Dv int ucaa_bulkin 85the number of the bulk input pipe. 86.It Dv int ucaa_bulkout 87the number of the bulk output pipe. 88.It Dv u_int ucaa_ibufsize 89the size of the read requests on the bulk in pipe. 90.It Dv u_int ucaa_ibufsizepad 91the size of the input buffer. 92This is usually the same as 93.Dv ibufsize . 94.It Dv u_int ucaa_obufsize 95the size of the write requests on the bulk out pipe. 96.It Dv u_int ucaa_ibufsizepad 97the size of the output buffer. 98This is usually the same as 99.Dv ucaa_obufsize . 100.It Dv struct usbd_device *ucaa_device 101a handle to the device. 102.It struct usbd_interface *ucaa_iface 103a handle to the interface that should be used. 104.It struct ucom_methods *ucaa_methods 105a pointer to the methods that the 106.Nm 107driver should use for further communication with the driver. 108.It void *ucaa_arg 109the value that should be passed as first argument to each method. 110.El 111.Sh METHODS 112The 113.Dv ucom_methods 114struct contains a number of function pointers used by the 115.Nm 116driver at various stages. 117If the device is not interested in being called at a particular point 118it should just use a 119.Dv NULL 120pointer and the 121.Nm 122driver will use a sensible default. 123.Bd -literal 124struct ucom_methods { 125 void (*ucom_get_status)(void *sc, int portno, 126 u_char *lsr, u_char *msr); 127 void (*ucom_set)(void *sc, int portno, int reg, int onoff); 128#define UCOM_SET_DTR 1 129#define UCOM_SET_RTS 2 130#define UCOM_SET_BREAK 3 131 int (*ucom_param)(void *sc, int portno, struct termios *); 132 int (*ucom_ioctl)(void *sc, int portno, u_long cmd, 133 void *data, int flag, proc_t *p); 134 int (*ucom_open)(void *sc, int portno); 135 void (*ucom_close)(void *sc, int portno); 136 void (*ucom_read)(void *sc, int portno, u_char **ptr, 137 uint32_t *count); 138 void (*ucom_write)(void *sc, int portno, u_char *to, 139 u_char *from, uint32_t *count); 140}; 141.Ed 142.Pp 143.Bl -tag -width indent 144.It Fn "void (*ucom_get_status)" "void *sc" "int portno" "u_char *lsr" "u_char *msr" 145get the status of port 146.Fa portno . 147The status consists of the line status, 148.Fa lsr , 149and the modem status 150.Fa msr . 151The contents of these two bytes is exactly as for a 16550 UART. 152.It Fn "void (*ucom_set)" "void *sc" "int portno" "int reg" "int onoff" 153Set (or unset) a particular feature of a port. 154.It Fn "int (*ucom_param)" "void *sc" "int portno" "struct termios *t" 155Set the speed, number of data bit, stop bits, and parity of a port 156according to the 157.Xr termios 4 158struct. 159.It Fn "int (*ucom_ioctl)" "void *sc" "int portno" "u_long cmd" "void *data" "int flag" "proc_t *p" 160implements any non-standard 161.Xr ioctl 2 162that a device needs. 163.It Fn "int (*ucom_open)" "void *sc" "int portno" 164called just before the 165.Nm 166driver opens the bulk pipes for the port. 167.It Fn "void (*ucom_close)" "void *sc" "int portno" 168called just after the 169.Nm 170driver closes the bulk pipes for the port. 171.It Fn "void (*ucom_read)" "void *sc" "int portno" "u_char **ptr" "uint32_t *count" 172if the data delivered on the bulk pipe is not just the raw input characters 173this routine needs to increment 174.Fa ptr 175by as many characters to skip from the start of the raw input and decrement 176.Fa count 177by as many characters to truncate from the end of the raw input. 178.It Fn "void (*ucom_write)" "void *sc" "int portno" "u_char *dst" "u_char *src" "uint32_t *count" 179if the data written to the bulk pipe is not just the raw characters then 180this routine needs to copy 181.Fa count 182raw characters from 183.Fa src 184into the buffer at 185.Fa dst 186and do the appropriate padding. 187The 188.Fa count 189should be updated to the new size. 190The buffer at 191.Fa src 192is at most 193.Va ibufsize 194bytes and the buffer 195at 196.Fa dst 197is 198.Va ibufsizepad 199bytes. 200.El 201.Pp 202Apart from these methods there is a function 203.Bl -tag -width 5n -offset 5n 204.It Fn "void ucom_status_change" "struct ucom_softc *" 205.El 206.Pp 207which should be called by the driver whenever it notices a status change. 208.Sh SEE ALSO 209.\" moscom 210.Xr tty 4 , 211.Xr u3g 4 , 212.Xr uark 4 , 213.Xr ubsa 4 , 214.Xr uchcom 4 , 215.Xr uftdi 4 , 216.Xr ugensa 4 , 217.Xr uhmodem 4 , 218.Xr uipaq 4 , 219.Xr ukyopon 4 , 220.Xr umct 4 , 221.Xr umodem 4 , 222.Xr uplcom 4 , 223.Xr usb 4 , 224.Xr uslsa 4 , 225.Xr uvisor 4 , 226.Xr uvscom 4 227.Sh HISTORY 228This 229.Nm 230interface first appeared in 231.Nx 1.5 . 232