diff options
29 files changed, 2559 insertions, 259 deletions
diff --git a/OWNERS.android b/OWNERS.android new file mode 100644 index 00000000..0b6d9eff --- /dev/null +++ b/OWNERS.android @@ -0,0 +1,8 @@ +# Used by the Gerrit find-owners plugin to find reviewers +blamb@google.com +claym@google.com +cqn@google.com +daroberts@google.com +gdimino@google.com +hvm@google.com +mheco@google.com diff --git a/en/devices/tech/dalvik/improvements.html b/en/devices/tech/dalvik/improvements.html index aa41a1f0..9317e336 100644 --- a/en/devices/tech/dalvik/improvements.html +++ b/en/devices/tech/dalvik/improvements.html @@ -22,131 +22,161 @@ --> <p> -The Android runtime (ART) has been improved significantly in the Android 8.0 -release. The list below summarizes enhancements device manufacturers can expect -in ART. + The Android runtime (ART) has been improved significantly in the Android 8.0 + release. The list below summarizes enhancements device manufacturers can expect + in ART. </p> <h2 id="concurrent-compacting-gc">Concurrent compacting garbage collector</h2> -<p>As announced at Google I/O, ART features a new concurrent compacting garbage -collector (GC) in Android 8.0. This collector compacts the heap every time GC -runs and while the app is running, with only one short pause for processing -thread roots. Here are its benefits:</p> +<p> + As announced at Google I/O, ART features a new concurrent compacting garbage + collector (GC) in Android 8.0. This collector compacts the heap every time GC + runs and while the app is running, with only one short pause for processing + thread roots. Here are its benefits: +</p> <ul> - <li>GC always compacts the heap: 32% smaller heap sizes on average compared - to Android 7.0.</li> - <li>Compaction enables thread local bump pointer object allocation: - Allocations are 70% faster than in Android 7.0.</li> - <li>Offers 85% smaller pause times for the H2 benchmark compared to the - Android 7.0 GC.</li> - <li>Pause times no longer scale with heap size; apps should be able to use - large heaps without worrying about jank.</li> + <li> + GC always compacts the heap: 32% smaller heap sizes on average compared to + Android 7.0. + </li> + <li> + Compaction enables thread local bump pointer object allocation: Allocations + are 70% faster than in Android 7.0. + </li> + <li> + Offers 85% smaller pause times for the H2 benchmark compared to the Android + 7.0 GC. + </li> + <li> + Pause times no longer scale with heap size; apps should be able to use large + heaps without worrying about jank. + </li> <li>GC implementation detail - Read barriers: <ul> - <li>Read barriers are a small amount of work done for each object field - read.</li> - <li>These are optimized in the compiler, but might slow down some use - cases.</li> + <li> + Read barriers are a small amount of work done for each object field read. + </li> + <li> + These are optimized in the compiler, but might slow down some use cases. + </li> </ul> </ul> <h2 id="loop-optimizations">Loop optimizations</h2> <p> -A wide variety of loop optimizations are employed by ART in the Android 8.0 -release: -</p> - <ul> - <li>Bounds check eliminations - <ul> - <li>Static: ranges are proven to be within bounds at compile-time - <li>Dynamic: run-time tests ensure loops stay within bounds (deopt otherwise) - </ul> - <li>Induction variable eliminations - <ul> - <li>Remove dead induction - <li>Replace induction that is used only after the loop by closed-form expressions - </ul> - <li>Dead code elimination inside the loop-body, removal of whole loops that -become dead - <li>Strength reduction - <li>Loop transformations: reversal, interchanging, splitting, unrolling, -unimodular, etc. - <li>SIMDization (also called vectorization)</li> - </ul> - -<p> -The loop optimizer resides in its own optimization pass in the ART compiler. -Most loop optimizations are similar to optimizations and simplification -elsewhere. Challenges arise with some optimizations that rewrite the CFG in a -more than usual elaborate way, because most CFG utilities (see nodes.h) focus on -building a CFG, not rewriting one. + A wide variety of loop optimizations are employed by ART in the Android 8.0 + release: +</p> + +<ul> + <li>Bounds check eliminations + <ul> + <li>Static: ranges are proven to be within bounds at compile-time</li> + <li> + Dynamic: run-time tests ensure loops stay within bounds (deopt otherwise) + </li> + </ul> + </li> + <li>Induction variable eliminations + <ul> + <li>Remove dead induction</li> + <li> + Replace induction that is used only after the loop by closed-form + expressions + </li> + </ul> + </li> + <li> + Dead code elimination inside the loop-body, removal of whole loops that + become dead + </li> + <li>Strength reduction</li> + <li> + Loop transformations: reversal, interchanging, splitting, unrolling, + unimodular, etc. + </li> + <li>SIMDization (also called vectorization)</li> +</ul> + +<p> + The loop optimizer resides in its own optimization pass in the ART compiler. + Most loop optimizations are similar to optimizations and simplification + elsewhere. Challenges arise with some optimizations that rewrite the CFG in a + more than usual elaborate way, because most CFG utilities (see nodes.h) focus + on building a CFG, not rewriting one. </p> <h2 id="class-hierarchy-analysis">Class hierarchy analysis</h2> <p> -ART in Android 8.0 uses Class Hierarchy Analysis (CHA), a compiler optimization -that devirtualizes virtual calls into direct calls based on the information -generated by analyzing class hierarchies. Virtual calls are expensive since they -are implemented around a vtable lookup, and they take a couple of dependent -loads. Also virtual calls cannot be inlined. -</p> - -<p> -Here is a summary of related enhancements: -</p> - <ul> - <li>Dynamic single-implementation method status updating - At the end of class -linking time, when vtable has been populated, ART conducts an entry-by-entry -comparison to the vtable of the super class.</li> - <li>Compiler optimization - The compiler will take advantage of the -single-implementation info of a method. If a method A.foo has -single-implementation flag set, compiler will devirtualize the virtual call into -a direct call, and further try to inline the direct call as a result.</li> - <li>Compiled code invalidation - Also at the end of class linking time when -single-implementation info is updated, if method A.foo that previously had -single-implementation but that status is now invalidated, all compiled code that -depends on the assumption that method A.foo has single-implementation needs to -have their compiled code invalidated.</li> - <li>Deoptimization - For live compiled code that's on stack, deoptimization will -be initiated to force the invalidated compiled code into interpreter mode to -guarantee correctness. A new mechanism of deoptimization which is a hybrid of -synchronous and asynchronous deoptimization will be used.</li> + ART in Android 8.0 uses Class Hierarchy Analysis (CHA), a compiler optimization + that devirtualizes virtual calls into direct calls based on the information + generated by analyzing class hierarchies. Virtual calls are expensive since + they are implemented around a vtable lookup, and they take a couple of + dependent loads. Also virtual calls cannot be inlined. +</p> + +<p>Here is a summary of related enhancements:</p> + +<ul> + <li> + Dynamic single-implementation method status updating - At the end of class + linking time, when vtable has been populated, ART conducts an entry-by-entry + comparison to the vtable of the super class. + </li> + <li>Compiler optimization - The compiler will take advantage of the + single-implementation info of a method. If a method A.foo has + single-implementation flag set, compiler will devirtualize the virtual call + into a direct call, and further try to inline the direct call as a result. + </li> + <li> + Compiled code invalidation - Also at the end of class linking time when + single-implementation info is updated, if method A.foo that previously had + single-implementation but that status is now invalidated, all compiled code + that depends on the assumption that method A.foo has single-implementation + needs to have their compiled code invalidated. + </li> + <li> + Deoptimization - For live compiled code that's on stack, deoptimization will + be initiated to force the invalidated compiled code into interpreter mode to + guarantee correctness. A new mechanism of deoptimization which is a hybrid of + synchronous and asynchronous deoptimization will be used. + </li> </ul> <h2 id="inline-caches-in-oat-files">Inline caches in .oat files</h2> <p> -ART now employs inline caches and optimizes the call sites for which enough data -exists. The inline caches feature records additional runtime information into -profiles and uses it to add dynamic optimizations to ahead of time compilation. + ART now employs inline caches and optimizes the call sites for which enough + data exists. The inline caches feature records additional runtime information + into profiles and uses it to add dynamic optimizations to ahead of time compilation. </p> <h2 id="dexlayout">Dexlayout</h2> <p> -Dexlayout is a library introduced in Android 8.0 to analyze dex files and reorder -them according to a profile. Dexlayout aims to use runtime profiling information -to reorder sections of the dex file during idle maintenance compilation on -device. By grouping together parts of the dex file that are often accessed -together, programs can have better memory access patterns from improved -locality, saving RAM and shortening start up time. + Dexlayout is a library introduced in Android 8.0 to analyze dex files and + reorder them according to a profile. Dexlayout aims to use runtime profiling + information to reorder sections of the dex file during idle maintenance + compilation on device. By grouping together parts of the dex file that are + often accessed together, programs can have better memory access patterns from + improved locality, saving RAM and shortening start up time. </p> <p> -Since profile information is currently available only after apps have been run, -dexlayout is integrated in dex2oat's on-device compilation during idle -maintenance. + Since profile information is currently available only after apps have been run, + dexlayout is integrated in dex2oat's on-device compilation during idle + maintenance. </p> <h2 id="dex-cache-removal">Dex cache removal</h2> <p> -Up to Android 7.0, the DexCache object owned four large arrays, proportional to the -number of certain elements in the DexFile, namely: + Up to Android 7.0, the DexCache object owned four large arrays, proportional to + the number of certain elements in the DexFile, namely: </p> <ul> @@ -172,60 +202,145 @@ number of certain elements in the DexFile, namely: <h2 id="interpreter-performance">Interpreter performance</h2> <p> -Interpreter performance significantly improved in the Android 7.0 release with the -introduction of "mterp" - an interpreter featuring a core fetch/decode/interpret -mechanism written in assembly language. Mterp is modelled after the fast Dalvik -interpreter, and supports arm, arm64, x86, x86_64, mips and mips64. For -computational code, Art's mterp is roughly comparable to Dalvik's fast -interpreter. However, in some situations it can be significantly - and even -dramatically - slower: + Interpreter performance significantly improved in the Android 7.0 release with + the introduction of "mterp" - an interpreter featuring a core + fetch/decode/interpret mechanism written in assembly language. Mterp is + modelled after the fast Dalvik interpreter, and supports arm, arm64, x86, + x86_64, mips and mips64. For computational code, Art's mterp is roughly + comparable to Dalvik's fast interpreter. However, in some situations it can be + significantly - and even dramatically - slower: </p> - <ol> - <li>Invoke performance.</li> - <li>String manipulation, and other heavy users of methods recognized as -intrinsics in Dalvik.</li> - <li>Higher stack memory usage.</li> - </ol> +<ol> + <li>Invoke performance.</li> + <li> + String manipulation, and other heavy users of methods recognized as + intrinsics in Dalvik. + </li> + <li>Higher stack memory usage.</li> +</ol> -<p> -Android 8.0 addresses these issues. -</p> +<p>Android 8.0 addresses these issues.</p> <h2 id="more-inlining">More inlining</h2> <p> -Since Android 6.0, ART can inline any call within the same dex files, but could -only inline leaf methods from different dex files. There were two reasons for -this limitation: + Since Android 6.0, ART can inline any call within the same dex files, but could + only inline leaf methods from different dex files. There were two reasons for + this limitation: </p> - <ol> - <li>Inlining from another dex file requires to use the dex cache of that other -dex file, unlike same dex file inlining, which could just re-use the dex cache -of the caller. The dex cache is needed in compiled code for a couple of -instructions like static calls, string load, or class load. - <li>The stack maps are only encoding a method index within the current dex -file.</li> - </ol> +<ol> + <li> + Inlining from another dex file requires to use the dex cache of that other + dex file, unlike same dex file inlining, which could just re-use the dex cache + of the caller. The dex cache is needed in compiled code for a couple of + instructions like static calls, string load, or class load. + <li> + The stack maps are only encoding a method index within the current dex file. + </li> +</ol> -<p> -To address these limitations, Android 8.0: -</p> +<p>To address these limitations, Android 8.0:</p> - <ol> - <li>Removes dex cache access from compiled code (also see section "Dex cache +<ol> + <li>Removes dex cache access from compiled code (also see section "Dex cache removal")</li> - <li>Extends stack map encoding.</li> - </ol> + <li>Extends stack map encoding.</li> +</ol> <h2 id="synchronization-improvements">Synchronization improvements</h2> + +<p> + The ART team tuned the MonitorEnter/MonitorExit code paths, and reduced our + reliance on traditional memory barriers on ARMv8, replacing them with newer + (acquire/release) instructions where possible. +</p> + +<h2 id="faster-native-methods">Faster native methods</h2> + +<p> + Faster native calls to the Java Native Interface (JNI) are available using + the <a class="external" +href="https://android.googlesource.com/platform/libcore/+/master/dalvik/src/main/java/dalvik/annotation/optimization/FastNative.java" +><code>@FastNative</code></a> and <a class="external" +href="https://android.googlesource.com/platform/libcore/+/master/dalvik/src/main/java/dalvik/annotation/optimization/CriticalNative.java" +><code>@CriticalNative</code></a> annotations. These built-in ART runtime + optimizations speed up JNI transitions and replace the now deprecated + <em>!bang JNI</em> notation. The annotations have no effect on non-native + methods and are only available to platform Java Language code on the + <code>bootclasspath</code> (no Play Store updates). +</p> <p> -The ART team tuned the MonitorEnter/MonitorExit code paths, and reduced our -reliance on traditional memory barriers on ARMv8, replacing them with newer -(acquire/release) instructions where possible. + The <code>@FastNative</code> annotation supports non-static methods. Use this + if a method accesses a <code>jobject</code> as a parameter or return value. </p> +<p> + The <code>@CriticalNative</code> annotation provides an even faster way to run + native methods, with the following restrictions: +</p> + +<ul> + <li> + Methods must be static—no objects for parameters, return values, or an + implicit <code>this</code>. + </li> + <li>Only primitive types are passed to the native method.</li> + <li> + The native method does not use the <code>JNIEnv</code> and + <code>jclass</code> parameters in its function definition. + </li> + <li> + The method must be registered with <code>RegisterNatives</code> instead of + relying on dynamic JNI linking. + </li> +</ul> + +<aside class="caution"> + <p> + The <code>@FastNative</code> and <code>@CriticalNative</code> annotations + disable garbage collection while executing a native method. Do not use with + long-running methods, including usually-fast, but generally unbounded, + methods. + </p> + <p> + Pauses to the garbage collection may cause deadlock. Do not acquire locks + during a fast native call if the locks haven't been released locally (i.e. + before returning to managed code). This does not apply to regular JNI calls + since ART considers the executing native code as suspended. + </p> +</aside> + +<p> + <code>@FastNative</code> can improve native method performance up to 3x, and + <code>@CriticalNative</code> up to 5x. For example, a JNI transition measured + on a Nexus 6P device: +</p> + +<table> + <tr> + <th>Java Native Interface (JNI) invocation</th> + <th>Execution time (in nanoseconds)</th> + </tr> + <tr> + <td>Regular JNI</td> + <td>115</td> + </tr> + <tr> + <td><em>!bang JNI</em></td> + <td>60</td> + </tr> + <tr> + <td><code>@FastNative</code></td> + <td>35</td> + </tr> + <tr> + <td><code>@CriticalNative</code></td> + <td>25</td> + </tr> +</table> + </body> </html> diff --git a/en/devices/tech/debug/index.html b/en/devices/tech/debug/index.html index 702b7a14..67b2fee2 100644 --- a/en/devices/tech/debug/index.html +++ b/en/devices/tech/debug/index.html @@ -35,8 +35,10 @@ characters. This meant that to create a wrap property with the name of the app, it was necessary to truncate the name to fit. In Android O and later, this limit is much greater and should require no truncation.</p> -<p>This page covers use of <code>debuggerd</code>, a daemon process for -collecting error information after applications crash. Other pages explore system services with +<p>This page covers the basics surrounding crash dumps found in logcat output. +Other pages have far more detail about +<a href="/devices/tech/debug/native-crash.html">diagnosing native crashes</a>, +exploring system services with <a href="https://developer.android.com/studio/command-line/dumpsys.html"> <code>dumpsys</code></a>, viewing @@ -46,26 +48,28 @@ collecting error information after applications crash. Other pages explore syste <a href="/devices/tech/debug/asan.html">AddressSanitizer</a> to detect memory bugs in native code, evaluating <a href="/devices/tech/debug/eval_perf.html"> performance issues</a> (includes -<a href="/devices/tech/debug/systrace">systrace</a>), and using -<a href="/devices/tech/debug/gdb.html">GNU Project debugger (GDB)</a> and +<a href="/devices/tech/debug/systrace">systrace</a>), and using the +<a href="/devices/tech/debug/gdb.html">GNU debugger (GDB)</a> and other debugging tools.</p> -<h2 id=debuggerd>Using debuggerd</h2> +<h2 id=debuggerd>Crash dumps</h2> -<p>The <code>debuggerd</code> process dumps registers and unwinds the stack. -When a dynamically linked executable starts, several signal handlers are -registered that connect to <code>debuggerd</code> (or <code>debuggerd64)</code> -in the event that signals (such as SIGSEGV or SIGABRT) are sent to the process.</p> +<p>When a dynamically linked executable starts, several signal handlers are +registered that, in the event of a crash, cause a basic crash dump to be written to logcat +and a more detailed "tombstone" file to be written to <code>/data/tombstones/</code>. +The tombstone is a file with extra data about the crashed process. In particular, it contains +stack traces for all the threads in the crashing process (not just the thread that caught the +signal), a full memory map, and a list of all open file descriptors.</p> -<p>It's possible for <code>debuggerd</code> to attach only if nothing else is +Before Android 8.0, crashes were handled by the +<code>debuggerd</code> and <code>debuggerd64</code> daemons. In Android O and later, +<code>crash_dump32</code> and <code>crash_dump64</code> are spawned as needed.</p> + +<p>It's possible for the crash dumper to attach only if nothing else is already attached, which means using tools such as <code>strace</code> or -<code>gdb</code> will prevent <code>debuggerd</code> from working. You can also -explicitly prevent <code>debuggerd</code> from attaching by calling -<code>prctl(PR_SET_DUMPABLE, 0)</code>, which can be useful when you need to -opt out of crash reporting.</p> +<code>gdb</code> will prevent crash dumps from occurring.</p> -<p>Example <code>debuggerd</code> output (with timestamps and extraneous -information removed):</p> +<p>Example output (with timestamps and extraneous information removed):</p> <pre class="devsite-click-to-copy"> *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** @@ -90,18 +94,13 @@ backtrace: Tombstone written to: /data/tombstones/tombstone_06 </pre> -<p>The last line of <code>debuggerd</code> output dumps a summary to the log and -writes a full <em>tombstone</em> to disk. The tombstone is simply a file with -extra data about the crashed process; it contains information that can be -helpful in debugging a crash, in particular the stack traces for all threads in -the crashing process (not just the thread that caught the signal) and a full -memory map.</p> +<p>The last line of output gives the location of the full <em>tombstone</em> on disk.</p> -<p>Assuming the unstripped binaries can be found, you can get a more detailed -unwind with line number information by pasting the above example into +<p>Assuming you have the unstripped binaries available, you can get a more detailed +unwind with line number information by pasting the stack into <code>development/scripts/stack</code>:</p> -<p class="key-point"><strong>Tip:</strong> For convenience, if you've lunched +<p class="key-point"><strong>Tip:</strong> For convenience, if you've run <code>lunch</code> <code>stack</code> will be on your $PATH already so you don't need to give the full path.</p> @@ -109,7 +108,7 @@ full path.</p> development/tools/stack </pre> -<p>Example output:</p> +<p>Example output (based on the logcat output above):</p> <pre class="devsite-click-to-copy"> Reading native crash info from stdin 03-02 23:53:49.477 17951 17951 F DEBUG : *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** @@ -156,8 +155,7 @@ Stack Trace: <p class="note"><strong>Note:</strong> Some system libraries are built with <code>LOCAL_STRIP_MODULE := keep_symbols</code> to provide usable backtraces -directly from <code>debuggerd</code> without taking up anywhere near as much -space as an unstripped version.</p> +directly without taking up anywhere near as much space as an unstripped version.</p> <p>You can also <code>stack</code> an entire tombstone. Example:</p> <pre class="devsite-terminal devsite-click-to-copy"> @@ -170,8 +168,8 @@ For more information about diagnosing native crashes and tombstones, see <h2 id="tombstone">Getting a stack trace/tombstone from a running process</h2> -<p>You can also use <code>debuggerd</code> on a running process. From the -command line, invoke <code>debuggerd</code> using a process ID (PID) to dump the +<p>You can also use the <code>debuggerd</code> tool to get a stack dump from a running process. +From the command line, invoke <code>debuggerd</code> using a process ID (PID) to dump a full tombstone to <code>stdout</code>. To get just the stack for every thread in the process, include the <code>-b</code> or <code>--backtrace</code> flag.</p> diff --git a/en/source/build-numbers.html b/en/source/build-numbers.html index e9809170..eb112273 100644 --- a/en/source/build-numbers.html +++ b/en/source/build-numbers.html @@ -208,6 +208,30 @@ site:</p> </thead> <tbody> <tr> + <td>OPD3.170816.012</td> + <td>android-8.0.0_r24</td> + <td>Oreo</td> + <td>Pixel 2 XL, Pixel 2</td> + </tr> + <tr> + <td>OPD1.170816.012</td> + <td>android-8.0.0_r23</td> + <td>Oreo</td> + <td>Pixel 2 XL, Pixel 2</td> + </tr> + <tr> + <td>OPD1.170816.011</td> + <td>android-8.0.0_r22</td> + <td>Oreo</td> + <td>Pixel 2 XL, Pixel 2</td> + </tr> + <tr> + <td>OPD1.170816.010</td> + <td>android-8.0.0_r21</td> + <td>Oreo</td> + <td>Pixel 2 XL, Pixel 2</td> + </tr> + <tr> <td>OPR5.170623.007</td> <td>android-8.0.0_r17</td> <td>Oreo</td> diff --git a/en/source/initializing.html b/en/source/initializing.html index 505b647e..611d0e4c 100644 --- a/en/source/initializing.html +++ b/en/source/initializing.html @@ -270,7 +270,7 @@ To mount the image when you execute <code>mountAndroid</code>: <pre class="devsite-click-to-copy"> # mount the android file image -function mountAndroid { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; } +function mountAndroid() { hdiutil attach ~/android.dmg -mountpoint /Volumes/android; } </pre> <p class="note"><strong>Note:</strong> If your system created a diff --git a/zh-cn/compatibility/cts/audio-framework.html b/zh-cn/compatibility/cts/audio-framework.html index 849a0a36..91869099 100644 --- a/zh-cn/compatibility/cts/audio-framework.html +++ b/zh-cn/compatibility/cts/audio-framework.html @@ -20,7 +20,7 @@ limitations under the License. --> -<p>这套新的测试需要人为干预和一些外部硬件，包括<a href="#loopback_latency">回环插头</a>、<a href="#audio_frequency_speaker_test">USB 参照麦克风</a>和<a href="#audio_frequency_microphone_test">外部扬声器</a>。对于没有 3.5 毫米 (⅛") 耳机端口的设备，用户将能够跳过测试并将其标记为成功。有关详情，请参阅以下部分。</p> +<p>这套新测试需要人为干预，并会用到一些外部硬件，包括<a href="#loopback_latency">回环插头</a>、<a href="#audio_frequency_speaker_test">USB 参照麦克风</a>和<a href="#audio_frequency_microphone_test">外部扬声器</a>。对于没有 3.5 毫米 (⅛") 耳机端口的设备，用户将能够跳过测试并将其标记为成功。有关详情，请参阅以下部分。</p> <h2 id="loopback_latency">回环插头延迟测试</h2> diff --git a/zh-cn/compatibility/cts/camera-its-box-assembly.html b/zh-cn/compatibility/cts/camera-its-box-assembly.html index 00d49d5c..3ef5df0d 100644 --- a/zh-cn/compatibility/cts/camera-its-box-assembly.html +++ b/zh-cn/compatibility/cts/camera-its-box-assembly.html @@ -161,6 +161,6 @@ LED 灯应朝下，塑料板应形成灯的背板，以阻挡 LED 灯条背面 空白处应刚好贴合。如果太紧，则对其进行修剪；如果太松，则需再做一个。</li> <li>为相机切割孔。您可以切割一个孔（用于测试一部手机）或两个孔（用于测试两部手机）。Pixel 和 Pixel XL 前置摄像头和后置摄像头的孔如图 29 所示：<br /><img src="images/camera_iab_front_apertures.jpg" width="50%"/><br /> <strong>图 29</strong>. 切割了前置摄像头孔和后置摄像头孔的盒装 ITS 的正面。<br /><br /> -前置摄像头对应的是圆形孔，因为没有闪光灯或激光器，而后置摄像头对应的是矩形孔，以免遮挡闪光灯和激光器。</li></ol> +前置摄像头因为没有闪光灯或激光传感器，所以应对准圆形孔；后置摄像头则应对准矩形孔，以免遮挡闪光灯和激光传感器。</li></ol> </body></html>
\ No newline at end of file diff --git a/zh-cn/compatibility/cts/downloads.html b/zh-cn/compatibility/cts/downloads.html index 9666a009..96a4e954 100644 --- a/zh-cn/compatibility/cts/downloads.html +++ b/zh-cn/compatibility/cts/downloads.html @@ -34,42 +34,42 @@ <h2 id="android-71">Android 7.1</h2> <p>Android 7.1 是代号为 Nougat-MR1 的开发里程碑版本。 -以下测试的源代码可以与开放源代码树中的“android-cts-7.1_r9”标记同步。</p> +以下测试的源代码可以与开放源代码树中的“android-cts-7.1_r10”标记同步。</p> <ul> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-7.1_r9-linux_x86-arm.zip">Android 7.1 R9 兼容性测试套件 (CTS) - ARM</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-7.1_r9-linux_x86-x86.zip">Android 7.1 R9 兼容性测试套件 (CTS) - x86</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r9-linux_x86-arm.zip">Android 7.1 R9 CTS 验证程序 - ARM</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r9-linux_x86-x86.zip">Android 7.1 R9 CTS 验证程序 - x86</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-7.1_r10-linux_x86-arm.zip">Android 7.1 R10 兼容性测试套件 (CTS) - ARM</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-7.1_r10-linux_x86-x86.zip">Android 7.1 R10 兼容性测试套件 (CTS) - x86</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r10-linux_x86-arm.zip">Android 7.1 R10 CTS 验证程序 - ARM</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.1_r10-linux_x86-x86.zip">Android 7.1 R10 CTS 验证程序 - x86</a></li> </ul> <h2 id="android-70">Android 7.0</h2> <p>Android 7.0 是代号为 Nougat 的开发里程碑版本。 -以下测试的源代码可以与开放源代码树中的“android-cts-7.0_r13”标记同步。</p> +以下测试的源代码可以与开放源代码树中的“android-cts-7.0_r14”标记同步。</p> <ul> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-7.0_r13-linux_x86-arm.zip">Android 7.0 R13 兼容性测试套件 (CTS) - ARM</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-7.0_r13-linux_x86-x86.zip">Android 7.0 R13 兼容性测试套件 (CTS) - x86</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r13-linux_x86-arm.zip">Android 7.0 R13 CTS 验证程序 - ARM</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r13-linux_x86-x86.zip">Android 7.0 R13 CTS 验证程序 - x86</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-7.0_r14-linux_x86-arm.zip">Android 7.0 R14 兼容性测试套件 (CTS) - ARM</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-7.0_r14-linux_x86-x86.zip">Android 7.0 R14 兼容性测试套件 (CTS) - x86</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r14-linux_x86-arm.zip">Android 7.0 R14 CTS 验证程序 - ARM</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-7.0_r14-linux_x86-x86.zip">Android 7.0 R14 CTS 验证程序 - x86</a></li> </ul> <h2 id="android-60">Android 6.0</h2> <p>Android 6.0 是代号为 Marshmallow 的开发里程碑版本。 -以下测试的源代码可以与开放源代码树中的“android-cts-6.0_r22”标记同步。</p> +以下测试的源代码可以与开放源代码树中的“android-cts-6.0_r23”标记同步。</p> <ul> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-6.0_r22-linux_x86-arm.zip">Android 6.0 R22 兼容性测试套件 (CTS) - ARM</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-6.0_r22-linux_x86-x86.zip">Android 6.0 R22 兼容性测试套件 (CTS) - x86</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r22-linux_x86-arm.zip">Android 6.0 R22 CTS 验证程序 - ARM</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r22-linux_x86-x86.zip">Android 6.0 R22 CTS 验证程序 - x86</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-6.0_r23-linux_x86-arm.zip">Android 6.0 R23 兼容性测试套件 (CTS) - ARM</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-6.0_r23-linux_x86-x86.zip">Android 6.0 R23 兼容性测试套件 (CTS) - x86</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r23-linux_x86-arm.zip">Android 6.0 R23 CTS 验证程序 - ARM</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-6.0_r23-linux_x86-x86.zip">Android 6.0 R23 CTS 验证程序 - x86</a></li> </ul> <h2 id="android-51">Android 5.1</h2> <p>Android 5.1 是代号为 Lollipop-MR1 的开发里程碑版本。 -以下测试的源代码可以与开放源代码树中的“android-cts-5.1_r23”标记同步。</p> +以下测试的源代码可以与开放源代码树中的“android-cts-5.1_r24”标记同步。</p> <ul> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-5.1_r23-linux_x86-arm.zip">Android 5.1 R23 兼容性测试套件 (CTS) - ARM</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-5.1_r23-linux_x86-x86.zip">Android 5.1 R23 兼容性测试套件 (CTS) - x86</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r23-linux_x86-arm.zip">Android 5.1 R23 CTS 验证程序 - ARM</a></li> -<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r23-linux_x86-x86.zip">Android 5.1 R23 CTS 验证程序 - x86</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-5.1_r24-linux_x86-arm.zip">Android 5.1 R24 兼容性测试套件 (CTS) - ARM</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-5.1_r24-linux_x86-x86.zip">Android 5.1 R24 兼容性测试套件 (CTS) - x86</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r24-linux_x86-arm.zip">Android 5.1 R24 CTS 验证程序 - ARM</a></li> +<li><a href="https://dl.google.com/dl/android/cts/android-cts-verifier-5.1_r24-linux_x86-x86.zip">Android 5.1 R24 CTS 验证程序 - x86</a></li> </ul> <h2 id="android-50">Android 5.0</h2> diff --git a/zh-cn/compatibility/cts/interpret.html b/zh-cn/compatibility/cts/interpret.html index e1e5721e..9c2fd3c3 100644 --- a/zh-cn/compatibility/cts/interpret.html +++ b/zh-cn/compatibility/cts/interpret.html @@ -29,7 +29,7 @@ $CTS_ROOT/android-cts/repository/results/<start_time>.zip <p>在 zip 压缩包中，testResult.xml 文件会包含实际的结果。在任何网络浏览器（推荐使用与 HTML 5 技术兼容的浏览器）中打开此文件，即可查看测试结果。</p> -<p>使用 Chrome 浏览器时，如果 testResult.xml 显示空白页面，请<a href="https://www.chromium.org/developers/how-tos/run-chromium-with-flags">更改浏览器配置</a>以启用 --allow-file-access-from-files 命令行标记。<em></em> </p> +<p>使用 Chrome 浏览器时，如果 testResult.xml 显示空白页面，请<a href="https://www.chromium.org/developers/how-tos/run-chromium-with-flags">更改浏览器配置</a>以启用 --allow-file-access-from-files 命令行标记。<em></em></p> <h3 id="reading-the-test-results">阅读测试结果</h3> diff --git a/zh-cn/compatibility/cts/setup.html b/zh-cn/compatibility/cts/setup.html index a78bfb7e..2150eee8 100644 --- a/zh-cn/compatibility/cts/setup.html +++ b/zh-cn/compatibility/cts/setup.html @@ -36,7 +36,7 @@ <p>CTS 目前支持 64 位 Linux 和 Mac OS 主机。</p> <h3 id="adb">ADB 和 AAPT</h3> -<p>在运行 CTS 之前，请确保您已安装最新版本的 <a href="http://developer.android.com/tools/help/adb.html">Android 调试桥 (adb)</a> 和 <a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html#testing">Android 资源打包工具 (AAPT)</a>，并将这些工具的位置添加到计算机的系统路径中。 </p> +<p>在运行 CTS 之前，请确保您已安装最新版本的 <a href="http://developer.android.com/tools/help/adb.html">Android 调试桥 (adb)</a> 和 <a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html#testing">Android 资源打包工具 (AAPT)</a>，并将这些工具的位置添加到计算机的系统路径中。</p> <p>要安装 ADB，请下载适用于您的操作系统的 <a href="http://developer.android.com/sdk/index.html#Other">Android SDK 工具</a>包，打开它，然后按照附带的 README 文件中的说明进行操作。要了解问题排查相关信息，请参阅<a href="http://developer.android.com/sdk/installing/index.html?pkg=tools">安装独立 SDK 工具</a>。</p> diff --git a/zh-cn/devices/architecture/dto/compile.html b/zh-cn/devices/architecture/dto/compile.html new file mode 100644 index 00000000..d861ad4f --- /dev/null +++ b/zh-cn/devices/architecture/dto/compile.html @@ -0,0 +1,72 @@ +<html devsite><head> + <title>编译和验证</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>您可以使用设备树编译器 (DTC) 来编译设备树源文件。不过，在将叠加 DT 应用于目标主 DT 之前，您还应该通过模拟 DTO 的行为来验证结果。</p> + +<h2 id="compile">通过 DTC 进行编译</h2> +<p>使用 <code>dtc</code> 编译 <code>.dts</code> 时，您必须添加选项 <code>-@</code> 以在生成的 <code>.dtbo</code> 中添加 <code>__symbols__</code> 节点。<code>__symbols__</code> 节点包含带标签的所有节点的列表，DTO 库可使用这个列表作为参考。</p> + +<p>编译主 <code>.dts</code> 的示例命令：</p> + +<pre class="devsite-terminal"> +dtc -@ -O dtb -o my_main_dt.dtb my_main_dt.dts +</pre> + +<p>编译叠加 DT <code>.dts</code> 的示例命令：</p> + +<pre class="devsite-terminal"> +dtc -@ -O dtb -o my_overlay_dt.dtbo my_overlay_dt.dts +</pre> + +<p class="note"><strong>注意</strong>：如果您遇到 DTC 编译错误：<code>invalid option --'@'</code>，则可能需要更新 DTC 版本。在 AOSP 上游，官方 DTC 对 DTO 的支持从<a href="https://github.com/dgibson/dtc/tree/v1.4.4" class="external">版本 1.4.4</a> 开始，而且大部分补丁程序在 2016 年 12 月后就完成了合并。为了支持 DTO，建议您使用 AOSP 中的 <code><a href="https://android.googlesource.com/platform/external/dtc/" class="external">external/dtc</a></code>，它已与最新的 DTC 同步（已视需要合并 DTO 补丁程序）。</p> + +<h2 id="verify">在主机上验证 DTO 结果</h2> +<p>验证流程可以帮助您识别将叠加 DT 放在主 DT 上时可能发生的错误。更新目标之前，您可以通过在 <code>.dts</code> 中使用 <code>/include/</code> 来模拟 DTO 行为，从而在主机上验证叠加 DT 的结果。</p> + +<p class="note"><strong>注意</strong>：<code>/include/</code> 不支持在叠加 DT 源中使用 <code>__overlay__</code>。</p> + +<p><img src="../images/treble_dto_simulate.png"/></p> +<p><strong>图 1</strong> 使用语法 <code>/include/</code> 来模拟主机上的 DTO。</p> + +<ol> +<li>创建叠加 <code>.dts</code> 的副本。在副本中，移除第一行头文件。例如：<pre> +/dts-v1/; +/plugin/; +</pre>将文件另存为 <code>my_overlay_dt_wo_header.dts</code>（或您希望的任何文件名）。</li> + +<li>创建主 <code>.dts</code> 的副本。在副本中的最后一行后，为您在第 1 步中创建的文件附加包含语法。例如：<pre> +/include/ "my_overlay_dt_wo_header.dts" +</pre>将文件另存为 <code>my_main_dt_with_include.dts</code>（或您希望的任何文件名）。</li> + +<li>使用 <code>dtc</code> 编译 <code>my_main_dt_with_include.dts</code> 以获得合并的 DT，这应该与使用 DTO 进行编译所得到的结果相同。例如：<pre class="devsite-terminal"> +dtc -@ -O dtb -o my_merged_dt.dtb my_main_dt_with_include.dts +</pre> +</li> + +<li>使用 <code>dtc</code> 转储 <code>my_merged_dt.dto</code>。 +<pre class="devsite-terminal"> +dtc -O dts -o my_merged_dt.dts my_merged_dt.dtb +</pre> +</li> +</ol> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/dto/implement.html b/zh-cn/devices/architecture/dto/implement.html new file mode 100644 index 00000000..3be4594a --- /dev/null +++ b/zh-cn/devices/architecture/dto/implement.html @@ -0,0 +1,140 @@ +<html devsite><head> + <title>实现 DTO</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>实现 DTO 包括分割设备树、编译、分区和运行。在实现可以正常工作之后，您还必须保持两个 DT 之间的兼容性，并确定用于确保每个 DT 分区安全性的策略。</p> + +<h2 id="divide">分割 DT</h2> +<p>首先将设备树分割成两 (2) 部分：</p> +<ul> +<li><strong>主 DT</strong>。由 SoC 供应商提供的 SoC 公用部分和默认配置。</li> +<li><strong>叠加 DT</strong>。由原始设计制造商 (ODM)/原始设备制造商(OEM) 提供的设备专属配置。</li> +</ul> +<p>分割设备树之后，您必须确保主 DT 和叠加 DT 之间的兼容性，以便通过合并主 DT 和叠加 DT 为设备生成完整的 DT。有关 DTO 格式和规则的详细信息，请参阅 <a href="/devices/architecture/dto/syntax.html">DTO 语法</a>。有关多个设备树的详细信息，请参阅<a href="/devices/architecture/dto/multiple.html">多个 DT</a>。</p> + +<h2 id="build">编译主 DT 和叠加 DT</h2> +<p>要编译主 DT，请执行以下操作：</p> +<ol> +<li>将主 <code>.dts</code> 编译为 <code>.dtb</code> 文件。</li> +<li>将 <code>.dtb</code> 文件刷写到引导加载程序在运行时可访问的分区（详见下文）。</li> +</ol> + +<p>要编译叠加 DT，请执行以下操作：</p> +<ol> +<li>将叠加 DT <code>.dts</code> 编译为 <code>.dtbo</code> 文件。虽然此文件格式与已格式化为扁平化设备树的 <code>.dtb</code> 文件相同，但是不同的文件扩展名可以将其与主 DT 区分开来。</li> +<li>将 <code>.dtbo</code> 文件刷写到引导加载程序在运行时可访问的分区（详见下文）。</li> +</ol> + +<p>要详细了解如何使用 DTC 进行编译并在主机上验证 DTO 结果，请参阅<a href="/devices/architecture/dto/compile.html">编译和验证</a>。 +</p> + +<h2 id="partition">对 DT 进行分区</h2> +<p>在闪存中确定引导加载程序在运行时可访问和可信的位置信息以放入 <code>.dtb</code> 和 <code>.dtbo</code>。</p> + +<p>主 DT 的示例位置：</p> +<ul> +<li>引导分区的一部分，已附加到内核 (<code>image.gz</code>)。</li> +<li>单独的 DT blob (<code>.dtb</code>)，位于专用分区 (<code>dtb</code>) 中。</li> +</ul> + +<p>叠加 DT 的示例位置：</p> + +<div style="width:75%"> +<div class="attempt-left"> +<table><tbody><tr><th style="text-align: center;">唯一分区</th></tr></tbody></table> +<figure id="treble_dto_dtbo_partition_1"> +<img src="../images/treble_dto_dtbo_partition_1.png" style="display:block; margin:0 auto"/> +<figcaption> +<strong>图 1</strong> 将 <code>.dtbo</code> 放在唯一的分区（例如 <code>dtbo</code> 分区）中。 +</figcaption> +</figure> +</div> +<div class="attempt-right"> +<figure id="treble_dto_dtbo_partition_2"> +<table><tbody><tr><th style="text-align: center;">ODM 分区</th></tr></tbody></table> +<img src="../images/treble_dto_dtbo_partition_2.png" style="display:block; margin:0 auto"/> +<figcaption> +<strong>图 2.</strong> 将 <code>.dtbo</code> 放入 <code>odm</code> 分区中（仅在您的引导加载程序能够从 <code>odm</code> 分区的文件系统中加载数据时才这样做）。 +</figcaption> +</figure> +</div> +</div> + +<p class="note" style="clear:both"><strong>注意</strong>：叠加 DT 分区的大小取决于设备和主 DT blob 上所需的更改量。通常，8 MB 已足够当前使用并已为未来扩展留出了空间（如果需要的话）。</p> + +<p>对于支持<a href="https://source.android.com/devices/tech/ota/ab_updates.html">无缝 (A/B) 更新</a>的设备，请用 A/B 来标识主 DT 和叠加 DT 分区：</p> + +<div style="width:75%"> +<div class="attempt-left"> +<table><tbody><tr><th style="text-align: center;">示例 1</th></tr></tbody></table> +<figure id="treble_dto_dtbo_ab_1"> +<img src="../images/treble_dto_dtbo_ab_1.png" style="display:block; margin:0 auto"/> +<figcaption> +<strong>图 3.</strong> DTBO 分区 A/B，示例 1。 +</figcaption> +</figure> +</div> +<div class="attempt-right"> +<table><tbody><tr><th style="text-align: center;">示例 2</th></tr></tbody></table> +<figure id="treble_dto_dtbo_ab_2"> +<img src="../images/treble_dto_dtbo_ab_2.png" style="display:block; margin:0 auto"/> +<figcaption> +<strong>图 4.</strong> DTBO 分区 A/B，示例 2。 +</figcaption> +</figure> +</div> +</div> + +<h2 id="run" style="clear:both">在引导加载程序中运行</h2> +<p>要运行，请执行以下操作：</p> + +<figure id="treble_dto_dtbo"> +<img src="../images/treble_dto_dtbo.png"/> +<figcaption><strong>图 5.</strong> 引导加载程序中设备树叠加层的典型运行时实现。</figcaption> +</figure> + +<ol> +<li>将 <code>.dtb</code> 从存储加载到内存中。</li> +<li>将 <code>.dtbo</code> 从存储加载到内存中。</li> +<li>用 <code>.dtbo</code> 叠加 <code>.dtb</code> 以形成合并的 DT。</li> +<li>启动内核（已给定合并 DT 的内存地址）。</li> +</ol> + +<h2 id="maintain">保持兼容性</h2> +<p>主 DTB（来自 SoC 供应商）会被视为 DTBO 的 API 表面。将设备树分离为 SoC 通用部件和设备专用部件后，您必须确保这两个部件以后相互兼容，包括：</p> + +<ul> +<li><strong>主 DT 中的 DT 定义</strong><em>（例如，节点、属性、标签）</em>。主 DT 中的任何定义更改都可能会触发叠加 DT 中的更改。例如，要更正主 DT 中的某个节点名称，请定义映射到原始节点名称的“别名”标签（以避免更改叠加 DT）。</li> +<li><strong>叠加 DT 的存储位置</strong><em>（例如，分区名称、存储格式）</em>。</li> +</ul> + +<h2 id="security">确保安全</h2> +<p>引导加载程序必须确保 DTB/DTBO 安全无虞、未被修改且未被损坏。您可以使用任何解决方案来保护 DTB/DTBO，例如，VBoot 1.0 中的<a href="/security/verifiedboot/verified-boot#signature_format">启动映像签名</a>或 <a href="https://android.googlesource.com/platform/external/avb/+/master/README.md#The-VBMeta-struct" class="external">AVB 哈希页脚</a> (VBoot 2.0)。 +</p> + +<ul> +<li>如果 DTB/DTBO 位于唯一的分区中，则可以将该分区添加到 AVB 的信任链。信任链从硬件保护的信任根开始，并进入引导加载程序，从而验证 DTB/DTBO 分区的完整性和真实性。</li> +<li>如果 DTB/DTBO 位于现有分区（如 <code>odm</code> 分区）中，则该分区应位于 AVB 的信任链中。（DTBO 分区可以与 <code>odm</code> 分区共享一个公共密钥）。</li> +</ul> + +<p>有关详细信息，请参阅<a href="/security/verifiedboot/index.html">验证启动</a>。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/dto/index.html b/zh-cn/devices/architecture/dto/index.html new file mode 100644 index 00000000..6f4e2d87 --- /dev/null +++ b/zh-cn/devices/architecture/dto/index.html @@ -0,0 +1,108 @@ +<html devsite><head> + <title>设备树叠加层</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>设备树 (DT) 是用于描述“不可发现”硬件的命名节点和属性的数据结构。操作系统（例如在 Android 中使用的 Linux 内核）会使用 DT 来支持 Android 设备使用的各种硬件配置。硬件供应商会提供自己的 DT 源文件，接下来 Linux 会将这些文件编译到引导加载程序使用的设备树 Blob (DTB) 文件中。</p><a href="https://lkml.org/lkml/2012/11/5/615" class="external">设备树叠加层</a> (DTO) 可让主要的 DTB 叠加在设备树上。使用 DTO 的引导加载程序可以维护系统芯片 (SoC) DT，并动态叠加设备特定的 DT，从而向树中添加节点并对现有树中的属性进行更改。<p></p> + +<p>本页详细介绍了引导加载程序加载 DT 的典型工作流程，并列出了常见的 DT 术语。本节的其他页介绍了如何<a href="/devices/architecture/dto/implement.html">为 DTO 实现引导加载程序支持</a>，如何<a href="/devices/architecture/dto/compile.html">编译</a>、验证和<a href="/devices/architecture/dto/optimize.html">优化 DTO 实现</a>以及如何<a href="/devices/architecture/dto/multiple.html">使用多个 DT</a>。您还可以获取关于 <a href="/devices/architecture/dto/syntax.html">DTO 语法</a>和推荐的 <a href="/devices/architecture/dto/partition.html">DTO/DTBO 分区格式的详细信息</a>。</p> + +<h2 id="load-dt">加载设备树</h2> +<p>在引导加载程序中加载设备树会涉及到编译、分区和运行。</p> + +<figure id="treble_dto_bootloader"> +<img src="../images/treble_dto_bootloader.png"/> +<figcaption><strong>图 1</strong> 用于在引导加载程序中加载设备树的典型实现。</figcaption> +</figure> + +<ol> +<li>要进行编译，请执行以下操作：<ul> +<li>使用设备树编译器 (<code>dtc</code>) 将设备树源 (<code>.dts</code>) 编译为设备树 blob (<code>.dtb</code>)（格式化为扁平设备树）。</li> +<li>将 <code>.dtb</code> 文件刷写到引导加载程序在运行时可访问的位置（详见下文）。</li> +</ul> +</li> +<li>要进行分区，请确定闪存中引导加载程序在运行时可访问和可信的位置以放入 <code>.dtb</code>。位置示例： + +<div style="width:75%"> +<div class="attempt-left"> +<table><tbody><tr><th style="text-align: center;">启动分区</th></tr></tbody></table> +<figure id="treble_dto_partition_1"> +<img src="../images/treble_dto_partition_1.png" style="display:block; margin:0 auto"/> +<figcaption> +<strong>图 2.</strong> 将 <code>.dtb</code> 附加到 <code>image.gz</code> 并作为“<code>kernel</code>”传递到 <code>mkbootimg</code>，从而将其放入启动分区。 +</figcaption> +</figure> +</div> +<div class="attempt-right"> +<table><tbody><tr><th style="text-align: center;">唯一的分区</th></tr></tbody></table> +<figure id="treble_dto_partition_2"> +<img src="../images/treble_dto_partition_2.png" style="display:block; margin:0 auto"/> +<figcaption> +<strong>图 3.</strong> 将 <code>.dtb</code> 放在唯一的分区（例如 <code>dtb</code> 分区）中。 +</figcaption> +</figure> +</div> +</div> +</li> + +<li style="clear:both">要运行，请执行以下操作： +<ul> +<li>将 <code>.dtb</code> 从存储加载到内存中。</li> +<li>启动内核（已给定所加载 DT 的内存地址）。</li> +</ul> +</li> +</ol> + +<h2 id="terms">术语</h2> +<p>本节使用以下设备树术语：</p> +<table> +<tbody> +<tr> +<th>DT</th> +<td>设备树</td> +</tr> +<tr> +<th>DTB</th> +<td>设备树 Blob</td> +</tr> +<tr> +<th>DTBO</th> +<td>用于叠加的设备树 Blob</td> +</tr> +<tr> +<th>DTC</th> +<td>设备树编译器</td> +</tr> +<tr> +<th>DTO</th> +<td>设备树叠加层</td> +</tr> +<tr> +<th>DTS</th> +<td>设备树源</td> +</tr> +<tr> +<th>FDT</th> +<td>扁平化设备树，包含在 <code>.dtb</code> blob 文件中的二进制格式</td> +</tr> +</tbody> +</table> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/dto/multiple.html b/zh-cn/devices/architecture/dto/multiple.html new file mode 100644 index 00000000..2f1a9a26 --- /dev/null +++ b/zh-cn/devices/architecture/dto/multiple.html @@ -0,0 +1,57 @@ +<html devsite><head> + <title>使用多个 DT</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>很多 SoC 供应商和原始设计制造商 (ODM) 都支持在一台设备上使用多个 DT，从而使一个映像能够为多个 SKU/配置提供支持。在这种情况下，引导加载程序会在运行时识别硬件，并加载相应的 DT：</p> + +<p><img src="../images/treble_dto_multiple_dt.png"/></p> +<figcaption><strong>图 1</strong> 引导加载程序中的多个设备树叠加层。</figcaption> + +<p class="note"><strong>注意</strong>：使用多个 DT 不是强制性要求。</p> + +<h2 id="setting">设置</h2> +<p>要向 DTO 模型添加对多个 DT 的支持，请设置一个主 DT 列表和另一个叠加 DT 列表。</p> + +<p><img src="../images/treble_dto_multiple_dt_runtime.png"/></p> +<figcaption><strong>图 2.</strong> 多个 DT 的运行时 DTO 实现。</figcaption> + +<p>引导加载程序应该能够：</p> + +<ul> +<li>读取 SoC ID 并选择相应的主 DT，并</li> +<li>读取板 ID 并选择相应的叠加 DT。</li> +</ul> + +<p>仅选择一个主 DT 和一个叠加 DT 以便在运行时使用，并且所选择的对必须是兼容的。</p> + +<h2 id="partition">分区</h2> +<p>要进行分区，请在闪存中确定引导加载程序在运行时可访问和可信的位置，以存储 DTB 和 DTBO（引导加载程序必须能够在匹配的进程中找到这些文件）。请记住，DTB 和 DTBO 不能存在于同一个分区中。如果您的 DTB/DTBO 位于 <code>dtb</code>/<code>dtbo</code> 分区中，请使用 <a href="/devices/architecture/dto/partitions.html">DTB/DTBO 分区格式</a>中详细列出的表结构和头文件格式。</p> + +<h2 id="runtime">在引导加载程序中运行</h2> +<p>要运行，请执行以下操作：</p> +<ol> +<li><strong>标识 SoC</strong> 并将相应的 .dtb 从存储加载到内存中。</li> +<li><strong>标识板</strong>并将相应的 <code>.dtbo</code> 从存储加载到内存中。</li> +<li>用 <code>.dtbo</code> 叠加 <code>.dtb</code> 以形成合并的 DT。</li> +<li>启动内核（已给定合并 DT 的内存地址）。</li> +</ol> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/dto/optimize.html b/zh-cn/devices/architecture/dto/optimize.html new file mode 100644 index 00000000..3fca0732 --- /dev/null +++ b/zh-cn/devices/architecture/dto/optimize.html @@ -0,0 +1,246 @@ +<html devsite><head> + <title>优化 DTO</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>本页详细介绍了您可以对 DTO 实现进行哪些优化，描述了针对叠加根节点的限制，并提供了示例实现说明和代码。</p> + +<h2 id="kernel">内核命令行</h2> +<p>设备树中的原始内核命令行位于 <code>chosen/bootargs</code> 节点中。引导加载程序必须将此位置与内核命令行的其他源进行串联：</p> +<pre class="prettyprint"> +/dts-v1/; + +/ { + chosen: chosen { + bootargs = "..."; + }; +}; +</pre> + +<p>DTO <strong>无法</strong>串联主 DT 和叠加 DT 的值。建议您将主 DT 的内核命令行置入 <code>chosen/bootargs</code> 中，将叠加 DT 的内核命令行置入 <code>chosen/bootargs_ext</code> 中。接下来，引导加载程序会合并这些位置，并将结果传递给内核。</p> + +<table> +<tbody><tr> +<th width="50%">main.dts</th> +<th>overlay.dts</th> +</tr> +<tr> +<td> +<pre class="prettyprint"> + +/dts-v1/; + +/ { + chosen: chosen { + bootargs = "..."; + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> + +/dts-v1/; +/plugin/; + +&chosen { + bootargs_ext = "..."; +}; +</pre> +</td> +</tr> +</tbody></table> + +<h2 id="libufdt">libufdt</h2> +<p>虽然最新的 <code><a href="https://github.com/dgibson/dtc/tree/master/libfdt" class="external">libfdt</a></code> 支持 DTO，但是我们建议您使用 <code>libufdt</code> 来实现 DTO（源文件位于 AOSP 中的 <code><a href="https://android.googlesource.com/platform/system/libufdt/+/refs/heads/master" class="external">platform/system/libufdt</a></code> 下）。<code>libufdt</code> 会从扁平化设备树 (FDT) 编译真实的树结构（非扁平化设备树，简称为 <em>ufdt</em>），因而可以改善两个 <code>.dtb</code> 文件（从 O(N2) 到 O(N)，其中 N 是树中的节点编号）的合并。</p> + +<h3 id="performance">性能测试</h3> +<p>在 Google 的内部测试中，进行编译后，在 2405 <code>.dtb</code> 和 283 <code>.dtbo</code> DT 节点上使用 <code>libufdt</code> 生成了 70,618 字节和 8,566 字节的文件大小。与从 FreeBSD 移植的 <a href="http://fxr.watson.org/fxr/source/boot/fdt/" class="external">DTO 实现</a>（运行时为 124 毫秒）相比，<code>libufdt</code> DTO 运行时为 10 毫秒。</p> + +<p>在 Pixel 设备的性能测试中，我们比较了 <code>libufdt</code> 和 <code>libfdt</code>。基本节点数量带来的影响相似，但包含以下差异：</p> +<ul> +<li>500 次叠加（附加或覆盖）操作具有 6〜8 倍的时间差异</li> +<li>1000 次叠加（附加或覆盖）操作具有 8〜10 倍的时间差异</li> +</ul> + +<p>附加计数设置为 X 的示例：</p> +<p><img src="../images/treble_dto_appending.png"/></p> +<figcaption><strong>图 1</strong> 附加计数为 X。</figcaption> + +<p>覆盖计数设置为 X 的示例：</p> +<p><img src="../images/treble_dto_overriding.png"/></p> +<figcaption><strong>图 2.</strong> 覆盖计数为 X。</figcaption> + +<p><code>libufdt</code> 是用一些 <code>libfdt</code> API 和数据结构开发的。使用 <code>libufdt</code> 时，您必须包含并链接 <code>libfdt</code>（不过，您可以在代码中使用 <code>libfdt</code> API 来操作 DTB 或 DTBO）。</p> + +<h3 id="api">libufdt DTO API</h3> +<p><code>libufdt</code> 中适用于 DTO 的主要 API 如下：</p> +<pre class="prettyprint"> +struct fdt_header *ufdt_apply_overlay( + struct fdt_header *main_fdt_header, + size_t main_fdt_size, + void *overlay_fdt, + size_t overlay_size); +</pre> + +<p>参数 <code>main_fdt_header</code> 是主 DT，<code>overlay_fdt</code> 是包含 <code>.dtbo</code> 文件内容的缓冲区。返回值是一个包含合并的 DT 的新缓冲区（如果出现错误，则返回 <code>null</code>）。合并的 DT 会在 FDT 中进行格式化，您可以在启动内核时将其传递给内核。</p> + +<p>来自返回值的新缓冲区由 <code>dto_malloc()</code>（您应在将 <code>libufdt</code> 移植到引导加载程序时加以实现）创建。有关参考实现，请参阅 <code>sysdeps/libufdt_sysdeps_*.c</code>。</p> + +<h2 id="root">根节点限制</h2> +<p>您不能将新节点或属性叠加到主 DT 的根节点，因为叠加操作依赖于标签。由于主 DT 必须定义一个标签，而叠加 DT 则会分配要叠加标签的节点，因此，我们无法为根节点提供标签（因而不能叠加根节点）。</p> + +<p>SoC 供应商必须定义主 DT 的叠加能力；ODM/OEM 只能使用由 SoC 供应商定义的标签附加或叠加节点。要解决这个问题，您可以在基础 DT 中的根节点下定义一个 <strong><code>odm</code></strong> 节点，使叠加 DT 中的所有 ODM 节点都能够添加新节点。或者，您也可以将基础 DT 中的所有 SoC 相关节点放在根节点下的 <strong><code>soc</code></strong> 节点中，如下所述：</p> + +<table> +<tbody><tr> +<th width="50%">main.dts</th> +<th>overlay.dts</th> +</tr> +<tr> +<td> +<pre> + +/dts-v1/; + +/ { + compatible = "corp,bar"; + ... + + chosen: chosen { + bootargs = "..."; + }; + + /* nodes for all soc nodes */ + soc { + ... + soc_device@0: soc_device@0 { + compatible = "corp,bar"; + ... + }; + ... + }; + + odm: odm { + /* reserved for overlay by odm */ + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> + +/dts-v1/; +/plugin/; + +/ { +}; + +&chosen { + bootargs_ex = "..."; +}; + +&odm { + odm_device@0 { + ... + }; + ... +}; +</pre> +</td> +</tr> +</tbody></table> + +<h2 id="sample">DTO 实现示例</h2> +<p>以下说明介绍了使用 <code>libufdt</code> 进行 DTO 实现的示例过程（示例代码如下）。</p> + +<h3 id="sample-instructions">示例 DTO 说明</h3> + +<ol> +<li>包含库。要使用 <code>libufdt</code>，请包含 <code>libfdt</code> 以用于数据结构和 API：<pre class="prettyprint"> +#include <libfdt.h> +#include <ufdt_overlay.h> +</pre> +</li> + +<li>加载主 DT 和叠加 DT。将 <code>.dtb</code> 和 <code>.dtbo</code> 从存储加载到内存中（确切的步骤取决于您的设计）。此时，您应该设置 <code>.dtb</code>/<code>.dtbo</code> 的缓冲区和大小：<pre class="prettyprint"> +main_size = my_load_main_dtb(main_buf, main_buf_size) +</pre> +<pre class="prettyprint"> +overlay_size = my_load_overlay_dtb(overlay_buf, overlay_buf_size); +</pre> +</li> + +<li>叠加 DT：<ol> + +<li>使用 <code>ufdt_install_blob()</code> 获取主 DT 的 FDT 头文件：<pre class="prettyprint"> +main_fdt_header = ufdt_install_blob(main_buf, main_size); +main_fdt_size = main_size; +</pre> +</li> +<li>对 DTO 调用 <code>ufdt_apply_overlay()</code> 以获取采用 FDT 格式的合并 DT：<pre class="prettyprint"> +merged_fdt = ufdt_apply_overlay(main_fdt_header, main_fdt_size, + overlay_buf, overlay_size); +</pre> +</li> + +<li>要获取 <code>merged_fdt</code> 的大小，请使用 <code>dtc_totalsize()</code>：<pre class="prettyprint"> +merged_fdt_size = dtc_totalsize(merged_fdt); +</pre> +</li> + +<li>传递合并的 DT 以启动内核。当您启动内核时，请将合并的 DT 传递给内核：<pre class="prettyprint"> +my_kernel_entry(0, machine_type, merged_fdt); +</pre> +</li> +</ol></li></ol> + +<h3 id="sample-code">示例 DTO 代码</h3> +<pre class="prettyprint"> +#include <libfdt.h> +#include <ufdt_overlay.h> + +… + +{ + struct fdt_header *main_fdt_header; + struct fdt_header *merged_fdt; + + /* load main dtb into memory and get the size */ + main_size = my_load_main_dtb(main_buf, main_buf_size); + + /* load overlay dtb into memory and get the size */ + overlay_size = my_load_overlay_dtb(overlay_buf, overlay_buf_size); + + /* overlay */ + main_fdt_header = ufdt_install_blob(main_buf, main_size); + main_fdt_size = main_size; + merged_fdt = ufdt_apply_overlay(main_fdt_header, main_fdt_size, + overlay_buf, overlay_size); + merged_fdt_size = dtc_totalsize(merged_fdt); + + /* pass to kernel */ + my_kernel_entry(0, machine_type, merged_fdt); +} +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/dto/partitions.html b/zh-cn/devices/architecture/dto/partitions.html new file mode 100644 index 00000000..a5fb8bea --- /dev/null +++ b/zh-cn/devices/architecture/dto/partitions.html @@ -0,0 +1,252 @@ +<html devsite><head> + <title>DTB/DTBO 分区</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>如果您的 DTB/DTBO 位于专属的分区（例如 <code>dtb</code> 和 <code>dtbo</code> 分区）中，请使用以下表格结构和头文件格式：</p> + +<p><img src="../images/treble_dto_partition_layout.png"/></p> +<figcaption><strong>图 1</strong> <code>dtb</code>/<code>dtbo</code> 分区布局示例（要了解 AVB 签名相关信息，请参阅<a href="/devices/architecture/dto/implement.html#security">安全性</a>）。 +</figcaption> + +<h2 id="structures">数据结构</h2> +<p><code>dt_table_header</code> <strong>仅</strong>适用于 <code>dtb</code>/<code>dtbo</code> 分区；您不能在 <code>image.gz</code> 末尾处附加此格式。如果您有一个 DTB/DTBO，则仍必须使用此格式（并且，<code>dt_table_header</code> 中的 <code>dt_entry_size</code> 为 1）。</p> + +<pre class="prettyprint"> +#define DT_TABLE_MAGIC 0xd7b7ab1e + +struct dt_table_header { + uint32_t magic; // DT_TABLE_MAGIC + uint32_t total_size; // includes dt_table_header + all dt_table_entry + // and all dtb/dtbo + uint32_t header_size; // sizeof(dt_table_header) + + uint32_t dt_entry_size; // sizeof(dt_table_entry) + uint32_t dt_entry_count; // number of dt_table_entry + uint32_t dt_entries_offset; // offset to the first dt_table_entry + // from head of dt_table_header + + uint32_t page_size; // flash page size we assume + uint32_t reserved[1]; // must be zero +}; + +struct dt_table_entry { + uint32_t dt_size; + uint32_t dt_offset; // offset from head of dt_table_header + + uint32_t id; // optional, must be zero if unused + uint32_t rev; // optional, must be zero if unused + uint32_t custom[4]; // optional, must be zero if unused +}; +</pre> + +<p>要读取所有 <code>dt_table_entry</code>，请使用 <code>dt_entry_size</code>、<code>dt_entry_count</code> 和 <code>dt_entries_offset</code>。示例：</p> +<pre class="prettyprint"> +my_read(entries_buf, + header_addr + header->dt_entries_offset, + header->dt_entry_size * header->dt_entry_count); +</pre> + +<p><code>dt_table_entry</code> 中的 <code>id</code>、<code>rev</code>、<code>custom</code> 是设备树的可选硬件标识，引导加载程序可以使用这些标识有效地识别要加载的 DTB/DTBO。如果引导加载程序需要获取更多信息，请将其放在 DTB/DTBO 中，引导加载程序可在这里解析 DTB/DTBO，从而读取这些信息（参见下面的示例代码）。</p> + +<h2 id="sample-code">示例代码</h2> +<p>以下示例代码可检查引导加载程序中的硬件标识。 +</p> + +<ul> +<li><code>check_dtbo()</code> 函数用于检查硬件标识。首先它会检查结构 <code>dt_table_entry</code> 中的数据（<code>id</code>、<code>rev</code> 等）。如果这种数据未能提供充足的信息，它会将 <code>dtb</code> 数据加载到内存中，并检查 <code>dtb</code> 中的值。</li> +<li><code>my_hw_information</code> 和 <code>soc_id</code> 属性的值会在根节点进行解析（请参见 <code>my_dtbo_1.dts</code> 中的示例）。 + +<pre class="prettyprint"> +[my_dtbo_1.dts] +/dts-v1/; +/plugin/; + +/ { + /* As DTS design, these properties only for loader, won't overlay */ + compatible = "board_manufacturer,board_model"; + + /* These properties are examples */ + board_id = <0x00010000>; + board_rev = <0x00010001>; + another_hw_information = "some_data"; + soc_id = <0x68000000>; + ... +}; + +&device@0 { + value = <0x1>; + status = "okay"; +}; + +[my_bootloader.c] +int check_dtbo(const dt_table_entry *entry, uint32_t header_addr) { + ... + if (entry->id != ... || entry->rev != ...) { + ... + } + ... + void * fdt_buf = my_load_dtb(header_addr + entry->dt_offset, entry->dt_size); + int root_node_off = fdt_path_offset(fdt_buf, "/"); + ... + const char *my_hw_information = + (const char *)fdt_getprop(fdt_buf, root_node_off, "my_hw_information", NULL); + if (my_hw_information != NULL && strcmp(my_hw_information, ...) != 0) { + ... + } + const fdt32_t *soc_id = fdt_getprop(fdt_buf, root_node_off, "soc_id", NULL); + if (soc_id != NULL && *soc_id != ...) { + ... + } + ... +} +</pre></li></ul> + +<h2 id="mkdtimg">mkdtimg</h2> +<p><code>mkdtimg</code> 是用于创建 <code>dtb</code>/<code>dtbo</code> 映像（AOSP 中 <code>system/libufdt</code> 下的<a href="https://android-review.googlesource.com/#/q/topic:mkdtimg+(status:open+OR+status:merged+OR+status:pending)" class="external">源代码</a>）的工具。<code>mkdtimg</code> 支持多个命令，包括 <code>create</code>、<code>cfg_create</code> 和 <code>dump</code>。</p> + +<h3 id="create">create</h3> +<p>使用 <code>create</code> 命令创建 <code>dtb</code>/<code>dtbo</code> 映像：</p> +<pre class="prettyprint"> +$mkdtimg create <image_filename> (<global-option>...) \ + <ftb1_filename> (<entry1_option>...) \ + <ftb2_filename> (<entry2_option>...) \ + ... +</pre> + +<p><code>ftbX_filename</code> 会在映像中生成一个 <code>dt_table_entry</code>。<code>entryX_option</code> 是分配给 <code>dt_table_entry</code> 的值。这些值可以是以下任一值：</p> +<pre class="prettyprint"> +--id=<number|path> +--rev=<number|path> +--custom0=<number|path> +--custom1=<number|path> +--custom2=<number|path> +--custom3=<number|path> +</pre> + +<p>数字值可以是 32 位数字（如 68000）或十六进制数字（如 0x6800）。或者，您也可以使用以下格式指定路径：</p> +<pre class="prettyprint"> +<full_node_path>:<property_name> +</pre> + +<p>例如，<code>/board/:id</code>。<code>mkdtimg</code> 从 DTB/DTBO 文件中的路径读取值，并将值（32 位）分配给 <code>dt_table_entry</code> 中的相对属性。或者，您也可以将 <code>global_option</code> 作为所有条目的默认选项。<code>dt_table_header</code> 中 <code>page_size</code> 的默认值为 2048；可使用 <code>global_option --page_size=<number></code> 分配不同的值。</p> + +<p>示例：</p> +<pre class="prettyprint"> +[board1.dts] +/dts-v1/; +/plugin/; + +/ { + compatible = "board_manufacturer,board_model"; + board_id = <0x00010000>; + board_rev = <0x00010001>; + another_hw_information = "some_data"; + ... +}; + +&device@0 { + value = <0x1>; + status = "okay"; +}; + +$mkdtimg create dtbo.img --id=/:board_id --custom0=0xabc \ + board1.dtbo \ + board2.dtbo --id=0x6800 \ + board3.dtbo --id=0x6801 --custom0=0x123 +</pre> + +<ul> +<li>第一个 <code>dt_table_entry</code> (<code>board1.dtbo</code>) <code>id</code> 为 <code>0x00010000</code>，<code>custom[0]</code> 为 <code>0x00000abc</code>。</li> +<li>第二个 <code>id</code> 为 <code>0x00006800</code>，<code>custom[0]</code> 为 <code>0x00000abc</code>。</li> +<li>第三个 <code>id</code> 为 <code>0x00006801</code>，<code>custom[0]</code> 为 <code>0x00000123</code>。</li> +<li>所有其他项均使用默认值 (<code>0</code>)。</li> +</ul> + +<h3 id="cfg-create">cfg_create</h3> +<p><code>cfg_create</code> 命令可创建具有采用以下格式的配置文件的映像：</p> +<pre class="prettyprint"> +# global options + <global_option> + ... +# entries +<ftb1_filename> # comment + <entry1_option> # comment + ... +<ftb2_filename> + <entry2_option> + ... +... +</pre> + +<p>选项 <code>global_option</code> 和 <code>entryX_option</code> 必须以一个或多个空格字符开头（这些选项与 <code>create</code> 选项相同，不带 <code>--</code> 前缀）。空行或者以 <code>#</code> 开头的行将被忽略。</p> + +<p>示例：</p> +<pre class="prettyprint"> +[dtboimg.cfg] +# global options + id=/:board_id + rev=/:board_rev + custom0=0xabc + +board1.dtbo + +board2.dtbo + id=0x6800 # override the value of id in global options + +board2.dtbo + id=0x6801 # override the value of id in global options + custom0=0x123 # override the value of custom0 in global options + +$mkdtimg cfg_create dtbo.img dtboimg.cfg +</pre> + +<p><code>mkdtimg</code> 不会处理 <code>.dtb</code>/<code>.dtbo</code> 文件的对齐方式，而是将它们附加到映像上。当您使用 <code>dtc</code> 将 <code>.dts</code> 编译为 <code>.dtb</code>/<code>.dtbo</code> 时，必须添加选项 <code>-a</code>。例如，添加选项 <code>-a 4</code> 会添加内边距，因此 <code>.dtb</code>/<code>.dtbo</code> 的大小将调整为 4 个字节。</p> + +<p>多个 DT 表格条目可以共享一个 <code>.dtb</code>/<code>.dtbo</code>。如果您为不同的条目使用同一个文件名，则系统只会在具有相同 <code>dt_offset</code> 和 <code>dt_size</code> 的映像中存储一份内容。使用具有相同 DT 的不同硬件时，这种方式非常有用。</p> + +<h3 id="dump">转储</h3> +<p>对于 <code>dtb</code>/<code>dtbo</code> 映像，请使用 <code>dump</code> 命令打印映像中的信息。示例：</p> +<pre class="prettyprint"> +$mkdtimg dump dtbo.img +dt_table_header: + magic = d7b7ab1e + total_size = 1300 + header_size = 32 + dt_entry_size = 32 + dt_entry_count = 3 + dt_entries_offset = 32 + page_size = 2048 + reserved[0] = 00000000 +dt_table_entry[0]: + dt_size = 380 + dt_offset = 128 + id = 00010000 + rev = 00010001 + custom[0] = 00000abc + custom[1] = 00000000 + custom[2] = 00000000 + custom[3] = 00000000 + (FDT)size = 380 + (FDT)compatible = board_manufacturer,board_model +... +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/dto/syntax.html b/zh-cn/devices/architecture/dto/syntax.html new file mode 100644 index 00000000..d1482a0b --- /dev/null +++ b/zh-cn/devices/architecture/dto/syntax.html @@ -0,0 +1,315 @@ +<html devsite><head> + <title>DTO 语法</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>设备树源 (DTS) 格式是设备树的文本表示形式。设备树编译器 (DTC) 可将这种格式处理为二进制设备树，这是 Linux 内核要求的形式。</p> + +<h2 id="reference">使用引用</h2> + +<p><a href="https://github.com/pantoniou/dtc" class="external">DTC</a>（设备树编译器 + 叠加补丁程序）项目在 <a href="https://android.googlesource.com/platform/external/dtc/+/refs/heads/master/Documentation/dts-format.txt" class="external">dtc-format.txt</a> +和 <a href="https://android.googlesource.com/platform/external/dtc/+/refs/heads/master/Documentation/manual.txt" class="external">manual.txt</a> 中说明了 DTS 格式。DTO 格式和规则在 <a href="https://android.googlesource.com/platform/external/dtc/+/refs/heads/master/Documentation/dt-object-internal.txt" class="external">dt-object-internal.txt</a> 中有相关说明。这些文档描述了如何使用叠加 DT 中的节点 <code>fragment@x</code> 和语法 <code>__overlay__</code> 来更新主 DT。例如：</p> +<pre class="prettyprint"> +/ { + fragment@0 { + target = <&some_node>; + __overlay__ { + some_prop = "okay"; + ... + }; + }; +}; +</pre> + +<p>不过，Google 强烈建议您<strong>不要</strong>使用 <code>fragment@x</code> 和语法 <code>__overlay__</code>，而是使用引用语法。例如：</p> +<pre class="prettyprint"> +&some_node { + some_prop = "okay"; + ... +}; +</pre> + +<p><code>dtc</code> 会将引用语法编译成与使用语法 <code>__overlay__</code> 所生成的上述对象相同的对象。此语法不强制您对片段进行编号，让您能够轻松地读取和写入叠加 DTS。如果您的 <code>dtc</code> 不支持此语法糖，请使用 <a href="https://android.googlesource.com/platform/external/dtc" class="external">AOSP 中的 dtc +</a>。</p> + +<h2 id="labels">使用标签</h2> +<p>为了允许在编译时不编译针对节点的未定义引用，叠加 DT <code>.dts</code> 文件必须在其头文件中具有标签 <code>/plugin/</code>。例如：</p> + +<pre class="prettyprint"> +/dts-v1/; +/plugin/; +</pre> + +<p>在这里，您可以使用引用来定位要叠加的节点，该引用是以和符号 (＆) 作为前缀的绝对节点路径。例如，对于主 DT 中的 <code>node@0</code>：</p> + +<table> +<tbody><tr> +<th width="50%">在主 DT 中定义标签...</th> +<th>...然后使用标签。</th> +</tr> + +<tr> +<td> +<pre class="prettyprint"> + +[my_main_dt.dts] + +/dts-v1/; + +/ { + my_node: node@0 { + status = "disabled"; + + my_child: child@0 { + value = <0xffffffff>; + }; + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> + +[my_overlay_dt.dts] + +/dts-v1/; +/plugin/; + +&my_node { + status = "okay"; +}; + +&my_child { + value = <0x1>; +}; +</pre> +</td> +</tr> +</tbody></table> + +<h2 id="override">叠加</h2> +<p>如果引用目标属性存在于主 DT 中，则在 DTO 之后被叠加；否则，系统会对其进行附加。例如：</p> + +<table> +<tbody><tr> +<th width="33%">main.dts</th> +<th width="33%">overlay.dts</th> +<th>合并结果</th> +</tr> + +<tr> +<td> +<pre class="prettyprint"> + +[my_main_dt.dts] + +/dts-v1/; + +/ { + compatible = "corp,foo"; + + my_node: node@0 { + status = "disabled"; + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> + +[my_overlay_dt.dts] + +/dts-v1/; +/plugin/; + +&my_node { + status = "okay"; +}; +</pre> +</td> + +<td> +<pre class="prettyprint"> + +/dts-v1/; + +/ { + compatible = "corp,foo"; + + ... + + node@0 { + linux,phandle = <0x1>; + phandle = <0x1>; + status = "okay"; + }; +}; +</pre> +</td> +</tr> +</tbody></table> + +<h2 id="append">附加</h2> +<p>如果引用目标属性不存在于主 DT 中，则在 DTO 之后被附加。例如：</p> + +<table> +<tbody><tr> +<th width="33%">main.dts</th> +<th width="33%">overlay.dts</th> +<th>合并结果</th> +</tr> + +<tr> +<td> +<pre class="prettyprint"> + +[my_main_dt.dts] + +/dts-v1/; + +/ { + compatible = "corp,foo"; + + my_node: node@0 { + status = "okay"; + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> + +[my_overlay_dt.dts] + +/dts-v1/; +/plugin/; + +&my_node { + new_prop = "bar"; +}; +</pre> +</td> + +<td> +<pre class="prettyprint"> + +/dts-v1/; + +/ { + compatible = "corp,foo"; + + ... + + node@0 { + linux,phandle = <0x1>; + phandle = <0x1>; + status = "okay"; + new_prop = "bar"; + }; +}; +</pre> +</td> +</tr> +</tbody></table> + +<h2 id="child">子节点</h2> +<p>子节点语法示例：</p> + +<table> +<tbody><tr> +<th width="33%">main.dts</th> +<th width="33%">overlay.dts</th> +<th>合并结果</th> +</tr> + +<tr> +<td> +<pre class="prettyprint"> + +[my_main_dt.dts] + +/dts-v1/; + +/ { + compatible = "corp,foo"; + + my_nodes: nodes { + compatible = "corp,bar"; + + node@0 { + status = "disabled"; + }; + }; +}; +</pre> +</td> + +<td class="alt"> +<pre class="prettyprint"> + +[my_overlay_dt.dts] + +/dts-v1/; +/plugin/; + +&my_nodes { + new_prop1 = "abc"; + + node@0 { + status = "okay"; + new_prop2 = "xyz"; + }; +}; +</pre> +</td> + +<td> +<pre class="prettyprint"> + +/dts-v1/; + +/ { + compatible = "corp,foo"; + + ... + + nodes { + linux,phandle = <0x1>; + phandle = <0x1>; + compatible = "corp,bar"; + new_prop1 = "abc"; + + node@0 { + linux,phandle = <0x2>; + phandle = <0x2>; + status = "okay"; + new_prop2 = "xyz"; + }; + }; +}; +</pre> +</td> +</tr> +</tbody></table> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/hal-types.html b/zh-cn/devices/architecture/hal-types.html index b6993b36..9df246f4 100644 --- a/zh-cn/devices/architecture/hal-types.html +++ b/zh-cn/devices/architecture/hal-types.html @@ -20,12 +20,12 @@ limitations under the License. --> -<p>为了更好地实现模块化，Android O 对 Android 操作系统底层进行了重新架构。作为此变化的一部分，运行 Android O 的设备必须支持绑定式或直通式 HAL：</p> +<p>为了更好地实现模块化，Android 8.0 对 Android 操作系统底层进行了重新架构。作为此变化的一部分，运行 Android 8.0 的设备必须支持绑定式或直通式 HAL：</p> <ul> -<li><strong>绑定式 HAL</strong>。以 HAL 接口定义语言 (HIDL) 表示的 HAL。这些 HAL 取代了早期 Android 版本中使用的传统 HAL 和旧版 HAL，可在绑定模式下使用。所有在推出时即搭载了 Android O 或后续版本的设备都必须只支持绑定式 HAL。</li> +<li><strong>绑定式 HAL</strong>。以 HAL 接口定义语言 (HIDL) 表示的 HAL。这些 HAL 取代了早期 Android 版本中使用的传统 HAL 和旧版 HAL。在绑定式 HAL 中，Android 框架和 HAL 之间通过 Binder 进程间通信 (IPC) 调用进行通信。所有在推出时即搭载了 Android 8.0 或后续版本的设备都必须只支持绑定式 HAL。</li> -<li><strong>直通式 HAL</strong>。以 HIDL 封装的传统 HAL 或旧版 HAL。这些 HAL 封装了现有的 HAL，可在绑定模式和 Same-Process（直通）模式下使用。升级到 Android O 的设备可以使用直通式 HAL。</li> +<li><strong>直通式 HAL</strong>。以 HIDL 封装的传统 HAL 或旧版 HAL。这些 HAL 封装了现有的 HAL，可在绑定模式和 Same-Process（直通）模式下使用。升级到 Android 8.0 的设备可以使用直通式 HAL。</li> </ul> <h2 id="requirements">HAL 模式要求</h2> @@ -40,13 +40,13 @@ </tr> <tr> -<td><em>搭载 Android O 的设备</em></td> +<td><em>搭载 Android 8.0 的设备</em></td> <td><a href="#passthrough">直通式 HAL</a> 中列出的 HAL 必须为直通式。</td> <td>所有其他 HAL 均为绑定式（包括作为供应商扩展程序的 HAL）。</td> </tr> <tr> -<td rowspan="2"><em>升级到 Android O 的设备</em></td> +<td rowspan="2"><em>升级到 Android 8.0 的设备</em></td> <td><a href="#passthrough">直通式 HAL</a> 中列出的 HAL 必须为直通式。</td> <td><a href="#binderized">绑定式 HAL</a> 中列出的 HAL 必须为绑定式。</td> </tr> @@ -62,13 +62,13 @@ <p>Android 要求所有 Android 设备（无论是搭载 Android O 的设备还是升级到 Android O 的设备）上的下列 HAL 均为绑定式：</p> <ul> -<li><code>android.hardware.biometrics.fingerprint@2.1</code>。取代 Android O 中已不存在的 <code>fingerprintd</code>。</li> -<li><code>android.hardware.configstore@1.0</code>。Android O 中的新 HAL。</li> +<li><code>android.hardware.biometrics.fingerprint@2.1</code>。取代 Android 8.0 中已不存在的 <code>fingerprintd</code>。</li> +<li><code>android.hardware.configstore@1.0</code>。Android 8.0 中的新 HAL。</li> <li><code>android.hardware.dumpstate@1.0</code>。此 HAL 提供的原始接口可能无法继续使用，并且已更改。因此，<code>dumpstate_board</code> 必须在指定的设备上重新实现（这是一个可选的 HAL）。</li> -<li><code>android.hardware.graphics.allocator@2.0</code>。在 Android O 中，此 HAL 必须为绑定式，因此无需在可信进程和不可信进程之间分享文件描述符。</li> +<li><code>android.hardware.graphics.allocator@2.0</code>。在 Android 8.0 中，此 HAL 必须为绑定式，因此无需在可信进程和不可信进程之间分享文件描述符。</li> <li><code>android.hardware.radio@1.0</code>。取代由存活于自身进程中的 <code>rild</code> 提供的接口。</li> -<li><code>android.hardware.usb@1.0</code>。Android O 中的新 HAL。</li> -<li><code>android.hardware.wifi@1.0</code>。Android O 中的新 HAL，可取代此前加载到 <code>system_server</code> 的旧版 WLAN HAL 库。</li> +<li><code>android.hardware.usb@1.0</code>。Android 8.0 中的新 HAL。</li> +<li><code>android.hardware.wifi@1.0</code>。Android 8.0 中的新 HAL，可取代此前加载到 <code>system_server</code> 的旧版 WLAN HAL 库。</li> <li><code>android.hardware.wifi.supplicant@1.0</code>。在现有 <code>wpa_supplicant</code> 进程之上的 HIDL 接口</li> </ul> @@ -98,8 +98,8 @@ <h2 id="legacy">传统 HAL 和旧版 HAL</h2> -<p>传统 HAL（在 Android O 中已弃用）是指与具有特定名称及版本号的应用二进制接口 (ABI) 标准相符的接口。大部分 Android 系统接口（<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/camera3.h">相机</a>、<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/audio.h">音频</a>和<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/sensors.h">传感器</a>等）都采用传统 HAL 形式（已在 <a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware">hardware/libhardware/include/hardware</a> 下进行定义）。</p> +<p>传统 HAL（在 Android 8.0 中已弃用）是指与具有特定名称及版本号的应用二进制接口 (ABI) 标准相符的接口。大部分 Android 系统接口（<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/camera3.h">相机</a>、<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/audio.h">音频</a>和<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/sensors.h">传感器</a>等）都采用传统 HAL 形式（已在 <a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware">hardware/libhardware/include/hardware</a> 下进行定义）。</p> -<p>旧版 HAL（也已在 Android O 中弃用）是指早于传统 HAL 的接口。一些重要的子系统（WLAN、无线接口层和蓝牙）采用的就是旧版 HAL。虽然没有统一或标准化的方式来指明是否为旧版 HAL，但如果 HAL 早于 Android O 而出现，那么这种 HAL 如果不是传统 HAL，就是旧版 HAL。有些旧版 HAL 的一部分包含在 <a href="https://android.googlesource.com/platform/hardware/libhardware_legacy/+/master">libhardware_legacy</a> 中，而其他部分则分散在整个代码库中。</p> +<p>旧版 HAL（也已在 Android 8.0 中弃用）是指早于传统 HAL 的接口。一些重要的子系统（WLAN、无线接口层和蓝牙）采用的就是旧版 HAL。虽然没有统一或标准化的方式来指明是否为旧版 HAL，但如果 HAL 早于 Android 8.0 而出现，那么这种 HAL 如果不是传统 HAL，就是旧版 HAL。有些旧版 HAL 的一部分包含在 <a href="https://android.googlesource.com/platform/hardware/libhardware_legacy/+/master">libhardware_legacy</a> 中，而其他部分则分散在整个代码库中。</p> </body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/hidl-java/interfaces.html b/zh-cn/devices/architecture/hidl-java/interfaces.html index 257e5869..bd2acb5d 100644 --- a/zh-cn/devices/architecture/hidl-java/interfaces.html +++ b/zh-cn/devices/architecture/hidl-java/interfaces.html @@ -22,7 +22,7 @@ <p>本部分详细介绍了接口方法和错误。</p> -<h2 id="void">无效方法</h2> +<h2 id="void">Void 方法</h2> <p>不返回结果的方法将转换为返回 <code>void</code> 的 Java 方法。例如，HIDL 声明：</p> <pre class="prettyprint"> @@ -36,7 +36,7 @@ void doThisWith(float param); </pre> <h2 id="single-result">单结果方法</h2> -<p>返回单个结果的方法将转换为同样返回单个结果的 Java 等效项。例如，以下方法：</p> +<p>返回单个结果的方法将转换为同样返回单个结果的 Java 等效方法。例如，以下方法：</p> <pre class="prettyprint"> doQuiteABit(int32_t a, int64_t b, @@ -102,13 +102,13 @@ class MyCallback implements oneProducesTwoThingsCallback { <p>由于服务实现可以在不同的进程中运行，在某些情况下，即使实现接口的进程已死亡，客户端也可以保持活动状态。 调用死亡进程中托管的接口对象会失败并返回传输错误（调用的方法抛出的运行时异常）。可以通过调用 <code>I<InterfaceName>.getService()</code> 以请求服务的新实例，从此类故障中恢复。不过，仅当崩溃的进程已重新启动且已向 servicemanager 重新注册其服务时，这种方法才有效（对 HAL 实现而言通常如此）。</p> -<p>接口的客户端也可以注册一个死亡通知接收方，以便在服务终止时收到通知。<em></em>如果服务一终止就发出调用，则仍然可能发生传输错误。要在检索的 <code>IFoo</code> 接口上注册此类通知，客户端可以执行以下操作：</p> +<p>接口的客户端也可以注册一个死亡通知接收方，以便在服务终止时收到通知。<em></em>但如果在服务刚终止时发出调用，则仍然可能发生传输错误。要在检索的 <code>IFoo</code> 接口上注册此类通知，客户端可以执行以下操作：</p> <pre class="prettyprint"> foo.linkToDeath(recipient, 1481 /* cookie */); </pre> -<p><code>recipient</code> 参数必须是 HIDL 提供的 <code>HwBinder.DeathRecipient</code> 接口的实现。该接口包含在托管接口的进程死亡时调用的单个方法 <code>serviceDied()</code>。</p> +<p><code>recipient</code> 参数必须是由 HIDL 提供的 <code>HwBinder.DeathRecipient</code> 接口的实现。该接口包含在托管接口的进程终止时调用的单个方法 <code>serviceDied()</code>。</p> <pre class="prettyprint"> final class DeathRecipient implements HwBinder.DeathRecipient { diff --git a/zh-cn/devices/architecture/vintf/comp-matrices.html b/zh-cn/devices/architecture/vintf/comp-matrices.html new file mode 100644 index 00000000..531cd05c --- /dev/null +++ b/zh-cn/devices/architecture/vintf/comp-matrices.html @@ -0,0 +1,222 @@ +<html devsite><head> + <title>兼容性矩阵</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>本部分介绍框架和设备兼容性矩阵以及<a href="#compatiblity-matrix-schema">兼容性矩阵结构</a>。有关匹配规则，请参见<a href="/devices/architecture/vintf/match-rules.html">匹配规则</a>一文。</p> + +<h2 id="framework-compatibility-matrix">框架兼容性矩阵</h2> +<p>框架兼容性矩阵说明了框架对运行它的设备的需求。矩阵文件与 Android 框架映像（位于 <code>system.img</code> 中）相关联。框架的兼容性矩阵的需求应通过设备清单来满足（在启动和 OTA 时需求是被强制执行的）。</p> + +<p>框架兼容性矩阵文件示例：</p> + +<pre class="prettyprint"> +<?xml version="1.0" encoding="UTF-8"?> +<!-- Comments, Legal notices, etc. here --> +<compatibility-matrix version="1.0" type="framework"> + <hal> + <name>android.hardware.camera</name> + <version>1.0</version> + <version>3.1-4</version> + <interface> + <name>ICameraProvider</name> + <instance>default</instance> + </interface> + </hal> + <hal> + <name>android.hardware.nfc</name> + <version>1.0</version> + <interface> + <name>INfc</name> + <instance>default</instance> + </interface> + </hal> + <hal optional="true"> + <name>android.hardware.graphics.composer</name> + <version>2.1</version> + </hal> + <hal format="native"> + <name>GL</name> + <version>1.1</version> + <version>3.0</version> + </hal> + <hal format="native"> + <name>EGL</name> + <version>1.1</version> + </hal> + <kernel version="3.18.51"> + <config> + <key>CONFIG_A</key> + <value type="string"></value> + </config> + <config> + <key>CONFIG_B</key> + <value type="tristate">y</value> + </config> + </kernel> + <kernel version="4.1.22"> + <config> + <key>CONFIG_A</key> + <value type="string">foo</value> + </config> + <config> + <key>CONFIG_B2</key> + <value type="int">1024</value> + </config> + </kernel> + <sepolicy> + <kernel-sepolicy-version>30</kernel-sepolicy-version> + <sepolicy-version>25.0</sepolicy-version> + <sepolicy-version>26.0-3</sepolicy-version> + </sepolicy> + <avb> + <vbmeta-version>2.1</vbmeta-version> + </avb> + <xmlfile format="dtd"> + <name>media_profile</name> + <version>1.0</version> + <path>/system/etc/media_profile_V1_0.dtd</path> + </xmlfile> +</compatiblity-matrix> +</pre> + +<h2 id="device-compatibility-matrix">设备兼容性矩阵</h2> +<p>设备兼容性矩阵说明了设备期望框架满足的一组需求（在启动和 OTA 时需求是被强制执行的）。 +</p> +<p>设备兼容性矩阵文件示例：</p> + +<pre class="prettyprint"> +<?xml version="1.0" encoding="UTF-8"?> +<!-- Comments, Legal notices, etc. here --> +<compatibility-matrix version="1.0" type="device"> + <hal> + <name>android.hidl.manager</name> + <version>1.0</version> + <interface> + <name>IServiceManager</name> + <instance>default</instance> + </interface> + </hal> + <hal> + <name>android.hidl.memory</name> + <version>1.0</version> + <interface> + <name>IMemory</name> + <instance>ashmem</instance> + </interface> + </hal> + <hal> + <name>android.hidl.allocator</name> + <version>1.0</version> + <interface> + <name>IAllocator</name> + <instance>ashmem</instance> + </interface> + </hal> + <hal> + <name>android.framework.sensor</name> + <version>1.0</version> + <interface> + <name>ISensorManager</name> + <instance>default</instance> + </interface> + </hal> + <xmlfile format="dtd" optional="false"> + <name>sample_xml</name> + <version>1.0</version> + </xmlfile> +</compatibility-matrix> +</pre> + +<h2 id="compatiblity-matrix-schema">兼容性矩阵结构</h2> +<dl> +<dt><code>?xml</code></dt> +<dd>可选。它只向 XML 解析器提供信息。</dd> +<dt><code>compatibility-matrix.version</code></dt> +<dd>必需。该兼容性矩阵的版本。描述清单中预期的元素。与 XML 版本无关。</dd> +<dt><code>compatibility-matrix.type</code></dt> +<dd>必需。该兼容性矩阵的类型： + <ul> + <li><code>"device"</code>：设备兼容性矩阵。</li> + <li><code>"framework"</code>：框架兼容性矩阵。</li> + </ul> +</dd> +<dt><code>compatibility-matrix.hal</code></dt> +<dd>可选且可重复。列出兼容性矩阵（框架或设备）的所有者要求存在的单个 HAL（HIDL 或本机）。HAL 条目通过 <code><name></code> 元素来区分，可以有多个同名的 HAL 条目（暗示“和”条件）。 +</dd> +<dt><code>compatibility-matrix.hal.format</code></dt> +<dd>可选。值可以是以下几项之一： + <ul> + <li><code>"hidl"</code>：HIDL HAL。这是默认值。</li> + <li><code>"native"</code>：本机 HAL。</li> + </ul> +</dd> +<dt><code>compatibility-matrix.hal.optional</code></dt> +<dd>属性是可选的，默认值为 false。指明该 HAL 对兼容性矩阵（框架或设备）的所有者来说是否为可选。如果将 <code>&ltp;hal></code> 条目标记为可选，则表示在存在的情况下所有者可以使用该 HAL，但并非是必须存在。</dd> +<dt><code>compatibility-matrix.hal.name</code></dt> +<dd>必需。该 HAL 的完整软件包名称。示例： + <ul> + <li><code>android.hardware.camera</code> (HIDL HAL)</li> + <li><code>GLES</code>（本机 HAL，只需提供名称）</li> + </ul> +</dd> +<dt><code>compatibility-matrix.hal.version</code></dt> +<dd>必需，可以在不重名的情况下进行重复使用。版本范围的列表（请参见 <a href="/devices/architecture/vintf/match-rules.html#hals">HAL 匹配</a>一节），用于定义兼容性矩阵（框架或设备）的所有者期望的版本。</dd> +<dt><code>compatibility-matrix.hal.interface</code></dt> +<dd>可选且可重复。该 HAL 的必需接口的列表。</dd> +<dt><code>compatibility-matrix.hal.interface.name</code></dt> +<dd>必需。接口的名称。</dd> +<dt><code>compatibility-matrix.hal.interface</code></dt> +<dd>可选且可重复。该接口的必需实例的列表。</dd> +<dt><code>compatibility-matrix.kernel.version</code></dt> +<dd>必需。内核版本。格式为 <code>{version}.{major-revision}.{minor-revision}</code>。版本和主要修订版本必须完全匹配，次要修订版本定义框架期望的内核的最低 LTS 版本。</dd> +<dt><code>compatibility-matrix.kernel.config</code></dt> +<dd>可选且可重复。列出该内核版本必须匹配的 <code>CONFIG</code> 项。每个 <code>CONFIG</code> 项是一个键值对，配置项通过键来区分。</dd> +<dt><code>compatibility-matrix.kernel.config.key</code></dt> +<dd>必需。<code>CONFIG</code> 项的键名称。以 <code>CONFIG_</code> 开头。</dd> +<dt><code>compatibility-matrix.kernel.config.value</code></dt> +<dd>必需。<code>CONFIG</code> 项的值。格式视类型而定： + <ul> + <li><code>string</code>：省略了引号。</li> + <li><code>int</code>：接受十进制和十六进制值（必须以 <code>0x</code> 或 <code>0X)</code> 开头）。解释为 64 位整数，溢出部分会被截断。（解析器接受从 -2<sup>64</sup> + 1 到 2<sup>64</sup> - 1 的值，会在第 65 位截断；有关详情，请参阅 <a href="http://man7.org/linux/man-pages/man3/strtoul.3.html" class="external">strtoull 手册页</a>。）</li> + <li><code>range</code>：格式为 <code>[int]-[int]</code>，例如 <code>10-20</code>。接受十六进制值且值必须以 <code>0x</code> 或 <code>0X</code> 开头。两个边界必须是无符号的 64 位整数。</li> + <li><code>tristate</code>：有效值为 <code>y</code>、<code>m</code> 和 <code>n</code>。</li> + </ul> +</dd> +<dt><code>compatibility-matrix.kernel.config.value.type</code></dt> +<dd>必需。<code>CONFIG</code> 项的值的类型，应该是以下几项之一： + <ul> + <li><code>string</code></li> + <li><code>int</code></li> + <li><code>range</code></li> + <li><code>tristate</code></li> + </ul> +</dd> +<dt><code>compatibility-matrix.sepolicy</code></dt> +<dd>必需。包含所有与 sepolicy 相关的条目。仅供框架兼容性矩阵使用。</dd> +<dt><code>compatibility-matrix.sepolicy.sepolicy-version</code></dt> +<dd>必需且可重复。描述对 sepolicy 版本的需求。与 <code>manifest.sepolicy.version</code> 相对应。元素的每个实例定义一系列 sepolicy 版本。</dd> +<dt><code>compatibility-matrix.sepolicy.kernel-sepolicy-version</code></dt> +<dd>必需。声明框架支持的 <code>policydb</code> 版本。</dd> +<dt><code>compatibility-matrix.avb.vbmeta-version</code></dt> +<dd>可选，仅供框架兼容性矩阵使用。声明用于对 <code>system.img</code> 签名的 <a href="/devices/architecture/vintf/match-rules.html#avb-version">AVB 版本</a>。</dd> +</dl> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/vintf/index.html b/zh-cn/devices/architecture/vintf/index.html new file mode 100644 index 00000000..a1f0b726 --- /dev/null +++ b/zh-cn/devices/architecture/vintf/index.html @@ -0,0 +1,71 @@ +<html devsite><head> + <title>供应商接口对象</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>本文档介绍供应商接口对象（VINTF 对象）的设计，该对象用于聚合设备的相关信息并通过可查询的 API 提供该信息。<em></em><em></em></p> + +<h2 id="about-objects">VINTF 对象设计</h2> +<p>VINTF 对象直接从设备中收集所需的一些信息。其他信息（如清单）以 XML 格式静态描述。</p> + +<img src="../images/treble_vintf_mm.png"/> +<figcaption><strong>图 1.</strong> 清单、兼容性矩阵和运行时可收集的信息。</figcaption> + +<p>VINTF 对象设计为设备和框架组件提供以下内容：</p> + +<table> +<tbody><tr> +<th style="width:50%">对于设备</th> +<th>对于框架</th> +</tr> +<tr> +<td> +<ul> +<li>定义静态组件（<a href="/devices/architecture/vintf/objects.html#device-manifest-file">设备清单文件</a>）的结构。</li> +<li>添加构建时支持，以便定义给定设备的设备清单文件。</li> +<li>在运行时定义相应<a href="/devices/architecture/vintf/objects.html#queryable-api">可查询的 API</a>，以用于检索设备清单文件（以及其他可在运行时收集的信息）并将其打包到查询结果中。</li> +</ul> +</td> +<td> +<ul> +<li>定义静态组件（<a href="/devices/architecture/vintf/objects.html#framework-manifest-file">框架清单文件</a>）的结构。</li> +<li>在运行时定义相应<a href="/devices/architecture/vintf/objects.html#queryable-api">可查询的 API</a>，以用于检索框架清单文件并将其打包到查询结果中。</li> +</ul> +</td> +</tr> +</tbody></table> + +<p>无论何时请求，VINTF 对象都必须稳定可靠且能提供相同的完整信息（请见<a href="/devices/architecture/vintf/resources.html#caveats">注意事项</a>）。</p> + +<h2 id="manifests-matrices">清单和矩阵</h2> +<p>Android O 在运行时需要使用 API 来查询设备上的内容，并将该信息发送到<a href="/devices/tech/ota/index.html">无线下载 (OTA)</a> 更新服务器以及其他相关方（如 CTS <code>DeviceInfo</code>）。某些信息在运行时进行检索，其中有一些是静态定义的信息。</p> + +<ul> +<li><strong>设备清单</strong>描述了设备可以为框架提供的静态组件。</li> +<li><strong>框架兼容性矩阵</strong>描述了 Android 框架从给定设备中期待获取的内容。矩阵是一个静态实体，其组成是在开发下一个版本的 Android 框架期间手动确定。</li> +<li><strong>框架清单</strong>描述了框架可以为设备提供的高级服务。</li> +<li><strong>设备兼容性矩阵</strong>描述了供应商映像需要框架提供的服务，其组成是在设备开发期间手动确定。</li> +</ul> + +<p>这两对清单和矩阵必须在 OTA 时进行调整，以确保设备可以获取与设备功能兼容的框架更新。一般来说，清单描述了提供的内容，兼容性矩阵描述了需要的内容。<em></em><em></em></p> + +<p><a href="/devices/architecture/vintf/objects.html">VINTF 对象数据</a>定义了清单的结构，<a href="/devices/architecture/vintf/comp-matrices.html">兼容性矩阵</a>定义了兼容性矩阵的结构，<a href="/devices/architecture/vintf/match-rules.html">匹配规则</a>定义了兼容性矩阵与清单之间成功匹配的规则。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/vintf/match-rules.html b/zh-cn/devices/architecture/vintf/match-rules.html new file mode 100644 index 00000000..28c55ae3 --- /dev/null +++ b/zh-cn/devices/architecture/vintf/match-rules.html @@ -0,0 +1,285 @@ +<html devsite><head> + <title>匹配规则</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>两对兼容性矩阵和清单目的是在 <a href="/devices/tech/ota/index.html">OTA</a> 时进行协调，以验证框架和供应商实现是否可以相互协同工作。当框架兼容性矩阵与设备清单之间以及框架清单与设备兼容性矩阵之间匹配时，便成功通过此验证。下面几部分将详细介绍各种组件使用的匹配规则。</p> + +<h2 id="hals">HAL 匹配</h2> +<p>HAL 匹配规则可以识别清单文件中认为受相应兼容性矩阵的所有者支持的 <code>hal</code> 元素的版本。</p> +<ul> +<li>多个 <code>version</code> 元素使用 <strong>OR</strong> 进行连接（请参见下面的相机示例）。</li> +<li>多个同名的 <code><hal></code> 元素使用 <strong>AND</strong> 进行连接。</li> +</ul> + +<h4><strong>示例</strong>：相机模块的成功 HAL 匹配</h4> +<p>对于 2.5 版的 HAL，匹配规则如下：</p> + +<table> + <tbody><tr> + <th>矩阵</th> + <th>匹配清单</th> + </tr> + <tr> + <td><code>2.5</code></td> + <td>2.5-2.∞. 2.5-5 的简写形式。</td> + </tr> + <tr> + <td><code>2.5-7</code></td> + <td>2.5-2.∞. 表示以下含义： + <br /> + <ul> + <li>2.5 是要求的最低版本，这意味着提供 HAL 2.0-2.4 的清单不兼容。</li> + <li>2.7 是可以请求的最高版本，这意味着兼容性矩阵（框架或设备）的所有者将不会请求超过 2.7 的版本。请求版本 2.7 时，匹配清单的所有者仍然可以提供版本 2.10（以此为例）。兼容性矩阵所有者只知道请求的服务与 API 版本 2.7 兼容。</li> + <li>-7 仅供参考，不影响 OTA 更新流程。</li> + </ul> + 因此，如果某个设备的清单文件中的 HAL 版本为 2.10，而某个框架的兼容性矩阵中指明 <code>camera:</code><code>2.5-7</code>，则该设备与该框架保持兼容。</td> + </tr> +</tbody></table> + +<h4><strong>示例</strong>：DRM 模块的成功 HAL 匹配</h4> +<p>框架兼容性矩阵指明了 DRM HAL 的以下版本信息：</p> + +<pre class="prettyprint"><hal> + <name>android.hardware.drm + <version>1.0</version> + <version>3.1-2</version> + <interface> + <name>IDrmFactory</name> + <instance>default</instance> + <instance>specific</instance> + </interface> +</hal> +<hal> + <name>android.hardware.drm + <version>2.0</version> + <interface> + <name>ICryptoFactory</name> + <instance>default</instance> + </interface> +</hal> +</pre> + +<p>供应商必须实现以下 HAL 之一：</p> + +<pre> +android.hardware.drm@1.x::IDrmFactory/default //where x >= 0 +android.hardware.drm@1.x::IDrmFactory/specific //where x >= 0 +</pre> + +或 + +<pre> +android.hardware.drm@3.y::IDrmFactory/default //where y >= 1 +android.hardware.drm@3.y::IDrmFactory/specific //where y >= 1 +</pre> + +<p>…并且还必须实现以下 HAL：</p> + +<pre> +android.hardware.drm@2.z::ICryptoFactory/default //where z >= 0 +</pre> + +<h2 id="kernel">内核匹配</h2> +<p>框架兼容性矩阵的 <code><kernel></code> 部分说明了框架对设备上 Linux 内核的需求。该信息用于在 OTA 时与设备的 VINTF 对象报告的内核相关<a href="/devices/architecture/vintf/objects.html#runtime-collectible-information">信息</a>进行匹配。</p> + +<p>矩阵可以包括多个 <code><kernel></code> 部分，每个部分使用不同的 <code>version</code> 属性，格式如下：</p> + +<pre class="prettyprint">${ver}.${major_rev}.${kernel_minor_rev}</pre> + +<p>OTA 只会将具有相同 <code>${ver}</code> 和 <code>${major_rev}</code> 的 <code><kernel></code> 部分视为设备内核（即 <code>version="${ver}.${major_rev}.${matrix_minor_rev}")</code>），而忽略其他部分。此外，内核的次要修订版本必须是兼容性矩阵 (<code>${kernel_minor_rev} >= +${matrix_minor_rev}</code>) 中的值。如果没有 <code><kernel></code> 部分满足这些需求，则不匹配。</p> + +<p>如果 <code><kernel></code> 部分匹配，则该过程接下来会尝试将 <code>config</code> 元素与 <code>/proc/config.gz</code> 进行匹配。对于兼容性矩阵中的每个配置元素，系统将查找 <code>/proc/config.gz</code> 以查看该配置是否存在。如果某个配置项在匹配的 <code><kernel></code> 部分的兼容性矩阵中设置为 <code>n</code>，便不得在 <code>/proc/config.gz</code> 中出现。最后，不在兼容性矩阵中的配置项不一定会包含在 <code>/proc/config.gz</code> 中。 +</p> + +<p>匹配示例：</p> +<ul> +<li><code><value type="string">bar</value></code> 与 <code>"bar"</code> 匹配。引号在兼容性矩阵中会被省略，但会包含在 <code>/proc/config.gz</code> 中。</li> +<li><code><value type="int">4096</value></code> 与 <code>4096</code>、<code>0x1000</code> 或 <code>0X1000</code> 匹配。</li> +<li><code><value type="int">0x1000</value></code> 与 <code>4096</code>、<code>0x1000</code> 或 <code>0X1000</code> 匹配。</li> +<li><code><value type="int">0X1000</value></code> 与 <code>4096</code>、<code>0x1000</code> 或 <code>0X1000</code> 匹配。</li> +<li><code><value type="tristate">y</value></code> 与 <code>y</code> 匹配。</li> +<li><code><value type="tristate">m</value></code> 与 <code>m</code> 匹配。</li> +<li><code><value type="tristate">n</value></code> 表示配置项不得存在于 <code>/proc/config.gz</code> 中。</li> +<li><code><value type="range">1-0x3</value></code> 与 <code>1</code>、<code>2</code>、<code>3</code> 或十六进制对等数字匹配。 +</li> +</ul> + +<h4><strong>示例</strong>：成功的内核匹配</h4> +<p>框架兼容性矩阵包含以下内核信息：</p> + +<pre class="prettyprint"> +<kernel version="3.18.51"> + <config> + <key>CONFIG_TRI</key> + <value type="tristate">y</value> + </config> + <config> + <key>CONFIG_NOEXIST</key> + <value type="tristate">n</value> + </config> + <config> + <key>CONFIG_DEC</key> + <value type="int">4096</value> + </config> + <config> + <key>CONFIG_HEX</key> + <value type="int">0XDEAD</value> + </config> + <config> + <key>CONFIG_STR</key> + <value type="string">str</value> + </config> + <config> + <key>CONFIG_EMPTY</key> + <value type="string"></value> + </config> +</kernel> +</pre> + +<p>首先匹配内核版本。如果 <code>uname()</code> 中的设备报告：</p> +<ul> +<li>3.10.73（除非有一个单独的内核部分在 <code>x <= 73</code> 的情况下包含 <code><kernel version="3.10.x"></code>，否则与矩阵不匹配）</li> +<li>3.18.50（与矩阵不匹配，小于 <code>version</code>）</li> +<li>3.18.51（与矩阵匹配）</li> +<li>3.18.52（与矩阵匹配）</li> +<li>4.1.22（除非有一个含有 <code><kernel version="4.1.x"></code> 的单独内核部分且其中的 <code>x <= 22</code>，否则与矩阵不匹配） +</li> +</ul> + +<p>选择适当的 <code><kernel></code> 部分后，对于值不为 <code>n</code> 的每个 <code><config></code> 项，我们预计对应条目会存在于 <code>/proc/config.gz</code> 中；对于值为 <code>n</code> 的每个 <code><config></code> 项，我们预计对应条目不会存在于 <code>/proc/config.gz</code> 中。我们预计 <code><value></code> 的内容与等号后面的文本（包括引号）完全匹配，直到换行符或 <code>#</code>，前导和行尾空格被截断。</p> + +<p>以下内核配置是成功匹配的示例：</p> + +<pre class="prettyprint"> +# comments don't matter +CONFIG_TRI=y +# CONFIG_NOEXIST should not exist +CONFIG_DEC = 4096 # trailing comments and whitespaces are fine +CONFIG_HEX=57005 # 0XDEAD == 57005 +CONFIG_STR="str" +CONFIG_EMPTY="" # empty string must have quotes +CONFIG_EXTRA="extra config items are fine too" +</pre> + +<p>以下内核配置是不成功匹配的示例：</p> + +<pre class="prettyprint"> +CONFIG_TRI="y" # mismatch: quotes +CONFIG_NOEXIST=y # mismatch: CONFIG_NOEXIST exists +CONFIG_HEX=0x0 # mismatch; value doesn't match +CONFIG_DEC="" # mismatch; type mismatch (expect int) +CONFIG_EMPTY=1 # mismatch; expects "" +# mismatch: CONFIG_STR is missing +</pre> + +<h2 id="se-policy">SE 策略匹配</h2> +<p>SE 策略需要以下匹配：</p> +<ul> +<li><code><sepolicy-version></code> 定义每个主要版本的次要版本的封闭范围。设备报告的 sepolicy 版本必须属于这些范围之一才能与框架兼容。匹配规则类似于 HAL 版本；如果 sepolicy 版本高于或等于范围内的最低版本，则匹配。最高版本仅供参考。</li> +<li><code><kernel-sepolicy-version></code>（即 policydb 版本）必须与设备报告的 <code>security_policyvers()</code> 完全匹配。 +</li> +</ul> + +<h4><strong>示例</strong>：成功的 SE 策略匹配</h4> +<p>框架兼容性矩阵指明了以下 sepolicy 信息： +</p> + +<pre class="prettyprint"> + <sepolicy> + <kernel-sepolicy-version>30</kernel-sepolicy-version> + <sepolicy-version>25.0</sepolicy-version> + <sepolicy-version>26.0-3</sepolicy-version> + </sepolicy> +</pre> + +<p>在设备上：</p> +<ul> +<li><code>security_policyvers()</code> 返回的值必须恰好等于 30。否则，不匹配。</li> +<li>SE 策略版本必须为 25.0-∞ 和 26.0-∞ 其中之一。否则，不匹配。（“<code>26.0</code>”后面的“<code>-3</code>”仅供参考。）</li> +</ul> + +<h2 id="avb-version">AVB 版本匹配</h2> +<p>AVB 版本包含 MAJOR 版本和 MINOR 版本，格式为 MAJOR.MINOR（例如 1.0 和 2.1）。有关详细信息，请参阅<a href="https://android.googlesource.com/platform/external/avb/#Versioning-and-compatibility" class="external">版本管理和兼容性</a>。AVB 版本具有以下系统属性：</p> +<ul> +<li><code>ro.boot.vbmeta.avb_version</code> 是引导加载程序中的 <code>libavb</code> 版本</li> +<li><code>ro.boot.avb_version</code> 是 Android 操作系统中的 <code>libavb</code> 版本 (<code>init/fs_mgr</code>)</li> +</ul> + +<p>仅当已使用对应的 libavb 验证 AVB 元数据（并且返回 OK）时，才会显示该系统属性。如果验证失败（或根本没有执行验证），则不会显示该系统属性。</p> + +<p>兼容性匹配将比较以下内容：</p> +<ul> +<li>sysprop <code>ro.boot.vbmeta.avb_version</code> 与框架兼容性矩阵中的 <code>avb.vbmeta-version</code>； + <ul> + <li><code>ro.boot.vbmeta.avb_version.MAJOR == avb.vbmeta-version.MAJOR</code></li> + <li><code>ro.boot.vbmeta.avb_version.MINOR >= avb.vbmeta-version.MINOR</code></li> + </ul> +</li> +<li>sysprop <code>ro.boot.avb_version</code> 与框架兼容性矩阵中的 <code>avb.vbmeta-version</code>。 + <ul> + <li><code>ro.boot.avb_version.MAJOR == avb.vbmeta-version.MAJOR</code></li> + <li><code>ro.boot.avb_version.MINOR >= avb.vbmeta-version.MINOR</code></li> + </ul> +</li> +</ul> + +<p>引导加载程序或 Android 操作系统可能包含 <code>libavb</code> 库的两个副本，每个副本具有不同的 MAJOR 版本，用于升级设备和启动设备。在这种情况下，可以共享同一个未签名的系统映像，但最终签名的系统映像是不同的（具有不同的 <code>avb.vbmeta-version</code>）：<em></em><em></em></p> + +<img src="../images/treble_vintf_avb_o_p.png"/> +<figcaption><strong>图 1. </strong>AVB 版本匹配（<code>/system</code> 为 P，其他所有分区均为 O）。</figcaption> +<br /> +<br /> +<img src="../images/treble_vintf_avb_p.png"/> +<figcaption><strong>图 2.</strong> AVB 版本匹配（所有分区均为 P）。</figcaption> + +<h4><strong>示例</strong>：成功的 AVB 版本匹配</h4> +<p>框架兼容性矩阵指明了以下 AVB 信息：</p> + +<pre class="prettyprint"> +<avb> + <vbmeta-version>2.1</vbmeta-version> +</avb> +</pre> + +<p>在设备上：</p> + +<pre class="prettyprint"> +ro.boot.avb_version == 1.0 && +ro.boot.vbmeta.avb_version == 2.1 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: red; color: white"> mismatch </font> +</pre> + +<pre class="prettyprint"> +ro.boot.avb_version == 2.1 && +ro.boot.vbmeta.avb_version == 3.0 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: red; color: white"> mismatch </font> +</pre> + +<pre class="prettyprint"> +ro.boot.avb_version == 2.1 && +ro.boot.vbmeta.avb_version == 2.3 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: green; color: white"> match </font> +</pre> + +<pre class="prettyprint"> +ro.boot.avb_version == 2.3 && +ro.boot.vbmeta.avb_version == 2.1 <font style="font-family: Roboto, Arial, Helvetica, sans-serif; background-color: green; color: white"> match </font> +</pre> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/vintf/objects.html b/zh-cn/devices/architecture/vintf/objects.html new file mode 100644 index 00000000..9db92b45 --- /dev/null +++ b/zh-cn/devices/architecture/vintf/objects.html @@ -0,0 +1,211 @@ +<html devsite><head> + <title>VINTF 对象数据</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>VINTF 对象在<a href="#runtime-data">运行时</a>聚合来自<a href="#device-manifest-file">设备清单</a>和<a href="#framework-manifest-file">框架清单</a>文件 (XML) 以及设备本身的数据。这两个清单共用一种格式，不过并非所有元素都适用于两者（有关结构的详细信息，请参见<a href="#manifest-file-schema">清单文件结构</a>）。</p> + +<h2 id="device-manifest-file">设备清单文件</h2> +<p>设备清单文件由设备提供。它在 Android 源代码树中位于 <code>device/${VENDOR}/${DEVICE}/manifest.xml</code>，在设备上位于 <code><a href="https://android.googlesource.com/platform/system/libhidl/+/master/manifest.xml" class="external">/vendor/manifest.xml</a></code>。 +</p> + +<p>设备清单示例：</p> + +<pre class="prettyprint"> +<?xml version="1.0" encoding="UTF-8"?> +<!-- Comments, Legal notices, etc. here --> +<manifest version="1.0" type="device"> + <hal> + <name>android.hardware.camera</name> + <transport>hwbinder</transport> + <version>3.4</version> + <interface> + <name>ICameraProvider</name> + <instance>legacy/0</instance> + <instance>proprietary/0</instance> + </interface> + </hal> + <hal> + <name>android.hardware.nfc</name> + <transport>hwbinder</transport> + <version>1.0</version> + <version>2.0</version> + <interface> + <name>INfc</name> + <instance>nfc_nci</instance> + </interface> + </hal> + <hal> + <name>android.hardware.nfc</name> + <transport>hwbinder</transport> + <version>2.0</version> + <interface> + <name>INfc</name> + <instance>default</instance> + </interface> + </hal> + <hal format="native"> + <name>EGL</name> + <version>1.1</version> + </hal> + <hal format="native"> + <name>GLES</name> + <version>1.1</version> + <version>2.0</version> + <version>3.0</version> + </hal> + <sepolicy> + <version>25.0</version> + </sepolicy> +</manifest> +</pre> + +<h2 id="framework-manifest-file">框架清单文件</h2> +<p>框架清单文件由 Google 提供，是手动生成的文件。它在 Android 源代码树中位于 <code>system/libhidl/manifest.xml</code>，在设备上位于 <code>/system/manifest.xml</code>。</p> + +<p>框架清单（由 Google 提供）示例：</p> + +<pre class="prettyprint"> +<?xml version="1.0" encoding="UTF-8"?> +<!-- Comments, Legal notices, etc. here --> +<manifest version="1.0" type="framework"> + <hal> + <name>android.hidl.allocator</name> + <transport>hwbinder</transport> + <version>1.0</version> + <interface> + <name>IAllocator</name> + <instance>ashmem</instance> + </interface> + </hal> + <hal> + <name>android.hidl.memory</name> + <transport arch="32+64">passthrough</transport> + <version>1.0</version> + <interface> + <name>IMapper</name> + <instance>ashmem</instance> + </interface> + </hal> + <hal> + <name>android.hidl.manager</name> + <transport>hwbinder</transport> + <version>1.0</version> + <interface> + <name>IServiceManager</name> + <instance>default</instance> + </interface> + </hal> + <hal> + <name>android.frameworks.sensorservice</name> + <transport>hwbinder</transport> + <version>1.0</version> + <interface> + <name>ISensorManager</name> + <instance>default</instance> + </interface> + </hal> +</manifest> +</pre> + +<h2 id="manifest-file-schema">清单文件结构</h2> +<dl> +<dt><code>?xml</code></dt> +<dd>可选。只向 XML 解析器提供信息。</dd> +<dt><code>manifest.version</code></dt> +<dd>必需。<strong>该</strong>清单的版本。描述清单中预期的元素。与 XML 版本无关。</dd> +<dt><code>manifest.type</code></dt> +<dd>必需。该清单的类型。对于设备清单文件，其值为 <code>device</code>；对于框架清单文件，其值为 <code>framework</code>。</dd> +<dt><code>manifest.hal</code></dt> +<dd>可选且可重复。单个 HAL（HIDL 或本机，如 GL），具体取决于 <code>format</code> 属性。</dd> +<dt><code>manifest.hal.format</code></dt> +<dd>可选。值可以是以下几项之一：<ul> + <li><code>hidl</code>：HIDL HAL。这是默认值。 + </li><li><code>native</code>：本机 HAL。</li> + </ul> +</dd> +<dt><code>manifest.hal.name</code></dt> +<dd>必需。HAL 的完全限定软件包名称。多个 HAL 条目可以使用相同的名称。示例：<ul> + <li><code>android.hardware.camera</code> (HIDL HAL)</li> + <li><code>GLES</code>（本机 HAL，只需要名称）</li> + </ul> + </dd> +<dt><code>manifest.hal.transport</code></dt> +<dd>在 <code>manifest.hal.format == "hidl"</code> 时是必需的。在其他情况下，则不得存在。指明从服务管理器查询来自该软件包的接口时将使用什么传输模式。值可以是以下几项之一：<ul> + <li><code>hwbinder</code>：绑定模式</li> + <li><code>passthrough</code>：直通模式</li> + </ul> +</dd> +<dt><code>manifest.hal.transport.arch</code></dt> +<dd>对于 <code>passthrough</code> 是必需的，对于 <code>hwbinder</code> 不得存在。描述正在提供的直通服务的位数。值可以是以下几项之一：<ul> + <li><code>32</code>：32 位模式</li> + <li><code>64</code>：64 位模式</li> + <li><code>32+64</code>：两者兼有</li> + </ul> +</dd> +<dt><code>manifest.hal.version</code></dt> +<dd>必需且可重复。清单中 <code>hal</code> 标记的版本。格式为 <code><var>MAJOR</var>.<var>MINOR</var></code>。有关示例，请参阅 <code>hardware/interfaces</code>、<code>vendor/${VENDOR}/interfaces</code>、<code>framework/hardware/interfaces</code> 或 <code> +system/hardware/interfaces</code>。 +<br /><br /> +HIDL 和本机 HAL 可以使用多个版本字段，前提是它们代表<strong>不同的主要版本</strong>，并且提供的每个主要版本只有一个次要版本。例如，3.1 和 3.2 不能共存，但 1.0 和 3.4 可以共存。这适用于所有同名的 <code>hal</code> 元素。</dd> +<dt><code>manifest.hal.interface</code></dt> +<dd>必需，可以在不重名的情况下进行重复使用。指明软件包中具有实例名称的接口。一个 <code><hal></code> 中可以有多个 <code><interface></code> 元素，但名称必须不同。</dd> +<dt><code>manifest.hal.interface.name</code></dt> +<dd>必需。接口的名称。</dd> +<dt><code>manifest.hal.interface.instance</code></dt> +<dd>必需且可重复。接口的实例名称。一个接口可以有多个实例，但不能有重复的 <code><instance></code> 元素。</dd> +<dt><code>manifest.sepolicy</code></dt> +<dd>必需。包含所有与 sepolicy 相关的条目。</dd> +<dt><code>manifest.sepolicy.version</code></dt> +<dd>对于设备清单是必需的。用于声明 sepolicy 版本。格式为 SDK_INT.PLAT_INT。<var></var><var></var></dd> +</dl> + +<h2 id="runtime-data">运行时数据</h2> +<p>设备清单所需的某些信息只能在运行时收集。信息通过 <code>::android::vintf::VintfObject::GetRuntimeInfo()</code> 获得，其中包含以下内容：</p> + +<ul> +<li>内核信息，包括：<ul> + <li><code>/proc/config.gz</code>：压缩的完整内核配置，该信息需要在运行时读取并转换为可查询的对象。</li> + <li><code>/proc/version</code>：通过 <code>uname()</code> 系统调用获得的信息。</li> + <li><code>/proc/cpuinfo</code>：对于 32 位和 64 位计算机，格式可能会不同。</li> + <li>policydb 版本 + <ul> + <li><code>/sys/fs/selinux/policyvers</code>（假设 <code>selinuxfs</code> 装载在 <code>/sys/fs/selinux</code> 处）。</li> + <li>来自 <code>libselinux</code> 的 <code>security_policyvers()</code> API 可提供相同的信息。</li> + </ul> + </li> + </ul> +</li><li>静态 libavb 版本，包括： + <ul> + <li>引导加载程序系统属性：<code>ro.boot.vbmeta.avb_version</code></li> + <li>init/fs_mgr 系统属性：<code>ro.boot.avb_version</code></li> + </ul> +</li> +</ul> + +<h2 id="queryable-api">可查询的 API</h2> +<p>当 <code>hwservicemanager</code>、OTA 更新服务、CTS <code>DeviceInfo</code> 以及其他组件需要从 VINTF 对象中获取信息时，该对象是作为系统 API 存在的。</p> + +<ul> +<li>C++ 可查询的 API 位于 <a href="https://android.googlesource.com/platform/system/libvintf/+/master/include/vintf/VintfObject.h" class="external"><code>android::vintf::VintfObject</code></a></li> +<li>Java 可查询的 API 位于 <a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/os/VintfObject.java" class="external"><code>android.os.VintfObject</code></a> +</li></ul> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/architecture/vintf/resources.html b/zh-cn/devices/architecture/vintf/resources.html new file mode 100644 index 00000000..e9ba7835 --- /dev/null +++ b/zh-cn/devices/architecture/vintf/resources.html @@ -0,0 +1,190 @@ +<html devsite><head> + <title>其他资源</title> + <meta name="project_path" value="/_project.yaml"/> + <meta name="book_path" value="/_book.yaml"/> + </head> + <body> + <!-- + Copyright 2017 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. + --> + +<p>以下资源提供了有关代码位置、工具、测试、许可和注意事项的详细信息。</p> + +<h2 id="query-api-code">可查询的代码位置</h2> +<p>可查询的供应商接口对象的代码位于 <code><a href="https://android.googlesource.com/platform/system/libvintf/+/master#" class="external">system/libvintf</a></code>（请参见<a href="/devices/architecture/vintf/objects.html#queryable-api">可查询的 API</a>）。</p> + +<h2 id="related-tools">工具</h2> +<p>手写清单文件和兼容性矩阵可能很难。您可以使用以下工具来生成样板清单/兼容性矩阵，从其入手。</p> + +<h3 id="lshal">LSHAL</h3> +<p>LSHAL 是一种设备端工具，可以列出向 <code>hwservicemanager</code> 注册的所有 HAL 以及设备上所有可用的直通实现（例如 <code>android.hardware.foo@1.0-impl.so</code>）。它还可以根据该列表生成<strong>设备清单</strong>文件：</p> + +<pre class="devsite-terminal"> +adb shell su 0 /system/bin/lshal --init-vintf +</pre> + +<p>请注意以下几点：</p> +<ol> +<li>如果既向 <code>hwservicemanager</code> 注册了某个软件包，又发现其作为直通 HAL，则将 <code><transport></code> 设置为 <code>hwbinder</code>。</li> +<li>清单的末尾存在一个虚拟 <code><sepolicy><version>0.0</version></sepolicy></code> 元素。它指明了该元素已被删除并将通过 <code>assemble_vintf</code> 将其注入（如下所述）。</li> +<li>生成的 HAL 清单文件可能不准确。需要手动对比来更正设备清单与 <code>vendor.img</code> 实际提供的内容之间的不一致。</li> +</ol> + +<h3 id="assemble_vintf">ASSEMBLE_VINTF</h3> +<p><code>assemble_vintf</code> 是一种主机端工具，可以执行以下操作：</p> +<ol> +<li>验证兼容性矩阵或清单文件是否有效。</li> +<li>将变量注入到构建时可用的清单/兼容性矩阵，并生成应该安装到设备上的新文件。</li> +<li>检查生成的文件与其双重文件之间的兼容性。</li> +<li>如果给出了清单文件，则可以视需要生成与该清单文件兼容的样板兼容性矩阵。</li> +</ol> + +<h4><strong>示例：</strong>从框架清单文件生成<strong>设备兼容性矩阵</strong></h4> + +<pre class="devsite-terminal"> +assemble_vintf -m \ + -i system/libhidl/manifest.xml \ + -o device/manufacturer/device_name/compatibility_matrix.xml +</pre> +<p>请注意以下几点：</p> +<ul> +<li>即使 <code><vndk></code> 条目在输出兼容性矩阵中，也应该将其删除，然后在构建时进行注入。</li> +<li>所有 HAL 都设置为 <code>optional="true"</code>。</li> +</ul> + +<h4><strong>示例：</strong>从设备清单文件生成骨架框架兼容性矩阵</h4> + +<pre class="devsite-terminal"> +BOARD_SEPOLICY_VERS=10000.0 assemble_vintf -m \ + -i device/foo/bar/manifest.xml + -o path/to/place/output/compatibility_matrix.xml +</pre> +<p>请注意以下几点：</p> +<ul> +<li>即使 <code><sepolicy></code> 和 <code><avb></code> 在输出兼容性矩阵中，也应该将其删除，然后在构建时进行注入。</li> +<li>所有 HAL 都设置为 <code>optional="true"</code>。</li> +</ul> + +<h4><strong>示例：</strong>从变量生成 XML 文件</h4> + +<p>构建时，如果在 <code>device/manufacturer/device_name/BoardConfig.mk</code> 中定义了以下变量：</p> + +<pre class="prettyprint"> +DEVICE_MANIFEST_FILE := \ + device/manufacturer/device_name/manifest.xml +DEVICE_MATRIX_FILE := \ + device/manufacturer/device_name/compatibility_matrix.xml +</pre> + +<p>然后，执行以下命令（修改为省略实现详细信息）来生成所有 XML 文件：</p> + +<pre class="prettyprint"> +# device manifest; only when DEVICE_MANIFEST_FILE is set +BOARD_SEPOLICY_VERS=10000.0 assemble_vintf \ + -i device/manufacturer/device_name/manifest.xml \ + -o $(TARGET_OUT_VENDOR)/manifest.xml + +# device compatibility matrix; only when DEVICE_MATRIX_FILE is set +assemble_vintf \ + -i device/manufacturer/device_name/compatibility_matrix.xml \ + -o $(TARGET_OUT_VENDOR)/compatibility_matrix.xml + +# framework manifest +assemble_vintf + -i system/libhidl/manifest.xml \ + -o $(TARGET_OUT)/manifest.xml \ + -c $(TARGET_OUT_VENDOR)/compatibility_matrix.xml + +# framework compatibility matrix +BOARD_SEPOLICY_VERS=$(BOARD_SEPOLICY_VERS) \ +POLICYVERS=$(POLICYVERS) \ +BOARD_AVB_VBMETA_VERSION=$(BOARD_AVB_VBMETA_VERSION) +assemble_vintf \ + -i hardware/interfaces/compatibility_matrix.xml \ + -o $(TARGET_OUT)/compatibility_matrix.xml \ + -c $(TARGET_OUT_VENDOR)/manifest.xml \ +</pre> + +<h4><strong>示例：</strong>从片段生成设备清单</h4> + +<p>多个设备清单片段可以在构建时捆绑。例如：</p> + +<pre class="prettyprint"> +<!-- device/manufacturer/device_name/manifest_common.xml --> +<manifest version="1.0" type="device"> + <!-- common HALs here --> +</manifest> +</pre> + +<pre class="prettyprint"> +<!-- device/manufacturer/device_name/ir.xml --> +<manifest version="1.0" type="device"> + <hal> + <name>android.hardware.ir</name> + <version>1.0</version> + <!-- other fields --> + </hal> +</manifest> +</pre> + +<pre class="prettyprint"> +# device/manufacturer/device_name/BoardConfig.mk +DEVICE_MANIFEST_FILE := device/manufacturer/device_name/manifest_common.xml +ifdef BOARD_ENABLE_IR + DEVICE_MANIFEST_FILE += device/manufacturer/device_name/ir.xml +endif +</pre> + +<p>然后，如果定义了 <code>BOARD_ENABLE_IR</code>，则 <code>assemble_vintf</code> 将 Ir HAL 添加到设备清单；如果未定义 <code>BOARD_ENABLE_IR</code>，则将其省略。执行以下命令（修改为省略实现详细信息）来生成设备清单：</p> + +<pre class="prettyprint"> +# if BOARD_ENABLE_IR is defined +BOARD_SEPOLICY_VERS=10000.0 assemble_vintf \ + -i device/manufacturer/device_name/manifest_common.xml:device/manufacturer/device_name/ir.xml \ + -o $(TARGET_OUT_VENDOR)/manifest.xml + +# if BOARD_ENABLE_IR is not defined +BOARD_SEPOLICY_VERS=10000.0 assemble_vintf \ + -i device/manufacturer/device_name/manifest_common.xml \ + -o $(TARGET_OUT_VENDOR)/manifest.xml +</pre> + +<p>有关详细信息，请参见：</p> + +<pre class="devsite-terminal">assemble_vintf --help</pre> + +<h2 id="testing">测试</h2> +<p><code>platform/system/libvintf</code> 项目使用 <a href="https://github.com/google/googletest" class="external">GTest</a> 进行序列化、反序列化和兼容性检查。</p> + +<h2 id="licensing">许可</h2> +<ul> +<li><code>tinyxml2</code> (external/tinyxml2) 用于将对象序列化到 XML 或从 XML 反序列化对象。类似于 BSD 的许可证。</li> +<li><code>libselinux</code> (external/selinux/libselinux) 用于获取 policydb 版本。公共网域许可证。</li> +<li><code>libz</code> (external/zlib) 用于解压缩 <code>/proc/config.gz</code>。类似于 BSD 的许可证。</li> +<li><code>libvintf</code> 项目使用 Apache 2.0 许可证（具有适当的 MODULE_LICENSE_APACHE2 和 NOTICE 文件）。</li> +</ul> + +<h2 id="caveats">注意事项</h2> +<p>您也可以通过查询 <code>hwservicemanager</code>（就像 <code>lshal</code> 一样）在运行时确定 HAL。但是：</p> +<ul> +<li><code>hwservicemanager</code> 不会列出直通服务。</li> +<li>如果服务刚刚崩溃并正在重新启动，则可能会在查询结果中缺失。</li> +<li>不适用于可热插拔服务。</li> +<li><code>hwservicemanager</code> 在恢复模式下不可用（请参见下文）。</li> +</ul> + +<p>在恢复模式下，用于检索供应商接口对象的 API 必须仍然可用，以允许设备再次对照兼容性矩阵检查供应商接口。</p> + +</body></html>
\ No newline at end of file diff --git a/zh-cn/devices/audio/data_formats.html b/zh-cn/devices/audio/data_formats.html index 574800a2..d4a90375 100644 --- a/zh-cn/devices/audio/data_formats.html +++ b/zh-cn/devices/audio/data_formats.html @@ -21,13 +21,13 @@ --> <p> -Android 在内部使用各种音频<a href="http://en.wikipedia.org/wiki/Data_format">数据格式</a>，并在公共 API、<a href="http://en.wikipedia.org/wiki/Audio_file_format">文件格式</a>和<a href="https://en.wikipedia.org/wiki/Hardware_abstraction">硬件抽象层</a> (HAL) 中公布了其中的一部分。 +Android 在内部使用多种音频<a href="http://en.wikipedia.org/wiki/Data_format">数据格式</a>，并在公共 API、<a href="http://en.wikipedia.org/wiki/Audio_file_format">文件格式</a>和<a href="https://en.wikipedia.org/wiki/Hardware_abstraction">硬件抽象层</a> (HAL) 中公布了其中的一部分。 </p> <h2 id="properties">属性</h2> <p> -音频数据格式是按其属性进行分类： +音频数据格式按其属性进行分类： </p> <dl> @@ -71,15 +71,15 @@ Android 在内部使用各种音频<a href="http://en.wikipedia.org/wiki/Data_fo </p> <p> -定点数在<a href="https://en.wikipedia.org/wiki/Radix_point">小数点</a>前后具有固定（恒定）位数。我们所有的表示法都使用<a href="https://en.wikipedia.org/wiki/Binary_number">基数 2</a>，所以我们用“位”代替“位数”，用“二进制点”或简单的“点”代替“小数点”。<em></em><em><em></em><em></em><em></em></em>点左边的位是整数部分，点右边的位是<a href="https://en.wikipedia.org/wiki/Fractional_part">小数部分</a>。 +定点数在<a href="https://en.wikipedia.org/wiki/Radix_point">小数点</a>前后具有固定（恒定）位数。我们所有的表示法都使用<a href="https://en.wikipedia.org/wiki/Binary_number">基数 2</a>，所以我们用“位”代替“位数”，用“二进制点”或简单的“点”代替“小数点”。<em></em><em></em><em></em><em></em><em></em>点左边的位是整数部分，点右边的位是<a href="https://en.wikipedia.org/wiki/Fractional_part">小数部分</a>。 </p> <p> -我们之所以用“整数 PCM”，是因为定点数值通常作为整数值进行存储和操作。<em></em>作为定点数的解释是隐含的。 +我们之所以用“整数 PCM”的说法，是因为定点数值通常作为整数值进行存储和操作。<em></em>作为定点数的解释是隐含的。 </p> <p> -我们对所有有符号的定点数表示法使用<a href="https://en.wikipedia.org/wiki/Two%27s_complement">二进制补码</a>，因此下列表达式的值可使用一个 <a href="https://en.wikipedia.org/wiki/Least_significant_bit">LSB</a> 来实现： +我们对所有带符号定点数表示法使用<a href="https://en.wikipedia.org/wiki/Two%27s_complement">二进制补码</a>，因此下列表达式中的所有值都以 <a href="https://en.wikipedia.org/wiki/Least_significant_bit">LSB</a> 为单位： </p> <pre class="devsite-click-to-copy"> |largest negative value| = |largest positive value| + 1 @@ -291,7 +291,7 @@ NaN 行为尚未定义：NaN 可以作为相同的 NaN 传递，也可以转换 <h3 id="lossyConversion">有损和无损转换</h3> <p> -如果转换<a href="https://en.wikipedia.org/wiki/Inverse_function">可逆</a>，则是无损的：从 <code>A</code> 转换到 <code>B</code> 再到 <code>C</code>，那么可以得出 <code>A = C</code>。否则，转换是<a href="https://en.wikipedia.org/wiki/Lossy_data_conversion">有损</a>的。<em></em> +<em></em>如果转换<a href="https://en.wikipedia.org/wiki/Inverse_function">可逆</a>，则是无损的：从 <code>A</code> 转换到 <code>B</code> 再到 <code>C</code>，那么可以得出 <code>A = C</code>。否则，转换是<a href="https://en.wikipedia.org/wiki/Lossy_data_conversion">有损的</a>。 </p> <p> diff --git a/zh-cn/devices/graphics/run-tests.html b/zh-cn/devices/graphics/run-tests.html index 596c6b94..b8117cc5 100644 --- a/zh-cn/devices/graphics/run-tests.html +++ b/zh-cn/devices/graphics/run-tests.html @@ -153,7 +153,7 @@ </tr> <tr> <td><code>--deqp-gl-config-name=<name></code></td> - <td><p>对已命名的 GL 配置运行测试。解译取决于平台。对于 EGL，格式为 <code>rgb(a)<bits>d<bits>s<bits></code>。例如，值 <code>rgb888s8</code> 会选择第一个配置，其中颜色缓冲区为 RGB888，模板缓冲区为 8 位。</p></td> + <td>对已命名的 GL 配置运行测试。解译取决于平台。对于 EGL，格式为 <code>rgb(a)<bits>d<bits>s<bits></code>。例如，值 <code>rgb888s8</code> 会选择第一个配置，其中颜色缓冲区为 RGB888，模板缓冲区为 8 位。</td> </tr> <tr> <td><code>--deqp-gl-context-flags=<flags></code></td> @@ -254,6 +254,6 @@ python android/scripts/debug.py \ <p class="note"><strong>注意</strong>：在 Windows 上，GDB 二进制文件需要使用 <code>libpython2.7.dll</code>。在启动 <code>debug.py</code> 前，请将 <code><path-to-ndk>/prebuilt/windows/bin</code> 添加到 PATH 变量中。</p> -<p class="note"><strong>注意</strong>：本机代码调试不适用于 Android 4.3。有关解决方法，请参考<a href="https://issuetracker.google.com/issues/36976703">相关公开错误</a>。Android 4.4 及更高版本不包含此错误。</p> +<p class="note"><strong>注意</strong>：本机代码调试不适用于 Android 4.3。有关解决方法，请参考<a href="https://issuetracker.google.com/issues/36976703">此公开错误</a>。Android 4.4 及更高版本不包含此错误。</p> </body></html>
\ No newline at end of file diff --git a/zh-cn/devices/tech/connect/emergency-affordance.html b/zh-cn/devices/tech/connect/emergency-affordance.html index 723514b8..67b3196a 100644 --- a/zh-cn/devices/tech/connect/emergency-affordance.html +++ b/zh-cn/devices/tech/connect/emergency-affordance.html @@ -69,21 +69,27 @@ <table> <tbody><tr> - <td width="50%"><img src="images/emergency-button.png" alt="紧急呼叫按钮" width="246" id="emergency-button"/> + <td width="50%"><img src="/devices/tech/connect/images/emergency-button.png" alt="紧急呼叫按钮" width="246" id="emergency-button"/> <p class="img-caption"> <strong>图 1. </strong> 长按锁定屏幕上的<strong>紧急呼救</strong>按钮（已用红框突显）。</p></td> - <td width="50%"><img src="images/emergency-option.png" alt="紧急呼叫按钮" width="247" id="emergency-option"/> + <td width="50%"><img src="/devices/tech/connect/images/emergency-option.png" alt="紧急呼叫选项" width="247" id="emergency-option"/> <p class="img-caption"> <strong>图 2. </strong> 点按全局操作菜单中的<strong>紧急呼救</strong>操作项。<em></em></p></td> </tr> </tbody></table> <p>该功能引入了以下内部组件：</p> <ul> -<li>EmergencyAffordanceManager<br /> -<code>frameworks/base/core/java/com/android/internal/policy/EmergencyAffordanceManager.java</code> -</li> <li>EmergencyAffordanceService<br /> -<code>frameworks/base/services/core/java/com/android/server/emergency/EmergencyAffordanceService.java</code> -</li> </ul> +<li>EmergencyAffordanceManager +<pre class="devsite-click-to-copy"> +frameworks/base/core/java/com/android/internal/policy/EmergencyAffordanceManager.java +</pre> +</li> +<li>EmergencyAffordanceService +<pre class="devsite-click-to-copy"> +frameworks/base/services/core/java/com/android/server/emergency/EmergencyAffordanceService.java +</pre> +</li> +</ul> <h3 id="EmergencyAffordanceManager">EmergencyAffordanceManager</h3> <p>EmergencyAffordanceManager 提供使用“提供紧急呼叫”功能的内部 API。它提供启动紧急呼救的方法，并在运行时查询是否应启用该功能。</p> <ul> <li><code>void performEmergencyCall()</code> - 启动紧急呼救</li> @@ -125,21 +131,21 @@ performEmergencyCall()</code> - 启动紧急呼救</li> </tbody> </table> -<h3 id="112">启用“112”紧急呼救</h3> <p>“提供紧急呼叫”功能使用紧急拨号器连接通话，因此通话可以在锁屏状态下连接。紧急拨号器只能将通话连接到无线界面层 (RIL) 提供的号码列表：在未安装 SIM 卡时，通过系统属性“ril.ecclist”连接；在插入 SIM 卡且 <code><i><SimSlotNumber></i></code> 是默认订阅者的插槽 ID 时，通过“<code>ril.ecclist<<i>SimSlotNumber</i>></code>”连接。<br />使用“提供紧急呼叫”功能的设备制造商必须确保在印度地区销售的设备始终将 112 作为 RIL 中的紧急呼救号码。</p> +<h3 id="112">启用“112”紧急呼救</h3> <p>“提供紧急呼叫”功能使用紧急拨号器连接通话，因此通话可以在锁屏状态下连接。紧急拨号器只能将通话连接到无线界面层 (RIL) 提供的号码列表：如果未安装 SIM 卡，则通过系统属性“ril.ecclist”连接；如果已插入 SIM 卡且 <code><i><SimSlotNumber></i></code> 是默认订阅者的槽位 ID，则通过“<code>ril.ecclist<<i>SimSlotNumber</i>></code>”连接。<br />使用“提供紧急呼叫”功能的设备制造商必须确保在印度地区销售的设备始终将 112 作为 RIL 中的紧急呼救号码。</p> <h2 id="validation">验证</h2> <p>在可调式的构建上测试时，可以使用以下命令更改呼叫的号码：</p> -<pre> -$ adb shell settings put global emergency_affordance_number <i><number_to_call></i> +<pre class="devsite-terminal devsite-click-to-copy"> +adb shell settings put global emergency_affordance_number <var>NUMBER_TO_CALL</var> </pre> <p>虽然此设置可以在普通用户构建中设置，但会被忽略。要实际连接通话，号码必须存在于 RIL 提供的紧急呼救号码列表中。这可以临时设置，具体方法是在 userdebug 设备上使用通过根 shell 执行的以下命令：</p> -<pre> -$ setprop ril.ecclist "$(getprop ril.ecclist),<i><number_to_call></i>" +<pre class="devsite-terminal devsite-click-to-copy"> +setprop ril.ecclist "$(getprop ril.ecclist),<var>NUMBER_TO_CALL</var>" </pre> <p>此外，如需在未检测到印度移动网络或未插入印度 SIM 卡的情况下强制启用“提供紧急呼叫”功能，可以使用以下命令：</p> -<pre> -$ adb shell settings put global force_emergency_affordance 1 +<pre class="devsite-terminal devsite-click-to-copy"> +adb shell settings put global force_emergency_affordance 1 </pre> <p>在测试期间，建议至少对以下情况进行测试。</p> diff --git a/zh-cn/devices/tech/ota/inside_packages.html b/zh-cn/devices/tech/ota/inside_packages.html index 8d58080b..ee40ad3d 100644 --- a/zh-cn/devices/tech/ota/inside_packages.html +++ b/zh-cn/devices/tech/ota/inside_packages.html @@ -74,17 +74,13 @@ tgt_size</i>, <i>patch1_sha1</i>, <i>patch1_blob</i>, [...])</code></dt> <dt><code>apply_patch_check(<i>filename</i>, <i>sha1</i>[, <i>sha1</i>, ...]) </code></dt> <dd>如果 filename 的内容或缓存分区中的临时副本（如果存在）中的内容具有与给定的 sha1 值之一相等的 SHA1 校验和，则返回 True。sha1 值指定为 40 位十六进制数字。<i></i><i></i><i></i>此函数与 <code>sha1_check(read_file(<i>filename</i>), -<i>sha1</i> [, ...])</code> 的不同之处在于，它知道检查缓存分区副本。因此，即使文件被中断的 <code>apply_patch() update</code> 损坏，<code>apply_patch_check()</code> 仍会成功执行。</dd> +<i>sha1</i> [, ...])</code> 的不同之处在于，它知道检查缓存分区副本。因此，即使文件被中断的 <code>apply_patch() update</code> 损坏，<code>apply_patch_check()</code> 也会成功执行。</dd> <dt><code>apply_patch_space(<i>bytes</i>)</code></dt> -<dd>如果至少有 bytes 字节暂存空间可用于应用二进制补丁程序，则返回 True。<i></i></dd> +<dd>如果至少有几字节暂存空间可用于应用二进制补丁程序，则返回 True。<i></i></dd> <dt><code>concat(<i>expr</i>[, <i>expr</i>, ...])</code></dt> <dd>评估每个表达式并将它们连接起来。在只有两个参数的特殊情况下，+ 运算符就是该函数的语法糖（但该函数形式可以包含任意数量的表达式）。表达式必须为字符串；该函数不能连接 Blob。</dd> -<dt><code>delete([<i>filename</i>, ...])</code></dt> -<dd>删除列出的所有 filename。<i></i>返回成功删除的文件数。</dd> -<dt><code>delete_recursive([<i>dirname</i>, ...])</code></dt> -<dd><i></i>递归删除 dirname 及目录中的所有内容。返回成功删除的目录数。</dd> <dt><code>file_getprop(<i>filename</i>, <i>key</i>)</code></dt> -<dd><i></i><i></i><i></i>读取给定的 filename，将其解释为属性文件（例如：<code>/system/build.prop</code>），并返回给定 key 的值，如果 key 不存在，则返回空字符串。</dd> +<dd>读取给定的 filename，将其解释为属性文件（例如：<code>/system/build.prop</code>），并返回给定 key 的值，如果 key 不存在，则返回空字符串。<i></i><i></i><i></i></dd> <dt><code>format(<i>fs_type</i>, <i>partition_type</i>, <i>location</i>, <i> fs_size</i>, <i>mount_point</i>)</code></dt> <dd>重新格式化给定的分区。支持的分区类型如下： @@ -121,22 +117,8 @@ partition_type<i></i> 必须为以下类型之一：<ul> <dd>从更新包中提取单个 package_file 并将其写入 dest_file，如有必要，覆盖现有文件。<i></i><i></i>在没有 dest_file 参数的情况下，将更新包文件的内容作为二进制 blob 返回。<i></i></dd> <dt><code>read_file(<i>filename</i>)</code></dt> <dd>读取 filename 并将其内容作为二进制 Blob 返回。<i></i></dd> -<dt><code>rename(<i>src_filename</i>, <i>tgt_filename</i>)</code></dt> -<dd>将 src_filename 重命名为 tgt_filename。<i></i><i></i>系统会自动为 tgt_filename 创建必要的目录。<i></i>例如：<code> -rename("system/app/Hangouts/Hangouts.apk", -"system/priv-app/Hangouts/Hangouts.apk")</code>。</dd> <dt><code>run_program(<i>path</i>[, <i>arg</i>, ...])</code></dt> <dd>在 path 上执行二进制文件，以传递 arg。<i></i><i></i>返回程序的退出状态。</dd> -<dt><code>set_metadata(<i>filename</i>, <i>key1</i>, <i>value1</i>[, <i>key2 -</i>, <i>value2</i>, ...])</code></dt> -<dd>将给定 filename 的 key 设置为 value。<i></i><i></i>例如： -<code>set_metadata("/system/bin/netcfg", "uid", 0, "gid", 3003, "mode", 02750, -"selabel", "u:object_r:system_file:s0", "capabilities", 0x0)</code>。</dd> -<dt><code>set_metadata_recursive(<i>dirname</i>, <i>key1</i>, <i>value1</i>[, -<i>key2</i>, <i>value2</i>, ...])</code></dt> -<dd>递归地将给定 dirname 及其所有子项的 key 设置为 value。<i></i><i></i>例如：<code>set_metadata_recursive("/system", "uid", -0, "gid", 0, "fmode", 0644, "dmode", 0755, "selabel", -"u:object_r:system_file:s0", "capabilities", 0x0)</code>。</dd> <dt><code>set_progress(<i>frac</i>)</code></dt> <dd>在最新的 <code>show_progress()</code> 调用所定义的块内设置进度条的位置。frac 必须介于 [0.0，1.0] 的范围内。<i></i>进度条从不向后移动；向后移动的尝试会被忽略。</dd> <dt><code>sha1_check(<i>blob</i>[, <i>sha1</i>])</code></dt> @@ -150,8 +132,6 @@ set_progress()</code> 函数实现进度递增。<i></i><i></i><i></i></dd> <dd>休眠 secs 秒（必须为整数）。<i></i></dd> <dt><code>stdout(<i>expr</i>[, <i>expr</i>, ...])</code></dt> <dd>评估每个表达式并将其值转储到 stdout。这在调试时很有用。</dd> -<dt><code>symlink(<i>target</i>[, <i>source</i>, ...])</code></dt> -<dd>将所有 source 创建为 target 的符号链接。<i></i><i></i></dd> <dt><code>tune2fs(<i>device</i>[, <i>arg</i>, …])</code></dt> <dd>调整 device 上的可调参数 arg。<i></i><i></i></dd> <dt><code>ui_print([<i>text</i>, ...])</code></dt> diff --git a/zh-cn/source/faqs.html b/zh-cn/source/faqs.html index 4b23549d..af00f26e 100644 --- a/zh-cn/source/faqs.html +++ b/zh-cn/source/faqs.html @@ -28,13 +28,13 @@ <p>我们使用“Android 开放源代码项目”或“AOSP”来表示 Android 涉及的人员、流程和源代码。</p> <p>人员负责监督该项目并开发实际的源代码。流程指我们为了管理该软件的开发而使用的工具和程序。该项目的最终结果是您可以用来打造手机和其他设备的源代码。</p> <h3 id="why-did-we-open-the-android-source-code">我们为什么开放了 Android 源代码？</h3> -<p>根据我们自己在发布移动应用方面的经验，Google 启动了 Android 项目。我们希望确保始终有开放的平台可供运营商、原始设备制造商 (OEM) 和开发者使用，以便他们将创新的想法变为现实。我们还希望确保不存在任何集中瓶颈，这样的话，就没有任何行业参与者可以一手限制或控制任何其他参与者开展创新。Android 开放源代码项目 (AOSP) 有一个最重要的目标，就是确保尽可能广泛、尽可能兼容地实施 Android 开放源代码软件，使每个人都能从中受益。</p> +<p>根据我们自己在开发移动应用方面的经验，Google 启动了 Android 项目。我们希望确保始终有开放的平台可供运营商、原始设备制造商 (OEM) 和开发者使用，以便他们将创新的想法变为现实。我们还希望确保不存在任何集中瓶颈，这样的话，就没有任何行业参与者可以一手限制或控制任何其他参与者开展创新。Android 开放源代码项目 (AOSP) 有一个最重要的目标，就是确保尽可能广泛、尽可能兼容地实施 Android 开放源代码软件，使每个人都能从中受益。</p> <h3 id="what-kind-of-open-source-project-is-android">Android 是哪种开放源代码项目？</h3> <p>Google 负责监督 Android 开放源代码平台核心部分的开发工作，并致力于打造卓越的开发者和用户社区。在大多数情况下，Android 源代码都是根据宽松的 Apache Software License 2.0（而非“Copyleft”许可）授权用户使用。这主要是因为我们最重要的目标是让用户广泛采用该软件，而我们认为 ASL2.0 许可有助于最好地实现这一目标。</p> <p>您可以在我们的<a href="/source/licenses.html">许可</a>页面中找到关于此主题的更多信息。</p> <h3 id="why-is-google-in-charge-of-android">为什么由 Google 主管 Android 项目？</h3> -<p>发布软件平台非常复杂。开放性对于平台长期取得成功至关重要，这是因为要吸引开发者投入到其中并确保公平的竞争环境，必须具备开放性。不过，平台本身也必须是对用户极具吸引力的产品。</p> -<p>正是因为这个原因，Google 调配了必需的专业工程资源，以确保 Android 是具备充分竞争力的软件平台。Google 将 Android 项目视为一个全方位的产品开发运营项目，并致力于实现必要的业务交易，以确保运行 Android 的卓越设备能够确确实实地将其推向市场。</p> +<p>开发软件平台是一项非常复杂的工作。开放性对于平台的长远成功至关重要，这是因为要吸引开发者投入到其中并确保公平的竞争环境，开放性必不可少。不过，平台本身也必须是对用户极具吸引力的产品。</p> +<p>正是因为这个原因，Google 调配了必需的专业工程资源，以确保 Android 是具备充分竞争力的软件平台。Google 将 Android 项目视为一个全方位的产品开发运营项目，并致力于达成必要的业务交易，以确保运行 Android 的卓越设备能够确确实实地将其推向市场。</p> <p>通过确保 Android 在用户那里获得成功，我们可以帮助确保 Android 作为平台和开放源代码项目的活力。毕竟，谁不希望 Android 源代码成为一款成功的产品呢？</p> <p>Google 的目标是确保围绕 Android 打造一个成功的生态系统。当然，没有哪个人必须参与其中。我们开放了 Android 源代码，以便任何人都可以修改和分发该软件来满足自己的需求。</p> <h3 id="what-is-googles-overall-strategy-for-android-product-development">Google 在 Android 产品开发方面的总体策略是什么？</h3> @@ -42,15 +42,15 @@ <p>在实践中，这意味着 Android 工程团队通常只侧重于少数“旗舰”设备，并负责开发下一版 Android 软件来为这些产品的发布提供支持。这些旗舰设备可以消化很多产品风险，并为广泛的原始设备制造商 (OEM) 社区开辟新的道路，让他们接下来能够推出更多充分利用新功能的设备。通过这种方式，我们可以确保 Android 平台能够根据现实设备的实际需求不断发展完善。</p> <h3 id="how-is-the-android-software-developed">Android 软件的开发方式是怎样的？</h3> <p>Android 的每个平台版本（例如 1.5、1.6 等）在开放源代码树中都有对应的分支。在任何指定的时刻，最新的此类分支将被视为“当前稳定”的分支版本。这个当前稳定的分支是制造商移植到其设备的分支。该分支会始终保持适合发布的状态。</p> -<p>同时，每个版本还有一个“当前实验性”分支，开发者可以在其中开发实验性贡献内容，例如大量的下一代功能。在适当情况下，实验性分支中的错误更正内容和其他贡献内容可以纳入到当前稳定分支中。</p> -<p>最后，Google 会在开发旗舰设备的同时致力于研究下一版 Android 平台。在适当情况下，该分支将纳入实验性分支和稳定分支中的更改。</p> +<p>同时，每个版本还有一个“当前实验性”分支，开发者可以在其中开发实验性贡献内容，例如大型的下一代功能。在适当情况下，实验性分支中的错误更正内容和其他贡献内容可以纳入到当前稳定分支中。</p> +<p>最后，Google 会在开发旗舰设备的同时致力于开发下一版 Android 平台。在适当情况下，该分支将纳入实验性分支和稳定分支中的更改。</p> <p>您可以在我们的<a href="/source/code-lines.html">代码行、分支和版本</a>页面中找到关于此主题的更多信息。</p> <h3 id="why-are-parts-of-android-developed-in-private">为什么 Android 的部分内容是在私下开发的？</h3> <p>将一款设备推向市场通常需要超过一年的时间。设备制造商无疑希望植入他们可以植入的最新 Android 软件。与此同时，开发者也不希望在编写应用时还要不断追用该平台的新版本。制造商和开发者都会面临及时推出自家产品与追用最新版本难以两全的状况。</p> <p>为了解决这个问题，下一版 Android 的部分内容（包括核心平台 API）会在私有分支中进行开发。这些 API 将纳入到下一版 Android 中。我们的目标是，在我们开发下一版平台的同时，让其他人将注意力放在当前稳定版 Android 源代码上。这样一来，开发者和原始设备制造商 (OEM) 便可以使用单个版本，而无需为了跟上 Android 开发步伐而追用尚不完善的未来版本。不过，Android 系统中与应用兼容性无关的其他部分是在开放环境中开发的。我们打算逐渐将其中更多的部分转移到开放的开发环境中。</p> <h3 id="when-are-source-code-releases-made">何时发布源代码？</h3> <p>当源代码准备就绪时发布。发布源代码是一个相当复杂的过程。Android 的某些部分是在开放环境中开发的，因此相应的源代码始终可用。还有一些部分最初是在私有树中开发的，并且相应的源代码会在下一个平台版本准备就绪时发布。</p> -<p>对于某些版本，核心平台 API 会提前足够长的时间准备就绪，这样我们就可以在设备发布之前推出源代码，以便提前了解一下相关情况；不过，对于另外一些版本，我们无法做到这一点。在所有情况下，当我们认为相应版本已足够稳定并且开发流程允许时，我们就会发布平台源代码。</p> +<p>对于某些版本，核心平台 API 会提前足够长的时间准备就绪。这种情况下，我们就可以在设备发布之前推出源代码，以便提前了解反馈情况。不过，对于另外一些版本，我们无法做到这一点。在所有情况下，当我们认为相应版本已足够稳定并且开发流程允许时，我们就会发布平台源代码。</p> <h3 id="what-is-involved-in-releasing-the-source-code-for-a-new-android-version">发布新版 Android 的源代码涉及哪些流程？</h3> <p>发布新版 Android 平台的源代码是一个非常重要的过程。首先，该软件要移植到设备的系统映像中，并通过各种形式的认证，包括手机销售区域的政府监管机构认证。另外，该软件还需要通过运营商测试。这是发布过程的一个重要阶段，因为这项测试有助于发现大量的软件错误。</p><p></p> <p>在发布事宜得到监管机构和运营商的批准后，制造商将开始大批量生产设备，并且我们将着手发布源代码。</p> @@ -59,11 +59,11 @@ <p>从制造商开始大批量生产设备算起，软件发布过程通常需要大约一个月的时间。这样一来，源代码的发布时间与设备到达用户手中的时间通常差不多。</p> <h3 id="how-does-the-aosp-relate-to-the-android-compatibility-program">AOSP 与 Android 兼容性计划有何关联？</h3> <p>Android 开放源代码项目旨在维护 Android 软件以及开发新版本。由于是开放源代码，因此该软件可用于任何用途，包括开发与基于同一源代码的其他设备不兼容的设备。</p> -<p>Android 兼容性计划旨在为 Android 制定与开发者编写的第三方应用兼容的基准实施方式。“与 Android 兼容”的设备可以参与 Android 生态系统，包括 Google Play；不符合兼容性要求的设备将无法参与该生态系统。</p> +<p>Android 兼容性计划旨在为 Android 制定与开发者编写的第三方应用兼容的基准实现方式。“与 Android 兼容”的设备可以参与 Android 生态系统，包括 Google Play；不符合兼容性要求的设备将无法参与该生态系统。</p> <p>也就是说，Android 兼容性计划规定了我们如何区分“与 Android 兼容的设备”与只是运行 Android 源代码衍生品的设备。我们欢迎各种 Android 源代码使用方式，但只有与 Android 兼容的设备（符合 Android 兼容性计划的定义并通过该计划的测试）才可以参与 Android 生态系统。</p> <h3 id="how-can-i-contribute-to-android">如何为 Android 做贡献？</h3> <p>您可以通过多种方式为 Android 做贡献。您可以报告错误、编写适用于 Android 平台的应用，或者为 Android 开放源代码项目贡献源代码。</p> -<p>关于我们愿意或能够接受哪些类型的代码贡献内容，有一些限制。例如，有人可能想要贡献替代应用 API，比如完全基于 C++- 的环境。我们会拒绝这种贡献内容，因为 Android 鼓励开发在 ART 运行时中运行的应用。同样，我们也不会接受与我们的许可目标不符的贡献内容（例如 GPL 或 LGPL 库）。</p> +<p>关于我们愿意或能够接受哪些类型的代码贡献内容，有一些限制。例如，有人可能想要贡献备选应用 API，比如完全基于 C++ 的环境。我们会拒绝这种贡献内容，因为 Android 鼓励开发在 ART 运行时中运行的应用。同样，我们也不会接受与我们的许可目标不符的贡献内容（例如 GPL 或 LGPL 库）。</p> <p>如果您有意贡献源代码，我们建议您在开始任何相关工作前先通过 <a href="/source/community.html">Android 社区</a>页面中列出的方式与我们联系。您可以在<a href="/source/contributing.html">贡献</a>页面中找到关于此主题的更多信息。</p> <h3 id="how-do-i-become-an-android-committer">如何成为 Android 代码提交者？</h3> <p>Android 开放源代码项目其实并没有“提交者”这一概念。所有贡献内容（包括由 Google 员工创作的内容）都是通过一个称为“Gerrit”的基于网页的系统提交的，该系统是 Android 工程流程的一部分。该系统与 Git 源代码管理系统协同工作，以便明晰地管理源代码贡献内容。</p> @@ -72,16 +72,16 @@ <a href="#top">返回页首</a> <h2 id="compatibility">兼容性</h2> <h3 id="what-does-compatibility-mean">“兼容性”是什么意思？</h3> -<p>我们将“与 Android 兼容的设备”定义为可以运行由第三方开发者使用 Android SDK 和 NDK 编写的任何应用的设备。我们将此作为过滤条件来区分可以参与和无法参与 Android 应用生态系统的设备。与 Android 妥善兼容的设备可以请求获准使用 Android 商标。不兼容的设备只不过是 Android 源代码的衍生产品，不能使用 Android 商标。</p> +<p>我们将“与 Android 兼容的设备”定义为可以运行由第三方开发者使用 Android SDK 和 NDK 编写的任何应用的设备。我们将此作为过滤条件来区分可以参与和无法参与 Android 应用生态系统的设备。与 Android 妥善兼容的设备可以申请使用 Android 商标。不兼容的设备只不过是 Android 源代码的衍生产品，不能使用 Android 商标。</p> <p>也就是说，兼容性是参与 Android 应用生态系统的前提条件。我们欢迎任何人使用 Android 源代码。但如果设备与 Android 不兼容，则不会被视为 Android 生态系统的一部分。</p> <h3 id="what-is-the-role-of-google-play-in-compatibility">Google Play 在兼容性方面发挥什么作用？</h3> -<p>与 Android 兼容的设备可以请求获得 Google Play 客户端软件使用许可。获得该许可后，这些设备便成为了 Android 应用生态系统的一部分，其用户将能够从所有与 Android 兼容的设备共享的目录中下载开发者的应用。与 Android 不兼容的设备无法获得该许可。</p> +<p>与 Android 兼容的设备可以申请 Google Play 客户端软件使用许可。获得该许可后，这些设备便成为了 Android 应用生态系统的一部分，其用户将能够从所有与 Android 兼容的设备共享的目录中下载开发者的应用。与 Android 不兼容的设备无法获得该许可。</p> <h3 id="what-kinds-of-devices-can-be-android-compatible">哪些类型的设备可与 Android 兼容？</h3> <p>Android 软件可以移植到许多不同类型的设备上，包括第三方应用无法在其中正常运行的某些设备。<a href="/compatibility/index.html">Android 兼容性定义文档</a> (CDD) 中详细说明了将被视为与 Android 兼容的具体设备配置。</p> <p>例如，虽然可以将 Android 源代码移植到没有摄像头的手机上，但兼容性定义文档要求所有手机都要有摄像头。该要求使得开发者在编写应用时可以采用一系列一致的功能。</p> <p>兼容性定义文档将会不时进行修订，以反映市场实际情况。例如，1.6 版兼容性定义文档仅支持手机。但 2.1 版兼容性定义文档允许设备不包含电话硬件，这使得平板式音乐播放器等非手机设备也可以是兼容的设备。在修订兼容性定义文档的同时，我们还将改进 Google Play，以便开发者可以控制在哪些地区提供其应用。让我们继续以电话为例，某个用于管理短信的应用在媒体播放器上并没有什么用处，因此 Google Play 允许开发者将该应用限制为专用于手机设备。</p> <h3 id="if-my-device-is-compatible-does-it-automatically-have-access-to-google-play-and-branding">如果我的设备与 Android 兼容，它是否会自动获得 Google Play 和品牌标识的使用权限？</h3> -<p>Google Play 是由 Google 运营的服务。实现兼容性是获得 Google Play 软件和品牌标识使用权限的前提条件。要获得 Google Play 使用权限，设备制造商应发送电子邮件至 <a href="mailto:android-partnerships@google.com">android-partnerships@google.com</a> 与我们联系。虽然我们会阅读发送到该地址的所有电子邮件，但我们无法一一进行回复。请注意，如果我们可以为您提供帮助，将会与您联系。</p> +<p>Google Play 是由 Google 运营的服务。实现兼容性是获得 Google Play 软件和品牌标识使用权限的前提条件。设备制造商应填写<a href="/compatibility/contact-us#for-business-inquiries">申请 Google 移动服务许可</a>中提供的联系表单，以获得 Google Play 使用权限。如果我们可以为您提供帮助，将会与您联系。</p> <h3 id="if-i-am-not-a-manufacturer-how-can-i-get-google-play">如果我不是制造商，如何获得 Google Play 使用权限？</h3> <p>我们只会向在设备中植入 Android 的手机制造商授予 Google Play 使用许可。如有关于具体情况方面的问题，请发送电子邮件至 <a href="mailto:android-partnerships@google.com">android-partnerships@google.com</a> 与我们联系。</p> <h3 id="how-can-i-get-access-to-the-google-apps-for-android-such-as-maps">如何获得 Android 版 Google 应用（例如 Google 地图）使用权限？</h3> @@ -91,7 +91,7 @@ <h3 id="how-much-does-compatibility-certification-cost">兼容性认证的费用是多少？</h3> <p>设备的 Android 兼容性认证无需任何费用。兼容性测试套件为开放源代码，可供任何人用于设备测试。</p> <h3 id="how-long-does-compatibility-take">兼容性认证需要多长时间？</h3> -<p>该过程是自动进行的。兼容性测试套件会生成一份报告，您可以将该报告提供给 Google 来证明兼容性。我们终归打算提供一些用于将这些报告上传到公共数据库的自助服务工具。</p> +<p>该过程是自动进行的。兼容性测试套件会生成一份报告，您可以将该报告提供给 Google 来证明兼容性。我们计划将来提供一些用于将这些报告上传到公共数据库的自助服务工具。</p> <h3 id="who-determines-what-will-be-part-of-the-compatibility-definition">谁负责决定兼容性定义的内容？</h3> <p>由于 Google 负责把握 Android 作为平台和产品的总体发展方向，因此 Google 会为每个版本维护兼容性定义文档。在为 Android 新版本起草兼容性定义文档时，我们会咨询各种原始设备制造商 (OEM)，他们将为该文档的内容提供建议。</p> <h3 id="how-long-will-each-android-version-be-supported-for-new-devices">各 Android 版本可用于开发新设备的时间有多长？</h3> @@ -99,25 +99,25 @@ <h3 id="can-a-device-have-a-different-user-interface-and-still-be-compatible">设备是否可以采用不同的界面但仍保持与 Android 兼容？</h3> <p>Android 兼容性计划旨在决定某种设备是否可以运行第三方应用。设备附带的界面组件（例如主屏幕、拨号器、配色方案等）一般对第三方应用的影响不大。因此，设备制造商可以根据自己的喜好随意定制界面。兼容性定义文档确实规定了原始设备制造商 (OEM) 可在多大程度内更改系统界面中会影响第三方应用的区域。</p> <h3 id="when-are-compatibility-definitions-released-for-new-android-versions">何时发布 Android 新版本的兼容性定义？</h3> -<p>我们的目标是，一旦相应的 Android 平台版本已涵盖足够多的内容，允许发布新版 Android 兼容性定义文档，我们就会进行发布。虽然我们无法在植入相应 Android 软件的首款旗舰设备之前发布该软件版本的兼容性定义文档终稿，但我们一定会在这一首款设备之后发布兼容性定义文档终稿。不过，无论实际情况如何，我们都将提供兼容性定义文档的草稿版本。</p> +<p>我们的目标是，一旦相应的 Android 平台版本已足够成型，允许发布新版 Android 兼容性定义文档，我们就会进行发布。虽然我们无法在植入相应 Android 软件的首款旗舰设备之前发布该软件版本的兼容性定义文档终稿，但我们一定会在这一首款设备之后发布兼容性定义文档终稿。不过，无论实际情况如何，我们都将提供兼容性定义文档的草稿版本。</p> <h3 id="how-are-device-manufacturers-compatibility-claims-validated">如何验证设备制造商的兼容性声明？</h3> <p>我们并没有针对 Android 设备兼容性的验证流程。不过，如果相应设备要添加 Google Play，Google 通常会先验证设备的兼容性，设备通过验证后，才会同意为其授予 Google Play 客户端软件使用许可。</p> <h3 id="what-happens-if-a-device-that-claims-compatibility-is-later-found-to-have-compatibility-problems">如果之后发现声称兼容的设备存在兼容性问题，会怎样？</h3> -<p>通常情况下，Google 与 Google Play 被许可人之间保持着良好的关系，这使得我们可以要求他们发布更新后解决了相关问题的系统映像。</p> +<p>通常情况下，Google 与 Google Play 被许可人之间保持着良好的关系，这使得我们可以要求他们发布经过更新的系统映像以解决相关问题。</p> <a href="#top">返回页首</a> <h2 id="compatibility-test-suite">兼容性测试套件</h2> <h3 id="what-is-the-purpose-of-the-cts">兼容性测试套件的用途是什么？</h3> <p>兼容性测试套件是一种工具，设备制造商可以借助该工具来确保其设备与 Android 兼容，以及报告测试结果供 Google 验证。原始设备制造商 (OEM) 应在整个工程流程中频繁运行兼容性测试套件，以便尽早发现兼容性问题。</p> -<h3 id="what-kinds-of-things-does-the-cts-test">兼容性测试套件会测试哪些类型的内容？</h3> +<h3 id="what-kinds-of-things-does-the-cts-test">兼容性测试套件会测试哪些类型的项目？</h3> <p>目前，兼容性测试套件会测试所有受支持的 Android 强类型 API 是否存在以及行为是否正常。此外，它还会测试其他非 API 系统行为，例如应用生命周期和性能。我们计划在未来的兼容性测试套件版本中扩大支持范围，以便同时测试 Intent 等“软”API。</p> <h3 id="will-the-cts-reports-be-made-public">兼容性测试套件报告会公开吗？</h3> -<p>会。虽然目前尚未实施，但 Google 打算为原始设备制造商 (OEM) 提供基于网络的自助服务工具来发布兼容性测试套件报告，以供任何人查看。制造商可在任意范围内分享兼容性测试套件报告。</p> +<p>会。虽然目前尚未实现，但 Google 打算为原始设备制造商 (OEM) 提供基于网络的自助服务工具来发布兼容性测试套件报告，以供任何人查看。制造商可在任意范围内分享兼容性测试套件报告。</p> <h3 id="how-is-the-cts-licensed">兼容性测试套件采用哪种许可方式？</h3> -<p>兼容性测试套件是根据大多数 Android 使用的 Apache Software License 2.0 授权用户使用。</p> +<p>兼容性测试套件是根据大部分 Android 代码使用的 Apache Software License 2.0 授权用户使用。</p> <h3 id="does-the-cts-accept-contributions">兼容性测试套件接受贡献内容吗？</h3> <p>接受，而且非常欢迎！Android 开放源代码项目接受贡献内容，以便采用与任何其他组件相同的方式来改进兼容性测试套件。事实上，提高兼容性测试套件测试案例的覆盖范围和质量是协助 Android 的最佳方式之一。</p> <h3 id="can-anyone-use-the-cts-on-existing-devices">任何人都可以在现有设备上使用兼容性测试套件吗？</h3> -<p>兼容性定义文档要求与 Android 兼容的设备实施“adb”调试实用工具。这意味着，任何与 Android 兼容的设备（包括零售的设备）都必须能够运行兼容性测试套件测试。</p> +<p>兼容性定义文档要求与 Android 兼容的设备实现“adb”调试实用工具。这意味着，任何与 Android 兼容的设备（包括零售的设备）都必须能够运行兼容性测试套件测试。</p> <h3 id="are-codecs-verified">编解码器需要通过兼容性测试套件验证吗？</h3> <p>需要。所有必需的编解码器都要通过兼容性测试套件验证。</p> |