Documentation/driver-api/media/v4l2-dev.rst

Source file repositories/reference/linux-study-clean/Documentation/driver-api/media/v4l2-dev.rst

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/media/v4l2-dev.rst
Extension
.rst
Size
15272 bytes
Lines
368
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

Video device' s internal representation
=======================================

The actual device nodes in the ``/dev`` directory are created using the
:c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be
allocated dynamically or embedded in a larger struct.

To allocate it dynamically use :c:func:`video_device_alloc`:

.. code-block:: c

	struct video_device *vdev = video_device_alloc();

	if (vdev == NULL)
		return -ENOMEM;

	vdev->release = video_device_release;

If you embed it in a larger struct, then you must set the ``release()``
callback to your own function:

.. code-block:: c

	struct video_device *vdev = &my_vdev->vdev;

	vdev->release = my_vdev_release;

The ``release()`` callback must be set and it is called when the last user
of the video device exits.

The default :c:func:`video_device_release` callback currently
just calls ``kfree`` to free the allocated memory.

There is also a :c:func:`video_device_release_empty` function that does
nothing (is empty) and should be used if the struct is embedded and there
is nothing to do when it is released.

You should also set these fields of :c:type:`video_device`:

- :c:type:`video_device`->v4l2_dev: must be set to the :c:type:`v4l2_device`
  parent device.

- :c:type:`video_device`->name: set to something descriptive and unique.

- :c:type:`video_device`->vfl_dir: set this to ``VFL_DIR_RX`` for capture
  devices (``VFL_DIR_RX`` has value 0, so this is normally already the
  default), set to ``VFL_DIR_TX`` for output devices and ``VFL_DIR_M2M`` for mem2mem (codec) devices.

- :c:type:`video_device`->fops: set to the :c:type:`v4l2_file_operations`
  struct.

- :c:type:`video_device`->ioctl_ops: if you use the :c:type:`v4l2_ioctl_ops`
  to simplify ioctl maintenance (highly recommended to use this and it might
  become compulsory in the future!), then set this to your
  :c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and
  :c:type:`video_device`->vfl_dir fields are used to disable ops that do not
  match the type/dir combination. E.g. VBI ops are disabled for non-VBI nodes,
  and output ops  are disabled for a capture device. This makes it possible to
  provide just one :c:type:`v4l2_ioctl_ops` struct for both vbi and
  video nodes.

- :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the
  locking  in the driver. Otherwise you give it a pointer to a struct
  ``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl
  file operation is called this lock will be taken by the core and released
  afterwards. See the next section for more details.

- :c:type:`video_device`->queue: a pointer to the struct vb2_queue

Annotation

Implementation Notes