Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src/share/man/man9 Add a man page describing the ucom interface ...
details: https://anonhg.NetBSD.org/src/rev/84bd1ae906b6
branches: trunk
changeset: 484944:84bd1ae906b6
user: augustss <augustss%NetBSD.org@localhost>
date: Sat Apr 15 17:20:26 2000 +0000
description:
Add a man page describing the ucom interface for making tty like USB devices.
diffstat:
share/man/man9/Makefile | 4 +-
share/man/man9/ucom.9 | 221 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 223 insertions(+), 2 deletions(-)
diffs (243 lines):
diff -r c774ff9bb350 -r 84bd1ae906b6 share/man/man9/Makefile
--- a/share/man/man9/Makefile Sat Apr 15 16:49:35 2000 +0000
+++ b/share/man/man9/Makefile Sat Apr 15 17:20:26 2000 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.59 2000/03/27 09:56:01 soda Exp $
+# $NetBSD: Makefile,v 1.60 2000/04/15 17:20:26 augustss Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -9,7 +9,7 @@
log.9 malloc.9 mbuf.9 microtime.9 panic.9 pfil.9 physio.9 pool.9 \
powerhook_establish.9 psignal.9 ratecheck.9 resettodr.9 rnd.9 \
rt_timer.9 shutdownhook_establish.9 \
- sleep.9 spl.9 store.9 time.9 uiomove.9 usbdi.9 uvm.9 \
+ sleep.9 spl.9 store.9 time.9 uiomove.9 ucom.9 usbdi.9 uvm.9 \
wdc.9
MLINKS+=arp.9 arp_ifinit.9 arp.9 arpresolve.9 arp.9 arpintr.9
MLINKS+=access.9 kernacc.9 access.9 useracc.9
diff -r c774ff9bb350 -r 84bd1ae906b6 share/man/man9/ucom.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/ucom.9 Sat Apr 15 17:20:26 2000 +0000
@@ -0,0 +1,221 @@
+.\" $NetBSD: ucom.9,v 1.1 2000/04/15 17:20:26 augustss 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
+(
+.Xr uftdt 4 ),
+modems (
+.Xr umodem 4 ),
+and devices that traditionally look like a tty (
+.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 havce 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 Dv void (*ucom_get_status) (void *sc, int portno, u_char *lsr, u_char *msr)
+get the status of port
+.Dv portno .
+The status consists of the line status,
+.Dv lsr ,
+and the modem status
+.Dv msr .
+The contents of these two bytes is exactly as for a 16550 UART.
+.It void (*ucom_set)(void *sc, int portno, int reg, int onoff)
+Set (or unset) a particular feature of a port.
+.It 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 int (*ucom_ioctl)(void *sc, int portno, u_long cmd, caddr_t data, int flag, struct proc *p)
+implements any non-standard
+.Xr ioctl 4
+that a device needs.
+.It int (*ucom_open)(void *sc, int portno)
+called just before the
+.Nm
+driver opens the bulk pipes for the port.
+.It void (*ucom_close)(void *sc, int portno)
+called just after the
+.Nm
+driver closes the bulk pipes for the port.
+.It 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
+.Dv ptr
+and
+.Dv count
+so that they tell where to find the given number of raw characters.
+.It 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
+.Dv
+count raw characters from
+.Dv src
+into the buffer at
+.Dv dst
+and do the appropriate padding. The
+.Dv count
+should be updated to the new size.
+The buffer at
+.Dv src
+is at most
+.Dv ibufsize
+bytes and the buffer
+at
+.Dv dst
+is
+.Dv ibufsizepad
+bytes.
+.El
+.Pp
+Apart from these methods there is a function
+.Bl -tag -width indent 5n
+.It Dv 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 .
Home |
Main Index |
Thread Index |
Old Index