498 lines
19 KiB
Plaintext
498 lines
19 KiB
Plaintext
Introduction
|
||
============
|
||
|
||
TSPP2 Driver
|
||
|
||
The TSPP2 (Transport Stream Packet Processor v2) is a hardware accelerator
|
||
designed to process MPEG-2 Transport Stream (TS) data. It can be used to
|
||
process broadcast TV services. The TSPP2 HW processes the TS packets, offloads
|
||
the host CPU and supports the real-time processing requirements of such
|
||
services.
|
||
|
||
TS data can be received either from TSIF (Transport Stream Interface) input
|
||
or from memory input, to support playing live broadcasts as well as
|
||
playback from memory. Recording is also supported.
|
||
|
||
TSPP2 is a significantly different HW unit than the TSPP unit described in
|
||
Documentation/arm/msm/tspp.txt. The functionality is enhanced and the HW
|
||
design is different.
|
||
|
||
Hardware description
|
||
====================
|
||
The TSPP2 HW contains the TSPP2 core, a BAM (Bus Access Manager, used for DMA
|
||
operations) unit, and a VBIF unit (IOMMU).
|
||
|
||
The TSPP2 HW supports:
|
||
a. Up to two TSIF inputs and up to eight memory inputs.
|
||
b. Various TS packet sizes (188/192 bytes) and formats (timestamp location).
|
||
c. PID filtering.
|
||
d. Raw transmit operation for section filtering or recording.
|
||
e. Full PES and separated PES transmit operation for audio and video playback.
|
||
f. Decryption and re-encryption operations for secure transport streams.
|
||
g. PCR extraction.
|
||
h. Indexing - identifying patterns in video streams.
|
||
|
||
The following diagram provides an overview of the TSPP2 HW:
|
||
+------------------------------------------------------------------+
|
||
| |
|
||
| +-------------+ +--------------------+ |
|
||
| | TSIF 0 +---> TSPP2 Core | |
|
||
| +-------------+ | | |
|
||
| | +---------------+ | |
|
||
| +-------------+ | | | | |
|
||
| | TSIF 1 +---> | Source 0 | | |
|
||
| +-------------+ | | | | |
|
||
| | | | | |
|
||
| | | | | |
|
||
| | | +------------+| | +--------------+ |
|
||
| | | | Filter 0 +|---------> BAM pipe 3 | |
|
||
| | | +------------+| | +--------------+ |
|
||
| | | +------------+| | +--------------+ |
|
||
| +-------------+ | | | Filter 1 +|---------> BAM pipe 4 | |
|
||
| | BAM pipe 0 +---> | +------------+| | +--------------+ |
|
||
| +-------------+ | | | | | |
|
||
| +-------------+ | +---------------+ | +--------------+ |
|
||
| | BAM pipe 1 +--->--------------------|----| | |
|
||
| +-------------+ | | | VBIF | |
|
||
| +-------------+ | | | IOMMU | |
|
||
| | BAM pipe 2 +--->--------------------|----| | |
|
||
| +-------------+ +--------------------+ +--------------+ |
|
||
+------------------------------------------------------------------+
|
||
|
||
A source is configured to have either a TSIF input (TSIF 0 or 1) or a
|
||
memory input (a BAM pipe). One or more filters are attached to the source.
|
||
Each filter has a 13-bit PID and mask values to perform the PID filtering.
|
||
Additionally, one or more operations are added to each filter to achieve the
|
||
required functionality. Each operation has specific parameters. The operation's
|
||
output is usually placed in an output pipe.
|
||
|
||
The TSPP HW uses its own virtual address space, mapping memory buffer addresses
|
||
using the VBIF IOMMU.
|
||
|
||
Software description
|
||
====================
|
||
The TSPP2 Linux kernel driver manages the TSPP2 core. The TSPP2 driver utilizes
|
||
the SPS driver to configure and manage the BAM unit, which is used to perform
|
||
DMA operations and move TS data to/from system memory.
|
||
|
||
The TSPP2 driver uses the ION driver to control the IOMMU and map user-allocated
|
||
buffers to the TSPP2 IOMMU domain.
|
||
|
||
The TSPP2 is a standard Linux platform device driver. It can be configured as a
|
||
loadable or built-in kernel module. The driver is supported only in platforms
|
||
that contain the TSPP2 HW.
|
||
|
||
The driver provides an abstraction of the TSPP2 HW functionality for
|
||
kernel-space clients. For example, the dvb/demux kernel driver, which provides
|
||
an API for upper layers to perform TS de-multiplexing (including PID filtering,
|
||
recording, indexing etc.), uses the TSPP2 driver to utilize the TSPP2 HW and
|
||
offload the CPU, instead of doing all the required processing in SW.
|
||
|
||
For further information please refer to Documentation/dvb/qcom-mpq.txt.
|
||
|
||
Terminology
|
||
-----------
|
||
This section describes some of the software "objects" implemented by the driver.
|
||
|
||
a. TSPP2 device: an instance of the TSPP2 device representing the TSPP2 HW and
|
||
its capabilities. The client identifies a device instance according to a
|
||
device ID.
|
||
|
||
b. Indexing table: A TSPP2 device contains 4 indexing tables. These tables are
|
||
used to identify patterns in the video stream and report on them.
|
||
The client identifies an indexing table according to a table ID.
|
||
|
||
c. Pipe: a BAM pipe used for DMA operations. The TSPP2 HW has a BAM unit with
|
||
31 pipes. A pipe contains a memory buffer and a corresponding descriptor ring,
|
||
and is used as the output for TSPP2 data (e.g. PES payload, PES headers,
|
||
indexing information etc.). For memory inputs, a pipe is used as the input
|
||
buffer where data can be written to for TSPP2 processing. BAM Pipes are
|
||
managed by the TSPP2 driver using the SPS driver which controls BAM HW. The
|
||
client is responsible for buffer memory allocation, and can control many
|
||
BAM-related pipe parameters.
|
||
|
||
d. Source: a source object represents data "stream" from the TS input,
|
||
through the filters and operations that perform the processing on the TS data,
|
||
until the output. A source has the following properties:
|
||
- Either a TSIF or a memory input.
|
||
- For memory input: an input pipe.
|
||
- Source-related configuration (e.g., packet size and format).
|
||
- One or more PID filters. Each filter contains operations.
|
||
- One or more output pipes.
|
||
The client is responsible to configure the source object as needed using the
|
||
appropriate API. The client identifies a source using a source handle, which
|
||
the driver provides when opening a source for use.
|
||
|
||
e. Filter: a filter object represents a PID filter which is used to get only the
|
||
TS packets with specific PIDs and filter out all other TS packets in the stream.
|
||
The client adds filters to the source object to define the processing of data.
|
||
Each filter has a 13-bit PID value and bit-mask, so a filter can be used to
|
||
get TS packets with various PID values. Note, however, that it is highly
|
||
recommended to use each filter with a unique PID (i.e., 0x1FFF mask), and it is
|
||
mandatory that the PIDs handled by each source's filters are mutually exclusive
|
||
(i.e., the client must not configure two filters in the same source that handle
|
||
the same PID values). A filter has up to 16 operations that instruct the TSPP2
|
||
HW how to process the data. The client identifies a filter using a filter
|
||
handle, which the driver provides when opening a filter for use.
|
||
|
||
f. Operation: an operation object represents a basic building block describing
|
||
how data is processed. Operations are added to a filter and are performed on
|
||
the data received by this filter, in the order they were added. One or more
|
||
operations may be required to achieve the desired functionality. For example,
|
||
a "section filtering" functionality requires a raw transmit operation, while a
|
||
"recording" functionality requires a raw transmit operations as well as an
|
||
indexing operation (to support trick modes).
|
||
|
||
Driver initialization
|
||
---------------------
|
||
The driver's probe function is invoked if there is a matching device tree node
|
||
(or platform device). The probe function gets the required memory resources
|
||
(i.e., register address spaces) and maps them to kernel space for the
|
||
driver's use. The probe function also request the required IRQs and gets the
|
||
TSPP2 IOMMU domain. Finally, the probe function resets all HW registers to
|
||
appropriate default values, and resets all the required software structures.
|
||
|
||
See API description in Interface section.
|
||
|
||
Usage examples
|
||
--------------
|
||
|
||
Section filtering example - opening a Raw filter with data from TSIF0:
|
||
----------------------------------------------------------------------
|
||
u32 dev_id = 0;
|
||
u32 src_handle;
|
||
u32 pipe_handle;
|
||
u32 filter_handle;
|
||
u32 iova;
|
||
u32 vaddress;
|
||
struct tspp2_config cfg = {...};
|
||
struct tspp2_pipe_config_params pipe_config;
|
||
struct tspp2_pipe_pull_mode_params pull_params = {0, 0};
|
||
struct tspp2_operation raw_op;
|
||
struct sps_event_notify event;
|
||
struct sps_iovec desc;
|
||
|
||
/* Open TSPP2 device for use */
|
||
tspp2_device_open(dev_id);
|
||
|
||
/* Set global configuration */
|
||
tspp2_config_set(dev_id, &cfg);
|
||
|
||
/* Open source with TSIF0 input */
|
||
tspp2_src_open(dev_id, TSPP2_INPUT_TSIF0, &src_handle);
|
||
|
||
/* Set parsing options if needed, for example: */
|
||
tspp2_src_parsing_option_set(src_handle,
|
||
TSPP2_SRC_PARSING_OPT_CHECK_CONTINUITY, 1);
|
||
|
||
/* Assume normal sync byte, assume no need for scrambling configuration */
|
||
|
||
/* Set packet size and format: */
|
||
tspp2_src_packet_format_set(src_handle, TSPP2_PACKET_FORMAT_188_RAW);
|
||
|
||
/* Since this is TSIF input, flow control is in push mode */
|
||
|
||
/* Allocate memory for output pipe via ION – not shown here */
|
||
|
||
/* Open an output pipe for use */
|
||
pipe_config.ion_client = ...
|
||
pipe_config.buffer_handle = ...
|
||
pipe_config.buffer_size = ...
|
||
pipe_config.pipe_mode = TSPP2_SRC_PIPE_OUTPUT;
|
||
pipe_config.sps_cfg.descriptor_size = 188;
|
||
pipe_config.sps_cfg.setting = (SPS_O_AUTO_ENABLE | SPS_O_HYBRID |
|
||
SPS_O_OUT_OF_DESC | SPS_O_ACK_TRANSFERS);
|
||
pipe_config.sps_cfg.wakeup_events = SPS_O_OUT_OF_DESC;
|
||
pipe_config.sps_cfg.callback = ...
|
||
pipe_config.sps_cfg.user_info = ...
|
||
tspp2_pipe_open(dev_id, &pipe_config, &iova, &pipe_handle);
|
||
|
||
/* Attache the pipe to the source */
|
||
tspp2_src_pipe_attach(src_handle, pipe_handle, &pull_params);
|
||
/* Open a filter for PID 13 */
|
||
tspp2_filter_open(src_handle, 13, 0x1FFF, &filter_handle);
|
||
|
||
/* Add a raw transmit operation */
|
||
raw_op.type = TSPP2_OP_RAW_TRANSMIT;
|
||
raw_op.params.raw_transmit.input = TSPP2_OP_BUFFER_A;
|
||
raw_op.params.raw_transmit.timestamp_mode = TSPP2_OP_TIMESTAMP_NONE;
|
||
raw_op.params.raw_transmit.skip_ts_packets_with_errors = 0;
|
||
raw_op.params.raw_transmit.output_pipe_handle = pipe_handle;
|
||
tspp2_filter_operations_add(filter_handle, &raw_op, 1);
|
||
|
||
/* Enable filter and source to start getting data */
|
||
tspp2_filter_enable(filter_handle);
|
||
tspp2_source_enable(src_handle);
|
||
|
||
/*
|
||
* Data path: poll pipe (or get notifications from pipe via
|
||
* registered callback).
|
||
*/
|
||
tspp2_pipe_last_address_used_get(pipe_handle, &vaddress);
|
||
|
||
/* Process data... */
|
||
|
||
/* Get and release descriptors: */
|
||
tspp2_pipe_descriptor_get(pipe_handle, &desc);
|
||
tspp2_pipe_descriptor_put(pipe_handle, desc.addr, desc.size, ...);
|
||
|
||
/* Teardown: */
|
||
tspp2_src_disable(src_handle);
|
||
tspp2_filter_disable(filter_handle);
|
||
tspp2_filter_close(filter_handle);
|
||
tspp2_src_pipe_detach(src_handle, pipe_handle);
|
||
tspp2_pipe_close(pipe_handle);
|
||
tspp2_src_close(src_handle);
|
||
tspp2_device_close(dev_id);
|
||
|
||
Debug facilities
|
||
----------------
|
||
The TSPP2 driver supports several debug facilities via debugfs:
|
||
a. Ability to read the status of TSIF and TSPP2 HW registers via debugfs.
|
||
b. Ability to print HW statistics, error and performance counters via debugfs.
|
||
c. Ability to print SW status via debugfs.
|
||
|
||
Design
|
||
======
|
||
The TSPP2 driver is a regular Linux platform driver designed to support the
|
||
TSPP2 HW available on specific Qualcomm SoCs.
|
||
|
||
The driver provides an extensive kernel-space API to allow the client full
|
||
control over the configuration of the TSPP2 HW, while encapsulating HW
|
||
implementation details that are not relevant to the client.
|
||
|
||
The driver enforces HW restrictions and checks for input parameters
|
||
validity, providing a success or failure return value for each API function.
|
||
However, the driver does not enforce any high-level policy with regard to the
|
||
correct use of the TSPP2 HW for various use-cases.
|
||
|
||
Power Management
|
||
================
|
||
The TSPP2 driver prevents the CPU from sleeping while the HW is active by
|
||
using the wakeup_source API. When the HW is not active (i.e., no sources
|
||
configured), the driver indicates it is ready for system suspend by invoking
|
||
__pm_relax(). When the HW needs to be active (i.e., a source has been opened and
|
||
enabled), the driver invokes __pm_stay_awake().
|
||
|
||
In a similar manner, the driver enables the HW clocks only when needed.
|
||
The TSPP2 HW manages power saving automatically when the HW is not used.
|
||
No SW involvement is required.
|
||
|
||
SMP/multi-core
|
||
==============
|
||
The driver uses a mutex for mutual exclusion between kernel API calls.
|
||
A spinlock is used to protect accesses to its internal databases which can be
|
||
performed both from interrupt handler context and from API context.
|
||
|
||
Security
|
||
========
|
||
None.
|
||
|
||
Performance
|
||
===========
|
||
Control operations are not considered as performance critical.
|
||
Most of the control operations are assumed to be fairly uncommon.
|
||
Data-path operations involve only getting descriptors from the pipe and
|
||
releasing them back to the pipe for reuse.
|
||
|
||
Interface
|
||
=========
|
||
Kernel-space API
|
||
----------------
|
||
|
||
Control path API
|
||
-------------------
|
||
|
||
TSPP2 device open / close API:
|
||
------------------------------
|
||
int tspp2_device_open(u32 dev_id);
|
||
|
||
int tspp2_device_close(u32 dev_id);
|
||
|
||
Global configuration for the TSPP2 device:
|
||
------------------------------------------
|
||
int tspp2_config_set(u32 dev_id, const struct tspp2_config *cfg);
|
||
Set device global configuration.
|
||
|
||
int tspp2_config_get(u32 dev_id, struct tspp2_config *cfg);
|
||
Get current device global configuration.
|
||
|
||
Configure Indexing Tables:
|
||
--------------------------
|
||
int tspp2_indexing_prefix_set(u32 dev_id, u8 table_id, u32 value, u32 mask);
|
||
Set prefix value and mask of an indexing table.
|
||
|
||
int tspp2_indexing_patterns_add(u32 dev_id, u8 table_id, const u32 *values,
|
||
const u32 *masks, u8 patterns_num);
|
||
Add patterns to an indexing table.
|
||
|
||
int tspp2_indexing_patterns_clear(u32 dev_id, u8 table_id);
|
||
Clear all patterns of an indexing table
|
||
|
||
Opening and closing Pipes:
|
||
--------------------------
|
||
int tspp2_pipe_open(u32 dev_id, const struct tspp2_pipe_config_params *cfg,
|
||
u32 *iova, u32 *pipe_handle);
|
||
Open a pipe for use.
|
||
|
||
int tspp2_pipe_close(u32 pipe_handle);
|
||
Close an opened pipe.
|
||
|
||
Source configuration:
|
||
---------------------
|
||
int tspp2_src_open(u32 dev_id, enum tspp2_src_input input, u32 *src_handle);
|
||
Open a new source for use.
|
||
|
||
int tspp2_src_close(u32 src_handle);
|
||
Close an opened source.
|
||
|
||
int tspp2_src_parsing_option_set(u32 src_handle,
|
||
enum tspp2_src_parsing_option option, int value);
|
||
Set source parsing configuration option.
|
||
|
||
int tspp2_src_parsing_option_get(u32 src_handle,
|
||
enum tspp2_src_parsing_option option, int *value);
|
||
Get source parsing configuration option.
|
||
|
||
int tspp2_src_sync_byte_config_set(u32 src_handle, int check_sync_byte,
|
||
u8 sync_byte_value);
|
||
Set source sync byte configuration.
|
||
|
||
int tspp2_src_sync_byte_config_get(u32 src_handle, int *check_sync_byte,
|
||
u8 *sync_byte_value);
|
||
Get source sync byte configuration.
|
||
|
||
int tspp2_src_scrambling_config_set(u32 src_handle,
|
||
const struct tspp2_src_scrambling_config *cfg);
|
||
Set source scrambling configuration.
|
||
|
||
int tspp2_src_scrambling_config_get(u32 src_handle,
|
||
struct tspp2_src_scrambling_config *cfg);
|
||
Get source scrambling configuration.
|
||
|
||
int tspp2_src_packet_format_set(u32 src_handle,
|
||
enum tspp2_packet_format format);
|
||
Set source packet size and format.
|
||
|
||
int tspp2_src_pipe_attach(u32 src_handle, u32 pipe_handle,
|
||
const struct tspp2_pipe_pull_mode_params *cfg);
|
||
Attach a pipe to a source.
|
||
|
||
int tspp2_src_pipe_detach(u32 src_handle, u32 pipe_handle);
|
||
Detach a pipe from a source.
|
||
|
||
int tspp2_src_enable(u32 src_handle);
|
||
Enable source (start using it).
|
||
|
||
int tspp2_src_disable(u32 src_handle);
|
||
Disable source (stop using it).
|
||
|
||
int tspp2_src_filters_clear(u32 src_handle);
|
||
Clear all filters from a source.
|
||
|
||
Filter and Operation configuration:
|
||
-----------------------------------
|
||
int tspp2_filter_open(u32 src_handle, u16 pid, u16 mask, u32 *filter_handle);
|
||
Open a new filter and add it to a source.
|
||
|
||
int tspp2_filter_close(u32 filter_handle);
|
||
Close a filter.
|
||
|
||
int tspp2_filter_enable(u32 filter_handle);
|
||
Enable a filter.
|
||
|
||
int tspp2_filter_disable(u32 filter_handle);
|
||
Disable a filter.
|
||
|
||
int tspp2_filter_operations_set(u32 filter_handle,
|
||
const struct tspp2_operation *ops, u8 operations_num);
|
||
Set (add or update) operations to a filter.
|
||
|
||
int tspp2_filter_operations_clear(u32 filter_handle);
|
||
Clear all operations from a filter.
|
||
|
||
int tspp2_filter_current_scrambling_bits_get(u32 filter_handle,
|
||
u8 *scrambling_bits_value);
|
||
Get the current scrambling bits.
|
||
|
||
Events notifications registration:
|
||
----------------------------------
|
||
int tspp2_global_event_notification_register(u32 dev_id,
|
||
u32 global_event_bitmask,
|
||
void (*callback)(void *cookie),
|
||
void *cookie);
|
||
Get notified on a global event.
|
||
|
||
int tspp2_src_event_notification_register(u32 src_handle,
|
||
u32 src_event_bitmask,
|
||
void (*callback)(void *cookie),
|
||
void *cookie);
|
||
Get notified on a source event.
|
||
|
||
int tspp2_filter_event_notification_register(u32 filter_handle,
|
||
u32 filter_event_bitmask,
|
||
void (*callback)(void *cookie),
|
||
void *cookie);
|
||
Get notified on a filter event.
|
||
|
||
Data path API
|
||
----------------
|
||
int tspp2_pipe_descriptor_get(u32 pipe_handle, struct sps_iovec *desc);
|
||
Get a data descriptor from a pipe.
|
||
|
||
int tspp2_pipe_descriptor_put(u32 pipe_handle, u32 addr,
|
||
u32 size, u32 flags);
|
||
Put (release) a descriptor for reuse by the pipe.
|
||
|
||
int tspp2_pipe_last_address_used_get(u32 pipe_handle, u32 *address);
|
||
Get the last address the TSPP2 used.
|
||
|
||
int tspp2_data_write(u32 src_handle, u32 offset, u32 size);
|
||
Write (feed) data to a source.
|
||
|
||
User-space API
|
||
--------------
|
||
The TSPP2 driver does not provide any user-space API, only a kernel-space API.
|
||
The dvb/demux driver, which utilizes the TSPP2 driver (and HW), provides an
|
||
extensive user-space API, allowing upper layers to achieve complex demuxing
|
||
functionality.
|
||
|
||
For further information please refer to Documentation/dvb/qcom-mpq.txt.
|
||
|
||
Driver parameters
|
||
=================
|
||
The TSPP2 driver supports the following module parameter:
|
||
tspp2_iommu_bypass: Bypass VBIF/IOMMU and use physical buffer addresses
|
||
instead. This is mostly useful for debug purposes if something is wrong with
|
||
the IOMMU configuration. Default is false.
|
||
|
||
Platform-dependent parameters (e.g., IRQ numbers) are provided to the driver
|
||
via the device tree mechanism or the platform device data mechanism.
|
||
|
||
Config options
|
||
==============
|
||
To enable the driver, set CONFIG_TSPP2 to y (built-in) or m (kernel module)
|
||
in the kernel configuration menu.
|
||
|
||
Dependencies
|
||
============
|
||
a. The TSPP2 driver uses the SPS driver to control the BAM unit.
|
||
b. The TSPP2 driver uses the ION driver for IOMMU registration and buffer
|
||
mapping. The client is responsible to allocate memory buffers via ION.
|
||
|
||
User space utilities
|
||
====================
|
||
None.
|
||
|
||
Other
|
||
=====
|
||
None.
|
||
|
||
Known issues
|
||
============
|
||
None.
|
||
|
||
To do
|
||
=====
|
||
None.
|