Tuner HAL : patch comments and ATSC3 am: 292d7ecceb am: 0b8028464a

am: 022ee1d3bf

Change-Id: Ib66e3acf6cc3749479d072bfeeb111a10bcf9a89

tv/tuner/1.0/IDemux.hal

@@ -1,3 +1,19 @@
+/*
+ * Copyright (C) 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package android.hardware.tv.tuner@1.0;
 
 import IDemuxCallback;
@@ -236,7 +252,7 @@ interface IDemux {
      *         INVALID_STATE if failed for wrong state.
      *         UNKNOWN_ERROR if failed for other reasons.
      */
-    attachOutputTsFilter(DemuxFilterId filterId) generates (Result result);
+    attachOutputFilter(DemuxFilterId filterId) generates (Result result);
 
     /**
      * Detach one filter from the demux's output.
@@ -250,7 +266,7 @@ interface IDemux {
      *         INVALID_STATE if failed for wrong state.
      *         UNKNOWN_ERROR if failed for other reasons.
      */
-    detachOutputTsFilter(DemuxFilterId filterId) generates (Result result);
+    detachOutputFilter(DemuxFilterId filterId) generates (Result result);
 
     /**
      * Start to take data to the demux's output.

tv/tuner/1.0/IDemuxCallback.hal

@@ -1,3 +1,19 @@
+/*
+ * Copyright (C) 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package android.hardware.tv.tuner@1.0;
 
 interface IDemuxCallback {

tv/tuner/1.0/IDescrambler.hal

@@ -1,3 +1,19 @@
+/*
+ * Copyright (C) 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package android.hardware.tv.tuner@1.0;
 /**
  * Descrambler is used to descramble input data.

tv/tuner/1.0/IFrontend.hal

@@ -143,7 +143,7 @@ interface IFrontend {
      *         cable frontend.
      *         UNKNOWN_ERROR if failed for other reasons.
      */
-    setLnb(ILnb lnb) generates (Result result);
+    setLnb(LnbId lnbId) generates (Result result);
 
     /**
      * Enble or Disable Low Noise Amplifier (LNA).
@@ -156,22 +156,4 @@ interface IFrontend {
      *         UNKNOWN_ERROR if failed for other reasons.
      */
     setLna(bool bEnable) generates (Result result);
-
-    /**
-     *  Sends DiSEqC (Digital Satellite Equipment Control) message.
-     *
-     * Client sends DiSeqc message to DiSEqc compatible device through the
-     * frontend. The response message from the device comes back to the client
-     * through frontend's callback onDiseqcMessage.
-     *
-     * @param diseqcMessage a byte array of data for DiSEqC message which is
-     *        specified by EUTELSAT Bus Functional Specification Version 4.2.
-     *
-     * @return result Result status of the operation.
-     *         SUCCESS if successful,
-     *         INVALID_STATE if the frontend can't send DiSEqc Message, such as
-     *         cable frontend.
-     *         UNKNOWN_ERROR if failed for other reasons.
-     */
-    sendDiseqcMessage(vec<uint8_t> diseqcMessage) generates (Result result);
 };

tv/tuner/1.0/ILnb.hal

