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