Documentation/media/kapi/v4l2-dev.rst

   1 Video device' s internal representation
   2 =======================================
   3
   4 The actual device nodes in the ``/dev`` directory are created using the
   5 :c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be
   6 allocated dynamically or embedded in a larger struct.
   7
   8 To allocate it dynamically use :c:func:`video_device_alloc`:
   9
  10 .. code-block:: c
  11
  12         struct video_device *vdev = video_device_alloc();
  13
  14         if (vdev == NULL)
  15                 return -ENOMEM;
  16
  17         vdev->release = video_device_release;
  18
  19 If you embed it in a larger struct, then you must set the ``release()``
  20 callback to your own function:
  21
  22 .. code-block:: c
  23
  24         struct video_device *vdev = &my_vdev->vdev;
  25
  26         vdev->release = my_vdev_release;
  27
  28 The ``release()`` callback must be set and it is called when the last user
  29 of the video device exits.
  30
  31 The default :c:func:`video_device_release` callback currently
  32 just calls ``kfree`` to free the allocated memory.
  33
  34 There is also a :c:func:`video_device_release_empty` function that does
  35 nothing (is empty) and should be used if the struct is embedded and there
  36 is nothing to do when it is released.
  37
  38 You should also set these fields of :c:type:`video_device`:
  39
  40 - :c:type:`video_device`->v4l2_dev: must be set to the :c:type:`v4l2_device`
  41   parent device.
  42
  43 - :c:type:`video_device`->name: set to something descriptive and unique.
  44
  45 - :c:type:`video_device`->vfl_dir: set this to ``VFL_DIR_RX`` for capture
  46   devices (``VFL_DIR_RX`` has value 0, so this is normally already the
  47   default), set to ``VFL_DIR_TX`` for output devices and ``VFL_DIR_M2M`` for mem2mem (codec) devices.
  48
  49 - :c:type:`video_device`->fops: set to the :c:type:`v4l2_file_operations`
  50   struct.
  51
  52 - :c:type:`video_device`->ioctl_ops: if you use the :c:type:`v4l2_ioctl_ops`
  53   to simplify ioctl maintenance (highly recommended to use this and it might
  54   become compulsory in the future!), then set this to your
  55   :c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and
  56   :c:type:`video_device`->vfl_dir fields are used to disable ops that do not
  57   match the type/dir combination. E.g. VBI ops are disabled for non-VBI nodes,
  58   and output ops  are disabled for a capture device. This makes it possible to
  59   provide just one :c:type:`v4l2_ioctl_ops` struct for both vbi and
  60   video nodes.
  61
  62 - :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the
  63   locking  in the driver. Otherwise you give it a pointer to a struct
  64   ``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl
  65   file operation is called this lock will be taken by the core and released
  66   afterwards. See the next section for more details.
  67
  68 - :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue`
  69   associated with this device node.
  70   If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock
  71   is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``,
  72   ``QBUF``, ``DQBUF``,  ``QUERYBUF``, ``PREPARE_BUF``, ``STREAMON`` and
  73   ``STREAMOFF``) instead of the lock above.
  74   That way the :ref:`vb2 <vb2_framework>` queuing framework does not have
  75   to wait for other ioctls.   This queue pointer is also used by the
  76   :ref:`vb2 <vb2_framework>` helper functions to check for
  77   queuing ownership (i.e. is the filehandle calling it allowed to do the
  78   operation).
  79
  80 - :c:type:`video_device`->prio: keeps track of the priorities. Used to
  81   implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``.
  82   If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state`
  83   in :c:type:`v4l2_device`. If you want to have a separate priority state per
  84   (group of) device node(s),   then you can point it to your own struct
  85   :c:type:`v4l2_prio_state`.
  86
  87 - :c:type:`video_device`->dev_parent: you only set this if v4l2_device was
  88   registered with ``NULL`` as the parent ``device`` struct. This only happens
  89   in cases where one hardware device has multiple PCI devices that all share
  90   the same :c:type:`v4l2_device` core.
  91
  92   The cx88 driver is an example of this: one core :c:type:`v4l2_device` struct,
  93   but   it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
  94   (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI
  95   devices at the same time it is setup without a parent device. But when the
  96   struct :c:type:`video_device` is initialized you **do** know which parent
  97   PCI device to use and so you set ``dev_device`` to the correct PCI device.
  98
  99 If you use :c:type:`v4l2_ioctl_ops`, then you should set
 100 :c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your
 101 :c:type:`v4l2_file_operations` struct.
 102
 103 In some cases you want to tell the core that a function you had specified in
 104 your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by
 105 calling this function before :c:func:`video_register_device` is called:
 106
 107         :c:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>`
 108         (:c:type:`vdev <video_device>`, cmd).
 109
 110 This tends to be needed if based on external factors (e.g. which card is
 111 being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops`
 112 without having to make a new struct.
 113
 114 The :c:type:`v4l2_file_operations` struct is a subset of file_operations.
 115 The main difference is that the inode argument is omitted since it is never
 116 used.
 117
 118 If integration with the media framework is needed, you must initialize the
 119 :c:type:`media_entity` struct embedded in the :c:type:`video_device` struct
 120 (entity field) by calling :c:func:`media_entity_pads_init`:
 121
 122 .. code-block:: c
 123
 124         struct media_pad *pad = &my_vdev->pad;
 125         int err;
 126
 127         err = media_entity_pads_init(&vdev->entity, 1, pad);
 128
 129 The pads array must have been previously initialized. There is no need to
 130 manually set the struct media_entity type and name fields.
 131
 132 A reference to the entity will be automatically acquired/released when the
 133 video device is opened/closed.
 134
 135 ioctls and locking
 136 ------------------
 137
 138 The V4L core provides optional locking services. The main service is the
 139 lock field in struct :c:type:`video_device`, which is a pointer to a mutex.
 140 If you set this pointer, then that will be used by unlocked_ioctl to
 141 serialize all ioctls.
 142
 143 If you are using the :ref:`videobuf2 framework <vb2_framework>`, then there
 144 is a second lock that you can set: :c:type:`video_device`->queue->lock. If
 145 set, then this lock will be used instead of :c:type:`video_device`->lock
 146 to serialize all queuing ioctls (see the previous section
 147 for the full list of those ioctls).
 148
 149 The advantage of using a different lock for the queuing ioctls is that for some
 150 drivers (particularly USB drivers) certain commands such as setting controls
 151 can take a long time, so you want to use a separate lock for the buffer queuing
 152 ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy
 153 changing the e.g. exposure of the webcam.
 154
 155 Of course, you can always do all the locking yourself by leaving both lock
 156 pointers at ``NULL``.
 157
 158 If you use the old :ref:`videobuf framework <vb_framework>` then you must
 159 pass the :c:type:`video_device`->lock to the videobuf queue initialize
 160 function: if videobuf has to wait for a frame to arrive, then it will
 161 temporarily unlock the lock and relock it afterwards. If your driver also
 162 waits in the code, then you should do the same to allow other
 163 processes to access the device node while the first process is waiting for
 164 something.
 165
 166 In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the
 167 ``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable.
 168 If you use the ``queue->lock`` pointer, then you can use the helper functions
 169 :c:func:`vb2_ops_wait_prepare` and :c:func:`vb2_ops_wait_finish`.
 170
 171 The implementation of a hotplug disconnect should also take the lock from
 172 :c:type:`video_device` before calling v4l2_device_disconnect. If you are also
 173 using :c:type:`video_device`->queue->lock, then you have to first lock
 174 :c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock.
 175 That way you can be sure no ioctl is running when you call
 176 :c:func:`v4l2_device_disconnect`.
 177
 178 Video device registration
 179 -------------------------
 180
 181 Next you register the video device with :c:func:`video_register_device`.
 182 This will create the character device for you.
 183
 184 .. code-block:: c
 185
 186         err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
 187         if (err) {
 188                 video_device_release(vdev); /* or kfree(my_vdev); */
 189                 return err;
 190         }
 191
 192 If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field,
 193 the video device entity will be automatically registered with the media
 194 device.
 195
 196 Which device is registered depends on the type argument. The following
 197 types exist:
 198
 199 ========================== ====================  ==============================
 200 :c:type:`vfl_devnode_type` Device name           Usage
 201 ========================== ====================  ==============================
 202 ``VFL_TYPE_GRABBER``       ``/dev/videoX``       for video input/output devices
 203 ``VFL_TYPE_VBI``           ``/dev/vbiX``         for vertical blank data (i.e.
 204                                                  closed captions, teletext)
 205 ``VFL_TYPE_RADIO``         ``/dev/radioX``       for radio tuners
 206 ``VFL_TYPE_SUBDEV``        ``/dev/v4l-subdevX``  for V4L2 subdevices
 207 ``VFL_TYPE_SDR``           ``/dev/swradioX``     for Software Defined Radio
 208                                                  (SDR) tuners
 209 ``VFL_TYPE_TOUCH``         ``/dev/v4l-touchX``   for touch sensors
 210 ========================== ====================  ==============================
 211
 212 The last argument gives you a certain amount of control over the device
 213 device node number used (i.e. the X in ``videoX``). Normally you will pass -1
 214 to let the v4l2 framework pick the first free number. But sometimes users
 215 want to select a specific node number. It is common that drivers allow
 216 the user to select a specific device node number through a driver module
 217 option. That number is then passed to this function and video_register_device
 218 will attempt to select that device node number. If that number was already
 219 in use, then the next free device node number will be selected and it
 220 will send a warning to the kernel log.
 221
 222 Another use-case is if a driver creates many devices. In that case it can
 223 be useful to place different video devices in separate ranges. For example,
 224 video capture devices start at 0, video output devices start at 16.
 225 So you can use the last argument to specify a minimum device node number
 226 and the v4l2 framework will try to pick the first free number that is equal
 227 or higher to what you passed. If that fails, then it will just pick the
 228 first free number.
 229
 230 Since in this case you do not care about a warning about not being able
 231 to select the specified device node number, you can call the function
 232 :c:func:`video_register_device_no_warn` instead.
 233
 234 Whenever a device node is created some attributes are also created for you.
 235 If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g.
 236 ``video0`` and you will see 'name', 'dev_debug' and 'index' attributes. The
 237 'name' attribute is the 'name' field of the video_device struct. The
 238 'dev_debug' attribute can be used to enable core debugging. See the next
 239 section for more detailed information on this.
 240
 241 The 'index' attribute is the index of the device node: for each call to
 242 :c:func:`video_register_device()` the index is just increased by 1. The
 243 first video device node you register always starts with index 0.
 244
 245 Users can setup udev rules that utilize the index attribute to make fancy
 246 device names (e.g. '``mpegX``' for MPEG video capture device nodes).
 247
 248 After the device was successfully registered, then you can use these fields:
 249
 250 - :c:type:`video_device`->vfl_type: the device type passed to
 251   :c:func:`video_register_device`.
 252 - :c:type:`video_device`->minor: the assigned device minor number.
 253 - :c:type:`video_device`->num: the device node number (i.e. the X in
 254   ``videoX``).
 255 - :c:type:`video_device`->index: the device index number.
 256
 257 If the registration failed, then you need to call
 258 :c:func:`video_device_release` to free the allocated :c:type:`video_device`
 259 struct, or free your own struct if the :c:type:`video_device` was embedded in
 260 it. The ``vdev->release()`` callback will never be called if the registration
 261 failed, nor should you ever attempt to unregister the device if the
 262 registration failed.
 263
 264 video device debugging
 265 ----------------------
 266
 267 The 'dev_debug' attribute that is created for each video, vbi, radio or swradio
 268 device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of
 269 file operations.
 270
 271 It is a bitmask and the following bits can be set:
 272
 273 .. tabularcolumns:: |p{5ex}|L|
 274
 275 ===== ================================================================
 276 Mask  Description
 277 ===== ================================================================
 278 0x01  Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are
 279       only logged if bit 0x08 is also set.
 280 0x02  Log the ioctl name arguments and error code. VIDIOC_(D)QBUF
 281       ioctls are
 282       only logged if bit 0x08 is also set.
 283 0x04  Log the file operations open, release, read, write, mmap and
 284       get_unmapped_area. The read and write operations are only
 285       logged if bit 0x08 is also set.
 286 0x08  Log the read and write file operations and the VIDIOC_QBUF and
 287       VIDIOC_DQBUF ioctls.
 288 0x10  Log the poll file operation.
 289 ===== ================================================================
 290
 291 Video device cleanup
 292 --------------------
 293
 294 When the video device nodes have to be removed, either during the unload
 295 of the driver or because the USB device was disconnected, then you should
 296 unregister them with:
 297
 298         :c:func:`video_unregister_device`
 299         (:c:type:`vdev <video_device>`);
 300
 301 This will remove the device nodes from sysfs (causing udev to remove them
 302 from ``/dev``).
 303
 304 After :c:func:`video_unregister_device` returns no new opens can be done.
 305 However, in the case of USB devices some application might still have one of
 306 these device nodes open. So after the unregister all file operations (except
 307 release, of course) will return an error as well.
 308
 309 When the last user of the video device node exits, then the ``vdev->release()``
 310 callback is called and you can do the final cleanup there.
 311
 312 Don't forget to cleanup the media entity associated with the video device if
 313 it has been initialized:
 314
 315         :c:func:`media_entity_cleanup <media_entity_cleanup>`
 316         (&vdev->entity);
 317
 318 This can be done from the release callback.
 319
 320
 321 helper functions
 322 ----------------
 323
 324 There are a few useful helper functions:
 325
 326 - file and :c:type:`video_device` private data
 327
 328 You can set/get driver private data in the video_device struct using:
 329
 330         :c:func:`video_get_drvdata <video_get_drvdata>`
 331         (:c:type:`vdev <video_device>`);
 332
 333         :c:func:`video_set_drvdata <video_set_drvdata>`
 334         (:c:type:`vdev <video_device>`);
 335
 336 Note that you can safely call :c:func:`video_set_drvdata` before calling
 337 :c:func:`video_register_device`.
 338
 339 And this function:
 340
 341         :c:func:`video_devdata <video_devdata>`
 342         (struct file \*file);
 343
 344 returns the video_device belonging to the file struct.
 345
 346 The :c:func:`video_devdata` function combines :c:func:`video_get_drvdata`
 347 with :c:func:`video_devdata`:
 348
 349         :c:func:`video_drvdata <video_drvdata>`
 350         (struct file \*file);
 351
 352 You can go from a :c:type:`video_device` struct to the v4l2_device struct using:
 353
 354 .. code-block:: c
 355
 356         struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
 357
 358 - Device node name
 359
 360 The :c:type:`video_device` node kernel name can be retrieved using:
 361
 362         :c:func:`video_device_node_name <video_device_node_name>`
 363         (:c:type:`vdev <video_device>`);
 364
 365 The name is used as a hint by userspace tools such as udev. The function
 366 should be used where possible instead of accessing the video_device::num and
 367 video_device::minor fields.
 368
 369 video_device functions and data structures
 370 ------------------------------------------
 371
 372 .. kernel-doc:: include/media/v4l2-dev.h