@@ -54,6 +54,24 @@ interface ILnb {
      */
     setSatellitePosition(FrontendLnbPosition position) generates (Result result);
 
+    /**
+     *  Sends DiSEqC (Digital Satellite Equipment Control) message.
+     *
+     * Client sends DiSeqc message to DiSEqc to LNB. The response message from
+     * the device comes back to the client through frontend's callback
+     * onDiseqcMessage.
+     *
+     * @param diseqcMessage a byte array of data for DiSEqC message which is
+     *        specified by EUTELSAT Bus Functional Specification Version 4.2.
+     *
+     * @return result Result status of the operation.
+     *         SUCCESS if successful,
+     *         INVALID_STATE if the frontend can't send DiSEqc Message, such as
+     *         cable frontend.
+     *         UNKNOWN_ERROR if failed for other reasons.
+     */
+    sendDiseqcMessage(vec<uint8_t> diseqcMessage) generates (Result result);
+
     /**
      * Releases the LNB instance
      *

tv/tuner/1.0/ITuner.hal

@@ -67,6 +67,16 @@ interface ITuner {
     openDemux()
          generates (Result result, DemuxId demuxId, IDemux demux);
 
+    /**
+     * Retrieve the Demux's Capabilities.
+     *
+     * @return result Result status of the operation.
+     *         SUCCESS if successful,
+     *         UNKNOWN_ERROR if the inquiry failed for other reasons.
+     * @return caps the Demux's Capabilities.
+     */
+    getDemuxCaps() generates (Result result, DemuxCapabilities caps);
+
     /**
      * Create a new instance of Descrambler.
      *
@@ -81,14 +91,13 @@ interface ITuner {
          generates (Result result, IDescrambler descrambler);
 
     /**
-     * Create a new instance of Descrambler.
+     * Retrieve the frontend's information.
-     *
-     * It is used by the client to create a Descrambler instance.
      *
+     * @param frontendId the id of the frontend to be inquiried.
      * @return result Result status of the operation.
      *         SUCCESS if successful,
-     *         UNKNOWN_ERROR if creation failed for other reasons.
+     *         UNKNOWN_ERROR if the inquiry failed for other reasons.
-     * @return descrambler the newly created descrambler interface.
+     * @return info the frontend's information.
      */
     getFrontendInfo(FrontendId frontendId)
         generates (Result result, FrontendInfo info);
@@ -119,6 +128,5 @@ interface ITuner {
      */
     openLnbById(LnbId lnbId)
         generates (Result result, ILnb lnb);
-
 };
 

tv/tuner/1.0/types.hal

@@ -43,7 +43,7 @@ enum FrontendType : uint32_t {
     ANALOG,
     /* Advanced Television Systems Committee (ATSC) Standard A/72. */
     ATSC,
-    /* Advanced Television Systems Committee (ATSC 3.0) Standard A/330. */
+    /* Advanced Television Systems Committee (ATSC 3.0) Standard A/300. */
     ATSC3,
     /**
      * Digital Video Broadcasting - Cable
@@ -63,11 +63,11 @@ enum FrontendType : uint32_t {
      */
     DVBT,
     /* Integrated Services Digital Broadcasting-Satellite (ISDB-S)
-     * ARIB SDT-B20 is technical document of ISDB-S.
+     * ARIB STD-B20 is technical document of ISDB-S.
      */
     ISDBS,
     /* Integrated Services Digital Broadcasting-Satellite (ISDB-S)
-     * ARIB TR-B15 is technical document of ISDB-S3.
+     * ARIB STD-B44 is technical document of ISDB-S3.
      */
     ISDBS3,
     /* Integrated Services Digital Broadcasting-Terrestrial (ISDB-T or SBTVD)
@@ -164,8 +164,10 @@ enum FrontendInnerFec : uint64_t {
 @export
 enum FrontendAtscModulation : uint32_t {
     UNDEFINED = 0,
-    MOD_8VSB = 1 << 0,
+    /** hardware is able to detect and set modulation automatically */
-    MOD_16VSB = 1 << 1,
+    AUTO      = 1 << 0,
+    MOD_8VSB  = 1 << 2,
+    MOD_16VSB = 1 << 3,
 };
 
 /**
@@ -191,12 +193,14 @@ struct FrontendAtscCapabilities {
 @export
 enum FrontendAtsc3Modulation : uint32_t {
     UNDEFINED = 0,
-    MOD_QPSK = 1 << 0,
+    /** hardware is able to detect and set modulation automatically */
-    MOD_16QAM = 1 << 1,
+    AUTO        = 1 << 0,
-    MOD_64QAM = 1 << 2,
+    MOD_QPSK    = 1 << 1,
-    MOD_256QAM = 1 << 3,
+    MOD_16QAM   = 1 << 2,
-    MOD_1024QAM = 1 << 4,
+    MOD_64QAM   = 1 << 3,
-    MOD_4096QAM = 1 << 5,
+    MOD_256QAM  = 1 << 4,
+    MOD_1024QAM = 1 << 5,
+    MOD_4096QAM = 1 << 6,
 };
 
 /**
@@ -205,9 +209,11 @@ enum FrontendAtsc3Modulation : uint32_t {
 @export
 enum FrontendAtsc3Bandwidth : uint32_t {
     UNDEFINED = 0,
-    BANDWIDTH_8MHZ = 1 << 0,
+    /** hardware is able to detect and set bandwidth automatically */
-    BANDWIDTH_7MHZ = 1 << 1,
+    AUTO = 1 << 0,
-    BANDWIDTH_6MHZ = 1 << 2,
+    BANDWIDTH_6MHZ = 1 << 1,
+    BANDWIDTH_7MHZ = 1 << 2,
+    BANDWIDTH_8MHZ = 1 << 3,
 };
 
 /**
@@ -215,9 +221,11 @@ enum FrontendAtsc3Bandwidth : uint32_t {
  */
 @export
 enum FrontendAtsc3TimeInterleaveMode : uint32_t {
-    UNDEFINED,
+    UNDEFINED = 0,
-    CTI,
+    /** hardware is able to detect and set TimeInterleaveMode automatically */
-    HTI,
+    AUTO = 1 << 0,
+    CTI  = 1 << 1,
+    HTI  = 1 << 2,
 };
 
 /**
@@ -247,13 +255,39 @@ enum FrontendAtsc3CodeRate : uint32_t {
  */
 @export
 enum FrontendAtsc3Fec : uint32_t {
-    UNDEFINED,
+    UNDEFINED = 0,
-    BCH_LDPC_16K,
+    /** hardware is able to detect and set FEC automatically */
-    BCH_LDPC_64K,
+    AUTO     = 1 << 0,
-    CRC_LDPC_16K,
+    BCH_LDPC_16K = 1 << 1,
-    CRC_LDPC_64K,
+    BCH_LDPC_64K = 1 << 2,
-    LDPC_16K,
+    CRC_LDPC_16K = 1 << 3,
-    LDPC_64K,
+    CRC_LDPC_64K = 1 << 4,
+    LDPC_16K     = 1 << 5,
+    LDPC_64K     = 1 << 6,
+};
+
+/**
+ *  Demodulator Output Format for an ATSC3 Frontend.
+ */
+@export
+enum FrontendAtsc3DemodOutputFormat : uint8_t {
+    /** Dummy. Scan uses this. */
+    UNDEFINED = 0,
+    /** ALP format. Typically used in US region. */
+    ATSC3_LINKLAYER_PACKET = 1 << 0,
+    /** BaseBand packet format. Typically used in Korea region. */
+    BASEBAND_PACKET        = 1 << 1,
+};
+
+/**
+ *  PLP basis Signal Settings for an ATSC3 Frontend.
+ */
+struct FrontendAtsc3PlpSettings {
+    uint8_t plpId;
+    FrontendAtsc3Modulation modulation;
+    FrontendAtsc3TimeInterleaveMode interleaveMode;
+    FrontendAtsc3CodeRate codeRate;
+    FrontendAtsc3Fec fec;
 };
 
 /**
@@ -262,21 +296,28 @@ enum FrontendAtsc3Fec : uint32_t {
 struct FrontendAtsc3Settings {
     /** Signal frequency in Hertz */
     uint32_t frequency;
