hollalinux
/
linux-sg2042
mirror of https://github.com/sophgo/linux-riscv.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[media] doc-rst: kapi: use :c:func: instead of :cpp:func 

References at the rst files for C functions generated via
kernel-doc should use :c:func:.

Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
This commit is contained in:
Mauro Carvalho Chehab 2016-07-23 07:21:06 -03:00
parent a3f57ad0e4
commit 7b998bae05
7 changed files with 106 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
Documentation/media/kapi/dtv-core.rst
View File

@ -34,16 +34,16 @@ drivers/media/dvb-core.
Before using the Digital TV frontend core, the bridge driver should attach Before using the Digital TV frontend core, the bridge driver should attach
the frontend demod, tuner and SEC devices and call the frontend demod, tuner and SEC devices and call
:cpp:func:`dvb_register_frontend()`, :c:func:`dvb_register_frontend()`,
in order to register the new frontend at the subsystem. At device in order to register the new frontend at the subsystem. At device
detach/removal, the bridge driver should call detach/removal, the bridge driver should call
:cpp:func:`dvb_unregister_frontend()` to :c:func:`dvb_unregister_frontend()` to
remove the frontend from the core and then :cpp:func:`dvb_frontend_detach()` remove the frontend from the core and then :c:func:`dvb_frontend_detach()`
to free the memory allocated by the frontend drivers. to free the memory allocated by the frontend drivers.
The drivers should also call :cpp:func:`dvb_frontend_suspend()` as part of The drivers should also call :c:func:`dvb_frontend_suspend()` as part of
their handler for the :c:type:`device_driver`.\ ``suspend()``, and their handler for the :c:type:`device_driver`.\ ``suspend()``, and
:cpp:func:`dvb_frontend_resume()` as :c:func:`dvb_frontend_resume()` as
part of their handler for :c:type:`device_driver`.\ ``resume()``. part of their handler for :c:type:`device_driver`.\ ``resume()``.
A few other optional functions are provided to handle some special cases. A few other optional functions are provided to handle some special cases.
@ -121,7 +121,7 @@ triggered by a hardware interrupt, it is recommended to use the Linux
bottom half mechanism or start a tasklet instead of making the callback bottom half mechanism or start a tasklet instead of making the callback
function call directly from a hardware interrupt. function call directly from a hardware interrupt.
This mechanism is implemented by :cpp:func:`dmx_ts_cb()` and :cpp:func:`dmx_section_cb()` This mechanism is implemented by :c:func:`dmx_ts_cb()` and :cpp:func:`dmx_section_cb()`
callbacks. callbacks.
.. kernel-doc:: drivers/media/dvb-core/demux.h .. kernel-doc:: drivers/media/dvb-core/demux.h

50
Documentation/media/kapi/mc-core.rst
View File

