Documentation/media/kapi/mc-core.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Media Controller devices
   4 ------------------------
   5
   6 Media Controller
   7 ~~~~~~~~~~~~~~~~
   8
   9 The media controller userspace API is documented in
  10 :ref:`the Media Controller uAPI book <media_controller>`. This document focus
  11 on the kernel-side implementation of the media framework.
  12
  13 Abstract media device model
  14 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  15
  16 Discovering a device internal topology, and configuring it at runtime, is one
  17 of the goals of the media framework. To achieve this, hardware devices are
  18 modelled as an oriented graph of building blocks called entities connected
  19 through pads.
  20
  21 An entity is a basic media hardware building block. It can correspond to
  22 a large variety of logical blocks such as physical hardware devices
  23 (CMOS sensor for instance), logical hardware devices (a building block
  24 in a System-on-Chip image processing pipeline), DMA channels or physical
  25 connectors.
  26
  27 A pad is a connection endpoint through which an entity can interact with
  28 other entities. Data (not restricted to video) produced by an entity
  29 flows from the entity's output to one or more entity inputs. Pads should
  30 not be confused with physical pins at chip boundaries.
  31
  32 A link is a point-to-point oriented connection between two pads, either
  33 on the same entity or on different entities. Data flows from a source
  34 pad to a sink pad.
  35
  36 Media device
  37 ^^^^^^^^^^^^
  38
  39 A media device is represented by a struct :c:type:`media_device`
  40 instance, defined in ``include/media/media-device.h``.
  41 Allocation of the structure is handled by the media device driver, usually by
  42 embedding the :c:type:`media_device` instance in a larger driver-specific
  43 structure.
  44
  45 Drivers register media device instances by calling
  46 :c:func:`__media_device_register()` via the macro ``media_device_register()``
  47 and unregistered by calling :c:func:`media_device_unregister()`.
  48
  49 Entities
  50 ^^^^^^^^
  51
  52 Entities are represented by a struct :c:type:`media_entity`
  53 instance, defined in ``include/media/media-entity.h``. The structure is usually
  54 embedded into a higher-level structure, such as
  55 :c:type:`v4l2_subdev` or :c:type:`video_device`
  56 instances, although drivers can allocate entities directly.
  57
  58 Drivers initialize entity pads by calling
  59 :c:func:`media_entity_pads_init()`.
  60
  61 Drivers register entities with a media device by calling
  62 :c:func:`media_device_register_entity()`
  63 and unregistred by calling
  64 :c:func:`media_device_unregister_entity()`.
  65
  66 Interfaces
  67 ^^^^^^^^^^
  68
  69 Interfaces are represented by a
  70 struct :c:type:`media_interface` instance, defined in
  71 ``include/media/media-entity.h``. Currently, only one type of interface is
  72 defined: a device node. Such interfaces are represented by a
  73 struct :c:type:`media_intf_devnode`.
  74
  75 Drivers initialize and create device node interfaces by calling
  76 :c:func:`media_devnode_create()`
  77 and remove them by calling:
  78 :c:func:`media_devnode_remove()`.
  79
  80 Pads
  81 ^^^^
  82 Pads are represented by a struct :c:type:`media_pad` instance,
  83 defined in ``include/media/media-entity.h``. Each entity stores its pads in
  84 a pads array managed by the entity driver. Drivers usually embed the array in
  85 a driver-specific structure.
  86
  87 Pads are identified by their entity and their 0-based index in the pads
  88 array.
  89
  90 Both information are stored in the struct :c:type:`media_pad`,
  91 making the struct :c:type:`media_pad` pointer the canonical way
  92 to store and pass link references.
  93
  94 Pads have flags that describe the pad capabilities and state.
  95
  96 ``MEDIA_PAD_FL_SINK`` indicates that the pad supports sinking data.
  97 ``MEDIA_PAD_FL_SOURCE`` indicates that the pad supports sourcing data.
  98
  99 .. note::
 100
 101   One and only one of ``MEDIA_PAD_FL_SINK`` or ``MEDIA_PAD_FL_SOURCE`` must
 102   be set for each pad.
 103
 104 Links
 105 ^^^^^
 106
 107 Links are represented by a struct :c:type:`media_link` instance,
 108 defined in ``include/media/media-entity.h``. There are two types of links:
 109
 110 **1. pad to pad links**:
 111
 112 Associate two entities via their PADs. Each entity has a list that points
 113 to all links originating at or targeting any of its pads.
 114 A given link is thus stored twice, once in the source entity and once in
 115 the target entity.
 116
 117 Drivers create pad to pad links by calling:
 118 :c:func:`media_create_pad_link()` and remove with
 119 :c:func:`media_entity_remove_links()`.
 120
 121 **2. interface to entity links**:
 122
 123 Associate one interface to a Link.
 124
 125 Drivers create interface to entity links by calling:
 126 :c:func:`media_create_intf_link()` and remove with
 127 :c:func:`media_remove_intf_links()`.
 128
 129 .. note::
 130
 131    Links can only be created after having both ends already created.
 132
 133 Links have flags that describe the link capabilities and state. The
 134 valid values are described at :c:func:`media_create_pad_link()` and
 135 :c:func:`media_create_intf_link()`.
 136
 137 Graph traversal
 138 ^^^^^^^^^^^^^^^
 139
 140 The media framework provides APIs to iterate over entities in a graph.
 141
 142 To iterate over all entities belonging to a media device, drivers can use
 143 the media_device_for_each_entity macro, defined in
 144 ``include/media/media-device.h``.
 145
 146 ..  code-block:: c
 147
 148     struct media_entity *entity;
 149
 150     media_device_for_each_entity(entity, mdev) {
 151     // entity will point to each entity in turn
 152     ...
 153     }
 154
 155 Drivers might also need to iterate over all entities in a graph that can be
 156 reached only through enabled links starting at a given entity. The media
 157 framework provides a depth-first graph traversal API for that purpose.
 158
 159 .. note::
 160
 161    Graphs with cycles (whether directed or undirected) are **NOT**
 162    supported by the graph traversal API. To prevent infinite loops, the graph
 163    traversal code limits the maximum depth to ``MEDIA_ENTITY_ENUM_MAX_DEPTH``,
 164    currently defined as 16.
 165
 166 Drivers initiate a graph traversal by calling
 167 :c:func:`media_graph_walk_start()`
 168
 169 The graph structure, provided by the caller, is initialized to start graph
 170 traversal at the given entity.
 171
 172 Drivers can then retrieve the next entity by calling
 173 :c:func:`media_graph_walk_next()`
 174
 175 When the graph traversal is complete the function will return ``NULL``.
 176
 177 Graph traversal can be interrupted at any moment. No cleanup function call
 178 is required and the graph structure can be freed normally.
 179
 180 Helper functions can be used to find a link between two given pads, or a pad
 181 connected to another pad through an enabled link
 182 :c:func:`media_entity_find_link()` and
 183 :c:func:`media_entity_remote_pad()`.
 184
 185 Use count and power handling
 186 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 187
 188 Due to the wide differences between drivers regarding power management
 189 needs, the media controller does not implement power management. However,
 190 the struct :c:type:`media_entity` includes a ``use_count``
 191 field that media drivers
 192 can use to track the number of users of every entity for power management
 193 needs.
 194
 195 The :c:type:`media_entity<media_entity>`.\ ``use_count`` field is owned by
 196 media drivers and must not be
 197 touched by entity drivers. Access to the field must be protected by the
 198 :c:type:`media_device`.\ ``graph_mutex`` lock.
 199
 200 Links setup
 201 ^^^^^^^^^^^
 202
 203 Link properties can be modified at runtime by calling
 204 :c:func:`media_entity_setup_link()`.
 205
 206 Pipelines and media streams
 207 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 208
 209 When starting streaming, drivers must notify all entities in the pipeline to
 210 prevent link states from being modified during streaming by calling
 211 :c:func:`media_pipeline_start()`.
 212
 213 The function will mark all entities connected to the given entity through
 214 enabled links, either directly or indirectly, as streaming.
 215
 216 The struct :c:type:`media_pipeline` instance pointed to by
 217 the pipe argument will be stored in every entity in the pipeline.
 218 Drivers should embed the struct :c:type:`media_pipeline`
 219 in higher-level pipeline structures and can then access the
 220 pipeline through the struct :c:type:`media_entity`
 221 pipe field.
 222
 223 Calls to :c:func:`media_pipeline_start()` can be nested.
 224 The pipeline pointer must be identical for all nested calls to the function.
 225
 226 :c:func:`media_pipeline_start()` may return an error. In that case,
 227 it will clean up any of the changes it did by itself.
 228
 229 When stopping the stream, drivers must notify the entities with
 230 :c:func:`media_pipeline_stop()`.
 231
 232 If multiple calls to :c:func:`media_pipeline_start()` have been
 233 made the same number of :c:func:`media_pipeline_stop()` calls
 234 are required to stop streaming.
 235 The :c:type:`media_entity`.\ ``pipe`` field is reset to ``NULL`` on the last
 236 nested stop call.
 237
 238 Link configuration will fail with ``-EBUSY`` by default if either end of the
 239 link is a streaming entity. Links that can be modified while streaming must
 240 be marked with the ``MEDIA_LNK_FL_DYNAMIC`` flag.
 241
 242 If other operations need to be disallowed on streaming entities (such as
 243 changing entities configuration parameters) drivers can explicitly check the
 244 media_entity stream_count field to find out if an entity is streaming. This
 245 operation must be done with the media_device graph_mutex held.
 246
 247 Link validation
 248 ^^^^^^^^^^^^^^^
 249
 250 Link validation is performed by :c:func:`media_pipeline_start()`
 251 for any entity which has sink pads in the pipeline. The
 252 :c:type:`media_entity`.\ ``link_validate()`` callback is used for that
 253 purpose. In ``link_validate()`` callback, entity driver should check
 254 that the properties of the source pad of the connected entity and its own
 255 sink pad match. It is up to the type of the entity (and in the end, the
 256 properties of the hardware) what matching actually means.
 257
 258 Subsystems should facilitate link validation by providing subsystem specific
 259 helper functions to provide easy access for commonly needed information, and
 260 in the end provide a way to use driver-specific callbacks.
 261
 262 .. kernel-doc:: include/media/media-device.h
 263
 264 .. kernel-doc:: include/media/media-devnode.h
 265
 266 .. kernel-doc:: include/media/media-entity.h
 267
 268 .. kernel-doc:: include/media/media-request.h