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