diff options
Diffstat (limited to 'Documentation/driver-api/media/mc-core.rst')
| -rw-r--r-- | Documentation/driver-api/media/mc-core.rst | 61 |
1 files changed, 39 insertions, 22 deletions
diff --git a/Documentation/driver-api/media/mc-core.rst b/Documentation/driver-api/media/mc-core.rst index 05bba0b61748..2456950ce8ff 100644 --- a/Documentation/driver-api/media/mc-core.rst +++ b/Documentation/driver-api/media/mc-core.rst @@ -36,20 +36,27 @@ pad to a sink pad. Media device ^^^^^^^^^^^^ -A media device is represented by a struct :c:type:`media_device` +A media device is represented by a struct media_device instance, defined in ``include/media/media-device.h``. Allocation of the structure is handled by the media device driver, usually by embedding the :c:type:`media_device` instance in a larger driver-specific structure. -Drivers register media device instances by calling -:c:func:`__media_device_register()` via the macro ``media_device_register()`` -and unregistered by calling :c:func:`media_device_unregister()`. +Drivers initialise media device instances by calling +:c:func:`media_device_init()`. After initialising a media device instance, it is +registered by calling :c:func:`__media_device_register()` via the macro +``media_device_register()`` and unregistered by calling +:c:func:`media_device_unregister()`. An initialised media device must be +eventually cleaned up by calling :c:func:`media_device_cleanup()`. + +Note that it is not allowed to unregister a media device instance that was not +previously registered, or clean up a media device instance that was not +previously initialised. Entities ^^^^^^^^ -Entities are represented by a struct :c:type:`media_entity` +Entities are represented by a struct media_entity instance, defined in ``include/media/media-entity.h``. The structure is usually embedded into a higher-level structure, such as :c:type:`v4l2_subdev` or :c:type:`video_device` @@ -67,10 +74,10 @@ Interfaces ^^^^^^^^^^ Interfaces are represented by a -struct :c:type:`media_interface` instance, defined in +struct media_interface instance, defined in ``include/media/media-entity.h``. Currently, only one type of interface is defined: a device node. Such interfaces are represented by a -struct :c:type:`media_intf_devnode`. +struct media_intf_devnode. Drivers initialize and create device node interfaces by calling :c:func:`media_devnode_create()` @@ -79,7 +86,7 @@ and remove them by calling: Pads ^^^^ -Pads are represented by a struct :c:type:`media_pad` instance, +Pads are represented by a struct media_pad instance, defined in ``include/media/media-entity.h``. Each entity stores its pads in a pads array managed by the entity driver. Drivers usually embed the array in a driver-specific structure. @@ -87,8 +94,8 @@ a driver-specific structure. Pads are identified by their entity and their 0-based index in the pads array. -Both information are stored in the struct :c:type:`media_pad`, -making the struct :c:type:`media_pad` pointer the canonical way +Both information are stored in the struct media_pad, +making the struct media_pad pointer the canonical way to store and pass link references. Pads have flags that describe the pad capabilities and state. @@ -104,7 +111,7 @@ Pads have flags that describe the pad capabilities and state. Links ^^^^^ -Links are represented by a struct :c:type:`media_link` instance, +Links are represented by a struct media_link instance, defined in ``include/media/media-entity.h``. There are two types of links: **1. pad to pad links**: @@ -179,15 +186,16 @@ 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 -:c:func:`media_entity_find_link()` and -:c:func:`media_entity_remote_pad()`. +(:c:func:`media_entity_find_link()`, :c:func:`media_pad_remote_pad_first()`, +:c:func:`media_entity_remote_source_pad_unique()` and +:c:func:`media_pad_remote_pad_unique()`). Use count and power handling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Due to the wide differences between drivers regarding power management needs, the media controller does not implement power management. However, -the struct :c:type:`media_entity` includes a ``use_count`` +the struct media_entity includes a ``use_count`` field that media drivers can use to track the number of users of every entity for power management needs. @@ -206,19 +214,28 @@ Link properties can be modified at runtime by calling Pipelines and media streams ^^^^^^^^^^^^^^^^^^^^^^^^^^^ +A media stream is a stream of pixels or metadata originating from one or more +source devices (such as a sensors) and flowing through media entity pads +towards the final sinks. The stream can be modified on the route by the +devices (e.g. scaling or pixel format conversions), or it can be split into +multiple branches, or multiple branches can be merged. + +A media pipeline is a set of media streams which are interdependent. This +interdependency can be caused by the hardware (e.g. configuration of a second +stream cannot be changed if the first stream has been enabled) or by the driver +due to the software design. Most commonly a media pipeline consists of a single +stream which does not branch. + When starting streaming, drivers must notify all entities in the pipeline to prevent link states from being modified during streaming by calling :c:func:`media_pipeline_start()`. -The function will mark all entities connected to the given entity through -enabled links, either directly or indirectly, as streaming. +The function will mark all the pads which are part of the pipeline as streaming. -The struct :c:type:`media_pipeline` instance pointed to by -the pipe argument will be stored in every entity in the pipeline. -Drivers should embed the struct :c:type:`media_pipeline` -in higher-level pipeline structures and can then access the -pipeline through the struct :c:type:`media_entity` -pipe field. +The struct media_pipeline instance pointed to by the pipe argument will be +stored in every pad in the pipeline. Drivers should embed the struct +media_pipeline in higher-level pipeline structures and can then access the +pipeline through the struct media_pad pipe field. Calls to :c:func:`media_pipeline_start()` can be nested. The pipeline pointer must be identical for all nested calls to the function. |