summaryrefslogtreecommitdiffstats
path: root/README.rst
blob: a6db1f1d7c5f57e3ad8a72bcec50ff6e341e8bfa (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
===============================================================
libbcc: A Versatile Bitcode Execution Engine for Mobile Devices
===============================================================


Introduction
------------

libbcc is an LLVM bitcode execution engine that compiles the bitcode
to an in-memory executable. libbcc is versatile because:

* it implements both AOT (Ahead-of-Time) and JIT (Just-in-Time)
  compilation.

* Android devices demand fast start-up time, small size, and high
  performance *at the same time*. libbcc attempts to address these
  design constraints.

* it supports on-device linking. Each device vendor can supply his or
  her own runtime bitcode library (lib*.bc) that differentiates his or
  her system. Specialization becomes ecosystem-friendly.

libbcc provides:

* a *just-in-time bitcode compiler*, which translates the LLVM bitcode
  into machine code

* a *caching mechanism*, which can:

  * after each compilation, serialize the in-memory executable into a
    cache file.  Note that the compilation is triggered by a cache
    miss.
  * load from the cache file upon cache-hit.

Highlights of libbcc are:

* libbcc supports bitcode from various language frontends, such as
  Renderscript, GLSL (pixelflinger2).

* libbcc strives to balance between library size, launch time and
  steady-state performance:

  * The size of libbcc is aggressively reduced for mobile devices. We
    customize and improve upon the default Execution Engine from
    upstream. Otherwise, libbcc's execution engine can easily become
    at least 2 times bigger.

  * To reduce launch time, we support caching of
    binaries. Just-in-Time compilation are oftentimes Just-too-Late,
    if the given apps are performance-sensitive. Thus, we implemented
    AOT to get the best of both worlds: Fast launch time and high
    steady-state performance.

    AOT is also important for projects such as NDK on LLVM with
    portability enhancement. Launch time reduction after we
    implemented AOT is signficant::


     Apps          libbcc without AOT       libbcc with AOT
                   launch time in libbcc    launch time in libbcc
     App_1            1218ms                   9ms
     App_2            842ms                    4ms
     Wallpaper:
       MagicSmoke     182ms                    3ms
       Halo           127ms                    3ms
     Balls            149ms                    3ms
     SceneGraph       146ms                    90ms
     Model            104ms                    4ms
     Fountain         57ms                     3ms

    AOT also masks the launching time overhead of on-device linking
    and helps it become reality.

  * For steady-state performance, we enable VFP3 and aggressive
    optimizations.

* Currently we disable Lazy JITting.



API
---

**Basic:**

* **bccCreateScript** - Create new bcc script

* **bccRegisterSymbolCallback** - Register the callback function for external
  symbol lookup

* **bccReadBC** - Set the source bitcode for compilation

* **bccReadModule** - Set the llvm::Module for compilation

* **bccLinkBC** - Set the library bitcode for linking

* **bccPrepareExecutable** - *deprecated* - Use bccPrepareExecutableEx instead

* **bccPrepareExecutableEx** - Create the in-memory executable by either
  just-in-time compilation or cache loading

* **bccGetFuncAddr** - Get the entry address of the function

* **bccDisposeScript** - Destroy bcc script and release the resources

* **bccGetError** - *deprecated* - Don't use this


**Reflection:**

* **bccGetExportVarCount** - Get the count of exported variables

* **bccGetExportVarList** - Get the addresses of exported variables

* **bccGetExportFuncCount** - Get the count of exported functions

* **bccGetExportFuncList** - Get the addresses of exported functions

* **bccGetPragmaCount** - Get the count of pragmas

* **bccGetPragmaList** - Get the pragmas


**Debug:**

* **bccGetFuncCount** - Get the count of functions (including non-exported)

* **bccGetFuncInfoList** - Get the function information (name, base, size)



Cache File Format
-----------------

A cache file (denoted as \*.oBCC) for libbcc consists of several sections:
header, string pool, dependencies table, relocation table, exported
variable list, exported function list, pragma list, function information
table, and bcc context.  Every section should be aligned to a word size.
Here is the brief description of each sections:

* **Header** (MCO_Header) - The header of a cache file. It contains the
  magic word, version, machine integer type information (the endianness,
  the size of off_t, size_t, and ptr_t), and the size
  and offset of other sections.  The header section is guaranteed
  to be at the beginning of the cache file.

* **String Pool** (MCO_StringPool) - A collection of serialized variable
  length strings.  The strp_index in the other part of the cache file
  represents the index of such string in this string pool.

* **Dependencies Table** (MCO_DependencyTable) - The dependencies table.
  This table stores the resource name (or file path), the resource
  type (rather in APK or on the file system), and the SHA1 checksum.

* **Relocation Table** (MCO_RelocationTable) - *not enabled*

* **Exported Variable List** (MCO_ExportVarList) -
  The list of the addresses of exported variables.

* **Exported Function List** (MCO_ExportFuncList) -
  The list of the addresses of exported functions.

* **Pragma List** (MCO_PragmaList) - The list of pragma key-value pair.

* **Function Information Table** (MCO_FuncTable) - This is a table of
  function information, such as function name, function entry address,
  and function binary size.  Besides, the table should be ordered by
  function name.

* **Context** - The context of the in-memory executable, including
  the code and the data.  The offset of context should aligned to
  a page size, so that we can mmap the context directly into memory.

For furthur information, you may read `bcc_cache.h <include/bcc/bcc_cache.h>`_,
`CacheReader.cpp <lib/bcc/CacheReader.cpp>`_, and
`CacheWriter.cpp <lib/bcc/CacheWriter.cpp>`_ for details.



JIT'ed Code Calling Conventions
-------------------------------

1. Calls from Execution Environment or from/to within script:

   On ARM, the first 4 arguments will go into r0, r1, r2, and r3, in that order.
   The remaining (if any) will go through stack.

   For ext_vec_types such as float2, a set of registers will be used. In the case
   of float2, a register pair will be used. Specifically, if float2 is the first
   argument in the function prototype, float2.x will go into r0, and float2.y,
   r1.

   Note: stack will be aligned to the coarsest-grained argument. In the case of
   float2 above as an argument, parameter stack will be aligned to an 8-byte
   boundary (if the sizes of other arguments are no greater than 8.)

2. Calls from/to a separate compilation unit: (E.g., calls to Execution
   Environment if those runtime library callees are not compiled using LLVM.)

   On ARM, we use hardfp.  Note that double will be placed in a register pair.