Wed Oct 12 21:18:46 2016 UTC ()
Fix xref, sort SEE ALSO.


(wiz)
diff -r1.18 -r1.19 src/share/man/man9/ucom.9
cvs diff -r1.18 -r1.19 src/share/man/man9/ucom.9 (switch to unified diff)

--- src/share/man/man9/ucom.9 2016/10/12 21:09:36 1.18
+++ src/share/man/man9/ucom.9 2016/10/12 21:18:46 1.19
@@ -1,231 +1,231 @@ @@ -1,231 +1,231 @@
1.\" $NetBSD: ucom.9,v 1.18 2016/10/12 21:09:36 skrll Exp $ 1.\" $NetBSD: ucom.9,v 1.19 2016/10/12 21:18:46 wiz Exp $
2.\" 2.\"
3.\" Copyright (c) 2000 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Lennart Augustsson. 7.\" by Lennart Augustsson.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\" notice, this list of conditions and the following disclaimer in the 15.\" notice, this list of conditions and the following disclaimer in the
16.\" documentation and/or other materials provided with the distribution. 16.\" documentation and/or other materials provided with the distribution.
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd September 12, 2016 30.Dd September 12, 2016
31.Dt UCOM 9 31.Dt UCOM 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm ucom 34.Nm ucom
35.Nd interface for USB tty like devices 35.Nd interface for USB tty like devices
36.Sh DESCRIPTION 36.Sh DESCRIPTION
37The 37The
38.Nm 38.Nm
39driver is a (relatively) easy way to make a USB device look like 39driver is a (relatively) easy way to make a USB device look like
40a 40a
41.Xr tty 4 . 41.Xr tty 4 .
42It basically takes two bulk pipes, input and output, and makes 42It basically takes two bulk pipes, input and output, and makes
43a tty out of them. 43a tty out of them.
44This is useful for a number of device types, e.g., serial ports 44This is useful for a number of device types, e.g., serial ports
45(see 45(see
46.Xr uftdi 4 ) , 46.Xr uftdi 4 ) ,
47modems (see 47modems (see
48.Xr umodem 4 ) , 48.Xr umodem 4 ) ,
49and devices that traditionally look like a tty (see 49and devices that traditionally look like a tty (see
50.Xr uvisor 4 ) . 50.Xr uvisor 4 ) .
51.Pp 51.Pp
52Communication between the real driver and the 52Communication between the real driver and the
53.Nm 53.Nm
54driver is via the attachment arguments (when attached) and 54driver is via the attachment arguments (when attached) and
55via the 55via the
56.Va ucom_methods 56.Va ucom_methods
57struct 57struct
58.Sh ATTACHMENT 58.Sh ATTACHMENT
59.Bd -literal 59.Bd -literal
60struct ucom_attach_args { 60struct ucom_attach_args {
61 int ucaa_portno; 61 int ucaa_portno;
62 int ucaa_bulkin; 62 int ucaa_bulkin;
63 int ucaa_bulkout; 63 int ucaa_bulkout;
64 u_int ucaa_ibufsize; 64 u_int ucaa_ibufsize;
65 u_int ucaa_ibufsizepad; 65 u_int ucaa_ibufsizepad;
66 u_int ucaa_obufsize; 66 u_int ucaa_obufsize;
67 u_int ucaa_opkthdrlen; 67 u_int ucaa_opkthdrlen;
68 const char *ucaa_info; 68 const char *ucaa_info;
69 struct usbd_device *ucaa_device; 69 struct usbd_device *ucaa_device;
70 struct usbd_interface *ucaa_iface; 70 struct usbd_interface *ucaa_iface;
71 const struct ucom_methods *ucaa_methods; 71 const struct ucom_methods *ucaa_methods;
72 void *ucaa_arg; 72 void *ucaa_arg;
73}; 73};
74.Ed 74.Ed
75.Pp 75.Pp
76.Bl -tag -width indent 76.Bl -tag -width indent
77.It Dv int ucaa_portno 77.It Dv int ucaa_portno
78identifies the port if the devices should have more than one 78identifies the port if the devices should have more than one
79.Nm 79.Nm
80attached. 80attached.
81Use the value 81Use the value
82.Dv UCOM_UNK_PORTNO 82.Dv UCOM_UNK_PORTNO
83if there is only one port. 83if there is only one port.
84.It Dv int ucaa_bulkin 84.It Dv int ucaa_bulkin
85the number of the bulk input pipe. 85the number of the bulk input pipe.
86.It Dv int ucaa_bulkout 86.It Dv int ucaa_bulkout
87the number of the bulk output pipe. 87the number of the bulk output pipe.
88.It Dv u_int ucaa_ibufsize 88.It Dv u_int ucaa_ibufsize
89the size of the read requests on the bulk in pipe. 89the size of the read requests on the bulk in pipe.
90.It Dv u_int ucaa_ibufsizepad 90.It Dv u_int ucaa_ibufsizepad
91the size of the input buffer. 91the size of the input buffer.
92This is usually the same as 92This is usually the same as
93.Dv ibufsize . 93.Dv ibufsize .
94.It Dv u_int ucaa_obufsize 94.It Dv u_int ucaa_obufsize
95the size of the write requests on the bulk out pipe. 95the size of the write requests on the bulk out pipe.
96.It Dv u_int ucaa_ibufsizepad 96.It Dv u_int ucaa_ibufsizepad
97the size of the output buffer. 97the size of the output buffer.
98This is usually the same as 98This is usually the same as
99.Dv ucaa_obufsize . 99.Dv ucaa_obufsize .
100.It Dv struct usbd_device *ucaa_device 100.It Dv struct usbd_device *ucaa_device
101a handle to the device. 101a handle to the device.
102.It struct usbd_interface *ucaa_iface 102.It struct usbd_interface *ucaa_iface
103a handle to the interface that should be used. 103a handle to the interface that should be used.
104.It struct ucom_methods *ucaa_methods 104.It struct ucom_methods *ucaa_methods
105a pointer to the methods that the 105a pointer to the methods that the
106.Nm 106.Nm
107driver should use for further communication with the driver. 107driver should use for further communication with the driver.
108.It void *ucaa_arg 108.It void *ucaa_arg
109the value that should be passed as first argument to each method. 109the value that should be passed as first argument to each method.
110.El 110.El
111.Sh METHODS 111.Sh METHODS
112The 112The
113.Dv ucom_methods 113.Dv ucom_methods
114struct contains a number of function pointers used by the 114struct contains a number of function pointers used by the
115.Nm 115.Nm
116driver at various stages. 116driver at various stages.
117If the device is not interested in being called at a particular point 117If the device is not interested in being called at a particular point
118it should just use a 118it should just use a
119.Dv NULL 119.Dv NULL
120pointer and the 120pointer and the
121.Nm 121.Nm
122driver will use a sensible default. 122driver will use a sensible default.
123.Bd -literal 123.Bd -literal
124struct ucom_methods { 124struct ucom_methods {
125 void (*ucom_get_status)(void *sc, int portno, 125 void (*ucom_get_status)(void *sc, int portno,
126 u_char *lsr, u_char *msr); 126 u_char *lsr, u_char *msr);
127 void (*ucom_set)(void *sc, int portno, int reg, int onoff); 127 void (*ucom_set)(void *sc, int portno, int reg, int onoff);
128#define UCOM_SET_DTR 1 128#define UCOM_SET_DTR 1
129#define UCOM_SET_RTS 2 129#define UCOM_SET_RTS 2
130#define UCOM_SET_BREAK 3 130#define UCOM_SET_BREAK 3
131 int (*ucom_param)(void *sc, int portno, struct termios *); 131 int (*ucom_param)(void *sc, int portno, struct termios *);
132 int (*ucom_ioctl)(void *sc, int portno, u_long cmd, 132 int (*ucom_ioctl)(void *sc, int portno, u_long cmd,
133 void *data, int flag, proc_t *p); 133 void *data, int flag, proc_t *p);
134 int (*ucom_open)(void *sc, int portno); 134 int (*ucom_open)(void *sc, int portno);
135 void (*ucom_close)(void *sc, int portno); 135 void (*ucom_close)(void *sc, int portno);
136 void (*ucom_read)(void *sc, int portno, u_char **ptr, 136 void (*ucom_read)(void *sc, int portno, u_char **ptr,
137 uint32_t *count); 137 uint32_t *count);
138 void (*ucom_write)(void *sc, int portno, u_char *to, 138 void (*ucom_write)(void *sc, int portno, u_char *to,
139 u_char *from, uint32_t *count); 139 u_char *from, uint32_t *count);
140}; 140};
141.Ed 141.Ed
142.Pp 142.Pp
143.Bl -tag -width indent 143.Bl -tag -width indent
144.It Fn "void (*ucom_get_status)" "void *sc" "int portno" "u_char *lsr" "u_char *msr" 144.It Fn "void (*ucom_get_status)" "void *sc" "int portno" "u_char *lsr" "u_char *msr"
145get the status of port 145get the status of port
146.Fa portno . 146.Fa portno .
147The status consists of the line status, 147The status consists of the line status,
148.Fa lsr , 148.Fa lsr ,
149and the modem status 149and the modem status
150.Fa msr . 150.Fa msr .
151The contents of these two bytes is exactly as for a 16550 UART. 151The contents of these two bytes is exactly as for a 16550 UART.
152.It Fn "void (*ucom_set)" "void *sc" "int portno" "int reg" "int onoff" 152.It Fn "void (*ucom_set)" "void *sc" "int portno" "int reg" "int onoff"
153Set (or unset) a particular feature of a port. 153Set (or unset) a particular feature of a port.
154.It Fn "int (*ucom_param)" "void *sc" "int portno" "struct termios *t" 154.It Fn "int (*ucom_param)" "void *sc" "int portno" "struct termios *t"
155Set the speed, number of data bit, stop bits, and parity of a port 155Set the speed, number of data bit, stop bits, and parity of a port
156according to the 156according to the
157.Xr termios 4 157.Xr termios 4
158struct. 158struct.
159.It Fn "int (*ucom_ioctl)" "void *sc" "int portno" "u_long cmd" "void *data" "int flag" "proc_t *p" 159.It Fn "int (*ucom_ioctl)" "void *sc" "int portno" "u_long cmd" "void *data" "int flag" "proc_t *p"
160implements any non-standard 160implements any non-standard
161.Xr ioctl 2 161.Xr ioctl 2
162that a device needs. 162that a device needs.
163.It Fn "int (*ucom_open)" "void *sc" "int portno" 163.It Fn "int (*ucom_open)" "void *sc" "int portno"
164called just before the 164called just before the
165.Nm 165.Nm
166driver opens the bulk pipes for the port. 166driver opens the bulk pipes for the port.
167.It Fn "void (*ucom_close)" "void *sc" "int portno" 167.It Fn "void (*ucom_close)" "void *sc" "int portno"
168called just after the 168called just after the
169.Nm 169.Nm
170driver closes the bulk pipes for the port. 170driver closes the bulk pipes for the port.
171.It Fn "void (*ucom_read)" "void *sc" "int portno" "u_char **ptr" "uint32_t *count" 171.It Fn "void (*ucom_read)" "void *sc" "int portno" "u_char **ptr" "uint32_t *count"
172if the data delivered on the bulk pipe is not just the raw input characters 172if the data delivered on the bulk pipe is not just the raw input characters
173this routine needs to increment 173this routine needs to increment
174.Fa ptr 174.Fa ptr
175by as many characters to skip from the start of the raw input and decrement 175by as many characters to skip from the start of the raw input and decrement
176.Fa count 176.Fa count
177by as many characters to truncate from the end of the raw input. 177by as many characters to truncate from the end of the raw input.
178.It Fn "void (*ucom_write)" "void *sc" "int portno" "u_char *dst" "u_char *src" "uint32_t *count" 178.It Fn "void (*ucom_write)" "void *sc" "int portno" "u_char *dst" "u_char *src" "uint32_t *count"
179if the data written to the bulk pipe is not just the raw characters then 179if the data written to the bulk pipe is not just the raw characters then
180this routine needs to copy 180this routine needs to copy
181.Fa count 181.Fa count
182raw characters from 182raw characters from
183.Fa src 183.Fa src
184into the buffer at 184into the buffer at
185.Fa dst 185.Fa dst
186and do the appropriate padding. 186and do the appropriate padding.
187The 187The
188.Fa count 188.Fa count
189should be updated to the new size. 189should be updated to the new size.
190The buffer at 190The buffer at
191.Fa src 191.Fa src
192is at most 192is at most
193.Va ibufsize 193.Va ibufsize
194bytes and the buffer 194bytes and the buffer
195at 195at
196.Fa dst 196.Fa dst
197is 197is
198.Va ibufsizepad 198.Va ibufsizepad
199bytes. 199bytes.
200.El 200.El
201.Pp 201.Pp
202Apart from these methods there is a function 202Apart from these methods there is a function
203.Bl -tag -width 5n -offset 5n 203.Bl -tag -width 5n -offset 5n
204.It Fn "void ucom_status_change" "struct ucom_softc *" 204.It Fn "void ucom_status_change" "struct ucom_softc *"
205.El 205.El
206.Pp 206.Pp
207which should be called by the driver whenever it notices a status change. 207which should be called by the driver whenever it notices a status change.
208.Sh SEE ALSO 208.Sh SEE ALSO
209.\" moscom 209.\" moscom
210.Xr tty 4 , 210.Xr tty 4 ,
211.Xr u3g 4 , 211.Xr u3g 4 ,
212.Xr uark 4 , 212.Xr uark 4 ,
213.Xr ubsa 4 , 213.Xr ubsa 4 ,
214.Xr uchcom 4 , 214.Xr uchcom 4 ,
215.Xr uftdi 4 , 215.Xr uftdi 4 ,
216.Xr ugensa 4 , 216.Xr ugensa 4 ,
217.Xr uhmodem 4 , 217.Xr uhmodem 4 ,
218.Xr uipaq 4 , 218.Xr uipaq 4 ,
219.Xr ukyopon 219.Xr ukyopon 4 ,
220.Xr umct 4 , 220.Xr umct 4 ,
221.Xr umodem 4 , 221.Xr umodem 4 ,
222.Xr usb 4 , 
223.Xr uplcom 4 , 222.Xr uplcom 4 ,
 223.Xr usb 4 ,
224.Xr uslsa 4 , 224.Xr uslsa 4 ,
225.Xr uvisor 4 , 225.Xr uvisor 4 ,
226.Xr uvscom 4 226.Xr uvscom 4
227.Sh HISTORY 227.Sh HISTORY
228This 228This
229.Nm 229.Nm
230interface first appeared in 230interface first appeared in
231.Nx 1.5 . 231.Nx 1.5 .