share/man/man9/video.9

   1 .\"     $NetBSD: video.9,v 1.4 2008/09/08 22:21:47 ahoka Exp $
   2 .\"
   3 .\" Copyright (c) 2008 Patrick Mahoney
   4 .\" All rights reserved.
   5 .\"
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  17 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  18 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26 .\" POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .Dd July 24, 2008
  29 .Dt VIDEO 9
  30 .Os
  31 .Sh NAME
  32 .Nm video
  33 .Nd interface between low and high level video drivers
  34 .Sh SYNOPSIS
  35 .In dev/video_if.h
  36 .Ft device_t
  37 .Fn video_attach_mi "const struct video_hw_if *hw_if" "device_t hw_dev"
  38 .Ft void
  39 .Fn video_submit_payload "device_t vl_dev" "const struct video_payload *payload"
  40 .Sh DESCRIPTION
  41 The video device driver is divided into a high level, machine
  42 independent layer, and a low level hardware dependent layer.
  43 The interface between these is the
  44 .Fa video_hw_if
  45 structure function pointers called by the video layer, and video layer
  46 functions called by the hardware driver.
  47 .Pp
  48 The high level video driver attaches to the low level driver
  49 when the latter calls
  50 .Fa video_attach_mi .
  51 The
  52 .Fa video_hw_if
  53 struct is as shown below.
  54 .Fa dev
  55 is the device struct for the hardware device.
  56 Return value is the video layer device.
  57 .Bd -literal
  58 struct video_hw_if {
  59         int     (*open)(void *, int); /* open hardware */
  60         void    (*close)(void *);     /* close hardware */
  61
  62         const char *    (*get_devname)(void *);
  63
  64         int     (*enum_format)(void *, uint32_t, struct video_format *);
  65         int     (*get_format)(void *, struct video_format *);
  66         int     (*set_format)(void *, struct video_format *);
  67         int     (*try_format)(void *, struct video_format *);
  68
  69         int     (*start_transfer)(void *);
  70         int     (*stop_transfer)(void *);
  71
  72         int     (*control_iter_init)(void *, struct video_control_iter *);
  73         int     (*control_iter_next)(void *, struct video_control_iter *);
  74         int     (*get_control_desc_group)(void *,
  75                                           struct video_control_desc_group *);
  76         int     (*get_control_group)(void *, struct video_control_group *);
  77         int     (*set_control_group)(void *, const struct video_control_group *);
  78 };
  79 .Ed
  80 .Pp
  81 The upper layer of the video driver allocates buffers for video
  82 samples.
  83 The hardware driver submits data to the video layer with
  84 .Fa video_submit_payload .
  85 .Fa vl_dev
  86 is the video layer device returned by
  87 .Fa video_attach_mi .
  88 .Bd -literal
  89 struct video_payload {
  90         const uint8_t   *data;
  91         size_t          size;
  92         int             frameno;
  93         bool            end_of_frame;
  94 };
  95 .Ed
  96 .Bl -tag -width indent
  97 .It Fa data
  98 Pointer to the video data for this payload.
  99 This may only be a
 100 portion of the data in one video sample or frame.
 101 .It Fa size
 102 Size in bytes of the video data in this payload
 103 .It Fa frameno
 104 Frame number to which this payload belongs.
 105 The hardware driver must toggle the frame number between 0 and 1
 106 so the video layer can detect sample or frame boundaries.
 107 .It Fa end_of_frame
 108 Optional end of frame marker.
 109 If the hardware layer sets this, the
 110 video layer can immediately pass the completed sample or frame to
 111 userspace rather than waiting for the next payload to toggle
 112 .Fa frameno .
 113 .El
 114 .Sh HARDWARE-LAYER FUNCTIONS
 115 The fields of
 116 .Va video_hw_if
 117 are described in some more detail below.
 118 Some fields are optional and can be set to
 119 .Dv NULL
 120 if not needed.
 121 .Bl -tag -width indent
 122 .It Dv int open(void *hdl, int flags)
 123 optional, is called when the video device is opened.
 124 It should initialize the hardware for I/O.
 125 Every successful call to
 126 .Va open
 127 is matched by a call to
 128 .Va close .
 129 Return 0 on success, otherwise an error code.
 130 .It Dv void close(void *hdl)
 131 optional, is called when the audio device is closed.
 132 .It Dv const char * get_devname(void *hdl)
 133 mandatory, returns a NUL-terminated string naming the device, e.g. a
 134 vendor and product model name.
 135 .It Dv int enum_format(void *hdl, uint32_t index, struct video_format *format);
 136 mandatory, called with an
 137 .Va index
 138 from 0 to
 139 .Va max_index \- 1 .
 140 Fills
 141 .Va format
 142 with the format description at that index.
 143 Returns 0 on success, otherwise an error code.
 144 .It Dv int get_format(void *hdl, struct video_format *format)
 145 mandatory, fills
 146 .Va format
 147 with the current video format.
 148 There should be a default format so
 149 this function works before and streaming has begun.
 150 Returns 0 on success, otherwise an error code.
 151 .It Dv int set_format(void *hdl, struct video_format *format)
 152 mandatory, sets the format of the video stream based on
 153 .Va format .
 154 Fills
 155 .Va format
 156 with the actual format used which may not be the same as requested.
 157 Returns 0 on success, otherwise an error code.
 158 .It Dv int try_format(void *hdl, struct video_format *format)
 159 optional, like
 160 .Va set_format
 161 but does not actually change the stream format, just checks what is
 162 available.
 163 Returns 0 on success, otherwise an error code.
 164 .It Dv int start_transfer(void *hdl)
 165 mandatory, starts the capture of video frames.
 166 Incoming video data
 167 must be submitted to the video layer with repeated calls to
 168 .Fn video_submit_payload .
 169 .It Dv int stop_transfer(void *hdl)
 170 .It Dv int control_iter_init(void *hdl, struct video_control_iter *)
 171 Does nothing at this time.
 172 .It Dv int control_iter_next(void *hdl, struct video_control_iter *)
 173 Does nothing at this time.
 174 .It Dv int get_control_group(void *hdl, struct video_control_group *)
 175 .It Dv int set_control_group(void *hdl, struct video_control_group *)
 176 .El
 177 .Sh SEE ALSO
 178 .Xr video 4
 179 .Sh AUTHORS
 180 .An Patrick Mahoney Aq pat@polycrystal.org
 181 .Sh BUGS
 182 Incomplete.
 183 Only supports a single video capture stream.
 184 Does not support output streams.
 185 Format handling may change in the future.
 186 Control handling may change.
 187 Current design requires copying all incoming video data.