• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..--

BitWriter_2_9/22-Nov-2023-2,7301,941

BitWriter_2_9_func/22-Nov-2023-2,7692,006

BitWriter_3_2/22-Nov-2023-2,8722,090

lit-tests/22-Nov-2023-348212

tests/22-Nov-2023-59,05957,999

.clang-formatD22-Nov-202381 32

.gitD01-Jan-19700

Android.mkD22-Nov-20234.9 KiB195133

MODULE_LICENSE_APACHE2D22-Nov-20230

NOTICED22-Nov-202316.7 KiB340272

README.htmlD22-Nov-202319.8 KiB627543

README.rstD22-Nov-202312.2 KiB344242

RSCCOptions.tdD22-Nov-20235.8 KiB145113

legacy_bitcode.hD22-Nov-20231.3 KiB3310

llvm-rs-as.cppD22-Nov-20234.6 KiB154110

llvm-rs-cc.cppD22-Nov-20239.9 KiB296204

os_sep.hD22-Nov-20231.1 KiB3410

rs_cc_options.cppD22-Nov-20239.1 KiB270200

rs_cc_options.hD22-Nov-20234.3 KiB14060

rs_version.mkD22-Nov-2023790 232

slang.cppD22-Nov-202323.5 KiB767554

slang.hD22-Nov-20238.9 KiB293165

slang_assert.hD22-Nov-20231.5 KiB4120

slang_backend.cppD22-Nov-202328.1 KiB864628

slang_backend.hD22-Nov-20235.6 KiB18290

slang_diagnostic_buffer.cppD22-Nov-20232.1 KiB8252

slang_diagnostic_buffer.hD22-Nov-20231.9 KiB6532

slang_pragma_recorder.cppD22-Nov-20233.6 KiB11577

slang_pragma_recorder.hD22-Nov-20231.6 KiB5527

slang_rs_ast_replace.cppD22-Nov-20234 KiB158115

slang_rs_ast_replace.hD22-Nov-20232.4 KiB8958

slang_rs_check_ast.cppD22-Nov-20238.1 KiB296223

slang_rs_check_ast.hD22-Nov-20232.4 KiB8039

slang_rs_context.cppD22-Nov-20237.6 KiB279201

slang_rs_context.hD22-Nov-20238.9 KiB290216

slang_rs_export_element.cppD22-Nov-20235.8 KiB179128

slang_rs_export_element.hD22-Nov-20231.9 KiB7336

slang_rs_export_foreach.cppD22-Nov-202324.8 KiB699526

slang_rs_export_foreach.hD22-Nov-20236.3 KiB210144

slang_rs_export_func.cppD22-Nov-20235.1 KiB174113

slang_rs_export_func.hD22-Nov-20233.2 KiB10966

slang_rs_export_type.cppD22-Nov-202354.3 KiB1,6051,264

slang_rs_export_type.hD22-Nov-202318.7 KiB602388

slang_rs_export_var.cppD22-Nov-20233.7 KiB10984

slang_rs_export_var.hD22-Nov-20232 KiB7140

slang_rs_exportable.cppD22-Nov-2023941 3412

slang_rs_exportable.hD22-Nov-20231.7 KiB6431

slang_rs_metadata.hD22-Nov-20231.2 KiB3712

slang_rs_object_ref_count.cppD22-Nov-202355.1 KiB1,5641,054

slang_rs_object_ref_count.hD22-Nov-20234.9 KiB15792

slang_rs_pragma_handler.cppD22-Nov-202311.6 KiB368240

slang_rs_pragma_handler.hD22-Nov-20232.5 KiB7940

slang_rs_reflect_utils.cppD22-Nov-202312.5 KiB440349

slang_rs_reflect_utils.hD22-Nov-20235.8 KiB15254

slang_rs_reflection.cppD22-Nov-202372.4 KiB2,1271,662

slang_rs_reflection.hD22-Nov-20239.4 KiB259165

slang_rs_reflection_cpp.cppD22-Nov-202332.4 KiB1,013824

slang_rs_reflection_cpp.hD22-Nov-20235 KiB14075

slang_version.hD22-Nov-20231.9 KiB6634

strip_unknown_attributes.cppD22-Nov-20231.8 KiB6435

strip_unknown_attributes.hD22-Nov-20231.4 KiB4312

