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