1 /*
2  * Copyright (C) 2011 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_LIBDEXFILE_DEX_DEX_FILE_H_
18 #define ART_LIBDEXFILE_DEX_DEX_FILE_H_
19 
20 #include <memory>
21 #include <string>
22 #include <string_view>
23 #include <vector>
24 
25 #include <android-base/logging.h>
26 
27 #include "base/globals.h"
28 #include "base/hiddenapi_domain.h"
29 #include "base/macros.h"
30 #include "base/value_object.h"
31 #include "class_iterator.h"
32 #include "dex_file_structs.h"
33 #include "dex_file_types.h"
34 #include "jni.h"
35 #include "modifiers.h"
36 #include "signature.h"
37 
38 namespace art {
39 
40 class ClassDataItemIterator;
41 class CompactDexFile;
42 class DexInstructionIterator;
43 enum InvokeType : uint32_t;
44 template <typename Iter> class IterationRange;
45 class MemMap;
46 class OatDexFile;
47 class StandardDexFile;
48 class ZipArchive;
49 
50 // Some instances of DexFile own the storage referred to by DexFile.  Clients who create
51 // such management do so by subclassing Container.
52 class DexFileContainer {
53  public:
DexFileContainer()54   DexFileContainer() { }
~DexFileContainer()55   virtual ~DexFileContainer() { }
56   virtual int GetPermissions() = 0;
57   virtual bool IsReadOnly() = 0;
58   virtual bool EnableWrite() = 0;
59   virtual bool DisableWrite() = 0;
60 
61  private:
62   DISALLOW_COPY_AND_ASSIGN(DexFileContainer);
63 };
64 
65 // Dex file is the API that exposes native dex files (ordinary dex files) and CompactDex.
66 // Originally, the dex file format used by ART was mostly the same as APKs. The only change was
67 // quickened opcodes and layout optimizations.
68 // Since ART needs to support both native dex files and CompactDex files, the DexFile interface
69 // provides an abstraction to facilitate this.
70 class DexFile {
71  public:
72   // Number of bytes in the dex file magic.
73   static constexpr size_t kDexMagicSize = 4;
74   static constexpr size_t kDexVersionLen = 4;
75 
76   // First Dex format version enforcing class definition ordering rules.
77   static const uint32_t kClassDefinitionOrderEnforcedVersion = 37;
78 
79   static constexpr size_t kSha1DigestSize = 20;
80   static constexpr uint32_t kDexEndianConstant = 0x12345678;
81 
82   // The value of an invalid index.
83   static const uint16_t kDexNoIndex16 = 0xFFFF;
84   static const uint32_t kDexNoIndex32 = 0xFFFFFFFF;
85 
86   // Raw header_item.
87   struct Header {
88     uint8_t magic_[8] = {};
89     uint32_t checksum_ = 0;  // See also location_checksum_
90     uint8_t signature_[kSha1DigestSize] = {};
91     uint32_t file_size_ = 0;  // size of entire file
92     uint32_t header_size_ = 0;  // offset to start of next section
93     uint32_t endian_tag_ = 0;
94     uint32_t link_size_ = 0;  // unused
95     uint32_t link_off_ = 0;  // unused
96     uint32_t map_off_ = 0;  // map list offset from data_off_
97     uint32_t string_ids_size_ = 0;  // number of StringIds
98     uint32_t string_ids_off_ = 0;  // file offset of StringIds array
99     uint32_t type_ids_size_ = 0;  // number of TypeIds, we don't support more than 65535
100     uint32_t type_ids_off_ = 0;  // file offset of TypeIds array
101     uint32_t proto_ids_size_ = 0;  // number of ProtoIds, we don't support more than 65535
102     uint32_t proto_ids_off_ = 0;  // file offset of ProtoIds array
103     uint32_t field_ids_size_ = 0;  // number of FieldIds
104     uint32_t field_ids_off_ = 0;  // file offset of FieldIds array
105     uint32_t method_ids_size_ = 0;  // number of MethodIds
106     uint32_t method_ids_off_ = 0;  // file offset of MethodIds array
107     uint32_t class_defs_size_ = 0;  // number of ClassDefs
108     uint32_t class_defs_off_ = 0;  // file offset of ClassDef array
109     uint32_t data_size_ = 0;  // size of data section
110     uint32_t data_off_ = 0;  // file offset of data section
111 
112     // Decode the dex magic version
113     uint32_t GetVersion() const;
114   };
115 
116   // Map item type codes.
117   enum MapItemType : uint16_t {  // private
118     kDexTypeHeaderItem               = 0x0000,
119     kDexTypeStringIdItem             = 0x0001,
120     kDexTypeTypeIdItem               = 0x0002,
121     kDexTypeProtoIdItem              = 0x0003,
122     kDexTypeFieldIdItem              = 0x0004,
123     kDexTypeMethodIdItem             = 0x0005,
124     kDexTypeClassDefItem             = 0x0006,
125     kDexTypeCallSiteIdItem           = 0x0007,
126     kDexTypeMethodHandleItem         = 0x0008,
127     kDexTypeMapList                  = 0x1000,
128     kDexTypeTypeList                 = 0x1001,
129     kDexTypeAnnotationSetRefList     = 0x1002,
130     kDexTypeAnnotationSetItem        = 0x1003,
131     kDexTypeClassDataItem            = 0x2000,
132     kDexTypeCodeItem                 = 0x2001,
133     kDexTypeStringDataItem           = 0x2002,
134     kDexTypeDebugInfoItem            = 0x2003,
135     kDexTypeAnnotationItem           = 0x2004,
136     kDexTypeEncodedArrayItem         = 0x2005,
137     kDexTypeAnnotationsDirectoryItem = 0x2006,
138     kDexTypeHiddenapiClassData       = 0xF000,
139   };
140 
141   // MethodHandle Types
142   enum class MethodHandleType : uint16_t {  // private
143     kStaticPut         = 0x0000,  // a setter for a given static field.
144     kStaticGet         = 0x0001,  // a getter for a given static field.
145     kInstancePut       = 0x0002,  // a setter for a given instance field.
146     kInstanceGet       = 0x0003,  // a getter for a given instance field.
147     kInvokeStatic      = 0x0004,  // an invoker for a given static method.
148     kInvokeInstance    = 0x0005,  // invoke_instance : an invoker for a given instance method. This
149                                   // can be any non-static method on any class (or interface) except
150                                   // for “<init>”.
151     kInvokeConstructor = 0x0006,  // an invoker for a given constructor.
152     kInvokeDirect      = 0x0007,  // an invoker for a direct (special) method.
153     kInvokeInterface   = 0x0008,  // an invoker for an interface method.
154     kLast = kInvokeInterface
155   };
156 
157   // Annotation constants.
158   enum {
159     kDexVisibilityBuild         = 0x00,     /* annotation visibility */
160     kDexVisibilityRuntime       = 0x01,
161     kDexVisibilitySystem        = 0x02,
162 
163     kDexAnnotationByte          = 0x00,
164     kDexAnnotationShort         = 0x02,
165     kDexAnnotationChar          = 0x03,
166     kDexAnnotationInt           = 0x04,
167     kDexAnnotationLong          = 0x06,
168     kDexAnnotationFloat         = 0x10,
169     kDexAnnotationDouble        = 0x11,
170     kDexAnnotationMethodType    = 0x15,
171     kDexAnnotationMethodHandle  = 0x16,
172     kDexAnnotationString        = 0x17,
173     kDexAnnotationType          = 0x18,
174     kDexAnnotationField         = 0x19,
175     kDexAnnotationMethod        = 0x1a,
176     kDexAnnotationEnum          = 0x1b,
177     kDexAnnotationArray         = 0x1c,
178     kDexAnnotationAnnotation    = 0x1d,
179     kDexAnnotationNull          = 0x1e,
180     kDexAnnotationBoolean       = 0x1f,
181 
182     kDexAnnotationValueTypeMask = 0x1f,     /* low 5 bits */
183     kDexAnnotationValueArgShift = 5,
184   };
185 
186   enum AnnotationResultStyle {  // private
187     kAllObjects,
188     kPrimitivesOrObjects,
189     kAllRaw
190   };
191 
192   struct AnnotationValue;
193 
194   // Closes a .dex file.
195   virtual ~DexFile();
196 
GetLocation()197   const std::string& GetLocation() const {
198     return location_;
199   }
200 
201   // For DexFiles directly from .dex files, this is the checksum from the DexFile::Header.
202   // For DexFiles opened from a zip files, this will be the ZipEntry CRC32 of classes.dex.
GetLocationChecksum()203   uint32_t GetLocationChecksum() const {
204     return location_checksum_;
205   }
206 
GetHeader()207   const Header& GetHeader() const {
208     DCHECK(header_ != nullptr) << GetLocation();
209     return *header_;
210   }
211 
212   // Decode the dex magic version
GetDexVersion()213   uint32_t GetDexVersion() const {
214     return GetHeader().GetVersion();
215   }
216 
217   // Returns true if the byte string points to the magic value.
218   virtual bool IsMagicValid() const = 0;
219 
220   // Returns true if the byte string after the magic is the correct value.
221   virtual bool IsVersionValid() const = 0;
222 
223   // Returns true if the dex file supports default methods.
224   virtual bool SupportsDefaultMethods() const = 0;
225 
226   // Returns the maximum size in bytes needed to store an equivalent dex file strictly conforming to
227   // the dex file specification. That is the size if we wanted to get rid of all the
228   // quickening/compact-dexing/etc.
229   //
230   // TODO This should really be an exact size! b/72402467
231   virtual size_t GetDequickenedSize() const = 0;
232 
233   // Returns the number of string identifiers in the .dex file.
NumStringIds()234   size_t NumStringIds() const {
235     DCHECK(header_ != nullptr) << GetLocation();
236     return header_->string_ids_size_;
237   }
238 
239   // Returns the StringId at the specified index.
GetStringId(dex::StringIndex idx)240   const dex::StringId& GetStringId(dex::StringIndex idx) const {
241     DCHECK_LT(idx.index_, NumStringIds()) << GetLocation();
242     return string_ids_[idx.index_];
243   }
244 
GetIndexForStringId(const dex::StringId & string_id)245   dex::StringIndex GetIndexForStringId(const dex::StringId& string_id) const {
246     CHECK_GE(&string_id, string_ids_) << GetLocation();
247     CHECK_LT(&string_id, string_ids_ + header_->string_ids_size_) << GetLocation();
248     return dex::StringIndex(&string_id - string_ids_);
249   }
250 
251   int32_t GetStringLength(const dex::StringId& string_id) const;
252 
253   // Returns a pointer to the UTF-8 string data referred to by the given string_id as well as the
254   // length of the string when decoded as a UTF-16 string. Note the UTF-16 length is not the same
255   // as the string length of the string data.
256   const char* GetStringDataAndUtf16Length(const dex::StringId& string_id,
257                                           uint32_t* utf16_length) const;
258 
259   const char* GetStringData(const dex::StringId& string_id) const;
260 
261   // Index version of GetStringDataAndUtf16Length.
262   const char* StringDataAndUtf16LengthByIdx(dex::StringIndex idx, uint32_t* utf16_length) const;
263 
264   const char* StringDataByIdx(dex::StringIndex idx) const;
265   std::string_view StringViewByIdx(dex::StringIndex idx) const;
266 
267   // Looks up a string id for a given modified utf8 string.
268   const dex::StringId* FindStringId(const char* string) const;
269 
270   const dex::TypeId* FindTypeId(const char* string) const;
271 
272   // Returns the number of type identifiers in the .dex file.
NumTypeIds()273   uint32_t NumTypeIds() const {
274     DCHECK(header_ != nullptr) << GetLocation();
275     return header_->type_ids_size_;
276   }
277 
IsTypeIndexValid(dex::TypeIndex idx)278   bool IsTypeIndexValid(dex::TypeIndex idx) const {
279     return idx.IsValid() && idx.index_ < NumTypeIds();
280   }
281 
282   // Returns the TypeId at the specified index.
GetTypeId(dex::TypeIndex idx)283   const dex::TypeId& GetTypeId(dex::TypeIndex idx) const {
284     DCHECK_LT(idx.index_, NumTypeIds()) << GetLocation();
285     return type_ids_[idx.index_];
286   }
287 
GetIndexForTypeId(const dex::TypeId & type_id)288   dex::TypeIndex GetIndexForTypeId(const dex::TypeId& type_id) const {
289     CHECK_GE(&type_id, type_ids_) << GetLocation();
290     CHECK_LT(&type_id, type_ids_ + header_->type_ids_size_) << GetLocation();
291     size_t result = &type_id - type_ids_;
292     DCHECK_LT(result, 65536U) << GetLocation();
293     return dex::TypeIndex(static_cast<uint16_t>(result));
294   }
295 
296   // Get the descriptor string associated with a given type index.
297   const char* StringByTypeIdx(dex::TypeIndex idx, uint32_t* unicode_length) const;
298 
299   const char* StringByTypeIdx(dex::TypeIndex idx) const;
300 
301   // Returns the type descriptor string of a type id.
302   const char* GetTypeDescriptor(const dex::TypeId& type_id) const;
303 
304   // Looks up a type for the given string index
305   const dex::TypeId* FindTypeId(dex::StringIndex string_idx) const;
306 
307   // Returns the number of field identifiers in the .dex file.
NumFieldIds()308   size_t NumFieldIds() const {
309     DCHECK(header_ != nullptr) << GetLocation();
310     return header_->field_ids_size_;
311   }
312 
313   // Returns the FieldId at the specified index.
GetFieldId(uint32_t idx)314   const dex::FieldId& GetFieldId(uint32_t idx) const {
315     DCHECK_LT(idx, NumFieldIds()) << GetLocation();
316     return field_ids_[idx];
317   }
318 
GetIndexForFieldId(const dex::FieldId & field_id)319   uint32_t GetIndexForFieldId(const dex::FieldId& field_id) const {
320     CHECK_GE(&field_id, field_ids_) << GetLocation();
321     CHECK_LT(&field_id, field_ids_ + header_->field_ids_size_) << GetLocation();
322     return &field_id - field_ids_;
323   }
324 
325   // Looks up a field by its declaring class, name and type
326   const dex::FieldId* FindFieldId(const dex::TypeId& declaring_klass,
327                                   const dex::StringId& name,
328                                   const dex::TypeId& type) const;
329 
330   uint32_t FindCodeItemOffset(const dex::ClassDef& class_def,
331                               uint32_t dex_method_idx) const;
332 
333   virtual uint32_t GetCodeItemSize(const dex::CodeItem& disk_code_item) const = 0;
334 
335   // Returns the declaring class descriptor string of a field id.
GetFieldDeclaringClassDescriptor(const dex::FieldId & field_id)336   const char* GetFieldDeclaringClassDescriptor(const dex::FieldId& field_id) const {
337     const dex::TypeId& type_id = GetTypeId(field_id.class_idx_);
338     return GetTypeDescriptor(type_id);
339   }
340 
341   // Returns the class descriptor string of a field id.
342   const char* GetFieldTypeDescriptor(const dex::FieldId& field_id) const;
343 
344   // Returns the name of a field id.
345   const char* GetFieldName(const dex::FieldId& field_id) const;
346 
347   // Returns the number of method identifiers in the .dex file.
NumMethodIds()348   size_t NumMethodIds() const {
349     DCHECK(header_ != nullptr) << GetLocation();
350     return header_->method_ids_size_;
351   }
352 
353   // Returns the MethodId at the specified index.
GetMethodId(uint32_t idx)354   const dex::MethodId& GetMethodId(uint32_t idx) const {
355     DCHECK_LT(idx, NumMethodIds()) << GetLocation();
356     return method_ids_[idx];
357   }
358 
GetIndexForMethodId(const dex::MethodId & method_id)359   uint32_t GetIndexForMethodId(const dex::MethodId& method_id) const {
360     CHECK_GE(&method_id, method_ids_) << GetLocation();
361     CHECK_LT(&method_id, method_ids_ + header_->method_ids_size_) << GetLocation();
362     return &method_id - method_ids_;
363   }
364 
365   // Looks up a method by its declaring class, name and proto_id
366   const dex::MethodId* FindMethodId(const dex::TypeId& declaring_klass,
367                                     const dex::StringId& name,
368                                     const dex::ProtoId& signature) const;
369 
370   // Returns the declaring class descriptor string of a method id.
371   const char* GetMethodDeclaringClassDescriptor(const dex::MethodId& method_id) const;
372 
373   // Returns the prototype of a method id.
GetMethodPrototype(const dex::MethodId & method_id)374   const dex::ProtoId& GetMethodPrototype(const dex::MethodId& method_id) const {
375     return GetProtoId(method_id.proto_idx_);
376   }
377 
378   // Returns a representation of the signature of a method id.
379   const Signature GetMethodSignature(const dex::MethodId& method_id) const;
380 
381   // Returns a representation of the signature of a proto id.
382   const Signature GetProtoSignature(const dex::ProtoId& proto_id) const;
383 
384   // Returns the name of a method id.
385   const char* GetMethodName(const dex::MethodId& method_id) const;
386   const char* GetMethodName(const dex::MethodId& method_id, uint32_t* utf_length) const;
387   const char* GetMethodName(uint32_t idx, uint32_t* utf_length) const;
388 
389   // Returns the shorty of a method by its index.
390   const char* GetMethodShorty(uint32_t idx) const;
391 
392   // Returns the shorty of a method id.
393   const char* GetMethodShorty(const dex::MethodId& method_id) const;
394   const char* GetMethodShorty(const dex::MethodId& method_id, uint32_t* length) const;
395 
396   // Returns the number of class definitions in the .dex file.
NumClassDefs()397   uint32_t NumClassDefs() const {
398     DCHECK(header_ != nullptr) << GetLocation();
399     return header_->class_defs_size_;
400   }
401 
402   // Returns the ClassDef at the specified index.
GetClassDef(uint16_t idx)403   const dex::ClassDef& GetClassDef(uint16_t idx) const {
404     DCHECK_LT(idx, NumClassDefs()) << GetLocation();
405     return class_defs_[idx];
406   }
407 
GetIndexForClassDef(const dex::ClassDef & class_def)408   uint16_t GetIndexForClassDef(const dex::ClassDef& class_def) const {
409     CHECK_GE(&class_def, class_defs_) << GetLocation();
410     CHECK_LT(&class_def, class_defs_ + header_->class_defs_size_) << GetLocation();
411     return &class_def - class_defs_;
412   }
413 
414   // Returns the class descriptor string of a class definition.
415   const char* GetClassDescriptor(const dex::ClassDef& class_def) const;
416 
417   // Looks up a class definition by its type index.
418   const dex::ClassDef* FindClassDef(dex::TypeIndex type_idx) const;
419 
GetInterfacesList(const dex::ClassDef & class_def)420   const dex::TypeList* GetInterfacesList(const dex::ClassDef& class_def) const {
421     return DataPointer<dex::TypeList>(class_def.interfaces_off_);
422   }
423 
NumMethodHandles()424   uint32_t NumMethodHandles() const {
425     return num_method_handles_;
426   }
427 
GetMethodHandle(uint32_t idx)428   const dex::MethodHandleItem& GetMethodHandle(uint32_t idx) const {
429     CHECK_LT(idx, NumMethodHandles());
430     return method_handles_[idx];
431   }
432 
NumCallSiteIds()433   uint32_t NumCallSiteIds() const {
434     return num_call_site_ids_;
435   }
436 
GetCallSiteId(uint32_t idx)437   const dex::CallSiteIdItem& GetCallSiteId(uint32_t idx) const {
438     CHECK_LT(idx, NumCallSiteIds());
439     return call_site_ids_[idx];
440   }
441 
442   // Returns a pointer to the raw memory mapped class_data_item
GetClassData(const dex::ClassDef & class_def)443   const uint8_t* GetClassData(const dex::ClassDef& class_def) const {
444     return DataPointer<uint8_t>(class_def.class_data_off_);
445   }
446 
447   // Return the code item for a provided offset.
GetCodeItem(const uint32_t code_off)448   const dex::CodeItem* GetCodeItem(const uint32_t code_off) const {
449     // May be null for native or abstract methods.
450     return DataPointer<dex::CodeItem>(code_off);
451   }
452 
453   const char* GetReturnTypeDescriptor(const dex::ProtoId& proto_id) const;
454 
455   // Returns the number of prototype identifiers in the .dex file.
NumProtoIds()456   size_t NumProtoIds() const {
457     DCHECK(header_ != nullptr) << GetLocation();
458     return header_->proto_ids_size_;
459   }
460 
461   // Returns the ProtoId at the specified index.
GetProtoId(dex::ProtoIndex idx)462   const dex::ProtoId& GetProtoId(dex::ProtoIndex idx) const {
463     DCHECK_LT(idx.index_, NumProtoIds()) << GetLocation();
464     return proto_ids_[idx.index_];
465   }
466 
GetIndexForProtoId(const dex::ProtoId & proto_id)467   dex::ProtoIndex GetIndexForProtoId(const dex::ProtoId& proto_id) const {
468     CHECK_GE(&proto_id, proto_ids_) << GetLocation();
469     CHECK_LT(&proto_id, proto_ids_ + header_->proto_ids_size_) << GetLocation();
470     return dex::ProtoIndex(&proto_id - proto_ids_);
471   }
472 
473   // Looks up a proto id for a given return type and signature type list
474   const dex::ProtoId* FindProtoId(dex::TypeIndex return_type_idx,
475                                   const dex::TypeIndex* signature_type_idxs,
476                              uint32_t signature_length) const;
FindProtoId(dex::TypeIndex return_type_idx,const std::vector<dex::TypeIndex> & signature_type_idxs)477   const dex::ProtoId* FindProtoId(dex::TypeIndex return_type_idx,
478                                   const std::vector<dex::TypeIndex>& signature_type_idxs) const {
479     return FindProtoId(return_type_idx, &signature_type_idxs[0], signature_type_idxs.size());
480   }
481 
482   // Given a signature place the type ids into the given vector, returns true on success
483   bool CreateTypeList(std::string_view signature,
484                       dex::TypeIndex* return_type_idx,
485                       std::vector<dex::TypeIndex>* param_type_idxs) const;
486 
487   // Returns the short form method descriptor for the given prototype.
488   const char* GetShorty(dex::ProtoIndex proto_idx) const;
489 
GetProtoParameters(const dex::ProtoId & proto_id)490   const dex::TypeList* GetProtoParameters(const dex::ProtoId& proto_id) const {
491     return DataPointer<dex::TypeList>(proto_id.parameters_off_);
492   }
493 
GetEncodedStaticFieldValuesArray(const dex::ClassDef & class_def)494   const uint8_t* GetEncodedStaticFieldValuesArray(const dex::ClassDef& class_def) const {
495     return DataPointer<uint8_t>(class_def.static_values_off_);
496   }
497 
GetCallSiteEncodedValuesArray(const dex::CallSiteIdItem & call_site_id)498   const uint8_t* GetCallSiteEncodedValuesArray(const dex::CallSiteIdItem& call_site_id) const {
499     return DataBegin() + call_site_id.data_off_;
500   }
501 
502   dex::ProtoIndex GetProtoIndexForCallSite(uint32_t call_site_idx) const;
503 
504   static const dex::TryItem* GetTryItems(const DexInstructionIterator& code_item_end,
505                                          uint32_t offset);
506 
507   // Get the base of the encoded data for the given DexCode.
508   static const uint8_t* GetCatchHandlerData(const DexInstructionIterator& code_item_end,
509                                             uint32_t tries_size,
510                                             uint32_t offset);
511 
512   // Find which try region is associated with the given address (ie dex pc). Returns -1 if none.
513   static int32_t FindTryItem(const dex::TryItem* try_items, uint32_t tries_size, uint32_t address);
514 
515   // Get the pointer to the start of the debugging data
GetDebugInfoStream(uint32_t debug_info_off)516   const uint8_t* GetDebugInfoStream(uint32_t debug_info_off) const {
517     // Check that the offset is in bounds.
518     // Note that although the specification says that 0 should be used if there
519     // is no debug information, some applications incorrectly use 0xFFFFFFFF.
520     return (debug_info_off == 0 || debug_info_off >= data_size_)
521         ? nullptr
522         : DataBegin() + debug_info_off;
523   }
524 
525   struct PositionInfo {
526     PositionInfo() = default;
527 
528     uint32_t address_ = 0;  // In 16-bit code units.
529     uint32_t line_ = 0;  // Source code line number starting at 1.
530     const char* source_file_ = nullptr;  // nullptr if the file from ClassDef still applies.
531     bool prologue_end_ = false;
532     bool epilogue_begin_ = false;
533   };
534 
535   struct LocalInfo {
536     LocalInfo() = default;
537 
538     const char* name_ = nullptr;  // E.g., list.  It can be nullptr if unknown.
539     const char* descriptor_ = nullptr;  // E.g., Ljava/util/LinkedList;
540     const char* signature_ = nullptr;  // E.g., java.util.LinkedList<java.lang.Integer>
541     uint32_t start_address_ = 0;  // PC location where the local is first defined.
542     uint32_t end_address_ = 0;  // PC location where the local is no longer defined.
543     uint16_t reg_ = 0;  // Dex register which stores the values.
544     bool is_live_ = false;  // Is the local defined and live.
545   };
546 
547   // Callback for "new locals table entry".
548   typedef void (*DexDebugNewLocalCb)(void* context, const LocalInfo& entry);
549 
GetAnnotationsDirectory(const dex::ClassDef & class_def)550   const dex::AnnotationsDirectoryItem* GetAnnotationsDirectory(const dex::ClassDef& class_def)
551       const {
552     return DataPointer<dex::AnnotationsDirectoryItem>(class_def.annotations_off_);
553   }
554 
GetClassAnnotationSet(const dex::AnnotationsDirectoryItem * anno_dir)555   const dex::AnnotationSetItem* GetClassAnnotationSet(const dex::AnnotationsDirectoryItem* anno_dir)
556       const {
557     return DataPointer<dex::AnnotationSetItem>(anno_dir->class_annotations_off_);
558   }
559 
GetFieldAnnotations(const dex::AnnotationsDirectoryItem * anno_dir)560   const dex::FieldAnnotationsItem* GetFieldAnnotations(
561       const dex::AnnotationsDirectoryItem* anno_dir) const {
562     return (anno_dir->fields_size_ == 0)
563          ? nullptr
564          : reinterpret_cast<const dex::FieldAnnotationsItem*>(&anno_dir[1]);
565   }
566 
GetMethodAnnotations(const dex::AnnotationsDirectoryItem * anno_dir)567   const dex::MethodAnnotationsItem* GetMethodAnnotations(
568       const dex::AnnotationsDirectoryItem* anno_dir) const {
569     if (anno_dir->methods_size_ == 0) {
570       return nullptr;
571     }
572     // Skip past the header and field annotations.
573     const uint8_t* addr = reinterpret_cast<const uint8_t*>(&anno_dir[1]);
574     addr += anno_dir->fields_size_ * sizeof(dex::FieldAnnotationsItem);
575     return reinterpret_cast<const dex::MethodAnnotationsItem*>(addr);
576   }
577 
GetParameterAnnotations(const dex::AnnotationsDirectoryItem * anno_dir)578   const dex::ParameterAnnotationsItem* GetParameterAnnotations(
579       const dex::AnnotationsDirectoryItem* anno_dir) const {
580     if (anno_dir->parameters_size_ == 0) {
581       return nullptr;
582     }
583     // Skip past the header, field annotations, and method annotations.
584     const uint8_t* addr = reinterpret_cast<const uint8_t*>(&anno_dir[1]);
585     addr += anno_dir->fields_size_ * sizeof(dex::FieldAnnotationsItem);
586     addr += anno_dir->methods_size_ * sizeof(dex::MethodAnnotationsItem);
587     return reinterpret_cast<const dex::ParameterAnnotationsItem*>(addr);
588   }
589 
GetFieldAnnotationSetItem(const dex::FieldAnnotationsItem & anno_item)590   const dex::AnnotationSetItem* GetFieldAnnotationSetItem(
591       const dex::FieldAnnotationsItem& anno_item) const {
592     return DataPointer<dex::AnnotationSetItem>(anno_item.annotations_off_);
593   }
594 
GetMethodAnnotationSetItem(const dex::MethodAnnotationsItem & anno_item)595   const dex::AnnotationSetItem* GetMethodAnnotationSetItem(
596       const dex::MethodAnnotationsItem& anno_item) const {
597     return DataPointer<dex::AnnotationSetItem>(anno_item.annotations_off_);
598   }
599 
GetParameterAnnotationSetRefList(const dex::ParameterAnnotationsItem * anno_item)600   const dex::AnnotationSetRefList* GetParameterAnnotationSetRefList(
601       const dex::ParameterAnnotationsItem* anno_item) const {
602     return DataPointer<dex::AnnotationSetRefList>(anno_item->annotations_off_);
603   }
604 
GetAnnotationItemAtOffset(uint32_t offset)605   ALWAYS_INLINE const dex::AnnotationItem* GetAnnotationItemAtOffset(uint32_t offset) const {
606     return DataPointer<dex::AnnotationItem>(offset);
607   }
608 
GetHiddenapiClassDataAtOffset(uint32_t offset)609   ALWAYS_INLINE const dex::HiddenapiClassData* GetHiddenapiClassDataAtOffset(uint32_t offset)
610       const {
611     return DataPointer<dex::HiddenapiClassData>(offset);
612   }
613 
GetHiddenapiClassData()614   ALWAYS_INLINE const dex::HiddenapiClassData* GetHiddenapiClassData() const {
615     return hiddenapi_class_data_;
616   }
617 
HasHiddenapiClassData()618   ALWAYS_INLINE bool HasHiddenapiClassData() const {
619     return hiddenapi_class_data_ != nullptr;
620   }
621 
GetAnnotationItem(const dex::AnnotationSetItem * set_item,uint32_t index)622   const dex::AnnotationItem* GetAnnotationItem(const dex::AnnotationSetItem* set_item,
623                                                uint32_t index) const {
624     DCHECK_LE(index, set_item->size_);
625     return GetAnnotationItemAtOffset(set_item->entries_[index]);
626   }
627 
GetSetRefItemItem(const dex::AnnotationSetRefItem * anno_item)628   const dex::AnnotationSetItem* GetSetRefItemItem(const dex::AnnotationSetRefItem* anno_item)
629       const {
630     return DataPointer<dex::AnnotationSetItem>(anno_item->annotations_off_);
631   }
632 
633   // Debug info opcodes and constants
634   enum {
635     DBG_END_SEQUENCE         = 0x00,
636     DBG_ADVANCE_PC           = 0x01,
637     DBG_ADVANCE_LINE         = 0x02,
638     DBG_START_LOCAL          = 0x03,
639     DBG_START_LOCAL_EXTENDED = 0x04,
640     DBG_END_LOCAL            = 0x05,
641     DBG_RESTART_LOCAL        = 0x06,
642     DBG_SET_PROLOGUE_END     = 0x07,
643     DBG_SET_EPILOGUE_BEGIN   = 0x08,
644     DBG_SET_FILE             = 0x09,
645     DBG_FIRST_SPECIAL        = 0x0a,
646     DBG_LINE_BASE            = -4,
647     DBG_LINE_RANGE           = 15,
648   };
649 
650   // Returns false if there is no debugging information or if it cannot be decoded.
651   template<typename NewLocalCallback, typename IndexToStringData, typename TypeIndexToStringData>
652   static bool DecodeDebugLocalInfo(const uint8_t* stream,
653                                    const std::string& location,
654                                    const char* declaring_class_descriptor,
655                                    const std::vector<const char*>& arg_descriptors,
656                                    const std::string& method_name,
657                                    bool is_static,
658                                    uint16_t registers_size,
659                                    uint16_t ins_size,
660                                    uint16_t insns_size_in_code_units,
661                                    const IndexToStringData& index_to_string_data,
662                                    const TypeIndexToStringData& type_index_to_string_data,
663                                    const NewLocalCallback& new_local) NO_THREAD_SAFETY_ANALYSIS;
664   template<typename NewLocalCallback>
665   bool DecodeDebugLocalInfo(uint32_t registers_size,
666                             uint32_t ins_size,
667                             uint32_t insns_size_in_code_units,
668                             uint32_t debug_info_offset,
669                             bool is_static,
670                             uint32_t method_idx,
671                             const NewLocalCallback& new_local) const;
672 
673   // Returns false if there is no debugging information or if it cannot be decoded.
674   template<typename DexDebugNewPosition, typename IndexToStringData>
675   static bool DecodeDebugPositionInfo(const uint8_t* stream,
676                                       const IndexToStringData& index_to_string_data,
677                                       const DexDebugNewPosition& position_functor);
678 
GetSourceFile(const dex::ClassDef & class_def)679   const char* GetSourceFile(const dex::ClassDef& class_def) const {
680     if (!class_def.source_file_idx_.IsValid()) {
681       return nullptr;
682     } else {
683       return StringDataByIdx(class_def.source_file_idx_);
684     }
685   }
686 
687   int GetPermissions() const;
688 
689   bool IsReadOnly() const;
690 
691   bool EnableWrite() const;
692 
693   bool DisableWrite() const;
694 
Begin()695   const uint8_t* Begin() const {
696     return begin_;
697   }
698 
Size()699   size_t Size() const {
700     return size_;
701   }
702 
DataBegin()703   const uint8_t* DataBegin() const {
704     return data_begin_;
705   }
706 
DataSize()707   size_t DataSize() const {
708     return data_size_;
709   }
710 
711   template <typename T>
DataPointer(size_t offset)712   const T* DataPointer(size_t offset) const {
713     DCHECK_LT(offset, DataSize()) << "Offset past end of data section";
714     return (offset != 0u) ? reinterpret_cast<const T*>(DataBegin() + offset) : nullptr;
715   }
716 
GetOatDexFile()717   const OatDexFile* GetOatDexFile() const {
718     return oat_dex_file_;
719   }
720 
721   // Used by oat writer.
SetOatDexFile(OatDexFile * oat_dex_file)722   void SetOatDexFile(OatDexFile* oat_dex_file) const {
723     oat_dex_file_ = oat_dex_file;
724   }
725 
726   // Read MapItems and validate/set remaining offsets.
GetMapList()727   const dex::MapList* GetMapList() const {
728     return reinterpret_cast<const dex::MapList*>(DataBegin() + header_->map_off_);
729   }
730 
731   // Utility methods for reading integral values from a buffer.
732   static int32_t ReadSignedInt(const uint8_t* ptr, int zwidth);
733   static uint32_t ReadUnsignedInt(const uint8_t* ptr, int zwidth, bool fill_on_right);
734   static int64_t ReadSignedLong(const uint8_t* ptr, int zwidth);
735   static uint64_t ReadUnsignedLong(const uint8_t* ptr, int zwidth, bool fill_on_right);
736 
737   // Recalculates the checksum of the dex file. Does not use the current value in the header.
738   virtual uint32_t CalculateChecksum() const;
739   static uint32_t CalculateChecksum(const uint8_t* begin, size_t size);
740   static uint32_t ChecksumMemoryRange(const uint8_t* begin, size_t size);
741 
742   // Number of bytes at the beginning of the dex file header which are skipped
743   // when computing the adler32 checksum of the entire file.
744   static constexpr uint32_t kNumNonChecksumBytes = OFFSETOF_MEMBER(DexFile::Header, signature_);
745 
746   // Returns a human-readable form of the method at an index.
747   std::string PrettyMethod(uint32_t method_idx, bool with_signature = true) const;
748   // Returns a human-readable form of the field at an index.
749   std::string PrettyField(uint32_t field_idx, bool with_type = true) const;
750   // Returns a human-readable form of the type at an index.
751   std::string PrettyType(dex::TypeIndex type_idx) const;
752 
753   // Not virtual for performance reasons.
IsCompactDexFile()754   ALWAYS_INLINE bool IsCompactDexFile() const {
755     return is_compact_dex_;
756   }
IsStandardDexFile()757   ALWAYS_INLINE bool IsStandardDexFile() const {
758     return !is_compact_dex_;
759   }
760   ALWAYS_INLINE const StandardDexFile* AsStandardDexFile() const;
761   ALWAYS_INLINE const CompactDexFile* AsCompactDexFile() const;
762 
GetHiddenapiDomain()763   hiddenapi::Domain GetHiddenapiDomain() const { return hiddenapi_domain_; }
SetHiddenapiDomain(hiddenapi::Domain value)764   void SetHiddenapiDomain(hiddenapi::Domain value) const { hiddenapi_domain_ = value; }
765 
IsInMainSection(const void * addr)766   bool IsInMainSection(const void* addr) const {
767     return Begin() <= addr && addr < Begin() + Size();
768   }
769 
IsInDataSection(const void * addr)770   bool IsInDataSection(const void* addr) const {
771     return DataBegin() <= addr && addr < DataBegin() + DataSize();
772   }
773 
GetContainer()774   DexFileContainer* GetContainer() const {
775     return container_.get();
776   }
777 
778   IterationRange<ClassIterator> GetClasses() const;
779 
780   template <typename Visitor>
781   static uint32_t DecodeDebugInfoParameterNames(const uint8_t** debug_info,
782                                                 const Visitor& visitor);
783 
784   static inline bool StringEquals(const DexFile* df1, dex::StringIndex sidx1,
785                                   const DexFile* df2, dex::StringIndex sidx2);
786 
787  protected:
788   // First Dex format version supporting default methods.
789   static const uint32_t kDefaultMethodsVersion = 37;
790 
791   DexFile(const uint8_t* base,
792           size_t size,
793           const uint8_t* data_begin,
794           size_t data_size,
795           const std::string& location,
796           uint32_t location_checksum,
797           const OatDexFile* oat_dex_file,
798           std::unique_ptr<DexFileContainer> container,
799           bool is_compact_dex);
800 
801   // Top-level initializer that calls other Init methods.
802   bool Init(std::string* error_msg);
803 
804   // Returns true if the header magic and version numbers are of the expected values.
805   bool CheckMagicAndVersion(std::string* error_msg) const;
806 
807   // Initialize section info for sections only found in map. Returns true on success.
808   void InitializeSectionsFromMapList();
809 
810   // The base address of the memory mapping.
811   const uint8_t* const begin_;
812 
813   // The size of the underlying memory allocation in bytes.
814   const size_t size_;
815 
816   // The base address of the data section (same as Begin() for standard dex).
817   const uint8_t* const data_begin_;
818 
819   // The size of the data section.
820   const size_t data_size_;
821 
822   // Typically the dex file name when available, alternatively some identifying string.
823   //
824   // The ClassLinker will use this to match DexFiles the boot class
825   // path to DexCache::GetLocation when loading from an image.
826   const std::string location_;
827 
828   const uint32_t location_checksum_;
829 
830   // Points to the header section.
831   const Header* const header_;
832 
833   // Points to the base of the string identifier list.
834   const dex::StringId* const string_ids_;
835 
836   // Points to the base of the type identifier list.
837   const dex::TypeId* const type_ids_;
838 
839   // Points to the base of the field identifier list.
840   const dex::FieldId* const field_ids_;
841 
842   // Points to the base of the method identifier list.
843   const dex::MethodId* const method_ids_;
844 
845   // Points to the base of the prototype identifier list.
846   const dex::ProtoId* const proto_ids_;
847 
848   // Points to the base of the class definition list.
849   const dex::ClassDef* const class_defs_;
850 
851   // Points to the base of the method handles list.
852   const dex::MethodHandleItem* method_handles_;
853 
854   // Number of elements in the method handles list.
855   size_t num_method_handles_;
856 
857   // Points to the base of the call sites id list.
858   const dex::CallSiteIdItem* call_site_ids_;
859 
860   // Number of elements in the call sites list.
861   size_t num_call_site_ids_;
862 
863   // Points to the base of the hiddenapi class data item_, or nullptr if the dex
864   // file does not have one.
865   const dex::HiddenapiClassData* hiddenapi_class_data_;
866 
867   // If this dex file was loaded from an oat file, oat_dex_file_ contains a
868   // pointer to the OatDexFile it was loaded from. Otherwise oat_dex_file_ is
869   // null.
870   mutable const OatDexFile* oat_dex_file_;
871 
872   // Manages the underlying memory allocation.
873   std::unique_ptr<DexFileContainer> container_;
874 
875   // If the dex file is a compact dex file. If false then the dex file is a standard dex file.
876   const bool is_compact_dex_;
877 
878   // The domain this dex file belongs to for hidden API access checks.
879   // It is decleared `mutable` because the domain is assigned after the DexFile
880   // has been created and can be changed later by the runtime.
881   mutable hiddenapi::Domain hiddenapi_domain_;
882 
883   friend class DexFileLoader;
884   friend class DexFileVerifierTest;
885   friend class OatWriter;
886 };
887 
888 std::ostream& operator<<(std::ostream& os, const DexFile& dex_file);
889 
890 // Iterate over a dex file's ProtoId's paramters
891 class DexFileParameterIterator {
892  public:
DexFileParameterIterator(const DexFile & dex_file,const dex::ProtoId & proto_id)893   DexFileParameterIterator(const DexFile& dex_file, const dex::ProtoId& proto_id)
894       : dex_file_(dex_file) {
895     type_list_ = dex_file_.GetProtoParameters(proto_id);
896     if (type_list_ != nullptr) {
897       size_ = type_list_->Size();
898     }
899   }
HasNext()900   bool HasNext() const { return pos_ < size_; }
Size()901   size_t Size() const { return size_; }
Next()902   void Next() { ++pos_; }
GetTypeIdx()903   dex::TypeIndex GetTypeIdx() {
904     return type_list_->GetTypeItem(pos_).type_idx_;
905   }
GetDescriptor()906   const char* GetDescriptor() {
907     return dex_file_.StringByTypeIdx(dex::TypeIndex(GetTypeIdx()));
908   }
909  private:
910   const DexFile& dex_file_;
911   const dex::TypeList* type_list_ = nullptr;
912   uint32_t size_ = 0;
913   uint32_t pos_ = 0;
914   DISALLOW_IMPLICIT_CONSTRUCTORS(DexFileParameterIterator);
915 };
916 
917 class EncodedArrayValueIterator {
918  public:
919   EncodedArrayValueIterator(const DexFile& dex_file, const uint8_t* array_data);
920 
HasNext()921   bool HasNext() const { return pos_ < array_size_; }
922 
923   void Next();
924 
925   enum ValueType {
926     kByte         = 0x00,
927     kShort        = 0x02,
928     kChar         = 0x03,
929     kInt          = 0x04,
930     kLong         = 0x06,
931     kFloat        = 0x10,
932     kDouble       = 0x11,
933     kMethodType   = 0x15,
934     kMethodHandle = 0x16,
935     kString       = 0x17,
936     kType         = 0x18,
937     kField        = 0x19,
938     kMethod       = 0x1a,
939     kEnum         = 0x1b,
940     kArray        = 0x1c,
941     kAnnotation   = 0x1d,
942     kNull         = 0x1e,
943     kBoolean      = 0x1f,
944   };
945 
GetValueType()946   ValueType GetValueType() const { return type_; }
GetJavaValue()947   const jvalue& GetJavaValue() const { return jval_; }
948 
949  protected:
950   static constexpr uint8_t kEncodedValueTypeMask = 0x1f;  // 0b11111
951   static constexpr uint8_t kEncodedValueArgShift = 5;
952 
953   const DexFile& dex_file_;
954   size_t array_size_;  // Size of array.
955   size_t pos_;  // Current position.
956   const uint8_t* ptr_;  // Pointer into encoded data array.
957   ValueType type_;  // Type of current encoded value.
958   jvalue jval_;  // Value of current encoded value.
959 
960  private:
961   DISALLOW_IMPLICIT_CONSTRUCTORS(EncodedArrayValueIterator);
962 };
963 std::ostream& operator<<(std::ostream& os, const EncodedArrayValueIterator::ValueType& code);
964 
965 class EncodedStaticFieldValueIterator : public EncodedArrayValueIterator {
966  public:
EncodedStaticFieldValueIterator(const DexFile & dex_file,const dex::ClassDef & class_def)967   EncodedStaticFieldValueIterator(const DexFile& dex_file,
968                                   const dex::ClassDef& class_def)
969       : EncodedArrayValueIterator(dex_file,
970                                   dex_file.GetEncodedStaticFieldValuesArray(class_def))
971   {}
972 
973  private:
974   DISALLOW_IMPLICIT_CONSTRUCTORS(EncodedStaticFieldValueIterator);
975 };
976 std::ostream& operator<<(std::ostream& os, const EncodedStaticFieldValueIterator::ValueType& code);
977 
978 class CallSiteArrayValueIterator : public EncodedArrayValueIterator {
979  public:
CallSiteArrayValueIterator(const DexFile & dex_file,const dex::CallSiteIdItem & call_site_id)980   CallSiteArrayValueIterator(const DexFile& dex_file,
981                              const dex::CallSiteIdItem& call_site_id)
982       : EncodedArrayValueIterator(dex_file,
983                                   dex_file.GetCallSiteEncodedValuesArray(call_site_id))
984   {}
985 
Size()986   uint32_t Size() const { return array_size_; }
987 
988  private:
989   DISALLOW_IMPLICIT_CONSTRUCTORS(CallSiteArrayValueIterator);
990 };
991 std::ostream& operator<<(std::ostream& os, const CallSiteArrayValueIterator::ValueType& code);
992 
993 }  // namespace art
994 
995 #endif  // ART_LIBDEXFILE_DEX_DEX_FILE_H_
996