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

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

File Facts

System
Linux kernel
Corpus path
Documentation/driver-api/media/v4l2-device.rst
Extension
.rst
Size
5588 bytes
Lines
147
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: operation-table or driver-model contract
Status
pattern implementation candidate

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

struct device_driver *drv;
		int err;

		/* Find driver 'ivtv' on the PCI bus.
		pci_bus_type is a global. For USB buses use usb_bus_type. */
		drv = driver_find("ivtv", &pci_bus_type);
		/* iterate over all ivtv device instances */
		err = driver_for_each_device(drv, NULL, p, callback);
		put_driver(drv);
		return err;
	}

Sometimes you need to keep a running counter of the device instance. This is
commonly used to map a device instance to an index of a module option array.

The recommended approach is as follows:

.. code-block:: c

	static atomic_t drv_instance = ATOMIC_INIT(0);

	static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
	{
		...
		state->instance = atomic_inc_return(&drv_instance) - 1;
	}

If you have multiple device nodes then it can be difficult to know when it is
safe to unregister :c:type:`v4l2_device` for hotpluggable devices. For this
purpose :c:type:`v4l2_device` has refcounting support. The refcount is
increased whenever :c:func:`video_register_device` is called and it is
decreased whenever that device node is released. When the refcount reaches
zero, then the :c:type:`v4l2_device` release() callback is called. You can
do your final cleanup there.

If other device nodes (e.g. ALSA) are created, then you can increase and
decrease the refcount manually as well by calling:

	:c:func:`v4l2_device_get`
	(:c:type:`v4l2_dev <v4l2_device>`).

or:

	:c:func:`v4l2_device_put`
	(:c:type:`v4l2_dev <v4l2_device>`).

Since the initial refcount is 1 you also need to call
:c:func:`v4l2_device_put` in the ``disconnect()`` callback (for USB devices)
or in the ``remove()`` callback (for e.g. PCI devices), otherwise the refcount
will never reach 0.

v4l2_device functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. kernel-doc:: include/media/v4l2-device.h

Annotation

Implementation Notes