summaryrefslogtreecommitdiffstats
path: root/README.html
blob: c4b965365356bec1615e6ae6ba121158daad6022 (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
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>libbcc: A Versatile Bitcode Execution Engine for Mobile Devices</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left{
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: left }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="libbcc-a-versatile-bitcode-execution-engine-for-mobile-devices">
<h1 class="title">libbcc: A Versatile Bitcode Execution Engine for Mobile Devices</h1>

<div class="section" id="introduction">
<h1>Introduction</h1>
<p>libbcc is an LLVM bitcode execution engine that compiles the bitcode
to an in-memory executable. libbcc is versatile because:</p>
<ul class="simple">
<li>it implements both AOT (Ahead-of-Time) and JIT (Just-in-Time)
compilation.</li>
<li>Android devices demand fast start-up time, small size, and high
performance <em>at the same time</em>. libbcc attempts to address these
design constraints.</li>
<li>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.</li>
</ul>
<p>libbcc provides:</p>
<ul class="simple">
<li>a <em>just-in-time bitcode compiler</em>, which translates the LLVM bitcode
into machine code</li>
<li>a <em>caching mechanism</em>, which can:<ul>
<li>after each compilation, serialize the in-memory executable into a
cache file.  Note that the compilation is triggered by a cache
miss.</li>
<li>load from the cache file upon cache-hit.</li>
</ul>
</li>
</ul>
<p>Highlights of libbcc are:</p>
<ul>
<li><p class="first">libbcc supports bitcode from various language frontends, such as
Renderscript, GLSL (pixelflinger2).</p>
</li>
<li><p class="first">libbcc strives to balance between library size, launch time and
steady-state performance:</p>
<ul>
<li><p class="first">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.</p>
</li>
<li><p class="first">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.</p>
<p>AOT is also important for projects such as NDK on LLVM with
portability enhancement. Launch time reduction after we
implemented AOT is signficant:</p>
<pre class="literal-block">
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
</pre>
<p>AOT also masks the launching time overhead of on-device linking
and helps it become reality.</p>
</li>
<li><p class="first">For steady-state performance, we enable VFP3 and aggressive
optimizations.</p>
</li>
</ul>
</li>
<li><p class="first">Currently we disable Lazy JITting.</p>
</li>
</ul>
</div>
<div class="section" id="api">
<h1>API</h1>
<p><strong>Basic:</strong></p>
<ul class="simple">
<li><strong>bccCreateScript</strong> - Create new bcc script</li>
<li><strong>bccRegisterSymbolCallback</strong> - Register the callback function for external
symbol lookup</li>
<li><strong>bccReadBC</strong> - Set the source bitcode for compilation</li>
<li><strong>bccReadModule</strong> - Set the llvm::Module for compilation</li>
<li><strong>bccLinkBC</strong> - Set the library bitcode for linking</li>
<li><strong>bccPrepareExecutable</strong> - <em>deprecated</em> - Use bccPrepareExecutableEx instead</li>
<li><strong>bccPrepareExecutableEx</strong> - Create the in-memory executable by either
just-in-time compilation or cache loading</li>
<li><strong>bccGetFuncAddr</strong> - Get the entry address of the function</li>
<li><strong>bccDisposeScript</strong> - Destroy bcc script and release the resources</li>
<li><strong>bccGetError</strong> - <em>deprecated</em> - Don't use this</li>
</ul>
<p><strong>Reflection:</strong></p>
<ul class="simple">
<li><strong>bccGetExportVarCount</strong> - Get the count of exported variables</li>
<li><strong>bccGetExportVarList</strong> - Get the addresses of exported variables</li>
<li><strong>bccGetExportFuncCount</strong> - Get the count of exported functions</li>
<li><strong>bccGetExportFuncList</strong> - Get the addresses of exported functions</li>
<li><strong>bccGetPragmaCount</strong> - Get the count of pragmas</li>
<li><strong>bccGetPragmaList</strong> - Get the pragmas</li>
</ul>
<p><strong>Debug:</strong></p>
<ul class="simple">
<li><strong>bccGetFuncCount</strong> - Get the count of functions (including non-exported)</li>
<li><strong>bccGetFuncInfoList</strong> - Get the function information (name, base, size)</li>
</ul>
</div>
<div class="section" id="cache-file-format">
<h1>Cache File Format</h1>
<p>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:</p>
<ul class="simple">
<li><strong>Header</strong> (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.</li>
<li><strong>String Pool</strong> (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.</li>
<li><strong>Dependencies Table</strong> (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.</li>
<li><strong>Relocation Table</strong> (MCO_RelocationTable) - <em>not enabled</em></li>
<li><strong>Exported Variable List</strong> (MCO_ExportVarList) -
The list of the addresses of exported variables.</li>
<li><strong>Exported Function List</strong> (MCO_ExportFuncList) -
The list of the addresses of exported functions.</li>
<li><strong>Pragma List</strong> (MCO_PragmaList) - The list of pragma key-value pair.</li>
<li><strong>Function Information Table</strong> (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.</li>
<li><strong>Context</strong> - 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.</li>
</ul>
<p>For furthur information, you may read <a class="reference external" href="include/bcc/bcc_cache.h">bcc_cache.h</a>,
<a class="reference external" href="lib/bcc/CacheReader.cpp">CacheReader.cpp</a>, and
<a class="reference external" href="lib/bcc/CacheWriter.cpp">CacheWriter.cpp</a> for details.</p>
</div>
<div class="section" id="jit-ed-code-calling-conventions">
<h1>JIT'ed Code Calling Conventions</h1>
<ol class="arabic">
<li><p class="first">Calls from Execution Environment or from/to within script:</p>
<p>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.</p>
<p>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.</p>
<p>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.)</p>
</li>
<li><p class="first">Calls from/to a separate compilation unit: (E.g., calls to Execution
Environment if those runtime library callees are not compiled using LLVM.)</p>
<p>On ARM, we use hardfp.  Note that double will be placed in a register pair.</p>
</li>
</ol>
</div>
</div>
</body>
</html>