+    /** Bandwidth of tuning band. */
     FrontendAtsc3Bandwidth bandwidth;
-    FrontendAtsc3TimeInterleaveMode interleaveMode;
+    FrontendAtsc3DemodOutputFormat demodOutputFormat;
-    FrontendAtsc3CodeRate codeRate;
+    vec<FrontendAtsc3PlpSettings> plpSettings;
-    FrontendAtsc3Fec fec;
-    vec<uint8_t> plpIdList;
 };
 
 /**
  *  Capabilities for ATSC3 Frontend.
  */
 struct FrontendAtsc3Capabilities {
-    /** Modulation capability */
-    bitfield<FrontendAtsc3Modulation> modulationCap;
     /** Bandwidth capability */
     bitfield<FrontendAtsc3Bandwidth> bandwidthCap;
+    /** Modulation capability */
+    bitfield<FrontendAtsc3Modulation> modulationCap;
+    /** TimeInterleaveMode capability */
+    bitfield<FrontendAtsc3TimeInterleaveMode> timeInterleaveModeCap;
+    /** CodeRate capability */
+    bitfield<FrontendAtsc3CodeRate> codeRateCap;
+    /** FEC capability */
+    bitfield<FrontendAtsc3Fec> fecCap;
+    /** Demodulator Output Format capability */
+    bitfield<FrontendAtsc3DemodOutputFormat> demodOutputFormatCap;
 };
 
 /**
@@ -647,7 +688,7 @@ enum FrontendIsdbsCoderate : uint32_t {
 @export
 enum FrontendIsdbsStreamIdType : uint32_t {
     STREAM_ID,
-    RELATIVE_STREAM_ID,
+    RELATIVE_STREAM_NUMBER,
 };
 
 /**
@@ -845,6 +886,7 @@ enum FrontendAnalogSifStandard : uint32_t {
     M_EIA_J = 1 << 13,
     I_NICAM = 1 << 14,
     L_NICAM = 1 << 15,
+    L_PRIME = 1 << 16,
 };
 
 /**
@@ -907,10 +949,20 @@ enum FrontendScanMessageType : uint32_t {
     PLP_IDS,
     /** Locked group Ids for DVBT2 frontend. */
     GROUP_IDS,
