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