[media] demux.h: move documentation overview from device-drivers.tmpl
It is better to keep the documentation overview at the header file, as this makes easier for developers to remember to fix when needed. Suggested-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
This commit is contained in:
Mauro Carvalho Chehab
parent
d55ebd07b6
commit
7b6e55b970
|
|
@ -243,71 +243,12 @@ X!Isound/sound_firmware.c
|
|||
!Idrivers/media/dvb-core/dvb_math.h
|
||||
!Idrivers/media/dvb-core/dvb_ringbuffer.h
|
||||
!Idrivers/media/dvb-core/dvbdev.h
|
||||
<sect1><title>Digital TV Demux API</title>
|
||||
<para>The kernel demux API 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 API is named
|
||||
<constant>demux.h</constant> and located in
|
||||
<constant>drivers/media/dvb-core</constant>.</para>
|
||||
|
||||
<para>The demux API 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 API, it receives a pointer to the API of that
|
||||
resource.</para>
|
||||
<para>Each demux receives its TS input from a DVB front-end or from
|
||||
memory, as set via this demux API. In a system with more than one
|
||||
front-end, the API 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 API only controls front-ends regarding to their connections
|
||||
with demuxes; the APIs used to set the other front-end parameters,
|
||||
such as tuning, are not defined in this document.</para>
|
||||
<para>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 <constant>dmx_demux</constant>. For example,
|
||||
a demux interface might support Section filtering, but not PES
|
||||
filtering. The API 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”.</para>
|
||||
<para>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.</para>
|
||||
<para>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 API function
|
||||
is called from network device code, the function must not sleep.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<section id="demux_callback_api">
|
||||
<title>Demux Callback API</title>
|
||||
<para>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.</para>
|
||||
<para>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.</para>
|
||||
<para>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.</para>
|
||||
<para>This mechanism is implemented by
|
||||
<link linkend='API-dmx-ts-cb'>dmx_ts_cb()</link> and
|
||||
<link linkend='API-dmx-section-cb'>dmx_section_cb()</link>.</para>
|
||||
</section>
|
||||
|
||||
<sect1><title>Digital TV Demux API</title>
|
||||
!Pdrivers/media/dvb-core/demux.h Digital TV Demux API
|
||||
</sect1>
|
||||
<sect1><title>Demux Callback API</title>
|
||||
!Pdrivers/media/dvb-core/demux.h Demux Callback API
|
||||
</sect1>
|
||||
!Idrivers/media/dvb-core/demux.h
|
||||
</sect1>
|
||||
<sect1><title>Remote Controller devices</title>
|
||||
|
|
|
|||
|
|
@ -32,6 +32,49 @@
|
|||
#include <linux/time.h>
|
||||
#include <linux/dvb/dmx.h>
|
||||
|
||||
/**
|
||||
* DOC: Digital TV Demux API
|
||||
*
|
||||
* The kernel demux API 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 API is named demux.h and located in
|
||||
* drivers/media/dvb-core.
|
||||
*
|
||||
* The demux API 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 API, it receives
|
||||
* a pointer to the API of that resource.
|
||||
*
|
||||
* Each demux receives its TS input from a DVB front-end or from memory, as
|
||||
* set via this demux API. In a system with more than one front-end, the API
|
||||
* 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 API only controls front-ends regarding to their connections with
|
||||
* demuxes; the APIs used to set the other front-end parameters, such as
|
||||
* tuning, are not defined in this document.
|
||||
*
|
||||
* 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 API 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 API function is called from network
|
||||
* device code, the function must not sleep.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Common definitions
|
||||
*/
|
||||
|
|
@ -187,8 +230,28 @@ struct dmx_section_feed {
|
|||
int (*stop_filtering)(struct dmx_section_feed *feed);
|
||||
};
|
||||
|
||||
/*
|
||||
* Callback functions
|
||||
/**
|
||||
* DOC: Demux Callback API
|
||||
*
|
||||
* 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.
|
||||
*/
|
||||
|
||||
/**
|
||||
|
|
|
|||
Loading…
Reference in New Issue