oat_file_assistant.h revision 325ec9bd8574b4bdff1dd6584b1b4ca6d6ddf9f9
1/* 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: 46 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, 51 52 // 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, 56 57 // 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 81 // date and has been properly relocated for the purposes of ASLR. 82 kOatUpToDate, 83 }; 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 // 93 // 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 146 // Return what action needs to be taken to produce up-to-date code for this 147 // dex location. 148 DexOptNeeded GetDexOptNeeded(); 149 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 null. 156 bool MakeUpToDate(std::string* error_msg); 157 158 // Returns an oat file that can be used for loading dex files. 159 // Returns null 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 177 // 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. 183 // 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(); 190 OatStatus OdexFileStatus(); 191 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: 202 // * OatFileName may return null if the oat file name could not be 203 // determined. 204 const std::string* OatFileName(); 205 bool OatFileExists(); 206 OatStatus OatFileStatus(); 207 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. 213 OatStatus GivenOatFileStatus(const OatFile& file); 214 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 240 // Generates the oat file by relocation from the named input file. 241 // 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 null. 248 bool RelocateOatFile(const std::string* input_file, std::string* error_msg); 249 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 null. 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 null. 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 // null 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 null 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 null 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 null 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 null 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 null 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 ScopedFlock flock_; 357 358 // In a properly constructed OatFileAssistant object, dex_location_ should 359 // never be null. 360 const char* dex_location_ = nullptr; 361 362 // In a properly constructed OatFileAssistant object, isa_ should be either 363 // the 32 or 64 bit variant for the current device. 364 const InstructionSet isa_ = kNone; 365 366 // The package name, used solely to find the profile file. 367 // This may be null in a properly constructed object. In this case, 368 // profile_load_attempted_ and old_profile_load_attempted_ will be true, and 369 // profile_load_succeeded_ and old_profile_load_succeeded_ will be false. 370 const char* package_name_ = nullptr; 371 372 // Whether we will attempt to load oat files executable. 373 bool load_executable_ = false; 374 375 // Cached value of the required dex checksum. 376 // This should be accessed only by the GetRequiredDexChecksum() method. 377 uint32_t cached_required_dex_checksum; 378 bool required_dex_checksum_attempted = false; 379 bool required_dex_checksum_found; 380 381 // Cached value of the odex file name. 382 // This should be accessed only by the OdexFileName() method. 383 bool cached_odex_file_name_attempted_ = false; 384 bool cached_odex_file_name_found_; 385 std::string cached_odex_file_name_; 386 387 // Cached value of the loaded odex file. 388 // Use the GetOdexFile method rather than accessing this directly, unless you 389 // know the odex file isn't out of date. 390 bool odex_file_load_attempted_ = false; 391 std::unique_ptr<OatFile> cached_odex_file_; 392 393 // Cached results for OdexFileIsOutOfDate 394 bool odex_file_is_out_of_date_attempted_ = false; 395 bool cached_odex_file_is_out_of_date_; 396 397 // Cached results for OdexFileIsUpToDate 398 bool odex_file_is_up_to_date_attempted_ = false; 399 bool cached_odex_file_is_up_to_date_; 400 401 // Cached value of the oat file name. 402 // This should be accessed only by the OatFileName() method. 403 bool cached_oat_file_name_attempted_ = false; 404 bool cached_oat_file_name_found_; 405 std::string cached_oat_file_name_; 406 407 // Cached value of the loaded oat file. 408 // Use the GetOatFile method rather than accessing this directly, unless you 409 // know the oat file isn't out of date. 410 bool oat_file_load_attempted_ = false; 411 std::unique_ptr<OatFile> cached_oat_file_; 412 413 // Cached results for OatFileIsOutOfDate 414 bool oat_file_is_out_of_date_attempted_ = false; 415 bool cached_oat_file_is_out_of_date_; 416 417 // Cached results for OatFileIsUpToDate 418 bool oat_file_is_up_to_date_attempted_ = false; 419 bool cached_oat_file_is_up_to_date_; 420 421 // Cached value of the image info. 422 // Use the GetImageInfo method rather than accessing these directly. 423 // TODO: The image info should probably be moved out of the oat file 424 // assistant to an image file manager. 425 bool image_info_load_attempted_ = false; 426 bool image_info_load_succeeded_ = false; 427 ImageInfo cached_image_info_; 428 429 // Cached value of the profile file. 430 // Use the GetProfile method rather than accessing these directly. 431 bool profile_load_attempted_ = false; 432 bool profile_load_succeeded_ = false; 433 ProfileFile cached_profile_; 434 435 // Cached value of the profile file. 436 // Use the GetOldProfile method rather than accessing these directly. 437 bool old_profile_load_attempted_ = false; 438 bool old_profile_load_succeeded_ = false; 439 ProfileFile cached_old_profile_; 440 441 // For debugging only. 442 // If this flag is set, the oat or odex file has been released to the user 443 // of the OatFileAssistant object and the OatFileAssistant object is in a 444 // bad state and should no longer be used. 445 bool oat_file_released_ = false; 446 447 DISALLOW_COPY_AND_ASSIGN(OatFileAssistant); 448}; 449 450} // namespace art 451 452#endif // ART_RUNTIME_OAT_FILE_ASSISTANT_H_ 453