sys/dev/video_if.h

   1 /* $NetBSD: video_if.h,v 1.4 2008/09/18 05:35:05 dogcow 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_ */