README.html

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>llvm-rs-cc: Compiler for Renderscript language</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="llvm-rs-cc-compiler-for-renderscript-language">
308<h1 class="title">llvm-rs-cc: Compiler for Renderscript language</h1>
309
310<div class="section" id="introduction">
311<h1>Introduction</h1>
312<p>llvm-rs-cc compiles a program in the Renderscript language to generate the
313following files:</p>
314<ul class="simple">
315<li>Bitcode file. Note that the bitcode here denotes the LLVM (Low-Level
316Virtual Machine) bitcode representation, which will be consumed on
317an Android device by libbcc (in
318platform/frameworks/compile/libbcc.git) to generate device-specific
319executables.</li>
320<li>Reflected APIs for Java. As a result, Android's Java developers can
321invoke those APIs from their code.</li>
322</ul>
323<p>Note that although Renderscript is C99-like, we enhance it with several
324distinct, effective features for Android programming. We will use
325some examples to illustrate these features.</p>
326<p>llvm-rs-cc is run on the host and performs many aggressive optimizations.
327As a result, libbcc on the device can be lightweight and focus on
328machine-dependent code generation for some input bitcode.</p>
329<p>llvm-rs-cc is a driver on top of libslang. The architecture of
330libslang and libbcc is depicted in the following figure:</p>
331<pre class="literal-block">
332libslang   libbcc
333    |   \   |
334    |    \  |
335 clang     llvm
336</pre>
337</div>
338<div class="section" id="usage">
339<h1>Usage</h1>
340<ul>
341<li><p class="first"><em>-o $(PRIVATE_RS_OUTPUT_DIR)/res/raw</em></p>
342<p>This option specifies the directory for outputting a .bc file.</p>
343</li>
344<li><p class="first"><em>-p $(PRIVATE_RS_OUTPUT_DIR)/src</em></p>
345<p>The option <em>-p</em> denotes the directory for outputting the reflected Java files.</p>
346</li>
347<li><p class="first"><em>-d $(PRIVATE_RS_OUTPUT_DIR)</em></p>
348<p>This option <em>-d</em> sets the directory for writing dependence information.</p>
349</li>
350<li><p class="first"><em>-MD</em></p>
351<p>Note that <em>-MD</em> will tell llvm-rs-cc to output dependence information.</p>
352</li>
353<li><p class="first"><em>-a $(EXTRA_TARGETS)</em></p>
354<p>Specifies additional target dependencies.</p>
355</li>
356</ul>
357</div>
358<div class="section" id="example-command">
359<h1>Example Command</h1>
360<p>First:</p>
361<pre class="literal-block">
362$ cd &lt;Android_Root_Directory&gt;
363</pre>
364<p>Using frameworks/base/tests/RenderScriptTests/Fountain as a simple app in both
365Java and Renderscript, we can find the following command line in the build
366log:</p>
367<pre class="literal-block">
368$ out/host/linux-x86/bin/llvm-rs-cc \
369  -o out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/res/raw \
370  -p out/target/common/obj/APPS/Fountain_intermediates/src/renderscript/src \
371  -d out/target/common/obj/APPS/Fountain_intermediates/src/renderscript \
372  -a out/target/common/obj/APPS/Fountain_intermediates/src/RenderScript.stamp \
373  -MD \
374  -I frameworks/base/libs/rs/scriptc \
375  -I external/clang/lib/Headers \
376  frameworks/base/libs/rs/java/Fountain/src/com/android/fountain/fountain.rs
377</pre>
378<p>This command will generate:</p>
379<ul class="simple">
380<li><strong>fountain.bc</strong></li>
381<li><strong>ScriptC_fountain.java</strong></li>
382<li><strong>ScriptField_Point.java</strong></li>
383</ul>
384<p>The <strong>Script*.java</strong> files above will be documented below.</p>
385</div>
386<div class="section" id="example-program-fountain-rs">
387<h1>Example Program: fountain.rs</h1>
388<p>fountain.rs is in the Renderscript language, which is based on the standard
389C99. However, llvm-rs-cc goes beyond &quot;clang -std=c99&quot; and provides the
390following important features:</p>
391</div>
392<div class="section" id="pragma">
393<h1>1. Pragma</h1>
394<ul>
395<li><p class="first"><em>#pragma rs java_package_name([PACKAGE_NAME])</em></p>
396<p>The ScriptC_[SCRIPT_NAME].java has to be packaged so that Java
397developers can invoke those APIs.</p>
398<p>To do that, a Renderscript programmer should specify the package name, so
399that llvm-rs-cc knows the package expression and hence the directory
400for outputting ScriptC_[SCRIPT_NAME].java.</p>
401<p>In fountain.rs, we have:</p>
402<pre class="literal-block">
403#pragma rs java_package_name(com.android.fountain)
404</pre>
405<p>In ScriptC_fountain.java, we have:</p>
406<pre class="literal-block">
407package com.android.fountain
408</pre>
409<p>Note that the ScriptC_fountain.java will be generated inside
410./com/android/fountain/.</p>
411</li>
412<li><p class="first">#pragma version(1)</p>
413<p>This pragma is for evolving the language. Currently we are at
414version 1 of the language.</p>
415</li>
416</ul>
417</div>
418<div class="section" id="basic-reflection-export-variables-and-functions">
419<h1>2. Basic Reflection: Export Variables and Functions</h1>
420<p>llvm-rs-cc automatically exports the &quot;externalizable and defined&quot; functions and
421variables to Android's Java side. That is, scripts are accessible from
422Java.</p>
423<p>For instance, for:</p>
424<pre class="literal-block">
425int foo = 0;
426</pre>
427<p>In ScriptC_fountain.java, llvm-rs-cc will reflect the following methods:</p>
428<pre class="literal-block">
429void set_foo(int v)...
430
431int get_foo()...
432</pre>
433<p>This access takes the form of generated classes which provide access
434to the functions and global variables within a script. In summary,
435global variables and functions within a script that are not declared
436static will generate get, set, or invoke methods.  This provides a way
437to set the data within a script and call its functions.</p>
438<p>Take the addParticles function in fountain.rs as an example:</p>
439<pre class="literal-block">
440void addParticles(int rate, float x, float y, int index, bool newColor) {
441  ...
442}
443</pre>
444<p>llvm-rs-cc will genearte ScriptC_fountain.java as follows:</p>
445<pre class="literal-block">
446void invoke_addParticles(int rate, float x, float y,
447                         int index, bool newColor) {
448  ...
449}
450</pre>
451</div>
452<div class="section" id="export-user-defined-structs">
453<h1>3. Export User-Defined Structs</h1>
454<p>In fountain.rs, we have:</p>
455<pre class="literal-block">
456typedef struct __attribute__((packed, aligned(4))) Point {
457  float2 delta;
458  float2 position;
459  uchar4 color;
460} Point_t;
461
462Point_t *point;
463</pre>
464<p>llvm-rs-cc generates one ScriptField*.java file for each user-defined
465struct. In this case, llvm-rs-cc will reflect two files,
466ScriptC_fountain.java and ScriptField_Point.java.</p>
467<p>Note that when the type of an exportable variable is a structure, Renderscript
468developers should avoid using anonymous structs. This is because llvm-rs-cc
469uses the struct name to identify the file, instead of the typedef name.</p>
470<p>For the generated Java files, using ScriptC_fountain.java as an
471example we also have:</p>
472<pre class="literal-block">
473void bind_point(ScriptField_Point v)
474</pre>
475<p>This binds your object with the allocated memory.</p>
476<p>You can bind the struct(e.g., Point), using the setter and getter
477methods in ScriptField_Point.java.</p>
478<p>After binding, you can access the object with this method:</p>
479<pre class="literal-block">
480ScriptField_Point get_point()
481</pre>
482<p>In ScriptField_Point_s.java:</p>
483<pre class="literal-block">
484...
485// Copying the Item, which is the object that stores every
486// fields of struct, to the *index*\-th entry of byte array.
487//
488// In general, this method would not be invoked directly
489// but is used to implement the setter.
490void copyToArray(Item i, int index)
491
492// The setter of Item array,
493// index: the index of the Item array
494// copyNow: If true, it will be copied to the *index*\-th entry
495// of byte array.
496void set(Item i, int index, boolean copyNow)
497
498// The getter of Item array, which gets the *index*-th element
499// of byte array.
500Item get(int index)
501
502set_delta(int index, Float2 v, boolean copyNow)
503
504// The following is the individual setters and getters of
505// each field of a struct.
506public void set_delta(int index, Float2 v, boolean copyNow)
507public void set_position(int index, Float2 v, boolean copyNow)
508public void set_color(int index, Short4 v, boolean copyNow)
509public Float2 get_delta(int index)
510public Float2 get_position(int index)
511public Short4 get_color(int index)
512
513// Copying all Item array to byte array (i.e., memory allocation).
514void copyAll()
515...
516</pre>
517</div>
518<div class="section" id="summary-of-the-java-reflection-above">
519<h1>4. Summary of the Java Reflection above</h1>
520<p>This section summarizes the high-level design of Renderscript's reflection.</p>
521<ul>
522<li><p class="first">In terms of a script's global functions, they can be called from Java.
523These calls operate asynchronously and no assumptions should be made
524on whether a function called will have actually completed operation.  If it
525is necessary to wait for a function to complete, the Java application
526may call the runtime finish() method, which will wait for all the script
527threads to complete pending operations.  A few special functions can also
528exist:</p>
529<ul>
530<li><p class="first">The function <strong>init</strong> (if present) will be called once after the script
531is loaded.  This is useful to initialize data or anything else the
532script may need before it can be used.  The init function may not depend
533on globals initialized from Java as it will be called before these
534can be initialized. The function signature for init must be:</p>
535<pre class="literal-block">
536void init(void);
537</pre>
538</li>
539<li><p class="first">The function <strong>root</strong> is a special function for graphics.  This function
540will be called when a script must redraw its contents.  No
541assumptions should be made as to when this function will be
542called.  It will only be called if the script is bound as a graphics root.
543Calls to this function will be synchronized with data updates and
544other invocations from Java.  Thus the script will not change due
545to external influence in the middle of running <strong>root</strong>.  The return value
546indicates to the runtime when the function should be called again to
547redraw in the future.  A return value of 0 indicates that no
548redraw is necessary until something changes on the Java side.  Any
549positive integer indicates a time in milliseconds that the runtime should
550wait before calling root again to render another frame.  The function
551signature for a graphics root functions is as follows:</p>
552<pre class="literal-block">
553int root(void);
554</pre>
555</li>
556<li><p class="first">It is also possible to create a purely compute-based <strong>root</strong> function.
557Such a function has the following signature:</p>
558<pre class="literal-block">
559void root(const T1 *in, T2 *out, const T3 *usrData, uint32_t x, uint32_t y);
560</pre>
561<p>T1, T2, and T3 represent any supported Renderscript type.  Any parameters
562above can be omitted, although at least one of in/out must be present.
563If both in and out are present, root must only be invoked with types of
564the same exact dimensionality (i.e. matching X and Y values for dimension).
565This root function is accessible through the Renderscript language
566construct <strong>forEach</strong>.  We also reflect a Java version to access this
567function as <strong>forEach_root</strong> (for API levels of 14+).  An example of this
568can be seen in the Android SDK sample for HelloCompute.</p>
569</li>
570<li><p class="first">The function <strong>.rs.dtor</strong> is a function that is sometimes generated by
571llvm-rs-cc.  This function cleans up any global variable that contains
572(or is) a reference counted Renderscript object type (such as an
573rs_allocation, rs_font, or rs_script).  This function will be invoked
574implicitly by the Renderscript runtime during script teardown.</p>
575</li>
576</ul>
577</li>
578<li><p class="first">In terms of a script's global data, global variables can be written
579from Java.  The Java instance will cache the value or object set and
580provide return methods to retrieve this value.  If a script updates
581the value, this update will not propagate back to the Java class.
582Initializers, if present, will also initialize the cached Java value.
583This provides a convenient way to declare constants within a script and
584make them accessible to the Java runtime.  If the script declares a
585variable const, only the get methods will be generated.</p>
586<p>Globals within a script are considered local to the script.  They
587cannot be accessed by other scripts and are in effect always 'static'
588in the traditional C sense.  Static here is used to control if
589accessors are generated.  Static continues to mean <em>not
590externally visible</em> and thus prevents the generation of
591accessors.  Globals are persistent across invocations of a script and
592thus may be used to hold data from run to run.</p>
593<p>Globals of two types may be reflected into the Java class.  The first
594type is basic non-pointer types.  Types defined in rs_types.rsh may also be
595used.  For the non-pointer class, get and set methods are generated for
596Java.  Globals of single pointer types behave differently.  These may
597use more complex types.  Simple structures composed of the types in
598rs_types.rsh may also be used.  These globals generate bind points in
599Java.  If the type is a structure they also generate an appropriate
600<strong>Field</strong> class that is used to pack and unpack the contents of the
601structure.  Binding an allocation in Java effectively sets the
602pointer in the script.  Bind points marked const indicate to the
603runtime that the script will not modify the contents of an allocation.
604This may allow the runtime to make more effective use of threads.</p>
605</li>
606</ul>
607</div>
608<div class="section" id="vector-types">
609<h1>5. Vector Types</h1>
610<p>Vector types such as float2, float4, and uint4 are included to support
611vector processing in environments where the processors provide vector
612instructions.</p>
613<p>On non-vector systems the same code will continue to run but without
614the performance advantage.  Function overloading is also supported.
615This allows the runtime to support vector version of the basic math
616routines without the need for special naming.  For instance,</p>
617<ul class="simple">
618<li><em>float sin(float);</em></li>
619<li><em>float2 sin(float2);</em></li>
620<li><em>float3 sin(float3);</em></li>
621<li><em>float4 sin(float4);</em></li>
622</ul>
623</div>
624</div>
625</body>
626</html>
627

