<?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>llvm-rs-cc: Compiler for ScriptC language</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="llvm-rs-cc-compiler-for-scriptc-language">
<h1 class="title">llvm-rs-cc: Compiler for ScriptC language</h1>

<div class="section" id="introduction">
<h1>Introduction</h1>
<p>llvm-rs-cc compiles a program in the ScriptC language to generate the
following files.</p>
<ul class="simple">
<li>Bitcode file. Note that the bitcode here denotes the LLVM (Low-Level
Virtual Machine) bitcode representation, which will be consumed on
an Android device by libbcc (in
platform/frameworks/compile/libbcc.git) to generate device-specific
executables.</li>
<li>Reflected APIs for Java. As a result, Android's Java developers can
invoke those APIs from their code.</li>
</ul>
<p>Note that although ScriptC is C99-like, we enhance it with several
distinct, effective features for Android programming. We will use
example usage below to illustrate these features.</p>
<p>llvm-rs-cc is being run on a host and is highly-optimizing. As a
result, libbcc on the device can be lightweight and focus on
machine-dependent code generation given some bitcode.</p>
<p>llvm-rs-cc is a driver on top of libslang. The archictecture of
libslang and libbcc is depicted in the following figure:</p>
<pre class="literal-block">
libslang   libbcc
    |   \   |
    |    \  |
 clang     llvm
</pre>
</div>
<div class="section" id="usage">
<h1>Usage</h1>
<ul>
<li><p class="first"><em>-o $(PRIVATE_RS_OUTPUT_DIR)/res/raw</em></p>
<p>This option specifies the directory for outputting a .bc file.</p>
</li>
<li><p class="first"><em>-p $(PRIVATE_RS_OUTPUT_DIR)/src</em></p>
<p>The option <em>-p</em> denotes the directory for outputting the reflected Java files.</p>
</li>
<li><p class="first"><em>-d $(PRIVATE_RS_OUTPUT_DIR)</em></p>
<p>This option <em>-d</em> sets the directory for writing dependences.</p>
</li>
<li><p class="first"><em>-MD</em></p>
<p>Note that <em>-MD</em> will tell llvm-rs-cc to output dependences.</p>
</li>
<li><p class="first"><em>-a</em></p>
<p>Specifies additional dependence target.</p>
</li>
</ul>
</div>
<div class="section" id="example-command">
<h1>Example Command</h1>
<p>First:</p>
<pre class="literal-block">
$ cd &lt;Android_Root_Directory&gt;
</pre>
<p>Using frameworks/base/libs/rs/java/Fountain as a simple app in both
Java and ScriptC, we can find the following command line in the build
log:</p>
<pre class="literal-block">
$ out/host/linux-x86/bin/llvm-rs-cc \
  -o out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/res/raw \
  -p out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/src \
  -d out/target/common/obj/APPS/Fountain_intermediates/src/renderscript \
  -a out/target/common/obj/APPS/Fountain_intermediates/src/RenderScript.stamp \
  -MD \
  -I frameworks/base/libs/rs/scriptc \
  -I external/clang/lib/Headers \
  frameworks/base/libs/rs/java/Fountain/src/com/android/fountain/fountain.rs
