[sac-user] English Documentation for Calling C from SAC

Salem Reyen salemreyen at yahoo.com
Mon Aug 9 18:09:14 CEST 2010

I first want to say thank you to Bodo and Clemens for providing me the additional details.
Since I currently don't have the access to AMD CPUs and AMD/Nividia GPGPU cards, I will try to provide the bindings for Intel MKL first.  Once AMD Fusion chips are available on the market, I can then work on the AMCL-GPU BLAS bindings for these chips if no one else has the time to do it. 
Best regards,

--- On Mon, 8/9/10, Clemens Grelck <c.grelck at uva.nl> wrote:

From: Clemens Grelck <c.grelck at uva.nl>
Subject: Re: [sac-user] English Documentation for Calling C from SAC
To: "sac user mailing list" <sac-user at sac-home.org>
Cc: "Salem Reyen" <salemreyen at yahoo.com>
Date: Monday, August 9, 2010, 6:08 AM

As a short add-on: As Bodo mentioned already, all array-typed values use
call-by-reference (including int[*], etc). In contrast, all scalar values
use call-by-value just as scalars in C.

The refcounting pragma only means that the SAC runtime exposes its internal
state, here the reference counter of a data object, to the external world.
AND, it makes the C code responsible for maintaining the reference counter
appropriately. This requires more insight into how SAC does reference counting.
If you do everything correctly, this gives you considerable power, if not,
you screw up (as always in life ;-) ).

Without the pragma, the SAC runtime does all manipulations of reference counter
states outside the called external function as they would happen by a normal
SAC function.

We're all curious to see your results,

