Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / frameworks / compile / libbcc / 8538dfa267837f95d83a0828e5c56a14d708b7b6 / . / README.html
blob: 8c11bcfd0d3ca794b785c607c4505f8e9ba9946a [file] [log] [blame]
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]1<?xml version="1.0" encoding="utf-8" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
7<title>libbcc: A Versatile Bitcode Execution Engine</title>
8<style type="text/css">
9
10/*
11:Author: David Goodger (goodger@python.org)
12:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $
13:Copyright: This stylesheet has been placed in the public domain.
14
15Default cascading style sheet for the HTML output of Docutils.
16
17See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
18customize this style sheet.
19*/
20
21/* used to remove borders from tables and images */
22.borderless, table.borderless td, table.borderless th {
23 border: 0 }
24
25table.borderless td, table.borderless th {
26 /* Override padding for "table.docutils td" with "! important".
27 The right padding separates the table cells. */
28 padding: 0 0.5em 0 0 ! important }
29
30.first {
31 /* Override more specific margin styles with "! important". */
32 margin-top: 0 ! important }
33
34.last, .with-subtitle {
35 margin-bottom: 0 ! important }
36
37.hidden {
38 display: none }
39
40a.toc-backref {
41 text-decoration: none ;
42 color: black }
43
44blockquote.epigraph {
45 margin: 2em 5em ; }
46
47dl.docutils dd {
48 margin-bottom: 0.5em }
49
50/* Uncomment (and remove this text!) to get bold-faced definition list terms
51dl.docutils dt {
52 font-weight: bold }
53*/
54
55div.abstract {
56 margin: 2em 5em }
57
58div.abstract p.topic-title {
59 font-weight: bold ;
60 text-align: center }
61
62div.admonition, div.attention, div.caution, div.danger, div.error,
63div.hint, div.important, div.note, div.tip, div.warning {
64 margin: 2em ;
65 border: medium outset ;
66 padding: 1em }
67
68div.admonition p.admonition-title, div.hint p.admonition-title,
69div.important p.admonition-title, div.note p.admonition-title,
70div.tip p.admonition-title {
71 font-weight: bold ;
72 font-family: sans-serif }
73
74div.attention p.admonition-title, div.caution p.admonition-title,
75div.danger p.admonition-title, div.error p.admonition-title,
76div.warning p.admonition-title {
77 color: red ;
78 font-weight: bold ;
79 font-family: sans-serif }
80
81/* Uncomment (and remove this text!) to get reduced vertical space in
82 compound paragraphs.
83div.compound .compound-first, div.compound .compound-middle {
84 margin-bottom: 0.5em }
85
86div.compound .compound-last, div.compound .compound-middle {
87 margin-top: 0.5em }
88*/
89
90div.dedication {
91 margin: 2em 5em ;
92 text-align: center ;
93 font-style: italic }
94
95div.dedication p.topic-title {
96 font-weight: bold ;
97 font-style: normal }
98
99div.figure {
100 margin-left: 2em ;
101 margin-right: 2em }
102
103div.footer, div.header {
104 clear: both;
105 font-size: smaller }
106
107div.line-block {
108 display: block ;
109 margin-top: 1em ;
110 margin-bottom: 1em }
111
112div.line-block div.line-block {
113 margin-top: 0 ;
114 margin-bottom: 0 ;
115 margin-left: 1.5em }
116
117div.sidebar {
118 margin: 0 0 0.5em 1em ;
119 border: medium outset ;
120 padding: 1em ;
121 background-color: #ffffee ;
122 width: 40% ;
123 float: right ;
124 clear: right }
125
126div.sidebar p.rubric {
127 font-family: sans-serif ;
128 font-size: medium }
129
130div.system-messages {
131 margin: 5em }
132
133div.system-messages h1 {
134 color: red }
135
136div.system-message {
137 border: medium outset ;
138 padding: 1em }
139
140div.system-message p.system-message-title {
141 color: red ;
142 font-weight: bold }
143
144div.topic {
145 margin: 2em }
146
147h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
148h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
149 margin-top: 0.4em }
150
151h1.title {
152 text-align: center }
153
154h2.subtitle {
155 text-align: center }
156
157hr.docutils {
158 width: 75% }
159
160img.align-left, .figure.align-left{
161 clear: left ;
162 float: left ;
163 margin-right: 1em }
164
165img.align-right, .figure.align-right {
166 clear: right ;
167 float: right ;
168 margin-left: 1em }
169
170.align-left {
171 text-align: left }
172
173.align-center {
174 clear: both ;
175 text-align: center }
176
177.align-right {
178 text-align: right }
179
180/* reset inner alignment in figures */
181div.align-right {
182 text-align: left }
183
184/* div.align-center * { */
185/* text-align: left } */
186
187ol.simple, ul.simple {
188 margin-bottom: 1em }
189
190ol.arabic {
191 list-style: decimal }
192
193ol.loweralpha {
194 list-style: lower-alpha }
195
196ol.upperalpha {
197 list-style: upper-alpha }
198
199ol.lowerroman {
200 list-style: lower-roman }
201
202ol.upperroman {
203 list-style: upper-roman }
204
205p.attribution {
206 text-align: right ;
207 margin-left: 50% }
208
209p.caption {
210 font-style: italic }
211
212p.credits {
213 font-style: italic ;
214 font-size: smaller }
215
216p.label {
217 white-space: nowrap }
218
219p.rubric {
220 font-weight: bold ;
221 font-size: larger ;
222 color: maroon ;
223 text-align: center }
224
225p.sidebar-title {
226 font-family: sans-serif ;
227 font-weight: bold ;
228 font-size: larger }
229
230p.sidebar-subtitle {
231 font-family: sans-serif ;
232 font-weight: bold }
233
234p.topic-title {
235 font-weight: bold }
236
237pre.address {
238 margin-bottom: 0 ;
239 margin-top: 0 ;
240 font: inherit }
241
242pre.literal-block, pre.doctest-block {
243 margin-left: 2em ;
244 margin-right: 2em }
245
246span.classifier {
247 font-family: sans-serif ;
248 font-style: oblique }
249
250span.classifier-delimiter {
251 font-family: sans-serif ;
252 font-weight: bold }
253
254span.interpreted {
255 font-family: sans-serif }
256
257span.option {
258 white-space: nowrap }
259
260span.pre {
261 white-space: pre }
262
263span.problematic {
264 color: red }
265
266span.section-subtitle {
267 /* font-size relative to parent (h1..h6 element) */
268 font-size: 80% }
269
270table.citation {
271 border-left: solid 1px gray;
272 margin-left: 1px }
273
274table.docinfo {
275 margin: 2em 4em }
276
277table.docutils {
278 margin-top: 0.5em ;
279 margin-bottom: 0.5em }
280
281table.footnote {
282 border-left: solid 1px black;
283 margin-left: 1px }
284
285table.docutils td, table.docutils th,
286table.docinfo td, table.docinfo th {
287 padding-left: 0.5em ;
288 padding-right: 0.5em ;
289 vertical-align: top }
290
291table.docutils th.field-name, table.docinfo th.docinfo-name {
292 font-weight: bold ;
293 text-align: left ;
294 white-space: nowrap ;
295 padding-left: 0 }
296
297h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
298h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
299 font-size: 100% }
300
301ul.auto-toc {
302 list-style-type: none }
303
304</style>
305</head>
306<body>
307<div class="document" id="libbcc-a-versatile-bitcode-execution-engine">
308<h1 class="title">libbcc: A Versatile Bitcode Execution Engine</h1>
309
310<div class="section" id="introduction">
311<h1>Introduction</h1>
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800[diff] [blame]312<p>libbcc is an LLVM bitcode execution engine that compiles the bitcode
313to an in-memory executable.</p>
314<p>libbcc provides:</p>
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]315<ul class="simple">
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800[diff] [blame]316<li>a <em>just-in-time (JIT) bitcode compiler</em>, which translates the bitcode into
317machine code</li>
318<li>a <em>caching mechanism</em>, which can:<ul>
319<li>after the compilation, serialize the in-memory executable into a cache file.
320Note that the compilation is triggered by a cache miss.</li>
321<li>load from the cache file upon cache-hit.</li>
322</ul>
323</li>
324</ul>
325<p>Here are some highlights of libbcc:</p>
326<ul class="simple">
327<li>libbcc supports bitcode from various language frontends, such as
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]328RenderScript, GLSL.</li>
329<li>libbcc strives to balance between library size, launch time and
330steady-state performance:<ul>
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800[diff] [blame]331<li>The size of libbcc is aggressively reduced for mobile devices.
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]332We customize and we don't use Execution Engine.</li>
333<li>To reduce launch time, we support caching of binaries.</li>
334<li>For steady-state performance, we enable VFP3 and aggressive
335optimizations.</li>
336</ul>
337</li>
338<li>Currently we disable Lazy JITting.</li>
339</ul>
340</div>
341<div class="section" id="api">
342<h1>API</h1>
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800[diff] [blame]343<p><strong>Basic:</strong></p>
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]344<ul class="simple">
345<li><strong>bccCreateScript</strong> - Create new bcc script</li>
346<li><strong>bccRegisterSymbolCallback</strong> - Register the callback function for external
347symbol lookup</li>
348<li><strong>bccReadBC</strong> - Set the source bitcode for compilation</li>
349<li><strong>bccReadModule</strong> - Set the llvm::Module for compilation</li>
350<li><strong>bccLinkBC</strong> - Set the library bitcode for linking</li>
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800[diff] [blame]351<li><strong>bccPrepareExecutable</strong> - Create the in-memory executable by either
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]352just-in-time compilation or cache loading</li>
353<li><strong>bccDeleteScript</strong> - Destroy bcc script and release the resources</li>
354<li><strong>bccGetError</strong> - Get the error code</li>
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800[diff] [blame]355<li><strong>bccGetScriptInfoLog</strong> - <em>deprecated</em> - Don't use this</li>
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]356</ul>
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800[diff] [blame]357<p><strong>Reflection:</strong></p>
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]358<ul class="simple">
359<li><strong>bccGetExportVars</strong> - Get the addresses of exported variables</li>
360<li><strong>bccGetExportFuncs</strong> - Get the addresses of exported functions</li>
361<li><strong>bccGetPragmas</strong> - Get the pragmas</li>
362</ul>
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800[diff] [blame]363<p><strong>Debug:</strong></p>
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]364<ul class="simple">
365<li><strong>bccGetFunctions</strong> - Get the function name list</li>
Shih-wei Liao7fff2282011-01-09 13:57:01 -0800[diff] [blame]366<li><strong>bccGetFunctionBinary</strong> - Get the address and the size of a function binary</li>
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]367</ul>
368</div>
369<div class="section" id="cache-file-format">
370<h1>Cache File Format</h1>
371<p>A cache file (denoted as *.oBCC) for libbcc consists of several sections:
372header, string pool, dependencies table, relocation table, exported
373variable list, exported function list, pragma list, function information
374table, and bcc context. Every section should be aligned to a word size.
375Here is the brief description of each sections:</p>
376<ul class="simple">
377<li><strong>Header</strong> (OBCC_Header) - The header of a cache file. It contains the
378magic word, version, machine integer type information, and the size
379and the offset of other sections. The header section is guaranteed
380to be at the beginning of the cache file.</li>
381<li><strong>String Pool</strong> (OBCC_StringPool) - A collection of serialized variable
382length strings. The strp_index in the other part of the cache file
383represents the index of such string in this string pool.</li>
384<li><strong>Dependencies Table</strong> (OBCC_DependencyTable) - The dependencies table.
Shih-wei Liao8538dfa2011-01-09 15:42:28 -0800[diff] [blame^]385This table stores the resource name (or file path), the resource
Shih-wei Liaoe961c662011-01-09 04:42:39 -0800[diff] [blame]386type (rather in APK or on the file system), and the SHA1 checksum.</li>
387<li><strong>Relocation Table</strong> (OBCC_RelocationTable) - <em>not enabled</em></li>
388<li><strong>Exported Variable List</strong> (OBCC_ExportVarList),
389<strong>Exported Function List</strong> (OBCC_ExportFuncList) -
390The list of the addresses of exported variables and exported functions.</li>
391<li><strong>Pragma List</strong> (OBCC_PragmaList) - The list of pragma key-value pair.</li>
392<li><strong>Function Information Table</strong> (OBCC_FuncTable) - This is a table of
393function information, such as function name, function entry address,
394and function binary size. Besides, the table should be ordered by
395function name.</li>
396<li><strong>Context</strong> - The context of the in-memory executable, including
397the code and the data. The offset of context should aligned to
398a page size, so that we can mmap the context directly into the memory.</li>
399</ul>
400<p>For furthur information, you may read <a class="reference external" href="include/bcc/bcc_cache.h">bcc_cache.h</a>,
401<a class="reference external" href="lib/bcc/CacheReader.cpp">CacheReader.cpp</a>, and
402<a class="reference external" href="lib/bcc/CacheWriter.cpp">CacheWriter.cpp</a> for details.</p>
403</div>
404<div class="section" id="jit-ed-code-calling-conventions">
405<h1>JIT'ed Code Calling Conventions</h1>
406<ol class="arabic">
407<li><p class="first">Calls from Execution Environment or from/to within script:</p>
408<p>On ARM, the first 4 arguments will go into r0, r1, r2, and r3, in that order.
409The remaining (if any) will go through stack.</p>
410<p>For ext_vec_types such as float2, a set of registers will be used. In the case
411of float2, a register pair will be used. Specifically, if float2 is the first
412argument in the function prototype, float2.x will go into r0, and float2.y,
413r1.</p>
414<p>Note: stack will be aligned to the coarsest-grained argument. In the case of
415float2 above as an argument, parameter stack will be aligned to an 8-byte
416boundary (if the sizes of other arguments are no greater than 8.)</p>
417</li>
418<li><p class="first">Calls from/to a separate compilation unit: (E.g., calls to Execution
419Environment if those runtime library callees are not compiled using LLVM.)</p>
420<p>On ARM, we use hardfp. Note that double will be placed in a register pair.</p>
421</li>
422</ol>
423</div>
424</div>
425</body>
426</html>