</pre>
<p>This command will generate:</p>
<ul class="simple">
<li><strong>fountain.bc</strong></li>
<li><strong>ScriptC_fountain.java</strong></li>
<li><strong>ScriptField_Point.java</strong></li>
</ul>
<p>The <strong>Script*.java</strong> files above will be documented below.</p>
</div>
<div class="section" id="example-program-fountain-rs">
<h1>Example Program: fountain.rs</h1>
<p>fountain.rs is in ScriptC language, which is based on the standard
C99. However, llvm-rs-cc goes beyond &quot;clang -std=c99&quot; and provides the
following important features:</p>
</div>
<div class="section" id="pragma">
<h1>1. Pragma</h1>
<ul>
<li><p class="first"><em>#pragma rs java_package_name([PACKAGE_NAME])</em></p>
<p>The ScriptC_[SCRIPT_NAME].java has to be packaged so that Java
developers can invoke those APIs.</p>
<p>To do that, a ScriptC programmer should specify the package name, so
that llvm-rs-cc knows the package expression and hence the directory
for outputting ScriptC_[SCRIPT_NAME].java.</p>
<p>In fountain.rs, we have:</p>
<pre class="literal-block">
#pragma rs java_package_name(com.android.fountain)
</pre>
<p>In ScriptC.fountain.java, we have:</p>
<pre class="literal-block">
package com.android.fountain
</pre>
<p>Note that the ScriptC_fountain.java will be generated inside
./com/android/fountain/.</p>
</li>
<li><p class="first">#pragma version(1)</p>
<p>This pragma is for evolving the language. Currently we are at
version 1 of the language.</p>
</li>
</ul>
</div>
<div class="section" id="basic-reflection-export-variables-and-functions">
<h1>2. Basic Reflection: Export Variables and Functions</h1>
<p>llvm-rs-cc automatically export the &quot;externalizable and defined&quot; functions and
variables to Android's Java side. That is, scripts are accessible from
Java.</p>
<p>For instance, for:</p>
<pre class="literal-block">
int foo = 0;
</pre>
<p>In ScriptC_fountain.java, llvm-rs-cc will reflect it to:</p>
<pre class="literal-block">
void set_foo(int v)...

int get_foo()...
</pre>
<p>This access takes the form of generated classes which provide access
to the functions and global variables within a script. In summary,
global variables and functions within a script that are not declared
static will generate get, set, or invoke methods.  This provides a way
to set the data within a script and call to its functions.</p>
<p>Take the addParticles function in fountain.rs as an example:</p>
<pre class="literal-block">
void addParticles(int rate, float x, float y, int index, bool newColor) {
  ...
}
</pre>
<p>llvm-rs-cc will genearte ScriptC_fountain.java as follows:</p>
<pre class="literal-block">
void invoke_addParticles(int rate, float x, float y,
                         int index, bool newColor) {
  ...
}
</pre>
</div>
<div class="section" id="export-user-defined-structs">
<h1>3. Export User-Defined Structs</h1>
<p>In fountain.rs, we have:</p>
<pre class="literal-block">
typedef struct __attribute__((packed, aligned(4))) Point {
  float2 delta;
  float2 position;
  uchar4 color;
} Point_t;

Point_t *point;
</pre>
<p>llvm-rs-cc generates one ScriptField*.java file for each user-defined
struct. I.e., in this case llvm-rs-cc will reflect to two files,
ScriptC_fountain.java and ScriptField_Point.java.</p>
<p>Note that when the type of exportable variable is struct, ScriptC
developers should avoid anonymous structs. This is because llvm-rs-cc
uses the struct name to name the file, instead of the typedef name.</p>
<p>For the generated Java files, using ScriptC_fountain.java as an
example we have:</p>
<pre class="literal-block">
void bind_point(ScriptField_Point v)
</pre>
<p>This binds your object with the allocated memory.</p>
<p>You can bind the struct(e.g., Point), using the setter and getter
method in ScriptField_Point.java.</p>
<p>After binding, you could get the object from this method:</p>
<pre class="literal-block">
ScriptField_Point get_point()
</pre>
<p>In ScriptField_Point_s.java:</p>
<pre class="literal-block">
...
// Copying the Item, which is the object that stores every
// fields of struct, to the *index*\-th entry of byte array.
//
// In general, this method would not be invoked directly
// but is used to implement the setter.
void copyToArray(Item i, int index)

// The setter of Item array,
// index: the index of the Item array
// copyNow: If true, it will be copied to the *index*\-th entry
// of byte array.
void set(Item i, int index, boolean copyNow)

// The getter of Item array, which gets the *index*-th element
// of byte array.
Item get(int index)

