Lines Matching +full:a +full:- +full:c

1 .. SPDX-License-Identifier: GPL-2.0
4 ------------------------
11 on the kernel-side implementation of the media framework.
16 Discovering a device internal topology, and configuring it at runtime, is one
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
27 A pad is a connection endpoint through which an entity can interact with
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.
39 A media device is represented by a struct media_device
40 instance, defined in ``include/media/media-device.h``.
42 embedding the :c:type:`media_device` instance in a larger driver-specific
46 :c:func:`media_device_init()`. After initialising a media device instance, it is
47 registered by calling :c:func:`__media_device_register()` via the macro
49 :c:func:`media_device_unregister()`. An initialised media device must be
50 eventually cleaned up by calling :c:func:`media_device_cleanup()`.
52 Note that it is not allowed to unregister a media device instance that was not
53 previously registered, or clean up a media device instance that was not
59 Entities are represented by a struct media_entity
60 instance, defined in ``include/media/media-entity.h``. The structure is usually
61 embedded into a higher-level structure, such as
62 :c:type:`v4l2_subdev` or :c:type:`video_device`
66 :c:func:`media_entity_pads_init()`.
68 Drivers register entities with a media device by calling
69 :c:func:`media_device_register_entity()`
71 :c:func:`media_device_unregister_entity()`.
76 Interfaces are represented by a
78 ``include/media/media-entity.h``. Currently, only one type of interface is
79 defined: a device node. Such interfaces are represented by a
83 :c:func:`media_devnode_create()`
85 :c:func:`media_devnode_remove()`.
89 Pads are represented by a struct media_pad instance,
90 defined in ``include/media/media-entity.h``. Each entity stores its pads in
91 a pads array managed by the entity driver. Drivers usually embed the array in
92 a driver-specific structure.
94 Pads are identified by their entity and their 0-based index in the pads
114 Links are represented by a struct media_link instance,
115 defined in ``include/media/media-entity.h``. There are two types of links:
119 Associate two entities via their PADs. Each entity has a list that points
121 A given link is thus stored twice, once in the source entity and once in
125 :c:func:`media_create_pad_link()` and remove with
126 :c:func:`media_entity_remove_links()`.
130 Associate one interface to a Link.
133 :c:func:`media_create_intf_link()` and remove with
134 :c:func:`media_remove_intf_links()`.
141 valid values are described at :c:func:`media_create_pad_link()` and
142 :c:func:`media_create_intf_link()`.
147 The media framework provides APIs to iterate over entities in a graph.
149 To iterate over all entities belonging to a media device, drivers can use
151 ``include/media/media-device.h``.
153 ..  code-block:: c
162 Drivers might also need to iterate over all entities in a graph that can be
163 reached only through enabled links starting at a given entity. The media
164 framework provides a depth-first graph traversal API for that purpose.
173 Drivers initiate a graph traversal by calling
174 :c:func:`media_graph_walk_start()`
180 :c:func:`media_graph_walk_next()`
187 Helper functions can be used to find a link between two given pads, or a pad
189 (:c:func:`media_entity_find_link()`, :c:func:`media_pad_remote_pad_first()`,
190 :c:func:`media_entity_remote_source_pad_unique()` and
191 :c:func:`media_pad_remote_pad_unique()`).
198 the struct media_entity includes a ``use_count``
203 The :c:type:`media_entity<media_entity>`.\ ``use_count`` field is owned by
206 :c:type:`media_device`.\ ``graph_mutex`` lock.
212 :c:func:`media_entity_setup_link()`.
217 A media stream is a stream of pixels or metadata originating from one or more
218 source devices (such as a sensors) and flowing through media entity pads
223 A media pipeline is a set of media streams which are interdependent. This
224 interdependency can be caused by the hardware (e.g. configuration of a second
226 due to the software design. Most commonly a media pipeline consists of a single
231 :c:func:`media_pipeline_start()`.
238 in higher-level pipeline structures and can then access the
242 Calls to :c:func:`media_pipeline_start()` can be nested.
245 :c:func:`media_pipeline_start()` may return an error. In that case,
249 :c:func:`media_pipeline_stop()`.
251 If multiple calls to :c:func:`media_pipeline_start()` have been
252 made the same number of :c:func:`media_pipeline_stop()` calls
254 The :c:type:`media_entity`.\ ``pipe`` field is reset to ``NULL`` on the last
257 Link configuration will fail with ``-EBUSY`` by default if either end of the
258 link is a streaming entity. Links that can be modified while streaming must
269 Link validation is performed by :c:func:`media_pipeline_start()`
271 :c:type:`media_entity`.\ ``link_validate()`` callback is used for that
279 in the end provide a way to use driver-specific callbacks.
289 all the references are released. Each driver gets a reference to the media
293 routine when it calls :c:func:`media_device_delete()`.
301 Drivers should use the appropriate media-core routines to manage the shared
302 media device life-time handling the two states:
303 1. allocate -> register -> delete
304 2. get reference to already registered device -> delete
306 call :c:func:`media_device_delete()` routine to make sure the shared media
310 Call :c:func:`media_device_usb_allocate()` to allocate or get a reference
311 Call :c:func:`media_device_register()`, if media devnode isn't registered
314 Call :c:func:`media_device_delete()` to free the media_device. Freeing is
320 .. kernel-doc:: include/media/media-device.h
322 .. kernel-doc:: include/media/media-devnode.h
324 .. kernel-doc:: include/media/media-entity.h
326 .. kernel-doc:: include/media/media-request.h
328 .. kernel-doc:: include/media/media-dev-allocator.h