Add filter function to Demux interface and Add program info to Descrambler
bug: 135708935
Test: Manual
Change-Id: Iacaebdac6a8ce08ca47ae272be13d51fbd502959
diff --git a/tv/tuner/1.0/IDemux.hal b/tv/tuner/1.0/IDemux.hal
index 938bc44..2d7b275 100644
--- a/tv/tuner/1.0/IDemux.hal
+++ b/tv/tuner/1.0/IDemux.hal
@@ -23,6 +23,153 @@
setFrontendDataSource(FrontendId frontendId) generates (Result result);
/**
+ * Add a filter to the demux
+ *
+ * It is used by the client to add a filter to the demux.
+ *
+ * @param type the type of the filter to be added.
+ * @param bufferSize the buffer size of the filter to be added. It's used to
+ * create a FMQ(Fast Message Queue) to hold data output from the filter.
+ * @param cb the callback for the filter to be used to send notifications
+ * back to the client.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ * @return filterId the ID of the newly added filter.
+ */
+ addFilter(DemuxFilterType type, uint32_t bufferSize, IDemuxCallback cb)
+ generates (Result result, DemuxFilterId filterId);
+
+ /**
+ * Get the descriptor of the filter's FMQ
+ *
+ * It is used by the client to get the descriptor of the filter's Fast
+ * Message Queue. The data in FMQ is filtered out from MPEG transport
+ * stream. The data is origanized to data blocks which may have
+ * different length. The length's information of one or multiple data blocks
+ * is sent to client throught DemuxFilterEvent.
+ *
+ * @param filterId the ID of the filter.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_ARGUMENT if failed for wrong filter ID.
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ * @return queue the descriptor of the filter's FMQ
+ */
+ getFilterQueueDesc(DemuxFilterId filterId)
+ generates (Result result, fmq_sync<uint8_t> queue);
+
+ /**
+ * Configure the filter.
+ *
+ * It is used by the client to configure the filter so that it can filter out
+ * intended data.
+ *
+ * @param filterId the ID of the filter.
+ * @param settings the settings of the filter.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_ARGUMENT if failed for wrong filter ID.
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ */
+ configureFilter(DemuxFilterId filterId, DemuxFilterSettings settings)
+ generates(Result result);
+
+ /**
+ * Start the filter.
+ *
+ * It is used by the client to ask the filter to start filterring data.
+ *
+ * @param filterId the ID of the filter.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_ARGUMENT if failed for wrong filter ID.
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ */
+ startFilter(DemuxFilterId filterId) generates (Result result);
+
+ /**
+ * Stop the filter.
+ *
+ * It is used by the client to ask the filter to stop filterring data.
+ * It won't discard the data already filtered out by the filter. The filter
+ * will be stopped and removed automatically if the demux is closed.
+ *
+ * @param filterId the ID of the filter.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_ARGUMENT if failed for wrong filter ID.
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ */
+ stopFilter(DemuxFilterId filterId) generates (Result result);
+
+ /**
+ * Flush the filter.
+ *
+ * It is used by the client to ask the filter to flush the data which is
+ * already produced but not consumed yet.
+ *
+ * @param filterId the ID of the filter.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_ARGUMENT if failed for wrong filter ID.
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ */
+ flushFilter(DemuxFilterId filterId) generates (Result result);
+
+ /**
+ * Remove a filter from the demux
+ *
+ * It is used by the client to remove a filter from the demux.
+ *
+ * @param filterId the ID of the removed filter.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_ARGUMENT if failed for wrong filter ID.
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ */
+ removeFilter(DemuxFilterId filterId) generates (Result result);
+
+ /**
+ * Get hardware sync ID for audio and video.
+ *
+ * It is used by the client to get the hardware sync ID for audio and video.
+ *
+ * @param filterId the ID of the filter.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_ARGUMENT if failed for a wrong filter ID.
+ * UNKNOWN_ERROR if failed for other reasons.
+ * @return avSyncHwId the id of hardware A/V sync.
+ */
+ getAvSyncHwId(DemuxFilterId filterId)
+ generates (Result result, AvSyncHwId avSyncHwId);
+
+ /**
+ * Get current time stamp to use for A/V sync
+ *
+ * It is used by the client to get current time stamp for A/V sync. HW is
+ * supported to increment and maintain current time stamp.
+ *
+ * @param avSyncHwId the hardware id of A/V sync.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_ARGUMENT if failed for a wrong hardware ID of A/V sync.
+ * UNKNOWN_ERROR if failed for other reasons.
+ * @return time the current time stamp of hardware A/V sync. The time stamp
+ * based on 90KHz has the same format as PTS (Presentation Time Stamp).
+ */
+ getAvSyncTime(AvSyncHwId avSyncHwId)
+ generates (Result result, uint64_t time);
+
+ /**
* Close the Demux instance
*
* It is used by the client to release the demux instance. HAL clear
diff --git a/tv/tuner/1.0/IDemuxCallback.hal b/tv/tuner/1.0/IDemuxCallback.hal
index c67c5f2..7efd2c3 100644
--- a/tv/tuner/1.0/IDemuxCallback.hal
+++ b/tv/tuner/1.0/IDemuxCallback.hal
@@ -6,6 +6,14 @@
*
* @param filterEvent a demux filter event.
*/
- oneway onFilterEvent(DemuxFilterEvent filterEvent);
+ oneway onFilterEvent(DemuxFilterEvent filterEvent);
+
+ /**
+ * Notify the client a new status of a demux filter.
+ *
+ * @param filterId the demux filter ID.
+ * @param status a new status of the demux filter.
+ */
+ oneway onFilterStatus(DemuxFilterId filterId, DemuxFilterStatus status);
};
diff --git a/tv/tuner/1.0/IDescrambler.hal b/tv/tuner/1.0/IDescrambler.hal
index 4d6cf3c..d078657 100644
--- a/tv/tuner/1.0/IDescrambler.hal
+++ b/tv/tuner/1.0/IDescrambler.hal
@@ -1,11 +1,9 @@
package android.hardware.tv.tuner@1.0;
-
/**
* Descrambler is used to descramble input data.
*
*/
interface IDescrambler {
-
/**
* Set a demux as source of the descrambler
*
@@ -13,6 +11,7 @@
* descrambler. A descrambler instance can have only one source, and
* this method can be only called once.
*
+ * @param demuxId the id of the demux to be used as descrambler's source.
* @return result Result status of the operation.
* SUCCESS if successful,
* INVALID_STATE if failed for wrong state.
@@ -21,6 +20,51 @@
setDemuxSource(DemuxId demuxId) generates (Result result);
/**
+ * Set a key token to link descrambler to a key slot
+ *
+ * It is used by the client to link a hardware key slot to a descrambler.
+ * A descrambler instance can have only one key slot to link, but a key
+ * slot can hold a few keys for different purposes.
+ *
+ * @param keyToken the token to be used to link the key slot.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ */
+ setKeyToken(TunerKeyToken keyToken) generates (Result result);
+
+ /**
+ * Add packets' PID to the descrambler for descrambling
+ *
+ * It is used by the client to specify Package ID (PID) of packets which the
+ * descrambler start to descramble. Multiple PIDs can be added into one
+ * descrambler instance because descambling can happen simultaneously on
+ * packets from different PIDs.
+ *
+ * @param pid the PID of packets to start to be descrambled.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ */
+ addPid(DemuxTpid pid) generates (Result result);
+
+ /**
+ * Remove packets' PID from the descrambler
+ *
+ * It is used by the client to specify Package ID (PID) of packets which the
+ * descrambler stop to descramble.
+ *
+ * @param pid the PID of packets to stop to be descrambled.
+ * @return result Result status of the operation.
+ * SUCCESS if successful,
+ * INVALID_STATE if failed for wrong state.
+ * UNKNOWN_ERROR if failed for other reasons.
+ */
+ removePid(DemuxTpid pid) generates (Result result);
+
+ /**
* Release the descrambler instance
*
* It is used by the client to release the descrambler instance. HAL clear
@@ -30,6 +74,6 @@
* SUCCESS if successful,
* UNKNOWN_ERROR if failed for other reasons.
*/
- close() generates (Result result);
+ close() generates (Result result);
};
diff --git a/tv/tuner/1.0/ITuner.hal b/tv/tuner/1.0/ITuner.hal
index 61a9d63..a0f3e8e 100644
--- a/tv/tuner/1.0/ITuner.hal
+++ b/tv/tuner/1.0/ITuner.hal
@@ -42,6 +42,7 @@
*
* It is used by the client to create a frontend instance.
*
+ * @param frontendId the id of the frontend to be opened.
* @return result Result status of the operation.
* SUCCESS if successful,
* UNKNOWN_ERROR if creation failed for other reasons.
diff --git a/tv/tuner/1.0/types.hal b/tv/tuner/1.0/types.hal
index 3fa9641..4522db2 100644
--- a/tv/tuner/1.0/types.hal
+++ b/tv/tuner/1.0/types.hal
@@ -170,7 +170,7 @@
*/
VIDEO,
/**
- * A filter to set PCR channel from input stream.
+ * A filter to set PCR (Program Clock Reference) channel from input stream.
*/
PCR,
/**
@@ -179,11 +179,303 @@
RECORD,
};
+/* Packet ID is used to specify packets in transport stream. */
+typedef uint16_t DemuxTpid;
+
+@export
+enum Constant : uint16_t {
+ /**
+ * An invalid packet ID in transport stream according to ISO/IEC 13818-1.
+ */
+ INVALID_TPID = 0xFFFF,
+ /**
+ * An invalid Stream ID.
+ */
+ INVALID_STREAM_ID = 0xFFFF,
+};
+
+/**
+ * A status of data in the filter's buffer.
+ */
+@export
+enum DemuxFilterStatus : uint8_t {
+ /**
+ * The data in the filter buffer is ready to be read.
+ */
+ DATA_READY = 1 << 0,
+ /**
+ * The available data amount in the filter buffer is at low level which is
+ * set to 25 percent by default.
+ */
+ LOW_WATER = 1 << 1,
+ /**
+ * The available data amount in the filter buffer is at high level which is
+ * set to 75 percent by default.
+ */
+ HIGH_WATER = 1 << 2,
+ /**
+ * The data in the filter buffer is full and newly filtered data is being
+ * discarded.
+ */
+ OVERFLOW = 1 << 3,
+};
+
+/**
+ * Bits Setting for Section Filter.
+ */
+struct DemuxFilterSectionBits {
+ /* The bytes are configured for Section Filter */
+ vec<uint8_t> filter;
+ /* Active bits in the configured bytes to be used for filtering */
+ vec<uint8_t> mask;
+ /*
+ * Do positive match at the bit position of the configured bytes when the
+ * bit at same position of the mode is 0.
+ * Do negative match at the bit position of the configured bytes when the
+ * bit at same position of the mode is 1.
+ */
+ vec<uint8_t> mode;
+};
+
+/**
+ * Filter Settings for Section data according to ISO/IEC 13818-1.
+ */
+struct DemuxFilterSectionSettings {
+ DemuxTpid tpid;
+ DemuxFilterSectionBits bits;
+ /* Table ID for Section Filter */
+ uint16_t tableId;
+ /* Version number for Section Filter */
+ uint16_t version;
+ /* true if the filter checks CRC and discards data with wrong CRC */
+ bool checkCrc;
+ /* true if the filter repeats the data with the same version */
+ bool isRepeat;
+ /* true if the filter output raw data */
+ bool isRaw;
+};
+
+/* Stream ID is used to specify one elementary stream */
+typedef uint16_t DemuxStreamId;
+
+/**
+ * Filter Settings for a PES Data.
+ */
+struct DemuxFilterPesDataSettings {
+ DemuxTpid tpid;
+ DemuxStreamId streamId;
+ /* true if the filter output raw data */
+ bool bIsRaw;
+};
+
+/**
+ * Filter Settings for a TS Data.
+ */
+struct DemuxFilterTsSettings {
+ DemuxTpid tpid;
+};
+
+/**
+ * Filter Settings for a Audio.
+ */
+struct DemuxFilterAudioSettings {
+ DemuxTpid tpid;
+ /**
+ * true if the filter output goes to decoder directly in pass through mode.
+ */
+ bool bPassthrough;
+};
+
+/**
+ * Filter Settings for a Video.
+ */
+struct DemuxFilterVideoSettings {
+ DemuxTpid tpid;
+ /**
+ * true if the filter output goes to decoder directly in pass through mode.
+ */
+ bool bPassthrough;
+};
+
+/**
+ * Filter Settings for a PCR (Program Clock Reference).
+ */
+struct DemuxFilterPcrSettings {
+ DemuxTpid tpid;
+};
+
+/**
+ * Indexes can be tagged through TS (Transport Stream) header.
+ */
+@export
+enum DemuxTsIndex : uint32_t {
+ FIRST_PACKET = 1 << 0,
+ PAYLOAD_UNIT_START_INDICATOR = 1 << 1,
+ CHANGE_TO_NOT_SCRAMBLED = 1 << 2,
+ CHANGE_TO_EVEN_SCRAMBLED = 1 << 3,
+ CHANGE_TO_ODD_SCRAMBLED = 1 << 4,
+ DISCONTINUITY_INDICATOR = 1 << 5,
+ RANDOM_ACCESS_INDICATOR = 1 << 6,
+ PRIORITY_INDICATOR = 1 << 7,
+ PCR_FLAG = 1 << 8,
+ OPCR_FLAG = 1 << 9,
+ SPLICING_POINT_FLAG = 1 << 10,
+ PRIVATE_DATA = 1 << 11,
+ ADAPTATION_EXTENSION_FLAG = 1 << 12,
+};
+
+/**
+ * A mask of TS indexes
+ *
+ * It's a combination of TS indexes.
+ */
+typedef bitfield<DemuxTsIndex> DemuxTsIndexMask;
+
+/**
+ * Indexes can be tagged by Start Code in PES (Packetized Elementary Stream)
+ * according to ISO/IEC 13818-1.
+ */
+@export
+enum DemuxScIndex : uint32_t {
+ /* Start Code is for a new I Frame */
+ I_FRAME = 1 << 0,
+ /* Start Code is for a new P Frame */
+ P_FRAME = 1 << 1,
+ /* Start Code is for a new B Frame */
+ B_FRAME = 1 << 2,
+ /* Start Code is for a new Sequence */
+ SEQUENCE = 1 << 3,
+};
+
+/**
+ * A mask of Start Code Indexes
+ *
+ * It's a combination of Start Code Indexes.
+ */
+typedef bitfield<DemuxScIndex> DemuxScIndexMask;
+
+/* Index type to be used in the filter for record */
+@export
+enum DemuxRecordIndexType : uint32_t {
+ /* Don't use index */
+ NONE,
+ /* Use TS index */
+ TS,
+ /* Use Start Code index */
+ SC,
+};
+
+/**
+ * Filter Settings for Record data.
+ */
+struct DemuxFilterRecordSettings {
+ DemuxTpid tpid;
+ DemuxRecordIndexType indexType;
+ safe_union IndexMask {
+ DemuxTsIndexMask tsIndexMask;
+ DemuxScIndexMask scIndexMask;
+ } indexMask;
+};
+
+/**
+ * Filter Settings.
+ */
+safe_union DemuxFilterSettings {
+ DemuxFilterSectionSettings section;
+ DemuxFilterPesDataSettings pesData;
+ DemuxFilterTsSettings ts;
+ DemuxFilterAudioSettings audio;
+ DemuxFilterVideoSettings video;
+ DemuxFilterPcrSettings pcr;
+ DemuxFilterRecordSettings record;
+};
+
+/**
+ * The bits of EventFlag in FMQ (Fast message queue) are used by client to
+ * notify HAL the status change.
+ */
+@export
+enum DemuxQueueNotifyBits : uint32_t {
+ /* client writes data and notify HAL the data is ready. */
+ DATA_READY = 1 << 0,
+ /* client reads data and notify HAL the data is consumed. */
+ DATA_CONSUMED = 1 << 1
+};
+
+/**
+ * Filter Event for Section Filter.
+ */
+struct DemuxFilterSectionEvent {
+ /* Table ID of filtered data */
+ uint16_t tableId;
+ /* Version number of filtered data */
+ uint16_t version;
+ /* Section number of filtered data */
+ uint16_t sectionNum;
+ /* Data size in bytes of filtered data */
+ uint16_t dataLength;
+};
+
+/**
+ * Filter Event for Audio or Video Filter.
+ */
+struct DemuxFilterMediaEvent {
+ /* Presentation Time Stamp for audio or video frame. It based on 90KHz has
+ * the same format as PTS (Presentation Time Stamp).
+ */
+ uint64_t pts;
+ /* Data size in bytes of audio or video frame */
+ uint16_t dataLength;
+ /* A handle associated to the memory where audio or video data stays. */
+ handle secureMemory;
+};
+
+/**
+ * Filter Event for PES data.
+ */
+struct DemuxFilterPesEvent {
+ DemuxStreamId streamId;
+ /* Data size in bytes of PES data */
+ uint16_t dataLength;
+};
+
+/**
+ * Filter Event for Record data.
+ */
+struct DemuxFilterRecordEvent {
+ DemuxTpid tpid;
+ /* Indexes of record output */
+ safe_union IndexMask {
+ DemuxTsIndexMask tsIndexMask;
+ DemuxScIndexMask scIndexMask;
+ } indexMask;
+ /* Packet number from beginning of the filter's output */
+ uint64_t packetNum;
+};
+
/**
* Filter Event.
*/
struct DemuxFilterEvent {
- DemuxFilterId filterId;
- DemuxFilterType filterType;
+ DemuxFilterId filterId;
+ DemuxFilterType filterType;
+ safe_union Event {
+ DemuxFilterSectionEvent section;
+ DemuxFilterMediaEvent media;
+ DemuxFilterPesEvent pes;
+ DemuxFilterRecordEvent ts;
+ };
+ /* An array of events */
+ vec<Event> events;
};
+/**
+ * A hardware resource ID to be used for audio and video hardware sync.
+ */
+typedef uint32_t AvSyncHwId;
+
+/**
+ * A token to be used to link descrambler and key slot. It's opaque to
+ * framework and apps.
+ */
+typedef vec<uint8_t> TunerKeyToken;