blob: 972292e72afd16cf955bf3a23d80c1356a468751 [file] [log] [blame]
Stephen Hines18687142011-09-02 19:07:14 -07001==============================================
2llvm-rs-cc: Compiler for Renderscript language
3==============================================
Shih-wei Liao19cc6972011-01-20 04:34:38 -08004
5
6Introduction
7------------
8
Stephen Hines18687142011-09-02 19:07:14 -07009llvm-rs-cc compiles a program in the Renderscript language to generate the
10following files:
Shih-wei Liao19cc6972011-01-20 04:34:38 -080011
12* Bitcode file. Note that the bitcode here denotes the LLVM (Low-Level
13 Virtual Machine) bitcode representation, which will be consumed on
14 an Android device by libbcc (in
15 platform/frameworks/compile/libbcc.git) to generate device-specific
16 executables.
17
18* Reflected APIs for Java. As a result, Android's Java developers can
19 invoke those APIs from their code.
20
Stephen Hines18687142011-09-02 19:07:14 -070021Note that although Renderscript is C99-like, we enhance it with several
Shih-wei Liao19cc6972011-01-20 04:34:38 -080022distinct, effective features for Android programming. We will use
Stephen Hines18687142011-09-02 19:07:14 -070023some examples to illustrate these features.
Shih-wei Liao19cc6972011-01-20 04:34:38 -080024
Stephen Hines18687142011-09-02 19:07:14 -070025llvm-rs-cc is run on the host and performs many aggressive optimizations.
26As a result, libbcc on the device can be lightweight and focus on
27machine-dependent code generation for some input bitcode.
Shih-wei Liao19cc6972011-01-20 04:34:38 -080028
Stephen Hines18687142011-09-02 19:07:14 -070029llvm-rs-cc is a driver on top of libslang. The architecture of
Shih-wei Liao19cc6972011-01-20 04:34:38 -080030libslang and libbcc is depicted in the following figure::
31
32 libslang libbcc
33 | \ |
34 | \ |
35 clang llvm
36
37
38Usage
39-----
40
41* *-o $(PRIVATE_RS_OUTPUT_DIR)/res/raw*
42
43 This option specifies the directory for outputting a .bc file.
44
45* *-p $(PRIVATE_RS_OUTPUT_DIR)/src*
46
47 The option *-p* denotes the directory for outputting the reflected Java files.
48
49* *-d $(PRIVATE_RS_OUTPUT_DIR)*
50
Stephen Hines18687142011-09-02 19:07:14 -070051 This option *-d* sets the directory for writing dependence information.
Shih-wei Liao19cc6972011-01-20 04:34:38 -080052
53* *-MD*
54
Stephen Hines18687142011-09-02 19:07:14 -070055 Note that *-MD* will tell llvm-rs-cc to output dependence information.
Shih-wei Liao19cc6972011-01-20 04:34:38 -080056
Stephen Hines18687142011-09-02 19:07:14 -070057* *-a $(EXTRA_TARGETS)*
Shih-wei Liao29c36732011-01-20 05:48:20 -080058
Stephen Hines18687142011-09-02 19:07:14 -070059 Specifies additional target dependencies.
Shih-wei Liao19cc6972011-01-20 04:34:38 -080060
61Example Command
62---------------
63
64First::
65
66 $ cd <Android_Root_Directory>
67
Stephen Hines18687142011-09-02 19:07:14 -070068Using frameworks/base/tests/RenderScriptTests/Fountain as a simple app in both
69Java and Renderscript, we can find the following command line in the build
Shih-wei Liao19cc6972011-01-20 04:34:38 -080070log::
71
72 $ out/host/linux-x86/bin/llvm-rs-cc \
73 -o out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/res/raw \
74 -p out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/src \
75 -d out/target/common/obj/APPS/Fountain_intermediates/src/renderscript \
76 -a out/target/common/obj/APPS/Fountain_intermediates/src/RenderScript.stamp \
77 -MD \
78 -I frameworks/base/libs/rs/scriptc \
79 -I external/clang/lib/Headers \
80 frameworks/base/libs/rs/java/Fountain/src/com/android/fountain/fountain.rs
81
82This command will generate:
83
84* **fountain.bc**
85
86* **ScriptC_fountain.java**
87
88* **ScriptField_Point.java**
89
90The **Script\*.java** files above will be documented below.
91
92
93Example Program: fountain.rs
94----------------------------
95
Stephen Hines18687142011-09-02 19:07:14 -070096fountain.rs is in the Renderscript language, which is based on the standard
Shih-wei Liao19cc6972011-01-20 04:34:38 -080097C99. However, llvm-rs-cc goes beyond "clang -std=c99" and provides the
98following important features:
99
1001. Pragma
101---------
102
103* *#pragma rs java_package_name([PACKAGE_NAME])*
104
105 The ScriptC_[SCRIPT_NAME].java has to be packaged so that Java
106 developers can invoke those APIs.
107
Stephen Hines18687142011-09-02 19:07:14 -0700108 To do that, a Renderscript programmer should specify the package name, so
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800109 that llvm-rs-cc knows the package expression and hence the directory
110 for outputting ScriptC_[SCRIPT_NAME].java.
111
112 In fountain.rs, we have::
113
114 #pragma rs java_package_name(com.android.fountain)
115
Stephen Hines18687142011-09-02 19:07:14 -0700116 In ScriptC_fountain.java, we have::
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800117
118 package com.android.fountain
119
120 Note that the ScriptC_fountain.java will be generated inside
121 ./com/android/fountain/.
122
123* #pragma version(1)
124
125 This pragma is for evolving the language. Currently we are at
126 version 1 of the language.
127
128
1292. Basic Reflection: Export Variables and Functions
130---------------------------------------------------
131
Stephen Hines18687142011-09-02 19:07:14 -0700132llvm-rs-cc automatically exports the "externalizable and defined" functions and
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800133variables to Android's Java side. That is, scripts are accessible from
134Java.
135
136For instance, for::
137
138 int foo = 0;
139
Stephen Hines18687142011-09-02 19:07:14 -0700140In ScriptC_fountain.java, llvm-rs-cc will reflect the following methods::
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800141
142 void set_foo(int v)...
143
144 int get_foo()...
145
146This access takes the form of generated classes which provide access
147to the functions and global variables within a script. In summary,
148global variables and functions within a script that are not declared
149static will generate get, set, or invoke methods. This provides a way
Stephen Hines18687142011-09-02 19:07:14 -0700150to set the data within a script and call its functions.
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800151
152Take the addParticles function in fountain.rs as an example::
153
154 void addParticles(int rate, float x, float y, int index, bool newColor) {
155 ...
156 }
157
158llvm-rs-cc will genearte ScriptC_fountain.java as follows::
159
160 void invoke_addParticles(int rate, float x, float y,
161 int index, bool newColor) {
162 ...
163 }
164
165
1663. Export User-Defined Structs
167------------------------------
168
169In fountain.rs, we have::
170
171 typedef struct __attribute__((packed, aligned(4))) Point {
172 float2 delta;
173 float2 position;
174 uchar4 color;
175 } Point_t;
176
177 Point_t *point;
178
179llvm-rs-cc generates one ScriptField*.java file for each user-defined
Stephen Hines18687142011-09-02 19:07:14 -0700180struct. In this case, llvm-rs-cc will reflect two files,
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800181ScriptC_fountain.java and ScriptField_Point.java.
182
Stephen Hines18687142011-09-02 19:07:14 -0700183Note that when the type of an exportable variable is a structure, Renderscript
184developers should avoid using anonymous structs. This is because llvm-rs-cc
185uses the struct name to identify the file, instead of the typedef name.
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800186
187For the generated Java files, using ScriptC_fountain.java as an
Stephen Hines18687142011-09-02 19:07:14 -0700188example we also have::
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800189
190 void bind_point(ScriptField_Point v)
191
192This binds your object with the allocated memory.
193
194You can bind the struct(e.g., Point), using the setter and getter
Stephen Hines18687142011-09-02 19:07:14 -0700195methods in ScriptField_Point.java.
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800196
Stephen Hines18687142011-09-02 19:07:14 -0700197After binding, you can access the object with this method::
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800198
199 ScriptField_Point get_point()
200
201In ScriptField_Point_s.java::
202
203 ...
204 // Copying the Item, which is the object that stores every
205 // fields of struct, to the *index*\-th entry of byte array.
206 //
207 // In general, this method would not be invoked directly
208 // but is used to implement the setter.
209 void copyToArray(Item i, int index)
210
211 // The setter of Item array,
212 // index: the index of the Item array
213 // copyNow: If true, it will be copied to the *index*\-th entry
214 // of byte array.
215 void set(Item i, int index, boolean copyNow)
216
217 // The getter of Item array, which gets the *index*-th element
218 // of byte array.
219 Item get(int index)
220
221 set_delta(int index, Float2 v, boolean copyNow)
222
223 // The following is the individual setters and getters of
224 // each field of a struct.
225 public void set_delta(int index, Float2 v, boolean copyNow)
226 public void set_position(int index, Float2 v, boolean copyNow)
227 public void set_color(int index, Short4 v, boolean copyNow)
228 public Float2 get_delta(int index)
229 public Float2 get_position(int index)
230 public Short4 get_color(int index)
231
232 // Copying all Item array to byte array (i.e., memory allocation).
233 void copyAll()
234 ...
235
236
Stephen Hines18687142011-09-02 19:07:14 -07002374. Summary of the Java Reflection above
238---------------------------------------
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800239
Stephen Hines18687142011-09-02 19:07:14 -0700240This section summarizes the high-level design of Renderscript's reflection.
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800241
Stephen Hines18687142011-09-02 19:07:14 -0700242* In terms of a script's global functions, they can be called from Java.
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800243 These calls operate asynchronously and no assumptions should be made
Stephen Hines18687142011-09-02 19:07:14 -0700244 on whether a function called will have actually completed operation. If it
245 is necessary to wait for a function to complete, the Java application
246 may call the runtime finish() method, which will wait for all the script
247 threads to complete pending operations. A few special functions can also
248 exist:
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800249
Stephen Hines18687142011-09-02 19:07:14 -0700250 * The function **init** (if present) will be called once after the script
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800251 is loaded. This is useful to initialize data or anything else the
Stephen Hines18687142011-09-02 19:07:14 -0700252 script may need before it can be used. The init function may not depend
253 on globals initialized from Java as it will be called before these
254 can be initialized. The function signature for init must be::
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800255
Stephen Hines18687142011-09-02 19:07:14 -0700256 void init(void);
257
258 * The function **root** is a special function for graphics. This function
259 will be called when a script must redraw its contents. No
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800260 assumptions should be made as to when this function will be
Stephen Hines18687142011-09-02 19:07:14 -0700261 called. It will only be called if the script is bound as a graphics root.
262 Calls to this function will be synchronized with data updates and
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800263 other invocations from Java. Thus the script will not change due
Stephen Hines18687142011-09-02 19:07:14 -0700264 to external influence in the middle of running **root**. The return value
265 indicates to the runtime when the function should be called again to
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800266 redraw in the future. A return value of 0 indicates that no
Stephen Hines18687142011-09-02 19:07:14 -0700267 redraw is necessary until something changes on the Java side. Any
268 positive integer indicates a time in milliseconds that the runtime should
269 wait before calling root again to render another frame. The function
270 signature for a graphics root functions is as follows::
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800271
Stephen Hines18687142011-09-02 19:07:14 -0700272 int root(void);
273
274 * It is also possible to create a purely compute-based **root** function.
275 Such a function has the following signature::
276
277 void root(const T1 *in, T2 *out, const T3 *usrData, uint32_t x, uint32_t y);
278
279 T1, T2, and T3 represent any supported Renderscript type. Any parameters
280 above can be omitted, although at least one of in/out must be present.
281 If both in and out are present, root must only be invoked with types of
282 the same exact dimensionality (i.e. matching X and Y values for dimension).
283 This root function is accessible through the Renderscript language
284 construct **forEach**. We also reflect a Java version to access this
285 function as **forEach_root** (for API levels of 14+). An example of this
286 can be seen in the Android SDK sample for HelloCompute.
287
288 * The function **.rs.dtor** is a function that is sometimes generated by
289 llvm-rs-cc. This function cleans up any global variable that contains
290 (or is) a reference counted Renderscript object type (such as an
291 rs_allocation, rs_font, or rs_script). This function will be invoked
292 implicitly by the Renderscript runtime during script teardown.
293
294* In terms of a script's global data, global variables can be written
295 from Java. The Java instance will cache the value or object set and
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800296 provide return methods to retrieve this value. If a script updates
297 the value, this update will not propagate back to the Java class.
Stephen Hines18687142011-09-02 19:07:14 -0700298 Initializers, if present, will also initialize the cached Java value.
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800299 This provides a convenient way to declare constants within a script and
Stephen Hines18687142011-09-02 19:07:14 -0700300 make them accessible to the Java runtime. If the script declares a
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800301 variable const, only the get methods will be generated.
302
303 Globals within a script are considered local to the script. They
304 cannot be accessed by other scripts and are in effect always 'static'
Stephen Hines18687142011-09-02 19:07:14 -0700305 in the traditional C sense. Static here is used to control if
306 accessors are generated. Static continues to mean *not
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800307 externally visible* and thus prevents the generation of
Stephen Hines18687142011-09-02 19:07:14 -0700308 accessors. Globals are persistent across invocations of a script and
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800309 thus may be used to hold data from run to run.
310
311 Globals of two types may be reflected into the Java class. The first
Stephen Hines18687142011-09-02 19:07:14 -0700312 type is basic non-pointer types. Types defined in rs_types.rsh may also be
313 used. For the non-pointer class, get and set methods are generated for
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800314 Java. Globals of single pointer types behave differently. These may
315 use more complex types. Simple structures composed of the types in
316 rs_types.rsh may also be used. These globals generate bind points in
Stephen Hines18687142011-09-02 19:07:14 -0700317 Java. If the type is a structure they also generate an appropriate
318 **Field** class that is used to pack and unpack the contents of the
319 structure. Binding an allocation in Java effectively sets the
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800320 pointer in the script. Bind points marked const indicate to the
321 runtime that the script will not modify the contents of an allocation.
322 This may allow the runtime to make more effective use of threads.
323
324
3255. Vector Types
326---------------
327
328Vector types such as float2, float4, and uint4 are included to support
329vector processing in environments where the processors provide vector
330instructions.
331
332On non-vector systems the same code will continue to run but without
333the performance advantage. Function overloading is also supported.
334This allows the runtime to support vector version of the basic math
335routines without the need for special naming. For instance,
336
337* *float sin(float);*
338
339* *float2 sin(float2);*
340
Stephen Hines18687142011-09-02 19:07:14 -0700341* *float3 sin(float3);*
342
Shih-wei Liao19cc6972011-01-20 04:34:38 -0800343* *float4 sin(float4);*