NAME
ucom —
interface for USB tty like
devices
DESCRIPTION
The
ucom driver is a (relatively) easy way to make a USB
device look like a
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
uftdi(4)), modems (see
umodem(4)), and devices that
traditionally look like a tty (see
uvisor(4)).
Communication between the real driver and the
ucom driver is
via the attachment arguments (when attached) and via the
ucom_methods struct
ATTACHMENT
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;
};
-
-
int
ucaa_portno
- identifies the port if the devices should have more than
one ucom attached. Use the value
UCOM_UNK_PORTNO
if there is only one port.
-
-
int
ucaa_bulkin
- the number of the bulk input pipe.
-
-
int
ucaa_bulkout
- the number of the bulk output pipe.
-
-
u_int
ucaa_ibufsize
- the size of the read requests on the bulk in pipe.
-
-
u_int
ucaa_ibufsizepad
- the size of the input buffer. This is usually the same as
ibufsize
.
-
-
u_int
ucaa_obufsize
- the size of the write requests on the bulk out pipe.
-
-
u_int
ucaa_ibufsizepad
- the size of the output buffer. This is usually the same as
ucaa_obufsize
.
-
-
struct
usbd_device *ucaa_device
- a handle to the device.
-
-
- struct usbd_interface
*ucaa_iface
- a handle to the interface that should be used.
-
-
- struct ucom_methods
*ucaa_methods
- a pointer to the methods that the ucom
driver should use for further communication with the driver.
-
-
- void *ucaa_arg
- the value that should be passed as first argument to each
method.
METHODS
The
ucom_methods
struct contains a number of function
pointers used by the
ucom driver at various stages. If the
device is not interested in being called at a particular point it should just
use a
NULL
pointer and the
ucom
driver will use a sensible default.
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);
};
-
-
- void
(*ucom_get_status)(void *sc,
int portno, u_char *lsr,
u_char *msr)
- get the status of port portno. The
status consists of the line status, lsr, and the
modem status msr. The contents of these two bytes is
exactly as for a 16550 UART.
-
-
- void
(*ucom_set)(void *sc,
int portno, int reg,
int onoff)
- Set (or unset) a particular feature of a port.
-
-
- 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
termios(4) struct.
-
-
- int
(*ucom_ioctl)(void *sc,
int portno, u_long cmd,
void *data, int flag,
proc_t *p)
- implements any non-standard
ioctl(2) that a device
needs.
-
-
- int
(*ucom_open)(void *sc,
int portno)
- called just before the ucom driver opens
the bulk pipes for the port.
-
-
- void
(*ucom_close)(void *sc,
int portno)
- called just after the ucom driver closes
the bulk pipes for the port.
-
-
- 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 ptr
by as many characters to skip from the start of the raw input and
decrement count by as many characters to truncate
from the end of the raw input.
-
-
- 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 count raw
characters from src into the buffer at
dst and do the appropriate padding. The
count should be updated to the new size. The buffer
at src is at most ibufsize
bytes and the buffer at dst is
ibufsizepad bytes.
Apart from these methods there is a function
-
-
- void
ucom_status_change(struct ucom_softc
*)
-
which should be called by the driver whenever it notices a status change.
SEE ALSO
tty(4),
u3g(4),
uark(4),
ubsa(4),
uchcom(4),
uftdi(4),
ugensa(4),
uhmodem(4),
uipaq(4),
ukyopon(4),
umct(4),
umodem(4),
uplcom(4),
usb(4),
uslsa(4),
uvisor(4),
uvscom(4)
HISTORY
This
ucom interface first appeared in
NetBSD
1.5.