Merge "Docs: Add OEM and SoC vendor dependencies for resource manager" into mnc-dev

7 files changed, 247 insertions, 1 deletions

diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 9ef9a23b..8fd6d692 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -119,7 +119,17 @@
           <li><a href="<?cs var:toroot ?>devices/input/validate-keymaps.html">Validate Keymaps</a></li>
         </ul>
       </li>
-      <li><a href="<?cs var:toroot ?>devices/media.html">Media</a></li>
+      <li class="nav-section">
+        <div class="nav-section-header">
+          <a href="<?cs var:toroot ?>devices/media/index.html">
+            <span class="en">Media</span>
+          </a>
+        </div>
+        <ul>
+          <li><a href="<?cs var:toroot ?>devices/media/soc.html">SoC Dependencies</a></li>
+          <li><a href="<?cs var:toroot ?>devices/media/oem.html">OEM Dependencies</a></li>
+        </ul>
+      </li>
       <li class="nav-section">
         <div class="nav-section-header">
           <a href="<?cs var:toroot ?>devices/sensors/index.html">
diff --git a/src/devices/images/media.png b/src/devices/images/media.png
deleted file mode 100644
index 7aaee932..00000000
--- a/src/devices/images/media.png
+++ /dev/null
diff --git a/src/devices/images/ape_fwk_hal_media.png b/src/devices/media/images/ape_fwk_hal_media.png
index 30679472..30679472 100644
--- a/src/devices/images/ape_fwk_hal_media.png
+++ b/src/devices/media/images/ape_fwk_hal_media.png
diff --git a/src/devices/images/ape_fwk_media.png b/src/devices/media/images/ape_fwk_media.png
index 92a731bf..92a731bf 100644
--- a/src/devices/images/ape_fwk_media.png
+++ b/src/devices/media/images/ape_fwk_media.png
diff --git a/src/devices/media.jd b/src/devices/media/index.jd
index 166ba590..166ba590 100644
--- a/src/devices/media.jd
+++ b/src/devices/media/index.jd
diff --git a/src/devices/media/oem.jd b/src/devices/media/oem.jd
new file mode 100644
index 00000000..a271ecd5
--- /dev/null
+++ b/src/devices/media/oem.jd
@@ -0,0 +1,162 @@
+page.title=OEM Dependencies for Media Resource Manager
+@jd:body
+
+<!--
+    Copyright 2015 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>
+
+<p>This document is intended to help original equipment manufacturers (OEMs)
+properly implement support for Android media resource manager and related APIs.</p>
+
+<h2 id=1_max_concurrent_codec_instances>1. Max concurrent codec instances</h2>
+
+<p>The <code>CodecCapabilities.getMaxSupportedInstances</code> interface
+returns the maximum number of supported concurrent codec instances.</p>
+
+<p>The CTS test 
+<code>testGetMaxSupportedInstances(android.media.cts.MediaCodecCapabilitiesTest)</code>
+is used to enforce the proper maximum is set in 
+<code>/etc/media_codecs.xml</code>.</p>
+
+<p>Here is an example:</p>
+
+<pre>
+...
+&lt;MediaCodecs&gt;
+    ...
+    &lt;Encoders&gt;
+        &lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.encoder.avc" type="video/avc" &gt;
+           ...
+            &lt;Limit name="concurrent-instances" max="13" /&gt;
+        &lt;/MediaCodec&gt;
+        ...
+    &lt;/Encoders&gt;
+    ...
+&lt;/MediaCodecs&gt;
+</pre>
+
+<p>OEMs can use this test to generate the concurrent limits that pass the test.
+To do this:</p>
+
+  <ol>
+    <li>Run the test first using cts-tradefed.
+    <li>Evaluate the resulting failure message. Here is an example:
+
+<pre>
+There was 1 failure:
+1) testGetMaxSupportedInstances(android.media.cts.MediaCodecCapabilitiesTest)
+junit.framework.AssertionFailedError: In order to pass the test, please publish
+following codecs' concurrent instances limit in /etc/media_codecs.xml:
+&lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.encoder.mpeg4" type="video/mp4v-es" &gt;
+    &lt;Limit name="concurrent-instances" max="13" /&gt;
+&lt;/MediaCodec&gt;
+&lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.encoder.h263" type="video/3gpp" &gt;
+    &lt;Limit name="concurrent-instances" max="13" /&gt;
+&lt;/MediaCodec&gt;
+&lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.encoder.avc" type="video/avc" &gt;
+    &lt;Limit name="concurrent-instances" max="13" /&gt;
+&lt;/MediaCodec>
+&lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.encoder.vp8" type="video/x-vnd.on2.vp8" &gt;
+    &lt;Limit name="concurrent-instances" max="13" /&gt;
+&lt;/MediaCodec&gt;
+&lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.decoder.avc" type="video/avc" &gt;
+    &lt;Limit name="concurrent-instances" max="13" /&gt;
+&lt;/MediaCodec&gt;
+&lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.decoder.avc.secure" type="video/avc" &gt;
+    &lt;Limit name="concurrent-instances" max="4" /&gt;
+&lt;/MediaCodec&gt;
+&lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.decoder.mpeg4" type="video/mp4v-es" &gt;
+    &lt;Limit name="concurrent-instances" max="12" /&gt;
+&lt;/MediaCodec&gt;
+&lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.decoder.h263" type="video/3gpp" &gt;
+    &lt;Limit name="concurrent-instances" max="12" /&gt;
+&lt;/MediaCodec&gt;
+&lt;MediaCodec name="OMX.<em>&lt;vendor&gt;</em>.video.decoder.vp8" type="video/x-vnd.on2.vp8" &gt;
+    &lt;Limit name="concurrent-instances" max="12" /&gt;
+&lt;/MediaCodec&gt;
+</pre>
+
+    <li>Add the <code>concurrent-instances</code> lines suggested in the test
+failure message to the <code>/etc/media_codecs.xml</code> file.
+
+    <li>Re-run the test to verify its success.
+  </ol>
+
+<h2 id=2_achievable_frame_rates_for_video_codecs>2. Achievable frame rates for video codecs</h2>
+<p>The <code>VideoCapabilities.getAchievableFrameRatesFor</code> interface
+returns the range of achievable video frame rates for a video size. This
+information must be provided by the OEM for each device via an XML file placed at
+<code>/etc/media_codecs_performance.xml</code>. These settings are tested by
+the <code>com.android.cts.videoperf.VideoEncoderDecoderTest</code> and
+<code>android.media.cts.VideoDecoderPerfTest</code> CTS tests.</p>
+
+<p>OEMs can use the CTS tests to generate the XML files that pass the tests. To do this:</p>
+  <ol>
+    <li>Run the tests first using cts-tradefed. Given the
+variability of Android performance, it is recommended the tests are run
+multiple times to get more accurate minimum and maximum values.
+    <li>Use the provided <code>get_achievable_rates.py</code> script to
+generate the XML file.
+    <li>Place the XML file at: <code>/etc/media_codecs_performance.xml</code><br>
+This is usually done by placing the XML file in the device project
+(device/<em>&lt;vendor&gt;</em>/<em>&lt;product&gt;</em>) and adding a
+<code>PRODUCT_COPY_FILES</code> line to <code>device.mk</code> like so:
+<pre>
+PRODUCT_COPY_FILES += \
+...
+   device/moto/shamu/media_codecs.xml:system/etc/media_codecs.xml \
++    device/moto/shamu/media_codecs_performance.xml:system/etc/media_codecs_performance.xml
+</pre>
+    <li>Re-run the performance tests to verify their success.
+  </ol>
+
+<h2 id=3_co-exist_of_secure_codec_and_non-secure_codec>3. Co-exist of secure codec and non-secure codec</h2>
+
+<ul>
+  <li>supports-secure-with-non-secure-codec &mdash;
+If the instance of secure codec and the instance of non-secure codec can’t
+co-exist at the same time, that should be indicated as global setting in the
+<code>media_codecs.xml</code> file.
+<pre>
+&lt;MediaCodecs&gt;
+    &lt;Settings&gt;
+        &lt;Setting name="supports-secure-with-non-secure-codec" value="false" /&gt;
+    &lt;/Settings&gt;
+    &lt;Encoders&gt;
+…
+</pre>
+  <li>supports-multiple-secure-codecs &mdash;
+If co-exist of multiple secure codec instances is not supported, that should be
+indicated as a global setting in the <code>media_codecs.xml</code> file.
+<pre>
+&lt;MediaCodecs&gt;
+    &lt;Settings&gt;
+        &lt;Setting name="supports-multiple-secure-codecs" value="false" /&gt;
+    &lt;/Settings&gt;
+    &lt;Encoders&gt;
+…
+</pre>
+  <li>Note that the both settings are true by default, meaning if they are supported,
+there’s no need to add the setting line to the <code>media_codecs.xml</code>.
+  <li>The <code>ResourceManagerTest</code> CTS tests may fail if these two settings were not set
+properly.
+</ul>
diff --git a/src/devices/media/soc.jd b/src/devices/media/soc.jd
new file mode 100644
index 00000000..e42a2af6
--- /dev/null
+++ b/src/devices/media/soc.jd
@@ -0,0 +1,74 @@
+page.title=SoC Vendor Dependencies for Media Resource Manager
+@jd:body
+
+<!--
+    Copyright 2015 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>
+
+<p>This document is intended to help system on chip vendors (SoCs) properly
+implement support for priority, operating rate and the hooks needed for Android
+media resource manager.</p>
+
+<h2 id=1_omx_errorinsufficientresources>1. OMX_ErrorInsufficientResources</h2>
+
+<p>The codec component should return
+<code>OMX_ErrorInsufficientResources</code> on <code>GetHandle</code>,
+<code>Init</code>, <code>UseBuffer</code>, <code>AllocateBuffer</code> or a
+state transition if the failure is due to insufficient resource. The error code
+will be used by the media resource manager as the indicator to potentially
+preempt media resource from other lower priority process.</p>
+
+<p>An Android Compatibility Test Suite (CTS) test exists to allocate, configure
+and start each codec repeatedly until <code>catching
+OMX_ErrorInsufficientResources</code> (pass) or any other error (fail).</p>
+
+<h2 id=2_omx_indexconfigpriority>2. OMX_IndexConfigPriority</h2>
+
+<p>This configuration lets the application describe desired codec priority.</p>
+
+<p>The associated value is an integer. Higher value means lower priority.
+Currently, only two levels are supported:</p>
+
+<ul>
+  <li>0: realtime priority - meaning that the codec shall support the given
+performance configuration (e.g. framerate) at realtime. This will only be used
+by media playback, capture, and possibly by realtime communication scenarios if
+best effort performance is not suitable.</li>
+  <li>1: non-realtime priority (best effort). This is the default value.</li>
+</ul>
+
+<p>Vendor is suggested to use this as a hint used at codec configuration and
+resource planning - to understand the realtime requirements of the application.</p>
+
+<p>Don’t assume realtime priority unless it is configured to 0.</p>
+
+<h2 id=3_omx_indexconfigoperatingrate>3. OMX_IndexConfigOperatingRate</h2>
+
+<p>This configuration lets the application describe operating frame rate for
+video or sample rate for audio at which the codec will need to operate.</p>
+
+<p>This is used for cases like high-speed/slow-motion video capture, where the
+video encoder format contains the target playback rate (e.g. 30fps), but the
+component must be able to handle the high operating capture rate (e.g. 240fps).</p>
+
+<p>This rate should be used for resource planning and setting the operating
+points.</p>