Merge "Docs: Add OEM and SoC vendor dependencies for resource manager" into mnc-dev
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 9ef9a23..8fd6d69 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 7aaee93..0000000
--- a/src/devices/images/media.png
+++ /dev/null
Binary files differ
diff --git a/src/devices/images/ape_fwk_hal_media.png b/src/devices/media/images/ape_fwk_hal_media.png
similarity index 100%
rename from src/devices/images/ape_fwk_hal_media.png
rename to src/devices/media/images/ape_fwk_hal_media.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_media.png b/src/devices/media/images/ape_fwk_media.png
similarity index 100%
rename from src/devices/images/ape_fwk_media.png
rename to src/devices/media/images/ape_fwk_media.png
Binary files differ
diff --git a/src/devices/media.jd b/src/devices/media/index.jd
similarity index 100%
rename from src/devices/media.jd
rename to src/devices/media/index.jd
diff --git a/src/devices/media/oem.jd b/src/devices/media/oem.jd
new file mode 100644
index 0000000..a271ecd
--- /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>
+...
+<MediaCodecs>
+ ...
+ <Encoders>
+ <MediaCodec name="OMX.<em><vendor></em>.video.encoder.avc" type="video/avc" >
+ ...
+ <Limit name="concurrent-instances" max="13" />
+ </MediaCodec>
+ ...
+ </Encoders>
+ ...
+</MediaCodecs>
+</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:
+<MediaCodec name="OMX.<em><vendor></em>.video.encoder.mpeg4" type="video/mp4v-es" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.encoder.h263" type="video/3gpp" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.encoder.avc" type="video/avc" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.encoder.vp8" type="video/x-vnd.on2.vp8" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.avc" type="video/avc" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.avc.secure" type="video/avc" >
+ <Limit name="concurrent-instances" max="4" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.mpeg4" type="video/mp4v-es" >
+ <Limit name="concurrent-instances" max="12" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.h263" type="video/3gpp" >
+ <Limit name="concurrent-instances" max="12" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.vp8" type="video/x-vnd.on2.vp8" >
+ <Limit name="concurrent-instances" max="12" />
+</MediaCodec>
+</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><vendor></em>/<em><product></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 —
+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>
+<MediaCodecs>
+ <Settings>
+ <Setting name="supports-secure-with-non-secure-codec" value="false" />
+ </Settings>
+ <Encoders>
+…
+</pre>
+ <li>supports-multiple-secure-codecs —
+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>
+<MediaCodecs>
+ <Settings>
+ <Setting name="supports-multiple-secure-codecs" value="false" />
+ </Settings>
+ <Encoders>
+…
+</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 0000000..e42a2af
--- /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>
