share/man/man9/ucom.9

   1 .\"     $NetBSD: ucom.9,v 1.14 2007/03/07 00:41:17 dogcow 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
  37 The
  38 .Nm
  39 driver is a (relatively) easy way to make a USB device look like
  40 a
  41 .Xr tty 4 .
  42 It basically takes two bulk pipes, input and output, and makes
  43 a tty out of them.
  44 This is useful for a number of device types, e.g., serial ports
  45 (see
  46 .Xr uftdi 4 ) ,
  47 modems (see
  48 .Xr umodem 4 ) ,
  49 and devices that traditionally look like a tty (see
  50 .Xr uvisor 4 ) .
  51 .Pp
  52 Communication between the real driver and the
  53 .Nm
  54 driver is via the attachment arguments (when attached) and
  55 via the
  56 .Va ucom_methods
  57 struct
  58 .Sh ATTACHMENT
  59 .Bd -literal
  60 struct 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
  77 identifies the port if the devices should have more than one
  78 .Nm
  79 attached.
  80 Use the value
  81 .Dv UCOM_UNK_PORTNO
  82 if there is only one port.
  83 .It Dv int bulkin
  84 the number of the bulk input pipe.
  85 .It Dv int bulkout
  86 the number of the bulk output pipe.
  87 .It Dv u_int ibufsize
  88 the size of the read requests on the bulk in pipe.
  89 .It Dv u_int ibufsizepad
  90 the size of the input buffer.
  91 This is usually the same as
  92 .Dv ibufsize .
  93 .It Dv u_int obufsize
  94 the size of the write requests on the bulk out pipe.
  95 .It Dv u_int ibufsizepad
  96 the size of the output buffer.
  97 This is usually the same as
  98 .Dv obufsize .
  99 .It Dv usbd_device_handle device
 100 a handle to the device.
 101 .It usbd_interface_handle iface
 102 a handle to the interface that should be used.
 103 .It struct ucom_methods *methods
 104 a pointer to the methods that the
 105 .Nm
 106 driver should use for further communication with the driver.
 107 .It void *arg
 108 the value that should be passed as first argument to each method.
 109 .El
 110 .Sh METHODS
 111 The
 112 .Dv ucom_methods
 113 struct contains a number of function pointers used by the
 114 .Nm
 115 driver at various stages.
 116 If the device is not interested in being called at a particular point
 117 it should just use a
 118 .Dv NULL
 119 pointer and the
 120 .Nm
 121 driver will use a sensible default.
 122 .Bd -literal
 123 struct 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"
 144 get the status of port
 145 .Fa portno .
 146 The status consists of the line status,
 147 .Fa lsr ,
 148 and the modem status
 149 .Fa msr .
 150 The 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"
 152 Set (or unset) a particular feature of a port.
 153 .It Fn "int (*ucom_param)" "void *sc, int portno, struct termios *t"
 154 Set the speed, number of data bit, stop bits, and parity of a port
 155 according to the
 156 .Xr termios 4
 157 struct.
 158 .It Fn "int (*ucom_ioctl)" "void *sc, int portno, u_long cmd, void *data, int flag, struct lwp *l"
 159 implements any non-standard
 160 .Xr ioctl 2
 161 that a device needs.
 162 .It Fn "int (*ucom_open)" "void *sc, int portno"
 163 called just before the
 164 .Nm
 165 driver opens the bulk pipes for the port.
 166 .It Fn "void (*ucom_close)" "void *sc, int portno"
 167 called just after the
 168 .Nm
 169 driver closes the bulk pipes for the port.
 170 .It Fn "void (*ucom_read)" "void *sc, int portno, u_char **ptr, uint32_t *count"
 171 if the data delivered on the bulk pipe is not just the raw input characters
 172 this routine needs to adjust
 173 .Fa ptr
 174 and
 175 .Fa count
 176 so 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"
 178 if the data written to the bulk pipe is not just the raw characters then
 179 this routine needs to copy
 180 .Fa count
 181 raw characters from
 182 .Fa src
 183 into the buffer at
 184 .Fa dst
 185 and do the appropriate padding.
 186 The
 187 .Fa count
 188 should be updated to the new size.
 189 The buffer at
 190 .Fa src
 191 is at most
 192 .Va ibufsize
 193 bytes and the buffer
 194 at
 195 .Fa dst
 196 is
 197 .Va ibufsizepad
 198 bytes.
 199 .El
 200 .Pp
 201 Apart 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
 206 which 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
 214 This
 215 .Nm
 216 interface first appeared in
 217 .Nx 1.5 .