1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
<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>
|
