FreeBSD/Linux Kernel Cross Reference
sys/dev/video_if.h

     /* $NetBSD: video_if.h,v 1.12 2022/07/05 20:15:40 andvar Exp $ */
     
     /*
      * Copyright (c) 2008 Patrick Mahoney <pat@polycrystal.org>
      * All rights reserved.
      *
      * This code was written by Patrick Mahoney (pat@polycrystal.org) as
      * part of Google Summer of Code 2008.
      *
     * Redistribution and use in source and binary forms, with or without
     * modification, are permitted provided that the following conditions
     * are met:
     * 1. Redistributions of source code must retain the above copyright
     *    notice, this list of conditions and the following disclaimer.
     * 2. Redistributions in binary form must reproduce the above copyright
     *    notice, this list of conditions and the following disclaimer in the
     *    documentation and/or other materials provided with the distribution.
     *
     * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
     * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
     * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
     * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
     * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
     * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
     * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
     * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
     * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
     * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
     * POSSIBILITY OF SUCH DAMAGE.
     */
    
    /*
     * This ia a Video4Linux 2 compatible /dev/video driver for NetBSD
     *
     * See http://v4l2spec.bytesex.org/ for Video4Linux 2 specifications
     */
    
    #ifndef _SYS_DEV_VIDEO_IF_H_
    #define _SYS_DEV_VIDEO_IF_H_
    
    #include <sys/types.h>
    #include <sys/videoio.h>
    
    #if defined(_KERNEL_OPT)
    #include "video.h"
    
    #if (NVIDEO == 0)
    #error "No 'video* at videobus?' configured"
    #endif
    
    #endif  /* _KERNEL_OPT */
    
    struct video_softc;
    
    /* Controls provide a way to query and set controls in the camera
     * hardware.  The control structure is the primitive unit.  Control
     * groups are arrays of controls that must be set together (e.g. pan
     * direction and pan speed).  Control descriptors describe a control
     * including minimum and maximum values, read-only state, etc.  A
     * control group descriptor is an array of control descriptors
     * corresponding to a control group array of controls.
     *
     * A control_group is made up of multiple controls meant to be set
     * together and is identified by a 16 bit group_id.  Each control is
     * identified by a group_id and a control_id.  Controls that are the
     * sole member of a control_group may ignore the control_id or
     * redundantly have the control_id equal to the group_id.
     *
     * The hardware driver only handles control_group's, many of which
     * will only have a single control.
     *
     * Some id's are defined here (closely following the USB Video Class
     * controls) with room for unspecified extended controls.  These id's
     * may be used for group_id's or control_id's as appropriate.
     */
    
    enum video_control_id {
            VIDEO_CONTROL_UNDEFINED,
            /* camera hardware */
            VIDEO_CONTROL_SCANNING_MODE,
            VIDEO_CONTROL_AE_MODE,
            VIDEO_CONTROL_EXPOSURE_TIME_ABSOLUTE,
            VIDEO_CONTROL_EXPOSURE_TIME_RELATIVE,
            VIDEO_CONTROL_FOCUS_ABSOLUTE,
            VIDEO_CONTROL_FOCUS_RELATIVE,
            VIDEO_CONTROL_IRIS_ABSOLUTE,
            VIDEO_CONTROL_IRIS_RELATIVE,
            VIDEO_CONTROL_ZOOM_ABSOLUTE,
            VIDEO_CONTROL_ZOOM_RELATIVE,
            VIDEO_CONTROL_PANTILT_ABSOLUTE,
            VIDEO_CONTROL_PANTILT_RELATIVE,
            VIDEO_CONTROL_ROLL_ABSOLUTE,
            VIDEO_CONTROL_ROLL_RELATIVE,
            VIDEO_CONTROL_PRIVACY,
            /* video processing */
            VIDEO_CONTROL_BACKLIGHT_COMPENSATION,
            VIDEO_CONTROL_BRIGHTNESS,
            VIDEO_CONTROL_CONTRAST,
            VIDEO_CONTROL_GAIN,
           VIDEO_CONTROL_GAIN_AUTO, /* not in UVC */
           VIDEO_CONTROL_POWER_LINE_FREQUENCY,
           VIDEO_CONTROL_HUE,
           VIDEO_CONTROL_SATURATION,
           VIDEO_CONTROL_SHARPNESS,
           VIDEO_CONTROL_GAMMA,
           /* Generic WHITE_BALANCE controls applies to whichever type of
            * white balance the hardware implements to either perform one
            * white balance action or enable auto white balance. */
           VIDEO_CONTROL_WHITE_BALANCE_ACTION,
           VIDEO_CONTROL_WHITE_BALANCE_AUTO,
           VIDEO_CONTROL_WHITE_BALANCE_TEMPERATURE,
           VIDEO_CONTROL_WHITE_BALANCE_TEMPERATURE_AUTO,
           VIDEO_CONTROL_WHITE_BALANCE_COMPONENT,
           VIDEO_CONTROL_WHITE_BALANCE_COMPONENT_AUTO,
           VIDEO_CONTROL_DIGITAL_MULTIPLIER,
           VIDEO_CONTROL_DIGITAL_MULTIPLIER_LIMIT,
           VIDEO_CONTROL_HUE_AUTO,
           VIDEO_CONTROL_ANALOG_VIDEO_STANDARD,
           VIDEO_CONTROL_ANALOG_LOCK_STATUS,
           /* video stream */
           VIDEO_CONTROL_GENERATE_KEY_FRAME,
           VIDEO_CONTROL_UPDATE_FRAME_SEGMENT,
           /* misc, not in UVC */
           VIDEO_CONTROL_HFLIP,
           VIDEO_CONTROL_VFLIP,
           /* Custom controls start here; any controls beyond this are
            * valid and considered "extended". */
           VIDEO_CONTROL_EXTENDED
   };
   
   enum video_control_type {
           VIDEO_CONTROL_TYPE_INT, /* signed 32 bit integer */
           VIDEO_CONTROL_TYPE_BOOL,
           VIDEO_CONTROL_TYPE_LIST,  /* V4L2 MENU */
           VIDEO_CONTROL_TYPE_ACTION /* V4L2 BUTTON */
   };
   
   #define VIDEO_CONTROL_FLAG_READ         (1<<0)
   #define VIDEO_CONTROL_FLAG_WRITE        (1<<1)
   #define VIDEO_CONTROL_FLAG_DISABLED     (1<<2) /* V4L2 INACTIVE */
   #define VIDEO_CONTROL_FLAG_AUTOUPDATE   (1<<3)
   #define VIDEO_CONTROL_FLAG_ASYNC        (1<<4)
   
   struct video_control_desc {
           uint16_t        group_id;
           uint16_t        control_id;
           uint8_t         name[32];
           uint32_t        flags;
           enum video_control_type type;
           int32_t         min;
           int32_t         max;
           int32_t         step;
           int32_t         def;
   };
   
   /* array of struct video_control_value_info belonging to the same control */
   struct video_control_desc_group {
           uint16_t        group_id;
           uint8_t         length;
           struct video_control_desc *desc;
   };
   
   struct video_control {
           uint16_t        group_id;
           uint16_t        control_id;
           int32_t         value;
   };
   
   /* array of struct video_control_value belonging to the same control */
   struct video_control_group {
           uint16_t        group_id;
           uint8_t         length;
           struct video_control *control;
   };
   
   struct video_control_iter {
           struct video_control_desc *desc;
   };
   
   /* format of video data in a video sample */
   enum video_pixel_format {
           VIDEO_FORMAT_UNDEFINED,
           
           /* uncompressed frame-based formats */
           VIDEO_FORMAT_YUY2,      /* packed 4:2:2 */
           VIDEO_FORMAT_NV12,      /* planar 4:2:0 */
           VIDEO_FORMAT_RGB24,
           VIDEO_FORMAT_RGB555,
           VIDEO_FORMAT_RGB565,
           VIDEO_FORMAT_YUV420,
           VIDEO_FORMAT_SBGGR8,
           VIDEO_FORMAT_UYVY,
   
           /* compressed frame-based formats */
           VIDEO_FORMAT_MJPEG,     /* frames of JPEG images */
           VIDEO_FORMAT_DV,
   
           /* stream-based formats */
           VIDEO_FORMAT_MPEG
   };
   
   /* video standards */
   enum video_standard {
           VIDEO_STANDARD_PAL_B            = 0x00000001,
           VIDEO_STANDARD_PAL_B1           = 0x00000002,
           VIDEO_STANDARD_PAL_G            = 0x00000004,
           VIDEO_STANDARD_PAL_H            = 0x00000008,
           VIDEO_STANDARD_PAL_I            = 0x00000010,
           VIDEO_STANDARD_PAL_D            = 0x00000020,
           VIDEO_STANDARD_PAL_D1           = 0x00000040,
           VIDEO_STANDARD_PAL_K            = 0x00000080,
           VIDEO_STANDARD_PAL_M            = 0x00000100,
           VIDEO_STANDARD_PAL_N            = 0x00000200,
           VIDEO_STANDARD_PAL_Nc           = 0x00000400,
           VIDEO_STANDARD_PAL_60           = 0x00000800,
           VIDEO_STANDARD_NTSC_M           = 0x00001000,
           VIDEO_STANDARD_NTSC_M_JP        = 0x00002000,
           VIDEO_STANDARD_NTSC_443         = 0x00004000,
           VIDEO_STANDARD_NTSC_M_KR        = 0x00008000,
           VIDEO_STANDARD_SECAM_B          = 0x00010000,
           VIDEO_STANDARD_SECAM_D          = 0x00020000,
           VIDEO_STANDARD_SECAM_G          = 0x00040000,
           VIDEO_STANDARD_SECAM_H          = 0x00080000,
           VIDEO_STANDARD_SECAM_K          = 0x00100000,
           VIDEO_STANDARD_SECAM_K1         = 0x00200000,
           VIDEO_STANDARD_SECAM_L          = 0x00400000,
   
           VIDEO_STANDARD_UNKNOWN          = 0x00000000
   };
   
   /* interlace_flags bits are allocated like this:
         7 6 5 4 3 2 1 0
               \_/ | | |interlaced or progressive
                |  | |packing style of fields (interlaced or planar)
                |  |fields per sample (1 or 2)
                |pattern (F1 only, F2 only, F12, RND)
   */
   
   /* two bits */
   #define VIDEO_INTERLACED(iflags) (iflags & 1)
   enum video_interlace_presence {
           VIDEO_INTERLACE_OFF = 0, /* progressive */
           VIDEO_INTERLACE_ON = 1,
           VIDEO_INTERLACE_ANY = 2 /* in requests, accept any interlacing */
   };
   
   /* one bit, not in UVC */
   #define VIDEO_INTERLACE_PACKING(iflags) ((iflags >> 2) & 1)
   enum video_interlace_packing {
           VIDEO_INTERLACE_INTERLACED = 0, /* F1 and F2 are interlaced */
           VIDEO_INTERLACE_PLANAR = 1 /* entire F1 is followed by F2 */
   };
   
   /* one bit, not in V4L2; Is this not redundant with PATTERN below?
    * For now, I'm assuming it describes where the "end-of-frame" markers
    * appear in the stream data: after every field or after every two
    * fields. */
   #define VIDEO_INTERLACE_FIELDS_PER_SAMPLE(iflags) ((iflags >> 3) & 1)
   enum video_interlace_fields_per_sample {
           VIDEO_INTERLACE_TWO_FIELDS_PER_SAMPLE = 0,
           VIDEO_INTERLACE_ONE_FIELD_PER_SAMPLE = 1
   };
   
   /* two bits */
   #define VIDEO_INTERLACE_PATTERN(iflags) ((iflags >> 4) & 3)
   enum video_interlace_pattern {
           VIDEO_INTERLACE_PATTERN_F1 = 0,
           VIDEO_INTERLACE_PATTERN_F2 = 1,
           VIDEO_INTERLACE_PATTERN_F12 = 2,
           VIDEO_INTERLACE_PATTERN_RND = 3
   };
   
   enum video_color_primaries {
           VIDEO_COLOR_PRIMARIES_UNSPECIFIED,
           VIDEO_COLOR_PRIMARIES_BT709, /* identical to sRGB */
           VIDEO_COLOR_PRIMARIES_BT470_2_M,
           VIDEO_COLOR_PRIMARIES_BT470_2_BG,
           VIDEO_COLOR_PRIMARIES_SMPTE_170M,
           VIDEO_COLOR_PRIMARIES_SMPTE_240M,
           VIDEO_COLOR_PRIMARIES_BT878 /* in V4L2 as broken BT878 chip */
   };
   
   enum video_gamma_function {
           VIDEO_GAMMA_FUNCTION_UNSPECIFIED,
           VIDEO_GAMMA_FUNCTION_BT709,
           VIDEO_GAMMA_FUNCTION_BT470_2_M,
           VIDEO_GAMMA_FUNCTION_BT470_2_BG,
           VIDEO_GAMMA_FUNCTION_SMPTE_170M,
           VIDEO_GAMMA_FUNCTION_SMPTE_240M,
           VIDEO_GAMMA_FUNCTION_LINEAR,
           VIDEO_GAMMA_FUNCTION_sRGB, /* similar but not identical to BT709 */
           VIDEO_GAMMA_FUNCTION_BT878 /* in V4L2 as broken BT878 chip */
   };
   
   /* Matrix coefficients for converting YUV to RGB */
   enum video_matrix_coeff {
           VIDEO_MATRIX_COEFF_UNSPECIFIED,
           VIDEO_MATRIX_COEFF_BT709,
           VIDEO_MATRIX_COEFF_FCC,
           VIDEO_MATRIX_COEFF_BT470_2_BG,
           VIDEO_MATRIX_COEFF_SMPTE_170M,
           VIDEO_MATRIX_COEFF_SMPTE_240M,
           VIDEO_MATRIX_COEFF_BT878 /* in V4L2 as broken BT878 chip */
   };
   
   /* UVC spec separates these into three categories.  V4L2 does not. */
   struct video_colorspace {
           enum video_color_primaries primaries;
           enum video_gamma_function gamma_function;
           enum video_matrix_coeff matrix_coeff;
   };
   
   #ifdef undef
   /* Structs for future split into format/frame/interval.  All functions
    * interacting with the hardware layer will deal with these structs.
    * This video layer will handle translating them to V4L2 structs as
    * necessary. */
   
   struct video_format {
           enum video_pixel_format vfo_pixel_format;
           uint8_t                 vfo_aspect_x; /* aspect ratio x and y */
           uint8_t                 vfo_aspect_y;
           struct video_colorspace vfo_color;
           uint8_t                 vfo_interlace_flags;
   };
   
   struct video_frame {
           uint32_t        vfr_width; /* dimensions in pixels */
           uint32_t        vfr_height;
           uint32_t        vfr_sample_size; /* max sample size */
           uint32_t        vfr_stride; /* length of one row of pixels in
                                        * bytes; uncompressed formats
                                        * only */
   };
   
   enum video_frame_interval_type {
           VIDEO_FRAME_INTERVAL_TYPE_CONTINUOUS,
           VIDEO_FRAME_INTERVAL_TYPE_DISCRETE
   };
   
   /* UVC spec frame interval units are 100s of nanoseconds.  V4L2 spec
    * uses a {32/32} bit struct fraction in seconds. We use 100ns units
    * here. */
   #define VIDEO_FRAME_INTERVAL_UNITS_PER_US (10)
   #define VIDEO_FRAME_INTERVAL_UNITS_PER_MS (10 * 1000)
   #define VIDEO_FRAME_INTERVAL_UNITS_PER_S  (10 * 1000 * 1000)
   struct video_frame_interval {
           enum video_frame_interval_type  vfi_type;
           union {
                   struct {
                           uint32_t min;
                           uint32_t max;
                           uint32_t step;
                   } vfi_continuous;
   
                   uint32_t        vfi_discrete;
           };
   };
   #endif /* undef */
   
   /* Describes a video format.  For frame based formats, one sample is
    * equivalent to one frame.  For stream based formats such as MPEG, a
    * sample is logical unit of that streaming format.
    */
   struct video_format {
           enum video_pixel_format pixel_format;
           uint32_t        width;  /* dimensions in pixels */
           uint32_t        height;
           uint8_t         aspect_x; /* aspect ratio x and y */
           uint8_t         aspect_y;
           uint32_t        sample_size; /* max sample size */
           uint32_t        stride;      /* length of one row of pixels in
                                         * bytes; uncompressed formats
                                         * only */
           struct video_colorspace color;
           uint8_t         interlace_flags;
           uint32_t        priv;   /* For private use by hardware driver.
                                    * Must be set to zero if not used. */
   };
   
   /* Represents the amount of time a single frame is displayed. */
   struct video_fract {
           uint32_t        numerator;
           uint32_t        denominator;
   };
   
   /* A payload is the smallest unit transferred from the hardware driver
    * to the video layer. Multiple video payloads make up one video
    * sample. */
   struct video_payload {
           const uint8_t   *data;
           size_t          size;           /* size in bytes of this payload */
           int             frameno;        /* toggles between 0 and 1 */
           bool            end_of_frame;   /* set if this is the last
                                            * payload in the frame. */
   };
   
   /* tuner frequency, frequencies are in units of 62.5 kHz */
   struct video_frequency {
           uint32_t        tuner_index;
           uint32_t        frequency;
   };
   
   /* video tuner capability flags */
   #define VIDEO_TUNER_F_MONO      (1 << 0)
   #define VIDEO_TUNER_F_STEREO    (1 << 1)
   #define VIDEO_TUNER_F_LANG1     (1 << 2)
   #define VIDEO_TUNER_F_LANG2     (1 << 3)
   
   /* Video tuner definition */
   struct video_tuner {
           uint32_t        index;
           char            name[32];       /* tuner name */
           uint32_t        freq_lo;        /* lowest tunable frequency */
           uint32_t        freq_hi;        /* highest tunable frequency */
           uint32_t        caps;           /* capability flags */
           uint32_t        mode;           /* audio mode flags */
           uint32_t        signal;         /* signal strength */
           int32_t         afc;            /* automatic frequency control */
   };
   
   /* Video input capability flags */
   enum video_input_type {
           VIDEO_INPUT_TYPE_TUNER,         /* RF demodulator */
           VIDEO_INPUT_TYPE_BASEBAND,      /* analog baseband */
           VIDEO_INPUT_TYPE_CAMERA = VIDEO_INPUT_TYPE_BASEBAND,
   };
   
   #define VIDEO_STATUS_NO_POWER           (1 << 0)
   #define VIDEO_STATUS_NO_SIGNAL          (1 << 1)
   #define VIDEO_STATUS_NO_COLOR           (1 << 2)
   #define VIDEO_STATUS_NO_HLOCK           (1 << 3)
   #define VIDEO_STATUS_MACROVISION        (1 << 4)
   
   /* Video input definition */
   struct video_input {
           uint32_t        index;
           char            name[32];       /* video input name */
           enum video_input_type type;     /* input type */
           uint32_t        audiomask;      /* bitmask of assoc. audio inputs */
           uint32_t        tuner_index;    /* tuner index if applicable */
           uint64_t        standards;      /* all supported standards */
           uint32_t        status;         /* input status */
   };
   
   /* Audio input capability flags */
   #define VIDEO_AUDIO_F_STEREO    (1 << 0)
   #define VIDEO_AUDIO_F_AVL       (1 << 1)
   
   /* Audio input definition */
   struct video_audio {
           uint32_t        index;
           char            name[32];       /* audio input name */
           uint32_t        caps;           /* capabilities flags */
           uint32_t        mode;           /* audio mode flags */
   };
   
   struct video_hw_if {
           int     (*open)(void *, int); /* open hardware */
           void    (*close)(void *);     /* close hardware */
   
           const char *    (*get_devname)(void *);
           const char *    (*get_businfo)(void *);
   
           int     (*enum_format)(void *, uint32_t, struct video_format *);
           int     (*get_format)(void *, struct video_format *);
           int     (*set_format)(void *, struct video_format *);
           int     (*try_format)(void *, struct video_format *);
   
           int     (*enum_standard)(void *, uint32_t, enum video_standard *);
           int     (*get_standard)(void *, enum video_standard *);
           int     (*set_standard)(void *, enum video_standard);
   
           int     (*start_transfer)(void *);
           int     (*stop_transfer)(void *);
   
           int     (*control_iter_init)(void *, struct video_control_iter *);
           int     (*control_iter_next)(void *, struct video_control_iter *);
           int     (*get_control_desc_group)(void *,
                                             struct video_control_desc_group *);
           int     (*get_control_group)(void *, struct video_control_group *);
           int     (*set_control_group)(void *, const struct video_control_group *);
   
           int     (*enum_input)(void *, uint32_t, struct video_input *);
           int     (*get_input)(void *, struct video_input *);
           int     (*set_input)(void *, struct video_input *);
   
           int     (*enum_audio)(void *, uint32_t, struct video_audio *);
           int     (*get_audio)(void *, struct video_audio *);
           int     (*set_audio)(void *, struct video_audio *);
   
           int     (*get_tuner)(void *, struct video_tuner *);
           int     (*set_tuner)(void *, struct video_tuner *);
   
           int     (*get_frequency)(void *, struct video_frequency *);
           int     (*set_frequency)(void *, struct video_frequency *);
   
           int     (*get_framerate)(void *, struct video_fract *);
           int     (*set_framerate)(void *, struct video_fract *);
   };
   
   struct video_attach_args {
           const struct video_hw_if *hw_if;
           void    *hw_softc;
   };
   
   device_t video_attach_mi(const struct video_hw_if *, device_t, void *);
   void video_submit_payload(device_t, const struct video_payload *);
   
   #endif  /* _SYS_DEV_VIDEO_IF_H_ */

Cache object: b76a6478ce232b215a690766b53676c8