mirror of
https://github.com/torvalds/linux.git
synced 2024-11-01 01:31:44 +00:00
[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
parent
a3f57ad0e4
commit
7b998bae05
@ -34,16 +34,16 @@ drivers/media/dvb-core.
|
||||
|
||||
Before using the Digital TV frontend core, the bridge driver should attach
|
||||
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
|
||||
detach/removal, the bridge driver should call
|
||||
:cpp:func:`dvb_unregister_frontend()` to
|
||||
remove the frontend from the core and then :cpp:func:`dvb_frontend_detach()`
|
||||
:c:func:`dvb_unregister_frontend()` to
|
||||
remove the frontend from the core and then :c:func:`dvb_frontend_detach()`
|
||||
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
|
||||
:cpp:func:`dvb_frontend_resume()` as
|
||||
:c:func:`dvb_frontend_resume()` as
|
||||
part of their handler for :c:type:`device_driver`.\ ``resume()``.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
.. kernel-doc:: drivers/media/dvb-core/demux.h
|
||||
|
||||
@ -41,8 +41,8 @@ embedding the :c:type:`media_device` instance in a larger driver-specific
|
||||
structure.
|
||||
|
||||
Drivers register media device instances by calling
|
||||
:cpp:func:`__media_device_register()` via the macro ``media_device_register()``
|
||||
and unregistered by calling :cpp:func:`media_device_unregister()`.
|
||||
:c:func:`__media_device_register()` via the macro ``media_device_register()``
|
||||
and unregistered by calling :c:func:`media_device_unregister()`.
|
||||
|
||||
Entities
|
||||
^^^^^^^^
|
||||
@ -54,12 +54,12 @@ embedded into a higher-level structure, such as
|
||||
instances, although drivers can allocate entities directly.
|
||||
|
||||
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
|
||||
:cpp:func:`media_device_register_entity()`
|
||||
:c:func:`media_device_register_entity()`
|
||||
and unregistred by calling
|
||||
:cpp:func:`media_device_unregister_entity()`.
|
||||
:c:func:`media_device_unregister_entity()`.
|
||||
|
||||
Interfaces
|
||||
^^^^^^^^^^
|
||||
@ -71,9 +71,9 @@ defined: a device node. Such interfaces are represented by a
|
||||
:c:type:`struct media_intf_devnode <media_intf_devnode>`.
|
||||
|
||||
Drivers initialize and create device node interfaces by calling
|
||||
:cpp:func:`media_devnode_create()`
|
||||
:c:func:`media_devnode_create()`
|
||||
and remove them by calling:
|
||||
:cpp:func:`media_devnode_remove()`.
|
||||
:c:func:`media_devnode_remove()`.
|
||||
|
||||
Pads
|
||||
^^^^
|
||||
@ -112,24 +112,24 @@ A given link is thus stored twice, once in the source entity and once in
|
||||
the target entity.
|
||||
|
||||
Drivers create pad to pad links by calling:
|
||||
:cpp:func:`media_create_pad_link()` and remove with
|
||||
:cpp:func:`media_entity_remove_links()`.
|
||||
:c:func:`media_create_pad_link()` and remove with
|
||||
:c:func:`media_entity_remove_links()`.
|
||||
|
||||
**2. interface to entity links**:
|
||||
|
||||
Associate one interface to a Link.
|
||||
|
||||
Drivers create interface to entity links by calling:
|
||||
:cpp:func:`media_create_intf_link()` and remove with
|
||||
:cpp:func:`media_remove_intf_links()`.
|
||||
:c:func:`media_create_intf_link()` and remove with
|
||||
:c:func:`media_remove_intf_links()`.
|
||||
|
||||
.. note::
|
||||
|
||||
Links can only be created after having both ends already created.
|
||||
|
||||
Links have flags that describe the link capabilities and state. The
|
||||
valid values are described at :cpp:func:`media_create_pad_link()` and
|
||||
:cpp:func:`media_create_intf_link()`.
|
||||
valid values are described at :c:func:`media_create_pad_link()` and
|
||||
:c:func:`media_create_intf_link()`.
|
||||
|
||||
Graph traversal
|
||||
^^^^^^^^^^^^^^^
|
||||
@ -161,13 +161,13 @@ framework provides a depth-first graph traversal API for that purpose.
|
||||
currently defined as 16.
|
||||
|
||||
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
|
||||
traversal at the given entity.
|
||||
|
||||
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``.
|
||||
|
||||
@ -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
|
||||
connected to another pad through an enabled link
|
||||
:cpp:func:`media_entity_find_link()` and
|
||||
:cpp:func:`media_entity_remote_pad()`.
|
||||
:c:func:`media_entity_find_link()` and
|
||||
:c:func:`media_entity_remote_pad()`.
|
||||
|
||||
Use count and power handling
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -198,14 +198,14 @@ Links setup
|
||||
^^^^^^^^^^^
|
||||
|
||||
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
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When starting streaming, drivers must notify all entities in the pipeline to
|
||||
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
|
||||
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>`
|
||||
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.
|
||||
|
||||
: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.
|
||||
|
||||
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
|
||||
made the same number of :cpp:func:`media_entity_pipeline_stop()` calls
|
||||
If multiple calls to :c:func:`media_entity_pipeline_start()` have been
|
||||
made the same number of :c:func:`media_entity_pipeline_stop()` calls
|
||||
are required to stop streaming.
|
||||
The :c:type:`media_entity`.\ ``pipe`` field is reset to ``NULL`` on the last
|
||||
nested stop call.
|
||||
@ -244,7 +244,7 @@ operation must be done with the media_device graph_mutex held.
|
||||
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
|
||||
:c:type:`media_entity`.\ ``link_validate()`` callback is used for that
|
||||
purpose. In ``link_validate()`` callback, entity driver should check
|
||||
|
||||
@ -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
|
||||
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
|
||||
|
||||
@ -28,10 +28,10 @@ callback to your own function:
|
||||
The ``release()`` callback must be set and it is called when the last user
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
In some cases you want to tell the core that a function you had specified in
|
||||
your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by
|
||||
calling this function before :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).
|
||||
|
||||
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
|
||||
: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
|
||||
|
||||
@ -166,7 +166,7 @@ something.
|
||||
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.
|
||||
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
|
||||
: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
|
||||
-------------------------
|
||||
|
||||
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.
|
||||
|
||||
.. 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
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
- :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`->num: the device node number (i.e. the X in
|
||||
``videoX``).
|
||||
- :c:type:`video_device`->index: the device index number.
|
||||
|
||||
If the registration failed, then you need to call
|
||||
: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
|
||||
it. The ``vdev->release()`` callback will never be called if the registration
|
||||
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
|
||||
unregister them with:
|
||||
|
||||
:cpp:func:`video_unregister_device`
|
||||
:c:func:`video_unregister_device`
|
||||
(:c:type:`vdev <video_device>`);
|
||||
|
||||
This will remove the device nodes from sysfs (causing udev to remove them
|
||||
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
|
||||
these device nodes open. So after the unregister all file operations (except
|
||||
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
|
||||
it has been initialized:
|
||||
|
||||
:cpp:func:`media_entity_cleanup <media_entity_cleanup>`
|
||||
:c:func:`media_entity_cleanup <media_entity_cleanup>`
|
||||
(&vdev->entity);
|
||||
|
||||
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:
|
||||
|
||||
:cpp:func:`video_get_drvdata <video_get_drvdata>`
|
||||
:c:func:`video_get_drvdata <video_get_drvdata>`
|
||||
(: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>`);
|
||||
|
||||
Note that you can safely call :cpp:func:`video_set_drvdata` before calling
|
||||
:cpp:func:`video_register_device`.
|
||||
Note that you can safely call :c:func:`video_set_drvdata` before calling
|
||||
:c:func:`video_register_device`.
|
||||
|
||||
And this function:
|
||||
|
||||
:cpp:func:`video_devdata <video_devdata>`
|
||||
:c:func:`video_devdata <video_devdata>`
|
||||
(struct file \*file);
|
||||
|
||||
returns the video_device belonging to the file struct.
|
||||
|
||||
The :cpp:func:`video_devdata` function combines :cpp:func:`video_get_drvdata`
|
||||
with :cpp:func:`video_devdata`:
|
||||
The :c:func:`video_devdata` function combines :cpp:func:`video_get_drvdata`
|
||||
with :c:func:`video_devdata`:
|
||||
|
||||
:cpp:func:`video_drvdata <video_drvdata>`
|
||||
:c:func:`video_drvdata <video_drvdata>`
|
||||
(struct file \*file);
|
||||
|
||||
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:
|
||||
|
||||
: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>`);
|
||||
|
||||
The name is used as a hint by userspace tools such as udev. The function
|
||||
|
||||
@ -7,7 +7,7 @@ would embed this struct inside a larger struct.
|
||||
|
||||
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>`).
|
||||
|
||||
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
|
||||
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
|
||||
: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
|
||||
``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.
|
||||
@ -46,7 +46,7 @@ in ``include/media/subdevice.h``.
|
||||
|
||||
V4L2 devices are unregistered by calling:
|
||||
|
||||
:cpp:func:`v4l2_device_unregister`
|
||||
:c:func:`v4l2_device_unregister`
|
||||
(: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
|
||||
parent is gone. To do this call:
|
||||
|
||||
:cpp:func:`v4l2_device_disconnect`
|
||||
:c:func:`v4l2_device_disconnect`
|
||||
(:c:type:`v4l2_dev <v4l2_device>`).
|
||||
|
||||
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
|
||||
hotpluggable, then there is no need to call :cpp:func:`v4l2_device_disconnect`.
|
||||
:c:func:`v4l2_device_unregister` function for that. If your driver is not
|
||||
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
|
||||
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
|
||||
safe to unregister :c:type:`v4l2_device` for hotpluggable devices. For this
|
||||
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
|
||||
zero, then the :c:type:`v4l2_device` release() callback is called. You can
|
||||
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
|
||||
decrease the refcount manually as well by calling:
|
||||
|
||||
:cpp:func:`v4l2_device_get`
|
||||
:c:func:`v4l2_device_get`
|
||||
(:c:type:`v4l2_dev <v4l2_device>`).
|
||||
|
||||
or:
|
||||
|
||||
:cpp:func:`v4l2_device_put`
|
||||
:c:func:`v4l2_device_put`
|
||||
(:c:type:`v4l2_dev <v4l2_device>`).
|
||||
|
||||
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
|
||||
will never reach 0.
|
||||
|
||||
|
||||
@ -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:
|
||||
|
||||
: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>`)
|
||||
|
||||
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:
|
||||
|
||||
: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>` ,
|
||||
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``,
|
||||
but the driver must check first if the driver is able to produce events
|
||||
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,
|
||||
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:
|
||||
|
||||
: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>`)
|
||||
|
||||
This function is used to implement :c:type:`video_device`->
|
||||
: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.
|
||||
|
||||
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:
|
||||
|
||||
:cpp:func:`v4l2_event_pending <v4l2_event_pending>`
|
||||
:c:func:`v4l2_event_pending <v4l2_event_pending>`
|
||||
(:c:type:`fh <v4l2_fh>`)
|
||||
|
||||
|
||||
|
||||
@ -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
|
||||
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.
|
||||
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
|
||||
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
|
||||
structure. In that case you should call:
|
||||
|
||||
#) :cpp: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_init` and :cpp:func:`v4l2_fh_add` in ``open()``
|
||||
#) :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
|
||||
macro.
|
||||
@ -73,7 +73,7 @@ Example:
|
||||
|
||||
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>`)
|
||||
|
||||
|
||||
@ -81,19 +81,19 @@ Below is a short description of the :c:type:`v4l2_fh` functions used:
|
||||
: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>`)
|
||||
|
||||
- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list.
|
||||
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>`)
|
||||
|
||||
- Unassociate the file handle from :c:type:`video_device`. The file handle
|
||||
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>`)
|
||||
|
||||
- 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:
|
||||
|
||||
:cpp:func:`v4l2_fh_open <v4l2_fh_open>`
|
||||
:c:func:`v4l2_fh_open <v4l2_fh_open>`
|
||||
(struct file \*filp)
|
||||
|
||||
- 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.
|
||||
|
||||
:cpp:func:`v4l2_fh_release <v4l2_fh_release>`
|
||||
:c:func:`v4l2_fh_release <v4l2_fh_release>`
|
||||
(struct file \*filp)
|
||||
|
||||
- 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
|
||||
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>`)
|
||||
|
||||
- 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)
|
||||
|
||||
- Same, but it calls v4l2_fh_is_singular with filp->private_data.
|
||||
|
||||
@ -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
|
||||
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
|
||||
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
|
||||
device data.
|
||||
|
||||
@ -27,7 +27,7 @@ methods.
|
||||
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
|
||||
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
|
||||
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:
|
||||
|
||||
: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>`).
|
||||
|
||||
|
||||
@ -97,7 +97,7 @@ i2c helper functions.
|
||||
|
||||
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
|
||||
(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:
|
||||
|
||||
.. 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.
|
||||
|
||||
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
|
||||
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.
|
||||
@ -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
|
||||
: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>`).
|
||||
|
||||
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:
|
||||
|
||||
: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>`).
|
||||
|
||||
|
||||
@ -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
|
||||
the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
|
||||
attempts. Once all conditions are met the subdevice shall be registered using
|
||||
the :cpp:func:`v4l2_async_register_subdev` function. Unregistration is
|
||||
performed using the :cpp:func:`v4l2_async_unregister_subdev` call. Subdevices
|
||||
the :c:func:`v4l2_async_register_subdev` function. Unregistration is
|
||||
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
|
||||
picked up by bridge drivers.
|
||||
|
||||
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
|
||||
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
|
||||
: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
|
||||
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`
|
||||
@ -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
|
||||
device nodes for all registered sub-devices marked with
|
||||
``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.
|
||||
|
||||
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);
|
||||
|
||||
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
|
||||
from the bridge driver. It is safe to call this even if the sub-device was
|
||||
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.
|
||||
After that the corresponding v4l2_subdev structures are invalid, so they
|
||||
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.
|
||||
|
||||
|
||||
@ -393,18 +393,18 @@ The bridge driver also has some helper functions it can use:
|
||||
"module_foo", "chipid", 0x36, NULL);
|
||||
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
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.
|
||||
"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
|
||||
@ -414,7 +414,7 @@ for the i2c_device_id table. This lists all the possibilities.
|
||||
|
||||
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:
|
||||
if addr is not 0 then that will be used (non-probing variant), otherwise the
|
||||
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,
|
||||
"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
|
||||
arguments.
|
||||
|
||||
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 older :cpp:func:`v4l2_i2c_new_subdev` and
|
||||
:cpp:func:`v4l2_i2c_new_probed_subdev` functions will call ``s_config`` as
|
||||
The older :c:func:`v4l2_i2c_new_subdev` and
|
||||
: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``.
|
||||
|
||||
V4L2 sub-device functions and data structures
|
||||
|
||||
Loading…
Reference in New Issue
Block a user