diff options
Diffstat (limited to 'en/devices/architecture/vndk')
-rw-r--r-- | en/devices/architecture/vndk/abi-stability.html | 937 | ||||
-rw-r--r-- | en/devices/architecture/vndk/build-system.html | 892 | ||||
-rw-r--r-- | en/devices/architecture/vndk/deftool.html | 450 | ||||
-rw-r--r-- | en/devices/architecture/vndk/dir-rules-sepolicy.html | 177 | ||||
-rw-r--r-- | en/devices/architecture/vndk/enabling.html | 189 | ||||
-rw-r--r-- | en/devices/architecture/vndk/extensions.html | 181 | ||||
-rw-r--r-- | en/devices/architecture/vndk/index.html | 400 | ||||
-rw-r--r-- | en/devices/architecture/vndk/linker-namespace.html | 1287 | ||||
-rw-r--r-- | en/devices/architecture/vndk/renderscript.html | 562 | ||||
-rw-r--r-- | en/devices/architecture/vndk/snapshot-design.html | 249 | ||||
-rw-r--r-- | en/devices/architecture/vndk/snapshot-generate.html | 456 |
11 files changed, 0 insertions, 5780 deletions
diff --git a/en/devices/architecture/vndk/abi-stability.html b/en/devices/architecture/vndk/abi-stability.html deleted file mode 100644 index 36c33cd0..00000000 --- a/en/devices/architecture/vndk/abi-stability.html +++ /dev/null @@ -1,937 +0,0 @@ -<html devsite> - <head> - <title>ABI Stability</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - {% include "_versions.html" %} - <!-- - Copyright 2018 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> - Application Binary Interface (ABI) stability is a prerequisite of - framework-only updates because vendor modules may depend on the Vendor Native - Development Kit (VNDK) shared libraries that reside in the system partition. - Newly-built VNDK shared libraries must be ABI-compatible to previously - released VNDK shared libraries so vendor modules can work with those libraries - without recompilation and without runtime errors. -</p> - -<p> - To help ensure ABI compatibility, Android {{ androidPVersionNumber }} includes - a header ABI checker, as described in the following sections. - - -<h2 id="about-vndk-abi-compliance">About VNDK and ABI compliance</h2> - -<p> - The VNDK is a restrictive set of libraries that vendor modules may link to and - which enable framework-only updates. <em>ABI compliance</em> refers to the - ability of a newer version of a shared library to work as expected with a - module that is dynamically linked to it (i.e. works as an older version of the - library would). -</p> - -<h3 id="about-exported-symbols">About exported symbols</h3> - -<p> - An <em>exported symbol</em> (also known as a <em>global symbol</em>) refers to - a symbol that satisfies all of the following: -</p> - -<ul> - <li>Exported by the <em>public headers</em> of a shared library.</li> - <li>Appears in the <code>.dynsym</code> table of the <code>.so</code> file - corresponding to the shared library.</li> - <li>Has WEAK or GLOBAL binding.</li> - <li>Visibility is DEFAULT or PROTECTED.</li> - <li>Section index is not UNDEFINED.</li> - <li>Type is either FUNC or OBJECT.</li> -</ul> - -<p> - The <em>public headers</em> of a shared library are defined as the headers - available to other libraries/binaries through the - <code>export_include_dirs</code>, <code>export_header_lib_headers</code>, - <code>export_static_lib_headers</code>, - <code>export_shared_lib_headers</code>, and - <code>export_generated_headers</code> attributes in <code>Android.bp</code> - definitions of the module corresponding to the shared library. -</p> - -<h3 id="about-reachable-types">About reachable types</h3> - -<p> - A <em>reachable type</em> is any C/C++ built-in or user-defined type that is - reachable directly or indirectly through an exported symbol AND exported - through public headers. For example, <code>libfoo.so</code> has function - <code>Foo</code>, which is an exported symbol found in the - <code>.dynsym</code> table. The <code>libfoo.so</code> library includes the - following: -</p> - -<table> - <tr> - <th>foo_exported.h</th> - <th>foo.private.h</th> - </tr> - <tr> - <td> -<pre class="prettyprint"> -typedef struct foo_private foo_private_t; - -typedef struct foo { - int m1; - int *m2; - foo_private_t *mPfoo; -} foo_t; - -typedef struct bar { - foo_t mfoo; -} bar_t; - -bool Foo(int id, bar_t *bar_ptr); -</pre> -</td> - -<td> -<pre class="prettyprint"> -typedef struct foo_private { - int m1; - float mbar; -} foo_private_t; -</pre> - </td> - </tr> -</table> - -<table> - <tr> - <th>Android.bp</th> - </tr> - <tr> - <td> -<pre class="prettyprint"> -cc_library { - name : libfoo, - vendor_available: true, - vndk { - enabled : true, - } - srcs : ["src/*.cpp"], - export_include_dirs : [ - "include" - ], -} -</pre> - </td> - </tr> -</table> - -<table> - <tr> - <th colspan="8">.dynsym table</th> - </tr> - <tr> - <td><code>Num</code> - </td> - <td><code>Value</code> - </td> - <td><code>Size</code> - </td> - <td><code>Type</code> - </td> - <td><code>Bind</code> - </td> - <td><code>Vis</code> - </td> - <td><code>Ndx</code> - </td> - <td><code>Name</code> - </td> - </tr> - <tr> - <td><code>1</code> - </td> - <td><code>0</code> - </td> - <td><code>0</code> - </td> - <td><code>FUNC</code> - </td> - <td><code>GLOB</code> - </td> - <td><code>DEF</code> - </td> - <td><code>UND</code> - </td> - <td><code>dlerror@libc</code> - </td> - </tr> - <tr> - <td><code>2</code> - </td> - <td><code>1ce0</code> - </td> - <td><code>20</code> - </td> - <td><code>FUNC</code> - </td> - <td><code>GLOB</code> - </td> - <td><code>DEF</code> - </td> - <td><code>12</code> - </td> - <td><code>Foo</code> - </td> - </tr> -</table> - - -<p> - Looking at <code>Foo</code>, direct/indirect reachable types include: -</p> - -<table> - <tr> - <th>Type</th> - <th>Description</th> - </tr> - <tr> - <td><code>bool</code> - </td> - <td>Return type of <code>Foo</code>. - </td> - </tr> - <tr> - <td><code>int</code> - </td> - <td>Type of first <code>Foo</code> parameter. - </td> - </tr> - <tr> - <td><code>bar_t *</code> - </td> - <td>Type of second Foo parameter. By way of <code>bar_t *</code>, - <code>bar_t</code> is exported through <code>foo_exported.h</code>. - <br><br> - <code>bar_t</code> contains a member <code>mfoo</code>, of type - <code>foo_t</code>, which is exported through <code>foo_exported.h</code>, - which results in more types being exported: - - <ul> - <li><code>int :</code> is the type of <code>m1</code>.</li> - <li><code>int * :</code> is the type of <code>m2</code>.</li> - <li><code>foo_private_t * : </code> is the type of <code>mPfoo</code>.</li> - </ul> - <br> - However, <code>foo_private_t</code> is NOT reachable because it is not - exported through <code>foo_exported.h</code>. (<code>foot_private_t *</code> - is opaque, therefore changes made to <code>foo_private_t</code> are allowed.) - </td> - </tr> -</table> - -<p> - A similar explanation can be given for types reachable through base class - specifiers and template parameters as well. -</p> - -<h2 id="ensuring-abi-compliance">Ensuring ABI compliance</h2> - -<p> - ABI compliance must be ensured for the libraries marked - <code>vendor_available: true</code> and <code>vndk.enabled: true</code> in the - corresponding <code>Android.bp</code> files. For example: -</p> - -<pre class="prettyprint"> -cc_library { - name: "libvndk_example", - vendor_available: true, - vndk: { - enabled: true, - } -} -</pre> - -<p> - For data types reachable directly or indirectly by an exported function, the - following changes to a library are classified as ABI-breaking: -</p> - -<table> - <tr> - <th>Data type</th> - <th>Description</th> - </tr> - <tr> - <td>Structures and Classes</td> - <td> - <ul> - <li>Removing non-static data members.</li> - <li>Change resulting in the change of the size of the class/struct.</li> - <li>Change resulting in a change in the v-table layout.</li> - <li>Adding/removing base classes.</li> - <li>Changing the order of base classes.</li> - <li>Change in template arguments.</li> - <li>Change resulting in a change to memory offset of a data - member<sup>**</sup>.</li> - <li>Change in the const-volatile-restricted qualifiers of a - member<sup>*</sup>.</li> - <li>Downgrading the access specifier of a data member<sup>*</sup>.</li> - </ul> - </td> - </tr> - <tr> - <td>Unions</td> - <td> - <ul> - <li>Adding/removing fields.</li> - <li>Change which results in the change in the size.</li> - <li>Changing the order of fields.</li> - <li>Changing field types.</li> - </ul> - </td> - </tr> - <tr> - <td>Enumerations</td> - <td> - <ul> - <li>Changing the value of a member.</li> - <li>Changing the name of a member.</li> - <li>Changing the underlying type.</li> - </ul> - </td> - </tr> - <tr> - <td>Global Symbols</td> - <td> - <ul> - <li>Removing symbols exported by public headers.</li> - <li>For global symbols of type FUNC - <ul> - <li>Adding/removing parameters.</li> - <li>Changing the type of any parameter in any way.</li> - <li>Changing the return type in any way.</li> - <li>Downgrading the access specifier<sup>*</sup>.</li> - </ul> - </li> - <li>For global symbols of type OBJECT - <ul> - <li>Changing the corresponding C/C++ type in any way.</li> - <li>Downgrading the access specifier<sup>*</sup>.</li> - </ul> - </li> - </ul> - </td> - </tr> -</table> - -<p> - <strong><sup>**</sup></strong> Not restricted to changes in offsets of public - fields (as inline functions could use private fields internally). -</p> - -<p> - <strong><sup>*</sup></strong> While these do not represent a change in the - memory layout of the type, they are semantic differences that could lead to - libraries not functioning as expected. -</p> - -<h2 id="using-abi-compliance-tools">Using ABI compliance tools</h2> - -<p> - When a VNDK library is built, the library's ABI is compared with the - corresponding ABI reference for the version of the VNDK being built. Reference - ABI dumps are located in: -</p> - -<pre class="prettyprint"> -${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/(v)ndk/<${PLATFORM_VNDK_VERSION}>/<BINDER_BITNESS>/<ARCH_ARCH-VARIANT>/source-based -</pre> - -<p> - For example, on building <code>libfoo</code> for API level 27 of the VNDK, - <code>libfoo</code>'s inferred ABI is compared with its reference at: -</p> - -<pre class="prettyprint"> -${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/(v)ndk/27/64/<ARCH_ARCH-VARIANT>/source-based/libfoo.so.lsdump -</pre> - -<h3 id="abit-breakage-error">ABI breakage error</h3> - -<p> - On ABI breakages, the build log displays warnings with the warning type and a - path to the abi-diff report. For example, if <code>libbinder</code>'s ABI has - an incompatible change, the build system throws an error with a message - similar to the following: -</p> - -<pre> -***************************************************** -error: VNDK library: libbinder.so's ABI has INCOMPATIBLE CHANGES -Please check compatibility report at: -out/soong/.intermediates/frameworks/native/libs/binder/libbinder/android_arm64_armv8-a_cortex-a73_vendor_shared/libbinder.so.abidiff -****************************************************** ----- Please update abi references by running -platform/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libbinder ---- -</pre> - -<h3 id="building-vndk-lib-abi-checks">Building VNDK library ABI checks</h3> - -<p> - When a VNDK library is built: -</p> - -<ol> - <li><code>header-abi-dumper</code> processes the source files compiled to - build the VNDK library (the library's own source files as well as source files - inherited through static transitive dependencies), to produce - <code>.sdump</code> files that correspond to each source. - <br> - <img src="../images/abi_check_sdump.png" alt="sdump creation" - title="sdump creation"> - <figcaption><strong>Figure 1.</strong> Creating the <code>.sdump</code> - files</figcaption> - </li> - - <li><code>header-abi-linker</code> then processes the <code>.sdump</code> - files (using either a version script provided to it or the <code>.so</code> - file corresponding to the shared library) to produce a <code>.lsdump</code> - file that logs all of the ABI information corresponding to the shared library. - <br> - <img src="../images/abi_check_lsdump.png" alt="lsdump creation" - title="lsdump creation"> - <figcaption><strong>Figure 2.</strong> Creating the <code>.lsdump</code> - file</figcaption> - </li> - - <li><code>header-abi-diff</code> compares the <code>.lsdump</code> - file with a reference <code>.lsdump</code> file to produce a diff report - that outlines the differences in the ABIs of the two libraries. - <br> - <img src="../images/abi_check_abidiff.png" alt="abi diff creation" - title="abi diff creation"> - <figcaption><strong>Figure 3.</strong> Creating the diff report</figcaption> - </li> -</ol> - -<h3 id="header-abi-dumper">header-abi-dumper</h3> - -<p> - The <code>header-abi-dumper</code> tool parses a C/C++ source file and dumps - the ABI inferred from that source file into an intermediate file. The build - system runs <code>header-abi-dumper</code> on all compiled source files while - also building a library that includes the source files from transitive - dependencies. -</p> - -<p> - Currently <code>.sdump</code> files are formatted as - <a href="https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/TextFormat" class="external">Protobuf - TextFormatted</a>, which is not guaranteed to be stable across future - releases. As such, <code>.sdump</code> file formatting should be considered a - build system implementation detail. -</p> - -<p> - For example, <code>libfoo.so</code> has the following source file - <strong><code>foo.cpp</code></strong>: -</p> - -<pre class="prettyprint"> -#include <stdio.h> -#include <foo_exported.h> - -bool Foo(int id, bar_t *bar_ptr) { - if (id > 0 && bar_ptr->mfoo.m1 > 0) { - return true; - } - return false; -}</pre> - - -<p> - You can use <code>header-abi-dumper</code> to generate an intermediate - <code>.sdump</code> file that represents the ABI presented by the source file - using: -</p> - -<pre class="prettyprint"> -$ header-abi-dumper foo.cpp -I exported -o foo.sdump -- -x c++ -</pre> - -<p> - This command tells <code>header-abi-dumper</code> to parse - <code>foo.cpp</code> and emit the ABI information that is exposed in the - public headers in the <code>exported</code> directory. This is an excerpt - (not a complete representation) from <strong><code>foo.sdump</code></strong> - generated by <code>header-abi-dumper</code>: -</p> - -<pre class="prettyprint"> -record_types { - type_info { - name: "foo" - size: 12 - alignment: 4 - referenced_type: "type-1" - source_file: "foo/include/foo_exported.h" - linker_set_key: "foo" - self_type: "type-1" - } - fields { - referenced_type: "type-2" - field_offset: 0 - field_name: "m1" - access: public_access - } - fields { - referenced_type: "type-3" - field_offset: 32 - field_name: "m2" - access: public_access - } - fields { - referenced_type: "type-5" - field_offset: 64 - field_name: "mPfoo" - access: public_access - } - access: public_access - record_kind: struct_kind - tag_info { - unique_id: "_ZTS3foo" - } -} -record_types { - type_info { - name: "bar" - size: 12 - alignment: 4 - referenced_type: "type-6" -… -pointer_types { - type_info { - name: "bar *" - size: 4 - alignment: 4 - referenced_type: "type-6" - source_file: "foo/include/foo_exported.h" - linker_set_key: "bar *" - self_type: "type-8" - } -} -builtin_types { - type_info { - name: "int" - size: 4 - alignment: 4 - referenced_type: "type-2" - source_file: "" - linker_set_key: "int" - self_type: "type-2" - } - is_unsigned: false - is_integral: true -} -functions { - return_type: "type-7" - function_name: "Foo" - source_file: "foo/include/foo_exported.h" - parameters { - referenced_type: "type-2" - default_arg: false - } - parameters { - referenced_type: "type-8" - default_arg: false - } - linker_set_key: "_Z3FooiP3bar" - access: public_access -} -</pre> - - -<p> - <code>foo.sdump</code> contains ABI information exposed by the source file - <code>foo.cpp</code>, e.g.: -</p> - -<ul> - <li><code>record_types</code>. Refer to structs, unions, or classes exposed by - the public headers. Each record type has information about its fields, its - size, access specifier, the header file it was exposed in, etc.</li> - <li><code>pointer_types</code>. Refer to pointer types directly/indirectly - referenced by records/functions exposed by public headers, along with the type - the pointer points to (via the <code>referenced_type</code> field in - <code>type_info</code>). Similar information is logged in the - <code>.sdump</code> file for qualified types, built-in C/C++ types, array - types, and lvalue and rvalue reference types (such logging information about - types allows for recursive diffing).</li> - <li><code>functions</code>. Represent functions exposed by public headers. - They also have information about the function's mangled name, the return type, - the types of the parameters, the access specifier, etc.</li> -</ul> - -<aside class="tip"> - <strong>Tip:</strong> To get help with the <code>header-abi-dumper</code> - tool, run <code>header-abi-dumper --help</code>. -</aside> - -<h3 id="header-abi-linker">header-abi-linker</h3> - -<p> - The <code>header-abi-linker</code> tool takes the intermediate files produced - by <code>header-abi-dumper</code> as input then links those files: -</p> - -<table> - <tr> - <th>Inputs</th> - <td> - <ul> - <li>Intermediate files produced by <code>header-abi-dumper</code></li> - <li>Version script/Map file (optional)</li> - <li>.so file of the shared library</li> - </ul> - </td> - </tr> - <tr> - <th>Output</th> - <td>A file that logs the ABI of a shared library (e.g. - <code>libfoo.so.lsdump </code>represents <code>libfoo</code>'s ABI). - </td> - </tr> -</table> - -<p> - The tool merges the types graphs in all the intermediate files given to it, - taking into account one-definition (user-defined types in different - translation units with the same fully qualified name, might be semantically - different) differences across translation units. The tool then parses either - a version script or the <code>.dynsym</code> table of the shared library - (<code>.so</code> file) to make a list of the exported symbols. -</p> - -<p> - For example, when <code>libfoo</code> adds the <code>bar.cpp</code> file - (which exposes a C function <code>bar</code>) to its compilation, - <code>header-abi-linker</code> could be invoked to create the complete - linked ABI dump of <code>libfoo</code> as follows: -</p> - -<pre class="prettyprint"> -header-abi-linker -I exported foo.sdump bar.sdump \ - -o libfoo.so.lsdump \ - -so libfoo.so \ - -arch arm64 -api current -</pre> - -<p> - Example command output in <strong><code>libfoo.so.lsdump</code></strong>: -</p> - -<pre class="prettyprint"> -record_types { - type_info { - name: "foo" - size: 24 - alignment: 8 - referenced_type: "type-1" - source_file: "foo/include/foo_exported.h" - linker_set_key: "foo" - self_type: "type-1" - } - fields { - referenced_type: "type-2" - field_offset: 0 - field_name: "m1" - access: public_access - } - fields { - referenced_type: "type-3" - field_offset: 64 - field_name: "m2" - access: public_access - } - fields { - referenced_type: "type-4" - field_offset: 128 - field_name: "mPfoo" - access: public_access - } - access: public_access - record_kind: struct_kind - tag_info { - unique_id: "_ZTS3foo" - } -} -record_types { - type_info { - name: "bar" - size: 24 - alignment: 8 -... -builtin_types { - type_info { - name: "void" - size: 0 - alignment: 0 - referenced_type: "type-6" - source_file: "" - linker_set_key: "void" - self_type: "type-6" - } - is_unsigned: false - is_integral: false -} -functions { - return_type: "type-19" - function_name: "Foo" - source_file: "foo/include/foo_exported.h" - parameters { - referenced_type: "type-2" - default_arg: false - } - parameters { - referenced_type: "type-20" - default_arg: false - } - linker_set_key: "_Z3FooiP3bar" - access: public_access -} -functions { - return_type: "type-6" - function_name: "FooBad" - source_file: "foo/include/foo_exported_bad.h" - parameters { - referenced_type: "type-2" - default_arg: false - } -parameters { - referenced_type: "type-7" - default_arg: false - } - linker_set_key: "_Z6FooBadiP3foo" - access: public_access -} -elf_functions { - name: "_Z3FooiP3bar" -} -elf_functions { - name: "_Z6FooBadiP3foo" -} -</pre> - -<p> - The <code>header-abi-linker</code> tool: -</p> - -<ul> - <li>Links the <code>.sdump</code> files provided to it (<code>foo.sdump</code> - and <code>bar.sdump</code>), filtering out the ABI information not present in - the headers residing in the directory: <code>exported</code>.</li> - <li>Parses <code>libfoo.so</code>, and collects information about the symbols - exported by the library through its <code>.dynsym</code> table.</li> - <li>Adds <code>_Z3FooiP3bar</code> and <code>Bar</code>.</li> -</ul> - -<p> - <code>libfoo.so.lsdump</code> is the final generated ABI dump of - <code>libfoo.so</code>. -</p> - -<aside class="tip"><strong>Tip:</strong> To get help with the - <code>header-abi-linker</code> tool, run - <code>header-abi-linker --help</code>. -</aside> - -<h3 id="header-abi-diff">header-abi-diff</h3> - -<p> - The <code>header-abi-diff</code> tool compares two <code>.lsdump</code> files - representing the ABI of two libraries and produces a diff report stating the - differences between the two ABIs. -</p> - -<table> - <tr> - <th>Inputs</th> - <td> - <ul> - <li><code>.lsdump</code> file representing the ABI of an old shared - library.</li> - <li><code>.lsdump</code> file representing the ABI of a new shared library. - </li> - </ul> - </td> - </tr> - <tr> - <th>Output</th> - <td>A diff report stating the differences in the ABIs offered by the two - shared libraries compared. - </td> - </tr> -</table> - -<p> - The ABI diff file is designed to be as verbose and readable as possible. The - format is subject to change in future releases. For example, you have two - versions of <code>libfoo</code>: <code>libfoo_old.so</code> and - <code>libfoo_new.so</code>. In <code>libfoo_new.so</code>, in - <code>bar_t</code>, you change the type of <code>mfoo</code> from - <code>foo_t</code> to <code>foo_t *</code>. Since <code>bar_t</code> is a - directly reachable type, this should be flagged as an ABI breaking change by - <code>header-abi-diff</code>. -</p> - -<p> - To run <code>header-abi-diff</code>: -</p> - -<pre class="prettyprint"> -header-abi-diff -old libfoo_old.so.lsdump \ - -new libfoo_new.so.lsdump \ - -arch arm64 \ - -o libfoo.so.abidiff \ - -lib libfoo -</pre> - -<p> - Example command output in <strong><code>libfoo.so.abidiff</code></strong>: -</p> - -<pre class="prettyprint"> -lib_name: "libfoo" -arch: "arm64" -record_type_diffs { - name: "bar" - type_stack: "Foo-> bar *->bar " - type_info_diff { - old_type_info { - size: 24 - alignment: 8 - } - new_type_info { - size: 8 - alignment: 8 - } - } - fields_diff { - old_field { - referenced_type: "foo" - field_offset: 0 - field_name: "mfoo" - access: public_access - } - new_field { - referenced_type: "foo *" - field_offset: 0 - field_name: "mfoo" - access: public_access - } - } -}</pre> - - -<p> - The <code>libfoo.so.abidiff</code> contains a report of all ABI breaking - changes in <code>libfoo</code>. The <code>record_type_diffs</code> message - indicates a record has changed and lists the incompatible changes, which - include: -</p> - -<ul> - <li>The size of the record changing from <code>24</code> bytes to - <code>8</code> bytes.</li> - <li>The field type of <code>mfoo</code> changing from <code>foo</code> to - <code>foo *</code> (all typedefs are stripped off).</li> -</ul> - -<p> - The <code>type_stack</code> field indicates how <code>header-abi-diff</code> - reached the type that changed (<code>bar</code>). This field may be - interpreted as <code>Foo</code> is an exported function that takes in - <code>bar *</code> as parameter, that points to <code>bar</code>, which was - exported and changed. -</p> - -<aside class="tip"> - <strong>Tip:</strong> To get help with the <code>header-abi-diff</code> tool, - run <code>header-abi-diff --help</code>. You can also refer to - <code>development/vndk/tools/header-checker/README.md</code>. -</aside> - -<h2 id="enforcing-abi-api">Enforcing ABI/API</h2> - -<p> - To enforce the ABI/API of VNDK and LLNDK shared libraries, ABI references must - be checked into <code>${ANDROID_BUILD_TOP}/prebuilts/abi-dumps/(v)ndk/</code>. - To create these references, run the following command: -</p> - -<pre class="prettyprint"> -${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -</pre> - -<p> - After creating the references, any change made to the source code that results - in an incompatible ABI/API change in a VNDK or LLNDK library now results in a - build error. -</p> - -<p> - To update ABI references for specific VNDK core libraries, run the following - command: -</p> - -<pre class="prettyprint"> -${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l <lib1> -l <lib2> -</pre> - -<p> - For example, to update <code>libbinder</code> ABI references, run: -</p> - -<pre class="prettyprint"> -${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libbinder -</pre> - -<p> - To update ABI references for specific LLNDK libraries, run the following - command: -</p> - -<pre class="prettyprint"> -${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l <lib1> -l <lib2> --llndk -</pre> - -<p> - For example, to update <code>libm</code> ABI references, run: -</p> - -<pre class="prettyprint"> -${ANDROID_BUILD_TOP}/development/vndk/tools/header-checker/utils/create_reference_dumps.py -l libm --llndk -</pre> - - -</body> -</html>
\ No newline at end of file diff --git a/en/devices/architecture/vndk/build-system.html b/en/devices/architecture/vndk/build-system.html deleted file mode 100644 index 98e95b63..00000000 --- a/en/devices/architecture/vndk/build-system.html +++ /dev/null @@ -1,892 +0,0 @@ -<html devsite> - <head> - <title>VNDK Build System Support</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> - In Android 8.1 and higher, the build system has built-in VNDK support. When - VNDK support is enabled, the build system checks the dependencies between - modules, builds a vendor-specific variant for vendor modules, and - automatically installs those modules into designated directories. -</p> - -<h2 id=vndk-build-support-example>VNDK build support example</h2> - -<p> - In this example, the <code>Android.bp</code> module definition defines a - library named <code>libexample</code>. The <code>vendor_available</code> - property indicates framework modules and vendor modules may depend on - <code>libexample</code>: -</p> - -<p> - <img src="../images/treble_vndk_androidbp.png" alt="libexample vendor_available:true and vndk.enabled:true" /> -</p> -<figcaption> - <strong>Figure 1.</strong> VNDK support enabled -</figcaption> - -<p> - Both the framework executable <code>/system/bin/foo</code> and the vendor - executable <code>/vendor/bin/bar</code> depend on <code>libexample</code> and - have <code>libexample</code> in their <code>shared_libs</code> properties. -</p> - -<p> - If <code>libexample</code> is used by both framework modules and vendor - modules, two variants of <code>libexample</code> are built. The core variant - (named after <code>libexample</code>) is used by framework modules and the - vendor variant (named after <code>libexample.vendor</code>) is used by vendor - modules. The two variants are installed into different directories: -</p> - -<ul> - <li>The core variant is installed into - <code>/system/lib[64]/libexample.so</code>.</li> - <li>The vendor variant is installed into - <code>/system/lib[64]/vndk/libexample.so</code> because - <code>vndk.enabled</code> is <code>true</code>.</li> -</ul> - -<p> - For more details, see <a href="#module-definition">Module definition</a>. -</p> - -<h2 id="configuring-build-support">Configuring build support</h2> - -<p> - To enable full build system support for a product device, add - <code>BOARD_VNDK_VERSION</code> to <code>BoardConfig.mk</code>: -</p> - -<pre class="prettyprint">BOARD_VNDK_VERSION := current</pre> - -<p> - This setting has a <strong>global</strong> effect: When defined in - <code>BoardConfig.mk</code>, all modules are checked. As there is no mechanism - to blacklist or whitelist an offending module, you should clean all - unnecessary dependencies before adding <code>BOARD_VNDK_VERSION</code>. You - can test and compile a module by setting <code>BOARD_VNDK_VERSION</code> in - your environment variables: -</p> - -<pre class="prettyprint">$ BOARD_VNDK_VERSION=current m module_name.vendor</pre> - -<p>When <code>BOARD_VNDK_VERSION</code> is enabled, several default global - header search paths are <em>removed</em>. These include: -</p> - -<ul> - <li><code>frameworks/av/include</code></li> - <li><code>frameworks/native/include</code></li> - <li><code>frameworks/native/opengl/include</code></li> - <li><code>hardware/libhardware/include</code></li> - <li><code>hardware/libhardware_legacy/include</code></li> - <li><code>hardware/ril/include</code></li> - <li><code>libnativehelper/include</code></li> - <li><code>libnativehelper/include_deprecated</code></li> - <li><code>system/core/include</code></li> - <li><code>system/media/audio/include</code></li> -</ul> - -<p> - If a module depends on the headers from these directories, you must specify - (explicitly) the dependencies with <code>header_libs</code>, - <code>static_libs</code>, and/or <code>shared_libs</code>. -</p> - -<h2 id="module-definition">Module definition</h2> - -<p> - To build Android with <code>BOARD_VNDK_VERSION</code>, you must revise the - module definition in either <code>Android.mk</code> or - <code>Android.bp</code>. This section describes different kinds of module - definitions, several VNDK-related module properties, and dependency checks - implemented in the build system. -</p> - -<h3 id="vendor-modules">Vendor modules</h3> - -<p> - Vendor modules are vendor-specific executables or shared libraries that - must be installed into a vendor partition. In <code>Android.bp</code> files, - vendor modules must set vendor or proprietary property to <code>true</code>. - In <code>Android.mk</code> files, vendor modules must set - <code>LOCAL_VENDOR_MODULE</code> or <code>LOCAL_PROPRIETARY_MODULE</code> to - <code>true</code>. -</p> - -<p> - If <code>BOARD_VNDK_VERSION</code> is defined, the build system disallows - dependencies between vendor modules and framework modules and emits errors if: -</p> - -<ul> - <li>a module without <code>vendor:true</code> depends on a module with - <code>vendor:true</code>, or</li> - <li>a module with <code>vendor:true</code> depends on a - non-<code>llndk_library</code> module that has neither - <code>vendor:true</code> nor <code>vendor_available:true</code>.</li> -</ul> - -<p> - The dependency check applies to <code>header_libs</code>, - <code>static_libs</code>, and <code>shared_libs</code> in - <code>Android.bp</code>, and to <code>LOCAL_HEADER_LIBRARIES</code>, - <code>LOCAL_STATIC_LIBRARIES</code> and <code>LOCAL_SHARED_LIBRARIES</code> in - <code>Android.mk</code>. -</p> - -<h3 id="ll-ndk">LL-NDK</h3> - -<p> - LL-NDK shared libraries are shared libraries with stable ABIs. Both framework - and vendor modules share the same and the latest implementation. For each - LL-NDK shared library, <code>Android.bp</code> contains a - <code>llndk_library</code> module definition: -</p> - -<pre class="prettyprint"> -llndk_library { - name: "libvndksupport", - symbol_file: "libvndksupport.map.txt", -} -</pre> - -<p> - This module definition specifies a module name and a symbol file that - describes the symbols visible to vendor modules. For example: -</p> - -<pre class="prettyprint"> -LIBVNDKSUPPORT { - global: - android_load_sphal_library; # vndk - android_unload_sphal_library; # vndk - local: - *; -}; -</pre> - -<p> - Based on the symbol file, the build system generates a stub shared library for - vendor modules, which link with these libraries when - <code>BOARD_VNDK_VERSION</code> is enabled. A symbol is included in the stub - shared library only if it: -</p> - -<ul> - <li>Is not defined in the section end with <code>_PRIVATE</code> or - <code>_PLATFORM</code>,</li> - <li>Does not have <code>#platform-only</code> tag, and</li> - <li>Does not have <code>#introduce*</code> tags or the tag matches with the - target.</li> -</ul> - -<aside class="note"> - <strong>Note</strong>: Vendors must not define their own LL-NDK shared - libraries because vendor modules won't be able to find them in - <a href="/setup/build/gsi">Generic System Image (GSI)</a>. -</aside> - -<h3 id="vndk">VNDK</h3> - -<p> - In <code>Android.bp</code> files, <code>cc_library</code>, - <code>cc_library_static</code>, <code>cc_library_shared</code>, and - <code>cc_library_headers</code> module definitions support three VNDK-related - properties: <code>vendor_available</code>, <code>vndk.enabled</code>, and - <code>vndk.support_system_process</code>. -</p> - -<p> - If <code>vendor_available</code> or <code>vndk.enabled</code> is - <code>true</code>, two variants (<em>core</em> and <em>vendor</em>) may be - built. The core variant should be treated as a framework module and the vendor - variant should be treated as a vendor module. If some framework modules depend - on this module, the core variant is built. If some vendor modules - depend on this module, the vendor variant is built. The build system enforces - the following dependency checks: -</p> - -<ul> - <li>The core variant is always framework-only and inaccessible to vendor - modules.</li> - <li>The vendor variant is always inaccessible to framework modules.</li> - <li>All dependencies of the vendor variant, which are specified in - <code>header_libs</code>, <code>static_libs</code>, and/or - <code>shared_libs</code>, must be either an <code>llndk_library</code> or a - module with <code>vendor_available</code> or <code>vndk.enabled</code>.</li> - <li>If <code>vendor_available</code> is <code>true</code>, the vendor variant - is accessible to all vendor modules.</li> - <li>If <code>vendor_available</code> is <code>false</code>, the vendor variant - is accessible only to other VNDK or VNDK-SP modules (i.e., modules with - <code>vendor:true</code> cannot link <code>vendor_available:false</code> - modules).</li> -</ul> - -<p> - The default installation path for <code>cc_library</code> or - <code>cc_library_shared</code> is determined by the following rules: -</p> - -<ul> - <li>The core variant is installed to <code>/system/lib[64]</code>.</li> - <li>The vendor variant installation path may vary: - <ul> - <li>If <code>vndk.enabled</code> is <code>false</code>, the vendor variant - is installed into <code>/vendor/lib[64]</code>.</li> - <li>If <code>vndk.enabled</code> is <code>true</code>, - <code>vndk.support_system_process</code> can be either <code>true</code> or - <code>false</code>. If: - <ul> - <li><code>false</code>, the vendor variant is installed into - <code>/system/lib[64]/vndk-${VER}</code>.</li> - <li><code>true</code>, the vendor variant is installed to - <code>/system/lib[64]/vndk-sp-${VER}</code>.</li> - </ul> - </li> - </ul> - </li> -</ul> - -<p> - The table below summarizes how the build system handles the vendor variants: -</p> -<table> - <tr> - <th>vendor_available</th> - <th style="text-align: center">vndk<br>enabled</th> - <th style="text-align: center">vndk<br>support_same_process</th> - <th>Vendor variant descriptions</th> - </tr> - - <tr> - <td rowspan="4"><code>true</code></td> - <td rowspan="2"><code>false</code></td> - <td><code>false</code></td> - <td>The vendor variants are <em>VND-ONLY</em>. Shared libraries are - installed into <code>/vendor/lib[64]</code>.</td> - </tr> - - <tr> - <td><code>true</code></td> - <td><em>Invalid</em> (Build error)</td> - </tr> - - <tr> - <td rowspan="2"><code>true</code></td> - <td><code>false</code></td> - <td>The vendor variants are <em>VNDK</em>. Shared libraries are installed - to <code>/system/lib[64]/vndk-${VER}</code>.</td> - </tr> - - <tr> - <td><code>true</code></td> - <td>The vendor variants are <em>VNDK-SP</em>. Shared libraries are - installed to <code>/system/lib[64]/vndk-sp-${VER}</code>.</td> - </tr> - - <tr> - <td rowspan="4"><p><code>false</code></p></td> - <td rowspan="2"><p><code>false</code></p></td> - <td><p><code>false</code></p></td> - <td><p>No vendor variants. This module is <em>FWK-ONLY</em>.</p></td> - </tr> - - <tr> - <td><code>true</code></td> - <td><em>Invalid</em> (Build error)</td> - </tr> - - <tr> - <td rowspan="2"><code>true</code></td> - <td><code>false</code></td> - <td>The vendor variants are <em>VNDK-Private</em>. Shared libraries are - installed to <code>/system/lib[64]/vndk-${VER}</code>.These must not be - directly used by vendor modules.</td> - </tr> - - <tr> - <td><code>true</code></td> - <td>The vendor variants are <em>VNDK-SP-Private</em>. Shared libraries are - installed to <code>/system/lib[64]/vndk-sp-${VER}</code>. These must not be - directly used by vendor modules.</td> - </tr> -</table> - -<aside class="note"> - <strong>Note</strong>: Vendors may set <code>vendor_available</code> to their - modules but must not set <code>vndk.enabled</code> or - <code>vndk.support_system_process</code> because the modules won't be able - to find them in the <a href="/setup/build/gsi">Generic System Image (GSI)</a>. -</aside> - -<h3 id="vndk-extensions">VNDK extensions</h3> - -<p> - VNDK extensions are VNDK shared libraries with additional APIs. Extensions are - installed to <code>/vendor/lib[64]/vndk[-sp]</code> (without version suffix) - and override the original VNDK shared libraries at runtime. -</p> - -<h4 id="defining-vndk-extensions">Defining VNDK extensions</h4> - -<p> - In Android 9 and higher, <code>Android.bp</code> natively supports VNDK - extensions. To build a VNDK extension, define another module with a - <code>vendor:true</code> and an <code>extends</code> property: -</p> - -<pre class="prettyprint"> -cc_library { - name: "libvndk", - vendor_available: true, - vndk: { - enabled: true, - }, -} - -cc_library { - name: "libvndk_ext", - vendor: true, - vndk: { - enabled: true, - extends: "libvndk", - }, -} -</pre> - -<p> - A module with <code>vendor:true</code>, <code>vndk.enabled:true</code>, and - <code>extends</code> properties defines the VNDK extension:</p> - -<ul> - <li>The <code>extends</code> property must specify a base VNDK shared library - name (or VNDK-SP shared library name).</li> - <li>VNDK extensions (or VNDK-SP extensions) are named after the base module - names from which they extend. For example, the output binary of - <code>libvndk_ext</code> is <code>libvndk.so</code> instead of - <code>libvndk_ext.so</code>.</li> - <li>VNDK extensions are installed into <code>/vendor/lib[64]/vndk</code>.</li> - <li>VNDK-SP extensions are installed into - <code>/vendor/lib[64]/vndk-sp</code>.</li> - <li>The base shared libraries must have both <code>vndk.enabled:true</code> - and <code>vendor_available:true</code>.</li> -</ul> - -<p> - A VNDK-SP extension must extend from a VNDK-SP shared library - (<code>vndk.support_system_process</code> must be equal): -</p> - -<pre class="prettyprint"> -cc_library { - name: "libvndk_sp", - vendor_available: true, - vndk: { - enabled: true, - support_system_process: true, - }, -} - -cc_library { - name: "libvndk_sp_ext", - vendor: true, - vndk: { - enabled: true, - extends: "libvndk_sp", - support_system_process: true, - }, -} -</pre> - -<p> - VNDK extensions (or VNDK-SP extensions) may depend on other vendor shared - libraries: -</p> - -<pre class="prettyprint"> -cc_library { - name: "libvndk", - vendor_available: true, - vndk: { - enabled: true, - }, -} - -cc_library { - name: "libvndk_ext", - vendor: true, - vndk: { - enabled: true, - extends: "libvndk", - }, - shared_libs: [ - "libvendor", - ], -} - -cc_library { - name: "libvendor", - vendor: true, -} -</pre> - -<aside class="note"> - <strong>Note:</strong> Similar to SP-HAL-Dep, VNDK-SP extensions and their - dependencies (including vendor libraries) must be labeled as - <code>same_process_hal_file</code> in sepolicy. -</aside> - -<h4 id="using-vndk-extensions">Using VNDK extensions</h4> - -<p> - If a vendor module depends on additional APIs defined by VNDK extensions, the - module must specify the name of the VNDK extension in its - <code>shared_libs</code> property: -</p> - -<pre class="prettyprint"> -// A vendor shared library example -cc_library { - name: "libvendor", - vendor: true, - shared_libs: [ - "libvndk_ext", - ], -} - -// A vendor executable example -cc_binary { - name: "vendor-example", - vendor: true, - shared_libs: [ - "libvndk_ext", - ], -} -</pre> - -<p> - If a vendor module depends on VNDK extensions, those VNDK extensions are - installed to <code>/vendor/lib[64]/vndk[-sp]</code> automatically. If a module - no longer depends on a VNDK extension, add a clean step to - <code>CleanSpec.mk</code> to remove the shared library. For example: -</p> - -<pre class="prettyprint"> -$(call add-clean-step, rm -rf $(TARGET_OUT_VENDOR)/lib/libvndk.so) -</pre> - -<h3 id="conditional-compilation">Conditional compilation</h3> - -<p> - This section describes how to deal with the <em>subtle differences</em> (e.g. - adding or removing a feature from one of the variants) between the following - three VNDK shared libraries: -</p> - -<ul> - <li>Core variant (e.g. <code>/system/lib[64]/libexample.so</code>)</li> - <li>Vendor variant (e.g. - <code>/system/lib[64]/vndk[-sp]-${VER}/libexample.so</code>)</li> - <li>VNDK extension (e.g. <code>/vendor/lib[64]/vndk[-sp]/libexample.so</code>) - </li> -</ul> - - -<h4 id="conditional-cflags">Conditional compiler flags</h4> - -<p> - The Android build system defines <code>__ANDROID_VNDK__</code> for vendor - variants and VNDK extensions by default. You may guard the code - with the C preprocessor guards: -</p> - -<pre class="prettyprint"> -void all() { } - -#if !defined(__ANDROID_VNDK__) -void framework_only() { } -#endif - -#if defined(__ANDROID_VNDK__) -void vndk_only() { } -#endif -</pre> - -<p> - In addition to <code>__ANDROID_VNDK__</code>, different <code>cflags</code> or - <code>cppflags</code> may be specified in <code>Android.bp</code>. The - <code>cflags</code> or <code>cppflags</code> specified in - <code>target.vendor</code> is specific to the vendor variant. -</p> - -<p> - For example, the following <code>Android.bp</code> defines - <code>libexample</code> and <code>libexample_ext</code>: -</p> - -<pre class="prettyprint"> -cc_library { - name: "libexample", - srcs: ["src/example.c"], - vendor_available: true, - vndk: { - enabled: true, - }, - target: { - vendor: { - cflags: ["-DLIBEXAMPLE_ENABLE_VNDK=1"], - }, - }, -} - -cc_library { - name: "libexample_ext", - srcs: ["src/example.c"], - vendor: true, - vndk: { - enabled: true, - extends: "libexample", - }, - cflags: [ - "-DLIBEXAMPLE_ENABLE_VNDK=1", - "-DLIBEXAMPLE_ENABLE_VNDK_EXT=1", - ], -} -</pre> - -<p> - And this is the code listing of <code>src/example.c</code>: -</p> - -<pre class="prettyprint"> -void all() { } - -#if !defined(LIBEXAMPLE_ENABLE_VNDK) -void framework_only() { } -#endif - -#if defined(LIBEXAMPLE_ENABLE_VNDK) -void vndk() { } -#endif - -#if defined(LIBEXAMPLE_ENABLE_VNDK_EXT) -void vndk_ext() { } -#endif -</pre> - -<p> - According to these two files, the build system generates shared libraries - with following exported symbols: -</p> - -<table> - <tr> - <th>Installation path</th> - <th>Exported symbols</th> - </tr> - - <tr> - <td><code>/system/lib[64]/libexample.so</code></td> - <td><code>all</code>, <code>framework_only</code></td> - </tr> - - <tr> - <td><code>/system/lib[64]/vndk-${VER}/libexample.so</code></td> - <td><code>all</code>, <code>vndk</code></td> - </tr> - - <tr> - <td><code>/vendor/lib[64]/vndk/libexample.so</code></td> - <td><code>all</code>, <code>vndk</code>, <code>vndk_ext</code></td> - </tr> -</table> - - -<h4 id="exported-symbols">Requirements on the exported symbols</h4> - -<p> - The <a href="/devices/architecture/vndk/abi-stability">VNDK ABI checker</a> - compares the ABI of <em>VNDK vendor variants</em> and - <em>VNDK extensions</em> to the reference ABI dumps under - <code>prebuilts/abi-dumps/vndk</code>. -</p> - -<ul> - <li>Symbols exported by <em>VNDK vendor variants</em> (e.g. - <code>/system/lib[64]/vndk-${VER}/libexample.so</code>) must be identical - to (not the supersets of) the symbols defined in ABI dumps.</li> - - <li>Symbols exported by <em>VNDK extensions</em> (e.g. - <code>/vendor/lib[64]/vndk/libexample.so</code>) must be supersets of the - symbols defined in ABI dumps.</li> -</ul> - -<p> - If <em>VNDK vendor variants</em> or <em>VNDK extensions</em> fail to follow - the requirements above, VNDK ABI checker emits build errors and stops the - build. -</p> - - -<h4 id="excluding">Excluding source files or shared libraries from vendor variants</h4> - -<p> - To exclude source files from the vendor variant, add them to the - <code>exclude_srcs</code> property. Similarly, to ensure shared libraries are - not linked with the vendor variant, add those libraries to the - <code>exclude_shared_libs</code> property. For example: -</p> - -<pre class="prettyprint"> -cc_library { - name: "libexample_cond_exclude", - srcs: ["fwk.c", "both.c"], - shared_libs: ["libfwk_only", "libboth"], - target: { - vendor: { - exclude_srcs: ["fwk.c"], - exclude_shared_libs: ["libfwk_only"], - }, - }, -} -</pre> - -<p> - In this example, the core variant of <code>libexample_cond_exclude</code> - includes the code from <code>fwk.c</code> and <code>both.c</code> and depends - on the shared libraries <code>libfwk_only</code> and <code>libboth</code>. The - vendor variant of <code>libexample_cond_exclude</code> includes only the code - from <code>both.c</code> because <code>fwk.c</code> is excluded by the - <code>exclude_srcs</code> property. Similarly, - <code>libexample_cond_exclude</code> depends only on the shared library - <code>libboth</code> because <code>libfwk_only</code> is excluded by the - <code>exclude_shared_libs</code> property. -</p> - -<h4 id="export-headers-from-vndk-extension">Export headers from VNDK extensions</h4> - -<p> - A VNDK extension may add new classes or new functions to a VNDK shared - library. It is suggested to keep those declarations in independent headers - and avoid changing the existing headers. -</p> - -<p> - For example, a new header file - <code>include-ext/example/ext/feature_name.h</code> is created for the VNDK - extension <code>libexample_ext</code>: -</p> - -<ul> - <li>Android.bp</li> - <li><strong>include-ext/example/ext/feature_name.h</strong></li> - <li>include/example/example.h</li> - <li>src/example.c</li> - <li><strong>src/ext/feature_name.c</strong></li> -</ul> - -<p> - In the following <code>Android.bp</code>, <code>libexample</code> exports - only <code>include</code>, whereas <code>libexample_ext</code> exports both - <code>include</code> and <code>include-ext</code>. This ensures - <code>feature_name.h</code> won't be incorrectly included by the users of - <code>libexample</code>: -</p> - -<pre class="prettyprint"> -cc_library { - name: "libexample", - srcs: ["src/example.c"], - export_include_dirs: ["include"], - vendor_available: true, - vndk: { - enabled: true, - }, -} - -cc_library { - name: "libexample_ext", - srcs: [ - "src/example.c", - "src/ext/feature_name.c", - ], - export_include_dirs: [ - "include", - "include-ext", - ], - vendor: true, - vndk: { - enabled: true, - extends: "libexample", - }, -} -</pre> - -<p> - If separating extensions to independent header files is not feasible, an - alternative is to add <code>#ifdef</code> guards. However, make sure that all - VNDK extension users add the define flags. You may define - <code>cc_defaults</code> to add define flags to <code>cflags</code> and link - shared libraries with <code>shared_libs</code>. -</p> - -<p> - For example, to add a new member function <code>Example2::get_b()</code> to - the VNDK extension <code>libexample2_ext</code>, you must modify the existing - header file and add a <code>#ifdef</code> guard: -</p> - -<pre class="prettyprint"> -#ifndef LIBEXAMPLE2_EXAMPLE_H_ -#define LIBEXAMPLE2_EXAMPLE_H_ - -class Example2 { - public: - Example2(); - - void get_a(); - -#ifdef LIBEXAMPLE2_ENABLE_VNDK_EXT - void get_b(); -#endif - - private: - void *impl_; -}; - -#endif // LIBEXAMPLE2_EXAMPLE_H_ -</pre> - -<p> - A <code>cc_defaults</code> named <code>libexample2_ext_defaults</code> is - defined for the users of <code>libexample2_ext</code>: -</p> - -<pre class="prettyprint"> -cc_library { - name: "libexample2", - srcs: ["src/example2.cpp"], - export_include_dirs: ["include"], - vendor_available: true, - vndk: { - enabled: true, - }, -} - -cc_library { - name: "libexample2_ext", - srcs: ["src/example2.cpp"], - export_include_dirs: ["include"], - vendor: true, - vndk: { - enabled: true, - extends: "libexample2", - }, - cflags: [ - "-DLIBEXAMPLE2_ENABLE_VNDK_EXT=1", - ], -} - -cc_defaults { - name: "libexample2_ext_defaults", - shared_libs: [ - "libexample2_ext", - ], - cflags: [ - "-DLIBEXAMPLE2_ENABLE_VNDK_EXT=1", - ], -} -</pre> - -<p> - The users of <code>libexample2_ext</code> may simply include - <code>libexample2_ext_defaults</code> in their <code>defaults</code> - property: -</p> - -<pre class="prettyprint"> -cc_binary { - name: "example2_user_executable", - defaults: ["libexample2_ext_defaults"], - vendor: true, -} -</pre> - - - -<h3 id="product-packages">Product packages</h3> - -<p> - In the Android build system, the variable <code>PRODUCT_PACKAGES</code> - specifies the executables, shared libraries, or packages that should be - installed into the device. The transitive dependencies of the specified - modules are implicitly installed into the device as well. -</p> - -<p> - If <code>BOARD_VNDK_VERSION</code> is enabled, modules with - <code>vendor_available</code> or <code>vndk.enabled</code> get special - treatment. If a framework module depends on a module with - <code>vendor_available</code> or <code>vndk.enabled</code>, the core variant - is included in the transitive installation set. Similarly, if a vendor module - depends on a module with <code>vendor_available</code> or - <code>vndk.enabled</code>, the vendor variant is included in the transitive - installation set. -</p> - -<p> - When the dependencies are invisible to the build system (e.g. shared libraries - that may be opened with <code>dlopen()</code> in runtime), you should specify - the module names in <code>PRODUCT_PACKAGES</code> to install those modules - explicitly. -</p> - -<p> - If a module has <code>vendor_available</code> or <code>vndk.enabled</code>, - the module name stands for its core variant. To explicitly specify the - vendor variant in <code>PRODUCT_PACKAGES</code>, append a <code>.vendor</code> - suffix to the module name. For example: -</p> - -<pre class="prettyprint"> -cc_library { - name: "libexample", - srcs: ["example.c"], - vendor_available: true, -} -</pre> - -<p> - In this example, <code>libexample</code> stands for - <code>/system/lib[64]/libexample.so</code> and <code>libexample.vendor</code> - stands for <code>/vendor/lib[64]/libexample.so</code>. To install - <code>/vendor/lib[64]/libexample.so</code>, add <code>libexample.vendor</code> - to <code>PRODUCT_PACKAGES</code>: -</p> - -<pre class="prettyprint">PRODUCT_PACKAGES += libexample.vendor</pre> - - </body> -</html> diff --git a/en/devices/architecture/vndk/deftool.html b/en/devices/architecture/vndk/deftool.html deleted file mode 100644 index 29499045..00000000 --- a/en/devices/architecture/vndk/deftool.html +++ /dev/null @@ -1,450 +0,0 @@ -<html devsite> - <head> - <title>VNDK Definition Tool</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>The VNDK definition tool helps vendors migrate their source tree to an -Android 8.0 environment. This tool scans binary files in the system and vendor -images then resolves dependencies. Based on the module dependency graph, the -tool can also detect violations to VNDK concepts and provide -insight/suggestions for moving modules between partitions. If an Generic System -Image (GSI) is specified, the VNDK definition tool can compare your system -image with the GSI and determine the extended libraries.</p> - -<p>This section covers three frequently used commands for the VNDK definition -tool:</p> - -<ul> - <li><code>vndk</code>. Compute VNDK_SP_LIBRARIES, VNDK_SP_EXT_LIBRARIES, and - EXTRA_VENDOR_LIBRARIES for build system workaround in Android 8.0 and - higher.</li> - - <li><code>check-dep</code>. Check the violating module dependencies from - vendor modules to non-eligible framework shared libraries.</li> - - <li><code>deps</code>. Print the dependencies between the shared libraries and - executables.</li> -</ul> - -<p>For more details on advanced command usage, refer to -<a href="https://android.googlesource.com/platform/development/+/master/vndk/tools/definition-tool/README.md" class="external">README.md</a> -file in the VNDK Definition Tool repository.</p> - - - - - -<h2 id="vndk">vndk</h2> - -<p>The <code>vndk</code> subcommand loads the shared libraries and executables -from the system partition and vendor partitions, then resolves module -dependencies to determine the libraries that must be copied to -<code>/system/lib[64]/vndk-sp-${VER}</code> and <code>/vendor/lib[64]</code>. -Options for the <code>vndk</code> subcommand include:</p> - -<table> - <tr> - <th>Option</th> - <th>Description</th> - </tr> - - <tr> - <td><code>--system</code></td> - <td>Point to a directory containing the files that will reside in the system - partition.</td> - </tr> - - <tr> - <td><code>--vendor</code></td> - <td>Point to a directory containing the files that will reside in a vendor - partition.</td> - </tr> - - <tr> - <td><code>--aosp-system</code></td> - <td>Point to a directory containing the files that will reside in the Generic - System Image (GSI).</td> - </tr> - - <tr> - <td><code>--load-extra-deps</code></td> - <td>Point to a file that describes the implicit dependencies, such as - <code>dlopen()</code>.</td> - </tr> -</table> - -<p>For example, to compute the VNDK library sets, run the following -<code>vndk</code> subcommand:</p> - -<pre class="prettyprint"> -<code class="devsite-terminal">./vndk_definition_tool.py vndk \</code> - --system ${ANDROID_PRODUCT_OUT}/system \ - --vendor ${ANDROID_PRODUCT_OUT}/vendor \ - --aosp-system ${ANDROID_PRODUCT_OUT}/../generic_arm64_ab/system\ - --load-extra-deps dlopen.dep -</pre> - -<p>Specify extra dependencies with a simple file format. Each line represents a -relationship, with the file before the colon depending on the file after the -colon. For example:</p> - -<pre class="prettyprint">/system/lib/libart.so: /system/lib/libart-compiler.so</pre> - -<p>This line lets the VNDK definition tool know that <code>libart.so</code> -depends on <code>libart-compiler.so</code>.</p> - - - -<h3 id="installation-destination">Installation destination</h3> - -<p>VNDK definition tool lists libraries and corresponding install directories -for the following categories:</p> - -<table> - <tr> - <th>Category</th> - <th>Directory</th> - </tr> - - <tr> - <td>vndk_sp</td> - <td>Must install to <code>/system/lib[64]/vndk-sp-${VER}</code></td> - </tr> - - <tr> - <td>vndk_sp_ext</td> - <td>Must install to <code>/vendor/lib[64]/vndk-sp</code></td> - </tr> - - <tr> - <td>extra_vendor_libs</td> - <td>Must install to <code>/vendor/lib[64]</code></td> - </tr> -</table> - - - -<h3 id="build-system-templates">Build system templates</h3> - -<p>After gathering outputs from VNDK definition tool, a vendor can create an -<code>Android.mk</code> and fill in <code>VNDK_SP_LIBRARIES</code>, -<code>VNDK_SP_EXT_LIBRARIES</code> and <code>EXTRA_VENDOR_LIBRARIES</code> to -automate the process to copy libraries to the designated installation -destination.</p> - -<pre class="prettyprint">ifneq ($(filter $(YOUR_DEVICE_NAME),$(TARGET_DEVICE)),) -VNDK_SP_LIBRARIES := ##_VNDK_SP_## -VNDK_SP_EXT_LIBRARIES := ##_VNDK_SP_EXT_## -EXTRA_VENDOR_LIBRARIES := ##_EXTRA_VENDOR_LIBS_## - -#------------------------------------------------------------------------------- -# VNDK Modules -#------------------------------------------------------------------------------- -LOCAL_PATH := $(call my-dir) - -define define-vndk-lib -include $$(CLEAR_VARS) -LOCAL_MODULE := $1.$2 -LOCAL_MODULE_CLASS := SHARED_LIBRARIES -LOCAL_PREBUILT_MODULE_FILE := $$(TARGET_OUT_INTERMEDIATE_LIBRARIES)/$1.so -LOCAL_STRIP_MODULE := false -LOCAL_MULTILIB := first -LOCAL_MODULE_TAGS := optional -LOCAL_INSTALLED_MODULE_STEM := $1.so -LOCAL_MODULE_SUFFIX := .so -LOCAL_MODULE_RELATIVE_PATH := $3 -LOCAL_VENDOR_MODULE := $4 -include $$(BUILD_PREBUILT) - -ifneq ($$(TARGET_2ND_ARCH),) -ifneq ($$(TARGET_TRANSLATE_2ND_ARCH),true) -include $$(CLEAR_VARS) -LOCAL_MODULE := $1.$2 -LOCAL_MODULE_CLASS := SHARED_LIBRARIES -LOCAL_PREBUILT_MODULE_FILE := $$($$(TARGET_2ND_ARCH_VAR_PREFIX)TARGET_OUT_INTERMEDIATE_LIBRARIES)/$1.so -LOCAL_STRIP_MODULE := false -LOCAL_MULTILIB := 32 -LOCAL_MODULE_TAGS := optional -LOCAL_INSTALLED_MODULE_STEM := $1.so -LOCAL_MODULE_SUFFIX := .so -LOCAL_MODULE_RELATIVE_PATH := $3 -LOCAL_VENDOR_MODULE := $4 -include $$(BUILD_PREBUILT) -endif # TARGET_TRANSLATE_2ND_ARCH is not true -endif # TARGET_2ND_ARCH is not empty -endef - -$(foreach lib,$(VNDK_SP_LIBRARIES),\ - $(eval $(call define-vndk-lib,$(lib),vndk-sp-gen,vndk-sp,))) -$(foreach lib,$(VNDK_SP_EXT_LIBRARIES),\ - $(eval $(call define-vndk-lib,$(lib),vndk-sp-ext-gen,vndk-sp,true))) -$(foreach lib,$(EXTRA_VENDOR_LIBRARIES),\ - $(eval $(call define-vndk-lib,$(lib),vndk-ext-gen,,true))) - - -#------------------------------------------------------------------------------- -# Phony Package -#------------------------------------------------------------------------------- - -include $(CLEAR_VARS) -LOCAL_MODULE := $(YOUR_DEVICE_NAME)-vndk -LOCAL_MODULE_TAGS := optional -LOCAL_REQUIRED_MODULES := \ - $(addsuffix .vndk-sp-gen,$(VNDK_SP_LIBRARIES)) \ - $(addsuffix .vndk-sp-ext-gen,$(VNDK_SP_EXT_LIBRARIES)) \ - $(addsuffix .vndk-ext-gen,$(EXTRA_VENDOR_LIBRARIES)) -include $(BUILD_PHONY_PACKAGE) - -endif # ifneq ($(filter $(YOUR_DEVICE_NAME),$(TARGET_DEVICE)),) -</pre> - - - - - -<h2 id="check-dep">check-dep</h2> - -<p>The <code>check-dep</code> subcommand scans vendor modules and checks their -dependencies. If it detects violations, it prints the violating dependant -library and symbol usages:</p> - -<pre class="prettyprint"> -<code class="devsite-terminal">./vndk_definition_tool.py check-dep \</code> - --system ${ANDROID_PRODUCT_OUT}/system \ - --vendor ${ANDROID_PRODUCT_OUT}/vendor \ - --tag-file eligible-list.csv \ - --module-info ${ANDROID_PRODUCT_OUT}/module-info.json \ - 1> check_dep.txt \ - 2> check_dep_err.txt -</pre> - -<p>For example, the following sample output shows a violating dependency from -<code>libRS_internal.so</code> to <code>libmediandk.so</code>:</p> - -<pre class="prettyprint"> -/system/lib/libRS_internal.so - MODULE_PATH: frameworks/rs - /system/lib/libmediandk.so - AImageReader_acquireNextImage - AImageReader_delete - AImageReader_getWindow - AImageReader_new - AImageReader_setImageListener -</pre> - -<p>Options for the <code>check-dep</code> subcommand include:</p> - -<table> - <tr> - <th style="width:25%">Option</th> - <th>Description</th> - </tr> - - <tr> - <td><code>--tag-file</code></td> - <td>Must refer to an eligible library tag file (described below), which is a - Google-provided spreadsheet that described categories of framework shared - libraries.</td> - </tr> - - <tr> - <td><code>--module-info</code></td> - <td>Points to the <code>module-info.json</code> generated by Android build - system. It helps the VNDK definition tool associate binary modules with source - code.</td> - </tr> -</table> - - - -<h3 id="eligible-library-tag-file">Eligible library tag file</h3> - -<p>Google provides an eligible VNDK spreadsheet (e.g. -<code>eligible-list.csv</code>) that tags the framework shared libraries that -can be used by vendor modules:</p> - -<table> - <tr> - <th style="width:25%">Tag</th> - <th>Description</th> - </tr> - - <tr> - <td>LL-NDK</td> - <td>Shared libraries with stable ABIs/APIs that can be used by both - framework and vendor modules.</td> - </tr> - - <tr> - <td>LL-NDK-Private</td> - <td>Private dependencies of LL-NDK libraries. Vendor modules must not access - these libraries directly.</td> - </tr> - - <tr> - <td>VNDK-SP</td> - <td>SP-HAL framework shared libraries dependencies.</td> - </tr> - - <tr> - <td>VNDK-SP-Private</td> - <td>VNDK-SP dependencies that are not directly accessible to all vendor - modules.</td> - </tr> - - <tr> - <td>VNDK</td> - <td>Framework shared libraries that are available to vendor modules (except - SP-HAL and SP-HAL-Dep).</td> - </tr> - - <tr> - <td>VNDK-Private</td> - <td>VNDK dependencies that are not directly accessible to all vendor - modules.</td> - </tr> - - <tr> - <td>FWK-ONLY</td> - <td>Framework-only shared libraries that must not be accessed by vendor - modules (neither directly nor indirectly).</td> - </tr> - - <tr> - <td>FWK-ONLY-RS</td> - <td>Framework-only shared libraries that must not be accessed by vendor - modules (except for RS usages).</td> - </tr> -</table> - -<p>The following table describes tags used for vendor shared libraries:</p> - -<table> - <tr> - <th style="width:25%">Tag</th> - <th>Description</th> - </tr> - - <tr> - <td>SP-HAL</td> - <td>Same-process HAL implementation shared libraries.</td> - </tr> - - <tr> - <td>SP-HAL-Dep</td> - <td>SP-HAL vendor shared libraries dependencies (a.k.a. SP-HAL dependencies - excluding LL-NDK and VNDK-SP).</td> - </tr> - - <tr> - <td>VND-ONLY</td> - <td>Framework-invisible shared libraries that must not be accessed by - framework modules. The copied extended VNDK libraries will be tagged as - VND-ONLY as well.</td> - </tr> -</table> - -<p>Relationships between tags:</p> - -<img src="../images/treble_vndk_design.png"> -<figcaption><strong>Figure 1.</strong> Relationships between tags.</figcaption> - - - - - -<h2 id="deps">deps</h2> - -<p>To debug the library dependencies, the <code>deps</code> subcommand prints -the module dependencies:</p> - -<pre class="prettyprint"> -<code class="devsite-terminal">./vndk_definition_tool.py deps \</code> - --system ${ANDROID_PRODUCT_OUT}/system \ - --vendor ${ANDROID_PRODUCT_OUT}/vendor -</pre> - -<p>The output consists of multiple lines. The line without a tab character -starts a new section. The line with a tab character depends on the preceding -section. For example:</p> - -<pre class="prettyprint"> -/system/lib/ld-android.so -/system/lib/libc.so - /system/lib/libdl.so -</pre> - -<p>This output shows that <code>ld-android.so</code> does not have a dependency -and <code>libc.so</code> depends on <code>libdl.so</code>.</p> - -<p>When specifying the <code>--revert</code> option, <code>deps</code> -subcommand prints the <strong>usages of libraries</strong> (reversed -dependencies):</p> - -<pre class="prettyprint"> -<code class="devsite-terminal">./vndk_definition_tool.py deps \</code> - --revert \ - --system ${ANDROID_PRODUCT_OUT}/system \ - --vendor ${ANDROID_PRODUCT_OUT}/vendor</pre> - -<p>For example:</p> - -<pre class="prettyprint"> -/system/lib/ld-android.so - /system/lib/libdl.so - </pre> - -<p>This output shows that <code>ld-android.so</code> is used by -<code>libdl.so</code>, or in other words, <code>libdl.so</code> depends on -<code>ld-android.so</code>. In addition, this output shows that -<code>libdl.so</code> is the sole user of <code>ld-android.so</code>.</p> - -<p>When specifying the <code>--symbol</code> option, the <code>deps</code> -subcommand prints the symbols being used:</p> - -<pre class="prettyprint"> -<code class="devsite-terminal">./vndk_definition_tool.py deps \</code> - --symbol \ - --system ${ANDROID_PRODUCT_OUT}/system \ - --vendor ${ANDROID_PRODUCT_OUT}/vendor - </pre> - -<p>For example:</p> - -<pre class="prettyprint"> -/system/lib/libc.so - /system/lib/libdl.so - android_get_application_target_sdk_version - dl_unwind_find_exidx - dlclose - dlerror - dlopen - dlsym -</pre> - -<p>This output shows that <code>libc.so</code> depends on 6 functions exported -from <code>libdl.so</code>. If both the <code>--symbol</code> option and -<code>--revert</code> option are specified, the symbols used by the user -will be printed.</p> - - </body> -</html> diff --git a/en/devices/architecture/vndk/dir-rules-sepolicy.html b/en/devices/architecture/vndk/dir-rules-sepolicy.html deleted file mode 100644 index f04836c7..00000000 --- a/en/devices/architecture/vndk/dir-rules-sepolicy.html +++ /dev/null @@ -1,177 +0,0 @@ -<html devsite> - <head> - <title>Directories, Rules, and sepolicy</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>This page describes the directory layout for devices running Android 8.0 and -higher, VNDK rules, and associated sepolicy.</p> - -<h2 id="directory">Directory layout</h2> -<p>The <em>Degenerated Directory Layout</em> consists of the following -directories:</p> -<ul> -<li><code>/system/lib[64]</code> contains all framework shared libraries, -including LL-NDK, VNDK, and framework-only libraries (including -LL-NDK-Private and some libraries with the same names as the -ones in VNDK-SP).</li> -<li><code>/system/lib[64]/vndk-sp</code> contains VNDK-SP libraries for -same-process HALs.</li> -<li><code>/vendor/lib[64]</code> contains the extended VNDK libraries (either -DXUA or DXUX VNDK libraries), same-process HAL implementations, and other vendor -shared libraries.</li> -<li><code>/vendor/lib[64]/vndk-sp</code> may contain extra libraries that are -used by VNDK-SP libraries.</li> -</ul> - -<p>Vendor modules load the VNDK libraries from <code>/system/lib[64]</code>.</p> - -<h2 id="rules">VNDK rules</h2> -<p>This section provides a comprehensive list of VNDK rules:</p> - -<ul> -<li>Framework processes must not load non-SP-HAL shared libraries from vendor -partitions (not strictly enforced in Android O but will be in a future release). -</li> -<li>Vendor processes must not load non-LL-NDK, non-VNDK-SP, and -non-VNDK libraries from the system partition. (not strictly enforced in Android -O but will be in a future release).</li> - -<aside class="note"><strong>Note</strong>: To benefit from the framework-only -OTA beyond Android 8.0, this rule must not be violated in devices launched with -Android 8.0.</aside> - -<li>Installed VNDK libraries must be a subset of Google-defined eligible VNDK -libraries.</li> -<li>The outer dependencies of SP-HAL and SP-HAL-Dep must be restricted to -LL-NDK or Google-defined VNDK-SP libraries. - <ul> - <li>The dependencies of an SP-HAL shared library must be restricted to LL-NDK - libraries, Google-defined VNDK-SP libraries, other SP-HAL libraries, and/or - other vendor shared libraries that can be labeled as SP-HAL-Dep - libraries.</li> - <li>A vendor shared library can be labeled as a SP-HAL-Dep library only if it - is not an AOSP library and its dependencies are restricted to LL-NDK libraries, - Google-defined VNDK-SP libraries, SP-HAL libraries, and/or other SP-HAL-Dep - libraries.</li> - </ul> -</li> -<li>VNDK-SP must be self-contained. <code>libRS_internal.so</code> gets special -treatment in Android 8.0, but will be revisited in a future release.</li> -<li>No framework-vendor communication through non-HIDL interfaces, including -(but not limited to) binder, sockets, shared memories, files, etc.</li> -<li>The size of the system partition must be large enough to contain two copies -of all eligible VNDK libraries and a copy of ineligible framework shared -libraries.</li> -</ul> - -<h2 id="sepolicy">sepolicy</h2> -<p>Framework processes described in this section correspond to -<code>coredomain</code> in sepolicies while vendor processes correspond to -<code>non-coredomain</code>. For example, <code>/dev/binder</code> can be -accessed only in <code>coredomain</code> and <code>/dev/vndbinder</code> can be -accessed only in non-<code>coredomain</code>.</p> - -<p>Similar policies restrict the access to the shared libraries on system and -vendor partitions. The following table shows the rights to access shared -libraries of different categories:</p> - -<table> - <tr> - <th style="width:35%">Category</th> - <th>Partition</th> - <th>Accessible from<br>coredomain</th> - <th>Accessible from<br>non-coredomain</th> - </tr> - <tr> - <td>LL-NDK</td> - <td>System</td> - <td>Y</td> - <td>Y</td> - </tr> - <tr> - <td>LL-NDK-Private</td> - <td>System</td> - <td>Y</td> - <td>Y</td> - </tr> - <tr> - <td>VNDK-SP/VNDK-SP-Private</td> - <td>System</td> - <td>Y</td> - <td>Y</td> - </tr> - <tr> - <td>VNDK-SP-Ext</td> - <td>Vendor</td> - <td>Y</td> - <td>Y</td> - </tr> - <tr> - <td>VNDK</td> - <td>System</td> - <td>Y</td> - <td>Y</td> - </tr> - <tr> - <td>VNDK-Ext</td> - <td>Vendor</td> - <td>N</td> - <td>Y</td> - </tr> - <tr> - <td>FWK-ONLY</td> - <td>System</td> - <td>Y</td> - <td>N</td> - </tr> - <tr> - <td>FWK-ONLY-RS</td> - <td>System</td> - <td>Y</td> - <td>N</td> - </tr> - <tr> - <td>SP-HAL</td> - <td>Vendor</td> - <td>Y</td> - <td>Y</td> - </tr> - <tr> - <td>SP-HAL-Dep</td> - <td>Vendor</td> - <td>Y</td> - <td>Y</td> - </tr> - <tr> - <td>VND-ONLY</td> - <td>Vendor</td> - <td>N</td> - <td>Y</td> - </tr> -</table> - -<p>LL-NDK-Private and VNDK-SP-Private must be -accessible from both domains because non-<code>coredomain</code> will -indirectly access them. Similarly, SP-HAL-Dep must be accessible from -<code>coredomain</code> because SP-HAL relies on it.</p> - - </body> -</html> diff --git a/en/devices/architecture/vndk/enabling.html b/en/devices/architecture/vndk/enabling.html deleted file mode 100644 index a034135e..00000000 --- a/en/devices/architecture/vndk/enabling.html +++ /dev/null @@ -1,189 +0,0 @@ -<html devsite> - <head> - <title>Enabling the VNDK</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - <!-- - Copyright 2018 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>The VNDK requires several changes to a codebase to separate concerns between -vendor and system. Use the following guide to enable VNDK in a vendor/OEM -codebase.</p> - -<h2 id=build-system-libraries>Build system libraries</h2> -<p>The build system contains several types of objects including libraries -(shared, static, or header) and binaries:</p> - -<img src="../images/treble_vndk_build_system_libraries.png"> -<figcaption><strong>Figure 1.</strong> Build system libraries.</figcaption> - -<ul> -<li><strong>core</strong>. Used by the system image, on the system image. These -libraries cannot be used by <code>vendor</code>, <code>vendor_available</code>, -<code>vndk</code>, or <code>vndk-sp</code> libraries. -<pre class="prettyprint"> -cc_library { - name: "libThatIsCore", - ... -} -</pre> -</li> - -<li><strong>vendor-only</strong> (or <code>proprietary</code>). Used by the -vendor image, on the vendor image. -<pre class="prettyprint"> -cc_library { - name: "libThatIsVendorOnly", - proprietary: true, - # or: vendor: true, # (for things in AOSP) - ... -} -</dpre> -</li> - -<li><strong>vendor_available</strong>. Used by the vendor image, on the vendor -image (may contain duplicates of <code>core</code>). -<pre class="prettyprint"> -cc_library { - name: "libThatIsVendorAvailable", - vendor_available: true, - ... -} -</pre> -</li> - -<li><strong>vndk</strong>. Used by the vendor image, on the system image (a -subset of <code>vendor_available</code>). -<pre class="prettyprint"> -cc_library { - name: "libThatIsVndk", - vendor_available: true, - vndk: { - enabled: true, - } - ... -} -</pre> -</li> - -<li><strong>vndk-sp</strong>. Used by the system image indirectly, on the -system image (subset of <code>core</code>). -<pre class="prettyprint"> -cc_library { - name: "libThatIsVndkSp", - vendor_available: true, - vndk: { - enabled: true, - support_system_process: true, - } - ... -} -</pre> -</li> - -<li><strong>llndk</strong>. Used by both the system and vendor images. -<pre class="prettyprint"> -llndk_library { - name: "libThasIsLlndk", -} -</pre> -</li> -</ul> - -<p>When a lib is marked as <code>vendor_available:true</code>, it is built -twice:</p> -<ul> -<li>Once for platform (and thus installed to <code>/system/lib</code>).</li> -<li>Once for vendor (and thus installed to <code>/vendor/lib</code>, -<code>/system/lib/vndk</code>, or <code>/system/lib/vndk-sp</code>).</li> -</ul> - -<p>The vendor versions of libs are built with <code>-D__ANDROID_VNDK__</code>. -Private system components that may change significantly in future versions of -Android are disabled with this flag. In addition, different libraries export a -different set of headers (such as <code>liblog</code>). Options specific to a -vendor variant of a target can be specified in an <code>Android.bp</code> file -in:</p> -<pre class="prettyprint">target: { vendor: { … } }</pre> - -<h2 id=enabling>Enabling VNDK for a codebase</h2> -<p>To enable the VNDK for a codebase:</p> -<ol> -<li>Determine eligibility by calculating the required sizes of -<code>vendor.img</code> and <code>system.img</code> partitions.</li> -<li>Enable <code>BOARD_VNDK_VERSION=current</code>. You can add to -<code>BoardConfig.mk</code> or build components with it directly (i.e. -<code>m -j BOARD_VNDK_VERSION=current <var>MY-LIB</var></code>).</li> -</ol> -<p>After enabling <code>BOARD_VNDK_VERSION=current</code>, the build system -enforces the following dependency and header requirements.</p> - -<h3 id=managing-dependencies>Managing dependencies</h3> -<p>A <code>vendor</code> object that depends on a <code>core</code> component -that doesn't exist in the <code>vndk</code> or as a <code>vendor</code> object -must be resolved using one of the following options:</p> -<ul> -<li>The dependency can be removed.</li> -<li>If the <code>core</code> component is owned by <code>vendor</code>, it can -be marked as <code>vendor_available</code> or <code>vendor</code>.</li> -<li>A change making the core object part of the <code>vndk</code> may be -upstreamed to Google.</li> -</ul> -<p>In addition, if a <code>core</code> component has dependencies on a -<code>vendor</code> component, the <code>vendor</code> component must be made -into a <code>core</code> component <strong>or</strong> the dependency must be -removed in another way (for example, by removing the dependency or by moving the -dependency into a <code>vendor</code> component).</p> - -<h3 id=managing-headers>Managing headers</h3> -<p>Global header dependencies must be removed to enable the build system to know -whether to build the headers with or without <code>-D__ANDROID_VNDK__</code>. -For example, libutils headers such as <code>utils/StrongPointer.h</code> can -still be accessed using the header library -<a href="https://android.googlesource.com/platform/system/core/+/master/libutils/include/utils" class="external"><code>libutils_headers</code></a>. -</p> - -<p>Some headers (such as <code>unistd.h</code>) can no longer be transitively -included but can be included locally.</p> - -<p>Finally, the public part of <code>private/android_filesystem_config.h</code> -has been moved to <code>cutils/android_filesystem_config.h</code>. To manage -these headers, do one of the following:</p> - -<ul> -<li>Remove the dependency to -<code>private/android_filesystem_config.h</code> by replacing all -<code>AID_*</code> macros with -<code><a href="http://man7.org/linux/man-pages/man3/getgrnam.3.html" class="external">getgrnam</code></a>/<code><a href="http://man7.org/linux/man-pages/man3/getpwnam.3.html" class="external">getpwnam</code></a> -calls if possible. For example: - -<ul> -<li><code>(uid_t)AID_WIFI</code> becomes -<code>getpwnam("wifi")->pw_uid</code>.</li> -<li><code>(gid_t)AID_SDCARD_R</code> becomes -<code>getgrnam("sdcard_r")->gr_gid</code>.</li> -</ul> -For details, refer to -<code><a href="https://android.googlesource.com/platform/system/core/+/master/libcutils/include/private/android_filesystem_config.h" class="external">private/android_filesystem_config.h</code></a>. -</li> -<li>For hard-coded AIS, include -<code>cutils/android_filesystem_config.h</code>.</li> -</ul> - - </body> - </html> diff --git a/en/devices/architecture/vndk/extensions.html b/en/devices/architecture/vndk/extensions.html deleted file mode 100644 index 7f0e2abd..00000000 --- a/en/devices/architecture/vndk/extensions.html +++ /dev/null @@ -1,181 +0,0 @@ -<html devsite> - <head> - <title>VNDK Extensions</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>Android device manufacturers change the source code of AOSP libraries for -various reasons. Some vendors reimplement functions in AOSP libraries to -boost the performance while other vendors add new hooks, new APIs, or new -functionalities to AOSP libraries. This section provides guidelines for -extending AOSP libraries in a way that does not break CTS/VTS.</p> - - - - - -<h2 id="drop-in-replacement">Drop-in replacement</h2> - -<p>All modified shared libraries must be <strong>binary-compatible</strong>, -<strong>drop-in replacements</strong> of their AOSP counterpart. All existing -AOSP users must be able to use the modified shared library without -recompilations. This requirement implies the following:</p> - -<ul> - <li>AOSP functions must not be removed.</li> - <li>Structures must not be altered if such structures are exposed to their - users.</li> - <li>Pre-condition of functions must not be strengthened.</li> - <li>Functions must provide equivalent functionalities.</li> - <li>Post-condition of functions must not be weakened.</li> -</ul> - - - - - -<h2 id="extended-module-classifications">Extended module classifications</h2> - -<p>Classify modules by the functionalities they <strong>define</strong> and -<strong>use</strong>.</p> - -<p class="note"><strong>Note</strong>: <em>Functionalities</em> is used here -instead of API/ABI because it is possible to add functionality without changing -any API/ABI.</p> - -<p>Depending on the functionalities defined in a module, modules can be -classified into <strong>DA-Module</strong> and <strong>DX-Module</strong>:</p> - -<ul> - <li> - <em>Defining-only-AOSP Modules (DA-Module)</em> do not define new - functionalities which were not in the AOSP counterpart. - - <ul> - <li><em>Example 1.</em> An intact unmodified AOSP library is a - DA-Module.</li> - - <li><em>Example 2.</em> If a vendor rewrites the functions in - <code>libcrypto.so</code> with SIMD instructions (without adding new - functions), then the modified <code>libcrypto.so</code> will be a DA-Module. - </li> - </ul> - </li> - - <li> - <em>Defining-Extension Modules (DX-Module)</em> either define new - functionalities or do not have an AOSP counterpart. - - <ul> - <li><em>Example 1.</em> If a vendor adds a helper function to - <code>libjpeg.so</code> to access some internal data, then the modified - <code>libjpeg.so</code> will be a DX-Lib and the newly added function will be - the extended portion of the library.</li> - - <li><em>Example 2.</em> If a vendor defines a non-AOSP library named - <code>libfoo.so</code>, then <code>libfoo.so</code> will be a DX-Lib.</li> - </ul> - </li> -</ul> - -<p>Depending on the functionalities used by a module, modules can be classified -into <strong>UA-Module</strong> and <strong>UX-Module</strong>.</p> - -<ul> - <li> - <em>Using-only-AOSP Modules (UA-Module)</em> only use AOSP functionalities - in their implementations. They do not rely on any non-AOSP extensions. - - <ul> - <li><em>Example 1.</em> An intact unmodified AOSP library is an - UA-Module.</li> - - <li><em>Example 2.</em> If a modified shared library <code>libjpeg.so</code> - only relies on other AOSP APIs, then it will be an UA-Module.</li> - </ul> - </li> - - <li> - <em>Using-Extension Modules (UX-Module)</em> rely on some non-AOSP - functionalities in their implementations. - - <ul> - <li><em>Example 1.</em> If a modified <code>libjpeg.so</code> relies on - another non-AOSP library named <code>libjpeg_turbo2.so</code>, then the - modified <code>libjpeg.so</code> will be an UX-Module.</li> - - <li><em>Example 2.</em> If a vendor adds a new function to their modified - <code>libexif.so</code> and their modified <code>libjpeg.so</code> uses the - newly added function from <code>libexif.so</code>, then their modified - <code>libjpeg.so</code> will be an UX-Module.</li> - </ul> - </li> -</ul> - -<p>Definitions and usages are independent from each other:</p> - -<table> - <tr> - <td rowspan="2" colspan="2" class="columns"></td> - <th colspan="2">Used Functionalities</th> - </tr> - <tr> - <td>Only AOSP (UA)</td> - <td>Extended (UX)</td> - </tr> - <tr> - <th rowspan="2">Defined Functionalities</th> - <td>Only AOSP (DA)</td> - <td>DAUA</td> - <td>DAUX</td> - </tr> - <tr> - <td>Extended (DX)</td> - <td>DXUA</td> - <td>DXUX</td> - </tr> -</table> - - - - - -<h2 id="vndk-extension-mechanism">VNDK extension mechanism</h2> -<p>Vendor modules that rely on extended functionalities won't work because the -AOSP library with the same name does not have the extended functionality. If -vendor modules directly or indirectly depend on extended functionalities, -vendors should copy DAUX, DXUA, and DXUX shared libraries to the vendor -partition (vendor processes always look for shared libraries in the vendor -partition first). However, LL-NDK libraries must not be copied, so vendor -modules must not rely on the extended functionalities defined by the modified -LL-NDK libraries.</p> - -<p>DAUA shared libraries can remain on the system partition if the -corresponding AOSP library can provide the same functionality and vendor -modules continue to work when the system partition is overwritten by an Generic -System Image (GSI).</p> - -<p>Drop-in replacement is important because the unmodified VNDK libraries in -the GSI will link with the modified shared libraries on name collision. If the -AOSP libraries are modified in an API/ABI incompatible manner, the AOSP -libraries in the GSI might fail to link or result in undefined behaviors.</p> - - </body> -</html> diff --git a/en/devices/architecture/vndk/index.html b/en/devices/architecture/vndk/index.html deleted file mode 100644 index f692f8d8..00000000 --- a/en/devices/architecture/vndk/index.html +++ /dev/null @@ -1,400 +0,0 @@ -<html devsite> - <head> - <title>Vendor Native Development Kit (VNDK)</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - <body> - {% include "_versions.html" %} - <!-- - 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>The Vendor Native Development Kit (VNDK) is a set of libraries -exclusively for vendors to implement their HALs. The VNDK ships in -<code>system.img</code> and is dynamically linked to vendor code at runtime.</p> - -<h2 id=why-vndk>Why VNDK?</h2> -<p>Android 8.0 and higher enables framework-only updates in which the system -partition can be upgraded to the latest version while vendor partitions are left -unchanged. This implies that binaries built at different times must be able to -work with each other; VNDK covers API/ABI changes across Android releases.</p> - -<p>Framework-only updates include the following challenges:</p> - -<ul> -<li><strong>Dependency between framework modules and vendor modules</strong>. -Before Android 8.0, modules from both sides could link with modules from the -other side. However, dependencies from vendor modules imposed undesired -restrictions to framework modules development.</li> -<li><strong>Extensions to AOSP libraries</strong>. Android 8.0 and higher -requires all Android devices to pass CTS when the system partition is replaced -with a standard Generic System Image (GSI). However, as vendors extend AOSP -libraries to boost performance or to add extra functionalities for their HIDL -implementations, flashing the system partition with a standard GSI -might break a vendor's HIDL implementation. (For guidelines on -preventing such breakages, see -<a href="/devices/architecture/vndk/extensions.html">VNDK extensions</a>.)</li> -</ul> - -<p>To address these challenges, Android 8.0 introduces several techniques such -as VNDK (described in this section), -<a href="/devices/architecture/hidl/index.html">HIDL</a>, hwbinder, -<a href="/devices/architecture/dto/index.html">device tree overlay</a>, and -sepolicy overlay.</p> - -<h2 id=resources>VNDK resources</h2> -<p>This section includes the following VNDK resources:</p> -<ul> -<li><em><a href="#vndk-concepts">VNDK concepts</a></em> (below) describes -framework shared libraries, same-process HALs (SP-HALs), and VNDK terminology. -</li> -<li><em><a href="/devices/architecture/vndk/extensions.html">VNDK -extensions</a></em> classifies vendor-specific changes into categories. For -example, libraries with extended functionalities on which vendor modules rely -must be copied into the vendor partition, but ABI-incompatible changes are -prohibited.</li> -<li><em><a href="/devices/architecture/vndk/build-system.html">VNDK Build -System Support</a></em> describes the build system configurations and module -definition syntaxes that are related to VNDK.</li> -<li>The <em><a href="/devices/architecture/vndk/deftool.html">VNDK Definition -Tool</a></em> helps migrate your source tree to Android 8.0 and higher.</li> -<li><em><a href="/devices/architecture/vndk/linker-namespace.html">Linker -Namespace</a></em> provides fine-grained control over shared library linkages. -</li> -<li><em><a href="/devices/architecture/vndk/dir-rules-sepolicy.html">Directories, -Rules, and sepolicy</a></em> defines the directory structure for devices running -Android 8.0 and higher, VNDK rules, and associated sepolicy.</li> -<li>The <em><a href="/devices/architecture/images/VNDK.pdf">VNDK Design</a></em> -presentation illustrates fundamental VDNK concepts used in Android 8.0 and -higher.</li> -</ul> - -<h2 id="concepts">VNDK concepts</h2> -<p>In an ideal Android 8.0 and higher world, framework processes do not load -vendor shared libraries, all vendor processes load only vendor shared libraries -(and a portion of framework shared libraries), and communications between -framework processes and vendor processes are governed by HIDL and hardware -binder.</p> - -<p>Such a world includes the possibility that stable, public APIs from -framework shared libraries might not be sufficient for vendor module developers -(although APIs can change between Android releases), requiring that some portion -of framework shared libraries be accessible to vendor processes. In addition, as -performance requirements can lead to compromises, some response-time-critical -HALs must be treated differently.</p> - -<p>The following sections detail how VNDK handles framework shared libraries for -vendors and Same-Process HALs (SP-HALs).</p> - -<h3 id="framework-shared-libraries">Framework shared libraries for vendor</h3> -<p>This section describes the criteria for classifying shared libraries that are -accessible to vendor processes. There are two approaches to support vendor -modules across multiple Android releases:</p> - -<ol> -<li><strong>Stabilize the ABIs/APIs of the framework shared libraries</strong>. -New framework modules and old vendor modules can use the same shared library to -reduce memory footprint and storage size. A unique shared library also avoids -several double-loading issues. However, the development cost to maintain stable -ABIs/APIs is high and it is unrealistic to stabilize all ABIs/APIs exported by -every framework shared library.</li> -<li><strong>Copy old framework shared libraries</strong>. Comes with the strong -restriction against side channels, defined as all mechanisms to communicate -among framework modules and vendor modules, including (but not limited to) -binder, socket, pipe, shared memory, shared file, and system properties. There -must be no communication unless the communication protocol is frozen and stable -(e.g. HIDL through hwbinder). Double-loading shared libraries might cause -problems as well; for example, if an object created by the new library is passed -into the functions from the old library, an error may occur as these libraries -may interpret the object differently.</li> -</ol> - -<p>Different approaches are used depending on the characteristics of the shared -libraries. As a result, framework shared libraries are classified into three -sub-categories:</p> - -<ul> -<li><em>LL-NDK Libraries</em> are <em>Framework Shared Libraries</em> -that are known to be stable. Their developers are committed to maintain their -API/ABI stabilities. - <ul> - <li>LL-NDK includes the following libraries: -<code>libEGL.so</code>, <code>libGLESv1_CM.so</code>, -<code>libGLESv2.so</code>, <code>libGLESv3.so</code>, -<code>libandroid_net.so</code>, <code>libc.so</code>, <code>libdl.so</code>, -<code>liblog.so</code>, <code>libm.so</code>, <code>libnativewindow.so</code>, -<code>libneuralnetworks.so</code>, <code>libsync.so</code>, -<code>libvndksupport.so</code>, and <code>libvulkan.so</code>, -</li> - </ul> -</li> -<li><em>Eligible VNDK Libraries (VNDK)</em> are <em>Framework Shared -Libraries</em> that are safe to be copied twice. <em>Framework Modules</em> and -<em>Vendor Modules</em> can link with their own copies. A framework shared -library can become an eligible VNDK library only if it satisfies the following -criteria: - <ul> - <li>It does not send/receive IPCs to/from the framework.</li> - <li>It is not related to ART virtual machine.</li> - <li>It does not read/write files/partitions with unstable file formats.</li> - <li>It does not have special software license which requires legal reviews.</li> - <li>Its code owner does not have objections to vendor usages.</li> - </ul> -</li> -<li><em>Framework-Only Libraries (FWK-ONLY)</em> are <em>Framework Shared -Libraries</em> that do not belong to the categories mentioned above. These -libraries: - <ul> - <li>Are considered framework internal implementation details.</li> - <li>Must not be accessed by vendor modules.</li> - <li>Have unstable ABIs/APIs and no API/ABI compatibility guarantees.</li> - <li>Are not copied.</li> - </ul> -</li> -</ul> - -<h3 id="sp-hal">Same-Process HAL (SP-HAL)</h3> -<p> -<em>Same-Process HAL</em> (<em>SP-HAL</em>) is a set of predetermined HALs -implemented as <em>Vendor Shared Libraries</em> and loaded into <em>Framework -Processes</em>. SP-HALs are isolated by a linker namespace (controls the -libraries and symbols that are visible to the shared libraries). SP-HALs must -depend only on <em>LL-NDK</em> and <em>VNDK-SP</em>.</p> - -<p>VNDK-SP is a predefined subset of eligible VNDK libraries. VNDK-SP libraries -are carefully reviewed to ensure double-loading VNDK-SP libraries into framework -processes does not cause problems. Both SP-HALs and VNDK-SPs are defined by -Google.</p> - -<p>The following libraries are approved SP-HALs:</p> - -<ul> -<li><code>libGLESv1_CM_${driver}.so</code></li> -<li><code>libGLESv2_${driver}.so</code></li> -<li><code>libGLESv3_${driver}.so</code></li> -<li><code>libEGL_${driver}.so</code></li> -<li><code>vulkan.${driver}.so</code></li> -<li><code>android.hardware.renderscript@1.0-impl.so</code></li> -<li><code>android.hardware.graphics.mapper@2.0-impl.so</code></li> -</ul> - -<p>The following libraries are VNDK-SP libraries that are accessible by SP-HALs: -</p> - -<ul> -<li><code>android.hardware.graphics.common@1.0.so</code></li> -<li><code>android.hardware.graphics.mapper@2.0.so</code></li> -<li><code>android.hardware.renderscript@1.0.so</code> (Renderscript)</li> -<li><code>libRS_internal.so</code> (Renderscript)</li> -<li><code>libbase.so</code></li> -<li><code>libc++.so</code></li> -<li><code>libcutils.so</code></li> -<li><code>libhardware.so</code></li> -<li><code>libhidlbase.so</code></li> -<li><code>libhidltransport.so</code></li> -<li><code>libhwbinder.so</code></li> -<li><code>libion.so</code></li> -<li><code>libutils.so</code></li> -<li><code>libz.so</code></li> -</ul> - -<p> -The following <em>VNDK-SP dependencies (VNDK-SP-Private)</em> are invisible to -<em>SP-HALs</em>: -</p> - -<ul> -<li><code>libRSCpuRef.so</code> (Renderscript)</li> -<li><code>libRSDriver.so</code> (Renderscript)</li> -<li><code>libbacktrace.so</code></li> -<li><code>libblas.so</code> (Renderscript)</li> -<li><code>libbcinfo.so</code> (Renderscript)</li> -<li><code>liblzma.so</code></li> -<li><code>libunwind.so</code></li> -</ul> - -<p>The following are <em>framework-only libraries with RS exceptions -(FWK-ONLY-RS)</em>:</p> -<ul> -<li><code>libft2.so</code> (Renderscript)</li> -<li><code>libmediandk.so</code> (Renderscript)</li> -</ul> - - -<h2 id="vndk-terminology">VNDK terminology</h2> -<ul> -<li><em>Modules</em> refer to either <em>Shared Libraries</em> or -<em>Executables</em>.</li> -<li><em>Processes</em> are operating system tasks spawned from -<em>Executables</em>.</li> -<li><em>Framework</em>-qualified terms refer to the concepts related to the -<strong>system</strong> partition.</li> -<li><em>Vendor</em>-qualified terms refer to the concepts related to -<strong>vendor</strong> partitions.</li> -</ul> - -<p>For example:</p> -<ul> -<li><em>Framework Executables</em> refer to executables in -<code>/system/bin</code> or <code>/system/xbin</code>.</li> -<li><em>Framework Shared Libraries</em> refer to shared libraries under -<code>/system/lib[64]</code>.</li> -<li><em>Framework Modules</em> refer to both <em>Framework Shared Libraries</em> -and <em>Framework Executables</em>.</li> -<li><em>Framework Processes</em> are processes spawned from <em>Framework -Executables</em> (e.g. <code>/system/bin/app_process</code>).</li> -<li><em>Vendor Executables</em> refer to executables in <code>/vendor/bin</code> -<li><em>Vendor Shared Libraries</em> refer to shared libraries under -<code>/vendor/lib[64]</code>.</li> -<li><em>Vendor Modules</em> refer to both <em>Vendor Executables</em> and -<em>Vendor Shared Libraries</em>.</li> -<li><em>Vendor Processes</em> are processes spawned from <em>Vendor -Executables</em> (e.g.</li> -<code>/vendor/bin/android.hardware.camera.provider@2.4-service</code>).</li> -</ul> - -<aside class="note"><strong>Note</strong>: <em>Generic System Image (GSI)</em> -stands for the standard Android system image that is built from corresponding -branches (similar to the release branch but with some bug fixes or some -generalizations) and released by Google.</aside> - - -<h2 id="vndk-versioning">VNDK versioning</h2> - -<p> - In Android {{ androidPVersionNumber }}, VNDK shared libraries are versioned: -</p> - -<ul> - <li>The <code>ro.vndk.version</code> system property is automatically added to - <code>/vendor/default.prop</code>.</li> - - <li>VNDK shared libraries are installed to - <code>/system/lib[64]/vndk-${ro.vndk.version}</code>.</li> - - <li>VNDK-SP shared libraries are installed to - <code>/system/lib[64]/vndk-sp-${ro.vndk.version}</code>.</li> - - <li>The dynamic linker configuration file is installed to - <code>/system/etc/ld.config.${ro.vndk.version}.txt</code>.</li> -</ul> - -<p>The value of <code>ro.vndk.version</code> is chosen by the algorithm -below:</p> - -<ul> - <li>If <code>BOARD_VNDK_VERSION</code> is <em>not equal to</em> - <code>current</code>, use <code>BOARD_VNDK_VERSION</code>.</li> - - <li>If <code>BOARD_VNDK_VERSION</code> is <em>equal to</em> - <code>current</code>:</li> - - <ul> - <li>If <code>PLATFORM_VERSION_CODENAME</code> is <code>REL</code>, use - <code>PLATFORM_SDK_VERSION</code> (e.g. <code>28</code>).</li> - - <li>Otherwise, use <code>PLATFORM_VERSION_CODENAME</code> (e.g. - <code>P</code>).</li> - </ul> -</ul> - -<h3 id="upgrading-devices">Upgrading devices</h3> - -<p>If an Android 8.x device disabled VNDK run-time enforcement (i.e. either -built without <code>BOARD_VNDK_VERSION</code> or built with -<code>BOARD_VNDK_RUNTIME_DISABLE</code>), it may add -<code>PRODUCT_USE_VNDK_OVERRIDE := false</code> to <code>BoardConfig.mk</code> -while upgrading to Android {{ androidPVersionNumber }}.</p> - -<p>If <code>PRODUCT_USE_VNDK_OVERRIDE</code> is <code>false</code>, the -<code>ro.vndk.lite</code> property will be automatically added to -<code>/vendor/default.prop</code> and its value will be <code>true</code>. -Consequently, the dynamic linker will load the linker namespace configuration -from <code>/system/etc/ld.config.vndk_lite.txt</code>, which isolates only -SP-HAL and VNDK-SP.</p> - -<p> - To upgrade an Android 7.0 or lower device to Android - {{ androidPVersionNumber }}, add - <code>PRODUCT_TREBLE_LINKER_NAMESPACES_OVERRIDE := false</code> to - <code>BoardConfig.mk</code>. -</p> - -<h3 id="vendor-test-suite">Vendor Test Suite (VTS)</h3> - -<p> - The Android {{ androidPVersionNumber }} Vendor Test Suite (VTS) mandates a - non-empty <code>ro.vndk.version</code> property. Both newly-launched devices - and upgrading devices must define <code>ro.vndk.version</code>. Some VNDK test - cases (e.g. <code>VtsVndkFilesTest</code> and - <code>VtsVndkDependencyTest</code>) rely on the <code>ro.vndk.version</code> - property to load the matching eligible VNDK libraries data sets. -</p> - -<p> - If the <code>ro.product.first_api_level</code> property is greater than 27, - the <code>ro.vndk.lite</code> property must not be defined. - <code>VtsTreblePlatformVersionTest</code> will fail if - <code>ro.vndk.lite</code> is defined in a newly-launched Android - {{ androidPVersionNumber }} device. -</p> - - -<h2 id="document-history">Document history</h2> - -<p>This section tracks changes to VNDK documentation.</p> - -<h3 id="changes-p">Android {{ androidPVersionNumber }} changes</h3> - -<ul> - <li>Add VNDK versioning section.</li> - - <li>Add VTS section.</li> - - <li>Some VNDK categories have been renamed:</li> - <ul> - <li>LL-NDK-Indirect has been renamed to LL-NDK-Private.</li> - <li>VNDK-Indirect has been renamed to VNDK-Private.</li> - <li>VNDK-SP-Indirect-Private has been renamed to VNDK-SP-Private.</li> - <li>VNDK-SP-Indirect has been removed.</li> - </ul> -</ul> - -<h3 id="changes-81">Android 8.1 changes</h3> - -<ul> - <li>SP-NDK libraries have been merged into LL-NDK libraries.</li> - - <li>Replace <code>libui.so</code> with <code>libft2.so</code> in RS namespace - section. It was an error to include <code>libui.so</code>.</li> - - <li>Add <code>libGLESv3.so</code> and <code>libandroid_net.so</code> to LL-NDK - libraries.</li> - - <li>Add <code>libion.so</code> to VNDK-SP libraries.</li> - - <li>Remove <code>libstdc++.so</code> from LL-NDK libraries. Use - <code>libc++.so</code> instead. Some versions of standalone toolchains may add - <code>-lstdc++</code> to the default linker flags. To disable the defaults, add - <code>-nodefaultlibs -lc -lm -ldl</code> to <code>LDFLAGS</code>.</li> - - <li>Move <code>libz.so</code> from LL-NDK to VNDK-SP libraries. In some - configurations, <code>libz.so</code> may continue being LL-NDK. However, - there should be no observable differences.</li> -</ul> - - </body> -</html> diff --git a/en/devices/architecture/vndk/linker-namespace.html b/en/devices/architecture/vndk/linker-namespace.html deleted file mode 100644 index a460e158..00000000 --- a/en/devices/architecture/vndk/linker-namespace.html +++ /dev/null @@ -1,1287 +0,0 @@ -<html devsite> - <head> - <title>Linker Namespace</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>The dynamic linker tackles two challenges in Treble VNDK design:</p> - -<ul> - <li>SP-HAL shared libraries and their dependencies, including VNDK-SP - libraries, are loaded into framework processes. There should be some - mechanisms to prevent symbol conflicts.</li> - - <li><code>dlopen()</code> and <code>android_dlopen_ext()</code> may introduce - some run-time dependencies that are not visible at build-time and can be - difficult to detect using static analysis.</li> -</ul> - -<p>These two challenges can be resolved by the <em>linker namespace</em> -mechanism. The linker namespace mechanism is provided by the dynamic linker. It -can isolate the shared libraries in different linker namespaces so that -libraries with same library name but with different symbols won't conflict.</p> - -<p>On the other hand, the linker namespace mechanism provides the flexibility -so that some shared libraries may be exported by a linker namespace and used by -another linker namespace. These exported shared libraries may become the -application programming interfaces that are public to other programs while -hiding their implementation details within their linker namespaces.</p> - -<p>For example, <code>/system/lib[64]/libcutils.so</code> and -<code>/system/lib[64]/vndk-sp-${VER}/libcutils.so</code> are two shared -libraries. These two libraries may have different symbols. They are loaded -into different linker namespaces so that framework modules can depend on -<code>/system/lib[64]/libcutils.so</code> and SP-HAL shared libraries can -depend on <code>/system/lib[64]/vndk-sp-${VER}/libcutils.so</code>.</p> - -<p>On the other hand, <code>/system/lib[64]/libc.so</code> is an example of -public libraries that is exported by a linker namespace and imported into -many linker namespaces. The dependencies of -<code>/system/lib[64]/libc.so</code>, such as <code>libnetd_client.so</code>, -is loaded into the namespace in which <code>/system/lib[64]/libc.so</code> -resides. Other namespaces won't have accesses to those dependencies. This -mechanism encapsulates the implementation details while providing the public -interfaces.</p> - - - - - -<h2 id="how-does-it-work">How does it work?</h2> - -<p>The dynamic linker is responsible for loading the shared libraries specified -in <code>DT_NEEDED</code> entries or the shared libraries specified by the -argument of <code>dlopen()</code> or <code>android_dlopen_ext()</code>. In both -cases, the dynamic linker finds the linker namespace where the caller -resides and try to load the dependencies into the same linker namespace. If -the dynamic linker cannot load the shared library into the specified linker -namespace, it asks the <em>linked linker namespace</em> for exported shared -libraries.</p> - - - - - -<h2 id="configuration-file-format">Configuration file format</h2> - -<p>The configuration file format is based on the INI file format. A typical -configuration file looks like:</p> - -<pre class="prettyprint"> -dir.system = /system/bin -dir.system = /system/xbin -dir.vendor = /vendor/bin - -[system] -additional.namespaces = sphal,vndk - -namespace.default.isolated = true -namespace.default.search.paths = /system/${LIB} -namespace.default.permitted.paths = /system/${LIB}/hw -namespace.default.asan.search.paths = /data/asan/system/${LIB}:/system/${LIB} -namespace.default.asan.permitted.paths = /data/asan/system/${LIB}/hw:/system/${LIB}/hw - -namespace.sphal.isolated = true -namespace.sphal.visible = true -namespace.sphal.search.paths = /odm/${LIB}:/vendor/${LIB} -namespace.sphal.permitted.paths = /odm/${LIB}:/vendor/${LIB} -namespace.sphal.asan.search.paths = /data/asan/odm/${LIB}:/odm/${LIB} -namespace.sphal.asan.search.paths += /data/asan/vendor/${LIB}:/vendor/${LIB} -namespace.sphal.asan.permitted.paths = /data/asan/odm/${LIB}:/odm/${LIB} -namespace.sphal.asan.permitted.paths += /data/asan/vendor/${LIB}:/vendor/${LIB} -namespace.sphal.links = default,vndk -namespace.sphal.link.default.shared_libs = libc.so:libm.so -namespace.sphal.link.vndk.shared_libs = libbase.so:libcutils.so - -namespace.vndk.isolated = true -namespace.vndk.search.paths = /system/${LIB}/vndk-sp-29 -namespace.vndk.permitted.paths = /system/${LIB}/vndk-sp-29 -namespace.vndk.links = default -namespace.vndk.link.default.shared_libs = libc.so:libm.so - -[vendor] -namespace.default.isolated = false -namespace.default.search.paths = /vendor/${LIB}:/system/${LIB} -</pre> - -<p>The configuration file includes:</p> - -<ul> - <li>Several directory-section mapping properties at the beginning for the - dynamic linker to select the effective section.</li> - - <li> - Several linker namespaces configuration sections: - - <ul> - <li>Each section contains several namespaces (graph vertices) and several - fallback links between namespaces (graph arcs).</li> - - <li>Each namespace has its own isolation, search paths, permitted paths, - and visibility settings.</li> - </ul> - </li> -</ul> - -<p>The tables below describe the meaning of each property in detail.</p> - - - -<h3 id="directory-section-mapping-property">Directory-section mapping property</h3> - -<table> - <tr> - <th>Property</th> - <th>Description</th> - <th>Example</th> - </tr> - - <tr> - <td><p><code>dir.<var>name</var></code></p></td> - - <td> - <p>A path to a directory that the <code>[<var>name</var>]</code> section - applies to.</p> - - <p>Each property maps the executables under the directory to a linker - namespaces configuration section. There might be two (or more) properties - with the same <code><var>name</var></code> but point to different - directories.</p> - </td> - - <td> - <p> - <code>dir.system = /system/bin</code><br/> - <code>dir.system = /system/xbin</code><br/> - <code>dir.vendor = /vendor/bin</code><br/> - </p> - - <p>This indicates that the configuration specified in the - <code>[system]</code> section applies to the executables that are loaded - from either <code>/system/bin</code> or <code>/system/xbin</code>.</p> - - <p>The configuration specified in the <code>[vendor]</code> section applies - to the executables that are loaded from <code>/vendor/bin</code>.</p> - </td> - </tr> -</table> - - - -<h3 id="relation-properties">Relation properties</h3> - -<table> - <tr> - <th>Property</th> - <th>Description</th> - <th>Example</th> - </tr> - - <tr> - <td><code>additional.<wbr/>namespaces</code></td> - - <td> - <p>A comma-separated list of additional namespaces (in addition to the - <code>default</code> namespace) for the section.</p> - </td> - - <td> - <p><code>additional.<wbr/>namespaces = sphal,<wbr/>vndk</code></p> - - <p>This indicates there are three namespaces (<code>default</code>, - <code>sphal</code>, and <code>vndk</code>) in the <code>[system]</code> - configuration.</p> - </td> - </tr> - - <tr> - <td><code>namespace.<wbr/><var>name</var>.<wbr/>links</code></td> - - <td> - <p>A comma-separated list of fallback namespaces.</p> - - <p>If a shared library cannot be found in the current namespace, the dynamic - linker tries to load the shared library from the fallback namespaces. The - namespace specified at the beginning of the list has higher priority.</p> - - <aside class="note">Note: Fallback namespaces are not transitive. For - example, namespace <em>A</em> links to namespace <em>B</em> and namespace - <em>B</em> links to namespace <em>C</em>. If the dynamic linker can not - find the library in namespace <em>A</em>, it ONLY searches namespace - <em>B</em>. It doesn't search namespace <em>C</em>.</aside> - </td> - - <td> - <p><code>namespace.<wbr/>sphal.<wbr/>links = default,<wbr/>vndk</code></p> - - <p>If a shared library or an executable requests a shared library that - cannot be loaded into the <code>sphal</code> namespace, the dynamic linker - tries to load the shared library from the <code>default</code> - namespace.</p> - - <p>And then, if the shared library cannot be loaded from the - <code>default</code> namespace either, the dynamic linker tries to load the - shared library from the <code>vndk</code> namespace.</p> - - <p>Finally, if all attempts fail, the dynamic linker returns an error.</p> - </td> - </tr> - - <tr> - <td><code>namespace.<wbr/><var>name</var>.<wbr/>link.<wbr/><var>other</var>.<wbr/>shared_libs</code></td> - - <td> - <p>A colon-separated list of shared libraries that can be searched in the - <code>other</code> namespaces when those libraries cannot be found in the - <code>name</code> namespace.</p> - - <p>This property cannot be used with - <code>namespace.<wbr/><var>name</var>.<wbr/>link.<wbr/><var>other</var>.<wbr/>allow_all_shared_libs</code>.</p> - - <aside class="note"><p>Note: This property shares the same underlying - implementation with - <a href="/devices/tech/config/namespaces_libraries">public.libraries.txt</a> - files. Both mechanisms control the imported shared libraries by specifying a - link with a library name filter.</p> - - <p>The difference is that <code>ld.config.txt</code> is loaded by the - dynamic linker and all namespaces are created when a program starts. On the - contrary, <code>libnativeloader</code> creates a linker namespace when the - Zygote process is forked and specialized for an application. The namespace - for the application native libraries has a link that only allows the library - names specified in <code>public.libraries.txt</code>.</p></aside> - </td> - - <td> - <p><code>namespace.<wbr/>sphal.<wbr/>link.<wbr/>default.<wbr/>shared_libs = libc.so:<wbr/>libm.so</code></p> - - <p>This indicates that the fallback link only accepts <code>libc.so</code> - or <code>libm.so</code> as the requested library name. The dynamic linker - ignores the fallback link from <code>sphal</code> to - <code>default</code> namespace if the requested library name is not - <code>libc.so</code> nor <code>libm.so</code>.</p> - </td> - </tr> - - <tr> - <td><code>namespace.<wbr/><var>name</var>.<wbr/>link.<wbr/><var>other</var>.<wbr/>allow_all_shared_libs</code></td> - - <td> - <p>A boolean value that indicates whether all shared libraries can be - searched in the <code><var>other</var></code> namespace when those libraries cannot - be found in the <code><var>name</var></code> namespace.</p> - - <p>This property cannot be used with - <code>namespace.<wbr/><var>name</var>.<wbr/>link.<wbr/><var>other</var>.<wbr/>shared_libs</code>.</p> - </td> - - <td> - <p><code>namespace.<wbr/>vndk.<wbr/>link.<wbr/>sphal.<wbr/>allow_all_shared_libs = true</code></p> - - <p>This indicates all library names can walk through the fallback link - from <code>vndk</code> to <code>sphal</code> namespace.</p> - </td> - </tr> -</table> - - - -<h3 id="namespace-properties">Namespace properties</h3> - -<table> - <tr> - <th>Property</th> - <th>Description</th> - <th>Example</th> - </tr> - - <tr> - <td><code>namespace.<wbr/><var>name</var>.<wbr/>isolated</code></td> - - <td> - <p>A boolean value that indicates whether the dynamic linker should check - where the shared library resides.</p> - - <p>If <code>isolated</code> is <code>true</code>, only the shared libraries - that are <em>in</em> one of the <code>search.paths</code> directories - (excluding sub-directories) or are <em>under</em> one of the - <code>permitted.paths</code> directories (including sub-directories) can be - loaded.</p> - - <p>If <code>isolated</code> is <code>false</code> (default), the dynamic - linker doesn't check the path of shared libraries.</p> - </td> - - <td> - <p><code>namespace.<wbr/>sphal.<wbr/>isolated = true</code></p> - - <p>This indicates that only the shared libraries in - <code>search.paths</code> or under <code>permitted.paths</code> can be - loaded into the <code>sphal</code> namespace.</p> - </td> - </tr> - - <tr> - <td><code>namespace.<wbr/><var>name</var>.<wbr/>search.paths</code></td> - - <td> - <p>A colon-separated list of directories to search for shared - libraries.</p> - - <p>The directories specified in <code>search.paths</code> are prepended - to the requested library name if function calls to <code>dlopen()</code> or - <code>DT_NEEDED</code> entries do not specify the full path. The directory - specified at the beginning of the list has higher priority.</p> - - <p>When <code>isolated</code> is <code>true</code>, shared libraries that - are <em>in</em> one of the <code>search.paths</code> directories (excluding - sub-directories) can be loaded regardless the <code>permitted.paths</code> - property.</p> - - <p>For example, if <code>search.paths</code> is - <code>/system/${LIB}</code> and <code>permitted.paths</code> is empty, - <code>/system/${LIB}/libc.so</code> can be loaded but - <code>/system/${LIB}/vndk/libutils.so</code> cannot be loaded.</p> - - <aside class="note">Note: <code>${LIB}</code> is a built-in - placeholder. It is replaced by <code>lib</code> for 32-bit processes and - <code>lib64</code> for 64-bit processes.</aside> - </td> - - <td> - <p><code>namespace.<wbr/>default.<wbr/>search.paths = /system/${LIB}</code></p> - - <p>This indicates that the dynamic linker searches - <code>/system/${LIB}</code> for shared libraries.</p> - </td> - </tr> - - <tr> - <td><code>namespace.<wbr/><var>name</var>.<wbr/>asan.search.paths</code></td> - - <td> - <p>A colon-separated list of directories to search for shared libraries when - <a href="/devices/tech/debug/asan">Address Sanitizer</a> is enabled.</p> - - <p><code>namespace.<wbr/><var>name</var>.<wbr/>search.paths</code> is - ignored when <a href="/devices/tech/debug/asan">Address Sanitizer</a> is - enabled.</p> - </td> - - <td> - <p><code>namespace.<wbr/>default.<wbr/>asan.search.paths = /data/asan/system/${LIB}:<wbr/>/system/${LIB}</code></p> - - <p>This indicates that when - <a href="/devices/tech/debug/asan">Address Sanitizer</a> is enabled the - dynamic linker searches <code>/data/asan/system/${LIB}</code> first and - then searches <code>/system/${LIB}</code>.</p> - </td> - </tr> - - <tr> - <td><code>namespace.<wbr/><var>name</var>.<wbr/>permitted.paths</code></td> - - <td> - <p>A colon-separated list of directories (including sub-directories) where - the dynamic linker can load the shared libraries (in addition to - <code>search.paths</code>) when <code>isolated</code> is - <code>true</code>.</p> - - <p>The shared libraries that are under the sub-directories of - <code>permitted.paths</code> can be loaded too. For example, if - <code>permitted.paths</code> is <code>/system/${LIB}</code>, - both <code>/system/${LIB}/libc.so</code> and - <code>/system/${LIB}/vndk/libutils.so</code> can be loaded.</p> - - <p>If <code>isolated</code> is <code>false</code>, - <code>permitted.paths</code> are ignored and a warning is emitted.</p> - - <aside class="note">Note: <code>permitted.paths</code> are NOT - prepended to the requested library names when the dynamic linker is - searching for a shared library. Its main purpose is to allow programers to - load shared libraries into an isolated namespace by specifying the full path - of the shared library.</aside> - </td> - - <td> - <p><code>namespace.<wbr/>default.<wbr/>permitted.paths = /system/${LIB}/hw</code></p> - - <p>This indicates that the shared libraries under - <code>/system/${LIB}/hw</code> can be loaded into the isolated - <code>default</code> namespace.</p> - - <p>For example, without <code>permitted.paths</code>, - <code>libaudiohal.so</code> won't be able to load - <code>/system/${LIB}/hw/audio.a2dp.default.so</code> into the - <code>default</code> namespace.</p> - </td> - </tr> - - <tr> - <td><code>namespace.<wbr/><var>name</var>.<wbr/>asan.permitted.paths</code></td> - - <td> - <p>A colon-separated list of directories where the dynamic linker can load - the shared libraries when <a href="/devices/tech/debug/asan">Address - Sanitizer</a> is enabled.</p> - - <p><code>namespace.<wbr/><var>name</var>.<wbr/>permitted.paths</code> is - ignored when <a href="/devices/tech/debug/asan">Address Sanitizer</a> is - enabled.</p> - </td> - - <td> - <p><code>namespace.<wbr/>default.<wbr/>asan.permitted.paths = /data/asan/system/${LIB}/hw:<wbr/>/system/${LIB}/hw</code></p> - - <p>This indicates that when - <a href="/devices/tech/debug/asan">Address Sanitizer</a> is enabled shared - libraries under <code>/data/asan/system/${LIB}/hw</code> or - <code>/system/${LIB}/hw</code> can be loaded to the isolated - <code>default</code> namespace.</p> - </td> - </tr> - - <tr> - <td><code>namespace.<wbr/><var>name</var>.<wbr/>visible</code></td> - - <td> - <p>A boolean value that indicates whether the program (other than - <code>libc</code>) can obtain a linker namespace handle with - <code>android_get_exported_namespace()</code> and open a shared library in - the linker namespace by passing the handle to - <code>android_dlopen_ext()</code>.</p> - - <p>If <code>visible</code> is <code>true</code>, - <code>android_get_exported_namespace()</code> always returns the handle if - the namespace exists.</p> - - <p>If <code>visible</code> is <code>false</code> (default), - <code>android_get_exported_namespace()</code> always returns - <code>NULL</code> regardless the presence of the namespace. Shared libraries - can only be loaded into this namespace if (1) they are requested by another - linker namespace that has a fallback link to this namespace or (2) they are - requested by other shared libraries or executables in this namespace.</p> - </td> - - <td> - <p><code>namespace.<wbr/>sphal.<wbr/>visible = true</code></p> - - <p>This indicates that <code>android_get_exported_namespace("sphal")</code> - can return a valid linker namespace handle.</p> - </td> - </tr> -</table> - - - - - -<h2 id="linker-namespace-isolation">Linker namespace isolation</h2> - -<p>There are three configuration files in -<code>${android-src}/system/core/rootdir/etc</code>. Depending on the value of -<code>PRODUCT_TREBLE_LINKER_NAMESPACES</code>, <code>BOARD_VNDK_VERSION</code>, -and <code>BOARD_VNDK_RUNTIME_DISABLE</code> in <code>BoardConfig.mk</code>, -different configurations are selected:</p> - -<table> - <tr> - <th><code>PRODUCT_TREBLE_</code><br/><code>LINKER_NAMESPACES</code></th> - <th><code>BOARD_VNDK_</code><br/><code>VERSION</code></th> - <th><code>BOARD_VNDK_</code><br/><code>RUNTIME_DISABLE</code></th> - <th>Selected configuration</th> - <th>VTS Requirement</th> - </tr> - - <tr> - <td rowspan="3"><code>true</code></td> - <td rowspan="2"><code>current</code></td> - <td><em>empty</em></td> - <td><code>ld.config.txt</code></td> - <td>Mandatory for devices launched with Android P.</td> - </tr> - - <tr> - <td><code>true</code></td> - <td rowspan="2"><code>ld.config.vndk_lite.txt</code></td> - <td rowspan="2">Mandatory for devices launched with Android 8.x.</td> - </tr> - - <tr> - <td><em>empty</em></td> - <td><em>any</em></td> - </tr> - - <tr> - <td><code>false</code></td> - <td><em>any</em></td> - <td><em>any</em></td> - <td><code>ld.config.legacy.txt</code></td> - <td>For non-Treble devices</td> - </tr> -</table> - -<p><code>${android-src}/system/core/rootdir/etc/ld.config.vndk_lite.txt</code> -isolates SP-HAL and VNDK-SP shared libraries. In Android 8.0 and higher, this -must be the configuration file for dynamic linker when -<code>PRODUCT_TREBLE_LINKER_NAMESPACES</code> is <code>true</code>.</p> - -<p><code>${android-src}/system/core/rootdir/etc/ld.config.txt</code> isolates -SP-HAL and VNDK-SP shared libraries as well. In addition, -<code>ld.config.txt</code> also provides the full dynamic linker isolation. -It makes sure that modules in the system partition won't depend on the shared -libraries in the vendor partitions and vice versa.</p> - -<p>In Android 8.1, <code>ld.config.txt</code> is the default configuration file -and it is highly recommended to enable full dynamic linker isolation. However, -if there are too many dependencies to be cleaned up in Android 8.1, you may add -<code>BOARD_VNDK_RUNTIME_DISABLE</code> to <code>BoardConfig.mk</code>:</p> - -<pre class="prettyprint"> -BOARD_VNDK_RUNTIME_DISABLE := true -</pre> - -<p>If <code>BOARD_VNDK_RUNTIME_DISABLE</code> is <code>true</code>, -<code>${android-src}/system/core/rootdir/etc/ld.config.vndk_lite.txt</code> -is installed.</p> - - - -<h3 id="ld.config.txt">ld.config.txt</h3> - -<p><code>ld.config.txt</code> isolates the shared library dependencies -between the system partition and vendor partitions. Compared to -<code>ld.config.txt</code> mentioned in previous subsection, the differences -are outlined as following items:</p> - -<ul> - <li> - <p>Framework Processes</p> - - <ul> - <li>Four namespaces (<code>default</code>, <code>vndk</code>, - <code>sphal</code>, and <code>rs</code>) are created.</li> - - <li>All namespaces are isolated.</li> - - <li>System shared libraries are loaded into the <code>default</code> - namespace.</li> - - <li>SP-HALs are loaded into the <code>sphal</code> namespace.</li> - - <li>VNDK-SP shared libraries loaded into the <code>vndk</code> - namespace.</li> - </ul> - </li> - - <li> - <p>Vendor Processes</p> - - <ul> - <li>Three namespaces (<code>default</code>, <code>vndk</code>, and - <code>system</code>) are created.</li> - - <li>The <code>default</code> namespace is isolated.</li> - - <li>Vendor shared libraries are loaded into the <code>default</code> - namespace.</li> - - <li>VNDK and VNDK-SP shared libraries are loaded into the <code>vndk</code> - namespace.</li> - - <li>LL-NDK and their dependencies are loaded into the <code>system</code> - namespace.</li> - </ul> - </li> -</ul> - -<p>The relationship between the linker namespaces is depicted in the figure -below:</p> - -<img src="../images/treble_vndk_linker_namespace3.png" - alt="Linker namespace graph described in ld.config.txt" /> -<figcaption> - <strong>Figure 1.</strong> Linker namespace isolation - (<code>ld.config.txt</code>) -</figcaption> - - -<p>In the graph above, <em>LL-NDK</em> and <em>VNDK-SP</em> stand for following -shared libraries:</p> - -<ul> - <li> - <em>LL-NDK</em> - - <ul> - <li><code>libEGL.so</code></li> - <li><code>libGLESv1_CM.so</code></li> - <li><code>libGLESv2.so</code></li> - <li><code>libGLESv3.so</code></li> - <li><code>libandroid_net.so</code></li> - <li><code>libc.so</code></li> - <li><code>libdl.so</code></li> - <li><code>liblog.so</code></li> - <li><code>libm.so</code></li> - <li><code>libnativewindow.so</code></li> - <li><code>libneuralnetworks.so</code></li> - <li><code>libsync.so</code></li> - <li><code>libvndksupport.so</code></li> - <li><code>libvulkan.so</code></li> - </ul> - </li> - - <li> - <em>VNDK-SP</em> - - <ul> - <li><code>android.hardware.graphics.common@1.0.so</code></li> - <li><code>android.hardware.graphics.mapper@2.0.so</code></li> - <li><code>android.hardware.renderscript@1.0.so</code></li> - <li><code>android.hidl.memory@1.0.so</code></li> - <li><code>libRSCpuRef.so</code></li> - <li><code>libRSDriver.so</code></li> - <li><code>libRS_internal.so</code></li> - <li><code>libbase.so</code></li> - <li><code>libbcinfo.so</code></li> - <li><code>libc++.so</code></li> - <li><code>libcutils.so</code></li> - <li><code>libhardware.so</code></li> - <li><code>libhidlbase.so</code></li> - <li><code>libhidlmemory.so</code></li> - <li><code>libhidltransport.so</code></li> - <li><code>libhwbinder.so</code></li> - <li><code>libion.so</code></li> - <li><code>libutils.so</code></li> - <li><code>libz.so</code></li> - </ul> - </li> -</ul> - -<p>The table below presents the namespaces configuration for framework -processes, which is excerpted from the <code>[system]</code> section in -<code>ld.config.txt</code>:</p> - -<table> - <tr> - <th>Namespace</th> - <th>Property</th> - <th>Value</th> - </tr> - - <tr> - <td rowspan="3"><code>default</code></td> - <td><code>search.paths</code></td> - <td> - <code>/system/${LIB}</code><br/> - <code>/product/${LIB}</code> - </td> - </tr> - - <tr> - <td><code>permitted.paths</code></td> - <td> - <code>/system/${LIB}/drm</code><br/> - <code>/system/${LIB}/extractors</code><br/> - <code>/system/${LIB}/hw</code><br/> - <code>/product/${LIB}</code><br/> - <code>/system/framework</code><br/> - <code>/system/app</code><br/> - <code>/system/priv-app</code><br/> - <code>/vendor/app</code><br/> - <code>/vendor/priv-app</code><br/> - <code>/oem/app</code><br/> - <code>/odm/priv-app</code><br/> - <code>/oem/app</code><br/> - <code>/product/framework</code><br/> - <code>/product/app</code><br/> - <code>/product/priv-app</code><br/> - <code>/data</code><br/> - <code>/mnt/expand</code> - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td rowspan="8"><code>sphal</code></td> - <td><code>search.paths</code></td> - <td> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code> - </td> - </tr> - - <tr> - <td><code>permitted.paths</code></td> - <td> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code> - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>visible</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>links</code></td> - <td><code>default,vndk,rs</code></td> - </tr> - - <tr> - <td><code>link.default.shared_libs</code></td> - <td><em>LL-NDK</em></td> - </tr> - - <tr> - <td><code>link.vndk.shared_libs</code></td> - <td><em>VNDK-SP</em></td> - </tr> - - <tr> - <td><code>link.rs.shared_libs</code></td> - <td><code>libRS_internal.so</code></td> - </tr> - - <tr> - <td rowspan="7"><code>vndk</code> (For VNDK-SP)</td> - <td><code>search.paths</code></td> - <td> - <code>/odm/${LIB}/vndk-sp</code><br/> - <code>/vendor/${LIB}/vndk-sp</code><br/> - <code>/system/${LIB}/vndk-sp-${VER}</code> - </td> - </tr> - - <tr> - <td><code>permitted.paths</code></td> - <td> - <code>/odm/${LIB}/hw</code><br/> - <code>/odm/${LIB}/egl</code><br/> - <code>/vendor/${LIB}/hw</code><br/> - <code>/vendor/${LIB}/egl</code><br/> - <code>/system/${LIB}/vndk-sp-${VER}/hw</code> - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>visible</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>links</code></td> - <td><code>default</code>, <code>sphal</code></td> - </tr> - - <tr> - <td><code>link.default.shared_libs</code></td> - <td><em>LL-NDK</em></td> - </tr> - - <tr> - <td><code>link.default.allow_all_shared_libs</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td rowspan="7"><code>rs</code> (For Renderscript)</td> - <td><code>search.paths</code></td> - <td> - <code>/odm/${LIB}/vndk-sp</code><br/> - <code>/vendor/${LIB}/vndk-sp</code><br/> - <code>/system/${LIB}/vndk-sp-${VER}</code><br/> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code> - </td> - </tr> - - <tr> - <td><code>permitted.paths</code></td> - <td> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code><br/> - <code>/data</code> (For compiled RS kernel) - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>visible</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>links</code></td> - <td><code>default,vndk</code></td> - </tr> - - <tr> - <td><code>link.default.shared_libs</code></td> - <td> - <em>LL-NDK</em><br/> - <code>libmediandk.so</code><br/> - <code>libft2.so</code> - </td> - </tr> - - <tr> - <td><code>link.vndk.shared_libs</code></td> - <td><em>VNDK-SP</em></td> - </tr> -</table> - -<p>The table below presents the namespaces configuration for vendor processes, -which is excerpted from the <code>[vendor]</code> section in -<code>ld.config.txt</code>:</p> - -<table> - <tr> - <th>Namespace</th> - <th>Property</th> - <th>Value</th> - </tr> - - <tr> - <td rowspan="7"><code>default</code></td> - <td><code>search.paths</code></td> - <td> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code> - </td> - </tr> - - <tr> - <td><code>permitted.paths</code></td> - <td> - <code>/odm</code><br/> - <code>/vendor</code><br/> - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>visible</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>links</code></td> - <td><code>system</code>, <code>vndk</code></td> - </tr> - - <tr> - <td><code>link.system.shared_libs</code></td> - <td><em>LL-NDK</em></td> - </tr> - - <tr> - <td><code>link.vndk.shared_libs</code></td> - <td><em>VNDK</em>, <em>VNDK-SP</em> (vendor available)</td> - </tr> - - <tr> - <td rowspan="5"><code>vndk</code></td> - <td><code>search.paths</code></td> - <td> - <code>/odm/${LIB}/vndk</code><br/> - <code>/odm/${LIB}/vndk-sp</code><br/> - <code>/vendor/${LIB}/vndk</code><br/> - <code>/vendor/${LIB}/vndk-sp</code><br/> - <code>/system/${LIB}/vndk-${VER}</code><br/> - <code>/system/${LIB}/vndk-sp-${VER}</code> - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>links</code></td> - <td><code>system</code>, <code>default</code></td> - </tr> - - <tr> - <td><code>link.system.shared_libs</code></td> - <td><em>LL-NDK</em></td> - </tr> - - <tr> - <td><code>link.default.allow_all_shared_libs</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td rowspan="2"><code>system</code></td> - <td><code>search.paths</code></td> - <td><code>/system/${LIB}</code></td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>false</code></td> - </tr> -</table> - - -<p>More details can be found in -<code>${android-src}/system/core/rootdir/etc/ld.config.txt</code>.</p> - - - -<h3 id="ld.config.vndk_lite.txt">ld.config.vndk_lite.txt</h3> - -<p>As of Android 8.0, the dynamic linker is configured to isolate SP-HAL and -VNDK-SP shared libraries such that their symbols do not conflict with other -framework shared libraries. The relationship between the linker namespaces is -shown below:</p> - -<img src="../images/treble_vndk_linker_namespace1.png" - alt="Linker namespace graph described in ld.config.vndk_lite.txt" /> -<figcaption> - <strong>Figure 2.</strong> Linker namespace isolation - (<code>ld.config.vndk_lite.txt</code>) -</figcaption> - -<p><em>LL-NDK</em> and <em>VNDK-SP</em> stand for following shared libraries: -</p> - -<ul> - <li> - <em>LL-NDK</em> - - <ul> - <li><code>libEGL.so</code></li> - <li><code>libGLESv1_CM.so</code></li> - <li><code>libGLESv2.so</code></li> - <li><code>libc.so</code></li> - <li><code>libdl.so</code></li> - <li><code>liblog.so</code></li> - <li><code>libm.so</code></li> - <li><code>libnativewindow.so</code></li> - <li><code>libstdc++.so</code> (Not in <code>ld.config.txt</code>)</li> - <li><code>libsync.so</code></li> - <li><code>libvndksupport.so</code></li> - <li><code>libz.so</code> (Moved to <em>VNDK-SP</em> in - <code>ld.config.txt</code>)</li> - </ul> - </li> - - <li> - <em>VNDK-SP</em> - - <ul> - <li><code>android.hardware.graphics.common@1.0.so</code></li> - <li><code>android.hardware.graphics.mapper@2.0.so</code></li> - <li><code>android.hardware.renderscript@1.0.so</code></li> - <li><code>android.hidl.memory@1.0.so</code></li> - <li><code>libbase.so</code></li> - <li><code>libc++.so</code></li> - <li><code>libcutils.so</code></li> - <li><code>libhardware.so</code></li> - <li><code>libhidlbase.so</code></li> - <li><code>libhidlmemory.so</code></li> - <li><code>libhidltransport.so</code></li> - <li><code>libhwbinder.so</code></li> - <li><code>libion.so</code></li> - <li><code>libutils.so</code></li> - </ul> - </li> -</ul> - -<p>The table below presents the namespaces configuration for framework -processes, which is excerpted from the <code>[system]</code> section in -<code>ld.config.vndk_lite.txt</code>:</p> - -<table> - <tr> - <th>Namespace</th> - <th>Property</th> - <th>Value</th> - </tr> - - <tr> - <td rowspan="2"><code>default</code></td> - <td><code>search.paths</code></td> - <td> - <code>/system/${LIB}</code><br/> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code><br/> - <code>/product/${LIB}</code> - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>false</code></td> - </tr> - - <tr> - <td rowspan="8"><code>sphal</code></td> - <td><code>search.paths</code></td> - <td> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code> - </td> - </tr> - - <tr> - <td><code>permitted.paths</code></td> - <td> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code> - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>visible</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>links</code></td> - <td><code>default,vndk,rs</code></td> - </tr> - <tr> - <td><code>link.default.shared_libs</code></td> - <td><em>LL-NDK</em></td> - </tr> - <tr> - <td><code>link.vndk.shared_libs</code></td> - <td><em>VNDK-SP</em></td> - </tr> - <tr> - <td><code>link.rs.shared_libs</code></td> - <td><code>libRS_internal.so</code></td> - </tr> - - <tr> - <td rowspan="6"><code>vndk</code> (For VNDK-SP)</td> - <td><code>search.paths</code></td> - <td> - <code>/odm/${LIB}/vndk-sp</code><br/> - <code>/vendor/${LIB}/vndk-sp</code><br/> - <code>/system/${LIB}/vndk-sp-${VER}</code> - </td> - </tr> - - <tr> - <td><code>permitted.paths</code></td> - <td> - <code>/odm/${LIB}/hw</code><br/> - <code>/odm/${LIB}/egl</code><br/> - <code>/vendor/${LIB}/hw</code><br/> - <code>/vendor/${LIB}/egl</code><br/> - <code>/system/${LIB}/vndk-sp-${VER}/hw</code><br/> - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>visible</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>links</code></td> - <td><code>default</code></td> - </tr> - - <tr> - <td><code>link.default.shared_libs</code></td> - <td><em>LL-NDK</em></td> - </tr> - - <tr> - <td rowspan="7"><code>rs</code> (For Renderscript)</td> - <td><code>search.paths</code></td> - <td> - <code>/odm/${LIB}/vndk-sp</code><br/> - <code>/vendor/${LIB}/vndk-sp</code><br/> - <code>/system/${LIB}/vndk-sp-${VER}</code><br/> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code> - </td> - </tr> - - <tr> - <td><code>permitted.paths</code></td> - <td> - <code>/odm/${LIB}</code><br/> - <code>/vendor/${LIB}</code><br/> - <code>/data</code> (For compiled RS kernel) - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>visible</code></td> - <td><code>true</code></td> - </tr> - - <tr> - <td><code>links</code></td> - <td><code>default,vndk</code></td> - </tr> - - <tr> - <td><code>link.default.shared_libs</code></td> - <td> - <em>LL-NDK</em><br/> - <code>libmediandk.so</code><br/> - <code>libft2.so</code> - </td> - </tr> - - <tr> - <td><code>link.vndk.shared_libs</code></td> - <td><em>VNDK-SP</em></td> - </tr> -</table> - -<p>The table below presents the namespaces configuration for vendor processes, -which is excerpted from the <code>[vendor]</code> section in -<code>ld.config.vndk_lite.txt</code>:</p> - -<table> - <tr> - <th>Namespace</th> - <th>Property</th> - <th>Value</th> - </tr> - - <tr> - <td rowspan="2"><code>default</code></td> - <td><code>search.paths</code></td> - <td> - <code>/odm/${LIB}</code><br/> - <code>/odm/${LIB}/vndk</code><br/> - <code>/odm/${LIB}/vndk-sp</code><br/> - <code>/vendor/${LIB}</code><br/> - <code>/vendor/${LIB}/vndk</code><br/> - <code>/vendor/${LIB}/vndk-sp</code><br/> - <code>/system/${LIB}/vndk-${VER}</code><br/> - <code>/system/${LIB}/vndk-sp-${VER}</code><br/> - <code>/system/${LIB}</code> (Deprecated)<br/> - <code>/product/${LIB}</code> (Deprecated) - </td> - </tr> - - <tr> - <td><code>isolated</code></td> - <td><code>false</code></td> - </tr> -</table> - -<p>More details can be found in -<code>${android-src}/system/core/rootdir/etc/ld.config.vndk_lite.txt</code>.</p> - - - - - -<h2 id="document-history">Document history</h2> - -<h3 id="changes-p">Android P changes</h3> - -<ul> - <li><p>In Android P, the <code>vndk</code> linker namespace is added to vendor - processes and VNDK shared libraries are isolated from the default linker - namespace.</p></li> - - <li><p>Replace <code>PRODUCT_FULL_TREBLE</code> with more specific - <code>PRODUCT_TREBLE_LINKER_NAMESPACES</code>.</p></li> - - <li> - <p>Android P changes the names of the following dynamic linker configuration - files:</p> - - <table> - <tr> - <th>Android 8.x</th> - <th>Android P</th> - <th>Description</th> - </tr> - - <tr> - <td>ld.config.txt.in</td> - <td>ld.config.txt</td> - <td>For devices with runtime linker namespace isolation</td> - </tr> - - <tr> - <td>ld.config.txt</td> - <td>ld.config.vndk_lite.txt</td> - <td>For devices with VNDK-SP linker namespace isolation</td> - </tr> - - <tr> - <td>ld.config.legacy.txt</td> - <td>ld.config.legacy.txt</td> - <td>For legacy devices running Android 7.x and earlier</td> - </tr> - </table> - </li> - - <li><p>Remove <code>android.hardware.graphics.allocator@2.0.so</code>.</p></li> - - <li><p><code>product</code> and <code>odm</code> partitions are added.</p></li> -</ul> - - </body> -</html> diff --git a/en/devices/architecture/vndk/renderscript.html b/en/devices/architecture/vndk/renderscript.html deleted file mode 100644 index 873b24a2..00000000 --- a/en/devices/architecture/vndk/renderscript.html +++ /dev/null @@ -1,562 +0,0 @@ -<html devsite> - <head> - <title>Renderscript</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> - <em>RenderScript</em> is a framework for running computationally intensive - tasks at high performance on Android. It is designed for use with - data-parallel computation, although serial workloads can benefit as well. The - RenderScript runtime parallelizes work across processors available on a - device, such as multi-core CPUs and GPUs, enabling developers to focus on - expressing algorithms rather than scheduling work. RenderScript is especially - useful for applications performing image processing, computational - photography, or computer vision. -</p> - -<p> - Devices running Android 8.0 and higher use the following RenderScript - framework and vendor HALs: -</p> - -<img src="../images/treble_rs_linking.png"> -<figcaption> - <strong>Figure 1.</strong> Vendor code linking to internal libs -</figcaption> - -<p> - Differences from RenderScript in Android 7.x and lower include: -</p> - -<ul> - <li>Two instances of RenderScript internal libs in a process. One set is for - CPU fallback path and is from directly at <code>/system/lib</code>; the other - set is for GPU path and is from <code>/system/lib/vndk-sp</code>.</li> - <li>RS internal libs in <code>/system/lib</code> are built as part of the - platform and are updated as <code>system.img</code> is upgraded. However, libs - in <code>/system/lib/vndk-sp</code> are built for the vendor and are not - updated when <code>system.img</code> is upgraded (while they can be updated - for a security fix, their ABI remains the same).</li> - <li>Vendor code (RS HAL, RS driver, and the <code>bcc plugin</code>) are - linked against the RenderScript internal libs located at - <code>/system/lib/vndk-sp</code>. They cannot link against libs in - <code>/system/lib</code> because libs in that directory are built for the - platform and thus may not be compatible with the vendor code (i.e., symbols - may be removed). Doing so would make a framework-only OTA impossible.</li> -</ul> - -<p> - For more details, see - <a href="https://developer.android.com/guide/topics/renderscript/compute.html" class="external">Renderscript</a> - on developer.android.com. -</p> - -<h2 id="design">Design</h2> - -<p> - The following sections detail RenderScript design in Android 8.0 and higher. -</p> - -<h3 id="renderscript-libs-available-to-vendors">RenderScript libs available to -vendors</h3> - -<p> - This section lists the RenderScript libs (known as Vendor NDK for Same-Process - HALs or VNDK-SP) that are available to vendor code and which can be linked - against. It also details additional libraries that are unrelated to - RenderScript but which are also provided to vendor code. -</p> - -<p> - While the following list of libraries might differ between Android releases, - it is immutable for a specific Android release; for an up-to-date list of - available libraries, refer to <code>/system/etc/ld.config.txt</code>. -</p> - -<aside class="note"> - <strong>Note:</strong> Libraries not listed below cannot be used by any vendor - code; i.e. <code>libLLVM.so</code> cannot be used by the vendor's - <code>bcc plugin</code> as the lib is not in the list. -</aside> - -<table> -<tr> -<th style="width:50%">RenderScript Libs</th> -<th>Non-RenderScript Libs</th> -</tr> -<tr> -<td><ul> -<li><code>android.hardware.graphics.renderscript@1.0.so</code></li> -<li><code>libRS_internal.so</code></li> -<li><code>libRSCpuRef.so</code></li> -<li><code>libblas.so</code></li> -<li><code>libbcinfo.so</code></li> -<li><code>libcompiler_rt.so</code></li> -<li><code>libRSDriver.so</code></li> -</ul></td> -<td><ul> -<li><code>libc.so</code></li> -<li><code>libm.so</code></li> -<li><code>libdl.so</code></li> -<li><code>libstdc++.so</code></li> -<li><code>liblog.so</code></li> -<li><code>libnativewindow.so</code></li> -<li><code>libsync.so</code></li> -<li><code>libvndksupport.so</code></li> -<li><code>libbase.so</code></li> -<li><code>libc++.so</code></li> -<li><code>libcutils.so</code></li> -<li><code>libutils.so</code></li> -<li><code>libhardware.so</code></li> -<li><code>libhidlbase.so</code></li> -<li><code>libhidltransport.so</code></li> -<li><code>libhwbinder.so</code></li> -<li><code>liblzma.so</code></li> -<li><code>libz.so</code></li> -<li><code>libEGL.so</code></li> -<li><code>libGLESv1_CM.so</code></li> -<li><code>libGLESv2.so</code></li> -</ul></td> - </tr> -</table> - -<h3 id="linker-namespace-configuration">Linker namespace configuration</h3> - -<p> - The linking restriction that prevents libs not in VNDK-SP from being used by - vendor code is enforced at runtime using the linker namespace. (For details, - refer to the <a href="/devices/architecture/images/VNDK.pdf">VNDK Design</a> - presentation.) -</p> - -<p> - On a device running Android 8.0 and higher, all Same-Process HALs (SP-HALs) - <em>except RenderScript</em> are loaded inside the linker namespace - <code>sphal</code>. RenderScript is loaded into the RenderScript-specific - namespace <code>rs</code>, a location that enables a slightly looser - enforcement for RenderScript libs. Because the RS implementation needs to load - the compiled bitcode, <code>/data/*/*.so</code> is added to the path of the - <code>rs</code> namespace (other SP-HALs are not allowed to load libs from the - data partition). -</p> - -<p> - In addition, the <code>rs</code> namespace allows more libs than provided for - by other namespaces. <code>libmediandk.so</code> and <code>libft2.so</code> - are exposed to the <code>rs</code> namespace because - <code>libRS_internal.so</code> has an internal dependency to these libraries. -</p> - -<img src="../images/treble_rs_namespace.png"> -<figcaption> - <strong>Figure 2.</strong> Namespace configuration for linker -</figcaption> - -<h3 id="loading-drivers">Loading drivers</h3> - -<h4>CPU fallback path</h4> - -<p> - Depending on the existence of the <code>RS_CONTEXT_LOW_LATENCY</code> bit - when creating an RS context, either the CPU or GPU path is selected. When the - CPU path is selected, <code>libRS_internal.so</code> (the main implementation - of the RS framework) is directly <code>dlopen</code>ed from the default linker - namespace where the platform version of RS libs are provided. -</p> - -<p> - The RS HAL implementation from the vendor is not used at all when the CPU - fallback path is taken, and an <code>RsContext</code> object is created with - null <code>mVendorDriverName</code>. <code>libRSDriver.so</code> is (by - default) <code>dlopen</code>ed and the driver lib is loaded from the - <code>default</code> namespace because the caller - (<code>libRS_internal.so</code>) is also loaded in the <code>default</code> - namespace. -</p> - -<img src="../images/treble_rs_cpu_fallback.png"> -<figcaption> - <strong>Figure 4.</strong> CPU fallback path -</figcaption> - -<h4 id="gpu-path">GPU path</h4> - -<p> - For the GPU path, the <code>libRS_internal.so</code> is loaded differently. - First, <code>libRS.so</code> uses - <code>android.hardware.renderscript@1.0.so</code> (and its underlying - <code>libhidltransport.so</code>) to load - <code>android.hardware.renderscript@1.0-impl.so</code> (a vendor - implementation of RS HAL) into a different linker namespace called - <code>sphal</code>. The RS - HAL then <code>dlopen</code>s <code>libRS_internal.so</code> in a another - linker namespace called <code>rs</code>. -</p> - -<p> - Vendors can provide their own RS driver by setting the build time flag - <code>OVERRIDE_RS_DRIVER</code>, which is embedded into the RS HAL - implementation - (<code>hardware/interfaces/renderscript/1.0/default/Context.cpp</code>). This - driver name is then <code>dlopen</code>ed for the RS context for the GPU path. -</p> - -<p> - The creation of the <code>RsContext</code> object is delegated to the RS HAL - implementation. The HAL calls back to the RS framework using - <code>rsContextCreateVendor()</code> function with the name of the driver to - use as an argument. The RS framework then loads the specified driver when the - <code>RsContext</code> is initialized. In this case, the driver library is - loaded into the <code>rs</code> namespace because the <code>RsContext</code> - object is created inside the <code>rs</code> namespace and - <code>/vendor/lib</code> is in the search path of the namespace. -</p> - -<img src="../images/treble_rs_gpu_fallback.png"> -<figcaption> - <strong>Figure 5.</strong> GPU fallback path -</figcaption> - -<p> - When transitioning from the <code>default</code> namespace to the - <code>sphal</code> namespace, <code>libhidltransport.so</code> uses the - <code>android_load_sphal_library()</code> function to explicitly order the - dynamic linker to load the <code>-impl.so</code> library from the - <code>sphal</code> namespace. -</p> - -<p> - When transitioning from the <code>sphal</code> namespace to the - <code>rs</code> namespace, loading is done indirectly by the following line in - <code>/system/etc/ld.config.txt</code>: -</p> - -<pre class="prettyprint"> -namespace.sphal.link.rs.shared_libs = libRS_internal.so -</pre> - -<p> - This line specifies the dynamic linker should load - <code>libRS_internal.so</code> from the <code>rs</code> namespace when the lib - can't be found/loaded from the <code>sphal</code> namespace (which is always - the case because <code>sphal</code> namespace does not search - <code>/system/lib/vndk-sp</code> where <code>libRS_internal.so</code> - resides). With this configuration, a simple <code>dlopen()</code> call to - <code>libRS_internal.so</code> is enough to make the namespace transition. -</p> - -<h3 id="loading-bcc-plugin">Loading bcc plugin</h3> - -<p> - <code>bcc plugin</code> is a vendor-provided library loaded into the - <code>bcc</code> compiler. Because <code>bcc</code> is a system process in the - <code>/system/bin</code> directory, the <code>bcc plugin</code> library can be - considered an SP-HAL (i.e., a vendor HAL that can be directly loaded into the - system process without being binderized). As an SP-HAL, the - <code>bcc-plugin</code> library: -</p> - -<ul> - <li>Cannot link against framework-only libraries such as - <code>libLLVM.so</code>.</li> - <li>Can link against only the VNDK-SP libraries available to the vendor.</li> -</ul> - -<p> - This restriction is enforced by loading the <code>bcc plugin</code> into the - <code>sphal</code> namespace using the - <code>android_sphal_load_library()</code> function. In previous versions of - Android, the plugin name was specified using the <code>-load</code> option and - the lib was loaded using the simple <code>dlopen()</code> by - <code>libLLVM.so</code>. In Android 8.0 and higher, this is specified in the - <code>-plugin</code> option and the lib is directly loaded by the - <code>bcc</code> itself. This option enables a non-Android-specific path to - the open source LLVM project. -</p> - -<img src="../images/treble_rs_bcc_plugin_old.png"> -<figcaption> - <strong>Figure 6.</strong> Loading bcc plugin, Android 7.x and lower -</figcaption> -<br> -<br> -<img src="../images/treble_rs_bcc_plugin_new.png"> - <figcaption><strong>Figure 7.</strong> Loading bcc plugin, Android 8.0 and - higher -</figcaption> - -<h3 id="search-paths-for-ld-mc">Search paths for ld.mc</h3> - -<p> - When executing <code>ld.mc</code>, some RS runtime libs are given as inputs - to the linker. The RS bitcode from the app is linked against the runtime libs - and when the converted bitcode is loaded into an app process, the runtime libs - are again dynamically linked from the converted bitcode. -</p> - -<p>Runtime libs include:</p> - -<ul> - <li><code>libcompiler_rt.so</code></li> - <li><code>libm.so</code></li> - <li><code>libc.so</code></li> - <li>RS driver (either <code>libRSDriver.so</code> or - <code>OVERRIDE_RS_DRIVER</code>)</li> -</ul> - -<p> - When loading the compiled bitcode into the app process, provide the exact same - library that was used by <code>ld.mc</code>. Otherwise, the compiled bitcode - may not find a symbol which was available when it was linked. -</p> - -<p> - To do so, RS framework uses different search paths for the runtime libs when - executing <code>ld.mc</code>, depending on whether the RS framework itself is - loaded from <code>/system/lib</code> or from <code>/system/lib/vndk-sp</code>. - This can be determined by reading the address of an arbitrary symbol of a RS - framework lib and using <code>dladdr()</code> to get the file path mapped to - the address. -</p> - -<h3 id="selinux-policy">SELinux policy</h3> - -<p> - As a result of the SELinux policy changes in Android 8.0 and higher, you must - follow specific rules (enforced through <code>neverallows</code>) when - labelling additional files in <code>vendor</code> partition: -</p> - -<ul> - <li><code>vendor_file</code> must be the default label in for all files in - <code>vendor</code> partition. The platform policy requires this to access - passthrough HAL implementations.</li> - <li>All new <code>exec_types</code> added in <code>vendor</code> partition - through vendor SEPolicy must have <code>vendor_file_type</code> attribute. - This is enforced through <code>neverallows</code>.</li> - <li>To avoid conflicts with future platform/framework updates, avoid labelling - files other than <code>exec_types</code> in <code>vendor</code> partition. - </li> - <li>All library dependencies for AOSP-identified same process HALs must be - labelled as <code>same_process_hal_file</code>.</li> -</ul> - -<p> - For details on SELinux policy, see - <a href="/security/selinux/">Security-Enhanced Linux in Android</a>. -</p> - -<h3 id="abi-compatibility-for-bitcode">ABI compatibility for bitcode</h3> - -<p> - If no new APIs are added, which means no HAL version bump, the RS frameworks - will keep using the existing GPU (HAL 1.0) driver. -</p> - -<p> - For minor HAL changes (HAL 1.1) not affecting bitcode, the frameworks should - fallback to CPU for these newly added APIs and keep using GPU (HAL 1.0) driver - elsewhere. -</p> - -<p> - For major HAL changes (HAL 2.0) affecting bitcode compilation/linking, RS - frameworks should choose not to load vendor-provided GPU drivers and instead - use the CPU or Vulkan path for acceleration. -</p> - -<p>Consuming RenderScript bitcode occurs in three stages:</p> - -<table> -<tr> -<th>Stage</th> -<th>Details</th> -</tr> -<tr> -<td><em>Compile</em></td> -<td> - <ul> - <li>The input bitcode (.bc) for <code>bcc</code> must be in - <code>LLVM 3.2</code> bitcode format and <code>bcc</code> must be backward - compatible with existing (legacy) apps.</li> - <li>However, the meta-data in .bc could change (there could new runtime - functions, e.g, Allocation setters ∓ getters, math functions, etc.). Part - of the runtime functions lives in <code>libclcore.bc</code>, part of them - lives in LibRSDriver or vendor equivalent.</li> - <li>New runtime functions or breaking meta-data changes require incrementing - the bitcode API level. Because vendor drivers won't be able to consume it, - the HAL version must also be incremented.</li> - <li>Vendors may have their own compilers, but the conclusions/requirements - for <code>bcc</code> also apply to those compilers.</li> - </ul> -</td> -</tr> -<tr> -<td><em>Link</em></td> -<td> - <ul> - <li>The compiled .o will be linked with vendor driver, e.g, - <code>libRSDriver_foo.so</code>, and <code>libcompiler_rt.so</code>. The CPU - path will link with <code>libRSDriver.so</code>.</li> - <li>If the .o requires a new runtime API from <code>libRSDriver_foo</code>, - the vendor driver has to be updated to support it.</li> - <li>Certain vendors may have their own linkers, but the argument for - <code>ld.mc</code> also apply to them.</li> - </ul> -</td> -</tr> -<tr> -<td><em>Load</em></td> -<td> - <ul> - <li><code>libRSCpuRef</code> loads the shared object. If there are - changes to this interface, a HAL version bump is needed.</li> - <li>Vendors would either rely on <code>libRSCpuRef</code> to load the shared - object, or implement their own.</li> - </ul> -</td> -</tr> -</table> - -<p> - In addition to the HAL, runtime APIs and the exported symbols are also - interfaces. Neither interface has changed since Android 7.0 (API 24) and there - are no immediate plans to change it in Android 8.0 and beyond. However, if the - interface does change, the HAL version will also increment. -</p> - -<h2 id="vendor-implementations">Vendor implementations</h2> - -<p> - Android 8.0 and higher requires some GPU driver changes for the GPU driver to - work correctly. -</p> - -<h3 id="driver-modules">Driver modules</h3> - -<ul> - <li>Driver modules must not depend on any system libraries that are not in - <a href="#renderscript-libs-available-to-vendors">the list</a>.</li> - <li>Driver must provide its own - <code>android.hardware.renderscript@1.0-impl_{NAME}</code>, or declare the - default implementation <code>android.hardware.renderscript@1.0-impl</code> as - its dependency.</li> - <li>CPU implementation <code>libRSDriver.so</code> is a good example of how to - remove non-VNDK-SP dependencies.</li> -</ul> - -<h3 id="bitcode-compiler">Bitcode compiler</h3> - -<p> - You can compile RenderScript bitcode for the vendor driver in two ways: -</p> - -<ol> - <li>Invoke vendor-specific RenderScript compiler in <code>/vendor/bin/</code> - (preferred method of GPU compilation). Similar to other driver modules, the - vendor compiler binary cannot depend on any system library that is not in the - list of <a href="#renderscript-libs-available-to-vendors">RenderScript libs - available to vendors</a>.</li> - <li>Invoke system bcc: <code>/system/bin/bcc</code> with a vendor-provided - <code>bcc plugin</code>; this plugin cannot depend on any system library that - is not in the list of - <a href="#renderscript-libs-available-to-vendors">RenderScript libs available - to vendors</a>.</li> -</ol> - -<p> - If the vendor <code>bcc plugin</code> needs to interfere with the CPU - compilation and its dependency on <code>libLLVM.so</code> cannot be easily - removed, the vendor should copy <code>bcc</code> (and all the non-LL-NDK - dependencies, including <code>libLLVM.so</code>, <code>libbcc.so</code>) into - <code>/vendor</code> partition. -</p> - -<p> - In addition, vendors need to make the following changes: -</p> - -<img src="../images/treble_rs_vendor_driver.png"> -<figcaption> - <strong>Figure 8.</strong> Changes to vendor driver -</figcaption> - -<ol> - <li>Copy <code>libclcore.bc</code> to <code>/vendor</code> partition. This - ensures <code>libclcore.bc</code>, <code>libLLVM.so</code>, and - <code>libbcc.so</code> are in sync.</li> - <li>Change the path to the <code>bcc</code> executable by setting - <code>RsdCpuScriptImpl::BCC_EXE_PATH</code> from the RS HAL implementation. - </li> -</ol> - -<aside class="note"> - <strong>Note:</strong> Restrictions for <code>/vendor/bin/*</code> processes - are not fully implemented. While not recommended, it is theoretically possible - to just copy <code>bcc</code> to <code>/vendor/bin/</code> without copying its - dependencies. -</aside> - -<h3 id="selinux-policy">SELinux policy</h3> - -<p> - SELinux policy affects both the driver and the compiler executables. All - driver modules must be labeled <code>same_process_hal_file</code> in the - device's <code>file_contexts</code>. For example: -</p> - -<pre class="prettyprint"> -/vendor/lib(64)?/libRSDriver_EXAMPLE\.so u:object_r:same_process_hal_file:s0 -</pre> - -<p> - The compiler executable must be able to be invoked by an app process, as does - the vendor copy of bcc (<code>/vendor/bin/bcc</code>). For example: -</p> - -<pre class="prettyprint"> -device/vendor_foo/device_bar/sepolicy/file_contexts: -/vendor/bin/bcc u:object_r:same_process_hal_file:s0 -</pre> - -<h3 id="legacy-devices">Legacy devices</h3> - -<p> - Legacy devices are those that satisfy the following conditions: -</p> - -<ol> - <li><em>PRODUCT_SHIPPING_API_LEVEL</em> is lower than 26.</li> - <li><em>PRODUCT_FULL_TREBLE_OVERRIDE</em> is not defined.</li> -</ol> - -<p> - For legacy devices, the restrictions are not enforced when upgrading to - Android 8.0 and higher, meaning the drivers can continue to link to libraries - in <code>/system/lib[64]</code>. However, because of the architecture change - related to <code>OVERRIDE_RS_DRIVER</code>, - <code>android.hardware.renderscript@1.0-impl</code> must be installed to - <code>/vendor</code> partition; failing to do so forces RenderScript runtime - fallback to CPU path. -</p> - - </body> -</html> diff --git a/en/devices/architecture/vndk/snapshot-design.html b/en/devices/architecture/vndk/snapshot-design.html deleted file mode 100644 index 1cee1f58..00000000 --- a/en/devices/architecture/vndk/snapshot-design.html +++ /dev/null @@ -1,249 +0,0 @@ -<html devsite> - <head> - <title>VNDK Snapshot Design</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - {% include "_versions.html" %} - <body> - <!-- - Copyright 2018 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> - VNDK snapshots can be used by a system image to provide the correct VNDK - libraries to vendor images even when system and vendor images are built from - different versions of Android. Creating a VNDK snapshot requires capturing - VNDK libraries as a snapshot and marking them with a version number. The - vendor image may link with a specific VNDK version that provides required ABIs - for the modules in the vendor image. However, within the same VNDK version, - the VNDK libraries must be - <a href="/devices/architecture/hidl/hashing#abi-stability">ABI-stable</a>. -</p> - -<p> - VNDK snapshot design includes methods for - <a href="/devices/architecture/vndk/snapshot-generate.html">generating the - pre-builds of a VNDK snapshot</a> from the current system image and - <a href="/devices/architecture/vndk/snapshot-generate.html#install-vndk-snapshot">installing - those pre-built libs</a> to the system partition of a newer Android version. -</p> - -<h2 id=about-vndk-libs>About VNDK libraries</h2> - -<p> - <a href="/devices/architecture/index.html#hidl">HIDL-HALs</a>, introduced in - Android 8.0, enables separate upgrades for system and vendor partitions. VNDK - defines sets of libraries (VNDK-core, VNDK-SP and LL-NDK) that vendor code can - link with and blocks the vendors from using libraries that are not in a VNDK - set. As a result, the vendor image can be built and run if the proper VNDK - sets on the system image are provided to the vendor image. -</p> - -<aside class="note"><strong>Note:</strong> For details on these libraries, refer - to <a href="/devices/architecture/vndk/index.html#concepts">VNDK concepts</a>. -</aside> - -<h3 id="vndk-core">VNDK-core</h3> - -<p> - The VNDK-core set of libraries is installed in - <code>/system/lib[64]/vndk-${VER}</code> and is available - <strong>only</strong> for vendor processes with the API level equal to - <code>${VER}</code>. System processes may not use these libraries and must - instead use the libraries installed in <code>/system/lib[64]</code>. Because - of the strict namespace restriction for each process, the VNDK-core libraries - are safe from dual-loading. -</p> - -<p>To include a library in VNDK-core, add the following to - <code>Android.bp</code>: -</p> - -<pre class="prettyprint"> -vendor_available: true, -vndk: { - enabled: true, -}, -</pre> - -<aside class="note"><strong>Note:</strong> If a system process loads library - <code>foo.so</code> from <code>system/lib</code> and loads another - <code>foo.so</code> from <code>system/lib/vndk</code>, <code>foo.so</code> is - dual-loaded. Normally it is unsafe to load the same library twice in a - process. -</aside> - -<h3 id="vndk-sp">VNDK-SP</h3> - -<p> - VNDK-SP libraries are installed in <code>/system/lib[64]/vndk-sp-${VER}</code> - and are available to vendor processes and system processes (through the SP-HAL - libraries installed in vendor partition). VNDK-SP libraries may be - dual-loaded. -</p> - -<p> - To include a library in VNDK-SP, add the following to <code>Android.bp</code>: -</p> - -<pre class="prettyprint"> -vendor_available: true, -vndk: { - enabled: true, - support_system_process: true, -}, -</pre> - -<h3 id="ll-ndk">LL-NDK</h3> - -<p> - LL-NDK libraries are installed in <code>/system/lib[64]</code>. Vendor modules - can use LL-NDK stub libraries to access pre-selected symbols of LL-NDK - libraries. LL-NDK libraries must be backward-compatible and ABI-stable to - enable old versions of vendor modules to use new versions of LL-NDK libraries. - Because of the ABI-stable characteristics of LL-NDK, the VNDK snapshot does - not need to include LL-NDK libraries for old vendor images. -</p> - -<h2 id="about-vndk-snapshots">About VNDK snapshots</h2> - -<p> - Android 8.1 included <a href="/devices/architecture/vndk/build-system">VNDK - libraries built from the source code</a>. However, for later versions of - Android, each VNDK version must be captured as a snapshot and provided as a - pre-build to enabling linking to an older vendor image. -</p> - -<p> - Starting in Android {{ androidPVersionNumber }}, new versions of Android will - include at least one snapshot of VNDK-core and VNDK-SP directories for older - versions in the Android source code. At build time, required snapshots will be - installed to <code>/system/lib[64]/vndk-${VER}</code> and - <code>/system/lib[64]/vndk-sp-${VER}</code> (directories that can be used by - the vendor partition), where <code>${VER}</code> is the string variable that - represents the version name of the VNDK snapshot. -</p> - -<p> - As the VNDK snapshot libraries may differ for each VNDK version, the VNDK - snapshot also includes the linker namespace configurations, installed as - <code>etc/ld.config.${VER}.txt</code>, - <code>/etc/llndk.libraries.${VER}.txt</code>, and - <code>/etc/vndksp.libraries.${VER}.txt</code>. -</p> - -<h3 id="example-upgrade-system-vendor">Example: Upgrading system and vendor -images</h3> - -<p> - No snapshot required; build without additional configurations for VNDK - snapshots. -</p> - -<h3 id="example-upgrade-system-only">Example: Upgrading system image only</h3> - -<p> - Must include the VNDK snapshot and linker namespace configuration files for - the vendor image in the system image. The linker namespace configuration files - are automatically configured to search for VNDK libraries in - <code>/system/lib[64]/vndk-${VER}</code> and - <code>/system/lib[64]/vndk-sp-${VER}</code>. -</p> - -<img src="/devices/architecture/images/vndk_snapshot_system_only.png"> -<figcaption><strong>Figure 1.</strong> Upgrading system only</figcaption> - -<h3 id="example-upgrade-system-minor-vendor">Example: Upgrading system image, -minor vendor image change</h3> - -<p> - Building a vendor image against a VNDK snapshot is not yet supported, so you - must build the vendor image separately with its original source code, then - upgrade the system image as described in the previous example. -</p> - -<h2 id="vndk-snapshot-arch">VNDK snapshot architecture</h2> - -<p> - To make an Android {{ androidPVersionNumber }} system image compatible with an - Android 8.1 vendor image, the VNDK snapshot that matches the Android 8.1 - vendor image must be provided with the Android {{ androidPVersionNumber }} - system image, as shown below: -</p> - -<img src="/devices/architecture/images/vndk_snapshot_arch.png"> -<figcaption><strong>Figure 2.</strong> VNDK snapshot architecture</figcaption> - -<p> - The VNDK snapshot design includes the following methods: -</p> - -<ul> - <li><strong>Generating a snapshot for VNDK-core and VNDK-SP - libraries</strong>. Android {{ androidPVersionNumber }} includes a script you - can use to make a snapshot of the current VNDK build. This script bundles all - libraries in <code>/system/lib[64]/vndk-28</code> and - <code>/system/lib[64]/vndk-sp-28</code> that were built with the current - source as a VNDK snapshot, where <code>28</code> is the VNDK version of - Android {{ androidPVersionNumber }}. The snapshot also includes the linker - namespace configuration files <code>/etc/ld.config.28.txt</code>, - <code>/etc/llndk.libraries.28.txt</code>, and - <code>/etc/vndksp.libraries.28.txt</code>. The generated snapshot will be used - with newer Android versions (higher than Android {{ androidPVersionNumber }}). - </li> - <li><strong>Installing pre-built VNDK-core and VNDK-SP libraries from a - snapshot</strong>. In Android {{ androidPVersionNumber }}, a VNDK snapshot has - a set of pre-built VNDK-core libraries and a set of VNDK-SP libraries, as well - as linker namespace configuration files. When you provide a list of VNDK - snapshot versions to be installed, at build time, the system image installs - the VNDK snapshot libraries to <code>/system/lib[64]/vndk-${VER}</code> and - the <code>/system/lib[64]/vndk-sp-${VER}</code> directories and linker - namespace configuration files for those VNDK snapshots to - <code>/etc</code> directory.</li> -</ul> - -<h3 id="vndk-versioning">VNDK versioning</h3> - -<p> - Each Android release has only one VNDK snapshot and the SDK version is used as - a VNDK version (which means the VNDK version has an integer number, such as 27 - for Android 8.1). The VNDK version is fixed when the Android version is - released. The VNDK version used by the vendor partition is stored - automatically in the <code>ro.vndk.version</code> property, which can be read - on runtime. This version is then used in identifying the vendor VNDK version - for some libraries and identifying the VNDK snapshot version for namespace - configuration. -</p> - -<h3 id="build-vndk-libs">Building VNDK libraries</h3> - -<p> - The <code>make vndk</code> command builds libraries that have <code>vndk: - { enabled: true, … }</code>, including dependencies and namespace - configuration files. If <code>BOARD_VNDK_VERSION := current</code> is set, - these libraries are built with the <code>make</code> command. -<p> - -<p> - Because this build does not install the VNDK libraries from the snapshot, the - installed VNDK libraries are not ABI-stable. However, when an Android version - is released, the ABI for the current VNDK version is fixed. At this point, any - ABI breakage is a build error, so patches to the Android version must not - change the ABI for VNDK libraries. -</p> - -</body> -</html> diff --git a/en/devices/architecture/vndk/snapshot-generate.html b/en/devices/architecture/vndk/snapshot-generate.html deleted file mode 100644 index 92b4d7d0..00000000 --- a/en/devices/architecture/vndk/snapshot-generate.html +++ /dev/null @@ -1,456 +0,0 @@ -<html devsite> - <head> - <title>Generating VNDK Snapshots</title> - <meta name="project_path" value="/_project.yaml" /> - <meta name="book_path" value="/_book.yaml" /> - </head> - {% include "_versions.html" %} - <body> - <!-- - Copyright 2018 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 VNDK snapshot is a set of VNDK-core and VNDK-SP libs for an Android release. - You can upgrade only the system partition if the system.img includes the - corresponding VNDK snapshot needed by the vendor.img. -</p> - -<aside class="note"><strong>Note:</strong> This page provides design details for - building and updating a VNDK snapshot. For details on the background, - definition, and use cases of VNDK snapshots, refer to - <a href="/devices/architecture/vndk/snapshot-design">VNDK Snapshot Design</a>. -</aside> - -<p> - Official VNDK snapshots are built automatically on the Android build server - and checked into <code>/prebuilts/vndk</code> of the Android source tree. For - development purposes, you can build VNDK snapshots locally. VNDK snapshots are - supported for arm, arm64, x86, and x86_64 TARGET_ARCH flavors. -</p> - -<h2 id="snapshot-build-artifacts">Snapshot build artifacts</h2> - -<p> - The Android build server generates build artifacts for VNDK snapshots using - the following build parameters and build commands. -</p> - -<h3 id="build-parameters">Build parameters</h3> - -<p> - The build target name is <code>vndk</code> and the build target configuration - is as follows: -</p> - -<ul> - <li>TARGET_PRODUCT=aosp_{TARGET_ARCH}_ab</li> - <li>TARGET_BUILD_VARIANT=user</li> - <li>TARGET_ARCH. Same as Generic System Image (GSI) target archs (arm, arm64, - x86, x86_64).</li> - <li>TARGET_ARCH_VARIANT. For snapshot v27 (Android 8.1), includes popular - configurations (listed below); future releases may include other arch/cpu - variants.</li> -</ul> - -<table> -<thead> -<tr> -<th>TARGET_PRODUCT</th> -<th>TARGET_ARCH</th> -<th>TARGET_ARCH_VARIANT</th> -</tr> -</thead> -<tbody> -<tr> -<td>aosp_arm_ab</td> -<td>arm</td> -<td>armv7-a-neon</td> -</tr> -<tr> -<td>aosp_arm64_ab</td> -<td>arm64</td> -<td>armv8-a</td> -</tr> -<tr> -<td>aosp_x86_ab</td> -<td>x86</td> -<td>x86</td> -</tr> -<tr> -<td>aosp_x86_64_ab</td> -<td>x86_64</td> -<td>x86_64</td> -</tr> -</tbody> -</table> - -<h3 id="build-commands">Build commands</h3> - -<p> - For official snapshots, Android {{ androidPVersionNumber }} includes a new - dummy target (<code>vndk</code>) in - <a href="https://android.googlesource.com/platform/build/+/master/core/tasks/vndk.mk">vndk.mk</a> - that builds and outputs a VNDK snapshot to <code>$DIST_DIR</code>. The - snapshot zip file uses the format <code>android-vndk-{TARGET_ARCH}.zip</code>. - For example: -</p> - -<pre class="prettyprint"> -$ lunch aosp_<ARCH>_ab-user -$ make -j vndk dist [BOARD_VNDK_VERSION=current] -</pre> - -<p> - The Android build server uses the - <a href="https://android.googlesource.com/platform/development/+/master/vndk/snapshot/build.sh">build.sh</a> - script to build all supported arch flavors with the following command: -</p> - -<pre class="prettyprint"> -$ DIST_DIR=%dist_dir% development/vndk/snapshot/build.sh -</pre> - -<p> - VNDK snapshots for an Android Version are generated from the - <code><Android Version>-release</code> branch. -</p> - -<h3 id="build-locally">Building locally</h3> - -<p> - During development, you can build VNDK snapshots from a local source tree with - the following commands: -</p> - -<ul> - <li>To build all supported archs at once, execute the build script - (<code>build.sh</code>): -<pre class="prettyprint"> -$ cd $ANDROID_BUILD_TOP -$ development/vndk/snapshot/build.sh -</pre> - </li> - <li>To build one specific TARGET_ARCH: - -<pre class="prettyprint"> -$ lunch aosp_<ARCH>_ab-user -$ m -j vndk dist -</pre> - </li> -</ul> - -<p> - The corresponding <code>android-vndk-<ARCH>.zip</code> file is created - under <code>$DIST_DIR</code>. -</p> - -<h2 id="snapshot-files">Snapshot files</h2> - -<p> - A VNDK snapshot includes the following files: -</p> - -<ul> - <li>Vendor variant of VNDK-core and VNDK-SP shared libraries. - <ul> - <li>LL-NDK shared libs are not needed as they are backward compatible.</li> - <li>For 64bit targets, both TARGET_ARCH and TARGET_2ND_ARCH libraries are - built and included.</li> - </ul> - </li> - <li>List of VNDK-core, VNDK-SP, LL-NDK, and VNDK-private libraries is at - <code>[vndkcore|vndksp|llndk|vndkprivate].libraries.txt</code>.</li> - <li>Linker config file is <code>ld.config.txt</code>.</li> - <li>License files. </li> - <li><code>module_paths.txt</code>. Records the module paths for all VNDK - libraries, which is needed for checking that GPL projects have sources - released in a given Android source tree.</li> -</ul> - -<p> - For a given VNDK snapshot zip file, - <code>android-vndk-{TARGET_ARCH}.zip</code>, the VNDK prebuilt libraries are - grouped in separate directories named - <code>arch-{TARGET_ARCH}-{TARGET_ARCH_VARIANT}</code> according to ABI - bitness. For example, for <code>android-vndk-arm64.zip</code>, the 64-bit libs - are placed under <code>arch-arm64-armv8-a</code> and the 32-bit libs are - placed under <code>arch-arm-armv8-a</code>. -</p> - -<h3 id="example-snapshot-dir-structure">Example: VNDK snapshot directory -structure</h3> - -<p> - The example below shows the directory structure for an arm64 - (<code>TARGET_ARCH=arm64</code>) VNDK snapshot zip file - (<code>android-vndk-arm64.zip</code>). -</p> - -<img src="/devices/architecture/images/vndk_snapshot_directory.png"> -<figcaption><strong>Figure 1. </strong>VNDK snapshot directory structure -(example)</figcaption> - -<h2 id='upload-vndk-snapshots'>Uploading VNDK snapshots</h2> - -<p> - VNDK snapshots are checked in the source tree under - <code>/prebuilts/vndk/v<VER></code>, where <code><VER></code> is - equal to the version of the VNDK snapshot (which follows the SDK version of - the corresponding Android release). For example, the O MR1 VNDK snapshot has - version 27. -</p> - -<h3 id="using-update-py">Using the update.py script</h3> - -<p> - The <code>update.py</code> script - (<code>/development/vndk/snapshot/update.py)</code> automates the process of - adding a pre-built VNDK snapshot to the source tree. This script performs the - following tasks: -</p> - -<ol> - <li>In <code>/prebuilts/vndk/v<VER></code>, uses <code>repo start</code> - to create new git branch.</li> - <li>Fetches and unzips VNDK snapshot build artifacts.</li> - <li>Runs <code>gen_buildfiles.py</code> to auto generate the build files - (<code>Android.mk</code>, <code>Android.bp</code>).</li> - <li>Runs <code>check_gpl_license.py</code> to verify the prebuilt libraries - licensed under the General Public License (GPL) have sources released in - current source tree.</li> - <li>Uses <code>git commit</code> to commit new changes.</li> -</ol> - -<h3 id="using-local-snapshots">Using locally-built VNDK snapshots</h3> - -<p> - During development, you can use locally-built VNDK snapshots for testing. When - the <code>--local</code> option is specified, <code>update.py</code> fetches - VNDK snapshot build artifacts from local <code>$DIST_DIR</code> instead of the - Android build server. Usage: -</p> - -<pre class="prettyprint"> -$ python update.py <VER> --local -</pre> - -<p> - For example, to update the O MR1 VNDK snapshot with local build artifacts, - run: -</p> - -<pre class="prettyprint"> -$ python update.py 27 --local -</pre> - -<p> - Because local mode is designed for testing only, the script skips the GPL - license checking and git commit steps. -</p> - -<h3 id="dir-structure-prebuilts">Directory structure for prebuilts/vndk</h3> - -<img src="/devices/architecture/images/vndk_snapshot_prebuilt.png"> -<figcaption><strong>Figure 2. </strong>Prebuilts/vndk directory -structure</figcaption> - -<h2 id="install-vndk-snapshot">Installing VNDK snapshots</h2> - -<p> - The system image installs VNDK snapshot libraries at build time using the - information in <code>BOARD_VNDK_VERSION</code>, - <code>PRODUCT_EXTRA_VNDK_VERSIONS</code>, and <code>ro.vndk.version</code>. - You can control which VNDK snapshots get installed from - <code>/prebuilts/vndk/v<VER></code> using one of the following options: -</p> - -<ul> - <li><strong>Option 1:</strong> <code>BOARD_VNDK_VERSION</code>. Use the - snapshot modules for building the current vendor modules and install only the - snapshot modules that are required for the vendor modules.</li> - <li><strong>Option 2:</strong> <code>PRODUCT_EXTRA_VNDK_VERSIONS</code>. - Install the VNDK snapshot modules regardless of the current vendor modules. - This installs the prebuilt VNDK snapshots listed in - <code>PRODUCT_EXTRA_VNDK_VERSIONS</code> without linking them to any other - modules at build time.</li> -</ul> - -<h3 id="set-board-vndk">Setting BOARD_VNDK_VERSION</h3> - -<p> - <code>BOARD_VNDK_VERSION</code> shows the VNDK version that current vendor - modules are required to build. If <code>BOARD_VNDK_VERSION</code> has an - available VNDK snapshot version in <code>/prebuilts/vndk</code> directory, the - VNDK snapshot indicated in <code>BOARD_VNDK_VERSION</code> is installed. If - the VNDK snapshot is not available in the directory, a build error occurs. -</p> - -<p> - Defining <code>BOARD_VNDK_VERSION</code> also enables the VNDK modules to be - installed. Vendor modules link with the VNDK snapshot version defined in - <code>BOARD_VNDK_VERSION</code> at build time (this does not build current - VNDK modules in the system source). When downloading the full source tree from - a repository, both system and vendor sources are based on the same Android - release. -</p> - -<aside class="note"><strong>Note:</strong> Vendor modules use the current VNDK - version of the system source tree, so you must set - <code>BOARD_VNDK_VERSION</code> to <code>current</code>. -</aside> - -<h3 id="set-product-extra">Setting PRODUCT_EXTRA_VNDK_VERSIONS</h3> - -<p> - <code>PRODUCT_EXTRA_VNDK_VERSIONS</code> lists the extra VNDK versions to be - installed. Normally it is enough to have one VNDK snapshot for the current - vendor partition. However, in some cases you might need to include multiple - snapshots in one system image. For example, Generic System Image (GSI) has - multiple snapshots to support multiple vendor versions with one system image. - By setting <code>PRODUCT_EXTRA_VNDK_VERSIONS</code>, you can install the VNDK - snapshot modules in addition to the VNDK version in - <code>BOARD_VNDK_VERSION</code>. -</p> - -<p> - If <code>PRODUCT_EXTRA_VNDK_VERSIONS</code> has a specific list of versions, - the build system looks for pre-built snapshots of the version list in the - <code>prebuilts/vndk</code> directory. If the build system locates all listed - snapshots, it installs those snapshot files to each - <code>out/target/product/<board>/system/lib[64]/vndk[-sp]-${VER}</code>. - Missing versions generate a build error. -</p> - -<p> - The VNDK modules will not link with the vendor modules at build time but may - be used at runtime if the vendor modules in vendor partition require one of - the installed VNDK versions. <code>PRODUCT_EXTRA_VNDK_VERSIONS</code> is valid - only if <code>BOARD_VNDK_VERSION</code> is defined. For example, to install - the O MR1 VNDK snapshot to system.img: -</p> - -<pre class="prettyprint"> -$ m -j PRODUCT_EXTRA_VNDK_VERSIONS=27 -</pre> - -<h3 id="platform-vndk">PLATFORM_VNDK_VERSION</h3> - -<p> - <code>PLATFORM_VNDK_VERSION</code> defines the VNDK version for current VNDK - modules in the system source. The value is set automatically: -</p> - -<ul> - <li>Prior to release, the <code>PLATFORM_VNDK_VERSION</code> is set as - <code>PLATFORM_VERSION_CODENAME</code>.</li> - <li>At release, <code>PLATFORM_SDK_VERSION</code> is copied to - <code>PLATFORM_VNDK_VERSION</code>.</li> -</ul> - -<p> - After the Android version is released, the current VNDK libraries are - installed to <code>/system/lib[64]/vndk-$SDK_VER</code> and - <code>/system/lib[64]/vndk-sp-$SDK_VER</code>, where <code>$SDK_VER</code> is - the version stored in <code>PLATFORM_VNDK_VERSION</code>. -</p> - -<h3 id="namespace-config">Namespace configuration</h3> - -<p> - The vendor modules search the required shared libraries using the namespace - configuration in <code>/etc/ld.config.${VER}.txt</code> (where - <code>${VER}</code> is obtained from the <code>ro.vndk.version</code> - property). The namespace configuration has a versioned VNDK directory that - uses the following syntax: -</p> - -<ul> - <li><code>/system/${LIB}/vndk-%VNDK_VER%</code></li> - <li><code>/system/${LIB}/vndk-sp-%VNDK_VER%</code></li> -</ul> - -<p> - <code>%VNDK_VER%</code> is replaced with <code>PLATFORM_VNDK_VERSION</code> - at build time, enabling a system image to provide multiple snapshots for each - VNDK version. -</p> - -<p> - When <code>BOARD_VNDK_VERSION</code> is set to <code>current</code>, the - <code>PLATFORM_VNDK_VERSION</code> is stored in <code>ro.vndk.version</code>, - otherwise <code>BOARD_VNDK_VERSION </code>is stored in - <code>ro.vndk.version</code>. <code>PLATFORM_VNDK_VERSION</code> is set to the - SDK version when Android releases; prior to release, the alphanumeric Android - code name is used for <code>PLATFORM_VNDK_VERSION</code>. -</p> - -<h3 id="summary-vndk-version-settings">Summary of VNDK version settings</h3> - -<p> - The table below summarizes the VNDK version settings. -</p> - -<table> -<thead> -<tr> -<th width="15%">Vendor<br>Build</th> -<th>Board<br>Version</th> -<th>SDK<br>Release</th> -<th>Platform<br>Version</th> -<th>Version<br>Property</th> -<th>Install Directory</th> -</tr> -</thead> -<tbody> -<tr> -<td rowspan=2>Current VNDK modules</td> -<td rowspan=2><code>current</code></td> -<td>Before</td> -<td><CODE_NAME></td> -<td><CODE_NAME></td> -<td>/system/lib[64]/vndk[-sp]-<CODE_NAME></td> -</tr> -<tr> -<td>After</td> -<td><SDK_ver></td> -<td><SDK_ver></td> -<td>/system/lib[64]/vndk[-sp]-<SDK_ver></td> -</tr> -<tr> -<td>Prebuilt snapshot modules</td> -<td><VNDK_ver><br>for snapshot</td> -<td>Before or After</td> -<td><CODE_NAME><br>or <SDK_ver></td> -<td><VNDK_ver></td> -<td>/system/lib[64]/vndk[-sp]-<VNDK_ver></td> -</tr> -</tbody> -</table> - -<ul> - <li><strong>Board Version</strong> (<code>BOARD_VNDK_VERSION</code>). VNDK - version that vendor modules require to build. Set to <code>current</code> if - vendor modules can link with current system modules.</li> - <li><strong>Platform Version</strong> (<code>PLATFORM_VNDK_VERSION</code>). - VNDK version that current system modules are building. Built only when - <code>BOARD_VNDK_VERSION</code> equals current.</li> - <li><strong>Version Property</strong> (<code>ro.vndk.version</code>). Property - that specifies the VNDK version the binaries and libs in vendor.img require to - run. Stored in the vendor.img at<code> /vendor/default.prop</code>.</li> -</ul> - -</body> -</html>
\ No newline at end of file |