From 81d866fdcda8888970dc1812da927e509f429ea9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Thu, 21 Jul 2016 15:37:34 -0300 Subject: [media] doc-rst: move v4l2-dev doc to a separate file Move the documentation for video device node creation to a separate file. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/kapi/v4l2-core.rst | 1 + Documentation/media/kapi/v4l2-dev.rst | 343 +++++++++++++++++++++++++++ Documentation/media/kapi/v4l2-framework.rst | 344 ---------------------------- 3 files changed, 344 insertions(+), 344 deletions(-) create mode 100644 Documentation/media/kapi/v4l2-dev.rst (limited to 'Documentation') diff --git a/Documentation/media/kapi/v4l2-core.rst b/Documentation/media/kapi/v4l2-core.rst index fc623e9..6fa30f8 100644 --- a/Documentation/media/kapi/v4l2-core.rst +++ b/Documentation/media/kapi/v4l2-core.rst @@ -5,6 +5,7 @@ Video2Linux devices :maxdepth: 1 v4l2-framework + v4l2-dev v4l2-controls v4l2-device v4l2-dv-timings diff --git a/Documentation/media/kapi/v4l2-dev.rst b/Documentation/media/kapi/v4l2-dev.rst new file mode 100644 index 0000000..f9b75d2 --- /dev/null +++ b/Documentation/media/kapi/v4l2-dev.rst @@ -0,0 +1,343 @@ +Video device creation +===================== + +The actual device nodes in the /dev directory are created using the +video_device struct (v4l2-dev.h). This struct can either be allocated +dynamically or embedded in a larger struct. + +To allocate it dynamically use: + +.. code-block:: none + + 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:: none + + 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 video_device_release() callback just calls kfree to free the +allocated memory. + +There is also a video_device_release_empty() function that does nothing +(is empty) and can be used if the struct is embedded and there is nothing +to do when it is released. + +You should also set these fields: + +- v4l2_dev: must be set to the v4l2_device parent device. + +- name: set to something descriptive and unique. + +- 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. + +- fops: set to the v4l2_file_operations struct. + +- ioctl_ops: if you use the 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 v4l2_ioctl_ops struct. The vfl_type and + 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 v4l2_ioctl_ops struct for both vbi and video nodes. + +- 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 + unlocked_ioctl file operation is called this lock will be taken by the + core and released afterwards. See the next section for more details. + +- queue: a pointer to the struct vb2_queue associated with this device node. + If queue is non-NULL, and queue->lock is non-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 vb2 queuing framework does not have to wait for other ioctls. + This queue pointer is also used by the vb2 helper functions to check for + queuing ownership (i.e. is the filehandle calling it allowed to do the + operation). + +- prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY. + If left to NULL, then it will use the struct v4l2_prio_state in 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 v4l2_prio_state. + +- 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 v4l2_device core. + + The cx88 driver is an example of this: one core v4l2_device struct, but + it is used by both a raw video PCI device (cx8800) and a MPEG PCI device + (cx8802). Since the v4l2_device cannot be associated with two PCI devices + at the same time it is setup without a parent device. But when the struct + 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 v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2 +in your v4l2_file_operations struct. + +Do not use .ioctl! This is deprecated and will go away in the future. + +In some cases you want to tell the core that a function you had specified in +your v4l2_ioctl_ops should be ignored. You can mark such ioctls by calling this +function before video_device_register is called: + +.. code-block:: none + + void v4l2_disable_ioctl(struct video_device *vdev, unsigned int 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 v4l2_ioctl_ops without +having to make a new struct. + +The 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 +media_entity struct embedded in the video_device struct (entity field) by +calling media_entity_pads_init(): + +.. code-block:: none + + 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 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 videobuf2 framework, then there is a second lock that you +can set: video_device->queue->lock. If set, then this lock will be used instead +of 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 videobuf then you must pass the 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 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 vb2_ops_wait_prepare/finish. + +The implementation of a hotplug disconnect should also take the lock from +video_device before calling v4l2_device_disconnect. If you are also using +video_device->queue->lock, then you have to first lock video_device->queue->lock +followed by video_device->lock. That way you can be sure no ioctl is running +when you call v4l2_device_disconnect. + +video_device registration +------------------------- + +Next you register the video device: this will create the character device +for you. + +.. code-block:: none + + err = video_register_device(vdev, VFL_TYPE_GRABBER, -1); + if (err) { + video_device_release(vdev); /* or kfree(my_vdev); */ + return err; + } + +If the v4l2_device parent device has a non-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: + +VFL_TYPE_GRABBER: videoX for video input/output devices +VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext) +VFL_TYPE_RADIO: radioX for radio tuners +VFL_TYPE_SDR: swradioX for Software Defined Radio tuners + +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 +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 +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: + +- vfl_type: the device type passed to video_register_device. +- minor: the assigned device minor number. +- num: the device node number (i.e. the X in videoX). +- index: the device index number. + +If the registration failed, then you need to call video_device_release() +to free the allocated video_device struct, or free your own struct if the +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: + +.. code-block:: none + + 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. + +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: + +.. code-block:: none + + video_unregister_device(vdev); + +This will remove the device nodes from sysfs (causing udev to remove them +from /dev). + +After 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: + +.. code-block:: none + + media_entity_cleanup(&vdev->entity); + +This can be done from the release callback. + + +video_device helper functions +----------------------------- + +There are a few useful helper functions: + +- file/video_device private data + +You can set/get driver private data in the video_device struct using: + +.. code-block:: none + + void *video_get_drvdata(struct video_device *vdev); + void video_set_drvdata(struct video_device *vdev, void *data); + +Note that you can safely call video_set_drvdata() before calling +video_register_device(). + +And this function: + +.. code-block:: none + + struct video_device *video_devdata(struct file *file); + +returns the video_device belonging to the file struct. + +The video_drvdata function combines video_get_drvdata with video_devdata: + +.. code-block:: none + + void *video_drvdata(struct file *file); + +You can go from a video_device struct to the v4l2_device struct using: + +.. code-block:: none + + struct v4l2_device *v4l2_dev = vdev->v4l2_dev; + +- Device node name + +The video_device node kernel name can be retrieved using + +.. code-block:: none + + const char *video_device_node_name(struct video_device *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 kAPI +----------------- + +.. kernel-doc:: include/media/v4l2-dev.h diff --git a/Documentation/media/kapi/v4l2-framework.rst b/Documentation/media/kapi/v4l2-framework.rst index 315388e..c97ffd0 100644 --- a/Documentation/media/kapi/v4l2-framework.rst +++ b/Documentation/media/kapi/v4l2-framework.rst @@ -81,345 +81,6 @@ driver sets the struct v4l2_device mdev field, sub-devices and video nodes will automatically appear in the media framework as entities. -struct video_device -------------------- - -The actual device nodes in the /dev directory are created using the -video_device struct (v4l2-dev.h). This struct can either be allocated -dynamically or embedded in a larger struct. - -To allocate it dynamically use: - -.. code-block:: none - - 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:: none - - 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 video_device_release() callback just calls kfree to free the -allocated memory. - -There is also a video_device_release_empty() function that does nothing -(is empty) and can be used if the struct is embedded and there is nothing -to do when it is released. - -You should also set these fields: - -- v4l2_dev: must be set to the v4l2_device parent device. - -- name: set to something descriptive and unique. - -- 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. - -- fops: set to the v4l2_file_operations struct. - -- ioctl_ops: if you use the 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 v4l2_ioctl_ops struct. The vfl_type and - 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 v4l2_ioctl_ops struct for both vbi and video nodes. - -- 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 - unlocked_ioctl file operation is called this lock will be taken by the - core and released afterwards. See the next section for more details. - -- queue: a pointer to the struct vb2_queue associated with this device node. - If queue is non-NULL, and queue->lock is non-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 vb2 queuing framework does not have to wait for other ioctls. - This queue pointer is also used by the vb2 helper functions to check for - queuing ownership (i.e. is the filehandle calling it allowed to do the - operation). - -- prio: keeps track of the priorities. Used to implement VIDIOC_G/S_PRIORITY. - If left to NULL, then it will use the struct v4l2_prio_state in 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 v4l2_prio_state. - -- 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 v4l2_device core. - - The cx88 driver is an example of this: one core v4l2_device struct, but - it is used by both a raw video PCI device (cx8800) and a MPEG PCI device - (cx8802). Since the v4l2_device cannot be associated with two PCI devices - at the same time it is setup without a parent device. But when the struct - 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 v4l2_ioctl_ops, then you should set .unlocked_ioctl to video_ioctl2 -in your v4l2_file_operations struct. - -Do not use .ioctl! This is deprecated and will go away in the future. - -In some cases you want to tell the core that a function you had specified in -your v4l2_ioctl_ops should be ignored. You can mark such ioctls by calling this -function before video_device_register is called: - -.. code-block:: none - - void v4l2_disable_ioctl(struct video_device *vdev, unsigned int 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 v4l2_ioctl_ops without -having to make a new struct. - -The 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 -media_entity struct embedded in the video_device struct (entity field) by -calling media_entity_pads_init(): - -.. code-block:: none - - 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 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 videobuf2 framework, then there is a second lock that you -can set: video_device->queue->lock. If set, then this lock will be used instead -of 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 videobuf then you must pass the 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 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 vb2_ops_wait_prepare/finish. - -The implementation of a hotplug disconnect should also take the lock from -video_device before calling v4l2_device_disconnect. If you are also using -video_device->queue->lock, then you have to first lock video_device->queue->lock -followed by video_device->lock. That way you can be sure no ioctl is running -when you call v4l2_device_disconnect. - -video_device registration -------------------------- - -Next you register the video device: this will create the character device -for you. - -.. code-block:: none - - err = video_register_device(vdev, VFL_TYPE_GRABBER, -1); - if (err) { - video_device_release(vdev); /* or kfree(my_vdev); */ - return err; - } - -If the v4l2_device parent device has a non-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: - -VFL_TYPE_GRABBER: videoX for video input/output devices -VFL_TYPE_VBI: vbiX for vertical blank data (i.e. closed captions, teletext) -VFL_TYPE_RADIO: radioX for radio tuners -VFL_TYPE_SDR: swradioX for Software Defined Radio tuners - -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 -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 -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: - -- vfl_type: the device type passed to video_register_device. -- minor: the assigned device minor number. -- num: the device node number (i.e. the X in videoX). -- index: the device index number. - -If the registration failed, then you need to call video_device_release() -to free the allocated video_device struct, or free your own struct if the -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: - -.. code-block:: none - - 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. - -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: - -.. code-block:: none - - video_unregister_device(vdev); - -This will remove the device nodes from sysfs (causing udev to remove them -from /dev). - -After 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: - -.. code-block:: none - - media_entity_cleanup(&vdev->entity); - -This can be done from the release callback. - - -video_device helper functions ------------------------------ - -There are a few useful helper functions: - -- file/video_device private data - -You can set/get driver private data in the video_device struct using: - -.. code-block:: none - - void *video_get_drvdata(struct video_device *vdev); - void video_set_drvdata(struct video_device *vdev, void *data); - -Note that you can safely call video_set_drvdata() before calling -video_register_device(). - -And this function: - -.. code-block:: none - - struct video_device *video_devdata(struct file *file); - -returns the video_device belonging to the file struct. - -The video_drvdata function combines video_get_drvdata with video_devdata: - -.. code-block:: none - - void *video_drvdata(struct file *file); - -You can go from a video_device struct to the v4l2_device struct using: - -.. code-block:: none - - struct v4l2_device *v4l2_dev = vdev->v4l2_dev; - -- Device node name - -The video_device node kernel name can be retrieved using - -.. code-block:: none - - const char *video_device_node_name(struct video_device *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 buffer helper functions ----------------------------- @@ -699,8 +360,3 @@ methods. It is expected that once the CCF becomes available on all relevant architectures this API will be removed. - -video_device kAPI -^^^^^^^^^^^^^^^^^ - -.. kernel-doc:: include/media/v4l2-dev.h -- cgit v1.1