@ -41,8 +41,8 @@ embedding the :c:type:`media_device` instance in a larger driver-specific
structure. structure.
Drivers register media device instances by calling Drivers register media device instances by calling
:cpp:func:`__media_device_register()` via the macro ``media_device_register()`` :c:func:`__media_device_register()` via the macro ``media_device_register()``
and unregistered by calling :cpp:func:`media_device_unregister()`. and unregistered by calling :c:func:`media_device_unregister()`.
Entities Entities
^^^^^^^^ ^^^^^^^^
@ -54,12 +54,12 @@ embedded into a higher-level structure, such as
instances, although drivers can allocate entities directly. instances, although drivers can allocate entities directly.
Drivers initialize entity pads by calling Drivers initialize entity pads by calling
:cpp:func:`media_entity_pads_init()`. :c:func:`media_entity_pads_init()`.
Drivers register entities with a media device by calling Drivers register entities with a media device by calling
:cpp:func:`media_device_register_entity()` :c:func:`media_device_register_entity()`
and unregistred by calling and unregistred by calling
:cpp:func:`media_device_unregister_entity()`. :c:func:`media_device_unregister_entity()`.
Interfaces Interfaces
^^^^^^^^^^ ^^^^^^^^^^
@ -71,9 +71,9 @@ defined: a device node. Such interfaces are represented by a
:c:type:`struct media_intf_devnode <media_intf_devnode>`. :c:type:`struct media_intf_devnode <media_intf_devnode>`.
Drivers initialize and create device node interfaces by calling Drivers initialize and create device node interfaces by calling
:cpp:func:`media_devnode_create()` :c:func:`media_devnode_create()`
and remove them by calling: and remove them by calling:
:cpp:func:`media_devnode_remove()`. :c:func:`media_devnode_remove()`.
Pads Pads
^^^^ ^^^^
@ -112,24 +112,24 @@ A given link is thus stored twice, once in the source entity and once in
the target entity. the target entity.
Drivers create pad to pad links by calling: Drivers create pad to pad links by calling:
:cpp:func:`media_create_pad_link()` and remove with :c:func:`media_create_pad_link()` and remove with
:cpp:func:`media_entity_remove_links()`. :c:func:`media_entity_remove_links()`.
**2. interface to entity links**: **2. interface to entity links**:
Associate one interface to a Link. Associate one interface to a Link.
Drivers create interface to entity links by calling: Drivers create interface to entity links by calling:
:cpp:func:`media_create_intf_link()` and remove with :c:func:`media_create_intf_link()` and remove with
:cpp:func:`media_remove_intf_links()`. :c:func:`media_remove_intf_links()`.
.. note:: .. note::
Links can only be created after having both ends already created. Links can only be created after having both ends already created.
Links have flags that describe the link capabilities and state. The Links have flags that describe the link capabilities and state. The
valid values are described at :cpp:func:`media_create_pad_link()` and valid values are described at :c:func:`media_create_pad_link()` and
:cpp:func:`media_create_intf_link()`. :c:func:`media_create_intf_link()`.
Graph traversal Graph traversal
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
@ -161,13 +161,13 @@ framework provides a depth-first graph traversal API for that purpose.
currently defined as 16. currently defined as 16.
Drivers initiate a graph traversal by calling Drivers initiate a graph traversal by calling
:cpp:func:`media_entity_graph_walk_start()` :c:func:`media_entity_graph_walk_start()`
The graph structure, provided by the caller, is initialized to start graph The graph structure, provided by the caller, is initialized to start graph
traversal at the given entity. traversal at the given entity.
Drivers can then retrieve the next entity by calling Drivers can then retrieve the next entity by calling
:cpp:func:`media_entity_graph_walk_next()` :c:func:`media_entity_graph_walk_next()`
When the graph traversal is complete the function will return ``NULL``. When the graph traversal is complete the function will return ``NULL``.
@ -176,8 +176,8 @@ is required and the graph structure can be freed normally.
Helper functions can be used to find a link between two given pads, or a pad Helper functions can be used to find a link between two given pads, or a pad
connected to another pad through an enabled link connected to another pad through an enabled link
:cpp:func:`media_entity_find_link()` and :c:func:`media_entity_find_link()` and
:cpp:func:`media_entity_remote_pad()`. :c:func:`media_entity_remote_pad()`.
Use count and power handling Use count and power handling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -198,14 +198,14 @@ Links setup
^^^^^^^^^^^ ^^^^^^^^^^^
Link properties can be modified at runtime by calling Link properties can be modified at runtime by calling
:cpp:func:`media_entity_setup_link()`. :c:func:`media_entity_setup_link()`.
Pipelines and media streams Pipelines and media streams
^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^
When starting streaming, drivers must notify all entities in the pipeline to When starting streaming, drivers must notify all entities in the pipeline to
prevent link states from being modified during streaming by calling prevent link states from being modified during streaming by calling
:cpp:func:`media_entity_pipeline_start()`. :c:func:`media_entity_pipeline_start()`.
The function will mark all entities connected to the given entity through The function will mark all entities connected to the given entity through
enabled links, either directly or indirectly, as streaming. enabled links, either directly or indirectly, as streaming.
@ -217,17 +217,17 @@ in higher-level pipeline structures and can then access the
pipeline through the :c:type:`struct media_entity <media_entity>` pipeline through the :c:type:`struct media_entity <media_entity>`
pipe field. pipe field.
Calls to :cpp:func:`media_entity_pipeline_start()` can be nested. Calls to :c:func:`media_entity_pipeline_start()` can be nested.
The pipeline pointer must be identical for all nested calls to the function. The pipeline pointer must be identical for all nested calls to the function.
:cpp:func:`media_entity_pipeline_start()` may return an error. In that case, :c:func:`media_entity_pipeline_start()` may return an error. In that case,
it will clean up any of the changes it did by itself. it will clean up any of the changes it did by itself.
When stopping the stream, drivers must notify the entities with When stopping the stream, drivers must notify the entities with
:cpp:func:`media_entity_pipeline_stop()`. :c:func:`media_entity_pipeline_stop()`.
If multiple calls to :cpp:func:`media_entity_pipeline_start()` have been If multiple calls to :c:func:`media_entity_pipeline_start()` have been
made the same number of :cpp:func:`media_entity_pipeline_stop()` calls made the same number of :c:func:`media_entity_pipeline_stop()` calls
are required to stop streaming. are required to stop streaming.
The :c:type:`media_entity`.\ ``pipe`` field is reset to ``NULL`` on the last The :c:type:`media_entity`.\ ``pipe`` field is reset to ``NULL`` on the last
nested stop call. nested stop call.
@ -244,7 +244,7 @@ operation must be done with the media_device graph_mutex held.
Link validation Link validation
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
Link validation is performed by :cpp:func:`media_entity_pipeline_start()` Link validation is performed by :c:func:`media_entity_pipeline_start()`
for any entity which has sink pads in the pipeline. The for any entity which has sink pads in the pipeline. The
:c:type:`media_entity`.\ ``link_validate()`` callback is used for that :c:type:`media_entity`.\ ``link_validate()`` callback is used for that
purpose. In ``link_validate()`` callback, entity driver should check purpose. In ``link_validate()`` callback, entity driver should check

50
Documentation/media/kapi/v4l2-dev.rst
View File

