250 lines
11 KiB
Plaintext
250 lines
11 KiB
Plaintext
Introduction
|
|
============
|
|
The TSPP (Transport stream packet processor) is a hardware accelerator
|
|
designed to process MPEG2 TS (transport stream) data. It is mainly used for
|
|
broadcast terrestrial services to off-load the host CPU from real-time
|
|
sensitive TS processing for high bandwidth streams (~20Mbps). Data is received
|
|
either via TSIF (Transport stream interface) or system memory.
|
|
The TSPP driver manages the TSIF 12Seg HW core, which consists of a TSPP, a
|
|
BAM (Bus access manager, used for DMA) and two TSIF inputs.
|
|
It is applicable to the TSIF 12Seg core found on select Qualcomm MSM chips.
|
|
|
|
For more information on the TSIF interface, please refer to TSIF documentation
|
|
(Documentation/arm/msm/tsif.txt).
|
|
For more information on the BAM interface, please refer to SPS documentation
|
|
(Documentation/dma/sps/sps_architecture.txt).
|
|
|
|
Hardware description
|
|
====================
|
|
The TSPP unit expands the capabilities of the TSIF interface by adding MPEG2
|
|
stream processing such as:
|
|
- Elementary Stream PID filtering and de-multiplexing
|
|
- Several TSP processing operation modes:
|
|
- TSP Raw processing (with or w/o suffix)
|
|
- TSP PES assembly
|
|
- Error handling
|
|
- Multi2 decryption
|
|
|
|
+-------------+ +------+
|
|
+>|ARM subsystem| |Memory|
|
|
| +-------------+ +------+
|
|
| | |
|
|
I| | |
|
|
R| ========================== System bus
|
|
Q| |
|
|
s| | TSIF 12Seg
|
|
| +-----------------------+
|
|
| | +---+ |
|
|
| | |BAM| |
|
|
| | +---+ | GPIOs
|
|
| | | +------+--|-------- TSIF 0 clk
|
|
| | +----+ |TSIF 0|--|-------- TSIF 0 data
|
|
+-| | |-----+------+--|-------- TSIF 0 en
|
|
| |TSPP| |
|
|
| | |-----+------+--|-------- TSIF 1 clk
|
|
| +----+ |TSIF 1|--|-------- TSIF 1 data
|
|
| +------+--|-------- TSIF 1 en
|
|
+-----------------------+
|
|
|
|
The TSPP unit receives an MPEG2 transport stream either via the two TSIF
|
|
interfaces, or via system memory.
|
|
It uses the BAM interface to transfer data to and from system memory.
|
|
The ARM subsystem receives interrupts on various error conditions from TSPP
|
|
and TSIF units, and on data transfer events from the BAM.
|
|
|
|
Software Description
|
|
====================
|
|
The TSPP driver is responsible for:
|
|
- TSPP/TSIF hardware configuration (using SPS driver to configure BAM
|
|
hardware)
|
|
- TSIF GPIO/Clocks configuration
|
|
- Memory resource management
|
|
- Handling TSIF/TSPP interrupts and BAM events
|
|
- TSPP Power management
|
|
|
|
TSPP Terminology
|
|
----------------
|
|
Device - the TSPP hardware instance
|
|
- the device contains many streams
|
|
Stream: All data that is received from a particular TS packet source
|
|
- For example, MPEG2 Transport Stream from TSIF0
|
|
- A stream can consist of many channels
|
|
Channel: A channel routes part of a stream to a specified memory location
|
|
- For example, video and audio can be routed to different memory locations
|
|
using different channels
|
|
- Channel contents are defined by filters
|
|
Filter: Enables TS packet filtering and routing according to PID (packet ID)
|
|
- The decision regarding which PIDs in the stream will be routed to a
|
|
channel is done via filters
|
|
- Several filters can be registered to the same channel
|
|
- Filters can pass TS packets as-is (Raw mode) or assemble them into PES
|
|
packets (PES mode)
|
|
- Groups of contiguous PIDs can be filtered together (i.e. PSI/SI 0x0-0x2F,
|
|
1Seg PMTs 0x1FC8-0x1FCF)
|
|
- Filters can be used to discard packets (e.g. eliminate processing of
|
|
unwanted channels)
|
|
|
|
Init flow:
|
|
----------
|
|
Driver registers BAM (via SPS driver) and initializes TSIF/TSPP hardware.
|
|
|
|
Control path:
|
|
-------------
|
|
1. Client opens a TSPP stream and channel
|
|
2. Client notifies the driver of the source stream (TSIF0/TSIF1/Memory)
|
|
- TSPP driver allocates memory for the channel (circular buffer)
|
|
- As the amount of memory varies according to stream bandwidth (which the
|
|
driver doesn't know), a client can hint to the driver about the required
|
|
memory or stream bandwidth
|
|
- TSPP driver configures TSIF/BAM hardware according to selected stream
|
|
3. Client notifies the driver to filter a set of PIDs for the selected channel
|
|
- TSPP driver configures TSPP hardware filters accordingly
|
|
4. Client can now read data received from the selected channel
|
|
|
|
Optional: Scrambling keys can be configured for a filter to decrypt Multi2
|
|
encrypted streams. The scrambling keys are received encrypted in-stream every
|
|
~2 seconds. The client uses a smart card and master key to decrypt the
|
|
received scrambling keys. The master key remains inside the smart card and is
|
|
never revealed to software.
|
|
|
|
Conceptual flow:
|
|
Client TSPP Driver SPS Driver Hardware
|
|
| | | |
|
|
| | Init TSIF/TSPP | |
|
|
| |---------------------------|------------------>|
|
|
| | Register BAM | |
|
|
| |-------------------------->| |
|
|
| | | |
|
|
| open(tspp.5) | | |
|
|
|-------------------------->| | |
|
|
| ioctl(tspp.5,SOURCE,TSIF0)| | |
|
|
|-------------------------->| | |
|
|
| | buff[0..N] = alloc() | |
|
|
| |----------> | |
|
|
| | Connect(TSPP,MEM) | |
|
|
| |-------------------------->| |
|
|
| | Transfer(buff[0..N]) | |
|
|
| |-------------------------->| |
|
|
| | | |
|
|
| | Configure TSIF0 | |
|
|
| |---------------------------|------------------>|
|
|
| | | |
|
|
| ioctl(tspp.5,FILTER,pid) | | |
|
|
|-------------------------->| | |
|
|
| | Configure TSPP filters | |
|
|
| |---------------------------|------------------>|
|
|
| | | |
|
|
| | | INT |
|
|
| | |<------------------|
|
|
| | notify(EOT,buff[x]) | |
|
|
| |<--------------------------| |
|
|
| | Transfer(buff[y]) | |
|
|
| |-------------------------->| |
|
|
| | | |
|
|
| read(tspp.5) | | |
|
|
|-------------------------->| | |
|
|
| | | |
|
|
|
|
|
|
Data path:
|
|
----------
|
|
The TSPP driver is not involved in data transfer, other than managing the
|
|
circular buffer pointers when a transfer is complete. Data loss can occur if
|
|
a client cannot keep up with stream bandwidth.
|
|
The driver does not notify the application if there is data loss. It is
|
|
assumed that the application will read data when the data is ready, and when
|
|
the application is able.
|
|
|
|
API
|
|
===
|
|
int tspp_open_stream(u32 dev, u32 channel, struct tspp_select_source *source);
|
|
int tspp_close_stream(u32 dev, u32 channel);
|
|
int tspp_open_channel(u32 dev, u32 channel);
|
|
int tspp_close_channelu(32 dev, u32 channel);
|
|
int tspp_add_filter(u32 dev, u32 channel, struct tspp_filter *filter);
|
|
int tspp_remove_filter(u32 dev, u32 channel, struct tspp_filter *filter);
|
|
|
|
Refer to chrdev implementation in kernel/drivers/misc/tspp.c for an example of
|
|
how to use this api.
|
|
|
|
Each stream is represented by a chrdev device
|
|
16 available devices: /dev/tspp00 - /dev/tspp15
|
|
Each device implements these functions:
|
|
open()
|
|
close()
|
|
read()
|
|
ioctl()
|
|
|
|
ioctl() contains several sub-functions:
|
|
0: select source
|
|
1: add filter
|
|
2: remove filter
|
|
3: set decryption keys
|
|
4: set initial cbc values (IV)
|
|
5: set system keys
|
|
6: set buffer size
|
|
|
|
You can refer to include/linux/tspp.h for the details on the structures
|
|
associated with these IOCTL calls.
|
|
|
|
Design
|
|
======
|
|
Design is based on the existing TSIF driver, with added control functionality
|
|
for the extra hardware features.
|
|
|
|
Power Management
|
|
===============
|
|
TSPP driver prevents MSM from sleeping while TSPP hardware is active.
|
|
To achieve this, the driver holds the wake lock. When no channels are
|
|
configured to receive data, the driver stops the clocks to save power.
|
|
It will register for suspend/resume in the future.
|
|
|
|
SMP/multi-core
|
|
==============
|
|
Driver is fully SMP aware.
|
|
|
|
Performance
|
|
===========
|
|
Control flows are rare.
|
|
Data path only involves maintaining the circular buffer pointers.
|
|
|
|
Interface
|
|
=========
|
|
Driver exposes a char device interface to user-space for each channel.
|
|
Control transactions are performed via ioctl on the channel. Data is read as
|
|
any regular char device (blocking and non-blocking). Please see sequence
|
|
under software description for more info.
|
|
|
|
Debugfs may be used for debug purposes. Through debugfs, all of the TSIF
|
|
registers can be accessed under /sys/kernel/debug/tsif0 and tsif1. The
|
|
TSPP registers are found under /sys/kernel/debug/tspp0. If you cannot
|
|
see these devices, then either the driver has been built without debugfs
|
|
support (check the define TSPP_USE_DEBUGFS in tspp.c) or the debugfs has
|
|
not been mounted correctly (or mounted in a different location).
|
|
|
|
Driver Parameters
|
|
=================
|
|
TSPP driver has target-specific parameters:
|
|
- Memory base addresses for TSIF/TSPP/BAM
|
|
- TSIF/TSPP/BAM IRQ numbers
|
|
- TSIF GPIO numbers
|
|
|
|
Config Options
|
|
==============
|
|
To enable the driver, set CONFIG_TSPP (=y or =m) in the appropriate
|
|
config file for the platform.
|
|
|
|
Dependencies
|
|
============
|
|
The TSPP driver depends on the SPS driver to configure BAM hardware.
|
|
|
|
User space utilities
|
|
====================
|
|
The TSPP test suite can be found in:
|
|
vendor/qcom/proprietary/kernel-tests/tspp
|
|
|
|
Known Issues
|
|
============
|
|
Currently PES processing mode cannot be configured for streams in which the PES
|
|
length is 0. This is a HW limitation.
|