README.rst revision 0dc51b1873ba340722f483eb2a639922360fbaf9 
1===============================================================
2libbcc: A Versatile Bitcode Execution Engine for Mobile Devices
3===============================================================
4
5
6Introduction
7------------
8
9libbcc is an LLVM bitcode execution engine that compiles the bitcode
10to an in-memory executable. libbcc is versatile because:
11
12* it implements both AOT (Ahead-of-Time) and JIT (Just-in-Time) compilation.
13
14* Android devices demand fast start-up time, small size, and high performance
15  *at the same time*. libbcc attemps to address these design constraints.
16
17libbcc provides:
18
19* a *just-in-time bitcode compiler*, which translates the bitcode into
20  machine code
21
22* a *caching mechanism*, which can:
23
24  * after each compilation, serialize the in-memory executable into a cache file.
25    Note that the compilation is triggered by a cache miss.
26  * load from the cache file upon cache-hit.
27
28Highlights of libbcc are:
29
30* libbcc supports bitcode from various language frontends, such as
31  RenderScript, GLSL.
32
33* libbcc strives to balance between library size, launch time and
34  steady-state performance:
35
36  * The size of libbcc is aggressively reduced for mobile devices.
37    We customize and we don't use the default Execution Engine from upstream.
38
39  * To reduce launch time, we support caching of binaries.
40
41  * For steady-state performance, we enable VFP3 and aggressive
42    optimizations.
43
44* Currently we disable Lazy JITting.
45
46
47
48API
49---
50
51**Basic:**
52
53* **bccCreateScript** - Create new bcc script
54
55* **bccRegisterSymbolCallback** - Register the callback function for external
56  symbol lookup
57
58* **bccReadBC** - Set the source bitcode for compilation
59
60* **bccReadModule** - Set the llvm::Module for compilation
61
62* **bccLinkBC** - Set the library bitcode for linking
63
64* **bccPrepareExecutable** - Create the in-memory executable by either
65  just-in-time compilation or cache loading
66
67* **bccDeleteScript** - Destroy bcc script and release the resources
68
69* **bccGetError** - Get the error code
70
71* **bccGetScriptInfoLog** - *deprecated* - Don't use this
72
73
74**Reflection:**
75
76* **bccGetExportVars** - Get the addresses of exported variables
77
78* **bccGetExportFuncs** - Get the addresses of exported functions
79
80* **bccGetPragmas** - Get the pragmas
81
82
83**Debug:**
84
85* **bccGetFunctions** - Get the function name list
86
87* **bccGetFunctionBinary** - Get the address and the size of a function binary
88
89
90
91Cache File Format
92-----------------
93
94A cache file (denoted as \*.oBCC) for libbcc consists of several sections:
95header, string pool, dependencies table, relocation table, exported
96variable list, exported function list, pragma list, function information
97table, and bcc context.  Every section should be aligned to a word size.
98Here is the brief description of each sections:
99
100* **Header** (OBCC_Header) - The header of a cache file. It contains the
101  magic word, version, machine integer type information (the endianness,
102  the size of off_t, size_t, and ptr_t), and the size
103  and offset of other sections.  The header section is guaranteed
104  to be at the beginning of the cache file.
105
106* **String Pool** (OBCC_StringPool) - A collection of serialized variable
107  length strings.  The strp_index in the other part of the cache file
108  represents the index of such string in this string pool.
109
110* **Dependencies Table** (OBCC_DependencyTable) - The dependencies table.
111  This table stores the resource name (or file path), the resource
112  type (rather in APK or on the file system), and the SHA1 checksum.
113
114* **Relocation Table** (OBCC_RelocationTable) - *not enabled*
115
116* **Exported Variable List** (OBCC_ExportVarList) -
117  The list of the addresses of exported variables.
118
119* **Exported Function List** (OBCC_ExportFuncList) -
120  The list of the addresses of exported functions.
121
122* **Pragma List** (OBCC_PragmaList) - The list of pragma key-value pair.
123
124* **Function Information Table** (OBCC_FuncTable) - This is a table of
125  function information, such as function name, function entry address,
126  and function binary size.  Besides, the table should be ordered by
127  function name.
128
129* **Context** - The context of the in-memory executable, including
130  the code and the data.  The offset of context should aligned to
131  a page size, so that we can mmap the context directly into memory.
132
133For furthur information, you may read `bcc_cache.h <include/bcc/bcc_cache.h>`_,
134`CacheReader.cpp <lib/bcc/CacheReader.cpp>`_, and
135`CacheWriter.cpp <lib/bcc/CacheWriter.cpp>`_ for details.
136
137
138
139JIT'ed Code Calling Conventions
140-------------------------------
141
1421. Calls from Execution Environment or from/to within script:
143
144   On ARM, the first 4 arguments will go into r0, r1, r2, and r3, in that order.
145   The remaining (if any) will go through stack.
146
147   For ext_vec_types such as float2, a set of registers will be used. In the case
148   of float2, a register pair will be used. Specifically, if float2 is the first
149   argument in the function prototype, float2.x will go into r0, and float2.y,
150   r1.
151
152   Note: stack will be aligned to the coarsest-grained argument. In the case of
153   float2 above as an argument, parameter stack will be aligned to an 8-byte
154   boundary (if the sizes of other arguments are no greater than 8.)
155
1562. Calls from/to a separate compilation unit: (E.g., calls to Execution
157   Environment if those runtime library callees are not compiled using LLVM.)
158
159   On ARM, we use hardfp.  Note that double will be placed in a register pair.
160