blob: 7216fc73316ced4e3ae5408cb2dc155a61f4f382 [file] [log] [blame]
Richard Uhler66d874d2015-01-15 09:37:19 -08001/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef ART_RUNTIME_OAT_FILE_ASSISTANT_H_
18#define ART_RUNTIME_OAT_FILE_ASSISTANT_H_
19
20#include <cstdint>
21#include <memory>
22#include <string>
23
24#include "arch/instruction_set.h"
25#include "base/scoped_flock.h"
26#include "base/unix_file/fd_file.h"
27#include "oat_file.h"
28#include "os.h"
29#include "profiler.h"
30
31namespace art {
32
33// Class for assisting with oat file management.
34//
35// This class collects common utilities for determining the status of an oat
36// file on the device, updating the oat file, and loading the oat file.
37//
38// The oat file assistant is intended to be used with dex locations not on the
39// boot class path. See the IsInBootClassPath method for a way to check if the
40// dex location is in the boot class path.
41//
42// TODO: All the profiling related code is old and untested. It should either
43// be restored and tested, or removed.
44class OatFileAssistant {
45 public:
Richard Uhler95abd042015-03-24 09:51:28 -070046 enum DexOptNeeded {
47 // kNoDexOptNeeded - The code for this dex location is up to date and can
48 // be used as is.
49 // Matches Java: dalvik.system.DexFile.NO_DEXOPT_NEEDED = 0
50 kNoDexOptNeeded = 0,
Richard Uhler66d874d2015-01-15 09:37:19 -080051
Richard Uhler95abd042015-03-24 09:51:28 -070052 // kDex2OatNeeded - In order to make the code for this dex location up to
53 // date, dex2oat must be run on the dex file.
54 // Matches Java: dalvik.system.DexFile.DEX2OAT_NEEDED = 1
55 kDex2OatNeeded = 1,
Richard Uhler66d874d2015-01-15 09:37:19 -080056
Richard Uhler95abd042015-03-24 09:51:28 -070057 // kPatchOatNeeded - In order to make the code for this dex location up to
58 // date, patchoat must be run on the odex file.
59 // Matches Java: dalvik.system.DexFile.PATCHOAT_NEEDED = 2
60 kPatchOatNeeded = 2,
61
62 // kSelfPatchOatNeeded - In order to make the code for this dex location
63 // up to date, patchoat must be run on the oat file.
64 // Matches Java: dalvik.system.DexFile.SELF_PATCHOAT_NEEDED = 3
65 kSelfPatchOatNeeded = 3,
66 };
67
68 enum OatStatus {
69 // kOatOutOfDate - An oat file is said to be out of date if the file does
70 // not exist, or is out of date with respect to the dex file or boot
71 // image.
72 kOatOutOfDate,
73
74 // kOatNeedsRelocation - An oat file is said to need relocation if the
75 // code is up to date, but not yet properly relocated for address space
76 // layout randomization (ASLR). In this case, the oat file is neither
77 // "out of date" nor "up to date".
78 kOatNeedsRelocation,
79
80 // kOatUpToDate - An oat file is said to be up to date if it is not out of
Richard Uhler66d874d2015-01-15 09:37:19 -080081 // date and has been properly relocated for the purposes of ASLR.
Richard Uhler95abd042015-03-24 09:51:28 -070082 kOatUpToDate,
Richard Uhler66d874d2015-01-15 09:37:19 -080083 };
84
85 // Constructs an OatFileAssistant object to assist the oat file
86 // corresponding to the given dex location with the target instruction set.
87 //
Mathieu Chartier2cebb242015-04-21 16:50:40 -070088 // The dex_location must not be null and should remain available and
Richard Uhler66d874d2015-01-15 09:37:19 -080089 // unchanged for the duration of the lifetime of the OatFileAssistant object.
90 // Typically the dex_location is the absolute path to the original,
91 // un-optimized dex file.
92 //
Richard Uhler66d874d2015-01-15 09:37:19 -080093 // Note: Currently the dex_location must have an extension.
94 // TODO: Relax this restriction?
95 //
96 // The isa should be either the 32 bit or 64 bit variant for the current
97 // device. For example, on an arm device, use arm or arm64. An oat file can
98 // be loaded executable only if the ISA matches the current runtime.
99 OatFileAssistant(const char* dex_location, const InstructionSet isa,
100 bool load_executable);
101
102 // Constructs an OatFileAssistant, providing an explicit target oat_location
103 // to use instead of the standard oat location.
104 OatFileAssistant(const char* dex_location, const char* oat_location,
105 const InstructionSet isa, bool load_executable);
106
107 // Constructs an OatFileAssistant, providing an additional package_name used
108 // solely for the purpose of locating profile files.
109 //
110 // TODO: Why is the name of the profile file based on the package name and
111 // not the dex location? If there is no technical reason the dex_location
112 // can't be used, we should prefer that instead.
113 OatFileAssistant(const char* dex_location, const InstructionSet isa,
114 bool load_executable, const char* package_name);
115
116 // Constructs an OatFileAssistant with user specified oat location and a
117 // package name.
118 OatFileAssistant(const char* dex_location, const char* oat_location,
119 const InstructionSet isa, bool load_executable,
120 const char* package_name);
121
122 ~OatFileAssistant();
123
124 // Returns true if the dex location refers to an element of the boot class
125 // path.
126 bool IsInBootClassPath();
127
128 // Obtains a lock on the target oat file.
129 // Only one OatFileAssistant object can hold the lock for a target oat file
130 // at a time. The Lock is released automatically when the OatFileAssistant
131 // object goes out of scope. The Lock() method must not be called if the
132 // lock has already been acquired.
133 //
134 // Returns true on success.
135 // Returns false on error, in which case error_msg will contain more
136 // information on the error.
137 //
138 // The 'error_msg' argument must not be null.
139 //
140 // This is intended to be used to avoid race conditions when multiple
141 // processes generate oat files, such as when a foreground Activity and
142 // a background Service both use DexClassLoaders pointing to the same dex
143 // file.
144 bool Lock(std::string* error_msg);
145
Richard Uhler95abd042015-03-24 09:51:28 -0700146 // Return what action needs to be taken to produce up-to-date code for this
147 // dex location.
148 DexOptNeeded GetDexOptNeeded();
Richard Uhler66d874d2015-01-15 09:37:19 -0800149
150 // Attempts to generate or relocate the oat file as needed to make it up to
151 // date.
152 // Returns true on success.
153 //
154 // If there is a failure, the value of error_msg will be set to a string
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700155 // describing why there was failure. error_msg must not be null.
Richard Uhler66d874d2015-01-15 09:37:19 -0800156 bool MakeUpToDate(std::string* error_msg);
157
158 // Returns an oat file that can be used for loading dex files.
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700159 // Returns null if no suitable oat file was found.
Richard Uhler66d874d2015-01-15 09:37:19 -0800160 //
161 // After this call, no other methods of the OatFileAssistant should be
162 // called, because access to the loaded oat file has been taken away from
163 // the OatFileAssistant object.
164 std::unique_ptr<OatFile> GetBestOatFile();
165
166 // Loads the dex files in the given oat file for the given dex location.
167 // The oat file should be up to date for the given dex location.
168 // This loads multiple dex files in the case of multidex.
169 // Returns an empty vector if no dex files for that location could be loaded
170 // from the oat file.
171 //
172 // The caller is responsible for freeing the dex_files returned, if any. The
173 // dex_files will only remain valid as long as the oat_file is valid.
174 static std::vector<std::unique_ptr<const DexFile>> LoadDexFiles(
175 const OatFile& oat_file, const char* dex_location);
176
Richard Uhler9b994ea2015-06-24 08:44:19 -0700177 // Returns true if there are dex files in the original dex location that can
178 // be compiled with dex2oat for this dex location.
179 // Returns false if there is no original dex file, or if the original dex
180 // file is an apk/zip without a classes.dex entry.
181 bool HasOriginalDexFiles();
182
Richard Uhler63434112015-03-16 14:32:16 -0700183 // If the dex file has been installed with a compiled oat file alongside
184 // it, the compiled oat file will have the extension .odex, and is referred
185 // to as the odex file. It is called odex for legacy reasons; the file is
186 // really an oat file. The odex file will often, but not always, have a
187 // patch delta of 0 and need to be relocated before use for the purposes of
188 // ASLR. The odex file is treated as if it were read-only.
Richard Uhler66d874d2015-01-15 09:37:19 -0800189 // These methods return the location and status of the odex file for the dex
190 // location.
191 // Notes:
192 // * OdexFileName may return null if the odex file name could not be
193 // determined.
194 const std::string* OdexFileName();
195 bool OdexFileExists();
Richard Uhler95abd042015-03-24 09:51:28 -0700196 OatStatus OdexFileStatus();
Richard Uhler66d874d2015-01-15 09:37:19 -0800197 bool OdexFileIsOutOfDate();
198 bool OdexFileNeedsRelocation();
199 bool OdexFileIsUpToDate();
200
201 // When the dex files is compiled on the target device, the oat file is the
202 // result. The oat file will have been relocated to some
203 // (possibly-out-of-date) offset for ASLR.
204 // These methods return the location and status of the target oat file for
205 // the dex location.
206 //
207 // Notes:
Richard Uhler66d874d2015-01-15 09:37:19 -0800208 // * OatFileName may return null if the oat file name could not be
209 // determined.
210 const std::string* OatFileName();
211 bool OatFileExists();
Richard Uhler95abd042015-03-24 09:51:28 -0700212 OatStatus OatFileStatus();
Richard Uhler66d874d2015-01-15 09:37:19 -0800213 bool OatFileIsOutOfDate();
214 bool OatFileNeedsRelocation();
215 bool OatFileIsUpToDate();
216
217 // These methods return the status for a given opened oat file with respect
218 // to the dex location.
Richard Uhler95abd042015-03-24 09:51:28 -0700219 OatStatus GivenOatFileStatus(const OatFile& file);
Richard Uhler66d874d2015-01-15 09:37:19 -0800220 bool GivenOatFileIsOutOfDate(const OatFile& file);
221 bool GivenOatFileNeedsRelocation(const OatFile& file);
222 bool GivenOatFileIsUpToDate(const OatFile& file);
223
224 // Returns true if there is an accessible profile associated with the dex
225 // location.
226 // This returns false if profiling is disabled.
227 bool ProfileExists();
228
229 // The old profile is a file containing a previous snapshot of profiling
230 // information associated with the dex file code. This is used to track how
231 // the profiling information has changed over time.
232 //
233 // Returns true if there is an accessible old profile associated with the
234 // dex location.
235 // This returns false if profiling is disabled.
236 bool OldProfileExists();
237
238 // Returns true if there has been a significant change between the old
239 // profile and the current profile.
240 // This returns false if profiling is disabled.
241 bool IsProfileChangeSignificant();
242
243 // Copy the current profile to the old profile location.
244 void CopyProfileFile();
245
Richard Uhler95abd042015-03-24 09:51:28 -0700246 // Generates the oat file by relocation from the named input file.
Richard Uhler66d874d2015-01-15 09:37:19 -0800247 // This does not check the current status before attempting to relocate the
248 // oat file.
249 // Returns true on success.
250 // This will fail if dex2oat is not enabled in the current runtime.
251 //
252 // If there is a failure, the value of error_msg will be set to a string
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700253 // describing why there was failure. error_msg must not be null.
Richard Uhler95abd042015-03-24 09:51:28 -0700254 bool RelocateOatFile(const std::string* input_file, std::string* error_msg);
Richard Uhler66d874d2015-01-15 09:37:19 -0800255
256 // Generate the oat file from the dex file.
257 // This does not check the current status before attempting to generate the
258 // oat file.
259 // Returns true on success.
260 // This will fail if dex2oat is not enabled in the current runtime.
261 //
262 // If there is a failure, the value of error_msg will be set to a string
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700263 // describing why there was failure. error_msg must not be null.
Richard Uhler66d874d2015-01-15 09:37:19 -0800264 bool GenerateOatFile(std::string* error_msg);
265
266 // Executes dex2oat using the current runtime configuration overridden with
267 // the given arguments. This does not check to see if dex2oat is enabled in
268 // the runtime configuration.
269 // Returns true on success.
270 //
271 // If there is a failure, the value of error_msg will be set to a string
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700272 // describing why there was failure. error_msg must not be null.
Richard Uhler66d874d2015-01-15 09:37:19 -0800273 //
274 // TODO: The OatFileAssistant probably isn't the right place to have this
275 // function.
276 static bool Dex2Oat(const std::vector<std::string>& args, std::string* error_msg);
277
278 // Constructs the odex file name for the given dex location.
279 // Returns true on success, in which case odex_filename is set to the odex
280 // file name.
281 // Returns false on error, in which case error_msg describes the error.
282 // Neither odex_filename nor error_msg may be null.
283 static bool DexFilenameToOdexFilename(const std::string& location,
284 InstructionSet isa, std::string* odex_filename, std::string* error_msg);
285
286 private:
287 struct ImageInfo {
288 uint32_t oat_checksum = 0;
289 uintptr_t oat_data_begin = 0;
290 int32_t patch_delta = 0;
291 std::string location;
292 };
293
294 // Returns the path to the dalvik cache directory.
295 // Does not check existence of the cache or try to create it.
296 // Includes the trailing slash.
297 // Returns an empty string if we can't get the dalvik cache directory path.
298 std::string DalvikCacheDirectory();
299
300 // Constructs the filename for the profile file.
301 // Returns an empty string if we do not have the necessary information to
302 // construct the filename.
303 std::string ProfileFileName();
304
305 // Constructs the filename for the old profile file.
306 // Returns an empty string if we do not have the necessary information to
307 // construct the filename.
308 std::string OldProfileFileName();
309
310 // Returns the current image location.
311 // Returns an empty string if the image location could not be retrieved.
312 //
313 // TODO: This method should belong with an image file manager, not
314 // the oat file assistant.
315 static std::string ImageLocation();
316
317 // Gets the dex checksum required for an up-to-date oat file.
318 // Returns dex_checksum if a required checksum was located. Returns
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700319 // null if the required checksum was not found.
Richard Uhler66d874d2015-01-15 09:37:19 -0800320 // The caller shouldn't clean up or free the returned pointer.
Richard Uhler9b994ea2015-06-24 08:44:19 -0700321 // This sets the has_original_dex_files_ field to true if a checksum was
322 // found for the dex_location_ dex file.
Richard Uhler66d874d2015-01-15 09:37:19 -0800323 const uint32_t* GetRequiredDexChecksum();
324
325 // Returns the loaded odex file.
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700326 // Loads the file if needed. Returns null if the file failed to load.
Richard Uhler66d874d2015-01-15 09:37:19 -0800327 // The caller shouldn't clean up or free the returned pointer.
328 const OatFile* GetOdexFile();
329
330 // Clear any cached information about the odex file that depends on the
331 // contents of the file.
332 void ClearOdexFileCache();
333
334 // Returns the loaded oat file.
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700335 // Loads the file if needed. Returns null if the file failed to load.
Richard Uhler66d874d2015-01-15 09:37:19 -0800336 // The caller shouldn't clean up or free the returned pointer.
337 const OatFile* GetOatFile();
338
339 // Clear any cached information about the oat file that depends on the
340 // contents of the file.
341 void ClearOatFileCache();
342
343 // Returns the loaded image info.
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700344 // Loads the image info if needed. Returns null if the image info failed
Richard Uhler66d874d2015-01-15 09:37:19 -0800345 // to load.
346 // The caller shouldn't clean up or free the returned pointer.
347 const ImageInfo* GetImageInfo();
348
349 // Returns the loaded profile.
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700350 // Loads the profile if needed. Returns null if the profile failed
Richard Uhler66d874d2015-01-15 09:37:19 -0800351 // to load.
352 // The caller shouldn't clean up or free the returned pointer.
353 ProfileFile* GetProfile();
354
355 // Returns the loaded old profile.
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700356 // Loads the old profile if needed. Returns null if the old profile
Richard Uhler66d874d2015-01-15 09:37:19 -0800357 // failed to load.
358 // The caller shouldn't clean up or free the returned pointer.
359 ProfileFile* GetOldProfile();
360
361 // To implement Lock(), we lock a dummy file where the oat file would go
362 // (adding ".flock" to the target file name) and retain the lock for the
363 // remaining lifetime of the OatFileAssistant object.
Richard Uhler66d874d2015-01-15 09:37:19 -0800364 ScopedFlock flock_;
365
366 // In a properly constructed OatFileAssistant object, dex_location_ should
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700367 // never be null.
Richard Uhler66d874d2015-01-15 09:37:19 -0800368 const char* dex_location_ = nullptr;
369
370 // In a properly constructed OatFileAssistant object, isa_ should be either
371 // the 32 or 64 bit variant for the current device.
372 const InstructionSet isa_ = kNone;
373
374 // The package name, used solely to find the profile file.
Mathieu Chartier2cebb242015-04-21 16:50:40 -0700375 // This may be null in a properly constructed object. In this case,
Richard Uhler66d874d2015-01-15 09:37:19 -0800376 // profile_load_attempted_ and old_profile_load_attempted_ will be true, and
377 // profile_load_succeeded_ and old_profile_load_succeeded_ will be false.
378 const char* package_name_ = nullptr;
379
380 // Whether we will attempt to load oat files executable.
381 bool load_executable_ = false;
382
383 // Cached value of the required dex checksum.
384 // This should be accessed only by the GetRequiredDexChecksum() method.
Richard Uhler9b994ea2015-06-24 08:44:19 -0700385 uint32_t cached_required_dex_checksum_;
386 bool required_dex_checksum_attempted_ = false;
387 bool required_dex_checksum_found_;
388 bool has_original_dex_files_;
Richard Uhler66d874d2015-01-15 09:37:19 -0800389
390 // Cached value of the odex file name.
391 // This should be accessed only by the OdexFileName() method.
392 bool cached_odex_file_name_attempted_ = false;
393 bool cached_odex_file_name_found_;
394 std::string cached_odex_file_name_;
395
396 // Cached value of the loaded odex file.
397 // Use the GetOdexFile method rather than accessing this directly, unless you
398 // know the odex file isn't out of date.
399 bool odex_file_load_attempted_ = false;
400 std::unique_ptr<OatFile> cached_odex_file_;
401
402 // Cached results for OdexFileIsOutOfDate
403 bool odex_file_is_out_of_date_attempted_ = false;
404 bool cached_odex_file_is_out_of_date_;
405
406 // Cached results for OdexFileIsUpToDate
407 bool odex_file_is_up_to_date_attempted_ = false;
408 bool cached_odex_file_is_up_to_date_;
409
410 // Cached value of the oat file name.
411 // This should be accessed only by the OatFileName() method.
412 bool cached_oat_file_name_attempted_ = false;
413 bool cached_oat_file_name_found_;
414 std::string cached_oat_file_name_;
415
Richard Uhlerb361d942015-05-07 10:52:28 -0700416 // Cached value of the loaded oat file.
Richard Uhler66d874d2015-01-15 09:37:19 -0800417 // Use the GetOatFile method rather than accessing this directly, unless you
Richard Uhlerb361d942015-05-07 10:52:28 -0700418 // know the oat file isn't out of date.
Richard Uhler66d874d2015-01-15 09:37:19 -0800419 bool oat_file_load_attempted_ = false;
420 std::unique_ptr<OatFile> cached_oat_file_;
421
422 // Cached results for OatFileIsOutOfDate
423 bool oat_file_is_out_of_date_attempted_ = false;
424 bool cached_oat_file_is_out_of_date_;
425
426 // Cached results for OatFileIsUpToDate
427 bool oat_file_is_up_to_date_attempted_ = false;
428 bool cached_oat_file_is_up_to_date_;
429
430 // Cached value of the image info.
431 // Use the GetImageInfo method rather than accessing these directly.
432 // TODO: The image info should probably be moved out of the oat file
433 // assistant to an image file manager.
434 bool image_info_load_attempted_ = false;
435 bool image_info_load_succeeded_ = false;
436 ImageInfo cached_image_info_;
437
438 // Cached value of the profile file.
439 // Use the GetProfile method rather than accessing these directly.
440 bool profile_load_attempted_ = false;
441 bool profile_load_succeeded_ = false;
442 ProfileFile cached_profile_;
443
444 // Cached value of the profile file.
445 // Use the GetOldProfile method rather than accessing these directly.
446 bool old_profile_load_attempted_ = false;
447 bool old_profile_load_succeeded_ = false;
448 ProfileFile cached_old_profile_;
449
450 // For debugging only.
451 // If this flag is set, the oat or odex file has been released to the user
452 // of the OatFileAssistant object and the OatFileAssistant object is in a
453 // bad state and should no longer be used.
454 bool oat_file_released_ = false;
455
456 DISALLOW_COPY_AND_ASSIGN(OatFileAssistant);
457};
458
459} // namespace art
460
461#endif // ART_RUNTIME_OAT_FILE_ASSISTANT_H_