-    /** Locked the number of the Plps. */
+    /** Stream Ids. */
-   INPUT_STREAM_IDS,
+    INPUT_STREAM_IDS,
     /** Locked signal stardard.  */
     STANDARD,
+    /** PLP status in a tuned frequency band for ATSC3 frontend. */
+    ATSC3_PLP_INFO,
+};
+
+/**
+ *  ATSC3.0 PLP information for scan
+ */
+struct FrontendScanAtsc3PlpInfo {
+    uint8_t plpId;
+    bool bLlsFlag;
 };
 
 /**
@@ -927,11 +979,13 @@ safe_union FrontendScanMessage {
     uint32_t symbolRate;
     vec<uint8_t> plpIds;
     vec<uint8_t> groupIds;
-    vec<uint8_t> inputStreamIds;
+    vec<uint16_t> inputStreamIds;
     safe_union standard {
         FrontendDvbsStandard sStd;
         FrontendDvbtStandard tStd;
     } std;
+    /** A list of PLP status in a tuned frequency band for ATSC3 frontend. */
+    vec<FrontendScanAtsc3PlpInfo> atsc3PlpInfos;
 };
 
 /**
@@ -940,17 +994,17 @@ safe_union FrontendScanMessage {
 @export
 enum FrontendEventType : uint32_t {
     /**
-     * If frontend locked the signal which is specified by tune method, HAL sent
+     * If frontend locked the signal which is specified by tune method, HAL sends
      * Locked event.
      */
     LOCKED,
     /**
      * If frontend can't locked the signal which is specified by tune method,
-     * HAL sent NO_SIGNAL event.
+     * HAL sends NO_SIGNAL event.
      */
     NO_SIGNAL,
     /**
-     * If frontend detect that the locked signal get lost, HAL sent LOST_LOCK
+     * If frontend detect that the locked signal get lost, HAL sends LOST_LOCK
      * event.
      */
     LOST_LOCK,
