222 lines
6.8 KiB
Groff
222 lines
6.8 KiB
Groff
.\" $NetBSD: ucom.9,v 1.5 2001/06/21 11:59:01 wiz 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
|
|
|
|
.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)__P((void *sc, int portno,
|
|
u_char *lsr, u_char *msr));
|
|
void (*ucom_set)__P((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)__P((void *sc, int portno, struct termios *));
|
|
int (*ucom_ioctl)__P((void *sc, int portno, u_long cmd,
|
|
caddr_t data, int flag, struct proc *p));
|
|
int (*ucom_open)__P((void *sc, int portno));
|
|
void (*ucom_close)__P((void *sc, int portno));
|
|
void (*ucom_read)__P((void *sc, int portno, u_char **ptr,
|
|
u_int32_t *count));
|
|
void (*ucom_write)__P((void *sc, int portno, u_char *to,
|
|
u_char *from, u_int32_t *count));
|
|
};
|
|
.Ed
|
|
|
|
.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 indent 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 .
|