@ -5,7 +5,7 @@ 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 :c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be
allocated dynamically or embedded in a larger struct. allocated dynamically or embedded in a larger struct.
To allocate it dynamically use :cpp:func:`video_device_alloc`: To allocate it dynamically use :c:func:`video_device_alloc`:
.. code-block:: c .. code-block:: c
@ -28,10 +28,10 @@ callback to your own function:
The ``release()`` callback must be set and it is called when the last user The ``release()`` callback must be set and it is called when the last user
of the video device exits. of the video device exits.
The default :cpp:func:`video_device_release` callback currently The default :c:func:`video_device_release` callback currently
just calls ``kfree`` to free the allocated memory. just calls ``kfree`` to free the allocated memory.
There is also a ::cpp:func:`video_device_release_empty` function that does 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 nothing (is empty) and should be used if the struct is embedded and there
is nothing to do when it is released. is nothing to do when it is released.
@ -97,14 +97,14 @@ You should also set these fields of :c:type:`video_device`:
PCI device to use and so you set ``dev_device`` to the correct PCI device. 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 If you use :c:type:`v4l2_ioctl_ops`, then you should set
:c:type:`video_device`->unlocked_ioctl to :cpp:func:`video_ioctl2` in your :c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your
:c:type:`v4l2_file_operations` struct. :c:type:`v4l2_file_operations` struct.
In some cases you want to tell the core that a function you had specified in 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 your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by
calling this function before :cpp:func:`video_register_device` is called: calling this function before :c:func:`video_register_device` is called:
:cpp:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>` :c:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>`
(:c:type:`vdev <video_device>`, cmd). (:c:type:`vdev <video_device>`, cmd).
This tends to be needed if based on external factors (e.g. which card is This tends to be needed if based on external factors (e.g. which card is
@ -117,7 +117,7 @@ used.
If integration with the media framework is needed, you must initialize the 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 :c:type:`media_entity` struct embedded in the :c:type:`video_device` struct
(entity field) by calling :cpp:func:`media_entity_pads_init`: (entity field) by calling :c:func:`media_entity_pads_init`:
.. code-block:: c .. code-block:: c
@ -166,7 +166,7 @@ something.
In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the
``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable. ``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 If you use the ``queue->lock`` pointer, then you can use the helper functions
:cpp:func:`vb2_ops_wait_prepare` and :cpp:func:`vb2_ops_wait_finish`. :c:func:`vb2_ops_wait_prepare` and :cpp:func:`vb2_ops_wait_finish`.
The implementation of a hotplug disconnect should also take the lock from 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 :c:type:`video_device` before calling v4l2_device_disconnect. If you are also
@ -178,7 +178,7 @@ That way you can be sure no ioctl is running when you call
Video device registration Video device registration
------------------------- -------------------------
Next you register the video device with :cpp:func:`video_register_device`. Next you register the video device with :c:func:`video_register_device`.
This will create the character device for you. This will create the character device for you.
.. code-block:: c .. code-block:: c
@ -221,7 +221,7 @@ first free number.
Since in this case you do not care about a warning about not being able 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 to select the specified device node number, you can call the function
:cpp:func:`video_register_device_no_warn` instead. :c:func:`video_register_device_no_warn` instead.
Whenever a device node is created some attributes are also created for you. 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. If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g.
@ -231,7 +231,7 @@ If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g.
section for more detailed information on this. section for more detailed information on this.
The 'index' attribute is the index of the device node: for each call to The 'index' attribute is the index of the device node: for each call to
:cpp:func:`video_register_device()` the index is just increased by 1. The :c:func:`video_register_device()` the index is just increased by 1. The
first video device node you register always starts with index 0. first video device node you register always starts with index 0.
Users can setup udev rules that utilize the index attribute to make fancy Users can setup udev rules that utilize the index attribute to make fancy
@ -240,14 +240,14 @@ device names (e.g. '``mpegX``' for MPEG video capture device nodes).
After the device was successfully registered, then you can use these fields: After the device was successfully registered, then you can use these fields:
- :c:type:`video_device`->vfl_type: the device type passed to - :c:type:`video_device`->vfl_type: the device type passed to
:cpp:func:`video_register_device`. :c:func:`video_register_device`.
- :c:type:`video_device`->minor: the assigned device minor number. - :c:type:`video_device`->minor: the assigned device minor number.
- :c:type:`video_device`->num: the device node number (i.e. the X in - :c:type:`video_device`->num: the device node number (i.e. the X in
``videoX``). ``videoX``).
- :c:type:`video_device`->index: the device index number. - :c:type:`video_device`->index: the device index number.
If the registration failed, then you need to call If the registration failed, then you need to call
:cpp:func:`video_device_release` to free the allocated :c:type:`video_device` :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 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 it. The ``vdev->release()`` callback will never be called if the registration
failed, nor should you ever attempt to unregister the device if the failed, nor should you ever attempt to unregister the device if the
@ -286,13 +286,13 @@ 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 of the driver or because the USB device was disconnected, then you should
unregister them with: unregister them with:
:cpp:func:`video_unregister_device` :c:func:`video_unregister_device`
(:c:type:`vdev <video_device>`); (:c:type:`vdev <video_device>`);
This will remove the device nodes from sysfs (causing udev to remove them This will remove the device nodes from sysfs (causing udev to remove them
from ``/dev``). from ``/dev``).
After :cpp:func:`video_unregister_device` returns no new opens can be done. 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 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 these device nodes open. So after the unregister all file operations (except
release, of course) will return an error as well. release, of course) will return an error as well.
@ -303,7 +303,7 @@ 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 Don't forget to cleanup the media entity associated with the video device if
it has been initialized: it has been initialized:
:cpp:func:`media_entity_cleanup <media_entity_cleanup>` :c:func:`media_entity_cleanup <media_entity_cleanup>`
(&vdev->entity); (&vdev->entity);
This can be done from the release callback. This can be done from the release callback.
@ -318,26 +318,26 @@ There are a few useful helper functions:
You can set/get driver private data in the video_device struct using: You can set/get driver private data in the video_device struct using:
:cpp:func:`video_get_drvdata <video_get_drvdata>` :c:func:`video_get_drvdata <video_get_drvdata>`
(:c:type:`vdev <video_device>`); (:c:type:`vdev <video_device>`);
:cpp:func:`video_set_drvdata <video_set_drvdata>` :c:func:`video_set_drvdata <video_set_drvdata>`
(:c:type:`vdev <video_device>`); (:c:type:`vdev <video_device>`);
Note that you can safely call :cpp:func:`video_set_drvdata` before calling Note that you can safely call :c:func:`video_set_drvdata` before calling
:cpp:func:`video_register_device`. :c:func:`video_register_device`.
And this function: And this function:
:cpp:func:`video_devdata <video_devdata>` :c:func:`video_devdata <video_devdata>`
(struct file \*file); (struct file \*file);
returns the video_device belonging to the file struct. returns the video_device belonging to the file struct.
The :cpp:func:`video_devdata` function combines :cpp:func:`video_get_drvdata` The :c:func:`video_devdata` function combines :cpp:func:`video_get_drvdata`
with :cpp:func:`video_devdata`: with :c:func:`video_devdata`:
:cpp:func:`video_drvdata <video_drvdata>` :c:func:`video_drvdata <video_drvdata>`
(struct file \*file); (struct file \*file);
You can go from a :c:type:`video_device` struct to the v4l2_device struct using: You can go from a :c:type:`video_device` struct to the v4l2_device struct using:
@ -350,7 +350,7 @@ You can go from a :c:type:`video_device` struct to the v4l2_device struct using:
The :c:type:`video_device` node kernel name can be retrieved using: The :c:type:`video_device` node kernel name can be retrieved using:
:cpp:func:`video_device_node_name <video_device_node_name>` :c:func:`video_device_node_name <video_device_node_name>`
(:c:type:`vdev <video_device>`); (:c:type:`vdev <video_device>`);
The name is used as a hint by userspace tools such as udev. The function The name is used as a hint by userspace tools such as udev. The function

24
Documentation/media/kapi/v4l2-device.rst
View File

@ -7,7 +7,7 @@ would embed this struct inside a larger struct.
You must register the device instance by calling: You must register the device instance by calling:
:cpp:func:`v4l2_device_register <v4l2_device_register>` :c:func:`v4l2_device_register <v4l2_device_register>`
(dev, :c:type:`v4l2_dev <v4l2_device>`). (dev, :c:type:`v4l2_dev <v4l2_device>`).
Registration will initialize the :c:type:`v4l2_device` struct. If the Registration will initialize the :c:type:`v4l2_device` struct. If the
@ -23,12 +23,12 @@ properly initialized and registered :c:type:`media_device` instance.
If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a
value derived from dev (driver name followed by the bus_id, to be precise). value derived from dev (driver name followed by the bus_id, to be precise).
If you set it up before calling :cpp:func:`v4l2_device_register` then it will If you set it up before calling :c:func:`v4l2_device_register` then it will
be untouched. If dev is ``NULL``, then you **must** setup be untouched. If dev is ``NULL``, then you **must** setup
:c:type:`v4l2_dev <v4l2_device>`\ ->name before calling :c:type:`v4l2_dev <v4l2_device>`\ ->name before calling
:cpp:func:`v4l2_device_register`. :c:func:`v4l2_device_register`.
You can use :cpp:func:`v4l2_device_set_name` to set the name based on a driver You can use :c:func:`v4l2_device_set_name` to set the name based on a driver
name and a driver-global atomic_t instance. This will generate names like name and a driver-global atomic_t instance. This will generate names like
``ivtv0``, ``ivtv1``, etc. If the name ends with a digit, then it will insert ``ivtv0``, ``ivtv1``, etc. If the name ends with a digit, then it will insert
a dash: ``cx18-0``, ``cx18-1``, etc. This function returns the instance number. a dash: ``cx18-0``, ``cx18-1``, etc. This function returns the instance number.
@ -46,7 +46,7 @@ in ``include/media/subdevice.h``.
V4L2 devices are unregistered by calling: V4L2 devices are unregistered by calling:
:cpp:func:`v4l2_device_unregister` :c:func:`v4l2_device_unregister`
(:c:type:`v4l2_dev <v4l2_device>`). (:c:type:`v4l2_dev <v4l2_device>`).
If the dev->driver_data field points to :c:type:`v4l2_dev <v4l2_device>`, If the dev->driver_data field points to :c:type:`v4l2_dev <v4l2_device>`,
@ -58,12 +58,12 @@ happens the parent device becomes invalid. Since :c:type:`v4l2_device` has a
pointer to that parent device it has to be cleared as well to mark that the pointer to that parent device it has to be cleared as well to mark that the
parent is gone. To do this call: parent is gone. To do this call:
:cpp:func:`v4l2_device_disconnect` :c:func:`v4l2_device_disconnect`
(:c:type:`v4l2_dev <v4l2_device>`). (:c:type:`v4l2_dev <v4l2_device>`).
This does *not* unregister the subdevs, so you still need to call the This does *not* unregister the subdevs, so you still need to call the
:cpp:func:`v4l2_device_unregister` function for that. If your driver is not :c:func:`v4l2_device_unregister` function for that. If your driver is not
hotpluggable, then there is no need to call :cpp:func:`v4l2_device_disconnect`. hotpluggable, then there is no need to call :c:func:`v4l2_device_disconnect`.
Sometimes you need to iterate over all devices registered by a specific Sometimes you need to iterate over all devices registered by a specific
driver. This is usually the case if multiple device drivers use the same driver. This is usually the case if multiple device drivers use the same
@ -117,7 +117,7 @@ The recommended approach is as follows:
If you have multiple device nodes then it can be difficult to know when it is If you have multiple device nodes then it can be difficult to know when it is
safe to unregister :c:type:`v4l2_device` for hotpluggable devices. For this safe to unregister :c:type:`v4l2_device` for hotpluggable devices. For this
purpose :c:type:`v4l2_device` has refcounting support. The refcount is purpose :c:type:`v4l2_device` has refcounting support. The refcount is
increased whenever :cpp:func:`video_register_device` is called and it is increased whenever :c:func:`video_register_device` is called and it is
decreased whenever that device node is released. When the refcount reaches decreased whenever that device node is released. When the refcount reaches
zero, then the :c:type:`v4l2_device` release() callback is called. You can zero, then the :c:type:`v4l2_device` release() callback is called. You can
do your final cleanup there. do your final cleanup there.
@ -125,16 +125,16 @@ do your final cleanup there.
If other device nodes (e.g. ALSA) are created, then you can increase and If other device nodes (e.g. ALSA) are created, then you can increase and
decrease the refcount manually as well by calling: decrease the refcount manually as well by calling:
:cpp:func:`v4l2_device_get` :c:func:`v4l2_device_get`
(:c:type:`v4l2_dev <v4l2_device>`). (:c:type:`v4l2_dev <v4l2_device>`).
or: or:
:cpp:func:`v4l2_device_put` :c:func:`v4l2_device_put`
(:c:type:`v4l2_dev <v4l2_device>`). (:c:type:`v4l2_dev <v4l2_device>`).
Since the initial refcount is 1 you also need to call Since the initial refcount is 1 you also need to call
:cpp:func:`v4l2_device_put` in the ``disconnect()`` callback (for USB devices) :c:func:`v4l2_device_put` in the ``disconnect()`` callback (for USB devices)
or in the ``remove()`` callback (for e.g. PCI devices), otherwise the refcount or in the ``remove()`` callback (for e.g. PCI devices), otherwise the refcount
will never reach 0. will never reach 0.

12
Documentation/media/kapi/v4l2-event.rst
View File

@ -39,7 +39,7 @@ A good example of these ``replace``/``merge`` callbacks is in v4l2-event.c:
In order to queue events to video device, drivers should call: In order to queue events to video device, drivers should call:
:cpp:func:`v4l2_event_queue <v4l2_event_queue>` :c:func:`v4l2_event_queue <v4l2_event_queue>`
(:c:type:`vdev <video_device>`, :ref:`ev <v4l2-event>`) (:c:type:`vdev <video_device>`, :ref:`ev <v4l2-event>`)
The driver's only responsibility is to fill in the type and the data fields. The driver's only responsibility is to fill in the type and the data fields.
@ -50,7 +50,7 @@ Event subscription
Subscribing to an event is via: Subscribing to an event is via:
:cpp:func:`v4l2_event_subscribe <v4l2_event_subscribe>` :c:func:`v4l2_event_subscribe <v4l2_event_subscribe>`
(:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>` , (:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>` ,
elems, :c:type:`ops <v4l2_subscribed_event_ops>`) elems, :c:type:`ops <v4l2_subscribed_event_ops>`)
@ -59,7 +59,7 @@ This function is used to implement :c:type:`video_device`->
:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_subscribe_event``, :c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_subscribe_event``,
but the driver must check first if the driver is able to produce events but the driver must check first if the driver is able to produce events
with specified event id, and then should call with specified event id, and then should call
:cpp:func:`v4l2_event_subscribe` to subscribe the event. :c:func:`v4l2_event_subscribe` to subscribe the event.
The elems argument is the size of the event queue for this event. If it is 0, The elems argument is the size of the event queue for this event. If it is 0,
then the framework will fill in a default value (this depends on the event then the framework will fill in a default value (this depends on the event
@ -85,12 +85,12 @@ Unsubscribing an event
Unsubscribing to an event is via: Unsubscribing to an event is via:
:cpp:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>` :c:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>`
(:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>`) (:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>`)
This function is used to implement :c:type:`video_device`-> This function is used to implement :c:type:`video_device`->
:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``. :c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``.
A driver may call :cpp:func:`v4l2_event_unsubscribe` directly unless it A driver may call :c:func:`v4l2_event_unsubscribe` directly unless it
wants to be involved in unsubscription process. wants to be involved in unsubscription process.
The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The
@ -101,7 +101,7 @@ Check if there's a pending event
Checking if there's a pending event is via: Checking if there's a pending event is via:
:cpp:func:`v4l2_event_pending <v4l2_event_pending>` :c:func:`v4l2_event_pending <v4l2_event_pending>`
(:c:type:`fh <v4l2_fh>`) (:c:type:`fh <v4l2_fh>`)

22
Documentation/media/kapi/v4l2-fh.rst
View File

@ -12,7 +12,7 @@ data that is used by the V4L2 framework.
The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know
whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags. by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
This bit is set whenever :cpp:func:`v4l2_fh_init` is called. This bit is set whenever :c:func:`v4l2_fh_init` is called.
struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle
structure and ``file->private_data`` is set to it in the driver's ``open()`` structure and ``file->private_data`` is set to it in the driver's ``open()``
@ -21,8 +21,8 @@ function by the driver.
In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger
structure. In that case you should call: structure. In that case you should call:
#) :cpp:func:`v4l2_fh_init` and :cpp:func:`v4l2_fh_add` in ``open()`` #) :c:func:`v4l2_fh_init` and :cpp:func:`v4l2_fh_add` in ``open()``
#) :cpp:func:`v4l2_fh_del` and :cpp:func:`v4l2_fh_exit` in ``release()`` #) :c:func:`v4l2_fh_del` and :cpp:func:`v4l2_fh_exit` in ``release()``
Drivers can extract their own file handle structure by using the container_of Drivers can extract their own file handle structure by using the container_of
macro. macro.
@ -73,7 +73,7 @@ Example:
Below is a short description of the :c:type:`v4l2_fh` functions used: Below is a short description of the :c:type:`v4l2_fh` functions used:
:cpp:func:`v4l2_fh_init <v4l2_fh_init>` :c:func:`v4l2_fh_init <v4l2_fh_init>`
(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`) (:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`)
@ -81,19 +81,19 @@ Below is a short description of the :c:type:`v4l2_fh` functions used:
:c:type:`v4l2_file_operations`->open() handler. :c:type:`v4l2_file_operations`->open() handler.
:cpp:func:`v4l2_fh_add <v4l2_fh_add>` :c:func:`v4l2_fh_add <v4l2_fh_add>`
(:c:type:`fh <v4l2_fh>`) (:c:type:`fh <v4l2_fh>`)
- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list. - Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list.
Must be called once the file handle is completely initialized. Must be called once the file handle is completely initialized.
:cpp:func:`v4l2_fh_del <v4l2_fh_del>` :c:func:`v4l2_fh_del <v4l2_fh_del>`
(:c:type:`fh <v4l2_fh>`) (:c:type:`fh <v4l2_fh>`)
- Unassociate the file handle from :c:type:`video_device`. The file handle - Unassociate the file handle from :c:type:`video_device`. The file handle
exit function may now be called. exit function may now be called.
:cpp:func:`v4l2_fh_exit <v4l2_fh_exit>` :c:func:`v4l2_fh_exit <v4l2_fh_exit>`
(:c:type:`fh <v4l2_fh>`) (:c:type:`fh <v4l2_fh>`)
- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh` - Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh`
@ -102,13 +102,13 @@ Below is a short description of the :c:type:`v4l2_fh` functions used:
If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions: If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions:
:cpp:func:`v4l2_fh_open <v4l2_fh_open>` :c:func:`v4l2_fh_open <v4l2_fh_open>`
(struct file \*filp) (struct file \*filp)
- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to - This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to
the struct :c:type:`video_device` associated with the file struct. the struct :c:type:`video_device` associated with the file struct.
:cpp:func:`v4l2_fh_release <v4l2_fh_release>` :c:func:`v4l2_fh_release <v4l2_fh_release>`
(struct file \*filp) (struct file \*filp)
- This deletes it from the struct :c:type:`video_device` associated with the - This deletes it from the struct :c:type:`video_device` associated with the
@ -122,12 +122,12 @@ when the last file handle closes. Two helper functions were added to check
whether the :c:type:`v4l2_fh` struct is the only open filehandle of the whether the :c:type:`v4l2_fh` struct is the only open filehandle of the
associated device node: associated device node:
:cpp:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>` :c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>`
(:c:type:`fh <v4l2_fh>`) (:c:type:`fh <v4l2_fh>`)
- Returns 1 if the file handle is the only open file handle, else 0. - Returns 1 if the file handle is the only open file handle, else 0.
:cpp:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>` :c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>`
(struct file \*filp) (struct file \*filp)
- Same, but it calls v4l2_fh_is_singular with filp->private_data. - Same, but it calls v4l2_fh_is_singular with filp->private_data.

42
Documentation/media/kapi/v4l2-subdev.rst
View File

@ -15,7 +15,7 @@ can be stand-alone for simple sub-devices or it might be embedded in a larger
struct if more state information needs to be stored. Usually there is a struct if more state information needs to be stored. Usually there is a
low-level device struct (e.g. ``i2c_client``) that contains the device data as low-level device struct (e.g. ``i2c_client``) that contains the device data as
setup by the kernel. It is recommended to store that pointer in the private setup by the kernel. It is recommended to store that pointer in the private
data of :c:type:`v4l2_subdev` using :cpp:func:`v4l2_set_subdevdata`. That makes data of :c:type:`v4l2_subdev` using :c:func:`v4l2_set_subdevdata`. That makes
it easy to go from a :c:type:`v4l2_subdev` to the actual low-level bus-specific it easy to go from a :c:type:`v4l2_subdev` to the actual low-level bus-specific
device data. device data.
@ -27,7 +27,7 @@ methods.
Bridges might also need to store per-subdev private data, such as a pointer to Bridges might also need to store per-subdev private data, such as a pointer to
bridge-specific per-subdev private data. The :c:type:`v4l2_subdev` structure bridge-specific per-subdev private data. The :c:type:`v4l2_subdev` structure
provides host private data for that purpose that can be accessed with provides host private data for that purpose that can be accessed with
:cpp:func:`v4l2_get_subdev_hostdata` and :cpp:func:`v4l2_set_subdev_hostdata`. :c:func:`v4l2_get_subdev_hostdata` and :cpp:func:`v4l2_set_subdev_hostdata`.
From the bridge driver perspective, you load the sub-device module and somehow From the bridge driver perspective, you load the sub-device module and somehow
obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call
@ -87,7 +87,7 @@ to add new ops and categories.
A sub-device driver initializes the :c:type:`v4l2_subdev` struct using: A sub-device driver initializes the :c:type:`v4l2_subdev` struct using:
:cpp:func:`v4l2_subdev_init <v4l2_subdev_init>` :c:func:`v4l2_subdev_init <v4l2_subdev_init>`
(:c:type:`sd <v4l2_subdev>`, &\ :c:type:`ops <v4l2_subdev_ops>`). (:c:type:`sd <v4l2_subdev>`, &\ :c:type:`ops <v4l2_subdev_ops>`).
@ -97,7 +97,7 @@ i2c helper functions.
If integration with the media framework is needed, you must initialize the If integration with the media framework is needed, you must initialize the
:c:type:`media_entity` struct embedded in the :c:type:`v4l2_subdev` struct :c:type:`media_entity` struct embedded in the :c:type:`v4l2_subdev` struct
(entity field) by calling :cpp:func:`media_entity_pads_init`, if the entity has (entity field) by calling :c:func:`media_entity_pads_init`, if the entity has
pads: pads:
.. code-block:: c .. code-block:: c
@ -131,7 +131,7 @@ sub-devices. The driver is still responsible for validating the correctness
of the format configuration between sub-devices and video nodes. of the format configuration between sub-devices and video nodes.
If link_validate op is not set, the default function If link_validate op is not set, the default function
:cpp:func:`v4l2_subdev_link_validate_default` is used instead. This function :c:func:`v4l2_subdev_link_validate_default` is used instead. This function
ensures that width, height and the media bus pixel code are equal on both source ensures that width, height and the media bus pixel code are equal on both source
and sink of the link. Subdev drivers are also free to use this function to and sink of the link. Subdev drivers are also free to use this function to
perform the checks mentioned above in addition to their own checks. perform the checks mentioned above in addition to their own checks.
@ -158,7 +158,7 @@ run-time bridge-subdevice interaction is in both cases the same.
In the synchronous case a device (bridge) driver needs to register the In the synchronous case a device (bridge) driver needs to register the
:c:type:`v4l2_subdev` with the v4l2_device: :c:type:`v4l2_subdev` with the v4l2_device:
:cpp:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>` :c:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>`
(:c:type:`v4l2_dev <v4l2_device>`, :c:type:`sd <v4l2_subdev>`). (:c:type:`v4l2_dev <v4l2_device>`, :c:type:`sd <v4l2_subdev>`).
This can fail if the subdev module disappeared before it could be registered. This can fail if the subdev module disappeared before it could be registered.
@ -170,7 +170,7 @@ entity will be automatically registered with the media device.
You can unregister a sub-device using: You can unregister a sub-device using:
:cpp:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>` :c:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>`
(:c:type:`sd <v4l2_subdev>`). (:c:type:`sd <v4l2_subdev>`).
@ -242,16 +242,16 @@ the requirements for a successful probing are satisfied. This can include a
check for a master clock availability. If any of the conditions aren't satisfied check for a master clock availability. If any of the conditions aren't satisfied
the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
attempts. Once all conditions are met the subdevice shall be registered using attempts. Once all conditions are met the subdevice shall be registered using
the :cpp:func:`v4l2_async_register_subdev` function. Unregistration is the :c:func:`v4l2_async_register_subdev` function. Unregistration is
performed using the :cpp:func:`v4l2_async_unregister_subdev` call. Subdevices performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
registered this way are stored in a global list of subdevices, ready to be registered this way are stored in a global list of subdevices, ready to be
picked up by bridge drivers. picked up by bridge drivers.
Bridge drivers in turn have to register a notifier object with an array of Bridge drivers in turn have to register a notifier object with an array of
subdevice descriptors that the bridge device needs for its operation. This is subdevice descriptors that the bridge device needs for its operation. This is
performed using the :cpp:func:`v4l2_async_notifier_register` call. To performed using the :c:func:`v4l2_async_notifier_register` call. To
unregister the notifier the driver has to call unregister the notifier the driver has to call
:cpp:func:`v4l2_async_notifier_unregister`. The former of the two functions :c:func:`v4l2_async_notifier_unregister`. The former of the two functions
takes two arguments: a pointer to struct :c:type:`v4l2_device` and a pointer to takes two arguments: a pointer to struct :c:type:`v4l2_device` and a pointer to
struct :c:type:`v4l2_async_notifier`. The latter contains a pointer to an array struct :c:type:`v4l2_async_notifier`. The latter contains a pointer to an array
of pointers to subdevice descriptors of type struct :c:type:`v4l2_async_subdev` of pointers to subdevice descriptors of type struct :c:type:`v4l2_async_subdev`
@ -275,7 +275,7 @@ it must set the ``V4L2_SUBDEV_FL_HAS_DEVNODE`` flag before being registered.
After registering sub-devices, the :c:type:`v4l2_device` driver can create After registering sub-devices, the :c:type:`v4l2_device` driver can create
device nodes for all registered sub-devices marked with device nodes for all registered sub-devices marked with
``V4L2_SUBDEV_FL_HAS_DEVNODE`` by calling ``V4L2_SUBDEV_FL_HAS_DEVNODE`` by calling
:cpp:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be :c:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be
automatically removed when sub-devices are unregistered. automatically removed when sub-devices are unregistered.
The device node handles a subset of the V4L2 API. The device node handles a subset of the V4L2 API.
@ -372,7 +372,7 @@ And this to go from an ``i2c_client`` to a :c:type:`v4l2_subdev` struct:
struct v4l2_subdev *sd = i2c_get_clientdata(client); struct v4l2_subdev *sd = i2c_get_clientdata(client);
Make sure to call Make sure to call
:cpp:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) :c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
when the ``remove()`` callback is called. This will unregister the sub-device when the ``remove()`` callback is called. This will unregister the sub-device
from the bridge driver. It is safe to call this even if the sub-device was from the bridge driver. It is safe to call this even if the sub-device was
never registered. never registered.
@ -381,7 +381,7 @@ You need to do this because when the bridge driver destroys the i2c adapter
the ``remove()`` callbacks are called of the i2c devices on that adapter. the ``remove()`` callbacks are called of the i2c devices on that adapter.
After that the corresponding v4l2_subdev structures are invalid, so they After that the corresponding v4l2_subdev structures are invalid, so they
have to be unregistered first. Calling have to be unregistered first. Calling
:cpp:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`) :c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
from the ``remove()`` callback ensures that this is always done correctly. from the ``remove()`` callback ensures that this is always done correctly.
@ -393,18 +393,18 @@ The bridge driver also has some helper functions it can use:
"module_foo", "chipid", 0x36, NULL); "module_foo", "chipid", 0x36, NULL);
This loads the given module (can be ``NULL`` if no module needs to be loaded) This loads the given module (can be ``NULL`` if no module needs to be loaded)
and calls :cpp:func:`i2c_new_device` with the given ``i2c_adapter`` and and calls :c:func:`i2c_new_device` with the given ``i2c_adapter`` and
chip/address arguments. If all goes well, then it registers the subdev with chip/address arguments. If all goes well, then it registers the subdev with
the v4l2_device. the v4l2_device.
You can also use the last argument of :cpp:func:`v4l2_i2c_new_subdev` to pass You can also use the last argument of :c:func:`v4l2_i2c_new_subdev` to pass
an array of possible I2C addresses that it should probe. These probe addresses an array of possible I2C addresses that it should probe. These probe addresses
are only used if the previous argument is 0. A non-zero argument means that you are only used if the previous argument is 0. A non-zero argument means that you
know the exact i2c address so in that case no probing will take place. know the exact i2c address so in that case no probing will take place.
Both functions return ``NULL`` if something went wrong. Both functions return ``NULL`` if something went wrong.
Note that the chipid you pass to :cpp:func:`v4l2_i2c_new_subdev` is usually Note that the chipid you pass to :c:func:`v4l2_i2c_new_subdev` is usually
the same as the module name. It allows you to specify a chip variant, e.g. the same as the module name. It allows you to specify a chip variant, e.g.
"saa7114" or "saa7115". In general though the i2c driver autodetects this. "saa7114" or "saa7115". In general though the i2c driver autodetects this.
The use of chipid is something that needs to be looked at more closely at a The use of chipid is something that needs to be looked at more closely at a
@ -414,7 +414,7 @@ for the i2c_device_id table. This lists all the possibilities.
There are two more helper functions: There are two more helper functions:
:cpp:func:`v4l2_i2c_new_subdev_cfg`: this function adds new irq and :c:func:`v4l2_i2c_new_subdev_cfg`: this function adds new irq and
platform_data arguments and has both 'addr' and 'probed_addrs' arguments: platform_data arguments and has both 'addr' and 'probed_addrs' arguments:
if addr is not 0 then that will be used (non-probing variant), otherwise the if addr is not 0 then that will be used (non-probing variant), otherwise the
probed_addrs are probed. probed_addrs are probed.
@ -426,15 +426,15 @@ For example: this will probe for address 0x10:
struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter, struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
"module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10)); "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
:cpp:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct :c:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct
which is passed to the i2c driver and replaces the irq, platform_data and addr which is passed to the i2c driver and replaces the irq, platform_data and addr
arguments. arguments.
If the subdev supports the s_config core ops, then that op is called with If the subdev supports the s_config core ops, then that op is called with
the irq and platform_data arguments after the subdev was setup. the irq and platform_data arguments after the subdev was setup.
The older :cpp:func:`v4l2_i2c_new_subdev` and The older :c:func:`v4l2_i2c_new_subdev` and
:cpp:func:`v4l2_i2c_new_probed_subdev` functions will call ``s_config`` as :c:func:`v4l2_i2c_new_probed_subdev` functions will call ``s_config`` as
well, but with irq set to 0 and platform_data set to ``NULL``. well, but with irq set to 0 and platform_data set to ``NULL``.
V4L2 sub-device functions and data structures V4L2 sub-device functions and data structures