blob: cf4013868ad0c2850a01c2afdb669ac5c103a0a2 [file] [log] [blame]
Shih-wei Liaocecdab22011-01-10 02:10:29 -08001===============================================================
2libbcc: A Versatile Bitcode Execution Engine for Mobile Devices
3===============================================================
Logan36fafd92011-01-08 22:55:19 +08004
5
6Introduction
7------------
8
Shih-wei Liao7fff2282011-01-09 13:57:01 -08009libbcc is an LLVM bitcode execution engine that compiles the bitcode
Shih-wei Liaocecdab22011-01-10 02:10:29 -080010to an in-memory executable. libbcc is versatile because:
11
Shih-wei Liaobe849442011-01-20 05:19:00 -080012* it implements both AOT (Ahead-of-Time) and JIT (Just-in-Time)
13 compilation.
Shih-wei Liaocecdab22011-01-10 02:10:29 -080014
Shih-wei Liaobe849442011-01-20 05:19:00 -080015* Android devices demand fast start-up time, small size, and high
16 performance *at the same time*. libbcc attempts to address these
17 design constraints.
18
19* it supports on-device linking. Each device vendor can supply his or
20 her own runtime bitcode library (lib*.bc) that differentiates his or
21 her system. Specialization becomes ecosystem-friendly.
Shih-wei Liao7fff2282011-01-09 13:57:01 -080022
23libbcc provides:
24
Shih-wei Liaobe849442011-01-20 05:19:00 -080025* a *just-in-time bitcode compiler*, which translates the LLVM bitcode
26 into machine code
Shih-wei Liao7fff2282011-01-09 13:57:01 -080027
28* a *caching mechanism*, which can:
29
Shih-wei Liaobe849442011-01-20 05:19:00 -080030 * after each compilation, serialize the in-memory executable into a
31 cache file. Note that the compilation is triggered by a cache
32 miss.
Shih-wei Liao7fff2282011-01-09 13:57:01 -080033 * load from the cache file upon cache-hit.
34
Shih-wei Liao0dc51b12011-01-10 03:41:58 -080035Highlights of libbcc are:
Logan36fafd92011-01-08 22:55:19 +080036
Shih-wei Liao7fff2282011-01-09 13:57:01 -080037* libbcc supports bitcode from various language frontends, such as
Shih-wei Liaobe849442011-01-20 05:19:00 -080038 RenderScript, GLSL (pixelflinger2).
Logan36fafd92011-01-08 22:55:19 +080039
40* libbcc strives to balance between library size, launch time and
41 steady-state performance:
42
Shih-wei Liaobe849442011-01-20 05:19:00 -080043 * The size of libbcc is aggressively reduced for mobile devices. We
44 customize and improve upon the default Execution Engine from
45 upstream. Otherwise, libbcc's execution engine can easily become
46 at least 2 times bigger.
Logan36fafd92011-01-08 22:55:19 +080047
Shih-wei Liaobe849442011-01-20 05:19:00 -080048 * To reduce launch time, we support caching of
49 binaries. Just-in-Time compilation are oftentimes Just-too-Late,
50 if the given apps are performance-sensitive. Thus, we implemented
51 AOT to get the best of both worlds: Fast launch time and high
52 steady-state performance.
53
54 AOT is also important for projects such as NDK on LLVM with
55 portability enhancement. Launch time reduction after we
56 implemented AOT is signficant::
57
58
59 Apps libbcc without AOT libbcc with AOT
60 launch time in libbcc launch time in libbcc
61 App_1 1218ms 9ms
62 App_2 842ms 4ms
63 Wallpaper:
64 MagicSmoke 182ms 3ms
65 Halo 127ms 3ms
66 Balls 149ms 3ms
67 SceneGraph 146ms 90ms
68 Model 104ms 4ms
69 Fountain 57ms 3ms
70
71 AOT also masks the launching time overhead of on-device linking
72 and helps it become reality.
Logan36fafd92011-01-08 22:55:19 +080073
74 * For steady-state performance, we enable VFP3 and aggressive
75 optimizations.
76
Shih-wei Liao0d4984b2011-01-09 04:39:00 -080077* Currently we disable Lazy JITting.
78
Logan36fafd92011-01-08 22:55:19 +080079
80
81API
82---
83
Shih-wei Liao7fff2282011-01-09 13:57:01 -080084**Basic:**
Logan36fafd92011-01-08 22:55:19 +080085
86* **bccCreateScript** - Create new bcc script
87
88* **bccRegisterSymbolCallback** - Register the callback function for external
89 symbol lookup
90
91* **bccReadBC** - Set the source bitcode for compilation
92
93* **bccReadModule** - Set the llvm::Module for compilation
94
95* **bccLinkBC** - Set the library bitcode for linking
96
Logan Chiend9db38a2011-07-11 17:22:35 +080097* **bccPrepareExecutable** - *deprecated* - Use bccPrepareExecutableEx instead
98
99* **bccPrepareExecutableEx** - Create the in-memory executable by either
Logan36fafd92011-01-08 22:55:19 +0800100 just-in-time compilation or cache loading
101
Loganf340bf72011-01-14 17:51:40 +0800102* **bccGetFuncAddr** - Get the entry address of the function
Logan36fafd92011-01-08 22:55:19 +0800103
Loganf340bf72011-01-14 17:51:40 +0800104* **bccDisposeScript** - Destroy bcc script and release the resources
Logan36fafd92011-01-08 22:55:19 +0800105
Loganf340bf72011-01-14 17:51:40 +0800106* **bccGetError** - *deprecated* - Don't use this
Logan36fafd92011-01-08 22:55:19 +0800107
108
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800109**Reflection:**
Logan36fafd92011-01-08 22:55:19 +0800110
Loganf340bf72011-01-14 17:51:40 +0800111* **bccGetExportVarCount** - Get the count of exported variables
Logan36fafd92011-01-08 22:55:19 +0800112
Loganf340bf72011-01-14 17:51:40 +0800113* **bccGetExportVarList** - Get the addresses of exported variables
Logan36fafd92011-01-08 22:55:19 +0800114
Loganf340bf72011-01-14 17:51:40 +0800115* **bccGetExportFuncCount** - Get the count of exported functions
116
117* **bccGetExportFuncList** - Get the addresses of exported functions
118
119* **bccGetPragmaCount** - Get the count of pragmas
120
121* **bccGetPragmaList** - Get the pragmas
Logan36fafd92011-01-08 22:55:19 +0800122
123
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800124**Debug:**
Logan36fafd92011-01-08 22:55:19 +0800125
Loganf340bf72011-01-14 17:51:40 +0800126* **bccGetFuncCount** - Get the count of functions (including non-exported)
Logan36fafd92011-01-08 22:55:19 +0800127
Loganf340bf72011-01-14 17:51:40 +0800128* **bccGetFuncInfoList** - Get the function information (name, base, size)
Logan36fafd92011-01-08 22:55:19 +0800129
130
131
132Cache File Format
133-----------------
134
Shih-wei Liao0d4984b2011-01-09 04:39:00 -0800135A cache file (denoted as \*.oBCC) for libbcc consists of several sections:
Logan36fafd92011-01-08 22:55:19 +0800136header, string pool, dependencies table, relocation table, exported
137variable list, exported function list, pragma list, function information
138table, and bcc context. Every section should be aligned to a word size.
Shih-wei Liao0d4984b2011-01-09 04:39:00 -0800139Here is the brief description of each sections:
Logan36fafd92011-01-08 22:55:19 +0800140
Shih-wei Liao0d4984b2011-01-09 04:39:00 -0800141* **Header** (OBCC_Header) - The header of a cache file. It contains the
Shih-wei Liaocecdab22011-01-10 02:10:29 -0800142 magic word, version, machine integer type information (the endianness,
143 the size of off_t, size_t, and ptr_t), and the size
144 and offset of other sections. The header section is guaranteed
Logan36fafd92011-01-08 22:55:19 +0800145 to be at the beginning of the cache file.
146
Shih-wei Liao0d4984b2011-01-09 04:39:00 -0800147* **String Pool** (OBCC_StringPool) - A collection of serialized variable
Logan36fafd92011-01-08 22:55:19 +0800148 length strings. The strp_index in the other part of the cache file
149 represents the index of such string in this string pool.
150
151* **Dependencies Table** (OBCC_DependencyTable) - The dependencies table.
Shih-wei Liao8538dfa2011-01-09 15:42:28 -0800152 This table stores the resource name (or file path), the resource
Logan36fafd92011-01-08 22:55:19 +0800153 type (rather in APK or on the file system), and the SHA1 checksum.
154
Shih-wei Liao0d4984b2011-01-09 04:39:00 -0800155* **Relocation Table** (OBCC_RelocationTable) - *not enabled*
Logan36fafd92011-01-08 22:55:19 +0800156
Shih-wei Liaoac4e4582011-01-10 02:59:54 -0800157* **Exported Variable List** (OBCC_ExportVarList) -
158 The list of the addresses of exported variables.
159
160* **Exported Function List** (OBCC_ExportFuncList) -
161 The list of the addresses of exported functions.
Logan36fafd92011-01-08 22:55:19 +0800162
163* **Pragma List** (OBCC_PragmaList) - The list of pragma key-value pair.
164
165* **Function Information Table** (OBCC_FuncTable) - This is a table of
166 function information, such as function name, function entry address,
167 and function binary size. Besides, the table should be ordered by
168 function name.
169
170* **Context** - The context of the in-memory executable, including
171 the code and the data. The offset of context should aligned to
Shih-wei Liao0dc51b12011-01-10 03:41:58 -0800172 a page size, so that we can mmap the context directly into memory.
Logan36fafd92011-01-08 22:55:19 +0800173
174For furthur information, you may read `bcc_cache.h <include/bcc/bcc_cache.h>`_,
175`CacheReader.cpp <lib/bcc/CacheReader.cpp>`_, and
176`CacheWriter.cpp <lib/bcc/CacheWriter.cpp>`_ for details.
177
178
179
180JIT'ed Code Calling Conventions
181-------------------------------
182
1831. Calls from Execution Environment or from/to within script:
184
185 On ARM, the first 4 arguments will go into r0, r1, r2, and r3, in that order.
186 The remaining (if any) will go through stack.
187
188 For ext_vec_types such as float2, a set of registers will be used. In the case
189 of float2, a register pair will be used. Specifically, if float2 is the first
190 argument in the function prototype, float2.x will go into r0, and float2.y,
191 r1.
192
193 Note: stack will be aligned to the coarsest-grained argument. In the case of
194 float2 above as an argument, parameter stack will be aligned to an 8-byte
195 boundary (if the sizes of other arguments are no greater than 8.)
196
1972. Calls from/to a separate compilation unit: (E.g., calls to Execution
198 Environment if those runtime library callees are not compiled using LLVM.)
199
200 On ARM, we use hardfp. Note that double will be placed in a register pair.