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

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.

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

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

^^^^^^^^

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

^^^^^^^^^^

: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

^^^^

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

^^^^^^^^^^^^^^^

   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``.

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

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

^^^^^^^^^^^

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.

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.

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

: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

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.

  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

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

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

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

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.

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

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

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.

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.

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:

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

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

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.

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>`,

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

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.

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.

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.

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>`)

: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

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

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>`)