diff options
Diffstat (limited to 'static/netbsd/man9/ucom.9')
| -rw-r--r-- | static/netbsd/man9/ucom.9 | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/static/netbsd/man9/ucom.9 b/static/netbsd/man9/ucom.9 new file mode 100644 index 00000000..08c2de28 --- /dev/null +++ b/static/netbsd/man9/ucom.9 @@ -0,0 +1,231 @@ +.\" $NetBSD: ucom.9,v 1.20 2025/04/12 10:22:50 bad 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_obufsizepad +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 . |