From ff768f596fa19e719c88fbc9bd65e13145d944e7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 4 Mar 2020 10:50:14 +0100 Subject: media: docs: kAPI docs: move them to driver-api All those documents describe the media driver API. So, move them to the right place within the Kernel documentation. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-dev.rst | 375 ---------------------------------- 1 file changed, 375 deletions(-) delete mode 100644 Documentation/media/kapi/v4l2-dev.rst (limited to 'Documentation/media/kapi/v4l2-dev.rst') diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst deleted file mode 100644 index 63c064837c00..000000000000 --- a/Documentation/media/kapi/v4l2-dev.rst +++ /dev/null @@ -1,375 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -Video device' s internal representation -======================================= - -The actual device nodes in the ``/dev`` directory are created using the -:c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be -allocated dynamically or embedded in a larger struct. - -To allocate it dynamically use :c:func:`video_device_alloc`: - -.. code-block:: c - - struct video_device *vdev = video_device_alloc(); - - if (vdev == NULL) - return -ENOMEM; - - vdev->release = video_device_release; - -If you embed it in a larger struct, then you must set the ``release()`` -callback to your own function: - -.. code-block:: c - - struct video_device *vdev = &my_vdev->vdev; - - vdev->release = my_vdev_release; - -The ``release()`` callback must be set and it is called when the last user -of the video device exits. - -The default :c:func:`video_device_release` callback currently -just calls ``kfree`` to free the allocated memory. - -There is also a :c:func:`video_device_release_empty` function that does -nothing (is empty) and should be used if the struct is embedded and there -is nothing to do when it is released. - -You should also set these fields of :c:type:`video_device`: - -- :c:type:`video_device`->v4l2_dev: must be set to the :c:type:`v4l2_device` - parent device. - -- :c:type:`video_device`->name: set to something descriptive and unique. - -- :c:type:`video_device`->vfl_dir: set this to ``VFL_DIR_RX`` for capture - devices (``VFL_DIR_RX`` has value 0, so this is normally already the - default), set to ``VFL_DIR_TX`` for output devices and ``VFL_DIR_M2M`` for mem2mem (codec) devices. - -- :c:type:`video_device`->fops: set to the :c:type:`v4l2_file_operations` - struct. - -- :c:type:`video_device`->ioctl_ops: if you use the :c:type:`v4l2_ioctl_ops` - to simplify ioctl maintenance (highly recommended to use this and it might - become compulsory in the future!), then set this to your - :c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and - :c:type:`video_device`->vfl_dir fields are used to disable ops that do not - match the type/dir combination. E.g. VBI ops are disabled for non-VBI nodes, - and output ops are disabled for a capture device. This makes it possible to - provide just one :c:type:`v4l2_ioctl_ops` struct for both vbi and - video nodes. - -- :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the - locking in the driver. Otherwise you give it a pointer to a struct - ``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl - file operation is called this lock will be taken by the core and released - afterwards. See the next section for more details. - -- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue` - associated with this device node. - If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock - is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``, - ``QBUF``, ``DQBUF``, ``QUERYBUF``, ``PREPARE_BUF``, ``STREAMON`` and - ``STREAMOFF``) instead of the lock above. - That way the :ref:`vb2 ` queuing framework does not have - to wait for other ioctls. This queue pointer is also used by the - :ref:`vb2 ` helper functions to check for - queuing ownership (i.e. is the filehandle calling it allowed to do the - operation). - -- :c:type:`video_device`->prio: keeps track of the priorities. Used to - implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``. - If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state` - in :c:type:`v4l2_device`. If you want to have a separate priority state per - (group of) device node(s), then you can point it to your own struct - :c:type:`v4l2_prio_state`. - -- :c:type:`video_device`->dev_parent: you only set this if v4l2_device was - registered with ``NULL`` as the parent ``device`` struct. This only happens - in cases where one hardware device has multiple PCI devices that all share - the same :c:type:`v4l2_device` core. - - The cx88 driver is an example of this: one core :c:type:`v4l2_device` struct, - but it is used by both a raw video PCI device (cx8800) and a MPEG PCI device - (cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI - devices at the same time it is setup without a parent device. But when the - struct :c:type:`video_device` is initialized you **do** know which parent - PCI device to use and so you set ``dev_device`` to the correct PCI device. - -If you use :c:type:`v4l2_ioctl_ops`, then you should set -:c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your -:c:type:`v4l2_file_operations` struct. - -In some cases you want to tell the core that a function you had specified in -your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by -calling this function before :c:func:`video_register_device` is called: - - :c:func:`v4l2_disable_ioctl ` - (:c:type:`vdev `, cmd). - -This tends to be needed if based on external factors (e.g. which card is -being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops` -without having to make a new struct. - -The :c:type:`v4l2_file_operations` struct is a subset of file_operations. -The main difference is that the inode argument is omitted since it is never -used. - -If integration with the media framework is needed, you must initialize the -:c:type:`media_entity` struct embedded in the :c:type:`video_device` struct -(entity field) by calling :c:func:`media_entity_pads_init`: - -.. code-block:: c - - struct media_pad *pad = &my_vdev->pad; - int err; - - err = media_entity_pads_init(&vdev->entity, 1, pad); - -The pads array must have been previously initialized. There is no need to -manually set the struct media_entity type and name fields. - -A reference to the entity will be automatically acquired/released when the -video device is opened/closed. - -ioctls and locking ------------------- - -The V4L core provides optional locking services. The main service is the -lock field in struct :c:type:`video_device`, which is a pointer to a mutex. -If you set this pointer, then that will be used by unlocked_ioctl to -serialize all ioctls. - -If you are using the :ref:`videobuf2 framework `, then there -is a second lock that you can set: :c:type:`video_device`->queue->lock. If -set, then this lock will be used instead of :c:type:`video_device`->lock -to serialize all queuing ioctls (see the previous section -for the full list of those ioctls). - -The advantage of using a different lock for the queuing ioctls is that for some -drivers (particularly USB drivers) certain commands such as setting controls -can take a long time, so you want to use a separate lock for the buffer queuing -ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy -changing the e.g. exposure of the webcam. - -Of course, you can always do all the locking yourself by leaving both lock -pointers at ``NULL``. - -If you use the old :ref:`videobuf framework ` then you must -pass the :c:type:`video_device`->lock to the videobuf queue initialize -function: if videobuf has to wait for a frame to arrive, then it will -temporarily unlock the lock and relock it afterwards. If your driver also -waits in the code, then you should do the same to allow other -processes to access the device node while the first process is waiting for -something. - -In the case of :ref:`videobuf2 ` you will need to implement the -``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable. -If you use the ``queue->lock`` pointer, then you can use the helper functions -:c:func:`vb2_ops_wait_prepare` and :c:func:`vb2_ops_wait_finish`. - -The implementation of a hotplug disconnect should also take the lock from -:c:type:`video_device` before calling v4l2_device_disconnect. If you are also -using :c:type:`video_device`->queue->lock, then you have to first lock -:c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock. -That way you can be sure no ioctl is running when you call -:c:func:`v4l2_device_disconnect`. - -Video device registration -------------------------- - -Next you register the video device with :c:func:`video_register_device`. -This will create the character device for you. - -.. code-block:: c - - err = video_register_device(vdev, VFL_TYPE_VIDEO, -1); - if (err) { - video_device_release(vdev); /* or kfree(my_vdev); */ - return err; - } - -If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field, -the video device entity will be automatically registered with the media -device. - -Which device is registered depends on the type argument. The following -types exist: - -========================== ==================== ============================== -:c:type:`vfl_devnode_type` Device name Usage -========================== ==================== ============================== -``VFL_TYPE_VIDEO`` ``/dev/videoX`` for video input/output devices -``VFL_TYPE_VBI`` ``/dev/vbiX`` for vertical blank data (i.e. - closed captions, teletext) -``VFL_TYPE_RADIO`` ``/dev/radioX`` for radio tuners -``VFL_TYPE_SUBDEV`` ``/dev/v4l-subdevX`` for V4L2 subdevices -``VFL_TYPE_SDR`` ``/dev/swradioX`` for Software Defined Radio - (SDR) tuners -``VFL_TYPE_TOUCH`` ``/dev/v4l-touchX`` for touch sensors -========================== ==================== ============================== - -The last argument gives you a certain amount of control over the device -device node number used (i.e. the X in ``videoX``). Normally you will pass -1 -to let the v4l2 framework pick the first free number. But sometimes users -want to select a specific node number. It is common that drivers allow -the user to select a specific device node number through a driver module -option. That number is then passed to this function and video_register_device -will attempt to select that device node number. If that number was already -in use, then the next free device node number will be selected and it -will send a warning to the kernel log. - -Another use-case is if a driver creates many devices. In that case it can -be useful to place different video devices in separate ranges. For example, -video capture devices start at 0, video output devices start at 16. -So you can use the last argument to specify a minimum device node number -and the v4l2 framework will try to pick the first free number that is equal -or higher to what you passed. If that fails, then it will just pick the -first free number. - -Since in this case you do not care about a warning about not being able -to select the specified device node number, you can call the function -:c:func:`video_register_device_no_warn` instead. - -Whenever a device node is created some attributes are also created for you. -If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g. -``video0`` and you will see 'name', 'dev_debug' and 'index' attributes. The -'name' attribute is the 'name' field of the video_device struct. The -'dev_debug' attribute can be used to enable core debugging. See the next -section for more detailed information on this. - -The 'index' attribute is the index of the device node: for each call to -:c:func:`video_register_device()` the index is just increased by 1. The -first video device node you register always starts with index 0. - -Users can setup udev rules that utilize the index attribute to make fancy -device names (e.g. '``mpegX``' for MPEG video capture device nodes). - -After the device was successfully registered, then you can use these fields: - -- :c:type:`video_device`->vfl_type: the device type passed to - :c:func:`video_register_device`. -- :c:type:`video_device`->minor: the assigned device minor number. -- :c:type:`video_device`->num: the device node number (i.e. the X in - ``videoX``). -- :c:type:`video_device`->index: the device index number. - -If the registration failed, then you need to call -:c:func:`video_device_release` to free the allocated :c:type:`video_device` -struct, or free your own struct if the :c:type:`video_device` was embedded in -it. The ``vdev->release()`` callback will never be called if the registration -failed, nor should you ever attempt to unregister the device if the -registration failed. - -video device debugging ----------------------- - -The 'dev_debug' attribute that is created for each video, vbi, radio or swradio -device in ``/sys/class/video4linux//`` allows you to enable logging of -file operations. - -It is a bitmask and the following bits can be set: - -.. tabularcolumns:: |p{5ex}|L| - -===== ================================================================ -Mask Description -===== ================================================================ -0x01 Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are - only logged if bit 0x08 is also set. -0x02 Log the ioctl name arguments and error code. VIDIOC_(D)QBUF - ioctls are - only logged if bit 0x08 is also set. -0x04 Log the file operations open, release, read, write, mmap and - get_unmapped_area. The read and write operations are only - logged if bit 0x08 is also set. -0x08 Log the read and write file operations and the VIDIOC_QBUF and - VIDIOC_DQBUF ioctls. -0x10 Log the poll file operation. -0x20 Log error and messages in the control operations. -===== ================================================================ - -Video device cleanup --------------------- - -When the video device nodes have to be removed, either during the unload -of the driver or because the USB device was disconnected, then you should -unregister them with: - - :c:func:`video_unregister_device` - (:c:type:`vdev `); - -This will remove the device nodes from sysfs (causing udev to remove them -from ``/dev``). - -After :c:func:`video_unregister_device` returns no new opens can be done. -However, in the case of USB devices some application might still have one of -these device nodes open. So after the unregister all file operations (except -release, of course) will return an error as well. - -When the last user of the video device node exits, then the ``vdev->release()`` -callback is called and you can do the final cleanup there. - -Don't forget to cleanup the media entity associated with the video device if -it has been initialized: - - :c:func:`media_entity_cleanup ` - (&vdev->entity); - -This can be done from the release callback. - - -helper functions ----------------- - -There are a few useful helper functions: - -- file and :c:type:`video_device` private data - -You can set/get driver private data in the video_device struct using: - - :c:func:`video_get_drvdata ` - (:c:type:`vdev `); - - :c:func:`video_set_drvdata ` - (:c:type:`vdev `); - -Note that you can safely call :c:func:`video_set_drvdata` before calling -:c:func:`video_register_device`. - -And this function: - - :c:func:`video_devdata ` - (struct file \*file); - -returns the video_device belonging to the file struct. - -The :c:func:`video_devdata` function combines :c:func:`video_get_drvdata` -with :c:func:`video_devdata`: - - :c:func:`video_drvdata ` - (struct file \*file); - -You can go from a :c:type:`video_device` struct to the v4l2_device struct using: - -.. code-block:: c - - struct v4l2_device *v4l2_dev = vdev->v4l2_dev; - -- Device node name - -The :c:type:`video_device` node kernel name can be retrieved using: - - :c:func:`video_device_node_name ` - (:c:type:`vdev `); - -The name is used as a hint by userspace tools such as udev. The function -should be used where possible instead of accessing the video_device::num and -video_device::minor fields. - -video_device functions and data structures ------------------------------------------- - -.. kernel-doc:: include/media/v4l2-dev.h -- cgit