Docs: Port TV docs to source.android.com

Bug: 16572516
Change-Id: Ic33e472f1d22c6538f3feea99c070de03898590b

14 files changed, 804 insertions, 0 deletions

diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 0e2c3b77..93da9f4f 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -226,6 +226,17 @@
             </li>
           </ul>
       </li>
+      <li class="nav-section">
+        <div class="nav-section-header">
+          <a href="<?cs var:toroot ?>devices/tv/index.html">
+            <span class="en">TV</span>
+          </a>
+        </div>
+        <ul>
+          <li><a href="<?cs var:toroot ?>devices/tv/HDMI-CEC.html">HDMI-CEC control service</a></li>
+        </ul>
+      </li>
+
     </ul>
   </li>
 <!-- End Porting Android -->
diff --git a/src/devices/tv/HDMI-CEC.jd b/src/devices/tv/HDMI-CEC.jd
new file mode 100644
index 00000000..9c23ba52
--- /dev/null
+++ b/src/devices/tv/HDMI-CEC.jd
@@ -0,0 +1,312 @@
+page.title=HDMI-CEC Control Service
+@jd:body
+
+<!--
+    Copyright 2014 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.
+-->
+<div id="qv-wrapper">
+  <div id="qv">
+    <h2>In this document</h2>
+    <ol id="auto-toc">
+   </ol>
+  </div>
+</div>
+
+<h2 id=intro>Introduction</h2>
+
+<p>The High-Definition Multimedia Interface Consumer Electronics Control (HDMI-CEC) standard allows mulitmedia consumer products to communicate and
+exchange information with each other. HDMI-CEC supports many features, like
+Remote Control Passthrough and System Audio Control, but one of the most
+popular is One Touch Play. One Touch Play lets a media source device turn on
+the TV and switch its input port automatically, so you don’t have to search for
+the TV remote to switch from your Chromecast to Blu-ray player.</p>
+
+<p>Most manufacturers have adopted HDMI-CEC so their devices work with other
+companies’ devices. But because each manufacturer implements the HDMI-CEC
+standard in different ways, devices don’t always understand each other and
+supported features vary between devices. Because of this variance, consumers
+can’t safely assume that two products that claim CEC support are completely
+compatible.</p>
+
+<h2 id=solution>Solution</h2>
+
+
+<p>With the introduction of the Android TV Input Framework (TIF), HDMI-CEC brings
+together all connected devices and minimizes compatibility issues. Android has
+created a system service called <code>HdmiControlService</code> to alleviate these pain points.</p>
+
+<p>By offering <code>HdmiControlService</code> as a part of the Android ecosystem, Android hopes to provide:</p>
+
+<ul>
+  <li>A standard implementation of HDMI-CEC for all manufacturers, which will reduce
+device incompatibility. Previously, manufacturers had to develop their own
+implementations of HDMI-CEC or use third-party solutions.</li>
+  <li>A service that is well-tested against numerous HDMI-CEC devices already in the
+market. Android has been conducting rigorous research on compatibility issues
+found among the products and collecting useful advice from partners experienced
+in the technology. The CEC service is designed to keep a healthy balance
+between the standard and modifications to that standard so that it works with
+the products that people already use.</li>
+</ul>
+
+<h2 id=overall_design>Overall design</h2>
+
+
+<p><code>HdmiControlService</code> is connected with the rest of the system like TV Input Framework (TIF), Audio service, and Power service to implement the various features the standard
+specifies.</p>
+
+<p>See the following diagram for a depiction of the switch from a custom CEC
+controller to an implementation of the simpler HDMI-CEC hardware abstraction
+layer (HAL).</p>
+
+<img src="images/HDMI_Control_Service.png" alt="Diagram that shows how HDMI-CEC was implemented before and after Android 5.0">
+
+<p class="img-caption"><strong>Figure 1.</strong> HDMI Control Service replacement</p>
+
+<h2 id=implementation>Implementation</h2>
+
+
+<p>See the following diagram for a detailed view of the HDMI control service.</p>
+
+<img src="images/HDMI_Control_Service_Flow.png" alt="Image that shows how HDMI Control service details">
+
+<p class="img-caption"><strong>Figure 2.</strong> HDMI Control Service details</p>
+
+<p>Here are the key ingredients to a proper Android HDMI-CEC implementation:</p>
+
+<ul>
+  <li> A manager class <code>HdmiControlManager</code> provides priviledged apps with the API. System services like TV Input Manager service and Audio service can grab the service directly.</li>
+  <li> The service is designed to allow hosting more than one type of logical device.</li>
+  <li> HDMI-CEC is connected with the hardware via a hardware abstraction layer (HAL)
+to simplify handling differences of the protocol and signalling mechanisms
+between the devices. The HAL definition is available for device manufacturers
+to use to implement the HAL layer.</li>
+</ul>
+
+<p class="note">
+<p><strong>Note</strong>: Device manufacturers should add the following line into <code>PRODUCT_COPY_FILES</code> in <code>device.mk</code></p>
+
+<pre>
+PRODUCT_COPY_FILES += \
+frameworks/native/data/etc/android.hardware.hdmi.cec.xml:system/etc/permissions/android.hardware.hdmi.cec.xml
+</pre>
+
+
+<p>Depending on whether your device is a HDMI sink device or a HDMI source device,
+device manufactureres need to set <code>ro.hdmi.device_type</code> in <code>device.mk</code> for <code>HdmiControlService</code> to work correctly.</p>
+
+<p>For HDMI source devices, like Over the Top (OTT) boxes, set:</p>
+
+<pre>
+PRODUCT_PROPERTY_OVERRIDES += ro.hdmi.device_type=<strong>4</strong>
+</pre>
+
+<p>For HDMI sink devices, like panel TVs, set:</p>
+
+<pre>
+PRODUCT_PROPERTY_OVERRIDES += ro.hdmi.device_type=<strong>0</strong></pre>
+</p>
+
+
+<ul>
+  <li> A device manufacturer-provided proprietary CEC controller cannot coexist with <code>HdmiControlService</code>. It must be disabled or removed. Common requirements for this come from the need to handle manufacturer-specific commands. The manufacturer-specific
+command handler should be incorporated into the service by extending/modifying
+it. This work is left to the device manufacturer and not specified by Android.
+Note that any change made in the service for manufacturer-specific commands
+must not interfere with the way standard commands are handled or the device
+will not be Android compatible.</li>
+  <li> Access to the HDMI-CEC service is guarded with the protection level <code>SignatureOrSystem</code>. Only system components or the apps placed in <code>/system/priv-app</code> can access the service. This is to protect the service from abuse by apps with malicous intent.</li>
+</ul>
+
+<p>Android supports type <code>TV/Display(0)</code> and <code>playback device(4)</code>, which can issue the One Touch Play command to display. The other types (tuner
+and recorder) are currently not supported.</p>
+
+<h2 id=hdmi-cec_hal_definition>HDMI-CEC HAL definition</h2>
+
+
+<p>In order to have the service in action, the HDMI-CEC HAL needs to be
+implemented to the definition provided by Android. It abstracts differences in
+the hardware level and exposes the primitive operations (allocate/read/write,
+etc.) to the upper layer through API.</p>
+
+<p>The API calls that device manufacturers must support are:</p>
+
+<h3 id=tx_rx_events>TX/RX/Events</h3>
+<ul>
+  <li><code>send_message</code></li>
+  <li><code>register_event_callback</code></li>
+</ul>
+
+<h3 id=info>Info</h3>
+<ul>
+  <li><code>get_physical_address</code></li>
+  <li><code>get_version</code></li>
+  <li><code>get_vendor_id</code></li>
+  <li><code>get_port_info</code></li>
+</ul>
+
+<h3 id=logical_address>Logical Address</h3>
+<ul>
+  <li><code>add_logical_address</code></li>
+  <li><code>clear_logical_address</code></li>
+</ul>
+
+<h3 id=status>Status</h3>
+<ul>
+  <li><code>is_connected set_option</code></li>
+  <li><code>set_audio_return_channel</code></li>
+</ul>
+
+<p>Here is an excerpt of the HDMI-CEC HAL definition regarding APIs:</p>
+
+<pre>
+#ifndef ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H
+#define ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H
+
+...
+
+/*
+ * HDMI-CEC HAL interface definition.
+ */
+typedef struct hdmi_cec_device {
+    /**
+     * Common methods of the HDMI-CEC device.  This *must* be the first member of
+     * hdmi_cec_device as users of this structure will cast a hw_device_t to hdmi_cec_device
+     * pointer in contexts where it's known the hw_device_t references a hdmi_cec_device.
+     */
+    struct hw_device_t common;
+
+    /*
+     * (*add_logical_address)() passes the logical address that will be used
+     * in this system.
+     *
+     * HAL may use it to configure the hardware so that the CEC commands addressed
+     * the given logical address can be filtered in. This method can be called
+     * as many times as necessary in order to support multiple logical devices.
+     * addr should be in the range of valid logical addresses for the call
+     * to succeed.
+     *
+     * Returns 0 on success or -errno on error.
+     */
+    int (*add_logical_address)(const struct hdmi_cec_device* dev, cec_logical_address_t addr);
+
+    /*
+     * (*clear_logical_address)() tells HAL to reset all the logical addresses.
+     *
+     * It is used when the system doesn't need to process CEC command any more,
+     * hence to tell HAL to stop receiving commands from the CEC bus, and change
+     * the state back to the beginning.
+     */
+    void (*clear_logical_address)(const struct hdmi_cec_device* dev);
+
+    /*
+     * (*get_physical_address)() returns the CEC physical address. The
+     * address is written to addr.
+     *
+     * The physical address depends on the topology of the network formed
+     * by connected HDMI devices. It is therefore likely to change if the cable
+     * is plugged off and on again. It is advised to call get_physical_address
+     * to get the updated address when hot plug event takes place.
+     *
+     * Returns 0 on success or -errno on error.
+     */
+    int (*get_physical_address)(const struct hdmi_cec_device* dev, uint16_t* addr);
+
+    /*
+     * (*send_message)() transmits HDMI-CEC message to other HDMI device.
+     *
+     * The method should be designed to return in a certain amount of time not
+     * hanging forever, which can happen if CEC signal line is pulled low for
+     * some reason. HAL implementation should take the situation into account
+     * so as not to wait forever for the message to get sent out.
+     *
+     * It should try retransmission at least once as specified in the standard.
+     *
+     * Returns error code. See HDMI_RESULT_SUCCESS, HDMI_RESULT_NACK, and
+     * HDMI_RESULT_BUSY.
+     */
+    int (*send_message)(const struct hdmi_cec_device* dev, const cec_message_t*);
+
+    /*
+     * (*register_event_callback)() registers a callback that HDMI-CEC HAL
+     * can later use for incoming CEC messages or internal HDMI events.
+     * When calling from C++, use the argument arg to pass the calling object.
+     * It will be passed back when the callback is invoked so that the context
+     * can be retrieved.
+     */
+    void (*register_event_callback)(const struct hdmi_cec_device* dev,
+            event_callback_t callback, void* arg);
+
+    /*
+     * (*get_version)() returns the CEC version supported by underlying hardware.
+     */
+    void (*get_version)(const struct hdmi_cec_device* dev, int* version);
+
+    /*
+     * (*get_vendor_id)() returns the identifier of the vendor. It is
+     * the 24-bit unique company ID obtained from the IEEE Registration
+     * Authority Committee (RAC).
+     */
+    void (*get_vendor_id)(const struct hdmi_cec_device* dev, uint32_t* vendor_id);
+
+    /*
+     * (*get_port_info)() returns the hdmi port information of underlying hardware.
+     * info is the list of HDMI port information, and 'total' is the number of
+     * HDMI ports in the system.
+     */
+    void (*get_port_info)(const struct hdmi_cec_device* dev,
+            struct hdmi_port_info* list[], int* total);
+
+    /*
+     * (*set_option)() passes flags controlling the way HDMI-CEC service works down
+     * to HAL implementation. Those flags will be used in case the feature needs
+     * update in HAL itself, firmware or microcontroller.
+     */
+    void (*set_option)(const struct hdmi_cec_device* dev, int flag, int value);
+
+    /*
+     * (*set_audio_return_channel)() configures ARC circuit in the hardware logic
+     * to start or stop the feature. Flag can be either 1 to start the feature
+     * or 0 to stop it.
+     *
+     * Returns 0 on success or -errno on error.
+     */
+    void (*set_audio_return_channel)(const struct hdmi_cec_device* dev, int flag);
+
+    /*
+     * (*is_connected)() returns the connection status of the specified port.
+     * Returns HDMI_CONNECTED if a device is connected, otherwise HDMI_NOT_CONNECTED.
+     * The HAL should watch for +5V power signal to determine the status.
+     */
+    int (*is_connected)(const struct hdmi_cec_device* dev, int port);
+
+    /* Reserved for future use to maximum 16 functions. Must be NULL. */
+    void* reserved[16 - 11];
+} hdmi_cec_device_t;
+
+#endif /* ANDROID_INCLUDE_HARDWARE_HDMI_CEC_H */
+</pre>
+
+
+<p>The API lets the service make use of the hardware resource to send/receive
+HDMI-CEC commands, configure necessary settings, and (optionally) communicate
+with the microprocessor in the underlying platform that will take over the CEC
+control while the Android system is in standby mode.</p>
+
+<h2 id=testing>Testing</h2>
+
+
+<p>Device manufacturers must test the APIs of the HDMI-CEC HAL with their own
+tools to make sure they provide expected functionality.</p>
diff --git a/src/devices/tv/images/Built-in_Tuner_TV_Input.png b/src/devices/tv/images/Built-in_Tuner_TV_Input.png
new file mode 100644
index 00000000..bff7fea9
--- /dev/null
+++ b/src/devices/tv/images/Built-in_Tuner_TV_Input.png
diff --git a/src/devices/tv/images/HDMI_Control_Service.png b/src/devices/tv/images/HDMI_Control_Service.png
new file mode 100644
index 00000000..cc8e43d5
--- /dev/null
+++ b/src/devices/tv/images/HDMI_Control_Service.png
diff --git a/src/devices/tv/images/HDMI_Control_Service_Flow.png b/src/devices/tv/images/HDMI_Control_Service_Flow.png
new file mode 100644
index 00000000..84fe4a6a
--- /dev/null
+++ b/src/devices/tv/images/HDMI_Control_Service_Flow.png
diff --git a/src/devices/tv/images/TIF_HDMI_TV_Input.png b/src/devices/tv/images/TIF_HDMI_TV_Input.png
new file mode 100644
index 00000000..5274588c
--- /dev/null
+++ b/src/devices/tv/images/TIF_HDMI_TV_Input.png
diff --git a/src/devices/tv/images/TIF_MHEG5_app.png b/src/devices/tv/images/TIF_MHEG5_app.png
new file mode 100644
index 00000000..f977ea44
--- /dev/null
+++ b/src/devices/tv/images/TIF_MHEG5_app.png
diff --git a/src/devices/tv/images/TIF_Overview.png b/src/devices/tv/images/TIF_Overview.png
new file mode 100644
index 00000000..5041c170
--- /dev/null
+++ b/src/devices/tv/images/TIF_Overview.png
diff --git a/src/devices/tv/images/TIF_PIP-PAP.png b/src/devices/tv/images/TIF_PIP-PAP.png
new file mode 100644
index 00000000..ea3a3a72
--- /dev/null
+++ b/src/devices/tv/images/TIF_PIP-PAP.png
diff --git a/src/devices/tv/images/TIF_TV_Provider.png b/src/devices/tv/images/TIF_TV_Provider.png
new file mode 100644
index 00000000..d058d82b
--- /dev/null
+++ b/src/devices/tv/images/TIF_TV_Provider.png
diff --git a/src/devices/tv/images/TV_App_CEC_integration.png b/src/devices/tv/images/TV_App_CEC_integration.png
new file mode 100644
index 00000000..da2908cd
--- /dev/null
+++ b/src/devices/tv/images/TV_App_CEC_integration.png
diff --git a/src/devices/tv/images/TV_Input_DVR.png b/src/devices/tv/images/TV_Input_DVR.png
new file mode 100644
index 00000000..3a652db1
--- /dev/null
+++ b/src/devices/tv/images/TV_Input_DVR.png
diff --git a/src/devices/tv/images/Third-party_Input_HDMI.png b/src/devices/tv/images/Third-party_Input_HDMI.png
new file mode 100644
index 00000000..684613a9
--- /dev/null
+++ b/src/devices/tv/images/Third-party_Input_HDMI.png
diff --git a/src/devices/tv/index.jd b/src/devices/tv/index.jd
new file mode 100644
index 00000000..72e03fa8
--- /dev/null
+++ b/src/devices/tv/index.jd
@@ -0,0 +1,481 @@
+page.title=TV Input Framework
+@jd:body
+
+<!--
+    Copyright 2013 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.
+-->
+<div id="qv-wrapper">
+  <div id="qv">
+    <h2>In this document</h2>
+    <ol id="auto-toc">
+    </ol>
+  </div>
+</div>
+
+<h2 id=introduction>Introduction</h2>
+
+<p>The Android TV Input Framework (TIF) simplifies the delivery of live content to
+Android TV. The Android TIF provides a standard API for manufacturers to use to
+create input modules for controlling Android TV. It also enables live TV search
+and recommendations via metadata published by the TV Input. The framework does
+not seek to implement TV standards or regional requirements.</p>
+
+<p>The Android TIF makes it easier for partners to meet regional digital TV
+broadcast standards without re-implementation. This document may also inform
+third-party app developers who would like to create custom TV Inputs.</p>
+
+<h2 id=components>Components</h2>
+
+<p>The Android TV Input Framework implementation includes a TV Input Manager and
+an example TV App that works with a special remote control to access built-in
+and IP tuner channels. The TV App communicates with TV Input modules supplied
+by the device manufacturer or other parties through the TV Input Manager.</p>
+
+<p>The TV Input Framework consists of:</p>
+
+<ul>
+  <li>TV Provider (<code>com.android.providers.tv.TvProvider</code>): a database of channels, programs, and associated permissions
+  <li>TV App (<code>com.android.tv.TvActivity</code>): the app that handles user interaction
+  <li>TV Input Manager (<code>android.media.tv.TvInputManager</code>): allows the TV Inputs to communicate with the TV App
+  <li>TV Input: an app representing physical or virtual tuners and input ports
+  <li>TV Input HAL (<code>tv_input</code> module): a hardware definition that allows system TV Inputs to access
+TV-specific hardware when implemented
+  <li>Parental Control: the technology to allow blocking of channels and programs
+  <li>HDMI-CEC: the technology to allow remote control of various devices over HDMI
+</ul>
+
+<p>These components are covered in detail below. See the following diagram for a
+detailed view of the Android TV Input Framework architecture.</p>
+
+<img src="images/TIF_Overview.png" alt="Overview of the Android TIF architecture">
+<p class="img-caption"><strong>Figure 1.</strong> Android TV Input Framework (TIF) architecture</p>
+
+<h2 id=flow>Flow</h2>
+
+<p>Here is how the architecture is exercised:</p>
+
+<ol>
+  <li>The user sees and interacts with the TV App, a system app that can’t be
+replaced by a third-party app. The Android Open Source Project (AOSP) provides
+a reference TV App that manufacturers can extend to suit their needs.
+  <li>The TV App displays the AV content from the TV Input.
+  <li>The TV App cannot talk directly with the TV Inputs. The TV Input Manager
+identifies the state of TV Inputs for the TV App. See <em>TV Input Manager</em> below for more details about these limitations.
+</ol>
+
+<h2 id=permissions>Permissions</h2>
+
+<ul>
+  <li>Only <code><a href="http://developer.android.com/guide/topics/manifest/permission-element.html#plevel">signatureOrSystem</a> T</code>V Inputs and TV App have full access to the TV Provider database and are able
+to receive KeyEvents.
+  <li>Only system TV Inputs can access the TV Input HAL through the TV Input Manager
+service. TV Inputs are accessed one-to-one via TV Input Manager sessions.
+  <li>Third-party TV Inputs have package-locked access to the TV Provider database
+and can READ/WRITE only to matching package rows.
+  <li>Third-party TV inputs can either display their own content or content from a
+device manufacturer’s passthrough TV inputs, like HDMI1. They can’t display
+content from non-passthrough TV inputs, like a built-in or IPTV tuner.
+  <li><code>TV_INPUT_HARDWARE</code> permission for a hardware TV Input app, signals the TV Input Manager Service
+to notify the TV Input service on boot to call the TV Input Manager Service and
+add its TV Inputs. This permission allows a hardware TV Input app to support
+multiple TV Inputs per TV Input service, as well as being able to dynamically
+add and remove its supported TV Inputs.
+</ul>
+
+<h2 id=tv_provider>TV Provider</h2>
+
+<p>The TV Provider database stores the channels and programs from TV Inputs. The
+TV Provider also publishes and manages the associated permissions so that TV
+Inputs can see only their own records. For instance, a specific TV Input can
+see only the channels and programs it has supplied and is prohibited from
+accessing any other TV Inputs’ channels and programs. </p>
+
+<p>The TV Provider maps "broadcast genre" to "canonical genre" internally. TV
+Inputs are responsible for populating "broadcast genre" with the value in the
+underlying broadcast standard, and the "canonical genre" field will
+automatically be populated with the correct associated genre from <code>android.provider.TvContract.Genres</code>. For example, with broadcast standard ATSC A/65 and program with genre 0x25
+(meaning “Sports”), the TV Input will populate the “broadcast genre” with the
+String “Sports” and TV Provider will populate the “canonical genre” field with
+the mapped value <code>android.provider.TvContract.Genres.SPORTS</code>.</p>
+
+<p>See the diagram below for a detailed view of the TV Provider. </p>
+
+<img src="images/TIF_TV_Provider.png" alt="Android TV Provider">
+<p class="img-caption"><strong>Figure 2.</strong> Android TV Provider</p>
+
+<p><em>Only apps in the privileged system partition can read the entire TV Provider
+database. </em></p>
+
+<p>Passthrough TV inputs do not store channels and programs. </p>
+
+<p>In addition to the standard fields for channels and programs, the TV Provider
+database also offers a BLOB type field, <code>COLUMN_INTERNAL_PROVIDER_DATA</code>, in each table that TV Inputs may use to store arbitrary data. That BLOB data
+can include custom information, such as frequency of the associated tuner, and
+may be provided in a protocol buffer or another form. A Searchable field is
+available to make certain channels unavailable in search (such as to meet
+country-specific requirements for content protection).</p>
+
+<h3 id=tv_provider_database_field_examples>Database field examples</h3>
+
+<p>The TV Provider supports structured data in channel (<code>android.provider.TvContract.Channels</code>) and program (<code>android.provider.TvContract.Programs</code>) tables. These tables are populated and accessed by TV Inputs and system apps
+like the TV App. These tables have four types of fields:</p>
+
+<ul>
+  <li><strong>Display: </strong>Display fields contain information that apps may want to make visible to the
+user, like a channel’s name (<code>COLUMN_DISPLAY_NAME</code>) or number (<code>COLUMN_DISPLAY_NUMBER</code>), or the title of the program being viewed.
+  <li><strong>Metadata:</strong> There are three fields for identifying content, according to relevant
+standards, like a channel’s transport stream ID (<code>COLUMN_TRANSPORT_STREAM_ID</code>), original network ID (<code>COLUMN_ORIGINAL_NETWORK_ID</code>) and service id (<code>COLUMN_SERVICE_ID</code>).
+  <li><strong>Internal data</strong>: Fields that are for the custom use of TV Inputs.<br>
+    Some fields, like <code>COLUMN_INTERNAL_PROVIDER_DATA</code>, are customizable BLOB fields where a TV Input can store arbitrary metadata
+about their channel or program.
+  <li><strong>Flag: </strong>Flag fields represent whether a channel should be restricted from search,
+browse, or viewing. This can be set only at the channel level. All programs
+defer to the setting on the channel.
+  <ul>
+    <li><code>COLUMN_SEARCHABLE</code>: Restricting search from some channels may be a requirement in certain
+regions. <code>COLUMN_SEARCHABLE = 0</code> means the channel should not be exposed in search results. 
+    <li><code>COLUMN_BROWSABLE</code>: Visible to system applications only. Restricting channel from being browsed
+by applications. <code>COLUMN_BROWSABLE = 0</code> means the channel should not be included in the channel list.
+    <li><code>COLUMN_LOCKED</code>: Visible to system applications only. Restricting channel from being viewed by
+invalid accounts without entering PIN code. <code>COLUMN_LOCKED = 1</code> means the channel should be protected by parental control.
+  </ul>
+</ul>
+
+<p>For a more exhaustive list of the fields, see <code>android/frameworks/base/media/java/android/media/tv/TvContract.java</code></p>
+
+<h3 id=permissions_and_access_control>Permissions and access control</h3>
+
+<p>All fields are visible to anyone with access to the corresponding row. No
+fields are directly accessible to users; they see only what the TV App, System
+apps, or TV Inputs surface.</p>
+
+<ul>
+  <li>Each row has <code>PACKAGE_NAME</code>, the package (app) that owns that row, checked on Query, Insert, Update via
+TvProvider.java.
+A TV Input may access only the information it wrote and is
+cordoned off from the information provided by other TV Inputs.
+  <li>READ, WRITE permissions via AndroidManifest.xml (requires user consent) to
+determine available channels.
+  <li>Only <code>signatureOrSystem</code> apps can acquire <code>ACCESS_ALL_EPG_DATA</code> permission to access the entire database.
+</ul>
+
+<h2 id=tv_input_manager>TV Input Manager</h2>
+
+<p>The TV Input Manager provides a central system API to the overall Android TV
+Input Framework. It arbitrates interaction between apps and TV Inputs and
+provides parental control functionality. TV Input Manager sessions must be
+created one-to-one with TV Inputs. The TV Input Manager allows access to
+installed TV Inputs so apps may:</p>
+
+<ul>
+  <li>List TV inputs and check their status
+  <li>Create sessions and manage listeners
+</ul>
+
+<p>For sessions, a TV Input may be tuned by the TV App only to URIs it has added
+to the TV Provider database, except for passthrough TV Inputs which can be
+tuned to using <code>TvContract.buildChannelUriForPassthroughInput()</code>. A TV Input may also have its volume set. TV Inputs provided and signed by the
+device manufacturer (signature apps) or other apps installed in the system
+partition will have access to the entire TV Provider database. This access can
+be used to construct apps to browse and search across all available TV channels
+and programs.</p>
+
+<p>An app may create and register a <code>TvInputCallback</code> with the <code>android.media.tv.TvInputManager</code> to be called back on a TV Input’s state change or on the addition or removal
+of a TV Input. For example, a TV App can react when a TV Input is disconnected
+by displaying it as disconnected and preventing its selection.</p>
+
+<p>The TV Input Manager abstracts communication between the TV App and TV Inputs.
+The standard interface of TV Input Manager and TV Input allows multiple
+partners to create their own TV Apps while helping all third-party TV Inputs
+work on all TV Apps, thus creating an ecosystem. </p>
+
+<h2 id=tv_inputs>TV Inputs</h2>
+
+<p>TV Inputs are Android apps in the sense they have an AndroidManifest.xml and
+are installed (via Play, pre-installed, or sideloaded). Android TV supports
+pre-installed system apps, apps signed by the device manufacturer and
+third-party TV Inputs. </p>
+
+<p>Some inputs, like the HDMI input or built-in tuner input, can be provided only
+by the manufacturer as they speak directly with the underlying hardware.
+Others, such as IPTV, place-shifting, and external STB, can be supplied by
+third parties as APKs on Google Play Store. Once downloaded and installed, the
+new input can be selected within the TV App.</p>
+
+<h3 id=passthrough_input_example>Passthrough input example</h3>
+
+<img src="images/TIF_HDMI_TV_Input.png" alt="Android TV System Input">
+<p class="img-caption"><strong>Figure 3.</strong> Android TV System Input</p>
+
+<p>In this example, the TV Input provided by the device manufacturer is trusted
+and has full access to the TV Provider. As a passthrough TV Input, it does not
+register any channels or programs with the TV Provider. To obtain the URI used
+to reference the passthrough input, use the <code>android.media.tv.TvContract</code> utility method <code>buildChannelUriForPassthroughInput(String inputId)</code>.  The TV App communicates with the TV Input Manager to reach the HDMI TV
+Input. </p>
+
+<h3 id=built-in_tuner_example>Built-in tuner example</h3>
+
+<img src="images/Built-in_Tuner_TV_Input.png" alt="Android TV Built-in Tuner Input">
+<p class="img-caption"><strong>Figure 4.</strong> Android TV Built-in Tuner Input</p>
+
+<p>In this example, the Built-in Tuner TV Input provided by the device
+manufacturer is trusted and has full access to  the TV Provider. </p>
+
+<h3 id=third-party_input_example>Third-party input example</h3>
+
+<img src="images/Third-party_Input_HDMI.png" alt="Android TV third-party input">
+<p class="img-caption"><strong>Figure 5.</strong> Android TV third-party input</p>
+
+<p>In this example, the external STB TV Input is provided by a third party. Since
+that TV Input can’t directly access the HDMI video feed coming in, it must go
+through the TV Input Manager and use the HDMI TV Input provided by the device
+manufacture.</p>
+
+<p>Through the TV Input Manager, the external STB TV Input can speak with the HDMI
+TV Input and ask it to show the video on HDMI1. So the STB TV Input can control
+the TV while the manufacturer-provided HDMI TV Input renders the video.</p>
+
+<h3 id=picture_in_picture_pip_example>Picture in picture (PIP) example </h3>
+
+<img src="images/TIF_PIP-PAP.png" alt="Android TV KeyEvents">
+<p class="img-caption"><strong>Figure 6.</strong> Android TV KeyEvents</p>
+
+<p>The diagram above shows how buttons on a remote control are passed to a
+specific TV Input for picture in picture (PIP) display. Those button presses
+are interpreted by the hardware driver supplied by the device manufacturer,
+converting hardware scancodes to Android keycodes and passing them to the
+standard Android <a href="http://source.android.com/devices/tech/input/overview.html">input pipeline</a> <code>InputReader</code> and <code>InputDispatcher</code> functions as <a href="http://developer.android.com/reference/android/view/KeyEvent.html">KeyEvents</a>. These in turn trigger events on the TV App if it is in focus. </p>
+
+<p>Only system TV Inputs are eligible to receive <code>InputEvents</code>, and only if they have the <code>RECEIVE_INPUT_EVENT</code> system permission. The TV Input is responsible to determine which InputEvents
+to consume and should allow the TV App to handle the keys it does not need to
+consume.</p>
+
+<p>The TV App is responsible for knowing which system TV Input is active, meaning
+selected by the user, and to disambiguate incoming <code>KeyEvents</code> and route them to the correct TV Input Manager session, calling <code>dispatchInputEvent()</code> to pass on the event to the associated TV Input. </p>
+
+<h3 id=mheg-5_input_example>MHEG-5 input example</h3>
+
+<p>The following diagram shows a more detailed view of how <code>KeyEvents</code> are routed through the Android TIF.</p>
+
+<img src="images/TIF_MHEG5_app.png" alt="Android TV Red button example">
+<p class="img-caption"><strong>Figure 7.</strong> Android TV Red button example</p>
+
+<p>It depicts the flow of a Red button app, common in Europe for letting users
+access interactive apps on their televisions. An app can be delivered over this
+transport stream. When the button is clicked, it lets users interact with these
+broadcast apps. For example, you might use these broadcast apps to access
+related web pages or sports scores.</p>
+
+<p>See the <em>Broadcast app</em> section to learn how broadcast apps interact with the TV App.</p>
+
+<p>In this example:</p>
+
+<ol>
+  <li>The TV App is in focus and receives all keys.
+  <li><code>KeyEvents</code> (e.g. the Red button) is passed to the active TV Input as <code>InputEvents.</code>
+  <li>The system TV Input integrates with MHEG-5 stack and has the <code>RECEIVE_INPUT_EVENT</code> system permission.
+  <li>On receiving activation keycode (e.g. Red button), the TV Input activates
+broadcast app.
+  <li>TV input consumes <code>KeyEvents</code> as <code>InputEvents</code> and the broadcast app is the focus and handles <code>InputEvents</code> until dismissed. 
+</ol>
+
+<p class="note"><strong>Note</strong>: Third-party TV inputs never receive keys. </p>
+
+<h2 id=tv_input_hal>TV Input HAL</h2>
+
+<p>The TV Input HAL aids development of TV Inputs to access TV-specific hardware.
+As with other Android HALs, the TV Input HAL (<code>tv_input</code>) is
+available in the AOSP source tree and the vendor develops its implementation.</p>
+
+<h2 id=tv_app>TV App</h2>
+
+<p>The Android TV Input Framework includes a reference implementation to help
+manufacturers create their own TV Apps more quickly.  Third-party developers
+cannot develop TV Apps as the APIs require system or signature permission.</p>
+
+<p>Partners are strongly encouraged to take the reference as a base implementation
+and extend it to add additional functionality. By building upon the reference
+implementation, bug fixes and improvements added to the reference will be more
+easily included in the partner’s variant. By extending the TV App in a
+structured way, it is easier to pick up new features and bug fixes made to the
+reference. Ideally, those extensions are submitted to the Android ecosystem so
+others may benefit from and be compatible with them.</p>
+
+<p>The TV App provides channel and program search results (via <code>com.android.tv.search.TvProviderSearch</code>) and passes keys, tune, and volume calls to TV Inputs through the TV Input
+Manager. Manufacturers must implement the TV App to ensure search functions
+work for their users. Otherwise, users will struggle to navigate the resulting
+Android TV.</p>
+
+<p>The example Android TV App lets manufacturers see how the TIF works and should
+expedite their own development by demonstrating a simple TV-watching
+experience. </p>
+
+<p>As with the TIF in general, the TV App does not seek to implement device
+manufacturer or country-specific features. Instead, it handles these tasks by
+default:</p>
+
+<h3 id=setup_and_configuration>Setup and configuration</h3>
+
+<ul>
+  <li>Auto-detect TV Inputs
+  <li>Let TV Inputs initiate channel setup
+  <li>Control parental settings
+  <li>Alter TV settings
+  <ul>
+    <li>Edit channel
+  </ul>
+</ul>
+
+<h3 id=viewing>Viewing</h3>
+<ul>
+  <li>Access and navigate all TV channels
+  <li>Access TV program information bar
+  <li>Multiple audio and subtitle track support
+  <li>Parental control PIN challenge
+  <li>Allow TV Input UI overlay for:
+  <ul>
+    <li>TV standard (HbbTV, etc.)
+  </ul>
+</ul>
+
+<h2 id=parental_control>Parental Control</h2>
+
+<p>Parental control lets a user block undesired channels and programs, but bypass
+the block by entering a PIN code.</p>
+
+<p>Responsibility for parental control functionality is shared amongst the TV App,
+TV Input Manager service, TV Provider, and TV Input. </p>
+
+<h3 id=tv_provider>TV Provider</h3>
+
+<p>Each channel row has a <code>COLUMN_LOCKED</code> field that is used to lock specific channels from viewing without entering a
+PIN code. The program field <code>COLUMN_CONTENT_RATING</code> is intended for display and is not used to enforce parental control.</p>
+
+<h3 id=tv_input_manager>TV Input Manager</h3>
+
+<p>The TV Input Manager stores every blocked <code>TvContentRating</code> and responds to <code>isRatingBlocked()</code> to advise if content with the given rating should be blocked.</p>
+
+<h3 id=tv_input>TV Input</h3>
+
+<p>The TV Input checks if the current content should be blocked by calling <code>isRatingBlocked()</code> on the TV Input Manager when the rating of the displayed content has changed
+(on program or channel change), or parental control settings have changed (on <code>ACTION_BLOCKED_RATINGS_CHANGED</code> and <code>ACTION_PARENTAL_CONTROLS_ENABLED_CHANGED</code>). If the content should be blocked, the TV Input disables the audio and video
+and notifies the TV app that the current content is blocked by calling <code>notifyContentBlocked(TvContentRating)</code>.</p>
+
+<h3 id=tv_app>TV App</h3>
+
+<p>The TV App shows parental control settings to users and a PIN code UI when it
+is notified by a TV Input that the current content is blocked or when the user
+attempts to view a blocked channel.</p>
+
+<p>The TV App does not directly store the parental control settings. When the user
+changes the parental control settings, every blocked <code>TvContentRating</code> is stored by the TV Input Manager, and blocked channels are stored by the TV
+Provider.</p>
+
+<h2 id=hdmi-cec>HDMI-CEC</h2>
+
+<p>HDMI-CEC allows one device to control another, thereby enabling a single remote
+to control multiple appliances in a home theater. It is used by Android TV to
+speed setup and allow distant control over various TV Inputs via the central TV
+App. For instance, it may switch inputs, power up or down devices, and more.</p>
+
+<p>The Android TIF implements HDMI-CEC as the HDMI Control Service so that
+partners merely need to develop low-level drivers that interact with the
+lightweight Android TV HAL, skipping more complex business logic. In providing
+a standard implementation, Android seeks to mitigate compatibility issues by
+reducing fragmented implementations and selective feature support. The HDMI
+Control Service uses the existing Android services, including input and power.</p>
+
+<p>This means existing HDMI-CEC implementations will need to be redesigned to
+interoperate with the Android TIF. We recommend the hardware platform contain a
+microprocessor to receive CEC power on and other commands.</p>
+
+<img src="images/TV_App_CEC_integration.png" alt="CEC integration on Android TV">
+<p class="img-caption"><strong>Figure 8.</strong> CEC integration on Android TV</p>
+
+<ol>
+  <li> The CEC bus receives a command from the currently active source to switch to a
+different source.
+  <li> The driver passes the command to the HDMI-CEC HAL.
+  <li> The HAL notifies all <code>ActiveSourceChangeListeners</code>.
+  <li> THe HDMI Control Service is notified of source change via <code>ActiveSourceChangeListener</code>.
+  <li> The TV Input Manager service generates an intent for the TV App to switch the
+source.
+  <li> The TV App then creates a TV Input Manager Session for the TV Input being
+switched to and calls <code>setMain</code> on that session. 
+  <li> The TV Input Manager Session passes this information on to the HDMI TV Input.
+  <li> The HDMI TV input requests to set sideband surface.
+  <li> The TV Input Manager Service generates a corresponding routing control command
+back to HDMI Control Service when the surface is set.
+</ol>
+
+<h2 id=tv_integration_guidelines>TV integration guidelines</h2>
+
+<h3 id=broadcast_app>Broadcast app</h3>
+
+<p>Because each country has broadcast-specific requirements (MHEG, Teletext,
+HbbTV, and more), manufacturers are expected to supply their own solutions for
+the broadcast app, for example:</p>
+
+<ul>
+  <li> MHEG: native stack
+  <li> Teletext: native stack
+  <li> HbbTV: webkit modification by Opera browser
+</ul>
+
+<p>In the Android L release, Android TV expects partners to use systems
+integrators or the Android solutions for regional TV stacks, pass the surface
+to TV software stacks, or pass the necessary key code to interact with legacy
+stacks.</p>
+
+<p>Here’s how the broadcast app and TV App interact:</p>
+
+<ol>
+  <li>The TV App is in focus, receiving all keys.
+  <li>The TV App passes keys (e.g. Red button) to the TV Input device.
+  <li>The TV Input device internally integrates with legacy TV stack.
+  <li>On receiving an activation keycode (e.g. Red button), the TV Input device
+activates broadcast apps.
+  <li>A broadcast app takes focus in the TV App and handles user actions.
+</ol>
+
+<p>For voice search/recommendation, the broadcast app may support In-app search
+for voice search.</p>
+
+<h3 id=dvr>DVR</h3>
+
+<p>Android TV supports digital video recording (DVR) with partner development. The
+DVR function works like so:</p>
+
+<ol>
+  <li> DVR recording function / Live Buffer can be implemented by any TV Input.
+  <li> TV App passes on key inputs to TV Input (including recording/pause/fast
+forward/ rewind keys).
+  <li> When playing the recorded content, the TV Input handles it with trick play
+overlay.
+  <li> DVR app enables users to browse and manage recorded program.
+</ol>
+
+<p>For voice search/recommendation:</p>
+
+<ul>
+  <li>DVR app supports In-app search for Voice search.
+  <li>DVR app can propose recommendation using notifications.
+</ul>
+
+<p>See the following diagram for a view into a possible DVR implementation in
+Android TV.</p>
+
+<img src="images/TV_Input_DVR.png" alt="Digital video recording in Android TV">
+<p class="img-caption"><strong>Figure 9.</strong> Digital video recording in Android TV</p>