408 lines
17 KiB
Plaintext
408 lines
17 KiB
Plaintext
|
Introduction
|
||
|
|
============
|
||
|
|
MPQ DVB Adapter implements Digital Video Broadcasting devices according
|
||
|
|
to LinuxTV (linuxtv.org) defined API and infrastructure.
|
||
|
|
|
||
|
|
The implemented devices are dvb/demux devices, dvb/dvr devices and
|
||
|
|
dvb/video devices.
|
||
|
|
|
||
|
|
These devices are used in Qualcomm's MPQ chipsets that support
|
||
|
|
broadcast applications.
|
||
|
|
|
||
|
|
dvb/demux is responsible to receive a digital stream broadcasted over
|
||
|
|
the air from a hardware unit (TSPP - Transport stream packet processor,
|
||
|
|
or TSIF - Transport Stream Interface) and separates the stream into its
|
||
|
|
various sub-streams such as video, audio and auxiliary data.
|
||
|
|
The separation operation is named demuxing.
|
||
|
|
|
||
|
|
dvb/dvr is used in conjunction with dvb/demux to re-play a digital
|
||
|
|
stream from memory or to record stream to memory.
|
||
|
|
|
||
|
|
dvb/video is used to handle the video decoding, it receives compressed
|
||
|
|
video from dvb/demux through a stream-buffer interface and interacts
|
||
|
|
with the existing HW video driver to perform the decoding.
|
||
|
|
|
||
|
|
For more information on the TSIF interface, please refer to TSIF
|
||
|
|
documentation under "Documentation/arm/msm/tsif.txt".
|
||
|
|
For more information on the TSPP interface, please refer to TSPP
|
||
|
|
documentation under "Documentation/arm/msm/tspp.txt".
|
||
|
|
For more information on DVB-API definition, please refer dvb
|
||
|
|
documentation under "Documentation/dvb/readme.txt".
|
||
|
|
|
||
|
|
Hardware description
|
||
|
|
====================
|
||
|
|
dvb/demux, dvb/dvr and dvb/video do not interact with a hardware directly;
|
||
|
|
The implementation of these drivers is done using the kernel API of TSPP,
|
||
|
|
TSIF and video drivers.
|
||
|
|
|
||
|
|
Software description
|
||
|
|
====================
|
||
|
|
|
||
|
|
Terminology
|
||
|
|
-----------
|
||
|
|
Stream: A stream is a TS packet source
|
||
|
|
- For example, MPEG2 Transport Stream from TSIF0
|
||
|
|
Filter: Enables TS packet filtering and routing according to PID (packet ID)
|
||
|
|
- The decision regarding which PIDs in the stream will be routed
|
||
|
|
is done via filters, each demux open request corresponds to a filter.
|
||
|
|
- Filters can pass TS packets as-is (for recording), assemble them into
|
||
|
|
"other" PES packets (for PES packets read by client), assemble and send
|
||
|
|
them to decoder (for decoder PES), or assemble them into sections.
|
||
|
|
Service: A service is a set of PIDs as defined in the service PMT.
|
||
|
|
Each service may be carried in a different transport stream or part of the
|
||
|
|
same transport stream. Processing a service means either preparing the
|
||
|
|
data for display and/or for recording.
|
||
|
|
|
||
|
|
Requirments
|
||
|
|
-----------
|
||
|
|
1. Demuxing from different sources:
|
||
|
|
- Live transport stream inputs (TSIF)
|
||
|
|
- Memory inputs
|
||
|
|
2. Support different packet formats:
|
||
|
|
- 188-bytes transport packets
|
||
|
|
- 192-bytes transport packets
|
||
|
|
3. PID filtering
|
||
|
|
4. Output of the following data:
|
||
|
|
- Decoder PES: PES (video and/or audio) that can be directed to HW decoders
|
||
|
|
in tunneling mode (without interaction of user-space).
|
||
|
|
- Other PES: a non-decoder PES, such as subtitle, teletext. The consumer
|
||
|
|
of this data is user-space that reads the data through standard read
|
||
|
|
calls.
|
||
|
|
- Sections: Sections are used by user-space to acquire different kinds of
|
||
|
|
information such as channels list, program user guide, etc.
|
||
|
|
- Transport Stream Packets: Transport stream packets of specific PIDs as
|
||
|
|
they were received in the input stream. User-space can use those to
|
||
|
|
record specific services and/or to perform time-shift buffer.
|
||
|
|
- PCR/STC: Pairs of PCR/STC can be used by user-space to perform
|
||
|
|
clock-recovery.
|
||
|
|
- Frame-indexing: For recorded stream, demux provides indexing of the
|
||
|
|
I-frames within the stream that can be used for trick-modes operations
|
||
|
|
while playing a recorded file.
|
||
|
|
5. Support decryption of scrambled transport packets.
|
||
|
|
6. Support recording of scrambled streams.
|
||
|
|
8. Section filtering.
|
||
|
|
|
||
|
|
Control path
|
||
|
|
------------
|
||
|
|
1. Client opens a demux device. Open request is done on the same demux
|
||
|
|
device for each filter.
|
||
|
|
2. Client may configure the demux's internal ring-buffer size used to
|
||
|
|
hold the data for user-space (or default is used).
|
||
|
|
3. Client configures the opened filter either to capture sections,
|
||
|
|
TS packets (for recording) or PES (decoder or non-decoder PES).
|
||
|
|
- The demux configures the underlying HW accordingly through
|
||
|
|
TSPP or TSIF kernel APIs
|
||
|
|
- demux receives notification of new data from the underlying HW and
|
||
|
|
performs demuxing operation based on the configuration.
|
||
|
|
4. Client can then read data received from the selected filter.
|
||
|
|
|
||
|
|
Data path
|
||
|
|
---------
|
||
|
|
For each filter that is opened, demux manages a circular buffer that
|
||
|
|
holds the captured filter data; Client read commands extract data from
|
||
|
|
the relevant ring buffer. Data loss can occur if a client cannot keep up
|
||
|
|
with stream bandwidth.
|
||
|
|
|
||
|
|
For PES data tunneled to decoder, demux manages a stream-buffer used to
|
||
|
|
transfer the PES data to the decoder. The stream-buffer is built from
|
||
|
|
two ring-buffers: One holding the PES payload (elementary stream) and
|
||
|
|
the other holding PES parameters extracted from the PES header. The
|
||
|
|
ring-buffer with PES parameters points to the location of respective PES
|
||
|
|
payload in the PES payload ring-buffer.
|
||
|
|
|
||
|
|
To allow concurrency of multiple stream processing, multiple demux/dvr
|
||
|
|
devices exist. Each demux devices handles a single stream input. The
|
||
|
|
number of demux devices is configurable depending on the required number
|
||
|
|
of concurrent stream processing.
|
||
|
|
|
||
|
|
The client configures each demux device with the stream to process,
|
||
|
|
by default, all devices are configured to process stream from memory.
|
||
|
|
The default setting can be changed by issuing ioctl that configures
|
||
|
|
the demux source to either TSIF0 or TSIF1. For specific TSIF input,
|
||
|
|
only one demux device may process it at a time.
|
||
|
|
|
||
|
|
Background Processing
|
||
|
|
---------------------
|
||
|
|
Demux allocates a kernel thread for each live-input to process
|
||
|
|
the TS packets notified from the HW for specific input. There
|
||
|
|
are two such inputs (TSIF0 and TSIF1), both can be processed in
|
||
|
|
parallel by two seperate threads.
|
||
|
|
|
||
|
|
The processing is the action of demuxing of the new data; it may sleep
|
||
|
|
as it locks against the demux data-structure that may be accessed by
|
||
|
|
user-space in the meanwhile.
|
||
|
|
|
||
|
|
Dependencies
|
||
|
|
------------
|
||
|
|
The demux driver depends on the following kernel drivers and subsystems:
|
||
|
|
1. TSIF driver: Used to receive TS packets from TSIF interface for
|
||
|
|
targets supporting TSIF only.
|
||
|
|
2. TSPP driver: Used to receive TS packets and/or PES from TSPP
|
||
|
|
interface for targets supporting TSPP.
|
||
|
|
3. TZ-COM: Used to communicate with TrustZone to handle scrambled
|
||
|
|
streams.
|
||
|
|
4. ION: Used to allocate memory for buffers holding decoder-data in
|
||
|
|
case the data is tunneled between demux and decoders.
|
||
|
|
Also used to allocate memory for TSPP/TSIF output pipes.
|
||
|
|
5. dvb-core: Existing Linux infrastructure used for implementation of
|
||
|
|
dvb devices.
|
||
|
|
|
||
|
|
Design
|
||
|
|
======
|
||
|
|
|
||
|
|
Goals
|
||
|
|
-----
|
||
|
|
The demux driver is designed to:
|
||
|
|
1. Fulfil the requirements listed above.
|
||
|
|
2. Be able to work on different chipsets having different HW
|
||
|
|
capabilities. For example, some chipsets are equipped with TSIF only,
|
||
|
|
others are equipped with TSPP of different versions.
|
||
|
|
|
||
|
|
Design Blocks
|
||
|
|
-------------
|
||
|
|
Demux implementation hooks to the existing Linux dvb-core
|
||
|
|
infrastructure as follows:
|
||
|
|
|
||
|
|
+----------+ +------------------------------------------+
|
||
|
|
| | | MPQ Demux Driver |
|
||
|
|
| | | +----------+ +----------+ +----------+ |
|
||
|
|
| | | | MPQ DMX | | MPQ DMX | | MPQ DMX | |
|
||
|
|
| QCOM MPQ | | | TSIF | | TSPPv1 | | TSPPv2 | |
|
||
|
|
| Adapter | | | Plugin | | Plugin | | Plugin | |
|
||
|
|
| | | +----------+ +----------+ +----------+ |
|
||
|
|
| | | +--------------------------------------+ |
|
||
|
|
| | | | MPQ Demux Common Services | |
|
||
|
|
| | | +--------------------------------------+ |
|
||
|
|
+----------+ +------------------------------------------+
|
||
|
|
+--------------------------------------------------------+
|
||
|
|
| Linux DVB Core |
|
||
|
|
| +----------+ +----------+ +----------+ |
|
||
|
|
| | DVB | | DVB DMX | | DVB | |
|
||
|
|
| | Demux | | Device | | Device | |
|
||
|
|
| +----------+ +----------+ +----------+ |
|
||
|
|
+--------------------------------------------------------+
|
||
|
|
|
||
|
|
The new developed code is QCOM MPQ Adapter and the MPQ Demux driver
|
||
|
|
with the various MPQ-DMX Plugins.
|
||
|
|
|
||
|
|
QCOM MPQ Adapter registers a new DVB adapter to Linux dvb-core.
|
||
|
|
The MPQ DVB adapter is built as a separate kernel module. Using it
|
||
|
|
demux and video devices can register themselves to the adapter.
|
||
|
|
|
||
|
|
MPQ-DMX plugins exist to hook to dvb-core demux implementation
|
||
|
|
depending on the HW capabilities. Only one of these plugins might be
|
||
|
|
compiled and run at a time on the target.
|
||
|
|
As the name of each plugin implies, one plugin implements demux
|
||
|
|
functionality for targets supporting TSIF only, and the others
|
||
|
|
implement pluging for targets supporting TSPP in different versions.
|
||
|
|
|
||
|
|
The plugin implementation is not hooked to specific chipset as
|
||
|
|
different chipsets might have the same HW capability.
|
||
|
|
|
||
|
|
The MPQ-DMX Plugin Common Services provides common services that are
|
||
|
|
used by all plugins, such as registrations of demux devices to
|
||
|
|
the dvb-core.
|
||
|
|
|
||
|
|
The demux plugin is built as a separate kernel module. Each plugin
|
||
|
|
hooks to the DVB-Demux by providing set of pointers to functions
|
||
|
|
required for DVB-Demux and dvb-core operation. The actual
|
||
|
|
implementation of these function differs between the plugins depending
|
||
|
|
on the HW capabilities. The plugins may be viewed as "classes"
|
||
|
|
inheriting from DVB-Demux "class".
|
||
|
|
|
||
|
|
Interface to TSPP/TSIF Drivers
|
||
|
|
------------------------------
|
||
|
|
Each demux plugin interacts with the kernel API of the relevant driver
|
||
|
|
(either TSIF or TSPP) to receive TS packets or other kinds of data
|
||
|
|
depending on the HW capabilities.
|
||
|
|
|
||
|
|
The demux uses the kernel API of TSIF and TSPP drivers and registers
|
||
|
|
callback triggered when new data is received. The callback schedules
|
||
|
|
work to a single-threaded workqueue to process the data. The actual
|
||
|
|
processing of the data depends on the HW capabilities.
|
||
|
|
|
||
|
|
Interface to TZ-COM Driver
|
||
|
|
--------------------------
|
||
|
|
For cases HW does not support descrambling, the descrambling is
|
||
|
|
performed by communicating with TZ using TZ-COM kernel API.
|
||
|
|
|
||
|
|
ION driver is used to allocate input and output buffers provided to TZ.
|
||
|
|
|
||
|
|
Interface to Decoders
|
||
|
|
---------------------
|
||
|
|
The interface to the decoders is done through a stream-buffer interface.
|
||
|
|
The design aims not to have direct calls between dvb/demux and
|
||
|
|
dvb/video for de-coupling and generality. dvb/demux and dvb/video
|
||
|
|
interact only with stream-buffer API.
|
||
|
|
|
||
|
|
Stream buffer is built of two ring-buffers, one holding the PES payload
|
||
|
|
(the video elementary stream) and the other holding parameters from PES
|
||
|
|
headers required by decoders.
|
||
|
|
|
||
|
|
The separation to two ring-buffers allows locking the payload buffer
|
||
|
|
as secured buffer that only the decoder's HW may access while allowing
|
||
|
|
the software to access the PES headers which are not required to be
|
||
|
|
secured. Locking of the payload buffer is done when the data should be
|
||
|
|
secured (scrambled video stream for example).
|
||
|
|
|
||
|
|
The stream-buffer API make use of dvb-ring buffer implementation that
|
||
|
|
is part of dvb-core.
|
||
|
|
|
||
|
|
SMP/multi-core
|
||
|
|
==============
|
||
|
|
Driver is fully SMP aware.
|
||
|
|
|
||
|
|
Interface
|
||
|
|
=========
|
||
|
|
|
||
|
|
User-space API
|
||
|
|
--------------
|
||
|
|
dvb/demux and dvb/dvr each expose a char device interface to user-space
|
||
|
|
as defined by linuxtv.org. Extension to this interface is done to add
|
||
|
|
new features required by MPQ use-cases. The extensions preserve backward
|
||
|
|
compatibility of the API defined by linuxtv.org
|
||
|
|
|
||
|
|
The devices appear in file-system under:
|
||
|
|
/dev/dvb/adapter0/demuxN
|
||
|
|
/dev/dvb/adapter0/dvrN
|
||
|
|
|
||
|
|
Where "N" ranges between 0 to total number of demux devices defined.
|
||
|
|
The default configuration is 4 devices.
|
||
|
|
|
||
|
|
Extensions to this API (through new ioctl) exist to provide the
|
||
|
|
following functionality:
|
||
|
|
|
||
|
|
1. DMX_SET_TS_PACKET_FORMAT: Set the transport stream TS packet format.
|
||
|
|
Configures whether the stream fed to demux from memory is with TS packet
|
||
|
|
of 188 bytes long, 192 bytes long, etc.
|
||
|
|
Default is 188 bytes long to preserve backward compatibility.
|
||
|
|
|
||
|
|
Returns the following values:
|
||
|
|
0 in case of success.
|
||
|
|
-EINVAL if the parameter is invalid.
|
||
|
|
-EBUSY if demux is already running.
|
||
|
|
|
||
|
|
2. DMX_SET_DECODER_BUFFER_SIZE: Set the decoder's buffer size.
|
||
|
|
For data tunneled to decoder, client can configure the size of the buffer
|
||
|
|
holding the PES payload.
|
||
|
|
Default is set to the fixed size value that exists in current dvb-core to
|
||
|
|
preserve backward compatibility.
|
||
|
|
|
||
|
|
Returns the following values:
|
||
|
|
0 in case of success.
|
||
|
|
-EINVAL if the parameter is invalid.
|
||
|
|
-EBUSY if demux is already running.
|
||
|
|
|
||
|
|
3. DMX_SET_TS_OUT_FORMAT: Set the TS packet recording format.
|
||
|
|
Indicates whether the TS packet used for recording should be in 188 or 192
|
||
|
|
bytes long format. In case of 192-packets output, 4 bytes zero timestamp
|
||
|
|
is attached to the original 188 packet.
|
||
|
|
Default is set for 188 to preserve backward compatibility.
|
||
|
|
|
||
|
|
Returns the following values:
|
||
|
|
0 in case of success.
|
||
|
|
-EINVAL if the parameter is invalid.
|
||
|
|
-EBUSY if demux is already running.
|
||
|
|
|
||
|
|
4. Added support for mmap for direct access to input/output buffers.
|
||
|
|
User can either use the original read/write syscalls or use mmap
|
||
|
|
on the specific file-handle. Several ioctls were exposed so that
|
||
|
|
user can find-out the status of the buffers (DMX_GET_BUFFER_STATUS),
|
||
|
|
to notify demux when data is consumed (DMX_RELEASE_DATA) or notify
|
||
|
|
dvr when data is fed (DMX_FEED_DATA).
|
||
|
|
|
||
|
|
5. DMX_SET_PLAYBACK_MODE: Set playback mode in memory input.
|
||
|
|
In memory input, contrary to live input, playback can be in pull mode,
|
||
|
|
where if one of output buffers is full, demux stalls waiting for free space,
|
||
|
|
this would cause DVR input buffer fullness to accumulate.
|
||
|
|
|
||
|
|
Returns the following values:
|
||
|
|
0 in case of success.
|
||
|
|
-EINVAL if the parameter is invalid.
|
||
|
|
-EBUSY if demux is already running.
|
||
|
|
|
||
|
|
debugfs
|
||
|
|
-------
|
||
|
|
debugfs is used for debug purposes.
|
||
|
|
|
||
|
|
Directory in debugfs is created for each demux device.
|
||
|
|
|
||
|
|
Each directory includes several performance counters of the specific demux:
|
||
|
|
Total demuxing time, total CRC time, HW notification rate, HW notification
|
||
|
|
buffer size.
|
||
|
|
|
||
|
|
|
||
|
|
Exported Kernel API
|
||
|
|
-------------------
|
||
|
|
MPQ adapter exports the following kernel API:
|
||
|
|
1. Getter API for the registered MPQ adapter handle.
|
||
|
|
This is used by demux plugin as well as dvb/video implementation to
|
||
|
|
register their devices to that adapter.
|
||
|
|
2. Stream buffer API: Used to tunnel the data between dvb/demux and
|
||
|
|
decoders. The API is used by dvb/demux and by decoders to write/read
|
||
|
|
tunneled data.
|
||
|
|
3. Stream buffer interface registration: Used to register stream-buffer
|
||
|
|
interfaces. When demux driver is asked to tunnel data to a decoder,
|
||
|
|
the demux allocates a stream-buffer to be shared between demux and
|
||
|
|
the decoder. For the decoder to retrieve the info of the
|
||
|
|
stream-buffer it should connect to, stream-buffer registration API
|
||
|
|
exist.
|
||
|
|
The demux registers the new allocated stream buffer handle to MPQ
|
||
|
|
Adapter, and the decoder may query the registered interface through
|
||
|
|
MPQ Adapter.
|
||
|
|
|
||
|
|
Driver parameters
|
||
|
|
=================
|
||
|
|
There are three kernel modules required for DVB API operation:
|
||
|
|
1. dvb-core.ko: This is an existing Linux module for dvb functionality.
|
||
|
|
The parameters for this module are the one defined by linuxtv.org.
|
||
|
|
An additional parameter was added to specify whether to collect
|
||
|
|
performance debug information exposed through debugfs.
|
||
|
|
Parameter name: dvb_demux_performancecheck
|
||
|
|
|
||
|
|
2. mpq-adapter.ko: MPQ DVB adapter module. Has a parameter to
|
||
|
|
specify the adapter number, the number (X) is the same as the one
|
||
|
|
that appears in /dev/dvb/adapterX. Default is 0.
|
||
|
|
Parameter name: adapter_nr
|
||
|
|
|
||
|
|
3. mpq-dmx-hw-plugin.ko: Module for demux HW plugin. Receives as a
|
||
|
|
parameter the number of required demux devices. Default is set to the
|
||
|
|
number specified in kernel configuration.
|
||
|
|
Parameter name: mpq_demux_device_num
|
||
|
|
|
||
|
|
Config options
|
||
|
|
==============
|
||
|
|
New kernel configurations is available (through make menuconfig) to
|
||
|
|
enable MPQ based adapter functionality. The following configurations
|
||
|
|
exist:
|
||
|
|
1. Control whether to enable QCOM MPQ DVB adapter (tri-state).
|
||
|
|
It depends on having dvb-core enabled.
|
||
|
|
2. If MPQ adapter is enabled:
|
||
|
|
2.1. Control whether to enable MPQ dvb/demux (tri-state)
|
||
|
|
2.2. Control whether to enable MPQ dvb/video (tri-state)
|
||
|
|
2.3. If dvb/demux is enabled:
|
||
|
|
2.3.1. Configure the number of demux devices. Default is 4.
|
||
|
|
2.3.2. Select the desired demux plugin. Each plugin would appear
|
||
|
|
in the list of options depending whether the respective
|
||
|
|
driver (TSIF/TSPP) is enabled or not.
|
||
|
|
|
||
|
|
Dependencies
|
||
|
|
============
|
||
|
|
1. The implementation depends on having dvb-core enabled.
|
||
|
|
2. Each demux plugin depends on whether the relevant driver it uses
|
||
|
|
is enabled. TSIF plugin depends on TSIF driver and TSPP plugins
|
||
|
|
depend on TSPP driver.
|
||
|
|
3. There's no communication to other processors.
|
||
|
|
|
||
|
|
User space utilities
|
||
|
|
====================
|
||
|
|
N/A
|
||
|
|
|
||
|
|
Other
|
||
|
|
=====
|
||
|
|
N/A
|
||
|
|
|
||
|
|
Known issues
|
||
|
|
============
|
||
|
|
N/A
|