8bd7cb6a69
* There is no -indent option to .Bd or .Bl, although you would never know that from its frequent use in this tree. There is a "-offset indent" combination that makes sense, and you can certainly say "-width indent". * Also, you can't markup the -width option argument, tho you CAN use a callable macro. So "-width Ar filename" doesn't make sense, but either "-width Ar" or "-width filename" does, as might something like "-width xxfilename" for a little extra space. * There are a lot of needlessly complex hanging tag macros in man4 used to create simple item lists. Those should be simplified one of these days before someone copies and edits yet another man4 page.
220 lines
6.7 KiB
Groff
220 lines
6.7 KiB
Groff
.\" $NetBSD: ucom.9,v 1.8 2002/02/07 03:15:10 ross Exp $
|
|
.\"
|
|
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Lennart Augustsson.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd April 15, 2000
|
|
.Dt UCOM 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ucom
|
|
.Nd interface for USB tty like devices
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver is a (relatively) easy way to make a USB device look like
|
|
a
|
|
.Xr tty 4 .
|
|
It basically takes two bulk pipes, input and output, and makes
|
|
a tty out of them.
|
|
This is useful for a number of device types, e.g., serial ports
|
|
(see
|
|
.Xr uftdi 4 ) ,
|
|
modems (see
|
|
.Xr umodem 4 ) ,
|
|
and devices that traditionally look like a tty (see
|
|
.Xr uvisor 4 ) .
|
|
.Pp
|
|
Communication between the real driver and the
|
|
.Nm
|
|
driver is via the attachment arguments (when attached) and
|
|
via the
|
|
.Va ucom_methods
|
|
struct
|
|
.Sh ATTACHMENT
|
|
.Bd -literal
|
|
struct ucom_attach_args {
|
|
int portno;
|
|
int bulkin;
|
|
int bulkout;
|
|
u_int ibufsize;
|
|
u_int ibufsizepad;
|
|
u_int obufsize;
|
|
u_int obufsizepad;
|
|
usbd_device_handle device;
|
|
usbd_interface_handle iface;
|
|
struct ucom_methods *methods;
|
|
void *arg;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Bl -tag -width indent
|
|
.It Dv int portno
|
|
identifies the port if the devices should have more than one
|
|
.Nm
|
|
attached. Use the value
|
|
.Dv UCOM_UNK_PORTNO
|
|
if there is only one port.
|
|
.It Dv int bulkin
|
|
the number of the bulk input pipe.
|
|
.It Dv int bulkout
|
|
the number of the bulk output pipe.
|
|
.It Dv u_int ibufsize
|
|
the size of the read requests on the bulk in pipe.
|
|
.It Dv u_int ibufsizepad
|
|
the size of the input buffer. This is usually the same
|
|
as .Dv ibufsize.
|
|
.It Dv u_int obufsize
|
|
the size of the write requests on the bulk out pipe.
|
|
.It Dv u_int ibufsizepad
|
|
the size of the output buffer. This is usually the same
|
|
as .Dv obufsize.
|
|
.It Dv usbd_device_handle device
|
|
a handle to the device.
|
|
.It usbd_interface_handle iface
|
|
a handle to the interface that should be used.
|
|
.It struct ucom_methods *methods
|
|
a pointer to the methods that the
|
|
.Nm
|
|
driver should use for further communication with the driver.
|
|
.It void *arg
|
|
the value that should be passed as first argument to each method.
|
|
.El
|
|
.Sh METHODS
|
|
The
|
|
.Dv ucom_methods
|
|
struct contains a number of function pointers used by the
|
|
.Nm
|
|
driver at various stages. If the device is not interested
|
|
in being called at a particular point it should just use a
|
|
.Dv NULL
|
|
pointer and the
|
|
.Nm
|
|
driver will use a sensible default.
|
|
.Bd -literal
|
|
struct ucom_methods {
|
|
void (*ucom_get_status)(void *sc, int portno,
|
|
u_char *lsr, u_char *msr);
|
|
void (*ucom_set)(void *sc, int portno, int reg, int onoff);
|
|
#define UCOM_SET_DTR 1
|
|
#define UCOM_SET_RTS 2
|
|
#define UCOM_SET_BREAK 3
|
|
int (*ucom_param)(void *sc, int portno, struct termios *);
|
|
int (*ucom_ioctl)(void *sc, int portno, u_long cmd,
|
|
caddr_t data, int flag, struct proc *p);
|
|
int (*ucom_open)(void *sc, int portno);
|
|
void (*ucom_close)(void *sc, int portno);
|
|
void (*ucom_read)(void *sc, int portno, u_char **ptr,
|
|
u_int32_t *count);
|
|
void (*ucom_write)(void *sc, int portno, u_char *to,
|
|
u_char *from, u_int32_t *count);
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Bl -tag -width indent
|
|
.It Fn "void (*ucom_get_status)" "void *sc, int portno, u_char *lsr, u_char *msr"
|
|
get the status of port
|
|
.Fa portno .
|
|
The status consists of the line status,
|
|
.Fa lsr ,
|
|
and the modem status
|
|
.Fa msr .
|
|
The contents of these two bytes is exactly as for a 16550 UART.
|
|
.It Fn "void (*ucom_set)" "void *sc, int portno, int reg, int onoff"
|
|
Set (or unset) a particular feature of a port.
|
|
.It Fn "int (*ucom_param)" "void *sc, int portno, struct termios *t"
|
|
Set the speed, number of data bit, stop bits, and parity of a port
|
|
according to the
|
|
.Xr termios 4
|
|
struct.
|
|
.It Fn "int (*ucom_ioctl)" "void *sc, int portno, u_long cmd, caddr_t data, int flag, struct proc *p"
|
|
implements any non-standard
|
|
.Xr ioctl 2
|
|
that a device needs.
|
|
.It Fn "int (*ucom_open)" "void *sc, int portno"
|
|
called just before the
|
|
.Nm
|
|
driver opens the bulk pipes for the port.
|
|
.It Fn "void (*ucom_close)" "void *sc, int portno"
|
|
called just after the
|
|
.Nm
|
|
driver closes the bulk pipes for the port.
|
|
.It Fn "void (*ucom_read)" "void *sc, int portno, u_char **ptr, u_int32_t *count"
|
|
if the data delivered on the bulk pipe is not just the raw input characters
|
|
this routine needs to adjust
|
|
.Fa ptr
|
|
and
|
|
.Fa count
|
|
so that they tell where to find the given number of raw characters.
|
|
.It Fn "void (*ucom_write)" "void *sc, int portno, u_char *dst, u_char *src, u_int32_t *count"
|
|
if the data written to the bulk pipe is not just the raw characters then
|
|
this routine needs to copy
|
|
.Fa count
|
|
raw characters from
|
|
.Fa src
|
|
into the buffer at
|
|
.Fa dst
|
|
and do the appropriate padding. The
|
|
.Fa count
|
|
should be updated to the new size.
|
|
The buffer at
|
|
.Fa src
|
|
is at most
|
|
.Va ibufsize
|
|
bytes and the buffer
|
|
at
|
|
.Fa dst
|
|
is
|
|
.Va ibufsizepad
|
|
bytes.
|
|
.El
|
|
.Pp
|
|
Apart from these methods there is a function
|
|
.Bl -tag -width 5n -offset 5n
|
|
.It Fn "void ucom_status_change" "struct ucom_softc *"
|
|
.El
|
|
.Pp
|
|
which should be called by the driver whenever it notices a status change.
|
|
.Sh SEE ALSO
|
|
.Xr tty 4 ,
|
|
.Xr uftdi 4 ,
|
|
.Xr umodem 4 ,
|
|
.Xr usb 4 ,
|
|
.Xr uvisor 4
|
|
.Sh HISTORY
|
|
This
|
|
.Nm
|
|
interface first appeared in
|
|
.Nx 1.5 .
|