^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) V4L2 device instance
^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) Each device instance is represented by a struct v4l2_device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Very simple devices can just allocate this struct, but most of the time you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) would embed this struct inside a larger struct.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) You must register the device instance by calling:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) :c:func:`v4l2_device_register <v4l2_device_register>`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) (dev, :c:type:`v4l2_dev <v4l2_device>`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) Registration will initialize the :c:type:`v4l2_device` struct. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) dev->driver_data field is ``NULL``, it will be linked to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) :c:type:`v4l2_dev <v4l2_device>` argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) Drivers that want integration with the media device framework need to set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) dev->driver_data manually to point to the driver-specific device structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) that embed the struct v4l2_device instance. This is achieved by a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) ``dev_set_drvdata()`` call before registering the V4L2 device instance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) They must also set the struct v4l2_device mdev field to point to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) properly initialized and registered :c:type:`media_device` instance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) value derived from dev (driver name followed by the bus_id, to be precise).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) If you set it up before calling :c:func:`v4l2_device_register` then it will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) be untouched. If dev is ``NULL``, then you **must** setup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) :c:type:`v4l2_dev <v4l2_device>`\ ->name before calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) :c:func:`v4l2_device_register`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) You can use :c:func:`v4l2_device_set_name` to set the name based on a driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) name and a driver-global atomic_t instance. This will generate names like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) ``ivtv0``, ``ivtv1``, etc. If the name ends with a digit, then it will insert
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) a dash: ``cx18-0``, ``cx18-1``, etc. This function returns the instance number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) The first ``dev`` argument is normally the ``struct device`` pointer of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) ``pci_dev``, ``usb_interface`` or ``platform_device``. It is rare for dev to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) be ``NULL``, but it happens with ISA devices or when one device creates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) multiple PCI devices, thus making it impossible to associate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) :c:type:`v4l2_dev <v4l2_device>` with a particular parent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) You can also supply a ``notify()`` callback that can be called by sub-devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) to notify you of events. Whether you need to set this depends on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) sub-device. Any notifications a sub-device supports must be defined in a header
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) in ``include/media/subdevice.h``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) V4L2 devices are unregistered by calling:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) :c:func:`v4l2_device_unregister`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) (:c:type:`v4l2_dev <v4l2_device>`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) If the dev->driver_data field points to :c:type:`v4l2_dev <v4l2_device>`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) it will be reset to ``NULL``. Unregistering will also automatically unregister
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) all subdevs from the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) If you have a hotpluggable device (e.g. a USB device), then when a disconnect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) happens the parent device becomes invalid. Since :c:type:`v4l2_device` has a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) pointer to that parent device it has to be cleared as well to mark that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) parent is gone. To do this call:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) :c:func:`v4l2_device_disconnect`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) (:c:type:`v4l2_dev <v4l2_device>`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) This does *not* unregister the subdevs, so you still need to call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) :c:func:`v4l2_device_unregister` function for that. If your driver is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) hotpluggable, then there is no need to call :c:func:`v4l2_device_disconnect`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) Sometimes you need to iterate over all devices registered by a specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) driver. This is usually the case if multiple device drivers use the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) hardware. The same is true for alsa drivers for example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) You can iterate over all registered devices as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) static int callback(struct device *dev, void *p)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) /* test if this device was inited */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) if (v4l2_dev == NULL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) int iterate(void *p)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) struct device_driver *drv;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) /* Find driver 'ivtv' on the PCI bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) pci_bus_type is a global. For USB buses use usb_bus_type. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) drv = driver_find("ivtv", &pci_bus_type);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) /* iterate over all ivtv device instances */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) err = driver_for_each_device(drv, NULL, p, callback);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) put_driver(drv);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) Sometimes you need to keep a running counter of the device instance. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) commonly used to map a device instance to an index of a module option array.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) The recommended approach is as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) static atomic_t drv_instance = ATOMIC_INIT(0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) state->instance = atomic_inc_return(&drv_instance) - 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) If you have multiple device nodes then it can be difficult to know when it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) safe to unregister :c:type:`v4l2_device` for hotpluggable devices. For this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) purpose :c:type:`v4l2_device` has refcounting support. The refcount is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) increased whenever :c:func:`video_register_device` is called and it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) decreased whenever that device node is released. When the refcount reaches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) zero, then the :c:type:`v4l2_device` release() callback is called. You can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) do your final cleanup there.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) If other device nodes (e.g. ALSA) are created, then you can increase and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) decrease the refcount manually as well by calling:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) :c:func:`v4l2_device_get`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) (:c:type:`v4l2_dev <v4l2_device>`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) or:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) :c:func:`v4l2_device_put`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) (:c:type:`v4l2_dev <v4l2_device>`).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) Since the initial refcount is 1 you also need to call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) :c:func:`v4l2_device_put` in the ``disconnect()`` callback (for USB devices)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) or in the ``remove()`` callback (for e.g. PCI devices), otherwise the refcount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) will never reach 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) v4l2_device functions and data structures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) .. kernel-doc:: include/media/v4l2-device.h
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags