Home | History | Annotate | only in /frameworks/compile/slang
Up to higher level directory
NameDateSize
Android.mk10-Oct-20126.6K
BitWriter_2_9/10-Oct-2012
BitWriter_2_9_func/10-Oct-2012
lit-tests/10-Oct-2012
llvm-rs-cc.cpp10-Oct-201217.3K
llvm-rs-link.cpp10-Oct-20128.7K
MODULE_LICENSE_APACHE210-Oct-20120
NOTICE10-Oct-201216.7K
os_sep.h10-Oct-20121.1K
README.html10-Oct-201219.8K
README.rst10-Oct-201212.2K
RSCCOptions.td10-Oct-20125K
rslib.bc10-Oct-2012716
rslib.ll10-Oct-20122.6K
rsScriptC_Lib.bc10-Oct-2012464
rsScriptC_Lib.rs10-Oct-201241
RSSpec.mk10-Oct-20122.1K
slang-data.c10-Oct-20122.6K
slang.cpp10-Oct-201213.5K
slang.h10-Oct-20126.3K
slang_assert.h10-Oct-20121.5K
slang_backend.cpp10-Oct-201211.9K
slang_backend.h10-Oct-20124.5K
slang_diagnostic_buffer.cpp10-Oct-20122.2K
slang_diagnostic_buffer.h10-Oct-20121.7K
slang_pragma_recorder.cpp10-Oct-20123.6K
slang_pragma_recorder.h10-Oct-20121.6K
slang_rs.cpp10-Oct-201212.6K
slang_rs.h10-Oct-20125.2K
slang_rs_ast_replace.cpp10-Oct-20124.1K
slang_rs_ast_replace.h10-Oct-20122.4K
slang_rs_backend.cpp10-Oct-201216.8K
slang_rs_backend.h10-Oct-20122.4K
slang_rs_context.cpp10-Oct-20129.6K
slang_rs_context.h10-Oct-20126.8K
slang_rs_export_element.cpp10-Oct-20125.6K
slang_rs_export_element.h10-Oct-20121.9K
slang_rs_export_foreach.cpp10-Oct-201214.7K
slang_rs_export_foreach.h10-Oct-20125K
slang_rs_export_func.cpp10-Oct-20125.4K
slang_rs_export_func.h10-Oct-20123.2K
slang_rs_export_type.cpp10-Oct-201251.5K
slang_rs_export_type.h10-Oct-201217.9K
slang_rs_export_var.cpp10-Oct-20124K
slang_rs_export_var.h10-Oct-20122K
slang_rs_exportable.cpp10-Oct-2012935
slang_rs_exportable.h10-Oct-20121.7K
slang_rs_metadata.h10-Oct-20121.2K
slang_rs_metadata_spec.h10-Oct-20122.7K
slang_rs_metadata_spec_encoder.cpp10-Oct-201215.2K
slang_rs_object_ref_count.cpp10-Oct-201255K
slang_rs_object_ref_count.h10-Oct-20124.9K
slang_rs_pragma_handler.cpp10-Oct-20129.7K
slang_rs_pragma_handler.h10-Oct-20122.7K
slang_rs_reflect_utils.cpp10-Oct-20128K
slang_rs_reflect_utils.h10-Oct-20123.1K
slang_rs_reflection.cpp10-Oct-201272.3K
slang_rs_reflection.h10-Oct-201211.4K
slang_rs_reflection_base.cpp10-Oct-20124.7K
slang_rs_reflection_base.h10-Oct-20122K
slang_rs_reflection_cpp.cpp10-Oct-20128.9K
slang_rs_reflection_cpp.h10-Oct-20121.4K
slang_rs_spec_table.cpp10-Oct-201214.3K
slang_rs_type_spec.h10-Oct-20128.9K
slang_utils.cpp10-Oct-20121,011
slang_utils.h10-Oct-20121K
slang_version.h10-Oct-20121.6K
SlangData.mk10-Oct-20121.5K
slangdata.py10-Oct-20122.1K
tests/10-Oct-2012

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 (a] 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 
     15 Default cascading style sheet for the HTML output of Docutils.
     16 
     17 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
     18 customize 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 
     25 table.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 
     40 a.toc-backref {
     41   text-decoration: none ;
     42   color: black }
     43 
     44 blockquote.epigraph {
     45   margin: 2em 5em ; }
     46 
     47 dl.docutils dd {
     48   margin-bottom: 0.5em }
     49 
     50 /* Uncomment (and remove this text!) to get bold-faced definition list terms
     51 dl.docutils dt {
     52   font-weight: bold }
     53 */
     54 
     55 div.abstract {
     56   margin: 2em 5em }
     57 
     58 div.abstract p.topic-title {
     59   font-weight: bold ;
     60   text-align: center }
     61 
     62 div.admonition, div.attention, div.caution, div.danger, div.error,
     63 div.hint, div.important, div.note, div.tip, div.warning {
     64   margin: 2em ;
     65   border: medium outset ;
     66   padding: 1em }
     67 
     68 div.admonition p.admonition-title, div.hint p.admonition-title,
     69 div.important p.admonition-title, div.note p.admonition-title,
     70 div.tip p.admonition-title {
     71   font-weight: bold ;
     72   font-family: sans-serif }
     73 
     74 div.attention p.admonition-title, div.caution p.admonition-title,
     75 div.danger p.admonition-title, div.error p.admonition-title,
     76 div.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.
     83 div.compound .compound-first, div.compound .compound-middle {
     84   margin-bottom: 0.5em }
     85 
     86 div.compound .compound-last, div.compound .compound-middle {
     87   margin-top: 0.5em }
     88 */
     89 
     90 div.dedication {
     91   margin: 2em 5em ;
     92   text-align: center ;
     93   font-style: italic }
     94 
     95 div.dedication p.topic-title {
     96   font-weight: bold ;
     97   font-style: normal }
     98 
     99 div.figure {
    100   margin-left: 2em ;
    101   margin-right: 2em }
    102 
    103 div.footer, div.header {
    104   clear: both;
    105   font-size: smaller }
    106 
    107 div.line-block {
    108   display: block ;
    109   margin-top: 1em ;
    110   margin-bottom: 1em }
    111 
    112 div.line-block div.line-block {
    113   margin-top: 0 ;
    114   margin-bottom: 0 ;
    115   margin-left: 1.5em }
    116 
    117 div.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 
    126 div.sidebar p.rubric {
    127   font-family: sans-serif ;
    128   font-size: medium }
    129 
    130 div.system-messages {
    131   margin: 5em }
    132 
    133 div.system-messages h1 {
    134   color: red }
    135 
    136 div.system-message {
    137   border: medium outset ;
    138   padding: 1em }
    139 
    140 div.system-message p.system-message-title {
    141   color: red ;
    142   font-weight: bold }
    143 
    144 div.topic {
    145   margin: 2em }
    146 
    147 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
    148 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
    149   margin-top: 0.4em }
    150 
    151 h1.title {
    152   text-align: center }
    153 
    154 h2.subtitle {
    155   text-align: center }
    156 
    157 hr.docutils {
    158   width: 75% }
    159 
    160 img.align-left, .figure.align-left{
    161   clear: left ;
    162   float: left ;
    163   margin-right: 1em }
    164 
    165 img.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 */
    181 div.align-right {
    182   text-align: left }
    183 
    184 /* div.align-center * { */
    185 /*   text-align: left } */
    186 
    187 ol.simple, ul.simple {
    188   margin-bottom: 1em }
    189 
    190 ol.arabic {
    191   list-style: decimal }
    192 
    193 ol.loweralpha {
    194   list-style: lower-alpha }
    195 
    196 ol.upperalpha {
    197   list-style: upper-alpha }
    198 
    199 ol.lowerroman {
    200   list-style: lower-roman }
    201 
    202 ol.upperroman {
    203   list-style: upper-roman }
    204 
    205 p.attribution {
    206   text-align: right ;
    207   margin-left: 50% }
    208 
    209 p.caption {
    210   font-style: italic }
    211 
    212 p.credits {
    213   font-style: italic ;
    214   font-size: smaller }
    215 
    216 p.label {
    217   white-space: nowrap }
    218 
    219 p.rubric {
    220   font-weight: bold ;
    221   font-size: larger ;
    222   color: maroon ;
    223   text-align: center }
    224 
    225 p.sidebar-title {
    226   font-family: sans-serif ;
    227   font-weight: bold ;
    228   font-size: larger }
    229 
    230 p.sidebar-subtitle {
    231   font-family: sans-serif ;
    232   font-weight: bold }
    233 
    234 p.topic-title {
    235   font-weight: bold }
    236 
    237 pre.address {
    238   margin-bottom: 0 ;
    239   margin-top: 0 ;
    240   font: inherit }
    241 
    242 pre.literal-block, pre.doctest-block {
    243   margin-left: 2em ;
    244   margin-right: 2em }
    245 
    246 span.classifier {
    247   font-family: sans-serif ;
    248   font-style: oblique }
    249 
    250 span.classifier-delimiter {
    251   font-family: sans-serif ;
    252   font-weight: bold }
    253 
    254 span.interpreted {
    255   font-family: sans-serif }
    256 
    257 span.option {
    258   white-space: nowrap }
    259 
    260 span.pre {
    261   white-space: pre }
    262 
    263 span.problematic {
    264   color: red }
    265 
    266 span.section-subtitle {
    267   /* font-size relative to parent (h1..h6 element) */
    268   font-size: 80% }
    269 
    270 table.citation {
    271   border-left: solid 1px gray;
    272   margin-left: 1px }
    273 
    274 table.docinfo {
    275   margin: 2em 4em }
    276 
    277 table.docutils {
    278   margin-top: 0.5em ;
    279   margin-bottom: 0.5em }
    280 
    281 table.footnote {
    282   border-left: solid 1px black;
    283   margin-left: 1px }
    284 
    285 table.docutils td, table.docutils th,
    286 table.docinfo td, table.docinfo th {
    287   padding-left: 0.5em ;
    288   padding-right: 0.5em ;
    289   vertical-align: top }
    290 
    291 table.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 
    297 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
    298 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
    299   font-size: 100% }
    300 
    301 ul.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
    313 following files:</p>
    314 <ul class="simple">
    315 <li>Bitcode file. Note that the bitcode here denotes the LLVM (Low-Level
    316 Virtual Machine) bitcode representation, which will be consumed on
    317 an Android device by libbcc (in
    318 platform/frameworks/compile/libbcc.git) to generate device-specific
    319 executables.</li>
    320 <li>Reflected APIs for Java. As a result, Android's Java developers can
    321 invoke those APIs from their code.</li>
    322 </ul>
    323 <p>Note that although Renderscript is C99-like, we enhance it with several
    324 distinct, effective features for Android programming. We will use
    325 some examples to illustrate these features.</p>
    326 <p>llvm-rs-cc is run on the host and performs many aggressive optimizations.
    327 As a result, libbcc on the device can be lightweight and focus on
    328 machine-dependent code generation for some input bitcode.</p>
    329 <p>llvm-rs-cc is a driver on top of libslang. The architecture of
    330 libslang and libbcc is depicted in the following figure:</p>
    331 <pre class="literal-block">
    332 libslang   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
    365 Java and Renderscript, we can find the following command line in the build
    366 log:</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
    389 C99. However, llvm-rs-cc goes beyond &quot;clang -std=c99&quot; and provides the
    390 following 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
    397 developers can invoke those APIs.</p>
    398 <p>To do that, a Renderscript programmer should specify the package name, so
    399 that llvm-rs-cc knows the package expression and hence the directory
    400 for 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">
    407 package 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
    414 version 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
    421 variables to Android's Java side. That is, scripts are accessible from
    422 Java.</p>
    423 <p>For instance, for:</p>
    424 <pre class="literal-block">
    425 int foo = 0;
    426 </pre>
    427 <p>In ScriptC_fountain.java, llvm-rs-cc will reflect the following methods:</p>
    428 <pre class="literal-block">
    429 void set_foo(int v)...
    430 
    431 int get_foo()...
    432 </pre>
    433 <p>This access takes the form of generated classes which provide access
    434 to the functions and global variables within a script. In summary,
    435 global variables and functions within a script that are not declared
    436 static will generate get, set, or invoke methods.  This provides a way
    437 to 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">
    440 void 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">
    446 void 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">
    456 typedef struct __attribute__((packed, aligned(4))) Point {
    457   float2 delta;
    458   float2 position;
    459   uchar4 color;
    460 } Point_t;
    461 
    462 Point_t *point;
    463 </pre>
    464 <p>llvm-rs-cc generates one ScriptField*.java file for each user-defined
    465 struct. In this case, llvm-rs-cc will reflect two files,
    466 ScriptC_fountain.java and ScriptField_Point.java.</p>
    467 <p>Note that when the type of an exportable variable is a structure, Renderscript
    468 developers should avoid using anonymous structs. This is because llvm-rs-cc
    469 uses 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
    471 example we also have:</p>
    472 <pre class="literal-block">
    473 void 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
    477 methods in ScriptField_Point.java.</p>
    478 <p>After binding, you can access the object with this method:</p>
    479 <pre class="literal-block">
    480 ScriptField_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.
    490 void 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.
    496 void set(Item i, int index, boolean copyNow)
    497 
    498 // The getter of Item array, which gets the *index*-th element
    499 // of byte array.
    500 Item get(int index)
    501 
    502 set_delta(int index, Float2 v, boolean copyNow)
    503 
    504 // The following is the individual setters and getters of
    505 // each field of a struct.
    506 public void set_delta(int index, Float2 v, boolean copyNow)
    507 public void set_position(int index, Float2 v, boolean copyNow)
    508 public void set_color(int index, Short4 v, boolean copyNow)
    509 public Float2 get_delta(int index)
    510 public Float2 get_position(int index)
    511 public Short4 get_color(int index)
    512 
    513 // Copying all Item array to byte array (i.e., memory allocation).
    514 void 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.
    523 These calls operate asynchronously and no assumptions should be made
    524 on whether a function called will have actually completed operation.  If it
    525 is necessary to wait for a function to complete, the Java application
    526 may call the runtime finish() method, which will wait for all the script
    527 threads to complete pending operations.  A few special functions can also
    528 exist:</p>
    529 <ul>
    530 <li><p class="first">The function <strong>init</strong> (if present) will be called once after the script
    531 is loaded.  This is useful to initialize data or anything else the
    532 script may need before it can be used.  The init function may not depend
    533 on globals initialized from Java as it will be called before these
    534 can be initialized. The function signature for init must be:</p>
    535 <pre class="literal-block">
    536 void init(void);
    537 </pre>
    538 </li>
    539 <li><p class="first">The function <strong>root</strong> is a special function for graphics.  This function
    540 will be called when a script must redraw its contents.  No
    541 assumptions should be made as to when this function will be
    542 called.  It will only be called if the script is bound as a graphics root.
    543 Calls to this function will be synchronized with data updates and
    544 other invocations from Java.  Thus the script will not change due
    545 to external influence in the middle of running <strong>root</strong>.  The return value
    546 indicates to the runtime when the function should be called again to
    547 redraw in the future.  A return value of 0 indicates that no
    548 redraw is necessary until something changes on the Java side.  Any
    549 positive integer indicates a time in milliseconds that the runtime should
    550 wait before calling root again to render another frame.  The function
    551 signature for a graphics root functions is as follows:</p>
    552 <pre class="literal-block">
    553 int 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.
    557 Such a function has the following signature:</p>
    558 <pre class="literal-block">
    559 void 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
    562 above can be omitted, although at least one of in/out must be present.
    563 If both in and out are present, root must only be invoked with types of
    564 the same exact dimensionality (i.e. matching X and Y values for dimension).
    565 This root function is accessible through the Renderscript language
    566 construct <strong>forEach</strong>.  We also reflect a Java version to access this
    567 function as <strong>forEach_root</strong> (for API levels of 14+).  An example of this
    568 can 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
    571 llvm-rs-cc.  This function cleans up any global variable that contains
    572 (or is) a reference counted Renderscript object type (such as an
    573 rs_allocation, rs_font, or rs_script).  This function will be invoked
    574 implicitly 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
    579 from Java.  The Java instance will cache the value or object set and
    580 provide return methods to retrieve this value.  If a script updates
    581 the value, this update will not propagate back to the Java class.
    582 Initializers, if present, will also initialize the cached Java value.
    583 This provides a convenient way to declare constants within a script and
    584 make them accessible to the Java runtime.  If the script declares a
    585 variable const, only the get methods will be generated.</p>
    586 <p>Globals within a script are considered local to the script.  They
    587 cannot be accessed by other scripts and are in effect always 'static'
    588 in the traditional C sense.  Static here is used to control if
    589 accessors are generated.  Static continues to mean <em>not
    590 externally visible</em> and thus prevents the generation of
    591 accessors.  Globals are persistent across invocations of a script and
    592 thus 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
    594 type is basic non-pointer types.  Types defined in rs_types.rsh may also be
    595 used.  For the non-pointer class, get and set methods are generated for
    596 Java.  Globals of single pointer types behave differently.  These may
    597 use more complex types.  Simple structures composed of the types in
    598 rs_types.rsh may also be used.  These globals generate bind points in
    599 Java.  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
    601 structure.  Binding an allocation in Java effectively sets the
    602 pointer in the script.  Bind points marked const indicate to the
    603 runtime that the script will not modify the contents of an allocation.
    604 This 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
    611 vector processing in environments where the processors provide vector
    612 instructions.</p>
    613 <p>On non-vector systems the same code will continue to run but without
    614 the performance advantage.  Function overloading is also supported.
    615 This allows the runtime to support vector version of the basic math
    616 routines 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 ==============================================
      2 llvm-rs-cc: Compiler for Renderscript language
      3 ==============================================
      4 
      5 
      6 Introduction
      7 ------------
      8 
      9 llvm-rs-cc compiles a program in the Renderscript language to generate the
     10 following 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 
     21 Note that although Renderscript is C99-like, we enhance it with several
     22 distinct, effective features for Android programming. We will use
     23 some examples to illustrate these features.
     24 
     25 llvm-rs-cc is run on the host and performs many aggressive optimizations.
     26 As a result, libbcc on the device can be lightweight and focus on
     27 machine-dependent code generation for some input bitcode.
     28 
     29 llvm-rs-cc is a driver on top of libslang. The architecture of
     30 libslang and libbcc is depicted in the following figure::
     31 
     32     libslang   libbcc
     33         |   \   |
     34         |    \  |
     35      clang     llvm
     36 
     37 
     38 Usage
     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 
     61 Example Command
     62 ---------------
     63 
     64 First::
     65 
     66   $ cd <Android_Root_Directory>
     67 
     68 Using frameworks/base/tests/RenderScriptTests/Fountain as a simple app in both
     69 Java and Renderscript, we can find the following command line in the build
     70 log::
     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 
     82 This command will generate:
     83 
     84 * **fountain.bc**
     85 
     86 * **ScriptC_fountain.java**
     87 
     88 * **ScriptField_Point.java**
     89 
     90 The **Script\*.java** files above will be documented below.
     91 
     92 
     93 Example Program: fountain.rs
     94 ----------------------------
     95 
     96 fountain.rs is in the Renderscript language, which is based on the standard
     97 C99. However, llvm-rs-cc goes beyond "clang -std=c99" and provides the
     98 following important features:
     99 
    100 1. 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 
    129 2. Basic Reflection: Export Variables and Functions
    130 ---------------------------------------------------
    131 
    132 llvm-rs-cc automatically exports the "externalizable and defined" functions and
    133 variables to Android's Java side. That is, scripts are accessible from
    134 Java.
    135 
    136 For instance, for::
    137 
    138   int foo = 0;
    139 
    140 In ScriptC_fountain.java, llvm-rs-cc will reflect the following methods::
    141 
    142   void set_foo(int v)...
    143 
    144   int get_foo()...
    145 
    146 This access takes the form of generated classes which provide access
    147 to the functions and global variables within a script. In summary,
    148 global variables and functions within a script that are not declared
    149 static will generate get, set, or invoke methods.  This provides a way
    150 to set the data within a script and call its functions.
    151 
    152 Take 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 
    158 llvm-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 
    166 3. Export User-Defined Structs
    167 ------------------------------
    168 
    169 In 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 
    179 llvm-rs-cc generates one ScriptField*.java file for each user-defined
    180 struct. In this case, llvm-rs-cc will reflect two files,
    181 ScriptC_fountain.java and ScriptField_Point.java.
    182 
    183 Note that when the type of an exportable variable is a structure, Renderscript
    184 developers should avoid using anonymous structs. This is because llvm-rs-cc
    185 uses the struct name to identify the file, instead of the typedef name.
    186 
    187 For the generated Java files, using ScriptC_fountain.java as an
    188 example we also have::
    189 
    190   void bind_point(ScriptField_Point v)
    191 
    192 This binds your object with the allocated memory.
    193 
    194 You can bind the struct(e.g., Point), using the setter and getter
    195 methods in ScriptField_Point.java.
    196 
    197 After binding, you can access the object with this method::
    198 
    199   ScriptField_Point get_point()
    200 
    201 In 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 
    237 4. Summary of the Java Reflection above
    238 ---------------------------------------
    239 
    240 This 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 
    325 5. Vector Types
    326 ---------------
    327 
    328 Vector types such as float2, float4, and uint4 are included to support
    329 vector processing in environments where the processors provide vector
    330 instructions.
    331 
    332 On non-vector systems the same code will continue to run but without
    333 the performance advantage.  Function overloading is also supported.
    334 This allows the runtime to support vector version of the basic math
    335 routines 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