proxyFuncs.Rdb

<?xml version="1.0"?>
<article xmlns:r="http://www.r-project.org"
         xmlns:xi="http://www.w3.org/2003/XInclude"
	 xmlns:c="http://www.C.org"
	 xmlns:omg="http://www.omegahat.org"
	 xmlns:sh="http://www.shell.org">

<articleinfo>

<title></title>

<author><firstname>Duncan</firstname><surname>Temple Lang</surname>
  <affiliation><orgname>University of California at Davis</orgname>
               <orgdiv>Department of Statistics</orgdiv>
  </affiliation>
</author>
</articleinfo>

<section>
<title></title>
<r:init>
library(RLLVMCompile)
</r:init>
<para>

Consider the task of interfacing <r/> to a library such as libcuda and
libcudart.  We can do this manually by writing <c/> routines and <r/>
functions for each routine of interest in the library.  We also have
to write C and R code to access, create, query and modify the data
structures, i.e. <c:struct/> types.  Alternatively, we can use a
dynamic interface such as <r:pkg>rdyncall</r:pkg> and
<omg:pkg>Rffi</omg:pkg>. This avoids writing wrapper routines.
Instead, we need to be able describe each of the routines and data
structures.  With these descriptions, we can access the routines and
fields.  In this document, we will explore a different approach that
embraces the dynamic approach, but avoids using
<r:pkg>rdyncall</r:pkg> or <omg:pkg>Rffi</omg:pkg>.
Instead, we will use the <omg:func>Rllvm</omg:func> 
and <omg:pkg>RLLVMCompile</omg:pkg> packages
to dynamically generate machine code to invoke
native routines.
</para>
<para>
We'll start with a simple example.
Suppose there already exists a <c/> routine named
<c:func>fib</c:func> and it is available via a dynamic library
(DSO/DSL).
We can load it into <r/> with, say, 
<r:code>
dyn.load("fib.so")
</r:code>
and access the <c/> routine as <c:func>fib</c:func>.
</para>
<para>
Now, let's think about an <r/> function that acts as a simple
proxy for this.
We'll call this <r:func>fib</r:func>.  We know that the input
type is an <r:var>Int32Type</r:var>.
We can write an <r/> function that interfaces to this with
<r:function eval="false"><![CDATA[
cat("XXXXXXX\n")
createProxy = 
function(name, returnType, types = list())
{
  mod = Module(name)
  
}
]]></r:function>

<invisible>
<r:code eval="false">source("createProxy.R")</r:code>
library(RLLVMCompile)
</invisible>
</para>
<para>
How do we get the descriptions of the native routines?  Of course, we
can do this by hand, i.e. by reading the header files.  Alternatively,
we can do this programmatically via a number of facilities.  gccxml is
a extension to the GNU compiler that provides information about
routines and data structures.  The <r/> packages
<omg:pkg>RGCCTranslationUnit</omg:pkg> and
<omg:pkg>RCIndex</omg:pkg> provide alternative mechanisms to get
the information.  Given the description of the routines, we can generate
the code to invoke it.
In this way, the <omg:pkg>Rllvm</omg:pkg> package provides a 
simplification of the <omg:pkg>Rffi</omg:pkg> and <r:pkg>rdyncall</r:pkg>
mechanism. However, it is much more powerful as it allows us to generate
code for more general  situations, not just invoking existing routines.
In other words, we can compile <r/> code and other languages to native code.
</para>
<para>
The approach we use is quite simple, given the facilities in
the <omg:pkg>Rllvm</omg:pkg> and <omg:pkg>RLLVMCompile</omg:pkg> packages.
Essentially, we define a simple R function that is a direct proxy for the
native routine. It has the same parameters and the body merely calls
the native routine. In this sense, it is a true proxy function. 
For example, consider the simple <c/> routine declared as
<c:decl>int fib(int)</c:decl>.
The <r/> proxy is simply
<r:function><![CDATA[
rfib= 
function(n)
  fib(n)
]]></r:function>
The function <r:func>mkProxyFn</r:func> creates this proxy function for us.
We can then pass this to <r:func>compileFunction</r:func> to 
create the machine-level code to invoke the native routine.
We need to know the return type and the types of the parameters of
the native routine. Given these, we can make the <llvm/>
engine aware of this routine.
Then we can compile our proxy to invoke this.
</para>
<para>
We load the native code into  R with
<r:code>
dyn.load("fib.so")
</r:code>
Next we can compile the machine code for our proxy
<r:code>
fi = createProxy("fib", Int32Type, list(n = Int32Type))
</r:code>
We use the same name as the native routine.
The name of the argument(s) is not important.
</para>
<para>
We can now invoke this function/routine with 
<r:code>
.llvm(fi, 10)
</r:code>
</para>
</section>
<section>
<title>Programmatically Obtaining the Type Information</title>


<para>
We have show how we can create the proxy routine
using the type information.
The next step is to automate obtaining this type information.
We have several possible mechanisms.
We can nuse gcc-xml to dump information about C code into XML.
This is the approach <r:pkg>rdyncall</r:pkg> uses and provides.
I have two other approaches - <omg:pkg>RGCCTranslationUnit</omg:pkg>
and <omg:pkg>RCIndex</omg:pkg>.
</para>

