v4l2-dev.rst 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375
  1. .. SPDX-License-Identifier: GPL-2.0
  2. Video device' s internal representation
  3. =======================================
  4. The actual device nodes in the ``/dev`` directory are created using the
  5. :c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be
  6. allocated dynamically or embedded in a larger struct.
  7. To allocate it dynamically use :c:func:`video_device_alloc`:
  8. .. code-block:: c
  9. struct video_device *vdev = video_device_alloc();
  10. if (vdev == NULL)
  11. return -ENOMEM;
  12. vdev->release = video_device_release;
  13. If you embed it in a larger struct, then you must set the ``release()``
  14. callback to your own function:
  15. .. code-block:: c
  16. struct video_device *vdev = &my_vdev->vdev;
  17. vdev->release = my_vdev_release;
  18. The ``release()`` callback must be set and it is called when the last user
  19. of the video device exits.
  20. The default :c:func:`video_device_release` callback currently
  21. just calls ``kfree`` to free the allocated memory.
  22. There is also a :c:func:`video_device_release_empty` function that does
  23. nothing (is empty) and should be used if the struct is embedded and there
  24. is nothing to do when it is released.
  25. You should also set these fields of :c:type:`video_device`:
  26. - :c:type:`video_device`->v4l2_dev: must be set to the :c:type:`v4l2_device`
  27. parent device.
  28. - :c:type:`video_device`->name: set to something descriptive and unique.
  29. - :c:type:`video_device`->vfl_dir: set this to ``VFL_DIR_RX`` for capture
  30. devices (``VFL_DIR_RX`` has value 0, so this is normally already the
  31. default), set to ``VFL_DIR_TX`` for output devices and ``VFL_DIR_M2M`` for mem2mem (codec) devices.
  32. - :c:type:`video_device`->fops: set to the :c:type:`v4l2_file_operations`
  33. struct.
  34. - :c:type:`video_device`->ioctl_ops: if you use the :c:type:`v4l2_ioctl_ops`
  35. to simplify ioctl maintenance (highly recommended to use this and it might
  36. become compulsory in the future!), then set this to your
  37. :c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and
  38. :c:type:`video_device`->vfl_dir fields are used to disable ops that do not
  39. match the type/dir combination. E.g. VBI ops are disabled for non-VBI nodes,
  40. and output ops are disabled for a capture device. This makes it possible to
  41. provide just one :c:type:`v4l2_ioctl_ops` struct for both vbi and
  42. video nodes.
  43. - :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the
  44. locking in the driver. Otherwise you give it a pointer to a struct
  45. ``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl
  46. file operation is called this lock will be taken by the core and released
  47. afterwards. See the next section for more details.
  48. - :c:type:`video_device`->queue: a pointer to the struct vb2_queue
  49. associated with this device node.
  50. If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock
  51. is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``,
  52. ``QBUF``, ``DQBUF``, ``QUERYBUF``, ``PREPARE_BUF``, ``STREAMON`` and
  53. ``STREAMOFF``) instead of the lock above.
  54. That way the :ref:`vb2 <vb2_framework>` queuing framework does not have
  55. to wait for other ioctls. This queue pointer is also used by the
  56. :ref:`vb2 <vb2_framework>` helper functions to check for
  57. queuing ownership (i.e. is the filehandle calling it allowed to do the
  58. operation).
  59. - :c:type:`video_device`->prio: keeps track of the priorities. Used to
  60. implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``.
  61. If left to ``NULL``, then it will use the struct v4l2_prio_state
  62. in :c:type:`v4l2_device`. If you want to have a separate priority state per
  63. (group of) device node(s), then you can point it to your own struct
  64. :c:type:`v4l2_prio_state`.
  65. - :c:type:`video_device`->dev_parent: you only set this if v4l2_device was
  66. registered with ``NULL`` as the parent ``device`` struct. This only happens
  67. in cases where one hardware device has multiple PCI devices that all share
  68. the same :c:type:`v4l2_device` core.
  69. The cx88 driver is an example of this: one core :c:type:`v4l2_device` struct,
  70. but it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
  71. (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI
  72. devices at the same time it is setup without a parent device. But when the
  73. struct video_device is initialized you **do** know which parent
  74. PCI device to use and so you set ``dev_device`` to the correct PCI device.
  75. If you use :c:type:`v4l2_ioctl_ops`, then you should set
  76. :c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your
  77. :c:type:`v4l2_file_operations` struct.
  78. In some cases you want to tell the core that a function you had specified in
  79. your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by
  80. calling this function before :c:func:`video_register_device` is called:
  81. :c:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>`
  82. (:c:type:`vdev <video_device>`, cmd).
  83. This tends to be needed if based on external factors (e.g. which card is
  84. being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops`
  85. without having to make a new struct.
  86. The :c:type:`v4l2_file_operations` struct is a subset of file_operations.
  87. The main difference is that the inode argument is omitted since it is never
  88. used.
  89. If integration with the media framework is needed, you must initialize the
  90. :c:type:`media_entity` struct embedded in the :c:type:`video_device` struct
  91. (entity field) by calling :c:func:`media_entity_pads_init`:
  92. .. code-block:: c
  93. struct media_pad *pad = &my_vdev->pad;
  94. int err;
  95. err = media_entity_pads_init(&vdev->entity, 1, pad);
  96. The pads array must have been previously initialized. There is no need to
  97. manually set the struct media_entity type and name fields.
  98. A reference to the entity will be automatically acquired/released when the
  99. video device is opened/closed.
  100. ioctls and locking
  101. ------------------
  102. The V4L core provides optional locking services. The main service is the
  103. lock field in struct video_device, which is a pointer to a mutex.
  104. If you set this pointer, then that will be used by unlocked_ioctl to
  105. serialize all ioctls.
  106. If you are using the :ref:`videobuf2 framework <vb2_framework>`, then there
  107. is a second lock that you can set: :c:type:`video_device`->queue->lock. If
  108. set, then this lock will be used instead of :c:type:`video_device`->lock
  109. to serialize all queuing ioctls (see the previous section
  110. for the full list of those ioctls).
  111. The advantage of using a different lock for the queuing ioctls is that for some
  112. drivers (particularly USB drivers) certain commands such as setting controls
  113. can take a long time, so you want to use a separate lock for the buffer queuing
  114. ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy
  115. changing the e.g. exposure of the webcam.
  116. Of course, you can always do all the locking yourself by leaving both lock
  117. pointers at ``NULL``.
  118. If you use the old :ref:`videobuf framework <vb_framework>` then you must
  119. pass the :c:type:`video_device`->lock to the videobuf queue initialize
  120. function: if videobuf has to wait for a frame to arrive, then it will
  121. temporarily unlock the lock and relock it afterwards. If your driver also
  122. waits in the code, then you should do the same to allow other
  123. processes to access the device node while the first process is waiting for
  124. something.
  125. In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the
  126. ``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable.
  127. If you use the ``queue->lock`` pointer, then you can use the helper functions
  128. :c:func:`vb2_ops_wait_prepare` and :c:func:`vb2_ops_wait_finish`.
  129. The implementation of a hotplug disconnect should also take the lock from
  130. :c:type:`video_device` before calling v4l2_device_disconnect. If you are also
  131. using :c:type:`video_device`->queue->lock, then you have to first lock
  132. :c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock.
  133. That way you can be sure no ioctl is running when you call
  134. :c:func:`v4l2_device_disconnect`.
  135. Video device registration
  136. -------------------------
  137. Next you register the video device with :c:func:`video_register_device`.
  138. This will create the character device for you.
  139. .. code-block:: c
  140. err = video_register_device(vdev, VFL_TYPE_VIDEO, -1);
  141. if (err) {
  142. video_device_release(vdev); /* or kfree(my_vdev); */
  143. return err;
  144. }
  145. If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field,
  146. the video device entity will be automatically registered with the media
  147. device.
  148. Which device is registered depends on the type argument. The following
  149. types exist:
  150. ========================== ==================== ==============================
  151. :c:type:`vfl_devnode_type` Device name Usage
  152. ========================== ==================== ==============================
  153. ``VFL_TYPE_VIDEO`` ``/dev/videoX`` for video input/output devices
  154. ``VFL_TYPE_VBI`` ``/dev/vbiX`` for vertical blank data (i.e.
  155. closed captions, teletext)
  156. ``VFL_TYPE_RADIO`` ``/dev/radioX`` for radio tuners
  157. ``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`` for V4L2 subdevices
  158. ``VFL_TYPE_SDR`` ``/dev/swradioX`` for Software Defined Radio
  159. (SDR) tuners
  160. ``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` for touch sensors
  161. ========================== ==================== ==============================
  162. The last argument gives you a certain amount of control over the device
  163. device node number used (i.e. the X in ``videoX``). Normally you will pass -1
  164. to let the v4l2 framework pick the first free number. But sometimes users
  165. want to select a specific node number. It is common that drivers allow
  166. the user to select a specific device node number through a driver module
  167. option. That number is then passed to this function and video_register_device
  168. will attempt to select that device node number. If that number was already
  169. in use, then the next free device node number will be selected and it
  170. will send a warning to the kernel log.
  171. Another use-case is if a driver creates many devices. In that case it can
  172. be useful to place different video devices in separate ranges. For example,
  173. video capture devices start at 0, video output devices start at 16.
  174. So you can use the last argument to specify a minimum device node number
  175. and the v4l2 framework will try to pick the first free number that is equal
  176. or higher to what you passed. If that fails, then it will just pick the
  177. first free number.
  178. Since in this case you do not care about a warning about not being able
  179. to select the specified device node number, you can call the function
  180. :c:func:`video_register_device_no_warn` instead.
  181. Whenever a device node is created some attributes are also created for you.
  182. If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g.
  183. ``video0`` and you will see 'name', 'dev_debug' and 'index' attributes. The
  184. 'name' attribute is the 'name' field of the video_device struct. The
  185. 'dev_debug' attribute can be used to enable core debugging. See the next
  186. section for more detailed information on this.
  187. The 'index' attribute is the index of the device node: for each call to
  188. :c:func:`video_register_device()` the index is just increased by 1. The
  189. first video device node you register always starts with index 0.
  190. Users can setup udev rules that utilize the index attribute to make fancy
  191. device names (e.g. '``mpegX``' for MPEG video capture device nodes).
  192. After the device was successfully registered, then you can use these fields:
  193. - :c:type:`video_device`->vfl_type: the device type passed to
  194. :c:func:`video_register_device`.
  195. - :c:type:`video_device`->minor: the assigned device minor number.
  196. - :c:type:`video_device`->num: the device node number (i.e. the X in
  197. ``videoX``).
  198. - :c:type:`video_device`->index: the device index number.
  199. If the registration failed, then you need to call
  200. :c:func:`video_device_release` to free the allocated :c:type:`video_device`
  201. struct, or free your own struct if the :c:type:`video_device` was embedded in
  202. it. The ``vdev->release()`` callback will never be called if the registration
  203. failed, nor should you ever attempt to unregister the device if the
  204. registration failed.
  205. video device debugging
  206. ----------------------
  207. The 'dev_debug' attribute that is created for each video, vbi, radio or swradio
  208. device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of
  209. file operations.
  210. It is a bitmask and the following bits can be set:
  211. .. tabularcolumns:: |p{5ex}|L|
  212. ===== ================================================================
  213. Mask Description
  214. ===== ================================================================
  215. 0x01 Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are
  216. only logged if bit 0x08 is also set.
  217. 0x02 Log the ioctl name arguments and error code. VIDIOC_(D)QBUF
  218. ioctls are
  219. only logged if bit 0x08 is also set.
  220. 0x04 Log the file operations open, release, read, write, mmap and
  221. get_unmapped_area. The read and write operations are only
  222. logged if bit 0x08 is also set.
  223. 0x08 Log the read and write file operations and the VIDIOC_QBUF and
  224. VIDIOC_DQBUF ioctls.
  225. 0x10 Log the poll file operation.
  226. 0x20 Log error and messages in the control operations.
  227. ===== ================================================================
  228. Video device cleanup
  229. --------------------
  230. When the video device nodes have to be removed, either during the unload
  231. of the driver or because the USB device was disconnected, then you should
  232. unregister them with:
  233. :c:func:`video_unregister_device`
  234. (:c:type:`vdev <video_device>`);
  235. This will remove the device nodes from sysfs (causing udev to remove them
  236. from ``/dev``).
  237. After :c:func:`video_unregister_device` returns no new opens can be done.
  238. However, in the case of USB devices some application might still have one of
  239. these device nodes open. So after the unregister all file operations (except
  240. release, of course) will return an error as well.
  241. When the last user of the video device node exits, then the ``vdev->release()``
  242. callback is called and you can do the final cleanup there.
  243. Don't forget to cleanup the media entity associated with the video device if
  244. it has been initialized:
  245. :c:func:`media_entity_cleanup <media_entity_cleanup>`
  246. (&vdev->entity);
  247. This can be done from the release callback.
  248. helper functions
  249. ----------------
  250. There are a few useful helper functions:
  251. - file and :c:type:`video_device` private data
  252. You can set/get driver private data in the video_device struct using:
  253. :c:func:`video_get_drvdata <video_get_drvdata>`
  254. (:c:type:`vdev <video_device>`);
  255. :c:func:`video_set_drvdata <video_set_drvdata>`
  256. (:c:type:`vdev <video_device>`);
  257. Note that you can safely call :c:func:`video_set_drvdata` before calling
  258. :c:func:`video_register_device`.
  259. And this function:
  260. :c:func:`video_devdata <video_devdata>`
  261. (struct file \*file);
  262. returns the video_device belonging to the file struct.
  263. The :c:func:`video_devdata` function combines :c:func:`video_get_drvdata`
  264. with :c:func:`video_devdata`:
  265. :c:func:`video_drvdata <video_drvdata>`
  266. (struct file \*file);
  267. You can go from a :c:type:`video_device` struct to the v4l2_device struct using:
  268. .. code-block:: c
  269. struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
  270. - Device node name
  271. The :c:type:`video_device` node kernel name can be retrieved using:
  272. :c:func:`video_device_node_name <video_device_node_name>`
  273. (:c:type:`vdev <video_device>`);
  274. The name is used as a hint by userspace tools such as udev. The function
  275. should be used where possible instead of accessing the video_device::num and
  276. video_device::minor fields.
  277. video_device functions and data structures
  278. ------------------------------------------
  279. .. kernel-doc:: include/media/v4l2-dev.h