mirror of
https://github.com/torvalds/linux.git
synced 2024-11-16 17:12:06 +00:00
[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 <mchehab@s-opensource.com>
This commit is contained in:
Mauro Carvalho Chehab
parent
d9d3d1761a
commit
81d866fdcd
@ -5,6 +5,7 @@ Video2Linux devices
|
||||
:maxdepth: 1
|
||||
|
||||
v4l2-framework
|
||||
v4l2-dev
|
||||
v4l2-controls
|
||||
v4l2-device
|
||||
v4l2-dv-timings
|
||||
|
||||
343
Documentation/media/kapi/v4l2-dev.rst
Normal file
343
Documentation/media/kapi/v4l2-dev.rst
Normal file
@ -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/<devX>/ 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
|
||||
@ -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/<devX>/ 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user