| blob | 9ff2377634ba834c0da54ecc4d3e663f48be4461 |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH USBVC 7D "Jul 18, 2008"
7 .SH NAME
8 usbvc \- USB video class driver
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/usb/clients/video/usbvc/usbvc.h>
14 #include <sys/videodev2.h>
16 usbvc@unit-address
17 .fi
19 .LP
20 .nf
22 .fi
24 .SH DESCRIPTION
25 .sp
26 .LP
27 The \fBusbvc\fR driver is a USBA (Solaris USB Architecture)-compliant client
28 driver that supports the \fIUSB Device Class Definition for Video Devices\fR
29 specification, Versions 1.0 and 1.1. The \fBusbvc\fR driver supports a subset
30 of the video controls and formats described in the USB specification.
31 .sp
32 .LP
33 The \fBusbvc\fR driver also implements the Video4Linux2 API (\fIV4L2\fR),
34 Version 0.20 for applications. For more information on the \fIV4L2 API\fR,
35 visit \fIhttp://www.thedirks.org/v4l2\fR.
36 .sp
37 .LP
38 Note that the \fBusbvc\fR driver supports the video capture function only and
39 that video output is not supported. For more information on supported USB
40 video-class devices and functions, visit \fIhttp://www.sun.com/io\fR.
41 .SH READING DATA
42 .sp
43 .LP
44 The \fBusbvc\fR driver reads video data from the isochronous endpoint of the
45 device. Bulk data endpoints are not supported.
46 .sp
47 .LP
48 MJPEG and UNCOMPRESSED video formats are supported. Isochronous data are read
49 from the isochronous input device frame-by-frame and are maintained in a
50 buffer array within the driver. Video frames are read from the driver using the
51 \fBread\fR(2) or \fBmmap\fR(2) I/O method. For \fBread\fR(2), each read returns
52 a buffer of a video frame. For \fBmmap\fR(2), each \fBVIDIOC_DQBUF\fR ioctl
53 returns the buffer structure v4l2_buffer. (A video frame buffer pointer is
54 included in the structure). See the \fIV4L2 API\fR for buffer structure and
55 other related data structure information.
56 .SH IOCTLS
57 .sp
58 .LP
59 A brief overview of supported ioctl requests appears below. For more detailed
60 information, refer to the \fIV4L2 API\fR document. Note: ioctl information
61 presented in the \fIV4L2 API\fR document may differ slightly from the content
62 of this manpage. In such cases, you should rely on the information in this
63 manpage.
64 .sp
65 .ne 2
66 .na
67 \fBVIDIOC_QUERYCAP\fR
68 .ad
69 .sp .6
70 .RS 4n
71 Query the device capabilities. Besides device capabilities, the \fBusbvc\fR
72 driver returns structure v4l2_capability which includes information on the
73 driver, data bus and OS kernel. Please note that the "Version" structure member
74 has no meaning in Solaris and is always set to 1.
75 .RE
77 .sp
78 .ne 2
79 .na
80 \fBVIDIOC_ENUM_FMT\fR
81 .ad
82 .sp .6
83 .RS 4n
84 Enumerate the video formats supported by the device.
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fBVIDIOC_S_FMT\fR
91 .ad
92 .sp .6
93 .RS 4n
94 Set a video format.
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fBVIDIOC_G_FMT\fR
101 .ad
102 .sp .6
103 .RS 4n
104 Get a video format.
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fBVIDIOC_REQBUFS\fR
111 .ad
112 .sp .6
113 .RS 4n
114 Request the \fBusbvc\fR driver to allocate video data buffers. If a buffer is
115 set to zero, the driver stops reading video data from the device and releases
116 all allocated buffers. (For \fBmmap\fR(2) only).
117 .RE
119 .sp
120 .ne 2
121 .na
122 \fBVIDIOC_QUERYBUF\fR
123 .ad
124 .sp .6
125 .RS 4n
126 Query a given buffer's status. (For \fBmmap\fR(2) only).
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fBVIDIOC_QBUF\fR
133 .ad
134 .sp .6
135 .RS 4n
136 Enqueue an empty buffer to the video data buffer array. (For \fBmmap\fR(2)
137 only).
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fBVIDIOC_DQBUF\fR
144 .ad
145 .sp .6
146 .RS 4n
147 Dequeue a done buffer from the video data buffer array. (For \fBmmap\fR(2)
148 only).
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fBVIDIOC_STREAMON\fR
155 .ad
156 .sp .6
157 .RS 4n
158 Start reading video data.
159 .RE
161 .sp
162 .ne 2
163 .na
164 \fBVIDIOC_STREAMOFF\fR
165 .ad
166 .sp .6
167 .RS 4n
168 Stop reading video data.
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fBVIDIOC_ENUMINPUT\fR
175 .ad
176 .sp .6
177 .RS 4n
178 Enumerate all device inputs. Currently, the \fBusbvc\fR driver supports one
179 input only.
180 .RE
182 .sp
183 .ne 2
184 .na
185 \fBVIDIOC_G_INPUT\fR
186 .ad
187 .sp .6
188 .RS 4n
189 Get the device's current input. At this time, the \fBusbvc\fR driver supports
190 one input only.
191 .RE
193 .sp
194 .ne 2
195 .na
196 \fBVIDIOC_S_INPUT\fR
197 .ad
198 .sp .6
199 .RS 4n
200 Set the device's current input. At this time, the \fBusbvc\fR driver supports
201 one input only.
202 .RE
204 .sp
205 .ne 2
206 .na
207 \fBVIDIOC_QUERYCTRL\fR
208 .ad
209 .sp .6
210 .RS 4n
211 Query the device and driver for supported video controls. Currently, the
212 \fBusbvc\fR driver supports the brightness, contrast, saturation, hue, and
213 gamma video controls.
214 .RE
216 .sp
217 .ne 2
218 .na
219 \fBVIDIOC_G_CTRL\fR
220 .ad
221 .sp .6
222 .RS 4n
223 Get the device's current video control.
224 .RE
226 .sp
227 .ne 2
228 .na
229 \fBVIDIOC_S_CTRL\fR
230 .ad
231 .sp .6
232 .RS 4n
233 Set the device's current video control.
234 .RE
236 .sp
237 .ne 2
238 .na
239 \fBVIDIOC_G_PARM\fR
240 .ad
241 .sp .6
242 .RS 4n
243 Get streaming parameters, the number of frames per second and number of buffers
244 used internally by driver in read/write mode.
245 .RE
247 .sp
248 .ne 2
249 .na
250 \fBVIDIOC_S_PARM\fR
251 .ad
252 .sp .6
253 .RS 4n
254 Set streaming parameters, the number of frames per second and number of buffers
255 used internally by driver in read/write mode.
256 .RE
258 .SH ERRORS
259 .sp
260 .ne 2
261 .na
262 \fB\fBEBUSY\fR\fR
263 .ad
264 .RS 10n
265 An open was attempted after the device has already been opened.
266 .RE
268 .sp
269 .ne 2
270 .na
271 \fB\fBEINVAL\fR\fR
272 .ad
273 .RS 10n
274 An unsupported ioctl is received or an ioctl is attempted with an out-of-range
275 value.
276 .RE
278 .sp
279 .ne 2
280 .na
281 \fB\fBEIO\fR\fR
282 .ad
283 .RS 10n
284 The driver received an unrecoverable device error or the device did not
285 respond or the device stalled when attempting an access. A \fBread\fR(2) or
286 \fBioctl\fR(2) did not complete due to a peripheral access.
287 .RE
289 .sp
290 .ne 2
291 .na
292 \fB\fBENXIO\fR\fR
293 .ad
294 .RS 10n
295 The driver received an \fBopen\fR(2) request for a device for which the attach
296 failed.
297 .RE
299 .sp
300 .ne 2
301 .na
302 \fBENODEV\fR
303 .ad
304 .RS 10n
305 The driver received an \fBopen\fR(2) request for a disconnected device.
306 .RE
308 .SH FILES
309 .sp
310 .ne 2
311 .na
312 \fB\fB/kernel/drv/usbvc\fR\fR
313 .ad
314 .sp .6
315 .RS 4n
316 32-bit ELF kernel module. (x86)
317 .RE
319 .sp
320 .ne 2
321 .na
322 \fB\fB/kernel/drv/amd64/usbvc\fR\fR
323 .ad
324 .sp .6
325 .RS 4n
326 64-bit ELF kernel module. (x86)
327 .RE
329 .sp
330 .ne 2
331 .na
332 \fB\fB/kernel/drv/sparcv9/usbvc\fR\fR
333 .ad
334 .sp .6
335 .RS 4n
336 64-bit ELF kernel module. (SPARC)
337 .RE
339 .sp
340 .ne 2
341 .na
342 \fB\fB/dev/usb/*/*/*\fR\fR
343 .ad
344 .sp .6
345 .RS 4n
346 \fBugen\fR(7D) nodes.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fB/dev/videoN\fR\fR
353 .ad
354 .sp .6
355 .RS 4n
356 Device node for isochronous input from USB video device and device control.
357 .RE
359 .SH ATTRIBUTES
360 .sp
361 .LP
362 See \fBattributes\fR(5) for descriptions of the following attributes:
363 .sp
365 .sp
366 .TS
367 box;
368 c | c
369 l | l .
370 ATTRIBUTE TYPE ATTRIBUTE VALUE
371 _
372 Architecture SPARC, x86, PCI-based systems
373 .TE
375 .SH SEE ALSO
376 .sp
377 .LP
378 \fBcfgadm_usb\fR(1M), \fBioctl\fR(2), \fBopen\fR(2), \fBmmap\fR(2),
379 \fBread\fR(2), \fBlibusb\fR(3LIB), \fBattributes\fR(5),\fBugen\fR(7D),
380 \fBusba\fR(7D), \fBattach\fR(9E)
381 .sp
382 .LP
383 \fIWriting Device Drivers\fR
384 .sp
385 .LP
386 \fISystem Administration Guide: Basic Administration\fR
387 .sp
388 .LP
389 \fIUniversal Serial Bus Specification 1.0, 1.1 and 2.0\fR\(em 1996, 1998, 2000
390 .sp
391 .LP
392 \fIUSB Device Class Definition for Video Devices 1.0 and 1.1\fR\(em 2003, 2005
393 .sp
394 .LP
395 \fIVideo4Linux2 API (V4L2), Version 0.20\fR
396 .sp
397 .LP
398 \fII/O Technologies and Solutions \(emhttp://www.sun.com/io\fR
399 .sp
400 .LP
401 \fIhttp://docs.sun.com\fR
402 .sp
403 .LP
404 \fIhttp://www.usb.org\fR
405 .sp
406 .LP
407 \fIhttp://www.thedirks.org/v4l2\fR
408 .SH DIAGNOSTICS
409 .sp
410 .LP
411 In addition to being logged, the following messages may appear on the system
412 console. All messages are formatted in the following manner:
413 .sp
414 .in +2
415 .nf
416 Warning: <device path> (usbvc<instance num>):Error Message...
417 .fi
418 .in -2
419 .sp
421 .sp
422 .ne 2
423 .na
424 \fBDevice was disconnected while open. Data may have been lost.\fR
425 .ad
426 .sp .6
427 .RS 4n
428 The device has been hot-removed or powered off while it was open and a possible
429 data transfer was in progress. The job may be aborted.
430 .RE
432 .sp
433 .ne 2
434 .na
435 \fBCannot access <device>. Please reconnect.\fR
436 .ad
437 .sp .6
438 .RS 4n
439 This device has been disconnected because a device other than the original one
440 has been inserted. The driver informs you of this fact by displaying the name
441 of the original device.
442 .RE
444 .sp
445 .ne 2
446 .na
447 \fBDevice is not identical to the previous one on this port. Please disconnect
448 and reconnect.\fR
449 .ad
450 .sp .6
451 .RS 4n
452 The device was hot-removed while open. A new device was hot-inserted which is
453 not identical to the original device. Please disconnect the device and
454 reconnect the original device to the same port.
455 .RE
457 .SH NOTES
458 .sp
459 .LP
460 The USB video device will be power-managed when the device is idle.
461 .sp
462 .LP
463 If a USB video device is hot-removed while active, a console warning is
464 displayed requesting you to put the device back in the same port and telling
465 you of potential data loss. Hot-removal of an active video device is strongly
466 discouraged.
467 .sp
468 .LP
469 Always close all applications before hot-removing or hot-inserting a device.
470 If an application is open when a device is hot-removed, inserting the device
471 in a different port will create new \fB/dev/video\fR\fIN\fR links. Moving
472 an active device to another port is not recommended.