138032Speter.. SPDX-License-Identifier: GPL-2.0 2159609Sgshapiro 364562SgshapiroV4L2 device instance 438032Speter-------------------- 538032Speter 638032SpeterEach device instance is represented by a struct v4l2_device. 738032SpeterVery simple devices can just allocate this struct, but most of the time you 838032Speterwould embed this struct inside a larger struct. 938032Speter 1038032SpeterYou must register the device instance by calling: 1138032Speter 1238032Speter :c:func:`v4l2_device_register <v4l2_device_register>` 1338032Speter (dev, :c:type:`v4l2_dev <v4l2_device>`). 1490792Sgshapiro 1590792SgshapiroRegistration will initialize the :c:type:`v4l2_device` struct. If the 16168515Sgshapirodev->driver_data field is ``NULL``, it will be linked to 1790792Sgshapiro:c:type:`v4l2_dev <v4l2_device>` argument. 1890792Sgshapiro 1990792SgshapiroDrivers that want integration with the media device framework need to set 2038032Speterdev->driver_data manually to point to the driver-specific device structure 2190792Sgshapirothat embed the struct v4l2_device instance. This is achieved by a 22132943Sgshapiro``dev_set_drvdata()`` call before registering the V4L2 device instance. 2364562SgshapiroThey must also set the struct v4l2_device mdev field to point to a 2438032Speterproperly initialized and registered :c:type:`media_device` instance. 2538032Speter 2638032SpeterIf :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a 2764562Sgshapirovalue derived from dev (driver name followed by the bus_id, to be precise). 2838032SpeterIf you set it up before calling :c:func:`v4l2_device_register` then it will 29168515Sgshapirobe untouched. If dev is ``NULL``, then you **must** setup 3038032Speter:c:type:`v4l2_dev <v4l2_device>`\ ->name before calling 3138032Speter:c:func:`v4l2_device_register`. 3264562Sgshapiro 3364562SgshapiroYou can use :c:func:`v4l2_device_set_name` to set the name based on a driver 3464562Sgshapironame and a driver-global atomic_t instance. This will generate names like 3564562Sgshapiro``ivtv0``, ``ivtv1``, etc. If the name ends with a digit, then it will insert 3690792Sgshapiroa dash: ``cx18-0``, ``cx18-1``, etc. This function returns the instance number. 3790792Sgshapiro 3890792SgshapiroThe first ``dev`` argument is normally the ``struct device`` pointer of a 3990792Sgshapiro``pci_dev``, ``usb_interface`` or ``platform_device``. It is rare for dev to 4090792Sgshapirobe ``NULL``, but it happens with ISA devices or when one device creates 4190792Sgshapiromultiple PCI devices, thus making it impossible to associate 4290792Sgshapiro:c:type:`v4l2_dev <v4l2_device>` with a particular parent. 4390792Sgshapiro 4490792SgshapiroYou can also supply a ``notify()`` callback that can be called by sub-devices 4590792Sgshapiroto notify you of events. Whether you need to set this depends on the 4690792Sgshapirosub-device. Any notifications a sub-device supports must be defined in a header 4790792Sgshapiroin ``include/media/subdevice.h``. 4877349Sgshapiro 4990792SgshapiroV4L2 devices are unregistered by calling: 5090792Sgshapiro 5190792Sgshapiro :c:func:`v4l2_device_unregister` 5280785Sgshapiro (:c:type:`v4l2_dev <v4l2_device>`). 5377349Sgshapiro 5490792SgshapiroIf the dev->driver_data field points to :c:type:`v4l2_dev <v4l2_device>`, 5564562Sgshapiroit will be reset to ``NULL``. Unregistering will also automatically unregister 5638032Speterall subdevs from the device. 5738032Speter 5838032SpeterIf you have a hotpluggable device (e.g. a USB device), then when a disconnect 5938032Speterhappens the parent device becomes invalid. Since :c:type:`v4l2_device` has a 6038032Speterpointer to that parent device it has to be cleared as well to mark that the 6138032Speterparent is gone. To do this call: 6238032Speter 6338032Speter :c:func:`v4l2_device_disconnect` 6464562Sgshapiro (:c:type:`v4l2_dev <v4l2_device>`). 6538032Speter 6638032SpeterThis does *not* unregister the subdevs, so you still need to call the 6738032Speter:c:func:`v4l2_device_unregister` function for that. If your driver is not 6838032Speterhotpluggable, then there is no need to call :c:func:`v4l2_device_disconnect`. 6938032Speter 7038032SpeterSometimes you need to iterate over all devices registered by a specific 7138032Speterdriver. This is usually the case if multiple device drivers use the same 7290792Sgshapirohardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv 7338032Speterhardware. The same is true for alsa drivers for example. 7438032Speter 7538032SpeterYou can iterate over all registered devices as follows: 7638032Speter 7738032Speter.. code-block:: c 7838032Speter 7938032Speter static int callback(struct device *dev, void *p) 8038032Speter { 81111823Sgshapiro struct v4l2_device *v4l2_dev = dev_get_drvdata(dev); 8238032Speter 8338032Speter /* test if this device was inited */ 8490792Sgshapiro if (v4l2_dev == NULL) 8590792Sgshapiro return 0; 8690792Sgshapiro ... 8790792Sgshapiro return 0; 8890792Sgshapiro } 8990792Sgshapiro 9090792Sgshapiro int iterate(void *p) 9138032Speter { 9238032Speter struct device_driver *drv; 9338032Speter int err; 9438032Speter 9564562Sgshapiro /* Find driver 'ivtv' on the PCI bus. 9638032Speter pci_bus_type is a global. For USB buses use usb_bus_type. */ 9738032Speter drv = driver_find("ivtv", &pci_bus_type); 9838032Speter /* iterate over all ivtv device instances */ 9990792Sgshapiro err = driver_for_each_device(drv, NULL, p, callback); 10064562Sgshapiro put_driver(drv); 10190792Sgshapiro return err; 10238032Speter } 10338032Speter 10438032SpeterSometimes you need to keep a running counter of the device instance. This is 10564562Sgshapirocommonly used to map a device instance to an index of a module option array. 10638032Speter 10790792SgshapiroThe recommended approach is as follows: 10838032Speter 10964562Sgshapiro.. code-block:: c 11064562Sgshapiro 11164562Sgshapiro static atomic_t drv_instance = ATOMIC_INIT(0); 11264562Sgshapiro 11364562Sgshapiro static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id) 11464562Sgshapiro { 11564562Sgshapiro ... 11664562Sgshapiro state->instance = atomic_inc_return(&drv_instance) - 1; 11764562Sgshapiro } 11890792Sgshapiro 11990792SgshapiroIf you have multiple device nodes then it can be difficult to know when it is 12090792Sgshapirosafe to unregister :c:type:`v4l2_device` for hotpluggable devices. For this 12190792Sgshapiropurpose :c:type:`v4l2_device` has refcounting support. The refcount is 12290792Sgshapiroincreased whenever :c:func:`video_register_device` is called and it is 12390792Sgshapirodecreased whenever that device node is released. When the refcount reaches 12490792Sgshapirozero, then the :c:type:`v4l2_device` release() callback is called. You can 12564562Sgshapirodo your final cleanup there. 12690792Sgshapiro 12790792SgshapiroIf other device nodes (e.g. ALSA) are created, then you can increase and 12890792Sgshapirodecrease the refcount manually as well by calling: 12990792Sgshapiro 13090792Sgshapiro :c:func:`v4l2_device_get` 13190792Sgshapiro (:c:type:`v4l2_dev <v4l2_device>`). 132112810Sgshapiro 13390792Sgshapiroor: 13490792Sgshapiro 13590792Sgshapiro :c:func:`v4l2_device_put` 13690792Sgshapiro (:c:type:`v4l2_dev <v4l2_device>`). 13790792Sgshapiro 13890792SgshapiroSince the initial refcount is 1 you also need to call 13990792Sgshapiro:c:func:`v4l2_device_put` in the ``disconnect()`` callback (for USB devices) 14090792Sgshapiroor in the ``remove()`` callback (for e.g. PCI devices), otherwise the refcount 14190792Sgshapirowill never reach 0. 14290792Sgshapiro 14390792Sgshapirov4l2_device functions and data structures 14490792Sgshapiro^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 14590792Sgshapiro 14690792Sgshapiro.. kernel-doc:: include/media/v4l2-device.h 14790792Sgshapiro