set_delta(int index, Float2 v, boolean copyNow)

// The following is the individual setters and getters of
// each field of a struct.
public void set_delta(int index, Float2 v, boolean copyNow)
public void set_position(int index, Float2 v, boolean copyNow)
public void set_color(int index, Short4 v, boolean copyNow)
public Float2 get_delta(int index)
public Float2 get_position(int index)
public Short4 get_color(int index)

// Copying all Item array to byte array (i.e., memory allocation).
void copyAll()
...
</pre>
</div>
<div class="section" id="summarize-the-java-reflection-above">
<h1>4. Summarize the Java Reflection above</h1>
<p>Let us summarize the high-level design of reflection next.</p>
<ul>
<li><p class="first">In terms of script's global functions, they can be called from Java.
These calls operate asynchronously and no assumptions should be made
upon with a function called will actually complete operation.  If it
is necessary to wait for a function to complete the java application
may call the runtime finish method which will wait for all the script
threads to complete.  Two special functions also exist:</p>
<ul class="simple">
<li>The function <strong>init</strong> present will be called once after the script
is loaded.  This is useful to initialize data or anything else the
script may need before it can be used.  The init may not depend on
globals initialized from Java as it will be called before these
can be initialized.</li>
<li>The function <strong>root</strong> is a special function for graphics.  Which a
script must redraw its contents this function will be called.  No
assumptions should be made as to when this function will be
called.  It will only be called if the script is bound as root.
Also calls to this will be synchronized with data updates and
other invocations from Java.  Thus the script will not change due
to external influence during a run of <strong>root</strong>.  The return value
indicates to the runtime if the function should be called again to
redraw in the future.  A return value of 0 indicates that no
redraw is necessary until something changes.  Any positive integer
indicates a time in ms that the runtime should wait before calling
root again to render another frame.</li>
</ul>
</li>
<li><p class="first">In terms of script's global data, global variables can be written
from Java.  The Java class will cache the value or object set and
provide return methods to retrieve this value.  If a script updates
the value, this update will not propagate back to the Java class.
Initializers if present will also initialize the cached Java value.
This provides a convenient way to declare constants within a script and
make them accessible from the java runtime.  If the script declares a
variable const, only the get methods will be generated.</p>
<p>Globals within a script are considered local to the script.  They
cannot be accessed by other scripts and are in effect always 'static'
in the traditional C sense.  Static here is used to control if a
accessor is generated.  Static continues to mean <em>not
externally visible</em> and thus prevents the generation of
accessors.  Globals are persistent across invocations to a script and
thus may be used to hold data from run to run.</p>
<p>Globals of two types may be reflected into the Java class.  The first
type is basic non-pointer types.  Types defined in rs_types.rsh may be
used.  For the non-pointer class get and set methods are generated in
Java.  Globals of single pointer types behave differently.  These may
use more complex types.  Simple structures composed of the types in
rs_types.rsh may also be used.  These globals generate bind points in
java.  If the type is a structure they also generate a <strong>Field</strong> class
used to pack and unpack the contents of the structure.  Binding an
allocation to one of these bind points in Java effectively sets the
pointer in the script.  Bind points marked const indicate to the
runtime that the script will not modify the contents of an allocation.
This may allow the runtime to make more effective use of threads.</p>
</li>
</ul>
</div>
<div class="section" id="vector-types">
<h1>5. Vector Types</h1>
<p>Vector types such as float2, float4, and uint4 are included to support
vector processing in environments where the processors provide vector
instructions.</p>
<p>On non-vector systems the same code will continue to run but without
the performance advantage.  Function overloading is also supported.
This allows the runtime to support vector version of the basic math
routines without the need for special naming.  For instance,</p>
<ul class="simple">
<li><em>float sin(float);</em></li>
<li><em>float2 sin(float2);</em></li>
<li><em>float4 sin(float4);</em></li>
</ul>
</div>
</div>
</body>
</html>