1 .. SPDX-License-Identifier: GPL-2.0
2
3 V4L2 device instance
4 --------------------
5
6 Each device instance is represented by a struc
7 Very simple devices can just allocate this str
8 would embed this struct inside a larger struct
9
10 You must register the device instance by calli
11
12 :c:func:`v4l2_device_register <v4l2_de
13 (dev, :c:type:`v4l2_dev <v4l2_device>`
14
15 Registration will initialize the :c:type:`v4l2
16 dev->driver_data field is ``NULL``, it will be
17 :c:type:`v4l2_dev <v4l2_device>` argument.
18
19 Drivers that want integration with the media d
20 dev->driver_data manually to point to the driv
21 that embed the struct v4l2_device instance. Th
22 ``dev_set_drvdata()`` call before registering
23 They must also set the struct v4l2_device mdev
24 properly initialized and registered :c:type:`m
25
26 If :c:type:`v4l2_dev <v4l2_device>`\ ->name is
27 value derived from dev (driver name followed b
28 If you set it up before calling :c:func:`v4l2
29 be untouched. If dev is ``NULL``, then you **m
30 :c:type:`v4l2_dev <v4l2_device>`\ ->name befor
31 :c:func:`v4l2_device_register`.
32
33 You can use :c:func:`v4l2_device_set_name` to
34 name and a driver-global atomic_t instance. Th
35 ``ivtv0``, ``ivtv1``, etc. If the name ends wi
36 a dash: ``cx18-0``, ``cx18-1``, etc. This func
37
38 The first ``dev`` argument is normally the ``s
39 ``pci_dev``, ``usb_interface`` or ``platform_d
40 be ``NULL``, but it happens with ISA devices o
41 multiple PCI devices, thus making it impossibl
42 :c:type:`v4l2_dev <v4l2_device>` with a partic
43
44 You can also supply a ``notify()`` callback th
45 to notify you of events. Whether you need to s
46 sub-device. Any notifications a sub-device sup
47 in ``include/media/subdevice.h``.
48
49 V4L2 devices are unregistered by calling:
50
51 :c:func:`v4l2_device_unregister`
52 (:c:type:`v4l2_dev <v4l2_device>`).
53
54 If the dev->driver_data field points to :c:typ
55 it will be reset to ``NULL``. Unregistering wi
56 all subdevs from the device.
57
58 If you have a hotpluggable device (e.g. a USB
59 happens the parent device becomes invalid. Sin
60 pointer to that parent device it has to be cle
61 parent is gone. To do this call:
62
63 :c:func:`v4l2_device_disconnect`
64 (:c:type:`v4l2_dev <v4l2_device>`).
65
66 This does *not* unregister the subdevs, so you
67 :c:func:`v4l2_device_unregister` function for
68 hotpluggable, then there is no need to call :c
69
70 Sometimes you need to iterate over all devices
71 driver. This is usually the case if multiple d
72 hardware. E.g. the ivtvfb driver is a framebuf
73 hardware. The same is true for alsa drivers fo
74
75 You can iterate over all registered devices as
76
77 .. code-block:: c
78
79 static int callback(struct device *dev
80 {
81 struct v4l2_device *v4l2_dev =
82
83 /* test if this device was ini
84 if (v4l2_dev == NULL)
85 return 0;
86 ...
87 return 0;
88 }
89
90 int iterate(void *p)
91 {
92 struct device_driver *drv;
93 int err;
94
95 /* Find driver 'ivtv' on the P
96 pci_bus_type is a global. For
97 drv = driver_find("ivtv", &pci
98 /* iterate over all ivtv devic
99 err = driver_for_each_device(d
100 put_driver(drv);
101 return err;
102 }
103
104 Sometimes you need to keep a running counter o
105 commonly used to map a device instance to an i
106
107 The recommended approach is as follows:
108
109 .. code-block:: c
110
111 static atomic_t drv_instance = ATOMIC_
112
113 static int drv_probe(struct pci_dev *p
114 {
115 ...
116 state->instance = atomic_inc_r
117 }
118
119 If you have multiple device nodes then it can
120 safe to unregister :c:type:`v4l2_device` for h
121 purpose :c:type:`v4l2_device` has refcounting
122 increased whenever :c:func:`video_register_dev
123 decreased whenever that device node is release
124 zero, then the :c:type:`v4l2_device` release()
125 do your final cleanup there.
126
127 If other device nodes (e.g. ALSA) are created,
128 decrease the refcount manually as well by call
129
130 :c:func:`v4l2_device_get`
131 (:c:type:`v4l2_dev <v4l2_device>`).
132
133 or:
134
135 :c:func:`v4l2_device_put`
136 (:c:type:`v4l2_dev <v4l2_device>`).
137
138 Since the initial refcount is 1 you also need
139 :c:func:`v4l2_device_put` in the ``disconnect(
140 or in the ``remove()`` callback (for e.g. PCI
141 will never reach 0.
142
143 v4l2_device functions and data structures
144 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
145
146 .. kernel-doc:: include/media/v4l2-device.h
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.