@@ -977,15 +1031,15 @@ enum FrontendEventType : uint32_t {
  */
 @export
 enum FrontendStatusType : uint32_t {
-    /** Lock status for RF or Demod. */
+    /** Lock status for Demod. */
-    LOCK,
+    DEMOD_LOCK,
     /** Signal to Noise Ratio. */
     SNR,
     /** Bit Error Ratio. */
     BER,
     /** Packages Error Ratio. */
     PER,
-    /** Bit Error Ratio befor FEC. */
+    /** Bit Error Ratio before FEC. */
     PRE_BER,
     /*
      * Signal Quality (0..100). Good data over total data in percent can be
@@ -993,7 +1047,7 @@ enum FrontendStatusType : uint32_t {
      */
     SIGNAL_QUALITY,
     /** Signal Strength. */
-    SIGGAL_STRENGTH,
+    SIGNAL_STRENGTH,
     /** Symbol Rate. */
     SYMBOL_RATE,
     /** Forward Error Correction Type. */
@@ -1008,21 +1062,62 @@ enum FrontendStatusType : uint32_t {
     PLP_ID,
     /** Status for Emergency Warning Broadcasting System. */
     EWBS,
+    /** Automatic Gain Control. */
+    AGC,
+    /** Low Noise Amplifier. */
+    LNA,
+    /** Lock status for stream. */
+    STREAM_LOCK,
+    /** Error status by layer. */
+    LAYER_ERROR,
+    /** CN value by VBER. */
+    VBER_CN,
+    /** CN value by LBER. */
+    LBER_CN,
+    /** CN value by XER. */
+    XER_CN,
+    /** Moduration Error Ratio. */
+    MER,
+    /** Difference between tuning frequency and actual locked frequency. */
+    FREQ_OFFSET,
+    /* Hierarchy for DVBT. */
+    HIERARCHY,
+    /** Lock status for RF. */
+    RF_LOCK,
+    /** PLP information in a frequency band for ATSC3.0 frontend. */
+    ATSC3_PLP_INFO,
 };
 
+/**
+ * Status for each tuning PLPs
+ */
+struct FrontendStatusAtsc3PlpInfo {
+    /** PLP Id value. */
+    uint8_t plpId;
+    /** Demod Lock/Unlock status of this particular PLP. */
+    bool isLocked;
+    /** Uncorrectable Error Counts (UEC) of this particular PLP since last tune operation. */
+    uint32_t uec;
+};
+
+
 /**
  * Modulation Type for Frontend's status.
  */
 safe_union FrontendModulationStatus {
+    FrontendDvbcModulation dvbc;
     FrontendDvbsModulation dvbs;
-    FrontendAtsc3Modulation atsc3;
+    FrontendIsdbsModulation isdbs;
+    FrontendIsdbs3Modulation isdbs3;
+    FrontendIsdbtModulation isdbt;
 };
 
 /**
  *  The status for Frontend.
  */
 safe_union FrontendStatus {
-    bool isLocked;
+    /** Lock status for Demod in True/False. */
+    bool isDemodLocked;
     /** SNR value measured by 0.001 dB. */
     int32_t snr;
     /** The number of error bit per 1 billion bits. */
@@ -1043,6 +1138,25 @@ safe_union FrontendStatus {
     FrontendLnbVoltage lnbVoltage;
     uint8_t plpId;
     bool isEWBS;
+    /** AGC value is normalized from 0 to 255. */
+    uint8_t agc;
+    bool isLnaOn;
+    bool isStreamLock;
+    vec<bool> isLayerError;
+    /** CN value by VBER measured by 0.001 dB */
+    int32_t vberCn;
+    /** CN value by LBER measured by 0.001 dB */
+    int32_t lberCn;
+    /** CN value by XER measured by 0.001 dB */
+    int32_t xerCn;
+    /** MER value measured by 0.001 dB */
+    int32_t mer;
+    /** Frequency difference in Hertz. */
+    int32_t freqOffset;
+    FrontendDvbtHierarchy hierarchy;
+    bool isRfLocked;
+    /** A list of PLP status for tuned PLPs for ATSC3 frontend. */
+    vec<FrontendStatusAtsc3PlpInfo> plpInfo;
 };
 
 /**
@@ -1121,7 +1235,6 @@ enum FrontendLnbPosition : int32_t {
     POSITION_B,
 };
 
-
 /* Demux ID is used to associate with a hardware demux resource. */
 typedef uint32_t DemuxId;
 
@@ -1150,7 +1263,7 @@ enum DemuxFilterType : uint32_t {
      */
     AUDIO,
     /**
-     * A filter to filter Vidoe Metadata out from input stream.
+     * A filter to filter Video Metadata out from input stream.
      */
     VIDEO,
     /**
@@ -1475,6 +1588,8 @@ enum DemuxDataFormat : uint32_t {
     PES,
     /* Data is Elementary Stream. */
     ES,
+    /* Data is TLV (type-length-value) Stream for JP SHV */
+    SHV_TLV,
 };
 
 /**
@@ -1534,6 +1649,10 @@ enum DemuxInputStatus : uint32_t {
     SPACE_FULL         = 1 << 3,
 };
 
+/**
+ *  The Settings for the demux's input.
+ */
+@export
 struct DemuxInputSettings {
     /**
      * Register for interested status events so that the HAL can send these
@@ -1559,3 +1678,30 @@ struct DemuxInputSettings {
      */
     uint8_t packetSize;
 };
+
+/**
+ *  Capabilities for Demux.
+ */
+@export
+struct DemuxCapabilities {
+    /* The number of Demux to be supported. */
+    uint32_t numDemux;
+    /* The number of Input to be supported. */
+    uint32_t numInput;
+    /* The number of Output to be supported. */
+    uint32_t numOutput;
+    /* The number of TS Filter to be supported. */
+    uint32_t numTsFilter;
+    /* The number of Section Filter to be supported. */
+    uint32_t numSectionFilter;
+    /* The number of Audio Filter to be supported. */
+    uint32_t numAudioFilter;
+    /* The number of Video Filter to be supported. */
+    uint32_t numVideoFilter;
+    /* The number of PES Filter to be supported. */
+    uint32_t numPesFilter;
+    /* The number of PCR Filter to be supported. */
+    uint32_t numPcrFilter;
+    /* The maximum number of bytes is supported in the mask of Section Filter. */
+    uint32_t numBytesInSectionFilter;
+};