Update README, and markup with reStructuredText.
Update the API documentation, since bccCompileBC and bccLoadBinary
are removed. Update the document about the cache file format.
Since the caching mechanism has been rewritten completely.
Note: Now, we are going to adopt reStructuredText to markup
the document. reStructuredText is a natural markup language,
which is human-eye-friendly (contrast to html).
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..d77c665
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,139 @@
+=========================================
+libbcc: A Hybrid Bitcode Execution Engine
+=========================================
+
+
+Introduction
+------------
+
+libbcc is an LLVM bitcode execution engine which compiles the bitcode
+to an in-memory executable. It comes with a *just-in-time bitcode
+compiler*, which translates the bitcode to machine code, and a *caching
+mechanism*, which saves the in-memory executable after the compilation.
+Here are some highlights of libbcc:
+
+* libbcc supports bit code from various language frontends, such as
+ RenderScript, GLSL.
+
+* libbcc strives to balance between library size, launch time and
+ steady-state performance:
+
+ * The size of libbcc is aggressively reduced for a mobile device.
+ We customize and we don't use Execution Engine.
+
+ * To reduce launch time, we support caching of binaries.
+
+ * For steady-state performance, we enable VFP3 and aggressive
+ optimizations.
+
+
+
+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** Create the in-memory executable by either
+ just-in-time compilation or cache loading
+
+* **bccDeleteScript** - Destroy bcc script and release the resources
+
+* **bccGetError** - Get the error code
+
+* **bccGetScriptInfoLog** *deprecated* - Don't use this
+
+
+Reflection:
+
+* **bccGetExportVars** - Get the addresses of exported variables
+
+* **bccGetExportFuncs** - Get the addresses of exported functions
+
+* **bccGetPragmas** - Get the pragmas
+
+
+Debug:
+
+* **bccGetFunctions** - Get the function name list
+
+* **bccGetFunctionBinary** - Get the address and the size of function binary
+
+
+
+Cache File Format
+-----------------
+
+The cache file of libbcc (\*.oBCC) is consisted 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's the brief description of each sections:
+
+* **Header** (OBCC_Header) - The header of the cache file. Contains the
+ magic word, version, machine integer type information, and the size
+ and the offset of other sections. The header section is guaranteed
+ to be at the beginning of the cache file.
+
+* **String Pool** (OBCC_StringPool) - A collection of serialized variadic
+ 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** (OBCC_DependencyTable) - The dependencies table.
+ This table will store the resource name (or file path), the resouece
+ type (rather in APK or on the file system), and the SHA1 checksum.
+
+* **Relocation Table** (OBCC_RelocationTable) *not finished*
+
+* **Exported Variable List** (OBCC_ExportVarList),
+ **Exported Function List** (OBCC_ExportFuncList) -
+ The list of the addresses of exported variables and exported functions.
+
+* **Pragma List** (OBCC_PragmaList) - The list of pragma key-value pair.
+
+* **Function Information Table** (OBCC_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 the 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.