1/* $NetBSD: video_if.h,v 1.7 2010/12/24 20:54:28 jmcneill Exp $ */
2
3/*
4 * Copyright (c) 2008 Patrick Mahoney <pat@polycrystal.org>
5 * All rights reserved.
6 *
7 * This code was written by Patrick Mahoney (pat@polycrystal.org) as
8 * part of Google Summer of Code 2008.
9 *
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
12 * are met:
13 * 1. Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 * 2. Redistributions in binary form must reproduce the above copyright
16 * notice, this list of conditions and the following disclaimer in the
17 * documentation and/or other materials provided with the distribution.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
20 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
23 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 * POSSIBILITY OF SUCH DAMAGE.
30 */
31
32/*
33 * This ia a Video4Linux 2 compatible /dev/video driver for NetBSD
34 *
35 * See http://v4l2spec.bytesex.org/ for Video4Linux 2 specifications
36 */
37
38#ifndef _SYS_DEV_VIDEO_IF_H_
39#define _SYS_DEV_VIDEO_IF_H_
40
41#include <sys/types.h>
42#include <sys/videoio.h>
43
44#if defined(_KERNEL_OPT)
45#include "video.h"
46
47#if (NVIDEO == 0)
48#error "No 'video* at videobus?' configured"
49#endif
50
51#endif /* _KERNEL_OPT */
52
53struct video_softc;
54
55/* Controls provide a way to query and set controls in the camera
56 * hardware. The control structure is the primitive unit. Control
57 * groups are arrays of controls that must be set together (e.g. pan
58 * direction and pan speed). Control descriptors describe a control
59 * including minimum and maximum values, read-only state, etc. A
60 * control group descriptor is an array of control descriptors
61 * corresponding to a control group array of controls.
62 *
63 * A control_group is made up of multiple controls meant to be set
64 * together and is identified by a 16 bit group_id. Each control is
65 * identified by a group_id and a control_id. Controls that are the
66 * sole member of a control_group may ignore the control_id or
67 * redundantly have the control_id equal to the group_id.
68 *
69 * The hardware driver only handles control_group's, many of which
70 * will only have a single control.
71 *
72 * Some id's are defined here (closely following the USB Video Class
73 * controls) with room for unspecified extended controls. These id's
74 * may be used for group_id's or control_id's as appropriate.
75 */
76
77enum video_control_id {
78 VIDEO_CONTROL_UNDEFINED,
79 /* camera hardware */
80 VIDEO_CONTROL_SCANNING_MODE,
81 VIDEO_CONTROL_AE_MODE,
82 VIDEO_CONTROL_EXPOSURE_TIME_ABSOLUTE,
83 VIDEO_CONTROL_EXPOSURE_TIME_RELATIVE,
84 VIDEO_CONTROL_FOCUS_ABSOLUTE,
85 VIDEO_CONTROL_FOCUS_RELATIVE,
86 VIDEO_CONTROL_IRIS_ABSOLUTE,
87 VIDEO_CONTROL_IRIS_RELATIVE,
88 VIDEO_CONTROL_ZOOM_ABSOLUTE,
89 VIDEO_CONTROL_ZOOM_RELATIVE,
90 VIDEO_CONTROL_PANTILT_ABSOLUTE,
91 VIDEO_CONTROL_PANTILT_RELATIVE,
92 VIDEO_CONTROL_ROLL_ABSOLUTE,
93 VIDEO_CONTROL_ROLL_RELATIVE,
94 VIDEO_CONTROL_PRIVACY,
95 /* video processing */
96 VIDEO_CONTROL_BACKLIGHT_COMPENSATION,
97 VIDEO_CONTROL_BRIGHTNESS,
98 VIDEO_CONTROL_CONTRAST,
99 VIDEO_CONTROL_GAIN,
100 VIDEO_CONTROL_GAIN_AUTO, /* not in UVC */
101 VIDEO_CONTROL_POWER_LINE_FREQUENCY,
102 VIDEO_CONTROL_HUE,
103 VIDEO_CONTROL_SATURATION,
104 VIDEO_CONTROL_SHARPNESS,
105 VIDEO_CONTROL_GAMMA,
106 /* Generic WHITE_BALANCE controls applies to whichever type of
107 * white balance the hardware implements to either perform one
108 * white balance action or enable auto white balance. */
109 VIDEO_CONTROL_WHITE_BALANCE_ACTION,
110 VIDEO_CONTROL_WHITE_BALANCE_AUTO,
111 VIDEO_CONTROL_WHITE_BALANCE_TEMPERATURE,
112 VIDEO_CONTROL_WHITE_BALANCE_TEMPERATURE_AUTO,
113 VIDEO_CONTROL_WHITE_BALANCE_COMPONENT,
114 VIDEO_CONTROL_WHITE_BALANCE_COMPONENT_AUTO,
115 VIDEO_CONTROL_DIGITAL_MULTIPLIER,
116 VIDEO_CONTROL_DIGITAL_MULTIPLIER_LIMIT,
117 VIDEO_CONTROL_HUE_AUTO,
118 VIDEO_CONTROL_ANALOG_VIDEO_STANDARD,
119 VIDEO_CONTROL_ANALOG_LOCK_STATUS,
120 /* video stream */
121 VIDEO_CONTROL_GENERATE_KEY_FRAME,
122 VIDEO_CONTROL_UPDATE_FRAME_SEGMENT,
123 /* misc, not in UVC */
124 VIDEO_CONTROL_HFLIP,
125 VIDEO_CONTROL_VFLIP,
126 /* Custom controls start here; any controls beyond this are
127 * valid and condsidered "extended". */
128 VIDEO_CONTROL_EXTENDED
129};
130
131enum video_control_type {
132 VIDEO_CONTROL_TYPE_INT, /* signed 32 bit integer */
133 VIDEO_CONTROL_TYPE_BOOL,
134 VIDEO_CONTROL_TYPE_LIST, /* V4L2 MENU */
135 VIDEO_CONTROL_TYPE_ACTION /* V4L2 BUTTON */
136};
137
138#define VIDEO_CONTROL_FLAG_READ (1<<0)
139#define VIDEO_CONTROL_FLAG_WRITE (1<<1)
140#define VIDEO_CONTROL_FLAG_DISABLED (1<<2) /* V4L2 INACTIVE */
141#define VIDEO_CONTROL_FLAG_AUTOUPDATE (1<<3)
142#define VIDEO_CONTROL_FLAG_ASYNC (1<<4)
143
144struct video_control_desc {
145 uint16_t group_id;
146 uint16_t control_id;
147 uint8_t name[32];
148 uint32_t flags;
149 enum video_control_type type;
150 int32_t min;
151 int32_t max;
152 int32_t step;
153 int32_t def;
154};
155
156/* array of struct video_control_value_info belonging to the same control */
157struct video_control_desc_group {
158 uint16_t group_id;
159 uint8_t length;
160 struct video_control_desc *desc;
161};
162
163struct video_control {
164 uint16_t group_id;
165 uint16_t control_id;
166 int32_t value;
167};
168
169/* array of struct video_control_value belonging to the same control */
170struct video_control_group {
171 uint16_t group_id;
172 uint8_t length;
173 struct video_control *control;
174};
175
176struct video_control_iter {
177 struct video_control_desc *desc;
178};
179
180/* format of video data in a video sample */
181enum video_pixel_format {
182 VIDEO_FORMAT_UNDEFINED,
183
184 /* uncompressed frame-based formats */
185 VIDEO_FORMAT_YUY2, /* packed 4:2:2 */
186 VIDEO_FORMAT_NV12, /* planar 4:2:0 */
187 VIDEO_FORMAT_RGB24,
188 VIDEO_FORMAT_RGB555,
189 VIDEO_FORMAT_RGB565,
190 VIDEO_FORMAT_YUV420,
191 VIDEO_FORMAT_SBGGR8,
192 VIDEO_FORMAT_UYVY,
193
194 /* compressed frame-based formats */
195 VIDEO_FORMAT_MJPEG, /* frames of JPEG images */
196 VIDEO_FORMAT_DV,
197
198 /* stream-based formats */
199 VIDEO_FORMAT_MPEG
200};
201
202/* video standards */
203enum video_standard {
204 VIDEO_STANDARD_PAL_B = 0x00000001,
205 VIDEO_STANDARD_PAL_B1 = 0x00000002,
206 VIDEO_STANDARD_PAL_G = 0x00000004,
207 VIDEO_STANDARD_PAL_H = 0x00000008,
208 VIDEO_STANDARD_PAL_I = 0x00000010,
209 VIDEO_STANDARD_PAL_D = 0x00000020,
210 VIDEO_STANDARD_PAL_D1 = 0x00000040,
211 VIDEO_STANDARD_PAL_K = 0x00000080,
212 VIDEO_STANDARD_PAL_M = 0x00000100,
213 VIDEO_STANDARD_PAL_N = 0x00000200,
214 VIDEO_STANDARD_PAL_Nc = 0x00000400,
215 VIDEO_STANDARD_PAL_60 = 0x00000800,
216 VIDEO_STANDARD_NTSC_M = 0x00001000,
217 VIDEO_STANDARD_NTSC_M_JP = 0x00002000,
218 VIDEO_STANDARD_NTSC_443 = 0x00004000,
219 VIDEO_STANDARD_NTSC_M_KR = 0x00008000,
220 VIDEO_STANDARD_SECAM_B = 0x00010000,
221 VIDEO_STANDARD_SECAM_D = 0x00020000,
222 VIDEO_STANDARD_SECAM_G = 0x00040000,
223 VIDEO_STANDARD_SECAM_H = 0x00080000,
224 VIDEO_STANDARD_SECAM_K = 0x00100000,
225 VIDEO_STANDARD_SECAM_K1 = 0x00200000,
226 VIDEO_STANDARD_SECAM_L = 0x00400000,
227
228 VIDEO_STANDARD_UNKNOWN = 0x00000000
229};
230
231/* interlace_flags bits are allocated like this:
232 7 6 5 4 3 2 1 0
233 \_/ | | |interlaced or progressive
234 | | |packing style of fields (interlaced or planar)
235 | |fields per sample (1 or 2)
236 |pattern (F1 only, F2 only, F12, RND)
237*/
238
239/* two bits */
240#define VIDEO_INTERLACED(iflags) (iflags & 1)
241enum video_interlace_presence {
242 VIDEO_INTERLACE_OFF = 0, /* progressive */
243 VIDEO_INTERLACE_ON = 1,
244 VIDEO_INTERLACE_ANY = 2 /* in requests, accept any interlacing */
245};
246
247/* one bit, not in UVC */
248#define VIDEO_INTERLACE_PACKING(iflags) ((iflags >> 2) & 1)
249enum video_interlace_packing {
250 VIDEO_INTERLACE_INTERLACED = 0, /* F1 and F2 are interlaced */
251 VIDEO_INTERLACE_PLANAR = 1 /* entire F1 is followed by F2 */
252};
253
254/* one bit, not in V4L2; Is this not redundant with PATTERN below?
255 * For now, I'm assuming it describes where the "end-of-frame" markers
256 * appear in the stream data: after every field or after every two
257 * fields. */
258#define VIDEO_INTERLACE_FIELDS_PER_SAMPLE(iflags) ((iflags >> 3) & 1)
259enum video_interlace_fields_per_sample {
260 VIDEO_INTERLACE_TWO_FIELDS_PER_SAMPLE = 0,
261 VIDEO_INTERLACE_ONE_FIELD_PER_SAMPLE = 1
262};
263
264/* two bits */
265#define VIDEO_INTERLACE_PATTERN(iflags) ((iflags >> 4) & 3)
266enum video_interlace_pattern {
267 VIDEO_INTERLACE_PATTERN_F1 = 0,
268 VIDEO_INTERLACE_PATTERN_F2 = 1,
269 VIDEO_INTERLACE_PATTERN_F12 = 2,
270 VIDEO_INTERLACE_PATTERN_RND = 3
271};
272
273enum video_color_primaries {
274 VIDEO_COLOR_PRIMARIES_UNSPECIFIED,
275 VIDEO_COLOR_PRIMARIES_BT709, /* identical to sRGB */
276 VIDEO_COLOR_PRIMARIES_BT470_2_M,
277 VIDEO_COLOR_PRIMARIES_BT470_2_BG,
278 VIDEO_COLOR_PRIMARIES_SMPTE_170M,
279 VIDEO_COLOR_PRIMARIES_SMPTE_240M,
280 VIDEO_COLOR_PRIMARIES_BT878 /* in V4L2 as broken BT878 chip */
281};
282
283enum video_gamma_function {
284 VIDEO_GAMMA_FUNCTION_UNSPECIFIED,
285 VIDEO_GAMMA_FUNCTION_BT709,
286 VIDEO_GAMMA_FUNCTION_BT470_2_M,
287 VIDEO_GAMMA_FUNCTION_BT470_2_BG,
288 VIDEO_GAMMA_FUNCTION_SMPTE_170M,
289 VIDEO_GAMMA_FUNCTION_SMPTE_240M,
290 VIDEO_GAMMA_FUNCTION_LINEAR,
291 VIDEO_GAMMA_FUNCTION_sRGB, /* similar but not identical to BT709 */
292 VIDEO_GAMMA_FUNCTION_BT878 /* in V4L2 as broken BT878 chip */
293};
294
295/* Matrix coefficients for converting YUV to RGB */
296enum video_matrix_coeff {
297 VIDEO_MATRIX_COEFF_UNSPECIFIED,
298 VIDEO_MATRIX_COEFF_BT709,
299 VIDEO_MATRIX_COEFF_FCC,
300 VIDEO_MATRIX_COEFF_BT470_2_BG,
301 VIDEO_MATRIX_COEFF_SMPTE_170M,
302 VIDEO_MATRIX_COEFF_SMPTE_240M,
303 VIDEO_MATRIX_COEFF_BT878 /* in V4L2 as broken BT878 chip */
304};
305
306/* UVC spec separates these into three categories. V4L2 does not. */
307struct video_colorspace {
308 enum video_color_primaries primaries;
309 enum video_gamma_function gamma_function;
310 enum video_matrix_coeff matrix_coeff;
311};
312
313#ifdef undef
314/* Stucts for future split into format/frame/interval. All functions
315 * interacting with the hardware layer will deal with these structs.
316 * This video layer will handle translating them to V4L2 structs as
317 * necessary. */
318
319struct video_format {
320 enum video_pixel_format vfo_pixel_format;
321 uint8_t vfo_aspect_x; /* aspect ratio x and y */
322 uint8_t vfo_aspect_y;
323 struct video_colorspace vfo_color;
324 uint8_t vfo_interlace_flags;
325};
326
327struct video_frame {
328 uint32_t vfr_width; /* dimensions in pixels */
329 uint32_t vfr_height;
330 uint32_t vfr_sample_size; /* max sample size */
331 uint32_t vfr_stride; /* length of one row of pixels in
332 * bytes; uncompressed formats
333 * only */
334};
335
336enum video_frame_interval_type {
337 VIDEO_FRAME_INTERVAL_TYPE_CONTINUOUS,
338 VIDEO_FRAME_INTERVAL_TYPE_DISCRETE
339};
340
341/* UVC spec frame interval units are 100s of nanoseconds. V4L2 spec
342 * uses a {32/32} bit struct fraction in seconds. We use 100ns units
343 * here. */
344#define VIDEO_FRAME_INTERVAL_UNITS_PER_US (10)
345#define VIDEO_FRAME_INTERVAL_UNITS_PER_MS (10 * 1000)
346#define VIDEO_FRAME_INTERVAL_UNITS_PER_S (10 * 1000 * 1000)
347struct video_frame_interval {
348 enum video_frame_interval_type vfi_type;
349 union {
350 struct {
351 uint32_t min;
352 uint32_t max;
353 uint32_t step;
354 } vfi_continuous;
355
356 uint32_t vfi_discrete;
357 };
358};
359#endif /* undef */
360
361/* Describes a video format. For frame based formats, one sample is
362 * equivalent to one frame. For stream based formats such as MPEG, a
363 * sample is logical unit of that streaming format.
364 */
365struct video_format {
366 enum video_pixel_format pixel_format;
367 uint32_t width; /* dimensions in pixels */
368 uint32_t height;
369 uint8_t aspect_x; /* aspect ratio x and y */
370 uint8_t aspect_y;
371 uint32_t sample_size; /* max sample size */
372 uint32_t stride; /* length of one row of pixels in
373 * bytes; uncompressed formats
374 * only */
375 struct video_colorspace color;
376 uint8_t interlace_flags;
377 uint32_t priv; /* For private use by hardware driver.
378 * Must be set to zero if not used. */
379};
380
381/* A payload is the smallest unit transfered from the hardware driver
382 * to the video layer. Multiple video payloads make up one video
383 * sample. */
384struct video_payload {
385 const uint8_t *data;
386 size_t size; /* size in bytes of this payload */
387 int frameno; /* toggles between 0 and 1 */
388 bool end_of_frame; /* set if this is the last
389 * payload in the frame. */
390};
391
392/* tuner frequency, frequencies are in units of 62.5 kHz */
393struct video_frequency {
394 uint32_t tuner_index;
395 uint32_t frequency;
396};
397
398/* video tuner capability flags */
399#define VIDEO_TUNER_F_MONO (1 << 0)
400#define VIDEO_TUNER_F_STEREO (1 << 1)
401#define VIDEO_TUNER_F_LANG1 (1 << 2)
402#define VIDEO_TUNER_F_LANG2 (1 << 3)
403
404/* Video tuner definition */
405struct video_tuner {
406 uint32_t index;
407 char name[32]; /* tuner name */
408 uint32_t freq_lo; /* lowest tunable frequency */
409 uint32_t freq_hi; /* highest tunable frequency */
410 uint32_t caps; /* capability flags */
411 uint32_t mode; /* audio mode flags */
412 uint32_t signal; /* signal strength */
413 int32_t afc; /* automatic frequency control */
414};
415
416/* Video input capability flags */
417enum video_input_type {
418 VIDEO_INPUT_TYPE_TUNER, /* RF demodulator */
419 VIDEO_INPUT_TYPE_BASEBAND, /* analog baseband */
420 VIDEO_INPUT_TYPE_CAMERA = VIDEO_INPUT_TYPE_BASEBAND,
421};
422
423#define VIDEO_STATUS_NO_POWER (1 << 0)
424#define VIDEO_STATUS_NO_SIGNAL (1 << 1)
425#define VIDEO_STATUS_NO_COLOR (1 << 2)
426#define VIDEO_STATUS_NO_HLOCK (1 << 3)
427#define VIDEO_STATUS_MACROVISION (1 << 4)
428
429/* Video input definition */
430struct video_input {
431 uint32_t index;
432 char name[32]; /* video input name */
433 enum video_input_type type; /* input type */
434 uint32_t audiomask; /* bitmask of assoc. audio inputs */
435 uint32_t tuner_index; /* tuner index if applicable */
436 uint64_t standards; /* all supported standards */
437 uint32_t status; /* input status */
438};
439
440/* Audio input capability flags */
441#define VIDEO_AUDIO_F_STEREO (1 << 0)
442#define VIDEO_AUDIO_F_AVL (1 << 1)
443
444/* Audio input definition */
445struct video_audio {
446 uint32_t index;
447 char name[32]; /* audio input name */
448 uint32_t caps; /* capabilities flags */
449 uint32_t mode; /* audio mode flags */
450};
451
452struct video_hw_if {
453 int (*open)(void *, int); /* open hardware */
454 void (*close)(void *); /* close hardware */
455
456 const char * (*get_devname)(void *);
457 const char * (*get_businfo)(void *);
458
459 int (*enum_format)(void *, uint32_t, struct video_format *);
460 int (*get_format)(void *, struct video_format *);
461 int (*set_format)(void *, struct video_format *);
462 int (*try_format)(void *, struct video_format *);
463
464 int (*enum_standard)(void *, uint32_t, enum video_standard *);
465 int (*get_standard)(void *, enum video_standard *);
466 int (*set_standard)(void *, enum video_standard);
467
468 int (*start_transfer)(void *);
469 int (*stop_transfer)(void *);
470
471 int (*control_iter_init)(void *, struct video_control_iter *);
472 int (*control_iter_next)(void *, struct video_control_iter *);
473 int (*get_control_desc_group)(void *,
474 struct video_control_desc_group *);
475 int (*get_control_group)(void *, struct video_control_group *);
476 int (*set_control_group)(void *, const struct video_control_group *);
477
478 int (*enum_input)(void *, uint32_t, struct video_input *);
479 int (*get_input)(void *, struct video_input *);
480 int (*set_input)(void *, struct video_input *);
481
482 int (*enum_audio)(void *, uint32_t, struct video_audio *);
483 int (*get_audio)(void *, struct video_audio *);
484 int (*set_audio)(void *, struct video_audio *);
485
486 int (*get_tuner)(void *, struct video_tuner *);
487 int (*set_tuner)(void *, struct video_tuner *);
488
489 int (*get_frequency)(void *, struct video_frequency *);
490 int (*set_frequency)(void *, struct video_frequency *);
491};
492
493struct video_attach_args {
494 const struct video_hw_if *hw_if;
495};
496
497device_t video_attach_mi(const struct video_hw_if *, device_t);
498void video_submit_payload(device_t, const struct video_payload *);
499
500#endif /* _SYS_DEV_VIDEO_IF_H_ */
501