| 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. |