From 5e86eed7dff844c5ccb0f96821429f18bcfae4a4 Mon Sep 17 00:00:00 2001
From: Hongguang <hgchen@google.com>
Date: Mon, 13 Dec 2021 17:06:34 -0800
Subject: [PATCH] Update some comments for tuner AIDL HAL.

*) Clarify the meaning and unit of FrontendStatus.
*) Add comment for STC ready support.
*) Support for control signal (e.g. TMCC) change monitoring

Bug: 183634950
Bug: 202247846
Bug: 183630794
Test: Make
Change-Id: I3c48993c354e865b0edfe56adbd34c7fce120efc
---
 .../hardware/tv/tuner/DemuxFilterStatus.aidl  |  3 +-
 .../hardware/tv/tuner/FrontendEventType.aidl  |  4 ++-
 .../hardware/tv/tuner/FrontendStatus.aidl     | 28 +++++++++++++++++++
 3 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/tv/tuner/aidl/android/hardware/tv/tuner/DemuxFilterStatus.aidl b/tv/tuner/aidl/android/hardware/tv/tuner/DemuxFilterStatus.aidl
index f07c26f4de..e6f3b63b95 100644
--- a/tv/tuner/aidl/android/hardware/tv/tuner/DemuxFilterStatus.aidl
+++ b/tv/tuner/aidl/android/hardware/tv/tuner/DemuxFilterStatus.aidl
@@ -24,7 +24,8 @@ package android.hardware.tv.tuner;
 @Backing(type="byte")
 enum DemuxFilterStatus {
     /**
-     * The data in the filter buffer is ready to be read.
+     * The data in the filter buffer is ready to be read. It can also be used to know the STC
+     * (System Time Clock) ready status if it's PCR filter.
      */
     DATA_READY = 1 << 0,
 
diff --git a/tv/tuner/aidl/android/hardware/tv/tuner/FrontendEventType.aidl b/tv/tuner/aidl/android/hardware/tv/tuner/FrontendEventType.aidl
index 40b5161b3b..501dc1f7a1 100644
--- a/tv/tuner/aidl/android/hardware/tv/tuner/FrontendEventType.aidl
+++ b/tv/tuner/aidl/android/hardware/tv/tuner/FrontendEventType.aidl
@@ -24,7 +24,9 @@ package android.hardware.tv.tuner;
 @Backing(type="int")
 enum FrontendEventType {
     /**
-     * The frontend has locked to the signal specified by the tune method.
+     * The frontend has locked to the signal specified by the tune method. It can also be notified
+     * after signal is locked if the signal attributes transmission parameter of the signal is
+     * changed (e.g., Modulation).
      */
     LOCKED,
 
diff --git a/tv/tuner/aidl/android/hardware/tv/tuner/FrontendStatus.aidl b/tv/tuner/aidl/android/hardware/tv/tuner/FrontendStatus.aidl
index 234e18392e..6e6f315d38 100644
--- a/tv/tuner/aidl/android/hardware/tv/tuner/FrontendStatus.aidl
+++ b/tv/tuner/aidl/android/hardware/tv/tuner/FrontendStatus.aidl
@@ -91,11 +91,19 @@ union FrontendStatus {
 
     /**
      * AGC value is normalized from 0 to 255.
+     * Larger AGC values indicate it is applying more gain.
      */
     int agc;
 
     boolean isLnaOn;
 
+    /**
+     * Layer Error status.
+     *
+     * The order of the vectors is in ascending order of the required CNR (Contrast-to-noise ratio).
+     * The most robust layer is the first. For example, in ISDB-T, isLayerError[0] is the
+     * information of layer A. isLayerError[1] is the information of layer B.
+     */
     boolean[] isLayerError;
 
     /**
@@ -119,16 +127,28 @@ union FrontendStatus {
 
     /**
      * Modulation status.
+     *
+     * The order of the vectors is in ascending order of the required CNR (Contrast-to-noise ratio).
+     * The most robust layer is the first. For example, in ISDB-T, modulations[0] is the information
+     * of layer A. modulations[1] is the information of layer B.
      */
     FrontendModulation[] modulations;
 
     /**
      * Bit error ratio status.
+     *
+     * The order of the vectors is in ascending order of the required CNR (Contrast-to-noise ratio).
+     * The most robust layer is the first. For example, in ISDB-T, bers[0] is the information of
+     * layer A. bers[1] is the information of layer B.
      */
     int[] bers;
 
     /**
      * Code rate status.
+     *
+     * The order of the vectors is in ascending order of the required CN. The most robust layer is
+     * the first. For example, in ISDB-T, codeRates[0] is the information of layer A. codeRates[1]
+     * is the information of layer B.
      */
     FrontendInnerFec[] codeRates;
 
@@ -160,11 +180,19 @@ union FrontendStatus {
 
     /**
      * Frontend Interleaving Modes.
+     *
+     * The order of the vectors is in ascending order of the required CNR (Contrast-to-noise ratio).
+     * The most robust layer is the first. For example, in ISDB-T, interleaving[0] is the
+     * information of layer A. interleaving[1] is the information of layer B.
      */
     FrontendInterleaveMode[] interleaving;
 
     /**
      * Segments in ISDB-T Specification of all the channels.
+     *
+     * The order of the vectors is in ascending order of the required CNR (Contrast-to-noise ratio).
+     * The most robust layer is the first. For example, in ISDB-T, isdbtSegment[0] is the
+     * information of layer A. isdbtSegment[1] is the information of layer B.
      */
     int[] isdbtSegment;