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()`.
150 To iterate over all entities belonging to a media device, drivers can use
152 ``include/media/media-device.h``.
154 ..  code-block:: c
163 Helper functions can be used to find a link between two given pads, or a pad
165 (:c:func:`media_entity_find_link()`, :c:func:`media_pad_remote_pad_first()`,
166 :c:func:`media_entity_remote_source_pad_unique()` and
167 :c:func:`media_pad_remote_pad_unique()`).
174 the struct media_entity includes a ``use_count``
179 The :c:type:`media_entity<media_entity>`.\ ``use_count`` field is owned by
182 :c:type:`media_device`.\ ``graph_mutex`` lock.
188 :c:func:`media_entity_setup_link()`.
193 A media stream is a stream of pixels or metadata originating from one or more
194 source devices (such as a sensors) and flowing through media entity pads
199 A media pipeline is a set of media streams which are interdependent. This
200 interdependency can be caused by the hardware (e.g. configuration of a second
202 due to the software design. Most commonly a media pipeline consists of a single
207 :c:func:`media_pipeline_start()`.
213 media_pipeline in higher-level pipeline structures and can then access the
216 Calls to :c:func:`media_pipeline_start()` can be nested.
219 :c:func:`media_pipeline_start()` may return an error. In that case,
223 :c:func:`media_pipeline_stop()`.
225 If multiple calls to :c:func:`media_pipeline_start()` have been
226 made the same number of :c:func:`media_pipeline_stop()` calls
228 The :c:type:`media_entity`.\ ``pipe`` field is reset to ``NULL`` on the last
231 Link configuration will fail with ``-EBUSY`` by default if either end of the
232 link is a streaming entity. Links that can be modified while streaming must
243 Link validation is performed by :c:func:`media_pipeline_start()`
245 :c:type:`media_entity`.\ ``link_validate()`` callback is used for that
253 in the end provide a way to use driver-specific callbacks.
258 Once a pipeline has been constructed with :c:func:`media_pipeline_start()`,
260 :c:macro:´media_pipeline_for_each_entity` and
261 :c:macro:´media_pipeline_for_each_pad` macros. Iterating over pads is
264 .. code-block:: c
277 .. code-block:: c
302 all the references are released. Each driver gets a reference to the media
306 routine when it calls :c:func:`media_device_delete()`.
314 Drivers should use the appropriate media-core routines to manage the shared
315 media device life-time handling the two states:
316 1. allocate -> register -> delete
317 2. get reference to already registered device -> delete
319 call :c:func:`media_device_delete()` routine to make sure the shared media
323 Call :c:func:`media_device_usb_allocate()` to allocate or get a reference
324 Call :c:func:`media_device_register()`, if media devnode isn't registered
327 Call :c:func:`media_device_delete()` to free the media_device. Freeing is
333 .. kernel-doc:: include/media/media-device.h
335 .. kernel-doc:: include/media/media-devnode.h
337 .. kernel-doc:: include/media/media-entity.h
339 .. kernel-doc:: include/media/media-request.h
341 .. kernel-doc:: include/media/media-dev-allocator.h