blob: 9e7c2efc45f6456165cbce4a674f403579a87da2 [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 //
88 // The dex_location must not be NULL and should remain available and
89 // 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
155 // describing why there was failure. error_msg must not be nullptr.
156 bool MakeUpToDate(std::string* error_msg);
157
158 // Returns an oat file that can be used for loading dex files.
159 // Returns nullptr if no suitable oat file was found.
160 //
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 Uhler63434112015-03-16 14:32:16 -0700177 // If the dex file has been installed with a compiled oat file alongside
178 // it, the compiled oat file will have the extension .odex, and is referred
179 // to as the odex file. It is called odex for legacy reasons; the file is
180 // really an oat file. The odex file will often, but not always, have a
181 // patch delta of 0 and need to be relocated before use for the purposes of
182 // ASLR. The odex file is treated as if it were read-only.
Richard Uhler66d874d2015-01-15 09:37:19 -0800183 // These methods return the location and status of the odex file for the dex
184 // location.
185 // Notes:
186 // * OdexFileName may return null if the odex file name could not be
187 // determined.
188 const std::string* OdexFileName();
189 bool OdexFileExists();
Richard Uhler95abd042015-03-24 09:51:28 -0700190 OatStatus OdexFileStatus();
Richard Uhler66d874d2015-01-15 09:37:19 -0800191 bool OdexFileIsOutOfDate();
192 bool OdexFileNeedsRelocation();
193 bool OdexFileIsUpToDate();
194
195 // When the dex files is compiled on the target device, the oat file is the
196 // result. The oat file will have been relocated to some
197 // (possibly-out-of-date) offset for ASLR.
198 // These methods return the location and status of the target oat file for
199 // the dex location.
200 //
201 // Notes:
Richard Uhler66d874d2015-01-15 09:37:19 -0800202 // * OatFileName may return null if the oat file name could not be
203 // determined.
204 const std::string* OatFileName();
205 bool OatFileExists();
Richard Uhler95abd042015-03-24 09:51:28 -0700206 OatStatus OatFileStatus();
Richard Uhler66d874d2015-01-15 09:37:19 -0800207 bool OatFileIsOutOfDate();
208 bool OatFileNeedsRelocation();
209 bool OatFileIsUpToDate();
210
211 // These methods return the status for a given opened oat file with respect
212 // to the dex location.
Richard Uhler95abd042015-03-24 09:51:28 -0700213 OatStatus GivenOatFileStatus(const OatFile& file);
Richard Uhler66d874d2015-01-15 09:37:19 -0800214 bool GivenOatFileIsOutOfDate(const OatFile& file);
215 bool GivenOatFileNeedsRelocation(const OatFile& file);
216 bool GivenOatFileIsUpToDate(const OatFile& file);
217
218 // Returns true if there is an accessible profile associated with the dex
219 // location.
220 // This returns false if profiling is disabled.
221 bool ProfileExists();
222
223 // The old profile is a file containing a previous snapshot of profiling
224 // information associated with the dex file code. This is used to track how
225 // the profiling information has changed over time.
226 //
227 // Returns true if there is an accessible old profile associated with the
228 // dex location.
229 // This returns false if profiling is disabled.
230 bool OldProfileExists();
231
232 // Returns true if there has been a significant change between the old
233 // profile and the current profile.
234 // This returns false if profiling is disabled.
235 bool IsProfileChangeSignificant();
236
237 // Copy the current profile to the old profile location.
238 void CopyProfileFile();
239
Richard Uhler95abd042015-03-24 09:51:28 -0700240 // Generates the oat file by relocation from the named input file.
Richard Uhler66d874d2015-01-15 09:37:19 -0800241 // This does not check the current status before attempting to relocate the
242 // oat file.
243 // Returns true on success.
244 // This will fail if dex2oat is not enabled in the current runtime.
245 //
246 // If there is a failure, the value of error_msg will be set to a string
247 // describing why there was failure. error_msg must not be nullptr.
Richard Uhler95abd042015-03-24 09:51:28 -0700248 bool RelocateOatFile(const std::string* input_file, std::string* error_msg);
Richard Uhler66d874d2015-01-15 09:37:19 -0800249
250 // Generate the oat file from the dex file.
251 // This does not check the current status before attempting to generate the
252 // oat file.
253 // Returns true on success.
254 // This will fail if dex2oat is not enabled in the current runtime.
255 //
256 // If there is a failure, the value of error_msg will be set to a string
257 // describing why there was failure. error_msg must not be nullptr.
258 bool GenerateOatFile(std::string* error_msg);
259
260 // Executes dex2oat using the current runtime configuration overridden with
261 // the given arguments. This does not check to see if dex2oat is enabled in
262 // the runtime configuration.
263 // Returns true on success.
264 //
265 // If there is a failure, the value of error_msg will be set to a string
266 // describing why there was failure. error_msg must not be nullptr.
267 //
268 // TODO: The OatFileAssistant probably isn't the right place to have this
269 // function.
270 static bool Dex2Oat(const std::vector<std::string>& args, std::string* error_msg);
271
272 // Constructs the odex file name for the given dex location.
273 // Returns true on success, in which case odex_filename is set to the odex
274 // file name.
275 // Returns false on error, in which case error_msg describes the error.
276 // Neither odex_filename nor error_msg may be null.
277 static bool DexFilenameToOdexFilename(const std::string& location,
278 InstructionSet isa, std::string* odex_filename, std::string* error_msg);
279
280 private:
281 struct ImageInfo {
282 uint32_t oat_checksum = 0;
283 uintptr_t oat_data_begin = 0;
284 int32_t patch_delta = 0;
285 std::string location;
286 };
287
288 // Returns the path to the dalvik cache directory.
289 // Does not check existence of the cache or try to create it.
290 // Includes the trailing slash.
291 // Returns an empty string if we can't get the dalvik cache directory path.
292 std::string DalvikCacheDirectory();
293
294 // Constructs the filename for the profile file.
295 // Returns an empty string if we do not have the necessary information to
296 // construct the filename.
297 std::string ProfileFileName();
298
299 // Constructs the filename for the old profile file.
300 // Returns an empty string if we do not have the necessary information to
301 // construct the filename.
302 std::string OldProfileFileName();
303
304 // Returns the current image location.
305 // Returns an empty string if the image location could not be retrieved.
306 //
307 // TODO: This method should belong with an image file manager, not
308 // the oat file assistant.
309 static std::string ImageLocation();
310
311 // Gets the dex checksum required for an up-to-date oat file.
312 // Returns dex_checksum if a required checksum was located. Returns
313 // nullptr if the required checksum was not found.
314 // The caller shouldn't clean up or free the returned pointer.
315 const uint32_t* GetRequiredDexChecksum();
316
317 // Returns the loaded odex file.
318 // Loads the file if needed. Returns nullptr if the file failed to load.
319 // The caller shouldn't clean up or free the returned pointer.
320 const OatFile* GetOdexFile();
321
322 // Clear any cached information about the odex file that depends on the
323 // contents of the file.
324 void ClearOdexFileCache();
325
326 // Returns the loaded oat file.
327 // Loads the file if needed. Returns nullptr if the file failed to load.
328 // The caller shouldn't clean up or free the returned pointer.
329 const OatFile* GetOatFile();
330
331 // Clear any cached information about the oat file that depends on the
332 // contents of the file.
333 void ClearOatFileCache();
334
335 // Returns the loaded image info.
336 // Loads the image info if needed. Returns nullptr if the image info failed
337 // to load.
338 // The caller shouldn't clean up or free the returned pointer.
339 const ImageInfo* GetImageInfo();
340
341 // Returns the loaded profile.
342 // Loads the profile if needed. Returns nullptr if the profile failed
343 // to load.
344 // The caller shouldn't clean up or free the returned pointer.
345 ProfileFile* GetProfile();
346
347 // Returns the loaded old profile.
348 // Loads the old profile if needed. Returns nullptr if the old profile
349 // failed to load.
350 // The caller shouldn't clean up or free the returned pointer.
351 ProfileFile* GetOldProfile();
352
353 // To implement Lock(), we lock a dummy file where the oat file would go
354 // (adding ".flock" to the target file name) and retain the lock for the
355 // remaining lifetime of the OatFileAssistant object.
356 std::unique_ptr<File> lock_file_;
357 ScopedFlock flock_;
358
359 // In a properly constructed OatFileAssistant object, dex_location_ should
360 // never be nullptr.
361 const char* dex_location_ = nullptr;
362
363 // In a properly constructed OatFileAssistant object, isa_ should be either
364 // the 32 or 64 bit variant for the current device.
365 const InstructionSet isa_ = kNone;
366
367 // The package name, used solely to find the profile file.
368 // This may be nullptr in a properly constructed object. In this case,
369 // profile_load_attempted_ and old_profile_load_attempted_ will be true, and
370 // profile_load_succeeded_ and old_profile_load_succeeded_ will be false.
371 const char* package_name_ = nullptr;
372
373 // Whether we will attempt to load oat files executable.
374 bool load_executable_ = false;
375
376 // Cached value of the required dex checksum.
377 // This should be accessed only by the GetRequiredDexChecksum() method.
378 uint32_t cached_required_dex_checksum;
379 bool required_dex_checksum_attempted = false;
380 bool required_dex_checksum_found;
381
382 // Cached value of the odex file name.
383 // This should be accessed only by the OdexFileName() method.
384 bool cached_odex_file_name_attempted_ = false;
385 bool cached_odex_file_name_found_;
386 std::string cached_odex_file_name_;
387
388 // Cached value of the loaded odex file.
389 // Use the GetOdexFile method rather than accessing this directly, unless you
390 // know the odex file isn't out of date.
391 bool odex_file_load_attempted_ = false;
392 std::unique_ptr<OatFile> cached_odex_file_;
393
394 // Cached results for OdexFileIsOutOfDate
395 bool odex_file_is_out_of_date_attempted_ = false;
396 bool cached_odex_file_is_out_of_date_;
397
398 // Cached results for OdexFileIsUpToDate
399 bool odex_file_is_up_to_date_attempted_ = false;
400 bool cached_odex_file_is_up_to_date_;
401
402 // Cached value of the oat file name.
403 // This should be accessed only by the OatFileName() method.
404 bool cached_oat_file_name_attempted_ = false;
405 bool cached_oat_file_name_found_;
406 std::string cached_oat_file_name_;
407
408 // Cached value of the loaded odex file.
409 // Use the GetOatFile method rather than accessing this directly, unless you
410 // know the odex file isn't out of date.
411 bool oat_file_load_attempted_ = false;
412 std::unique_ptr<OatFile> cached_oat_file_;
413
414 // Cached results for OatFileIsOutOfDate
415 bool oat_file_is_out_of_date_attempted_ = false;
416 bool cached_oat_file_is_out_of_date_;
417
418 // Cached results for OatFileIsUpToDate
419 bool oat_file_is_up_to_date_attempted_ = false;
420 bool cached_oat_file_is_up_to_date_;
421
422 // Cached value of the image info.
423 // Use the GetImageInfo method rather than accessing these directly.
424 // TODO: The image info should probably be moved out of the oat file
425 // assistant to an image file manager.
426 bool image_info_load_attempted_ = false;
427 bool image_info_load_succeeded_ = false;
428 ImageInfo cached_image_info_;
429
430 // Cached value of the profile file.
431 // Use the GetProfile method rather than accessing these directly.
432 bool profile_load_attempted_ = false;
433 bool profile_load_succeeded_ = false;
434 ProfileFile cached_profile_;
435
436 // Cached value of the profile file.
437 // Use the GetOldProfile method rather than accessing these directly.
438 bool old_profile_load_attempted_ = false;
439 bool old_profile_load_succeeded_ = false;
440 ProfileFile cached_old_profile_;
441
442 // For debugging only.
443 // If this flag is set, the oat or odex file has been released to the user
444 // of the OatFileAssistant object and the OatFileAssistant object is in a
445 // bad state and should no longer be used.
446 bool oat_file_released_ = false;
447
448 DISALLOW_COPY_AND_ASSIGN(OatFileAssistant);
449};
450
451} // namespace art
452
453#endif // ART_RUNTIME_OAT_FILE_ASSISTANT_H_