<section r:eval="false">
<para>
To use <omg:pkg>RGCCTranslationUnit</omg:pkg>,
we have to compile our <c/> code to create a tu file.
We can do this with
<sh:code>
gcc -fdump-translation-unit -c fib.c -o /dev/null
</sh:code>
This creates <file>fib.c.001t.tu</file>.
We can then read this in <r/>
<r:code>
library(RGCCTranslationUnit)
tu = parseTU("fib.c.001t.tu")
</r:code>
<r:code>
r = getRoutines(tu)
rr = resolveType(r, tu)
</r:code>
<r:var>rr</r:var> is a list with just one element:
<r:code>
rr
<r:output><![CDATA[
$fib
[1] " int     fib (  int n  )"

attr(,"class")
[1] "ResolvedRoutineList"
]]></r:output>
</r:code>
</para>
<para>
This element contains information about the routine.
It is displayed here as a string, but in fact, is
much richer:
<r:code>
names(rr$fib)
<r:output><![CDATA[
[1] "parameters" "INDEX"      "name"       "node"       "returnType"
[6] "pure"       "virtual"   
]]></r:output>
</r:code>
Importantly, we have the return type and the parameters
and their types, e.g.
<r:code>
rr$fib$returnType
<r:output><![CDATA[
An object of class "intType"
Slot "name":
[1] "int"

Slot "alias":
character(0)

Slot "qualifiers":
character(0)

Slot "scope":
NULL
]]></r:output>
</r:code>
This is a simple integer type (as we expected from the <c/> code).
This corresponds to <r:var>Int32Type</r:var> in <omg:pkg>Rllvm</omg:pkg>.
(See types.cc in <dir>examples</dir> in the <omg:pkg>RGCCTranslationUnit</omg:pkg> package for others.)
</para>
<para>
We can define a function that maps a type description from the 
<omg:pkg>RGCCTranslationUnit</omg:pkg> package to an llvm type.
The basics of this are very simple, but there are lot of details to deal
with all the different sub-types.
<r:function><![CDATA[
library(Rllvm)
tuLLVMType =
function(type)
{
  if(is(type, "ArrayType"))
     return(arrayType(tuLLVMType(type@type), type@length))
  else if(is(type, "PointerType"))
     return(pointerType(tuLLVMType(type@type)))

  switch(class(type),
         intType = Int32Type,
         doubleType = DoubleType,
         shortUnsignedIntType = ,
         shortIntType = Int16Type,
         boolType = Int1Type,
         longUnsignedIntType = ,
         longIntType = Int32Type,
         charType = Int8Type
        )
}
]]></r:function>
This doesn't deal with extended/qualified types <c:type>long double</c:type>
but could be easily modified to do so.
</para>


<para>
We can then use this to get the types for the <c:func>fib</c:func> routine
and create our proxy function with
<r:code>
fun = createProxy("fib", tuLLVMType(rr$fib$returnType),
                   lapply(rr$fib$parameters, function(x) tuLLVMType(x$type)))
</r:code>
This is the same as we obtained above where we explicitly specified the types.
We can invoke the routine with 
<r:code>
.llvm(fun, 20)
</r:code>
</para>


<ignore>
<para>
See types.cc and types.R in RGCCTranslationUnit/examples/
<r:code eval="false">
sapply(rgvars, function(x) tuLLVMType(x@type))
</r:code>
</para>
</ignore>
</section>

</section>
<section>
<title>Using <omg:pkg>RCIndex</omg:pkg></title>

<para>
We'll now see how we can do the same thing with 
<omg:pkg>RCIndex</omg:pkg>.
We can start by obtaining the translation unit.
We could read it and traverse it in different ways.
However, we only want the descriptions of the routines, so we can 
use
<r:code>
library(RCIndex)
funs = getRoutines("fib.c")
</r:code>
We can specify flags for the compiler via the <r:arg>args</r:arg> parameter of <r:func>parseTU</r:func>.
</para>
<para>
This is slightly simpler using <omg:pkg>RCIndex</omg:pkg>
as we can do it entirely in <r/>.
However, we did have to install the clang libraries.
</para>
<note>
<para>
If we want to read the 
<r:code eval="false">
tu = parseTU("fib.c")
</r:code>
Then we can use <r:func>visitTU</r:func> to traverse the nodes.
</para>
</note>

<para>
<r:var>funs</r:var> is a <r:list/> and we can see the names of the functions
with 
<r:code>
names(funs)
<r:output><![CDATA[
[1] "fib"
]]></r:output>
f = funs$fib
</r:code>
This element is a <r:class>FunctionDecl</r:class> object.
This is currently an <s3/> class which is a list
with elements for the return type, parameters and the function definition
node.  These are all <r:class>CXCursor</r:class> objects. 
</para>
<para>
We can find the nature of the return type with
<r:code>
getTypeKind(f@returnType)
<r:output><![CDATA[
Int 
 17 
]]></r:output>
</r:code>
This is an enumerated type, with the name of the element giving us some
indication.
We can compare it the built-in values which are prefixed by <r:var>CXType_</r:var>,
e.g. <r:var>CXType_Int</r:var>.
</para>
<para>
We can also as many questions of the type, e.g. is it a constant, its size, etc.
For example,
<r:code>
getSizeOf(f@returnType)
</r:code>
yields 4.
</para>

<para>
We can also query the function's parameters:
<r:code>
sapply(f@params, getTypeKind)
</r:code>
</para>

<para>
We can now write our function that maps a CLang/<omg:pkg>RCIndex</omg:pkg> type 
to the corresponding LLVM type.
<r:function><![CDATA[
clang2LLVMType = 
function(type, kind = getTypeKind(type))
{
#    if(kind == CXType_Array
    switch(names(kind),
           Int = Int32Type,
           Double = DoubleType,
           shortUnsignedIntType = ,
           shortIntType = Int16Type,
           Bool = Int1Type,
           ULong = ,
           Long = Int32Type,
           SChar = Int8Type
          )
}
]]></r:function>
</para>

</section>
</article>