[media] doc-rst: Convert media API to rst
Move the contents of the media section at DocBooks/DocBook/device-drivers.tmpl to a new ReST book. For now, the contents is kept as-is. Next patches will fix the warnings and add cross-references that were removed due to the conversion. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
This commit is contained in:
Mauro Carvalho Chehab
parent
520a247760
commit
d26a5d4350
@ -219,64 +219,6 @@ X!Isound/sound_firmware.c
|
|||||||
-->
|
-->
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
<chapter id="mediadev">
|
|
||||||
<title>Media Devices</title>
|
|
||||||
|
|
||||||
<sect1><title>Video2Linux devices</title>
|
|
||||||
!Iinclude/media/tuner.h
|
|
||||||
!Iinclude/media/tuner-types.h
|
|
||||||
!Iinclude/media/tveeprom.h
|
|
||||||
!Iinclude/media/v4l2-async.h
|
|
||||||
!Iinclude/media/v4l2-ctrls.h
|
|
||||||
!Iinclude/media/v4l2-dv-timings.h
|
|
||||||
!Iinclude/media/v4l2-event.h
|
|
||||||
!Iinclude/media/v4l2-flash-led-class.h
|
|
||||||
!Iinclude/media/v4l2-mc.h
|
|
||||||
!Iinclude/media/v4l2-mediabus.h
|
|
||||||
!Iinclude/media/v4l2-mem2mem.h
|
|
||||||
!Iinclude/media/v4l2-of.h
|
|
||||||
!Iinclude/media/v4l2-rect.h
|
|
||||||
!Iinclude/media/v4l2-subdev.h
|
|
||||||
!Iinclude/media/videobuf2-core.h
|
|
||||||
!Iinclude/media/videobuf2-v4l2.h
|
|
||||||
!Iinclude/media/videobuf2-memops.h
|
|
||||||
</sect1>
|
|
||||||
<sect1><title>Digital TV (DVB) devices</title>
|
|
||||||
<sect1><title>Digital TV Common functions</title>
|
|
||||||
!Idrivers/media/dvb-core/dvb_math.h
|
|
||||||
!Idrivers/media/dvb-core/dvb_ringbuffer.h
|
|
||||||
!Idrivers/media/dvb-core/dvbdev.h
|
|
||||||
</sect1>
|
|
||||||
<sect1><title>Digital TV Frontend kABI</title>
|
|
||||||
!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend
|
|
||||||
!Idrivers/media/dvb-core/dvb_frontend.h
|
|
||||||
</sect1>
|
|
||||||
<sect1><title>Digital TV Demux kABI</title>
|
|
||||||
!Pdrivers/media/dvb-core/demux.h Digital TV Demux
|
|
||||||
<sect1><title>Demux Callback API</title>
|
|
||||||
!Pdrivers/media/dvb-core/demux.h Demux Callback
|
|
||||||
</sect1>
|
|
||||||
!Idrivers/media/dvb-core/demux.h
|
|
||||||
</sect1>
|
|
||||||
<sect1><title>Digital TV Conditional Access kABI</title>
|
|
||||||
!Idrivers/media/dvb-core/dvb_ca_en50221.h
|
|
||||||
</sect1>
|
|
||||||
</sect1>
|
|
||||||
<sect1><title>Remote Controller devices</title>
|
|
||||||
!Iinclude/media/rc-core.h
|
|
||||||
!Iinclude/media/lirc_dev.h
|
|
||||||
</sect1>
|
|
||||||
<sect1><title>Media Controller devices</title>
|
|
||||||
!Pinclude/media/media-device.h Media Controller
|
|
||||||
!Iinclude/media/media-device.h
|
|
||||||
!Iinclude/media/media-devnode.h
|
|
||||||
!Iinclude/media/media-entity.h
|
|
||||||
</sect1>
|
|
||||||
<sect1><title>Consumer Electronics Control devices</title>
|
|
||||||
!Iinclude/media/cec-edid.h
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
</chapter>
|
|
||||||
|
|
||||||
<chapter id="uart16x50">
|
<chapter id="uart16x50">
|
||||||
<title>16x50 UART Driver</title>
|
<title>16x50 UART Driver</title>
|
||||||
|
|||||||
@ -15,6 +15,7 @@ Contents:
|
|||||||
|
|
||||||
kernel-documentation
|
kernel-documentation
|
||||||
media/media_uapi
|
media/media_uapi
|
||||||
|
media/media_drivers
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|||||||
414
Documentation/media/media_drivers.rst
Normal file
414
Documentation/media/media_drivers.rst
Normal file
@ -0,0 +1,414 @@
|
|||||||
|
==========
|
||||||
|
Media core
|
||||||
|
==========
|
||||||
|
|
||||||
|
Video2Linux devices
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/tuner.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/tuner-types.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/tveeprom.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-async.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-ctrls.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-dv-timings.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-event.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-flash-led-class.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-mc.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-mediabus.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-mem2mem.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-of.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-rect.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/v4l2-subdev.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/videobuf2-core.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/videobuf2-v4l2.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/videobuf2-memops.h
|
||||||
|
|
||||||
|
|
||||||
|
Digital TV (DVB) devices
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Digital TV Common functions
|
||||||
|
---------------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/media/dvb-core/dvb_math.h
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
|
||||||
|
|
||||||
|
|
||||||
|
Digital TV Frontend kABI
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Digital TV Frontend
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The Digital TV Frontend kABI defines a driver-internal interface for
|
||||||
|
registering low-level, hardware specific driver to a hardware independent
|
||||||
|
frontend layer. It is only of interest for Digital TV device driver writers.
|
||||||
|
The header file for this API is named dvb_frontend.h and located in
|
||||||
|
drivers/media/dvb-core.
|
||||||
|
|
||||||
|
Before using the Digital TV frontend core, the bridge driver should attach
|
||||||
|
the frontend demod, tuner and SEC devices and call dvb_register_frontend(),
|
||||||
|
in order to register the new frontend at the subsystem. At device
|
||||||
|
detach/removal, the bridge driver should call dvb_unregister_frontend() to
|
||||||
|
remove the frontend from the core and then dvb_frontend_detach() to free the
|
||||||
|
memory allocated by the frontend drivers.
|
||||||
|
|
||||||
|
The drivers should also call dvb_frontend_suspend() as part of their
|
||||||
|
handler for the &device_driver.suspend(), and dvb_frontend_resume() as
|
||||||
|
part of their handler for &device_driver.resume().
|
||||||
|
|
||||||
|
few other optional functions are provided to handle some special cases.
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
|
||||||
|
|
||||||
|
|
||||||
|
Digital TV Demux kABI
|
||||||
|
---------------------
|
||||||
|
|
||||||
|
Digital TV Demux
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The Kernel Digital TV Demux kABI defines a driver-internal interface for
|
||||||
|
registering low-level, hardware specific driver to a hardware independent
|
||||||
|
demux layer. It is only of interest for Digital TV device driver writers.
|
||||||
|
The header file for this kABI is named demux.h and located in
|
||||||
|
drivers/media/dvb-core.
|
||||||
|
|
||||||
|
The demux kABI should be implemented for each demux in the system. It is
|
||||||
|
used to select the TS source of a demux and to manage the demux resources.
|
||||||
|
When the demux client allocates a resource via the demux kABI, it receives
|
||||||
|
a pointer to the kABI of that resource.
|
||||||
|
|
||||||
|
Each demux receives its TS input from a DVB front-end or from memory, as
|
||||||
|
set via this demux kABI. In a system with more than one front-end, the kABI
|
||||||
|
can be used to select one of the DVB front-ends as a TS source for a demux,
|
||||||
|
unless this is fixed in the HW platform.
|
||||||
|
|
||||||
|
The demux kABI only controls front-ends regarding to their connections with
|
||||||
|
demuxes; the kABI used to set the other front-end parameters, such as
|
||||||
|
tuning, are devined via the Digital TV Frontend kABI.
|
||||||
|
|
||||||
|
The functions that implement the abstract interface demux should be defined
|
||||||
|
static or module private and registered to the Demux core for external
|
||||||
|
access. It is not necessary to implement every function in the struct
|
||||||
|
&dmx_demux. For example, a demux interface might support Section filtering,
|
||||||
|
but not PES filtering. The kABI client is expected to check the value of any
|
||||||
|
function pointer before calling the function: the value of NULL means
|
||||||
|
that the function is not available.
|
||||||
|
|
||||||
|
Whenever the functions of the demux API modify shared data, the
|
||||||
|
possibilities of lost update and race condition problems should be
|
||||||
|
addressed, e.g. by protecting parts of code with mutexes.
|
||||||
|
|
||||||
|
Note that functions called from a bottom half context must not sleep.
|
||||||
|
Even a simple memory allocation without using %GFP_ATOMIC can result in a
|
||||||
|
kernel thread being put to sleep if swapping is needed. For example, the
|
||||||
|
Linux Kernel calls the functions of a network device interface from a
|
||||||
|
bottom half context. Thus, if a demux kABI function is called from network
|
||||||
|
device code, the function must not sleep.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Demux Callback API
|
||||||
|
------------------
|
||||||
|
|
||||||
|
Demux Callback
|
||||||
|
~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This kernel-space API comprises the callback functions that deliver filtered
|
||||||
|
data to the demux client. Unlike the other DVB kABIs, these functions are
|
||||||
|
provided by the client and called from the demux code.
|
||||||
|
|
||||||
|
The function pointers of this abstract interface are not packed into a
|
||||||
|
structure as in the other demux APIs, because the callback functions are
|
||||||
|
registered and used independent of each other. As an example, it is possible
|
||||||
|
for the API client to provide several callback functions for receiving TS
|
||||||
|
packets and no callbacks for PES packets or sections.
|
||||||
|
|
||||||
|
The functions that implement the callback API need not be re-entrant: when
|
||||||
|
a demux driver calls one of these functions, the driver is not allowed to
|
||||||
|
call the function again before the original call returns. If a callback is
|
||||||
|
triggered by a hardware interrupt, it is recommended to use the Linux
|
||||||
|
bottom half mechanism or start a tasklet instead of making the callback
|
||||||
|
function call directly from a hardware interrupt.
|
||||||
|
|
||||||
|
This mechanism is implemented by dmx_ts_cb() and dmx_section_cb()
|
||||||
|
callbacks.
|
||||||
|
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/media/dvb-core/demux.h
|
||||||
|
|
||||||
|
|
||||||
|
Digital TV Conditional Access kABI
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h
|
||||||
|
|
||||||
|
|
||||||
|
Remote Controller devices
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/rc-core.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/lirc_dev.h
|
||||||
|
|
||||||
|
|
||||||
|
Media Controller devices
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Media Controller
|
||||||
|
~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
|
||||||
|
The media controller userspace API is documented in DocBook format in
|
||||||
|
Documentation/DocBook/media/v4l/media-controller.xml. This document focus
|
||||||
|
on the kernel-side implementation of the media framework.
|
||||||
|
|
||||||
|
* Abstract media device model:
|
||||||
|
|
||||||
|
Discovering a device internal topology, and configuring it at runtime, is one
|
||||||
|
of the goals of the media framework. To achieve this, hardware devices are
|
||||||
|
modelled as an oriented graph of building blocks called entities connected
|
||||||
|
through pads.
|
||||||
|
|
||||||
|
An entity is a basic media hardware building block. It can correspond to
|
||||||
|
a large variety of logical blocks such as physical hardware devices
|
||||||
|
(CMOS sensor for instance), logical hardware devices (a building block
|
||||||
|
in a System-on-Chip image processing pipeline), DMA channels or physical
|
||||||
|
connectors.
|
||||||
|
|
||||||
|
A pad is a connection endpoint through which an entity can interact with
|
||||||
|
other entities. Data (not restricted to video) produced by an entity
|
||||||
|
flows from the entity's output to one or more entity inputs. Pads should
|
||||||
|
not be confused with physical pins at chip boundaries.
|
||||||
|
|
||||||
|
A link is a point-to-point oriented connection between two pads, either
|
||||||
|
on the same entity or on different entities. Data flows from a source
|
||||||
|
pad to a sink pad.
|
||||||
|
|
||||||
|
|
||||||
|
* Media device:
|
||||||
|
|
||||||
|
A media device is represented by a struct &media_device instance, defined in
|
||||||
|
include/media/media-device.h. Allocation of the structure is handled by the
|
||||||
|
media device driver, usually by embedding the &media_device instance in a
|
||||||
|
larger driver-specific structure.
|
||||||
|
|
||||||
|
Drivers register media device instances by calling
|
||||||
|
__media_device_register() via the macro media_device_register()
|
||||||
|
and unregistered by calling
|
||||||
|
media_device_unregister().
|
||||||
|
|
||||||
|
* Entities, pads and links:
|
||||||
|
|
||||||
|
- Entities
|
||||||
|
|
||||||
|
Entities are represented by a struct &media_entity instance, defined in
|
||||||
|
include/media/media-entity.h. The structure is usually embedded into a
|
||||||
|
higher-level structure, such as a v4l2_subdev or video_device instance,
|
||||||
|
although drivers can allocate entities directly.
|
||||||
|
|
||||||
|
Drivers initialize entity pads by calling
|
||||||
|
media_entity_pads_init().
|
||||||
|
|
||||||
|
Drivers register entities with a media device by calling
|
||||||
|
media_device_register_entity()
|
||||||
|
and unregistred by calling
|
||||||
|
media_device_unregister_entity().
|
||||||
|
|
||||||
|
- Interfaces
|
||||||
|
|
||||||
|
Interfaces are represented by a struct &media_interface instance, defined in
|
||||||
|
include/media/media-entity.h. Currently, only one type of interface is
|
||||||
|
defined: a device node. Such interfaces are represented by a struct
|
||||||
|
&media_intf_devnode.
|
||||||
|
|
||||||
|
Drivers initialize and create device node interfaces by calling
|
||||||
|
media_devnode_create()
|
||||||
|
and remove them by calling:
|
||||||
|
media_devnode_remove().
|
||||||
|
|
||||||
|
- Pads
|
||||||
|
|
||||||
|
Pads are represented by a struct &media_pad instance, defined in
|
||||||
|
include/media/media-entity.h. Each entity stores its pads in a pads array
|
||||||
|
managed by the entity driver. Drivers usually embed the array in a
|
||||||
|
driver-specific structure.
|
||||||
|
|
||||||
|
Pads are identified by their entity and their 0-based index in the pads
|
||||||
|
array.
|
||||||
|
Both information are stored in the &media_pad structure, making the
|
||||||
|
&media_pad pointer the canonical way to store and pass link references.
|
||||||
|
|
||||||
|
Pads have flags that describe the pad capabilities and state.
|
||||||
|
|
||||||
|
%MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
|
||||||
|
%MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
|
||||||
|
|
||||||
|
NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
|
||||||
|
be set for each pad.
|
||||||
|
|
||||||
|
- Links
|
||||||
|
|
||||||
|
Links are represented by a struct &media_link instance, defined in
|
||||||
|
include/media/media-entity.h. There are two types of links:
|
||||||
|
|
||||||
|
1. pad to pad links:
|
||||||
|
|
||||||
|
Associate two entities via their PADs. Each entity has a list that points
|
||||||
|
to all links originating at or targeting any of its pads.
|
||||||
|
A given link is thus stored twice, once in the source entity and once in
|
||||||
|
the target entity.
|
||||||
|
|
||||||
|
Drivers create pad to pad links by calling:
|
||||||
|
media_create_pad_link() and remove with media_entity_remove_links().
|
||||||
|
|
||||||
|
2. interface to entity links:
|
||||||
|
|
||||||
|
Associate one interface to a Link.
|
||||||
|
|
||||||
|
Drivers create interface to entity links by calling:
|
||||||
|
media_create_intf_link() and remove with media_remove_intf_links().
|
||||||
|
|
||||||
|
NOTE:
|
||||||
|
|
||||||
|
Links can only be created after having both ends already created.
|
||||||
|
|
||||||
|
Links have flags that describe the link capabilities and state. The
|
||||||
|
valid values are described at media_create_pad_link() and
|
||||||
|
media_create_intf_link().
|
||||||
|
|
||||||
|
Graph traversal:
|
||||||
|
|
||||||
|
The media framework provides APIs to iterate over entities in a graph.
|
||||||
|
|
||||||
|
To iterate over all entities belonging to a media device, drivers can use
|
||||||
|
the media_device_for_each_entity macro, defined in
|
||||||
|
include/media/media-device.h.
|
||||||
|
|
||||||
|
struct media_entity *entity;
|
||||||
|
|
||||||
|
media_device_for_each_entity(entity, mdev) {
|
||||||
|
// entity will point to each entity in turn
|
||||||
|
...
|
||||||
|
}
|
||||||
|
|
||||||
|
Drivers might also need to iterate over all entities in a graph that can be
|
||||||
|
reached only through enabled links starting at a given entity. The media
|
||||||
|
framework provides a depth-first graph traversal API for that purpose.
|
||||||
|
|
||||||
|
Note that graphs with cycles (whether directed or undirected) are *NOT*
|
||||||
|
supported by the graph traversal API. To prevent infinite loops, the graph
|
||||||
|
traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
|
||||||
|
currently defined as 16.
|
||||||
|
|
||||||
|
Drivers initiate a graph traversal by calling
|
||||||
|
media_entity_graph_walk_start()
|
||||||
|
|
||||||
|
The graph structure, provided by the caller, is initialized to start graph
|
||||||
|
traversal at the given entity.
|
||||||
|
|
||||||
|
Drivers can then retrieve the next entity by calling
|
||||||
|
media_entity_graph_walk_next()
|
||||||
|
|
||||||
|
When the graph traversal is complete the function will return NULL.
|
||||||
|
|
||||||
|
Graph traversal can be interrupted at any moment. No cleanup function call
|
||||||
|
is required and the graph structure can be freed normally.
|
||||||
|
|
||||||
|
Helper functions can be used to find a link between two given pads, or a pad
|
||||||
|
connected to another pad through an enabled link
|
||||||
|
media_entity_find_link() and media_entity_remote_pad()
|
||||||
|
|
||||||
|
Use count and power handling:
|
||||||
|
|
||||||
|
Due to the wide differences between drivers regarding power management
|
||||||
|
needs, the media controller does not implement power management. However,
|
||||||
|
the &media_entity structure includes a use_count field that media drivers
|
||||||
|
can use to track the number of users of every entity for power management
|
||||||
|
needs.
|
||||||
|
|
||||||
|
The &media_entity.@use_count field is owned by media drivers and must not be
|
||||||
|
touched by entity drivers. Access to the field must be protected by the
|
||||||
|
&media_device.@graph_mutex lock.
|
||||||
|
|
||||||
|
Links setup:
|
||||||
|
|
||||||
|
Link properties can be modified at runtime by calling
|
||||||
|
media_entity_setup_link()
|
||||||
|
|
||||||
|
Pipelines and media streams:
|
||||||
|
|
||||||
|
When starting streaming, drivers must notify all entities in the pipeline to
|
||||||
|
prevent link states from being modified during streaming by calling
|
||||||
|
media_entity_pipeline_start().
|
||||||
|
|
||||||
|
The function will mark all entities connected to the given entity through
|
||||||
|
enabled links, either directly or indirectly, as streaming.
|
||||||
|
|
||||||
|
The &media_pipeline instance pointed to by the pipe argument will be stored
|
||||||
|
in every entity in the pipeline. Drivers should embed the &media_pipeline
|
||||||
|
structure in higher-level pipeline structures and can then access the
|
||||||
|
pipeline through the &media_entity pipe field.
|
||||||
|
|
||||||
|
Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
|
||||||
|
must be identical for all nested calls to the function.
|
||||||
|
|
||||||
|
media_entity_pipeline_start() may return an error. In that case, it will
|
||||||
|
clean up any of the changes it did by itself.
|
||||||
|
|
||||||
|
When stopping the stream, drivers must notify the entities with
|
||||||
|
media_entity_pipeline_stop().
|
||||||
|
|
||||||
|
If multiple calls to media_entity_pipeline_start() have been made the same
|
||||||
|
number of media_entity_pipeline_stop() calls are required to stop streaming.
|
||||||
|
The &media_entity pipe field is reset to NULL on the last nested stop call.
|
||||||
|
|
||||||
|
Link configuration will fail with -%EBUSY by default if either end of the
|
||||||
|
link is a streaming entity. Links that can be modified while streaming must
|
||||||
|
be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
|
||||||
|
|
||||||
|
If other operations need to be disallowed on streaming entities (such as
|
||||||
|
changing entities configuration parameters) drivers can explicitly check the
|
||||||
|
media_entity stream_count field to find out if an entity is streaming. This
|
||||||
|
operation must be done with the media_device graph_mutex held.
|
||||||
|
|
||||||
|
Link validation:
|
||||||
|
|
||||||
|
Link validation is performed by media_entity_pipeline_start() for any
|
||||||
|
entity which has sink pads in the pipeline. The
|
||||||
|
&media_entity.@link_validate() callback is used for that purpose. In
|
||||||
|
@link_validate() callback, entity driver should check that the properties of
|
||||||
|
the source pad of the connected entity and its own sink pad match. It is up
|
||||||
|
to the type of the entity (and in the end, the properties of the hardware)
|
||||||
|
what matching actually means.
|
||||||
|
|
||||||
|
Subsystems should facilitate link validation by providing subsystem specific
|
||||||
|
helper functions to provide easy access for commonly needed information, and
|
||||||
|
in the end provide a way to use driver-specific callbacks.
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/media-device.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/media-devnode.h
|
||||||
|
|
||||||
|
.. kernel-doc:: include/media/media-entity.h
|
||||||
|
|
||||||
@ -1,6 +1,10 @@
|
|||||||
/*
|
/*
|
||||||
* demux.h
|
* demux.h
|
||||||
*
|
*
|
||||||
|
* The Kernel Digital TV Demux kABI defines a driver-internal interface for
|
||||||
|
* registering low-level, hardware specific driver to a hardware independent
|
||||||
|
* demux layer.
|
||||||
|
*
|
||||||
* Copyright (c) 2002 Convergence GmbH
|
* Copyright (c) 2002 Convergence GmbH
|
||||||
*
|
*
|
||||||
* based on code:
|
* based on code:
|
||||||
@ -32,49 +36,6 @@
|
|||||||
#include <linux/time.h>
|
#include <linux/time.h>
|
||||||
#include <linux/dvb/dmx.h>
|
#include <linux/dvb/dmx.h>
|
||||||
|
|
||||||
/**
|
|
||||||
* DOC: Digital TV Demux
|
|
||||||
*
|
|
||||||
* The Kernel Digital TV Demux kABI defines a driver-internal interface for
|
|
||||||
* registering low-level, hardware specific driver to a hardware independent
|
|
||||||
* demux layer. It is only of interest for Digital TV device driver writers.
|
|
||||||
* The header file for this kABI is named demux.h and located in
|
|
||||||
* drivers/media/dvb-core.
|
|
||||||
*
|
|
||||||
* The demux kABI should be implemented for each demux in the system. It is
|
|
||||||
* used to select the TS source of a demux and to manage the demux resources.
|
|
||||||
* When the demux client allocates a resource via the demux kABI, it receives
|
|
||||||
* a pointer to the kABI of that resource.
|
|
||||||
*
|
|
||||||
* Each demux receives its TS input from a DVB front-end or from memory, as
|
|
||||||
* set via this demux kABI. In a system with more than one front-end, the kABI
|
|
||||||
* can be used to select one of the DVB front-ends as a TS source for a demux,
|
|
||||||
* unless this is fixed in the HW platform.
|
|
||||||
*
|
|
||||||
* The demux kABI only controls front-ends regarding to their connections with
|
|
||||||
* demuxes; the kABI used to set the other front-end parameters, such as
|
|
||||||
* tuning, are devined via the Digital TV Frontend kABI.
|
|
||||||
*
|
|
||||||
* The functions that implement the abstract interface demux should be defined
|
|
||||||
* static or module private and registered to the Demux core for external
|
|
||||||
* access. It is not necessary to implement every function in the struct
|
|
||||||
* &dmx_demux. For example, a demux interface might support Section filtering,
|
|
||||||
* but not PES filtering. The kABI client is expected to check the value of any
|
|
||||||
* function pointer before calling the function: the value of NULL means
|
|
||||||
* that the function is not available.
|
|
||||||
*
|
|
||||||
* Whenever the functions of the demux API modify shared data, the
|
|
||||||
* possibilities of lost update and race condition problems should be
|
|
||||||
* addressed, e.g. by protecting parts of code with mutexes.
|
|
||||||
*
|
|
||||||
* Note that functions called from a bottom half context must not sleep.
|
|
||||||
* Even a simple memory allocation without using %GFP_ATOMIC can result in a
|
|
||||||
* kernel thread being put to sleep if swapping is needed. For example, the
|
|
||||||
* Linux Kernel calls the functions of a network device interface from a
|
|
||||||
* bottom half context. Thus, if a demux kABI function is called from network
|
|
||||||
* device code, the function must not sleep.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/*
|
/*
|
||||||
* Common definitions
|
* Common definitions
|
||||||
*/
|
*/
|
||||||
@ -230,30 +191,6 @@ struct dmx_section_feed {
|
|||||||
int (*stop_filtering)(struct dmx_section_feed *feed);
|
int (*stop_filtering)(struct dmx_section_feed *feed);
|
||||||
};
|
};
|
||||||
|
|
||||||
/**
|
|
||||||
* DOC: Demux Callback
|
|
||||||
*
|
|
||||||
* This kernel-space API comprises the callback functions that deliver filtered
|
|
||||||
* data to the demux client. Unlike the other DVB kABIs, these functions are
|
|
||||||
* provided by the client and called from the demux code.
|
|
||||||
*
|
|
||||||
* The function pointers of this abstract interface are not packed into a
|
|
||||||
* structure as in the other demux APIs, because the callback functions are
|
|
||||||
* registered and used independent of each other. As an example, it is possible
|
|
||||||
* for the API client to provide several callback functions for receiving TS
|
|
||||||
* packets and no callbacks for PES packets or sections.
|
|
||||||
*
|
|
||||||
* The functions that implement the callback API need not be re-entrant: when
|
|
||||||
* a demux driver calls one of these functions, the driver is not allowed to
|
|
||||||
* call the function again before the original call returns. If a callback is
|
|
||||||
* triggered by a hardware interrupt, it is recommended to use the Linux
|
|
||||||
* bottom half mechanism or start a tasklet instead of making the callback
|
|
||||||
* function call directly from a hardware interrupt.
|
|
||||||
*
|
|
||||||
* This mechanism is implemented by dmx_ts_cb() and dmx_section_cb()
|
|
||||||
* callbacks.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* typedef dmx_ts_cb - DVB demux TS filter callback function prototype
|
* typedef dmx_ts_cb - DVB demux TS filter callback function prototype
|
||||||
*
|
*
|
||||||
|
|||||||
@ -1,6 +1,10 @@
|
|||||||
/*
|
/*
|
||||||
* dvb_frontend.h
|
* dvb_frontend.h
|
||||||
*
|
*
|
||||||
|
* The Digital TV Frontend kABI defines a driver-internal interface for
|
||||||
|
* registering low-level, hardware specific driver to a hardware independent
|
||||||
|
* frontend layer.
|
||||||
|
*
|
||||||
* Copyright (C) 2001 convergence integrated media GmbH
|
* Copyright (C) 2001 convergence integrated media GmbH
|
||||||
* Copyright (C) 2004 convergence GmbH
|
* Copyright (C) 2004 convergence GmbH
|
||||||
*
|
*
|
||||||
@ -42,29 +46,6 @@
|
|||||||
|
|
||||||
#include "dvbdev.h"
|
#include "dvbdev.h"
|
||||||
|
|
||||||
/**
|
|
||||||
* DOC: Digital TV Frontend
|
|
||||||
*
|
|
||||||
* The Digital TV Frontend kABI defines a driver-internal interface for
|
|
||||||
* registering low-level, hardware specific driver to a hardware independent
|
|
||||||
* frontend layer. It is only of interest for Digital TV device driver writers.
|
|
||||||
* The header file for this API is named dvb_frontend.h and located in
|
|
||||||
* drivers/media/dvb-core.
|
|
||||||
*
|
|
||||||
* Before using the Digital TV frontend core, the bridge driver should attach
|
|
||||||
* the frontend demod, tuner and SEC devices and call dvb_register_frontend(),
|
|
||||||
* in order to register the new frontend at the subsystem. At device
|
|
||||||
* detach/removal, the bridge driver should call dvb_unregister_frontend() to
|
|
||||||
* remove the frontend from the core and then dvb_frontend_detach() to free the
|
|
||||||
* memory allocated by the frontend drivers.
|
|
||||||
*
|
|
||||||
* The drivers should also call dvb_frontend_suspend() as part of their
|
|
||||||
* handler for the &device_driver.suspend(), and dvb_frontend_resume() as
|
|
||||||
* part of their handler for &device_driver.resume().
|
|
||||||
*
|
|
||||||
* A few other optional functions are provided to handle some special cases.
|
|
||||||
*/
|
|
||||||
|
|
||||||
/*
|
/*
|
||||||
* Maximum number of Delivery systems per frontend. It
|
* Maximum number of Delivery systems per frontend. It
|
||||||
* should be smaller or equal to 32
|
* should be smaller or equal to 32
|
||||||
|
|||||||
@ -29,237 +29,6 @@
|
|||||||
#include <media/media-devnode.h>
|
#include <media/media-devnode.h>
|
||||||
#include <media/media-entity.h>
|
#include <media/media-entity.h>
|
||||||
|
|
||||||
/**
|
|
||||||
* DOC: Media Controller
|
|
||||||
*
|
|
||||||
* The media controller userspace API is documented in DocBook format in
|
|
||||||
* Documentation/DocBook/media/v4l/media-controller.xml. This document focus
|
|
||||||
* on the kernel-side implementation of the media framework.
|
|
||||||
*
|
|
||||||
* * Abstract media device model:
|
|
||||||
*
|
|
||||||
* Discovering a device internal topology, and configuring it at runtime, is one
|
|
||||||
* of the goals of the media framework. To achieve this, hardware devices are
|
|
||||||
* modelled as an oriented graph of building blocks called entities connected
|
|
||||||
* through pads.
|
|
||||||
*
|
|
||||||
* An entity is a basic media hardware building block. It can correspond to
|
|
||||||
* a large variety of logical blocks such as physical hardware devices
|
|
||||||
* (CMOS sensor for instance), logical hardware devices (a building block
|
|
||||||
* in a System-on-Chip image processing pipeline), DMA channels or physical
|
|
||||||
* connectors.
|
|
||||||
*
|
|
||||||
* A pad is a connection endpoint through which an entity can interact with
|
|
||||||
* other entities. Data (not restricted to video) produced by an entity
|
|
||||||
* flows from the entity's output to one or more entity inputs. Pads should
|
|
||||||
* not be confused with physical pins at chip boundaries.
|
|
||||||
*
|
|
||||||
* A link is a point-to-point oriented connection between two pads, either
|
|
||||||
* on the same entity or on different entities. Data flows from a source
|
|
||||||
* pad to a sink pad.
|
|
||||||
*
|
|
||||||
*
|
|
||||||
* * Media device:
|
|
||||||
*
|
|
||||||
* A media device is represented by a struct &media_device instance, defined in
|
|
||||||
* include/media/media-device.h. Allocation of the structure is handled by the
|
|
||||||
* media device driver, usually by embedding the &media_device instance in a
|
|
||||||
* larger driver-specific structure.
|
|
||||||
*
|
|
||||||
* Drivers register media device instances by calling
|
|
||||||
* __media_device_register() via the macro media_device_register()
|
|
||||||
* and unregistered by calling
|
|
||||||
* media_device_unregister().
|
|
||||||
*
|
|
||||||
* * Entities, pads and links:
|
|
||||||
*
|
|
||||||
* - Entities
|
|
||||||
*
|
|
||||||
* Entities are represented by a struct &media_entity instance, defined in
|
|
||||||
* include/media/media-entity.h. The structure is usually embedded into a
|
|
||||||
* higher-level structure, such as a v4l2_subdev or video_device instance,
|
|
||||||
* although drivers can allocate entities directly.
|
|
||||||
*
|
|
||||||
* Drivers initialize entity pads by calling
|
|
||||||
* media_entity_pads_init().
|
|
||||||
*
|
|
||||||
* Drivers register entities with a media device by calling
|
|
||||||
* media_device_register_entity()
|
|
||||||
* and unregistred by calling
|
|
||||||
* media_device_unregister_entity().
|
|
||||||
*
|
|
||||||
* - Interfaces
|
|
||||||
*
|
|
||||||
* Interfaces are represented by a struct &media_interface instance, defined in
|
|
||||||
* include/media/media-entity.h. Currently, only one type of interface is
|
|
||||||
* defined: a device node. Such interfaces are represented by a struct
|
|
||||||
* &media_intf_devnode.
|
|
||||||
*
|
|
||||||
* Drivers initialize and create device node interfaces by calling
|
|
||||||
* media_devnode_create()
|
|
||||||
* and remove them by calling:
|
|
||||||
* media_devnode_remove().
|
|
||||||
*
|
|
||||||
* - Pads
|
|
||||||
*
|
|
||||||
* Pads are represented by a struct &media_pad instance, defined in
|
|
||||||
* include/media/media-entity.h. Each entity stores its pads in a pads array
|
|
||||||
* managed by the entity driver. Drivers usually embed the array in a
|
|
||||||
* driver-specific structure.
|
|
||||||
*
|
|
||||||
* Pads are identified by their entity and their 0-based index in the pads
|
|
||||||
* array.
|
|
||||||
* Both information are stored in the &media_pad structure, making the
|
|
||||||
* &media_pad pointer the canonical way to store and pass link references.
|
|
||||||
*
|
|
||||||
* Pads have flags that describe the pad capabilities and state.
|
|
||||||
*
|
|
||||||
* %MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
|
|
||||||
* %MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
|
|
||||||
*
|
|
||||||
* NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
|
|
||||||
* be set for each pad.
|
|
||||||
*
|
|
||||||
* - Links
|
|
||||||
*
|
|
||||||
* Links are represented by a struct &media_link instance, defined in
|
|
||||||
* include/media/media-entity.h. There are two types of links:
|
|
||||||
*
|
|
||||||
* 1. pad to pad links:
|
|
||||||
*
|
|
||||||
* Associate two entities via their PADs. Each entity has a list that points
|
|
||||||
* to all links originating at or targeting any of its pads.
|
|
||||||
* A given link is thus stored twice, once in the source entity and once in
|
|
||||||
* the target entity.
|
|
||||||
*
|
|
||||||
* Drivers create pad to pad links by calling:
|
|
||||||
* media_create_pad_link() and remove with media_entity_remove_links().
|
|
||||||
*
|
|
||||||
* 2. interface to entity links:
|
|
||||||
*
|
|
||||||
* Associate one interface to a Link.
|
|
||||||
*
|
|
||||||
* Drivers create interface to entity links by calling:
|
|
||||||
* media_create_intf_link() and remove with media_remove_intf_links().
|
|
||||||
*
|
|
||||||
* NOTE:
|
|
||||||
*
|
|
||||||
* Links can only be created after having both ends already created.
|
|
||||||
*
|
|
||||||
* Links have flags that describe the link capabilities and state. The
|
|
||||||
* valid values are described at media_create_pad_link() and
|
|
||||||
* media_create_intf_link().
|
|
||||||
*
|
|
||||||
* Graph traversal:
|
|
||||||
*
|
|
||||||
* The media framework provides APIs to iterate over entities in a graph.
|
|
||||||
*
|
|
||||||
* To iterate over all entities belonging to a media device, drivers can use
|
|
||||||
* the media_device_for_each_entity macro, defined in
|
|
||||||
* include/media/media-device.h.
|
|
||||||
*
|
|
||||||
* struct media_entity *entity;
|
|
||||||
*
|
|
||||||
* media_device_for_each_entity(entity, mdev) {
|
|
||||||
* // entity will point to each entity in turn
|
|
||||||
* ...
|
|
||||||
* }
|
|
||||||
*
|
|
||||||
* Drivers might also need to iterate over all entities in a graph that can be
|
|
||||||
* reached only through enabled links starting at a given entity. The media
|
|
||||||
* framework provides a depth-first graph traversal API for that purpose.
|
|
||||||
*
|
|
||||||
* Note that graphs with cycles (whether directed or undirected) are *NOT*
|
|
||||||
* supported by the graph traversal API. To prevent infinite loops, the graph
|
|
||||||
* traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
|
|
||||||
* currently defined as 16.
|
|
||||||
*
|
|
||||||
* Drivers initiate a graph traversal by calling
|
|
||||||
* media_entity_graph_walk_start()
|
|
||||||
*
|
|
||||||
* The graph structure, provided by the caller, is initialized to start graph
|
|
||||||
* traversal at the given entity.
|
|
||||||
*
|
|
||||||
* Drivers can then retrieve the next entity by calling
|
|
||||||
* media_entity_graph_walk_next()
|
|
||||||
*
|
|
||||||
* When the graph traversal is complete the function will return NULL.
|
|
||||||
*
|
|
||||||
* Graph traversal can be interrupted at any moment. No cleanup function call
|
|
||||||
* is required and the graph structure can be freed normally.
|
|
||||||
*
|
|
||||||
* Helper functions can be used to find a link between two given pads, or a pad
|
|
||||||
* connected to another pad through an enabled link
|
|
||||||
* media_entity_find_link() and media_entity_remote_pad()
|
|
||||||
*
|
|
||||||
* Use count and power handling:
|
|
||||||
*
|
|
||||||
* Due to the wide differences between drivers regarding power management
|
|
||||||
* needs, the media controller does not implement power management. However,
|
|
||||||
* the &media_entity structure includes a use_count field that media drivers
|
|
||||||
* can use to track the number of users of every entity for power management
|
|
||||||
* needs.
|
|
||||||
*
|
|
||||||
* The &media_entity.@use_count field is owned by media drivers and must not be
|
|
||||||
* touched by entity drivers. Access to the field must be protected by the
|
|
||||||
* &media_device.@graph_mutex lock.
|
|
||||||
*
|
|
||||||
* Links setup:
|
|
||||||
*
|
|
||||||
* Link properties can be modified at runtime by calling
|
|
||||||
* media_entity_setup_link()
|
|
||||||
*
|
|
||||||
* Pipelines and media streams:
|
|
||||||
*
|
|
||||||
* When starting streaming, drivers must notify all entities in the pipeline to
|
|
||||||
* prevent link states from being modified during streaming by calling
|
|
||||||
* media_entity_pipeline_start().
|
|
||||||
*
|
|
||||||
* The function will mark all entities connected to the given entity through
|
|
||||||
* enabled links, either directly or indirectly, as streaming.
|
|
||||||
*
|
|
||||||
* The &media_pipeline instance pointed to by the pipe argument will be stored
|
|
||||||
* in every entity in the pipeline. Drivers should embed the &media_pipeline
|
|
||||||
* structure in higher-level pipeline structures and can then access the
|
|
||||||
* pipeline through the &media_entity pipe field.
|
|
||||||
*
|
|
||||||
* Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
|
|
||||||
* must be identical for all nested calls to the function.
|
|
||||||
*
|
|
||||||
* media_entity_pipeline_start() may return an error. In that case, it will
|
|
||||||
* clean up any of the changes it did by itself.
|
|
||||||
*
|
|
||||||
* When stopping the stream, drivers must notify the entities with
|
|
||||||
* media_entity_pipeline_stop().
|
|
||||||
*
|
|
||||||
* If multiple calls to media_entity_pipeline_start() have been made the same
|
|
||||||
* number of media_entity_pipeline_stop() calls are required to stop streaming.
|
|
||||||
* The &media_entity pipe field is reset to NULL on the last nested stop call.
|
|
||||||
*
|
|
||||||
* Link configuration will fail with -%EBUSY by default if either end of the
|
|
||||||
* link is a streaming entity. Links that can be modified while streaming must
|
|
||||||
* be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
|
|
||||||
*
|
|
||||||
* If other operations need to be disallowed on streaming entities (such as
|
|
||||||
* changing entities configuration parameters) drivers can explicitly check the
|
|
||||||
* media_entity stream_count field to find out if an entity is streaming. This
|
|
||||||
* operation must be done with the media_device graph_mutex held.
|
|
||||||
*
|
|
||||||
* Link validation:
|
|
||||||
*
|
|
||||||
* Link validation is performed by media_entity_pipeline_start() for any
|
|
||||||
* entity which has sink pads in the pipeline. The
|
|
||||||
* &media_entity.@link_validate() callback is used for that purpose. In
|
|
||||||
* @link_validate() callback, entity driver should check that the properties of
|
|
||||||
* the source pad of the connected entity and its own sink pad match. It is up
|
|
||||||
* to the type of the entity (and in the end, the properties of the hardware)
|
|
||||||
* what matching actually means.
|
|
||||||
*
|
|
||||||
* Subsystems should facilitate link validation by providing subsystem specific
|
|
||||||
* helper functions to provide easy access for commonly needed information, and
|
|
||||||
* in the end provide a way to use driver-specific callbacks.
|
|
||||||
*/
|
|
||||||
|
|
||||||
struct ida;
|
struct ida;
|
||||||
struct device;
|
struct device;
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user