Scholz, Sven-Bodo wrote:
> On 07/08/2010 01:56, "Salem Reyen" <salemreyen at yahoo.com> wrote:
>> Thank you so much for clear things up Stephan.  Since I may need to pass large
>> (GB) size matrices, how can I pass the parameters entirely by reference (for
>> saving memory) to a BLAS function?
> Yes, you can ! (tm)
> Per default, i.e. when you do NOT use a refcounting pragma, you do pass
> arrays per reference into a C function and out as well. For this to be safe
> the following conventions need to be observed by the C function:
> 1) arguments (arrays that are passed into the C function) are not modified
> in any form (no overwriting behind pointers and no memory ops such as
> freeing!!)
> 2) return values (arrays that are returned from your C function) are freshly
> allocated (no reuse of argument arrays [no aliasing])!
> HOWEVER, there is ONE important exception to this:
> IFF you use a linksign pragma to map a return position onto the SAME
> argument position you map an argument to
> eg   external int[4] foo( int[4] x);
>      #pragma linksign [1,1]
> (YES you can do this!)
> then this expects a function
> void foo( int *x);
> AND the runtime system of SaC allows you to modify the array behind x in
> place!
> The caveat of this is that the runtime system of SaC now ensures that by the
> time foo is called no other part of the program will ever inspect the
> argument again. This may(!) come at the expense of creating a copy!
> Example 1:
> int main()
> {
>   x = [1, 2, 3, 4];
>   val = foo( x);
>   return( val[0] );
> }
> Here, no copy of x will be generated.
> Example 2:
> int main()
> {
>   x = [1, 2, 3, 4];
>   val = foo( x);
>   return( val[0] + bar(x) );
> }
> Here, x is copied prior to the call to foo!
> So, you only should use this mapping trick if you want to modify only a
> small portion of data!
>> Thanks again for the big help,
>> Salem
>> P.S.  My understanding (and I could be wrong) is that SAC does not support
>> call by reference for calling a SAC function.  Then in actual C translation,
>> can SAC compiler clever enough to pass a read-only parameter by reference?
> Yes, all arguments are passed by reference. Copies are delayed to the moment
> when existing arrays are to be modified and further references exist
> elsewhere; very much in the same way as described for external functions
> above!
> HTH,
>   Bodo
> PS: if you create a SaC-binding for BLAS we'd be very interested in adding
> that to the stdlib! :-)
>> --- On Fri, 8/6/10, Herhut, Stephan <s.a.herhut at herts.ac.uk> wrote:
>>> From: Herhut, Stephan <s.a.herhut at herts.ac.uk>
>>> Subject: Re: [sac-user] English Documentation for Calling C from SAC
>>> To: "Salem Reyen" <salemreyen at yahoo.com>, "sac-user at sac-home.org"
>>> <sac-user at sac-home.org>
>>> Date: Friday, August 6, 2010, 10:23 AM
>>> Dear Salem,
>>> unfortunately no such documentation exists at the moment. There is a German
>>> master¹s thesis but that is outdated, too.
>>> We have not tried to use a BLAS C implementation in SAC. However, we have
>>> implemented some of the BLAS routines in SAC itself. It would be great to see
>>> how the two approaches compare. From our experience, if one compares single
>>> primitives, BLAS C implementations will almost always win as they have been
>>> tuned to the extreme. The power of an optimising compiler like sac2c only
>>> plays out as soon as multiple primitives are called in sequence. Only then
>>> additional optimisation potential arises.
>>> You can find our BLAS implementation in the standard library
>>> (modules/numerical/blas).
>>> Let my try to give you a brief intro into the C interface. This should
>>> suffice
>>> to integrate BLAS. As an example, consider the string module in the standard
>>> library (modules/structures/String.sac). In that file, the SAC function
>>> strtoi
>>> is defined as follows:
>>> external int, string strtoi(string S, int BASE);
>>> As the keyword external gives away, the function is not implemented in SAC
>>> but
>>> some other language. The compiler does not actually care what language that
>>> is, as long as it uses C calling conventions. To declare an external
>>> functions, one simply provides its signature prefixed with the keyword
>>> external.
>>> By just using the line above, the SAC compiler will make some assumptions on
>>> how to map the function to an actual C function. Firstly, it will map return
>>> values and arguments from the SAC side to arguments only on the C side. This
>>> is done to map the multiple return values of SAC to the C word. So, for the
>>> above example, the resulting C prototype would be
>>> void strtoi( int *res1, char **res2, char *S, int BASE);
>>> As you can see, the return values have been mapped into reference arguments.
>>> Often, this is not desired, like in the example of BLAS where the signatures
>>> are fixed. For those cases, we provide a means to remap SAC results/arguments
>>> to C results/arguments. For the above example, the following pragma is used
>>> in
>>> the standard library:
>>>     #pragma linksign [0,1,2,3]
>>> Pragmas in general directly follow an external function declaration. In this
>>> case, we use the linksign pragma. It maps each result/argument in SAC to the
>>> corresponding C result/arguments by means of a permutation vector. So, to
>>> achieve the desired C signature of strtoi, we want to have the first SAC
>>> result to be mapped to the C result and the arguments to be mapped in the
>>> same
>>> order. This is done using the permutation vector [0,1,2,3].  Position zero
>>> thereby represents the C function return value and numbers from one onwards
>>> are the function arguments. Using that vector, we get
>>> int strtoi( char **res1, char *S, int BASE)
>>> which is the standard C signature for that function. As you might guess, SAC
>>> by default uses the permutation vector [1,2,...].
>>> There are some more tuneable settings:
>>>     #pragma linkname " SACstrtoi"
>>> The linkname pragma allows to use a different C function name. Using the
>>> above
>>> pragma, we would get
>>> int SACstrtoi( char **res1, char *S, int BASE);
>>> Further two pragmas handle linking:
>>>     #pragma linkobj "src/String/strtoi.o"
>>> would instruct the compiler to link the given file whenever the function is
>>> required in a program. Similarly
>>>     #pragma linkobj "mylib"
>>> would make the compiler link the final executable against the specified
>>> library. The library is looked for in the search path configured in the
>>> sac2crc resource file. The default paths for system wide libraries are
>>> preconfigured. By editing or creating a .sac2crc file in your home directory
>>> and adding the following lines
>>> target default:
>>> EXTLIBPATH       := ³path1:path2:pathn²
>>> you can add additional paths to the search. A description of all valid field
>>> in that file can be found in its master copy in the setup subdirectory of the
>>> sac2c compiler.
>>> Lastly, there is a the
>>> #pragma refcounting [0,1,2]
>>> pragma. This configures whether parameters are passed by value or reference.
>>> Per default, all parameters are passed by value and thus are immutable. If
>>> you
>>> want to modify a parameter, you have to use a slightly more complex calling
>>> convention. I will cover that subject as demand arises.
>>> I hope this suffices to get you started. If you have any further questions,
>>> please feel free to reply to this list. Please use the list instead of
>>> contacting me directly as this will increase the audience and ensure a timely
>>> reply
>>> Regards
>>>   Stephan
>>> On 05/08/2010 04:24, "Salem Reyen" <salemreyen at yahoo.com> wrote:
>>>> Hi,
>>>>   Is there any documentation (in English) about how to call C functions from
>>>> a SAC Module?  More importantly, has anyone successfully tried to call
>>>> BLAS/LAPACK (eg, Intel MKL or AMD AML) from SAC?  Any help will be greatly
>>>> appreciated.
>>>> Salem
>>> --
>>> Stephan Herhut
>>> Centre for Computer Science and Informatics Research
>>> Science and Technology Research Institute
>>> University of Hertfordshire
> _______________________________________________
> sac-user mailing list
> sac-user at sac-home.org
> http://lists.sac-home.org/mailman/listinfo.cgi/sac-user

Dr Clemens Grelck                                     Science Park 107
Universitair Docent                                  1098 XG Amsterdam
Universiteit van Amsterdam
Instituut voor Informatica                       T +31 (0) 20 525 7578
                                                  F +31 (0) 20 525 7419
Office F2.46                                www.science.uva.nl/~grelck

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sac-home.org/pipermail/sac-user/attachments/20100809/23af9123/attachment-0002.html>

More information about the sac-user mailing list