DexPrepare.h revision d862faa2ceae186da5518607505eb942d634ced9 
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 * DEX preparation declarations.
19 */
20#ifndef _DALVIK_DEXPREPARE
21#define _DALVIK_DEXPREPARE
22
23/*
24 * Global DEX optimizer control.  Determines the circumstances in which we
25 * try to rewrite instructions in the DEX file.
26 *
27 * Optimizing is performed ahead-of-time by dexopt and, in some cases, at
28 * load time by the VM.
29 */
30enum DexOptimizerMode {
31    OPTIMIZE_MODE_UNKNOWN = 0,
32    OPTIMIZE_MODE_NONE,         /* never optimize (except "essential") */
33    OPTIMIZE_MODE_VERIFIED,     /* only optimize verified classes (default) */
34    OPTIMIZE_MODE_ALL,          /* optimize verified & unverified (risky) */
35    OPTIMIZE_MODE_FULL          /* fully opt verified classes at load time */
36};
37
38/* some additional bit flags for dexopt */
39enum DexoptFlags {
40    DEXOPT_OPT_ENABLED       = 1,       /* optimizations enabled? */
41    DEXOPT_OPT_ALL           = 1 << 1,  /* optimize when verify fails? */
42    DEXOPT_VERIFY_ENABLED    = 1 << 2,  /* verification enabled? */
43    DEXOPT_VERIFY_ALL        = 1 << 3,  /* verify bootstrap classes? */
44    DEXOPT_IS_BOOTSTRAP      = 1 << 4,  /* is dex in bootstrap class path? */
45    DEXOPT_GEN_REGISTER_MAPS = 1 << 5,  /* generate register maps during vfy */
46    DEXOPT_UNIPROCESSOR      = 1 << 6,  /* specify uniprocessor target */
47    DEXOPT_SMP               = 1 << 7   /* specify SMP target */
48};
49
50/*
51 * An enumeration of problems that can turn up during verification.
52 */
53enum VerifyError {
54    VERIFY_ERROR_NONE = 0,      /* no error; must be zero */
55    VERIFY_ERROR_GENERIC,       /* VerifyError */
56
57    VERIFY_ERROR_NO_CLASS,      /* NoClassDefFoundError */
58    VERIFY_ERROR_NO_FIELD,      /* NoSuchFieldError */
59    VERIFY_ERROR_NO_METHOD,     /* NoSuchMethodError */
60    VERIFY_ERROR_ACCESS_CLASS,  /* IllegalAccessError */
61    VERIFY_ERROR_ACCESS_FIELD,  /* IllegalAccessError */
62    VERIFY_ERROR_ACCESS_METHOD, /* IllegalAccessError */
63    VERIFY_ERROR_CLASS_CHANGE,  /* IncompatibleClassChangeError */
64    VERIFY_ERROR_INSTANTIATION, /* InstantiationError */
65};
66
67/*
68 * Identifies the type of reference in the instruction that generated the
69 * verify error (e.g. VERIFY_ERROR_ACCESS_CLASS could come from a method,
70 * field, or class reference).
71 *
72 * This must fit in two bits.
73 */
74enum VerifyErrorRefType {
75    VERIFY_ERROR_REF_CLASS  = 0,
76    VERIFY_ERROR_REF_FIELD  = 1,
77    VERIFY_ERROR_REF_METHOD = 2,
78};
79
80#define kVerifyErrorRefTypeShift 6
81
82#define VERIFY_OK(_failure) ((_failure) == VERIFY_ERROR_NONE)
83
84/*
85 * Given the full path to a DEX or Jar file, and (if appropriate) the name
86 * within the Jar, open the optimized version from the cache.
87 *
88 * If "*pNewFile" is set, a new file has been created with only a stub
89 * "opt" header, and the caller is expected to fill in the blanks.
90 *
91 * Returns the file descriptor, locked and seeked past the "opt" header.
92 */
93int dvmOpenCachedDexFile(const char* fileName, const char* cachedFile,
94    u4 modWhen, u4 crc, bool isBootstrap, bool* pNewFile, bool createIfMissing);
95
96/*
97 * Unlock the specified file descriptor.  Use in conjunction with
98 * dvmOpenCachedDexFile().
99 *
100 * Returns true on success.
101 */
102bool dvmUnlockCachedDexFile(int fd);
103
104/*
105 * Verify the contents of the "opt" header, and check the DEX file's
106 * dependencies on its source zip (if available).
107 */
108bool dvmCheckOptHeaderAndDependencies(int fd, bool sourceAvail, u4 modWhen,
109    u4 crc, bool expectVerify, bool expectOpt);
110
111/*
112 * Optimize a DEX file.  The file must start with the "opt" header, followed
113 * by the plain DEX data.  It must be mmap()able.
114 *
115 * "fileName" is only used for debug output.
116 */
117bool dvmOptimizeDexFile(int fd, off_t dexOffset, long dexLen,
118    const char* fileName, u4 modWhen, u4 crc, bool isBootstrap);
119
120/*
121 * Continue the optimization process on the other side of a fork/exec.
122 */
123bool dvmContinueOptimization(int fd, off_t dexOffset, long dexLength,
124    const char* fileName, u4 modWhen, u4 crc, bool isBootstrap);
125
126/*
127 * Prepare DEX data that is only available to the VM as in-memory data.
128 */
129bool dvmPrepareDexInMemory(u1* addr, size_t len, DvmDex** ppDvmDex);
130
131/*
132 * Prep data structures.
133 */
134bool dvmCreateInlineSubsTable(void);
135void dvmFreeInlineSubsTable(void);
136
137#endif /*_DALVIK_DEXPREPARE*/
138