driver-api/media/mc-core.rst

3 Media Controller devices
6 Media Controller
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.
13 Abstract media device model
17 of the goals of the media framework. To achieve this, hardware devices are
21 An entity is a basic media hardware building block. It can correspond to
36 Media device
39 A media device is represented by a struct 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
45 Drivers initialise media device instances by calling
46 :c:func:`media_device_init()`. After initialising a media device instance, it is
49 :c:func:`media_device_unregister()`. An initialised media device must be
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
60 instance, defined in ``include/media/media-entity.h``. The structure is usually
68 Drivers register entities with a media device by calling
78 ``include/media/media-entity.h``. Currently, only one type of interface is
90 defined in ``include/media/media-entity.h``. Each entity stores its pads in
115 defined in ``include/media/media-entity.h``. There are two types of links:
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``.
163 reached only through enabled links starting at a given entity. The media
197 needs, the media controller does not implement power management. However,
199 field that media drivers
204 media drivers and must not be
214 Pipelines and media streams
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
226 due to the software design. Most commonly a media pipeline consists of a single
279 Media Controller Device Allocator API
282 When the media device belongs to more than one driver, the shared media
285 The shared media device should stay in registered state until the last
286 driver unregisters it. In addition, the media device should be released when
287 all the references are released. Each driver gets a reference to the media
288 device during probe, when it allocates the media device. If media device is
290 existing media device. The driver puts the reference back in its disconnect
293 The media device is unregistered and cleaned up from the kref put handler to
294 ensure that the media device stays in registered state until the last driver
295 unregisters the media device.
299 Drivers should use the appropriate media-core routines to manage the shared
300 media device life-time handling the two states:
304 call :c:func:`media_device_delete()` routine to make sure the shared media
309 Call :c:func:`media_device_register()`, if media devnode isn't registered
318 .. kernel-doc:: include/media/media-device.h
320 .. kernel-doc:: include/media/media-devnode.h
322 .. kernel-doc:: include/media/media-entity.h
324 .. kernel-doc:: include/media/media-request.h
326 .. kernel-doc:: include/media/media-dev-allocator.h