README.rst

1==============================================
2llvm-rs-cc: Compiler for Renderscript language
3==============================================
4
5
6Introduction
7------------
8
9llvm-rs-cc compiles a program in the Renderscript language to generate the
10following files:
11
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
21Note that although Renderscript is C99-like, we enhance it with several
22distinct, effective features for Android programming. We will use
23some examples to illustrate these features.
24
25llvm-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.
28
29llvm-rs-cc is a driver on top of libslang. The architecture of
30libslang 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
51  This option *-d* sets the directory for writing dependence information.
52
53* *-MD*
54
55  Note that *-MD* will tell llvm-rs-cc to output dependence information.
56
57* *-a $(EXTRA_TARGETS)*
58
59  Specifies additional target dependencies.
60
61Example Command
62---------------
63
64First::
65
66  $ cd <Android_Root_Directory>
67
68Using frameworks/base/tests/RenderScriptTests/Fountain as a simple app in both
69Java and Renderscript, we can find the following command line in the build
70log::
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
96fountain.rs is in the Renderscript language, which is based on the standard
97C99. 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
108  To do that, a Renderscript programmer should specify the package name, so
109  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
116  In ScriptC_fountain.java, we have::
117
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
132llvm-rs-cc automatically exports the "externalizable and defined" functions and
133variables to Android's Java side. That is, scripts are accessible from
134Java.
135
136For instance, for::
137
138  int foo = 0;
139
140In ScriptC_fountain.java, llvm-rs-cc will reflect the following methods::
141
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
150to set the data within a script and call its functions.
151
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
180struct. In this case, llvm-rs-cc will reflect two files,
181ScriptC_fountain.java and ScriptField_Point.java.
182
183Note 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.
186
187For the generated Java files, using ScriptC_fountain.java as an
188example we also have::
189
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
195methods in ScriptField_Point.java.
196
197After binding, you can access the object with this method::
198
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
2374. Summary of the Java Reflection above
238---------------------------------------
239
240This section summarizes the high-level design of Renderscript's reflection.
241
242* In terms of a script's global functions, they can be called from Java.
243  These calls operate asynchronously and no assumptions should be made
244  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:
249
250  * The function **init** (if present) will be called once after the script
251    is loaded.  This is useful to initialize data or anything else the
252    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::
255
256      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
260    assumptions should be made as to when this function will be
261    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
263    other invocations from Java.  Thus the script will not change due
264    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
266    redraw in the future.  A return value of 0 indicates that no
267    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::
271
272      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
296  provide return methods to retrieve this value.  If a script updates
297  the value, this update will not propagate back to the Java class.
298  Initializers, if present, will also initialize the cached Java value.
299  This provides a convenient way to declare constants within a script and
300  make them accessible to the Java runtime.  If the script declares a
301  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'
305  in the traditional C sense.  Static here is used to control if
306  accessors are generated.  Static continues to mean *not
307  externally visible* and thus prevents the generation of
308  accessors.  Globals are persistent across invocations of a script and
309  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
312  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
314  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
317  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
320  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
341* *float3 sin(float3);*
342
343* *float4 sin(float4);*
344