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 53 struct 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 77 enum 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 131 enum 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 144 struct 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 */ 157 struct video_control_desc_group { 158 uint16_t group_id; 159 uint8_t length; 160 struct video_control_desc *desc; 161 }; 162 163 struct 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 */ 170 struct video_control_group { 171 uint16_t group_id; 172 uint8_t length; 173 struct video_control *control; 174 }; 175 176 struct video_control_iter { 177 struct video_control_desc *desc; 178 }; 179 180 /* format of video data in a video sample */ 181 enum 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 */ 203 enum 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) 241 enum 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) 249 enum 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) 259 enum 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) 266 enum 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 273 enum 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 283 enum 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 */ 296 enum 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. */ 307 struct 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 319 struct 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 327 struct 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 336 enum 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) 347 struct 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 */ 365 struct 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. */ 384 struct 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 */ 393 struct 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 */ 405 struct 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 */ 417 enum 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 */ 430 struct 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 */ 445 struct 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 452 struct 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 493 struct video_attach_args { 494 const struct video_hw_if *hw_if; 495 }; 496 497 device_t video_attach_mi(const struct video_hw_if *, device_t); 498 void video_submit_payload(device_t, const struct video_payload *); 499 500 #endif /* _SYS_DEV_VIDEO_IF_H_ */ 501