1 /* $NetBSD: video_if.h,v 1.5 2008/09/20 18:13:40 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 /* interlace_flags bits are allocated like this: 203 7 6 5 4 3 2 1 0 204 \_/ | | |interlaced or progressive 205 | | |packing style of fields (interlaced or planar) 206 | |fields per sample (1 or 2) 207 |pattern (F1 only, F2 only, F12, RND) 208 */ 209 210 /* two bits */ 211 #define VIDEO_INTERLACED(iflags) (iflags & 1) 212 enum video_interlace_presence { 213 VIDEO_INTERLACE_OFF = 0, /* progressive */ 214 VIDEO_INTERLACE_ON = 1, 215 VIDEO_INTERLACE_ANY = 2 /* in requests, accept any interlacing */ 216 }; 217 218 /* one bit, not in UVC */ 219 #define VIDEO_INTERLACE_PACKING(iflags) ((iflags >> 2) & 1) 220 enum video_interlace_packing { 221 VIDEO_INTERLACE_INTERLACED = 0, /* F1 and F2 are interlaced */ 222 VIDEO_INTERLACE_PLANAR = 1 /* entire F1 is followed by F2 */ 223 }; 224 225 /* one bit, not in V4L2; Is this not redundant with PATTERN below? 226 * For now, I'm assuming it describes where the "end-of-frame" markers 227 * appear in the stream data: after every field or after every two 228 * fields. */ 229 #define VIDEO_INTERLACE_FIELDS_PER_SAMPLE(iflags) ((iflags >> 3) & 1) 230 enum video_interlace_fields_per_sample { 231 VIDEO_INTERLACE_TWO_FIELDS_PER_SAMPLE = 0, 232 VIDEO_INTERLACE_ONE_FIELD_PER_SAMPLE = 1 233 }; 234 235 /* two bits */ 236 #define VIDEO_INTERLACE_PATTERN(iflags) ((iflags >> 4) & 3) 237 enum video_interlace_pattern { 238 VIDEO_INTERLACE_PATTERN_F1 = 0, 239 VIDEO_INTERLACE_PATTERN_F2 = 1, 240 VIDEO_INTERLACE_PATTERN_F12 = 2, 241 VIDEO_INTERLACE_PATTERN_RND = 3 242 }; 243 244 enum video_color_primaries { 245 VIDEO_COLOR_PRIMARIES_UNSPECIFIED, 246 VIDEO_COLOR_PRIMARIES_BT709, /* identical to sRGB */ 247 VIDEO_COLOR_PRIMARIES_BT470_2_M, 248 VIDEO_COLOR_PRIMARIES_BT470_2_BG, 249 VIDEO_COLOR_PRIMARIES_SMPTE_170M, 250 VIDEO_COLOR_PRIMARIES_SMPTE_240M, 251 VIDEO_COLOR_PRIMARIES_BT878 /* in V4L2 as broken BT878 chip */ 252 }; 253 254 enum video_gamma_function { 255 VIDEO_GAMMA_FUNCTION_UNSPECIFIED, 256 VIDEO_GAMMA_FUNCTION_BT709, 257 VIDEO_GAMMA_FUNCTION_BT470_2_M, 258 VIDEO_GAMMA_FUNCTION_BT470_2_BG, 259 VIDEO_GAMMA_FUNCTION_SMPTE_170M, 260 VIDEO_GAMMA_FUNCTION_SMPTE_240M, 261 VIDEO_GAMMA_FUNCTION_LINEAR, 262 VIDEO_GAMMA_FUNCTION_sRGB, /* similar but not identical to BT709 */ 263 VIDEO_GAMMA_FUNCTION_BT878 /* in V4L2 as broken BT878 chip */ 264 }; 265 266 /* Matrix coefficients for converting YUV to RGB */ 267 enum video_matrix_coeff { 268 VIDEO_MATRIX_COEFF_UNSPECIFIED, 269 VIDEO_MATRIX_COEFF_BT709, 270 VIDEO_MATRIX_COEFF_FCC, 271 VIDEO_MATRIX_COEFF_BT470_2_BG, 272 VIDEO_MATRIX_COEFF_SMPTE_170M, 273 VIDEO_MATRIX_COEFF_SMPTE_240M, 274 VIDEO_MATRIX_COEFF_BT878 /* in V4L2 as broken BT878 chip */ 275 }; 276 277 /* UVC spec separates these into three categories. V4L2 does not. */ 278 struct video_colorspace { 279 enum video_color_primaries primaries; 280 enum video_gamma_function gamma_function; 281 enum video_matrix_coeff matrix_coeff; 282 }; 283 284 #ifdef undef 285 /* Stucts for future split into format/frame/interval. All functions 286 * interacting with the hardware layer will deal with these structs. 287 * This video layer will handle translating them to V4L2 structs as 288 * necessary. */ 289 290 struct video_format { 291 enum video_pixel_format vfo_pixel_format; 292 uint8_t vfo_aspect_x; /* aspect ratio x and y */ 293 uint8_t vfo_aspect_y; 294 struct video_colorspace vfo_color; 295 uint8_t vfo_interlace_flags; 296 }; 297 298 struct video_frame { 299 uint32_t vfr_width; /* dimensions in pixels */ 300 uint32_t vfr_height; 301 uint32_t vfr_sample_size; /* max sample size */ 302 uint32_t vfr_stride; /* length of one row of pixels in 303 * bytes; uncompressed formats 304 * only */ 305 }; 306 307 enum video_frame_interval_type { 308 VIDEO_FRAME_INTERVAL_TYPE_CONTINUOUS, 309 VIDEO_FRAME_INTERVAL_TYPE_DISCRETE 310 }; 311 312 /* UVC spec frame interval units are 100s of nanoseconds. V4L2 spec 313 * uses a {32/32} bit struct fraction in seconds. We use 100ns units 314 * here. */ 315 #define VIDEO_FRAME_INTERVAL_UNITS_PER_US (10) 316 #define VIDEO_FRAME_INTERVAL_UNITS_PER_MS (10 * 1000) 317 #define VIDEO_FRAME_INTERVAL_UNITS_PER_S (10 * 1000 * 1000) 318 struct video_frame_interval { 319 enum video_frame_interval_type vfi_type; 320 union { 321 struct { 322 uint32_t min; 323 uint32_t max; 324 uint32_t step; 325 } vfi_continuous; 326 327 uint32_t vfi_discrete; 328 }; 329 }; 330 #endif /* undef */ 331 332 /* Describes a video format. For frame based formats, one sample is 333 * equivalent to one frame. For stream based formats such as MPEG, a 334 * sample is logical unit of that streaming format. 335 */ 336 struct video_format { 337 enum video_pixel_format pixel_format; 338 uint32_t width; /* dimensions in pixels */ 339 uint32_t height; 340 uint8_t aspect_x; /* aspect ratio x and y */ 341 uint8_t aspect_y; 342 uint32_t sample_size; /* max sample size */ 343 uint32_t stride; /* length of one row of pixels in 344 * bytes; uncompressed formats 345 * only */ 346 struct video_colorspace color; 347 uint8_t interlace_flags; 348 uint32_t priv; /* For private use by hardware driver. 349 * Must be set to zero if not used. */ 350 }; 351 352 /* A payload is the smallest unit transfered from the hardware driver 353 * to the video layer. Multiple video payloads make up one video 354 * sample. */ 355 struct video_payload { 356 const uint8_t *data; 357 size_t size; /* size in bytes of this payload */ 358 int frameno; /* toggles between 0 and 1 */ 359 bool end_of_frame; /* set if this is the last 360 * payload in the frame. */ 361 }; 362 363 struct video_hw_if { 364 int (*open)(void *, int); /* open hardware */ 365 void (*close)(void *); /* close hardware */ 366 367 const char * (*get_devname)(void *); 368 369 int (*enum_format)(void *, uint32_t, struct video_format *); 370 int (*get_format)(void *, struct video_format *); 371 int (*set_format)(void *, struct video_format *); 372 int (*try_format)(void *, struct video_format *); 373 374 int (*start_transfer)(void *); 375 int (*stop_transfer)(void *); 376 377 int (*control_iter_init)(void *, struct video_control_iter *); 378 int (*control_iter_next)(void *, struct video_control_iter *); 379 int (*get_control_desc_group)(void *, 380 struct video_control_desc_group *); 381 int (*get_control_group)(void *, struct video_control_group *); 382 int (*set_control_group)(void *, const struct video_control_group *); 383 }; 384 385 struct video_attach_args { 386 const struct video_hw_if *hw_if; 387 }; 388 389 device_t video_attach_mi(const struct video_hw_if *, device_t); 390 void video_submit_payload(device_t, const struct video_payload *); 391 392 #endif /* _SYS_DEV_VIDEO_IF_H_ */ 393