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 traverse media graphs, locating connected
150 To iterate over all entities belonging to a media device, drivers can use
152 ``include/media/media-device.h``.
173 needs, the media controller does not implement power management. However,
175 field that media drivers
180 media drivers and must not be
190 Pipelines and media streams
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
202 due to the software design. Most commonly a media pipeline consists of a single
294 Media Controller Device Allocator API
297 When the media device belongs to more than one driver, the shared media
300 The shared media device should stay in registered state until the last
301 driver unregisters it. In addition, the media device should be released when
302 all the references are released. Each driver gets a reference to the media
303 device during probe, when it allocates the media device. If media device is
305 existing media device. The driver puts the reference back in its disconnect
308 The media device is unregistered and cleaned up from the kref put handler to
309 ensure that the media device stays in registered state until the last driver
310 unregisters the media device.
314 Drivers should use the appropriate media-core routines to manage the shared
315 media device life-time handling the two states:
319 call :c:func:`media_device_delete()` routine to make sure the shared media
324 Call :c:func:`media_device_register()`, if media devnode isn't registered
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