1 DCAM1394(7D) Devices DCAM1394(7D)
2
3
4
5 NAME
6 dcam1394 - 1394-based digital camera (IIDC) driver
7
8 SYNOPSIS
9 #include <sys/dcam/dcam1394_io.h>
10
11
12 DESCRIPTION
13 The dcam1394 driver supports devices implementing the 1394 Trade
14 Association Digital Camera Specification (also referred to as the IIDC
15 specification). Only a subset of the specification is supported.
16
17 READING DATA
18 Isochronous data is read from the driver frame-by-frame and is
19 maintained within the driver in a ring buffer.
20
21
22 Video frames are read from the isochronous input device using read(2).
23
24
25 The dcam1394_frame_t structure describes the frame layout and is
26 defined as follows:
27
28 struct {
29 unsigned int vid_mode;
30 unsigned int seq_num;
31 hrtime_t timestamp;
32 unsigned char *buff;
33 };
34
35
36
37 The size to allocate for the structure is determined by the video mode
38 for which the camera is configured. Possible values for the vid_mode
39 field are listed under DCAM1394_PARAM_VID_MODE below.
40
41 IOCTL REQUESTS
42 The following ioctl requests are supported:
43
44 DCAM1394_CMD_CAM_RESET
45
46 Reset the device.
47
48
49 DCAM1394_CMD_REG_READ
50
51 Read the indicated dcam/IIDC register. The argument is a pointer to
52 a dcam1394_reg_io_t structure, which is defined as follows:
53
54 struct {
55 unsigned int offs;
56 unsigned int val;
57 };
58
59 The offs field should be set to the offset of the register from
60 which to read. Register offset values are defined in the 1394
61 Trade Association Digital Camera Specification.
62
63 After the operation is completed, the camera register value is put
64 in the val field.
65
66
67 DCAM1394_CMD_REG_WRITE
68
69 Write the indicated dcam/IIDC register. The argument is a pointer
70 to a dcam1394_reg_io_t structure (described above).
71
72 The offs field should be set to the offset of the register from
73 which to read. The register offset values are defined in the 1394
74 Trade Association Digital Camera Specification.
75
76 The val field should be set to the value to be written to the
77 camera register.
78
79
80 DCAM1394_CMD_PARAM_GET
81
82 Gets a list of parameters associated with a camera. The argument is
83 a pointer to a dcam1394_param_list_t structure (described below).
84 The parameter list is accessed through macros defined below.
85
86 The parameter list only supports Format 1 video formats.
87
88
89 DCAM1394_CMD_PARAM_SET
90
91 Sets a list of parameters associated with a camera. The argument is
92 a pointer to a dcam1394_param_list_t structure (described below).
93 The parameter list is accessed through macros defined below.
94
95 The parameter list only supports Format 1 video formats.
96
97
98 DCAM1394_CMD_FRAME_RCV_START
99
100 Start receiving video frames from the camera.
101
102 The contents of the ring buffer may be accessed by reading the
103 isochronous stream device.
104
105
106 DCAM1394_CMD_FRAME_RCV_STOP
107
108 Stop receiving frames from the camera.
109
110
111 DCAM1394_CMD_RING_BUFF_FLUSH
112
113 Flush the frames in the ring buffer.
114
115
116 DCAM1394_CMD_FRAME_SEQ_NUM_COUNT_RESET
117
118 Reset frame sequence number.
119
120
121 PARAMETER LIST ACCESS
122 The parameter list is initialized and access through macros. The data
123 type for the parameter list is dcam1394_param_list_t.
124
125
126 The following macros are used to access the parameter list:
127
128 PARAM_LIST_INIT(param_list)
129
130 Initialize the parameter list.
131
132
133 PARAM_LIST_ADD(param_list, param, subparam)
134
135 Add a parameter to the list.
136
137
138 PARAM_LIST_REMOVE(param_list, param, subparam)
139
140 Remove a parameter from the list.
141
142
143 PARAM_LIST_IS_ENTRY(param_list, param, subparam)
144
145 Indicates if a specific parameter is in the list.
146
147
148 PARAM_VAL(param_list, param, subparam)
149
150 Value of a specified parameter.
151
152
153 PARAM_ERR(param_list, param, subparam)
154
155 Indicates if a specific parameter is successfully set.
156
157
158
159 When no subparam value is required, the value DCAM1394_SUBPARAM_NONE
160 may be used.
161
162 PARAMETERS
163 The following parameters may appear in the list:
164
165 DCAM1394_PARAM_CAP_POWER_CTRL
166
167 Queries if the camera can be turned off and on through software.
168 The subparam value is ignored.
169
170
171 DCAM1394_PARAM_POWER
172
173 Controls or queries if the camera is powered up. Verify this
174 feature using DCAM1394_PARAM_CAP_POWER_CTRL before use. The
175 subparam field is ignored.
176
177
178 DCAM1394_PARAM_CAP_VID_MOD
179
180 Queries if a specific video mode is supported by the camera.
181
182 subparam is one of the following and is used to determine if a
183 specified video mode is supported by the camera:
184
185 DCAM1394_SUBPARAM_VID_MODE_0
186 DCAM1394_SUBPARAM_VID_MODE_YUV_444_160_120
187 Video mode is 4:4:4, YUV color space, 160x120 resolution.
188
189 DCAM1394_SUBPARAM_VID_MODE_1
190 DCAM1394_SUBPARAM_VID_MODE_YUV_422_320_240
191 Video mode is 4:2:2, YUV color space, 320x240 resolution.
192
193 DCAM1394_SUBPARAM_VID_MODE_2
194 DCAM1394_SUBPARAM_VID_MODE_YUV_411_640_480
195 Video mode is 4:1:1, YUV color space, 640x480 resolution.
196
197 DCAM1394_SUBPARAM_VID_MODE_3
198 DCAM1394_SUBPARAM_VID_MODE_YUV_422_640_480
199 Video mode is 4:2:2, YUV color space, 640x480 resolution.
200
201 DCAM1394_SUBPARAM_VID_MODE_4
202 DCAM1394_SUBPARAM_VID_MODE_RGB_640_480
203 Video mode is RGB color space, 640x480 resolution.
204
205 DCAM1394_SUBPARAM_VID_MODE_5
206 DCAM1394_SUBPARAM_VID_MODE_Y_640_480
207 Video mode is Y color space, 640x480 resolution.
208
209
210
211 DCAM1394_PARAM_VID_MODE
212
213 Controls or queries the current video mode of the camera. The
214 subparam field is ignored. When selecting the video mode, it should
215 be compatible with the capability of the camera, which may be
216 determined by checking the DCAM1394_PARAM_CAP_VID_MODE parameter.
217
218 The value of this parameter may be one of the following:
219
220 DCAM1394_VID_MODE_0
221 DCAM1394_VID_MODE_YUV_444_160_120
222 Video mode is 4:4:4, YUV color space, 160x120 resolution.
223
224 DCAM1394_VID_MODE_1
225 DCAM1394_VID_MODE_YUV_422_320_240
226 Video mode is 4:2:2, YUV color space, 320x240 resolution.
227
228 DCAM1394_VID_MODE_2
229 DCAM1394_VID_MODE_YUV_411_640_480
230 Video mode is 4:1:1, YUV color space, 640x480 resolution.
231
232 DCAM1394_VID_MODE_3
233 DCAM1394_VID_MODE_YUV_422_640_480
234 Video mode is 4:2:2, YUV color space, 640x480 resolution.
235
236 DCAM1394_VID_MODE_4
237 DCAM1394_VID_MODE_RGB_640_480
238 Video mode is RGB color space, 640x480 resolution.
239
240 DCAM1394_VID_MODE_5
241 DCAM1394_VID_MODE_Y_640_480
242 Video mode is Y color space, 640x480 resolution.
243
244
245
246 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_0
247
248 Queries if a specific frame rate is supported by the camera in
249 video mode 0 (4:4:4, YUV, 160x120).
250
251 subparam is one of the following and used to determine if a
252 specified frame rate is supported by the camera:
253
254 DCAM1394_SUBPARAM_FRAME_RATE_0
255 DCAM1394_SUBPARAM_FRAME_RATE_3_75_FPS
256 Frame rate is 3.75 frames/second.
257
258 DCAM1394_SUBPARAM_FRAME_RATE_1
259 DCAM1394_SUBPARAM_FRAME_RATE_7_5_FPS
260 Frame rate is 7.5 frames/second.
261
262 DCAM1394_SUBPARAM_FRAME_RATE_2
263 DCAM1394_SUBPARAM_FRAME_RATE_15_FPS
264 Frame rate is 15 frames/second.
265
266 DCAM1394_SUBPARAM_FRAME_RATE_3
267 DCAM1394_SUBPARAM_FRAME_RATE_30_FPS
268 Frame rate is 30 frames/second.
269
270 DCAM1394_SUBPARAM_FRAME_RATE_4
271 DCAM1394_SUBPARAM_FRAME_RATE_60_FPS
272 Frame rate is 60 frames/second.
273
274
275
276 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_1
277
278 Queries if a specific frame rate is supported by the camera in
279 video mode 1 (4:2:2, YUV, 320x240). See
280 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_0 for a listing of valid
281 subparam values.
282
283
284 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_2
285
286 Queries if a specific frame rate is supported by the camera in
287 video mode 2 (4:1:1, YUV, 640x480). See
288 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_0 for a listing of valid
289 subparam values.
290
291
292 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_3
293
294 Queries if a specific frame rate is supported by the camera in
295 video mode 3 (4:2:2, YUV, 640x480). See
296 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_0 for a listing of valid
297 subparam values.
298
299
300 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_4
301
302 Queries if a specific frame rate is supported by the camera in
303 video mode 4. (RGB, 640x480). See
304 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_0 for a listing of valid
305 subparam values.
306
307
308 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_5
309
310 Queries if a specific frame rate is supported by the camera in
311 video mode 5. (Y, 640x480). See
312 DCAM1394_PARAM_CAP_FRAME_RATE_VID_MODE_0 for a listing of valid
313 subparam values.
314
315
316 DCAM1394_PARAM_FRAME_RATE
317
318 Controls or queries the current frame rate of the camera. The
319 subparam field is ignored. When selecting a frame rate, it should
320 be compatible with the capability of the camera, which can be
321 determined by querying one of the frame rate capability parameters
322 above.
323
324 The value of this parameter may be one of the following:
325
326 DCAM1394_FRAME_RATE_0
327 DCAM1394_3_75_FPS
328 The frame rate is 3.75 frames per second.
329
330 DCAM1394_FRAME_RATE_1
331 DCAM1394_7_5_FPS
332 The frame rate is 7.5 frames per second.
333
334 DCAM1394_FRAME_RATE_2
335 DCAM1394_15_FPS
336 The frame rate is 15 frames per second.
337
338 DCAM1394_FRAME_RATE_3
339 DCAM1394_30_FPS
340 The frame rate is 30 frames per second.
341
342 DCAM1394_FRAME_RATE_4
343 DCAM1394_60_FPS
344 The frame rate is 60 frames per second.
345
346
347
348 DCAM1394_PARAM_RING_BUFF_CAPACITY
349
350 Controls or queries the number of frames that the ring buffer may
351 hold. This value can range between 2 and 30. The subparam field is
352 ignored.
353
354
355 DCAM1394_PARAM_RING_BUFF_NUM_FRAMES_READY
356
357 Queries the number of frames in the ring buffer ready to be
358 accessed. The subparam field is ignored.
359
360
361 DCAM1394_PARAM_RING_BUFF_READ_PTR_INCR
362
363 Controls or queries the number of bytes to advance the read pointer
364 as it consumes data from the ring buffer. The subparam field is
365 ignored.
366
367
368 DCAM1394_PARAM_FRAME_NUM_BYTES
369
370 Queries the number of bytes in a frame at the current video mode.
371 The subparam field is ignored.
372
373
374 DCAM1394_PARAM_STATUS
375
376 Queries the parameter status. The subparam field is ignored.
377
378 The values for the parameter status is a bit field with the
379 following values possibly set:
380
381 DCAM1394_STATUS_FRAME_RCV_DONE
382
383 Frame successfully received.
384
385
386 DCAM1394_STATUS_RING_BUFF_LOST_FRAME
387
388 A frame has been lost while processing the ring buffer.
389
390
391 DCAM1394_STATUS_PARAM_CHANGE
392
393 A parameter has been changed.
394
395
396 DCAM1394_STATUS_FRAME_SEQ_NUM_COUNT_OVERFLOW
397
398 Frame sequence number has reached its maximum possible value
399 and has overflowed.
400
401
402 DCAM1394_STATUS_CAM_UNPLUG
403
404 Camera has been unplugged.
405
406
407
408 DCAM1394_PARAM_BRIGHTNESS
409
410 Query or control a camera feature. This feature queries or controls
411 the brightness of the camera.
412
413 DCAM1394_SUBPARAM_PRESENCE
414
415 Indicates if the feature is available.
416
417
418 DCAM1394_SUBPARAM_CAP_ON_OFF
419
420 Indicates if the feature may be enabled and disabled. May only
421 be queried.
422
423
424 DCAM1394_SUBPARAM_ON_OFF
425
426 Indicates if the feature is enabled.
427
428
429 DCAM1394_SUBPARAM_CAP_CTRL_AUTO
430
431 Indicates if the automatic control of this feature is supported
432 by the camera. May only be queried.
433
434
435 DCAM1394_SUBPARAM_CAP_CTRL_MANUAL
436
437 Indicates if the manual control of this feature is supported by
438 the camera. May only be queried.
439
440
441 DCAM1394_SUBPARAM_CTRL_MODE
442
443 Indicates if the feature is in auto or manual mode.
444
445
446 DCAM1394_SUBPARAM_MIN_VAL
447
448 Minimum value of the feature. May only be queried.
449
450
451 DCAM1394_SUBPARAM_MAX_VAL
452
453 Maximum value of the feature. May only be queried.
454
455
456 DCAM1394_SUBPARAM_VALUE
457
458 Current value of the feature.
459
460
461 DCAM1394_SUBPARAM_CAP_READ
462
463 Indicates if the feature may be read. May only be
464 queried.
465
466
467
468 DCAM1394_PARAM_EXPOSURE
469
470 Query or control a camera feature. This feature queries or controls
471 the exposure of the camera. The subparams supported by this feature
472 are described under DCAM1394_PARAM_BRIGHTNESS.
473
474
475 DCAM1394_PARAM_SHARPNESS
476
477 Query or control a camera feature. This feature queries or controls
478 the sharpness of the camera. The subparams supported by this
479 feature are described under DCAM1394_PARAM_BRIGHTNESS.
480
481
482 DCAM1394_PARAM_WHITE_BALANCE
483
484 Query or control a camera feature. This feature queries or controls
485 the white balance of the camera. The subparams supported by this
486 feature are described under DCAM1394_PARAM_BRIGHTNESS, except for
487 DCAM1394_SUBPARAM_VALUE. DCAM1394_SUBPARAM_VALUE is replaced by
488 two distinct subparams.
489
490 DCAM1394_SUBPARAM_U_VALUE
491 U or B component of the white balance.
492
493
494 DCAM1394_SUBPARAM_V_VALUE
495 V or R component of the white balance.
496
497
498
499 DCAM1394_PARAM_HUE
500
501 Query or control a camera feature. This feature queries or controls
502 the hue of the camera. The subparams supported by this feature are
503 described under DCAM1394_PARAM_BRIGHTNESS.
504
505
506 DCAM1394_PARAM_SATURATION
507
508 Query or control a camera feature. This feature queries or controls
509 the saturation of the camera. The subparams supported by this
510 feature are described under DCAM1394_PARAM_BRIGHTNESS.
511
512
513 DCAM1394_PARAM_GAMMA
514
515 Query or control a camera feature. This feature queries or controls
516 the gamma of the camera. The subparams supported by this feature
517 are described under DCAM1394_PARAM_BRIGHTNESS.
518
519
520 DCAM1394_PARAM_SHUTTER
521
522 Query or control a camera feature. This feature queries or controls
523 the sharpness of the camera. The subparams supported by this
524 feature are described under DCAM1394_PARAM_BRIGHTNESS.
525
526
527 DCAM1394_PARAM_GAIN
528
529 Query or control a camera feature. This feature queries or controls
530 the gain of the camera. The subparams supported by this feature are
531 described under DCAM1394_PARAM_BRIGHTNESS.
532
533
534 DCAM1394_PARAM_IRIS
535
536 Query or control a camera feature. This feature queries or controls
537 the iris of the camera. The subparams supported by this feature are
538 described under DCAM1394_PARAM_BRIGHTNESS.
539
540
541 DCAM1394_PARAM_FOCUS
542
543 Query or control a camera feature. This feature queries or controls
544 the focus of the camera. The subparams supported by this feature
545 are described under DCAM1394_PARAM_BRIGHTNESS.
546
547
548 DCAM1394_PARAM_ZOOM
549
550 Query or control a camera feature. This feature queries or controls
551 the zoom of the camera. The subparams supported by this feature are
552 described under DCAM1394_PARAM_BRIGHTNESS.
553
554
555 DCAM1394_PARAM_PAN
556
557 Query or control a camera feature. This feature queries or controls
558 the pan of the camera. The subparams supported by this feature are
559 described under DCAM1394_PARAM_BRIGHTNESS.
560
561
562 DCAM1394_PARAM_TILT
563
564 Query or control a camera feature. This feature queries or controls
565 the tilt of the camera.The subparams supported by this feature are
566 described under DCAM1394_PARAM_BRIGHTNESS.
567
568
569 DEVICE SPECIAL FILES
570 /dev/dcamN
571 Device node for isochronous input from camera.
572
573
574 /dev/dcamctlN
575 Device node for camera control.
576
577
578 FILES
579 /kernel/drv/sparcv9/dcam1394
580
581 Device driver (SPARC)
582
583
584 /kernel/drv/amd64/dcam1394
585
586 Device driver (x86)
587
588
589 ATTRIBUTES
590 See attributes(5) for descriptions of the following attributes:
591
592
593
594
595 +--------------------+-----------------+
596 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
597 +--------------------+-----------------+
598 |Interface Stability | Evolving |
599 +--------------------+-----------------+
600
601 SEE ALSO
602 attributes(5), hci1394(7D)
603
604
605 1394 Trade Association Digital Camera Specification, Version 1.04 -
606 1996
607
608
609 IEEE Std 1394-2000 Standard for a High Performance Serial Bus - 2000
610
611
612
613 January 10, 2020 DCAM1394(7D)