• Home
  • History
  • Annotate
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2008 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 /*
18  * Access .dex (Dalvik Executable Format) files.  The code here assumes that
19  * the DEX file has been rewritten (byte-swapped, word-aligned) and that
20  * the contents can be directly accessed as a collection of C arrays.  Please
21  * see docs/dalvik/dex-format.html for a detailed description.
22  *
23  * The structure and field names were chosen to match those in the DEX spec.
24  *
25  * It's generally assumed that the DEX file will be stored in shared memory,
26  * obviating the need to copy code and constant pool entries into newly
27  * allocated storage.  Maintaining local pointers to items in the shared area
28  * is valid and encouraged.
29  *
30  * All memory-mapped structures are 32-bit aligned unless otherwise noted.
31  */
32 
33 #ifndef LIBDEX_DEXFILE_H_
34 #define LIBDEX_DEXFILE_H_
35 
36 #ifndef LOG_TAG
37 # define LOG_TAG "libdex"
38 #endif
39 
40 #include <stdbool.h>
41 #include <stdint.h>
42 #include <stdio.h>
43 #include <assert.h>
44 #include "cutils/log.h"
45 
46 /*
47  * If "very verbose" logging is enabled, make it equivalent to ALOGV.
48  * Otherwise, make it disappear.
49  *
50  * Define this above the #include "Dalvik.h" to enable for only a
51  * single file.
52  */
53 /* #define VERY_VERBOSE_LOG */
54 #if defined(VERY_VERBOSE_LOG)
55 # define LOGVV      ALOGV
56 # define IF_LOGVV() IF_ALOGV()
57 #else
58 # define LOGVV(...) ((void)0)
59 # define IF_LOGVV() if (false)
60 #endif
61 
62 /*
63  * These match the definitions in the VM specification.
64  */
65 typedef uint8_t             u1;
66 typedef uint16_t            u2;
67 typedef uint32_t            u4;
68 typedef uint64_t            u8;
69 typedef int8_t              s1;
70 typedef int16_t             s2;
71 typedef int32_t             s4;
72 typedef int64_t             s8;
73 
74 #include "libdex/SysUtil.h"
75 
76 /*
77  * gcc-style inline management -- ensures we have a copy of all functions
78  * in the library, so code that links against us will work whether or not
79  * it was built with optimizations enabled.
80  */
81 #ifndef _DEX_GEN_INLINES             /* only defined by DexInlines.c */
82 # define DEX_INLINE extern __inline__
83 #else
84 # define DEX_INLINE
85 #endif
86 
87 /* DEX file magic number */
88 #define DEX_MAGIC       "dex\n"
89 
90 /* The version for android N, encoded in 4 bytes of ASCII. This differentiates dex files that may
91  * use default methods.
92  */
93 #define DEX_MAGIC_VERS_37  "037\0"
94 
95 /* The version for android O, encoded in 4 bytes of ASCII. This differentiates dex files that may
96  * contain invoke-custom, invoke-polymorphic, call-sites, and method handles.
97  */
98 #define DEX_MAGIC_VERS_38  "038\0"
99 
100 /* The version for android P, encoded in 4 bytes of ASCII. This differentiates dex files that may
101  * contain const-method-handle and const-proto.
102  */
103 #define DEX_MAGIC_VERS_39  "039\0"
104 
105 /* current version, encoded in 4 bytes of ASCII */
106 #define DEX_MAGIC_VERS  "036\0"
107 
108 /*
109  * older but still-recognized version (corresponding to Android API
110  * levels 13 and earlier
111  */
112 #define DEX_MAGIC_VERS_API_13  "035\0"
113 
114 /* same, but for optimized DEX header */
115 #define DEX_OPT_MAGIC   "dey\n"
116 #define DEX_OPT_MAGIC_VERS  "036\0"
117 
118 #define DEX_DEP_MAGIC   "deps"
119 
120 /*
121  * 160-bit SHA-1 digest.
122  */
123 enum { kSHA1DigestLen = 20,
124        kSHA1DigestOutputLen = kSHA1DigestLen*2 +1 };
125 
126 /* general constants */
127 enum {
128     kDexEndianConstant = 0x12345678,    /* the endianness indicator */
129     kDexNoIndex = 0xffffffff,           /* not a valid index value */
130 };
131 
132 /*
133  * Enumeration of all the primitive types.
134  */
135 enum PrimitiveType {
136     PRIM_NOT        = 0,       /* value is a reference type, not a primitive type */
137     PRIM_VOID       = 1,
138     PRIM_BOOLEAN    = 2,
139     PRIM_BYTE       = 3,
140     PRIM_SHORT      = 4,
141     PRIM_CHAR       = 5,
142     PRIM_INT        = 6,
143     PRIM_LONG       = 7,
144     PRIM_FLOAT      = 8,
145     PRIM_DOUBLE     = 9,
146 };
147 
148 /*
149  * access flags and masks; the "standard" ones are all <= 0x4000
150  *
151  * Note: There are related declarations in vm/oo/Object.h in the ClassFlags
152  * enum.
153  */
154 enum {
155     ACC_PUBLIC       = 0x00000001,       // class, field, method, ic
156     ACC_PRIVATE      = 0x00000002,       // field, method, ic
157     ACC_PROTECTED    = 0x00000004,       // field, method, ic
158     ACC_STATIC       = 0x00000008,       // field, method, ic
159     ACC_FINAL        = 0x00000010,       // class, field, method, ic
160     ACC_SYNCHRONIZED = 0x00000020,       // method (only allowed on natives)
161     ACC_SUPER        = 0x00000020,       // class (not used in Dalvik)
162     ACC_VOLATILE     = 0x00000040,       // field
163     ACC_BRIDGE       = 0x00000040,       // method (1.5)
164     ACC_TRANSIENT    = 0x00000080,       // field
165     ACC_VARARGS      = 0x00000080,       // method (1.5)
166     ACC_NATIVE       = 0x00000100,       // method
167     ACC_INTERFACE    = 0x00000200,       // class, ic
168     ACC_ABSTRACT     = 0x00000400,       // class, method, ic
169     ACC_STRICT       = 0x00000800,       // method
170     ACC_SYNTHETIC    = 0x00001000,       // field, method, ic
171     ACC_ANNOTATION   = 0x00002000,       // class, ic (1.5)
172     ACC_ENUM         = 0x00004000,       // class, field, ic (1.5)
173     ACC_CONSTRUCTOR  = 0x00010000,       // method (Dalvik only)
174     ACC_DECLARED_SYNCHRONIZED =
175                        0x00020000,       // method (Dalvik only)
176     ACC_CLASS_MASK =
177         (ACC_PUBLIC | ACC_FINAL | ACC_INTERFACE | ACC_ABSTRACT
178                 | ACC_SYNTHETIC | ACC_ANNOTATION | ACC_ENUM),
179     ACC_INNER_CLASS_MASK =
180         (ACC_CLASS_MASK | ACC_PRIVATE | ACC_PROTECTED | ACC_STATIC),
181     ACC_FIELD_MASK =
182         (ACC_PUBLIC | ACC_PRIVATE | ACC_PROTECTED | ACC_STATIC | ACC_FINAL
183                 | ACC_VOLATILE | ACC_TRANSIENT | ACC_SYNTHETIC | ACC_ENUM),
184     ACC_METHOD_MASK =
185         (ACC_PUBLIC | ACC_PRIVATE | ACC_PROTECTED | ACC_STATIC | ACC_FINAL
186                 | ACC_SYNCHRONIZED | ACC_BRIDGE | ACC_VARARGS | ACC_NATIVE
187                 | ACC_ABSTRACT | ACC_STRICT | ACC_SYNTHETIC | ACC_CONSTRUCTOR
188                 | ACC_DECLARED_SYNCHRONIZED),
189 };
190 
191 /* annotation constants */
192 enum {
193     kDexVisibilityBuild         = 0x00,     /* annotation visibility */
194     kDexVisibilityRuntime       = 0x01,
195     kDexVisibilitySystem        = 0x02,
196 
197     kDexAnnotationByte          = 0x00,
198     kDexAnnotationShort         = 0x02,
199     kDexAnnotationChar          = 0x03,
200     kDexAnnotationInt           = 0x04,
201     kDexAnnotationLong          = 0x06,
202     kDexAnnotationFloat         = 0x10,
203     kDexAnnotationDouble        = 0x11,
204     kDexAnnotationMethodType    = 0x15,
205     kDexAnnotationMethodHandle  = 0x16,
206     kDexAnnotationString        = 0x17,
207     kDexAnnotationType          = 0x18,
208     kDexAnnotationField         = 0x19,
209     kDexAnnotationMethod        = 0x1a,
210     kDexAnnotationEnum          = 0x1b,
211     kDexAnnotationArray         = 0x1c,
212     kDexAnnotationAnnotation    = 0x1d,
213     kDexAnnotationNull          = 0x1e,
214     kDexAnnotationBoolean       = 0x1f,
215 
216     kDexAnnotationValueTypeMask = 0x1f,     /* low 5 bits */
217     kDexAnnotationValueArgShift = 5,
218 };
219 
220 /* map item type codes */
221 enum {
222     kDexTypeHeaderItem               = 0x0000,
223     kDexTypeStringIdItem             = 0x0001,
224     kDexTypeTypeIdItem               = 0x0002,
225     kDexTypeProtoIdItem              = 0x0003,
226     kDexTypeFieldIdItem              = 0x0004,
227     kDexTypeMethodIdItem             = 0x0005,
228     kDexTypeClassDefItem             = 0x0006,
229     kDexTypeCallSiteIdItem           = 0x0007,
230     kDexTypeMethodHandleItem         = 0x0008,
231     kDexTypeMapList                  = 0x1000,
232     kDexTypeTypeList                 = 0x1001,
233     kDexTypeAnnotationSetRefList     = 0x1002,
234     kDexTypeAnnotationSetItem        = 0x1003,
235     kDexTypeClassDataItem            = 0x2000,
236     kDexTypeCodeItem                 = 0x2001,
237     kDexTypeStringDataItem           = 0x2002,
238     kDexTypeDebugInfoItem            = 0x2003,
239     kDexTypeAnnotationItem           = 0x2004,
240     kDexTypeEncodedArrayItem         = 0x2005,
241     kDexTypeAnnotationsDirectoryItem = 0x2006,
242 };
243 
244 /* auxillary data section chunk codes */
245 enum {
246     kDexChunkClassLookup            = 0x434c4b50,   /* CLKP */
247     kDexChunkRegisterMaps           = 0x524d4150,   /* RMAP */
248 
249     kDexChunkEnd                    = 0x41454e44,   /* AEND */
250 };
251 
252 /* debug info opcodes and constants */
253 enum {
254     DBG_END_SEQUENCE         = 0x00,
255     DBG_ADVANCE_PC           = 0x01,
256     DBG_ADVANCE_LINE         = 0x02,
257     DBG_START_LOCAL          = 0x03,
258     DBG_START_LOCAL_EXTENDED = 0x04,
259     DBG_END_LOCAL            = 0x05,
260     DBG_RESTART_LOCAL        = 0x06,
261     DBG_SET_PROLOGUE_END     = 0x07,
262     DBG_SET_EPILOGUE_BEGIN   = 0x08,
263     DBG_SET_FILE             = 0x09,
264     DBG_FIRST_SPECIAL        = 0x0a,
265     DBG_LINE_BASE            = -4,
266     DBG_LINE_RANGE           = 15,
267 };
268 
269 /*
270  * Direct-mapped "header_item" struct.
271  */
272 struct DexHeader {
273     u1  magic[8];           /* includes version number */
274     u4  checksum;           /* adler32 checksum */
275     u1  signature[kSHA1DigestLen]; /* SHA-1 hash */
276     u4  fileSize;           /* length of entire file */
277     u4  headerSize;         /* offset to start of next section */
278     u4  endianTag;
279     u4  linkSize;
280     u4  linkOff;
281     u4  mapOff;
282     u4  stringIdsSize;
283     u4  stringIdsOff;
284     u4  typeIdsSize;
285     u4  typeIdsOff;
286     u4  protoIdsSize;
287     u4  protoIdsOff;
288     u4  fieldIdsSize;
289     u4  fieldIdsOff;
290     u4  methodIdsSize;
291     u4  methodIdsOff;
292     u4  classDefsSize;
293     u4  classDefsOff;
294     u4  dataSize;
295     u4  dataOff;
296 };
297 
298 /*
299  * Direct-mapped "map_item".
300  */
301 struct DexMapItem {
302     u2 type;              /* type code (see kDexType* above) */
303     u2 unused;
304     u4 size;              /* count of items of the indicated type */
305     u4 offset;            /* file offset to the start of data */
306 };
307 
308 /*
309  * Direct-mapped "map_list".
310  */
311 struct DexMapList {
312     u4  size;               /* #of entries in list */
313     DexMapItem list[1];     /* entries */
314 };
315 
316 /*
317  * Direct-mapped "string_id_item".
318  */
319 struct DexStringId {
320     u4 stringDataOff;      /* file offset to string_data_item */
321 };
322 
323 /*
324  * Direct-mapped "type_id_item".
325  */
326 struct DexTypeId {
327     u4  descriptorIdx;      /* index into stringIds list for type descriptor */
328 };
329 
330 /*
331  * Direct-mapped "field_id_item".
332  */
333 struct DexFieldId {
334     u2  classIdx;           /* index into typeIds list for defining class */
335     u2  typeIdx;            /* index into typeIds for field type */
336     u4  nameIdx;            /* index into stringIds for field name */
337 };
338 
339 /*
340  * Direct-mapped "method_id_item".
341  */
342 struct DexMethodId {
343     u2  classIdx;           /* index into typeIds list for defining class */
344     u2  protoIdx;           /* index into protoIds for method prototype */
345     u4  nameIdx;            /* index into stringIds for method name */
346 };
347 
348 /*
349  * Direct-mapped "proto_id_item".
350  */
351 struct DexProtoId {
352     u4  shortyIdx;          /* index into stringIds for shorty descriptor */
353     u4  returnTypeIdx;      /* index into typeIds list for return type */
354     u4  parametersOff;      /* file offset to type_list for parameter types */
355 };
356 
357 /*
358  * Direct-mapped "class_def_item".
359  */
360 struct DexClassDef {
361     u4  classIdx;           /* index into typeIds for this class */
362     u4  accessFlags;
363     u4  superclassIdx;      /* index into typeIds for superclass */
364     u4  interfacesOff;      /* file offset to DexTypeList */
365     u4  sourceFileIdx;      /* index into stringIds for source file name */
366     u4  annotationsOff;     /* file offset to annotations_directory_item */
367     u4  classDataOff;       /* file offset to class_data_item */
368     u4  staticValuesOff;    /* file offset to DexEncodedArray */
369 };
370 
371 /*
372  * Direct-mapped "call_site_id_item"
373  */
374 struct DexCallSiteId {
375     u4  callSiteOff;        /* file offset to DexEncodedArray */
376 };
377 
378 /*
379  * Enumeration of method handle type codes.
380  */
381 enum MethodHandleType {
382     STATIC_PUT = 0x00,
383     STATIC_GET = 0x01,
384     INSTANCE_PUT = 0x02,
385     INSTANCE_GET = 0x03,
386     INVOKE_STATIC = 0x04,
387     INVOKE_INSTANCE = 0x05,
388     INVOKE_CONSTRUCTOR = 0x06,
389     INVOKE_DIRECT = 0x07,
390     INVOKE_INTERFACE = 0x08
391 };
392 
393 /*
394  * Direct-mapped "method_handle_item"
395  */
396 struct DexMethodHandleItem {
397     u2 methodHandleType;    /* type of method handle */
398     u2 reserved1;           /* reserved for future use */
399     u2 fieldOrMethodIdx;    /* index of associated field or method */
400     u2 reserved2;           /* reserved for future use */
401 };
402 
403 /*
404  * Direct-mapped "type_item".
405  */
406 struct DexTypeItem {
407     u2  typeIdx;            /* index into typeIds */
408 };
409 
410 /*
411  * Direct-mapped "type_list".
412  */
413 struct DexTypeList {
414     u4  size;               /* #of entries in list */
415     DexTypeItem list[1];    /* entries */
416 };
417 
418 /*
419  * Direct-mapped "code_item".
420  *
421  * The "catches" table is used when throwing an exception,
422  * "debugInfo" is used when displaying an exception stack trace or
423  * debugging. An offset of zero indicates that there are no entries.
424  */
425 struct DexCode {
426     u2  registersSize;
427     u2  insSize;
428     u2  outsSize;
429     u2  triesSize;
430     u4  debugInfoOff;       /* file offset to debug info stream */
431     u4  insnsSize;          /* size of the insns array, in u2 units */
432     u2  insns[1];
433     /* followed by optional u2 padding */
434     /* followed by try_item[triesSize] */
435     /* followed by uleb128 handlersSize */
436     /* followed by catch_handler_item[handlersSize] */
437 };
438 
439 /*
440  * Direct-mapped "try_item".
441  */
442 struct DexTry {
443     u4  startAddr;          /* start address, in 16-bit code units */
444     u2  insnCount;          /* instruction count, in 16-bit code units */
445     u2  handlerOff;         /* offset in encoded handler data to handlers */
446 };
447 
448 /*
449  * Link table.  Currently undefined.
450  */
451 struct DexLink {
452     u1  bleargh;
453 };
454 
455 
456 /*
457  * Direct-mapped "annotations_directory_item".
458  */
459 struct DexAnnotationsDirectoryItem {
460     u4  classAnnotationsOff;  /* offset to DexAnnotationSetItem */
461     u4  fieldsSize;           /* count of DexFieldAnnotationsItem */
462     u4  methodsSize;          /* count of DexMethodAnnotationsItem */
463     u4  parametersSize;       /* count of DexParameterAnnotationsItem */
464     /* followed by DexFieldAnnotationsItem[fieldsSize] */
465     /* followed by DexMethodAnnotationsItem[methodsSize] */
466     /* followed by DexParameterAnnotationsItem[parametersSize] */
467 };
468 
469 /*
470  * Direct-mapped "field_annotations_item".
471  */
472 struct DexFieldAnnotationsItem {
473     u4  fieldIdx;
474     u4  annotationsOff;             /* offset to DexAnnotationSetItem */
475 };
476 
477 /*
478  * Direct-mapped "method_annotations_item".
479  */
480 struct DexMethodAnnotationsItem {
481     u4  methodIdx;
482     u4  annotationsOff;             /* offset to DexAnnotationSetItem */
483 };
484 
485 /*
486  * Direct-mapped "parameter_annotations_item".
487  */
488 struct DexParameterAnnotationsItem {
489     u4  methodIdx;
490     u4  annotationsOff;             /* offset to DexAnotationSetRefList */
491 };
492 
493 /*
494  * Direct-mapped "annotation_set_ref_item".
495  */
496 struct DexAnnotationSetRefItem {
497     u4  annotationsOff;             /* offset to DexAnnotationSetItem */
498 };
499 
500 /*
501  * Direct-mapped "annotation_set_ref_list".
502  */
503 struct DexAnnotationSetRefList {
504     u4  size;
505     DexAnnotationSetRefItem list[1];
506 };
507 
508 /*
509  * Direct-mapped "annotation_set_item".
510  */
511 struct DexAnnotationSetItem {
512     u4  size;
513     u4  entries[1];                 /* offset to DexAnnotationItem */
514 };
515 
516 /*
517  * Direct-mapped "annotation_item".
518  *
519  * NOTE: this structure is byte-aligned.
520  */
521 struct DexAnnotationItem {
522     u1  visibility;
523     u1  annotation[1];              /* data in encoded_annotation format */
524 };
525 
526 /*
527  * Direct-mapped "encoded_array".
528  *
529  * NOTE: this structure is byte-aligned.
530  */
531 struct DexEncodedArray {
532     u1  array[1];                   /* data in encoded_array format */
533 };
534 
535 /*
536  * Lookup table for classes.  It provides a mapping from class name to
537  * class definition.  Used by dexFindClass().
538  *
539  * We calculate this at DEX optimization time and embed it in the file so we
540  * don't need the same hash table in every VM.  This is slightly slower than
541  * a hash table with direct pointers to the items, but because it's shared
542  * there's less of a penalty for using a fairly sparse table.
543  */
544 struct DexClassLookup {
545     int     size;                       // total size, including "size"
546     int     numEntries;                 // size of table[]; always power of 2
547     struct {
548         u4      classDescriptorHash;    // class descriptor hash code
549         int     classDescriptorOffset;  // in bytes, from start of DEX
550         int     classDefOffset;         // in bytes, from start of DEX
551     } table[1];
552 };
553 
554 /*
555  * Header added by DEX optimization pass.  Values are always written in
556  * local byte and structure padding.  The first field (magic + version)
557  * is guaranteed to be present and directly readable for all expected
558  * compiler configurations; the rest is version-dependent.
559  *
560  * Try to keep this simple and fixed-size.
561  */
562 struct DexOptHeader {
563     u1  magic[8];           /* includes version number */
564 
565     u4  dexOffset;          /* file offset of DEX header */
566     u4  dexLength;
567     u4  depsOffset;         /* offset of optimized DEX dependency table */
568     u4  depsLength;
569     u4  optOffset;          /* file offset of optimized data tables */
570     u4  optLength;
571 
572     u4  flags;              /* some info flags */
573     u4  checksum;           /* adler32 checksum covering deps/opt */
574 
575     /* pad for 64-bit alignment if necessary */
576 };
577 
578 #define DEX_OPT_FLAG_BIG            (1<<1)  /* swapped to big-endian */
579 
580 #define DEX_INTERFACE_CACHE_SIZE    128     /* must be power of 2 */
581 
582 /*
583  * Structure representing a DEX file.
584  *
585  * Code should regard DexFile as opaque, using the API calls provided here
586  * to access specific structures.
587  */
588 struct DexFile {
589     /* directly-mapped "opt" header */
590     const DexOptHeader* pOptHeader;
591 
592     /* pointers to directly-mapped structs and arrays in base DEX */
593     const DexHeader*    pHeader;
594     const DexStringId*  pStringIds;
595     const DexTypeId*    pTypeIds;
596     const DexFieldId*   pFieldIds;
597     const DexMethodId*  pMethodIds;
598     const DexProtoId*   pProtoIds;
599     const DexClassDef*  pClassDefs;
600     const DexLink*      pLinkData;
601 
602     /*
603      * These are mapped out of the "auxillary" section, and may not be
604      * included in the file.
605      */
606     const DexClassLookup* pClassLookup;
607     const void*         pRegisterMapPool;       // RegisterMapClassPool
608 
609     /* points to start of DEX file data */
610     const u1*           baseAddr;
611 
612     /* track memory overhead for auxillary structures */
613     int                 overhead;
614 
615     /* additional app-specific data structures associated with the DEX */
616     //void*               auxData;
617 };
618 
619 /*
620  * Utility function -- rounds up to the nearest power of 2.
621  */
622 u4 dexRoundUpPower2(u4 val);
623 
624 /*
625  * Parse an optimized or unoptimized .dex file sitting in memory.
626  *
627  * On success, return a newly-allocated DexFile.
628  */
629 DexFile* dexFileParse(const u1* data, size_t length, int flags);
630 
631 /* bit values for "flags" argument to dexFileParse */
632 enum {
633     kDexParseDefault            = 0,
634     kDexParseVerifyChecksum     = 1,
635     kDexParseContinueOnError    = (1 << 1),
636 };
637 
638 /*
639  * Fix the byte ordering of all fields in the DEX file, and do
640  * structural verification. This is only required for code that opens
641  * "raw" DEX files, such as the DEX optimizer.
642  *
643  * Return 0 on success.
644  */
645 int dexSwapAndVerify(u1* addr, int len);
646 
647 /*
648  * Detect the file type of the given memory buffer via magic number.
649  * Call dexSwapAndVerify() on an unoptimized DEX file, do nothing
650  * but return successfully on an optimized DEX file, and report an
651  * error for all other cases.
652  *
653  * Return 0 on success.
654  */
655 int dexSwapAndVerifyIfNecessary(u1* addr, size_t len);
656 
657 /*
658  * Check to see if the file magic and format version in the given
659  * header are recognized as valid. Returns true if they are
660  * acceptable.
661  */
662 bool dexHasValidMagic(const DexHeader* pHeader);
663 
664 /*
665  * Compute DEX checksum.
666  */
667 u4 dexComputeChecksum(const DexHeader* pHeader);
668 
669 /*
670  * Free a DexFile structure, along with any associated structures.
671  */
672 void dexFileFree(DexFile* pDexFile);
673 
674 /*
675  * Create class lookup table.
676  */
677 DexClassLookup* dexCreateClassLookup(DexFile* pDexFile);
678 
679 /*
680  * Find a class definition by descriptor.
681  */
682 const DexClassDef* dexFindClass(const DexFile* pFile, const char* descriptor);
683 
684 /*
685  * Set up the basic raw data pointers of a DexFile. This function isn't
686  * meant for general use.
687  */
688 void dexFileSetupBasicPointers(DexFile* pDexFile, const u1* data);
689 
690 /* return the DexMapList of the file, if any */
dexGetMap(const DexFile * pDexFile)691 DEX_INLINE const DexMapList* dexGetMap(const DexFile* pDexFile) {
692     u4 mapOff = pDexFile->pHeader->mapOff;
693 
694     if (mapOff == 0) {
695         return NULL;
696     } else {
697         return (const DexMapList*) (pDexFile->baseAddr + mapOff);
698     }
699 }
700 
701 /* return the const char* string data referred to by the given string_id */
dexGetStringData(const DexFile * pDexFile,const DexStringId * pStringId)702 DEX_INLINE const char* dexGetStringData(const DexFile* pDexFile,
703         const DexStringId* pStringId) {
704     const u1* ptr = pDexFile->baseAddr + pStringId->stringDataOff;
705 
706     // Skip the uleb128 length.
707     while (*(ptr++) > 0x7f) /* empty */ ;
708 
709     return (const char*) ptr;
710 }
711 /* return the StringId with the specified index */
dexGetStringId(const DexFile * pDexFile,u4 idx)712 DEX_INLINE const DexStringId* dexGetStringId(const DexFile* pDexFile, u4 idx) {
713     assert(idx < pDexFile->pHeader->stringIdsSize);
714     return &pDexFile->pStringIds[idx];
715 }
716 /* return the UTF-8 encoded string with the specified string_id index */
dexStringById(const DexFile * pDexFile,u4 idx)717 DEX_INLINE const char* dexStringById(const DexFile* pDexFile, u4 idx) {
718     const DexStringId* pStringId = dexGetStringId(pDexFile, idx);
719     return dexGetStringData(pDexFile, pStringId);
720 }
721 
722 /* Return the UTF-8 encoded string with the specified string_id index,
723  * also filling in the UTF-16 size (number of 16-bit code points).*/
724 const char* dexStringAndSizeById(const DexFile* pDexFile, u4 idx,
725         u4* utf16Size);
726 
727 /* return the TypeId with the specified index */
dexGetTypeId(const DexFile * pDexFile,u4 idx)728 DEX_INLINE const DexTypeId* dexGetTypeId(const DexFile* pDexFile, u4 idx) {
729     assert(idx < pDexFile->pHeader->typeIdsSize);
730     return &pDexFile->pTypeIds[idx];
731 }
732 
733 /*
734  * Get the descriptor string associated with a given type index.
735  * The caller should not free() the returned string.
736  */
dexStringByTypeIdx(const DexFile * pDexFile,u4 idx)737 DEX_INLINE const char* dexStringByTypeIdx(const DexFile* pDexFile, u4 idx) {
738     const DexTypeId* typeId = dexGetTypeId(pDexFile, idx);
739     return dexStringById(pDexFile, typeId->descriptorIdx);
740 }
741 
742 /* return the MethodId with the specified index */
dexGetMethodId(const DexFile * pDexFile,u4 idx)743 DEX_INLINE const DexMethodId* dexGetMethodId(const DexFile* pDexFile, u4 idx) {
744     assert(idx < pDexFile->pHeader->methodIdsSize);
745     return &pDexFile->pMethodIds[idx];
746 }
747 
748 /* return the FieldId with the specified index */
dexGetFieldId(const DexFile * pDexFile,u4 idx)749 DEX_INLINE const DexFieldId* dexGetFieldId(const DexFile* pDexFile, u4 idx) {
750     assert(idx < pDexFile->pHeader->fieldIdsSize);
751     return &pDexFile->pFieldIds[idx];
752 }
753 
754 /* return the ProtoId with the specified index */
dexGetProtoId(const DexFile * pDexFile,u4 idx)755 DEX_INLINE const DexProtoId* dexGetProtoId(const DexFile* pDexFile, u4 idx) {
756     assert(idx < pDexFile->pHeader->protoIdsSize);
757     return &pDexFile->pProtoIds[idx];
758 }
759 
760 /*
761  * Get the parameter list from a ProtoId. The returns NULL if the ProtoId
762  * does not have a parameter list.
763  */
dexGetProtoParameters(const DexFile * pDexFile,const DexProtoId * pProtoId)764 DEX_INLINE const DexTypeList* dexGetProtoParameters(
765     const DexFile *pDexFile, const DexProtoId* pProtoId) {
766     if (pProtoId->parametersOff == 0) {
767         return NULL;
768     }
769     return (const DexTypeList*)
770         (pDexFile->baseAddr + pProtoId->parametersOff);
771 }
772 
773 /* return the ClassDef with the specified index */
dexGetClassDef(const DexFile * pDexFile,u4 idx)774 DEX_INLINE const DexClassDef* dexGetClassDef(const DexFile* pDexFile, u4 idx) {
775     assert(idx < pDexFile->pHeader->classDefsSize);
776     return &pDexFile->pClassDefs[idx];
777 }
778 
779 /* given a ClassDef pointer, recover its index */
dexGetIndexForClassDef(const DexFile * pDexFile,const DexClassDef * pClassDef)780 DEX_INLINE u4 dexGetIndexForClassDef(const DexFile* pDexFile,
781     const DexClassDef* pClassDef)
782 {
783     assert(pClassDef >= pDexFile->pClassDefs &&
784            pClassDef < pDexFile->pClassDefs + pDexFile->pHeader->classDefsSize);
785     return pClassDef - pDexFile->pClassDefs;
786 }
787 
788 /* get the interface list for a DexClass */
dexGetInterfacesList(const DexFile * pDexFile,const DexClassDef * pClassDef)789 DEX_INLINE const DexTypeList* dexGetInterfacesList(const DexFile* pDexFile,
790     const DexClassDef* pClassDef)
791 {
792     if (pClassDef->interfacesOff == 0)
793         return NULL;
794     return (const DexTypeList*)
795         (pDexFile->baseAddr + pClassDef->interfacesOff);
796 }
797 /* return the Nth entry in a DexTypeList. */
dexGetTypeItem(const DexTypeList * pList,u4 idx)798 DEX_INLINE const DexTypeItem* dexGetTypeItem(const DexTypeList* pList,
799     u4 idx)
800 {
801     assert(idx < pList->size);
802     return &pList->list[idx];
803 }
804 /* return the type_idx for the Nth entry in a TypeList */
dexTypeListGetIdx(const DexTypeList * pList,u4 idx)805 DEX_INLINE u4 dexTypeListGetIdx(const DexTypeList* pList, u4 idx) {
806     const DexTypeItem* pItem = dexGetTypeItem(pList, idx);
807     return pItem->typeIdx;
808 }
809 
810 /* get the static values list for a DexClass */
dexGetStaticValuesList(const DexFile * pDexFile,const DexClassDef * pClassDef)811 DEX_INLINE const DexEncodedArray* dexGetStaticValuesList(
812     const DexFile* pDexFile, const DexClassDef* pClassDef)
813 {
814     if (pClassDef->staticValuesOff == 0)
815         return NULL;
816     return (const DexEncodedArray*)
817         (pDexFile->baseAddr + pClassDef->staticValuesOff);
818 }
819 
820 /* get the annotations directory item for a DexClass */
dexGetAnnotationsDirectoryItem(const DexFile * pDexFile,const DexClassDef * pClassDef)821 DEX_INLINE const DexAnnotationsDirectoryItem* dexGetAnnotationsDirectoryItem(
822     const DexFile* pDexFile, const DexClassDef* pClassDef)
823 {
824     if (pClassDef->annotationsOff == 0)
825         return NULL;
826     return (const DexAnnotationsDirectoryItem*)
827         (pDexFile->baseAddr + pClassDef->annotationsOff);
828 }
829 
830 /* get the source file string */
dexGetSourceFile(const DexFile * pDexFile,const DexClassDef * pClassDef)831 DEX_INLINE const char* dexGetSourceFile(
832     const DexFile* pDexFile, const DexClassDef* pClassDef)
833 {
834     if (pClassDef->sourceFileIdx == 0xffffffff)
835         return NULL;
836     return dexStringById(pDexFile, pClassDef->sourceFileIdx);
837 }
838 
839 /* get the size, in bytes, of a DexCode */
840 size_t dexGetDexCodeSize(const DexCode* pCode);
841 
842 /* Get the list of "tries" for the given DexCode. */
dexGetTries(const DexCode * pCode)843 DEX_INLINE const DexTry* dexGetTries(const DexCode* pCode) {
844     const u2* insnsEnd = &pCode->insns[pCode->insnsSize];
845 
846     // Round to four bytes.
847     if ((((uintptr_t) insnsEnd) & 3) != 0) {
848         insnsEnd++;
849     }
850 
851     return (const DexTry*) insnsEnd;
852 }
853 
854 /* Get the base of the encoded data for the given DexCode. */
dexGetCatchHandlerData(const DexCode * pCode)855 DEX_INLINE const u1* dexGetCatchHandlerData(const DexCode* pCode) {
856     const DexTry* pTries = dexGetTries(pCode);
857     return (const u1*) &pTries[pCode->triesSize];
858 }
859 
860 /* get a pointer to the start of the debugging data */
dexGetDebugInfoStream(const DexFile * pDexFile,const DexCode * pCode)861 DEX_INLINE const u1* dexGetDebugInfoStream(const DexFile* pDexFile,
862     const DexCode* pCode)
863 {
864     if (pCode->debugInfoOff == 0) {
865         return NULL;
866     } else {
867         return pDexFile->baseAddr + pCode->debugInfoOff;
868     }
869 }
870 
871 /* DexClassDef convenience - get class descriptor */
dexGetClassDescriptor(const DexFile * pDexFile,const DexClassDef * pClassDef)872 DEX_INLINE const char* dexGetClassDescriptor(const DexFile* pDexFile,
873     const DexClassDef* pClassDef)
874 {
875     return dexStringByTypeIdx(pDexFile, pClassDef->classIdx);
876 }
877 
878 /* DexClassDef convenience - get superclass descriptor */
dexGetSuperClassDescriptor(const DexFile * pDexFile,const DexClassDef * pClassDef)879 DEX_INLINE const char* dexGetSuperClassDescriptor(const DexFile* pDexFile,
880     const DexClassDef* pClassDef)
881 {
882     if (pClassDef->superclassIdx == 0)
883         return NULL;
884     return dexStringByTypeIdx(pDexFile, pClassDef->superclassIdx);
885 }
886 
887 /* DexClassDef convenience - get class_data_item pointer */
dexGetClassData(const DexFile * pDexFile,const DexClassDef * pClassDef)888 DEX_INLINE const u1* dexGetClassData(const DexFile* pDexFile,
889     const DexClassDef* pClassDef)
890 {
891     if (pClassDef->classDataOff == 0)
892         return NULL;
893     return (const u1*) (pDexFile->baseAddr + pClassDef->classDataOff);
894 }
895 
896 /* Get an annotation set at a particular offset. */
dexGetAnnotationSetItem(const DexFile * pDexFile,u4 offset)897 DEX_INLINE const DexAnnotationSetItem* dexGetAnnotationSetItem(
898     const DexFile* pDexFile, u4 offset)
899 {
900     if (offset == 0) {
901         return NULL;
902     }
903     return (const DexAnnotationSetItem*) (pDexFile->baseAddr + offset);
904 }
905 /* get the class' annotation set */
dexGetClassAnnotationSet(const DexFile * pDexFile,const DexAnnotationsDirectoryItem * pAnnoDir)906 DEX_INLINE const DexAnnotationSetItem* dexGetClassAnnotationSet(
907     const DexFile* pDexFile, const DexAnnotationsDirectoryItem* pAnnoDir)
908 {
909     return dexGetAnnotationSetItem(pDexFile, pAnnoDir->classAnnotationsOff);
910 }
911 
912 /* get the class' field annotation list */
dexGetFieldAnnotations(const DexFile * pDexFile,const DexAnnotationsDirectoryItem * pAnnoDir)913 DEX_INLINE const DexFieldAnnotationsItem* dexGetFieldAnnotations(
914     const DexFile* pDexFile, const DexAnnotationsDirectoryItem* pAnnoDir)
915 {
916     (void) pDexFile;
917     if (pAnnoDir->fieldsSize == 0)
918         return NULL;
919 
920     // Skip past the header to the start of the field annotations.
921     return (const DexFieldAnnotationsItem*) &pAnnoDir[1];
922 }
923 
924 /* get field annotation list size */
dexGetFieldAnnotationsSize(const DexFile * pDexFile,const DexAnnotationsDirectoryItem * pAnnoDir)925 DEX_INLINE int dexGetFieldAnnotationsSize(const DexFile* pDexFile,
926     const DexAnnotationsDirectoryItem* pAnnoDir)
927 {
928     (void) pDexFile;
929     return pAnnoDir->fieldsSize;
930 }
931 
932 /* return a pointer to the field's annotation set */
dexGetFieldAnnotationSetItem(const DexFile * pDexFile,const DexFieldAnnotationsItem * pItem)933 DEX_INLINE const DexAnnotationSetItem* dexGetFieldAnnotationSetItem(
934     const DexFile* pDexFile, const DexFieldAnnotationsItem* pItem)
935 {
936     return dexGetAnnotationSetItem(pDexFile, pItem->annotationsOff);
937 }
938 
939 /* get the class' method annotation list */
dexGetMethodAnnotations(const DexFile * pDexFile,const DexAnnotationsDirectoryItem * pAnnoDir)940 DEX_INLINE const DexMethodAnnotationsItem* dexGetMethodAnnotations(
941     const DexFile* pDexFile, const DexAnnotationsDirectoryItem* pAnnoDir)
942 {
943     (void) pDexFile;
944     if (pAnnoDir->methodsSize == 0)
945         return NULL;
946 
947     /*
948      * Skip past the header and field annotations to the start of the
949      * method annotations.
950      */
951     const u1* addr = (const u1*) &pAnnoDir[1];
952     addr += pAnnoDir->fieldsSize * sizeof (DexFieldAnnotationsItem);
953     return (const DexMethodAnnotationsItem*) addr;
954 }
955 
956 /* get method annotation list size */
dexGetMethodAnnotationsSize(const DexFile * pDexFile,const DexAnnotationsDirectoryItem * pAnnoDir)957 DEX_INLINE int dexGetMethodAnnotationsSize(const DexFile* pDexFile,
958     const DexAnnotationsDirectoryItem* pAnnoDir)
959 {
960     (void) pDexFile;
961     return pAnnoDir->methodsSize;
962 }
963 
964 /* return a pointer to the method's annotation set */
dexGetMethodAnnotationSetItem(const DexFile * pDexFile,const DexMethodAnnotationsItem * pItem)965 DEX_INLINE const DexAnnotationSetItem* dexGetMethodAnnotationSetItem(
966     const DexFile* pDexFile, const DexMethodAnnotationsItem* pItem)
967 {
968     return dexGetAnnotationSetItem(pDexFile, pItem->annotationsOff);
969 }
970 
971 /* get the class' parameter annotation list */
dexGetParameterAnnotations(const DexFile * pDexFile,const DexAnnotationsDirectoryItem * pAnnoDir)972 DEX_INLINE const DexParameterAnnotationsItem* dexGetParameterAnnotations(
973     const DexFile* pDexFile, const DexAnnotationsDirectoryItem* pAnnoDir)
974 {
975     (void) pDexFile;
976     if (pAnnoDir->parametersSize == 0)
977         return NULL;
978 
979     /*
980      * Skip past the header, field annotations, and method annotations
981      * to the start of the parameter annotations.
982      */
983     const u1* addr = (const u1*) &pAnnoDir[1];
984     addr += pAnnoDir->fieldsSize * sizeof (DexFieldAnnotationsItem);
985     addr += pAnnoDir->methodsSize * sizeof (DexMethodAnnotationsItem);
986     return (const DexParameterAnnotationsItem*) addr;
987 }
988 
989 /* get method annotation list size */
dexGetParameterAnnotationsSize(const DexFile * pDexFile,const DexAnnotationsDirectoryItem * pAnnoDir)990 DEX_INLINE int dexGetParameterAnnotationsSize(const DexFile* pDexFile,
991     const DexAnnotationsDirectoryItem* pAnnoDir)
992 {
993     (void) pDexFile;
994     return pAnnoDir->parametersSize;
995 }
996 
997 /* return the parameter annotation ref list */
dexGetParameterAnnotationSetRefList(const DexFile * pDexFile,const DexParameterAnnotationsItem * pItem)998 DEX_INLINE const DexAnnotationSetRefList* dexGetParameterAnnotationSetRefList(
999     const DexFile* pDexFile, const DexParameterAnnotationsItem* pItem)
1000 {
1001     if (pItem->annotationsOff == 0) {
1002         return NULL;
1003     }
1004     return (const DexAnnotationSetRefList*) (pDexFile->baseAddr + pItem->annotationsOff);
1005 }
1006 
1007 /* get method annotation list size */
dexGetParameterAnnotationSetRefSize(const DexFile * pDexFile,const DexParameterAnnotationsItem * pItem)1008 DEX_INLINE int dexGetParameterAnnotationSetRefSize(const DexFile* pDexFile,
1009     const DexParameterAnnotationsItem* pItem)
1010 {
1011     if (pItem->annotationsOff == 0) {
1012         return 0;
1013     }
1014     return dexGetParameterAnnotationSetRefList(pDexFile, pItem)->size;
1015 }
1016 
1017 /* return the Nth entry from an annotation set ref list */
dexGetParameterAnnotationSetRef(const DexAnnotationSetRefList * pList,u4 idx)1018 DEX_INLINE const DexAnnotationSetRefItem* dexGetParameterAnnotationSetRef(
1019     const DexAnnotationSetRefList* pList, u4 idx)
1020 {
1021     assert(idx < pList->size);
1022     return &pList->list[idx];
1023 }
1024 
1025 /* given a DexAnnotationSetRefItem, return the DexAnnotationSetItem */
dexGetSetRefItemItem(const DexFile * pDexFile,const DexAnnotationSetRefItem * pItem)1026 DEX_INLINE const DexAnnotationSetItem* dexGetSetRefItemItem(
1027     const DexFile* pDexFile, const DexAnnotationSetRefItem* pItem)
1028 {
1029     return dexGetAnnotationSetItem(pDexFile, pItem->annotationsOff);
1030 }
1031 
1032 /* return the Nth annotation offset from a DexAnnotationSetItem */
dexGetAnnotationOff(const DexAnnotationSetItem * pAnnoSet,u4 idx)1033 DEX_INLINE u4 dexGetAnnotationOff(
1034     const DexAnnotationSetItem* pAnnoSet, u4 idx)
1035 {
1036     assert(idx < pAnnoSet->size);
1037     return pAnnoSet->entries[idx];
1038 }
1039 
1040 /* return the Nth annotation item from a DexAnnotationSetItem */
dexGetAnnotationItem(const DexFile * pDexFile,const DexAnnotationSetItem * pAnnoSet,u4 idx)1041 DEX_INLINE const DexAnnotationItem* dexGetAnnotationItem(
1042     const DexFile* pDexFile, const DexAnnotationSetItem* pAnnoSet, u4 idx)
1043 {
1044     u4 offset = dexGetAnnotationOff(pAnnoSet, idx);
1045     if (offset == 0) {
1046         return NULL;
1047     }
1048     return (const DexAnnotationItem*) (pDexFile->baseAddr + offset);
1049 }
1050 
1051 /*
1052  * Get the type descriptor character associated with a given primitive
1053  * type. This returns '\0' if the type is invalid.
1054  */
1055 char dexGetPrimitiveTypeDescriptorChar(PrimitiveType type);
1056 
1057 /*
1058  * Get the type descriptor string associated with a given primitive
1059  * type.
1060  */
1061 const char* dexGetPrimitiveTypeDescriptor(PrimitiveType type);
1062 
1063 /*
1064  * Get the boxed type descriptor string associated with a given
1065  * primitive type. This returns NULL for an invalid type, including
1066  * particularly for type "void". In the latter case, even though there
1067  * is a class Void, there's no such thing as a boxed instance of it.
1068  */
1069 const char* dexGetBoxedTypeDescriptor(PrimitiveType type);
1070 
1071 /*
1072  * Get the primitive type constant from the given descriptor character.
1073  * This returns PRIM_NOT (note: this is a 0) if the character is invalid
1074  * as a primitive type descriptor.
1075  */
1076 PrimitiveType dexGetPrimitiveTypeFromDescriptorChar(char descriptorChar);
1077 
1078 #endif  // LIBDEX_DEXFILE_H_
1079