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