===============================================================
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.