232 lines
6.7 KiB
Groff
232 lines
6.7 KiB
Groff
.\" $NetBSD: ucom.9,v 1.19 2016/10/12 21:18:46 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.
|
|
.\"
|
|
.\" 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 September 12, 2016
|
|
.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 ucaa_portno;
|
|
int ucaa_bulkin;
|
|
int ucaa_bulkout;
|
|
u_int ucaa_ibufsize;
|
|
u_int ucaa_ibufsizepad;
|
|
u_int ucaa_obufsize;
|
|
u_int ucaa_opkthdrlen;
|
|
const char *ucaa_info;
|
|
struct usbd_device *ucaa_device;
|
|
struct usbd_interface *ucaa_iface;
|
|
const struct ucom_methods *ucaa_methods;
|
|
void *ucaa_arg;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Bl -tag -width indent
|
|
.It Dv int ucaa_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 ucaa_bulkin
|
|
the number of the bulk input pipe.
|
|
.It Dv int ucaa_bulkout
|
|
the number of the bulk output pipe.
|
|
.It Dv u_int ucaa_ibufsize
|
|
the size of the read requests on the bulk in pipe.
|
|
.It Dv u_int ucaa_ibufsizepad
|
|
the size of the input buffer.
|
|
This is usually the same as
|
|
.Dv ibufsize .
|
|
.It Dv u_int ucaa_obufsize
|
|
the size of the write requests on the bulk out pipe.
|
|
.It Dv u_int ucaa_ibufsizepad
|
|
the size of the output buffer.
|
|
This is usually the same as
|
|
.Dv ucaa_obufsize .
|
|
.It Dv struct usbd_device *ucaa_device
|
|
a handle to the device.
|
|
.It struct usbd_interface *ucaa_iface
|
|
a handle to the interface that should be used.
|
|
.It struct ucom_methods *ucaa_methods
|
|
a pointer to the methods that the
|
|
.Nm
|
|
driver should use for further communication with the driver.
|
|
.It void *ucaa_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,
|
|
void *data, int flag, proc_t *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,
|
|
uint32_t *count);
|
|
void (*ucom_write)(void *sc, int portno, u_char *to,
|
|
u_char *from, uint32_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" "void *data" "int flag" "proc_t *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" "uint32_t *count"
|
|
if the data delivered on the bulk pipe is not just the raw input characters
|
|
this routine needs to increment
|
|
.Fa ptr
|
|
by as many characters to skip from the start of the raw input and decrement
|
|
.Fa count
|
|
by as many characters to truncate from the end of the raw input.
|
|
.It Fn "void (*ucom_write)" "void *sc" "int portno" "u_char *dst" "u_char *src" "uint32_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
|
|
.\" moscom
|
|
.Xr tty 4 ,
|
|
.Xr u3g 4 ,
|
|
.Xr uark 4 ,
|
|
.Xr ubsa 4 ,
|
|
.Xr uchcom 4 ,
|
|
.Xr uftdi 4 ,
|
|
.Xr ugensa 4 ,
|
|
.Xr uhmodem 4 ,
|
|
.Xr uipaq 4 ,
|
|
.Xr ukyopon 4 ,
|
|
.Xr umct 4 ,
|
|
.Xr umodem 4 ,
|
|
.Xr uplcom 4 ,
|
|
.Xr usb 4 ,
|
|
.Xr uslsa 4 ,
|
|
.Xr uvisor 4 ,
|
|
.Xr uvscom 4
|
|
.Sh HISTORY
|
|
This
|
|
.Nm
|
|
interface first appeared in
|
|
.Nx 1.5 .
|