STDLC(3)              Standard Compute Layer (CL) Manual              STDLC(3)



NAME
       stdcl - standard compute layer (CL) library functions

SYNOPSIS
       #include <stdcl.h>

       CONTEXT* stddev;
       CONTEXT* stdcpu;
       CONTEXT* stdgpu;
       CONTEXT* stdrpu;

       Link with -lstdcl.

DESCRIPTION
       The  standard  compute layer (CL) library (libstdcl) provides a simpli-
       fied interface to OpenCL designed to support the most typical use-cases
       in  a  style  inspired by familiar and traditional UNIX APIs for C pro-
       gramming.

       libstdcl provides managed OpenCL contexts  identified  with  a  context
       pointer  that is generally provided as an argument to library functions
       that transparently manage OpenCL constructs such as contexts,  devices,
       memory, kernels and events in a manner that simplifies their use.

       Default Contexts

       libstdcl  provides  several default contexts similar to the default I/O
       streams provided by stdio.  the following  default  contexts  are  pro-
       vided:

       stddev All devices for a given platform supported by the OpenCL API.

       stdcpu All  multi-core CPU processors for a given platform supported by
              the OpenCL API.

       stdgpu All many-core GPU processors for a given platform  supported  by
              the OpenCL API.

       stdrpu All  reconfigurable processors for a given platform supported by
              the OpenCL API.

       Dynamic CL Program Loader

       libstdcl provides a convenient interface  for  dynamically  loading  CL
       programs  and  accessing  CL  kernels.   Using the tool clld CL program
       source and binary files can be embedded  within  special  ELF  sections
       linked  against  other  object files on the host platform to generate a
       single executable.  The set of functions clopen(),  clsym(),  clclose()
       provide  a  convenient interface capable of dynamically loading CL pro-
       grams embedded within the executable as well as from an external  file.
       CL prorgams.

       Memory Management

       libstdcl provides functions for allocating and managing memory that may
       be shared between the host and CL co-processor devices.  Memory may  be
       allocated  with  clmalloc() and used transparently as the global memory
       for kernel execution on a CL device.   The  programmer  uses  a  single
       pointer  representing  the allocated memory which may be re-attached to
       various CL contexts using clmattach() and clmdetach().  Memory  consis-
       tency can be maintained using the clmsync() function which synchronizes
       memory between host and CL co-processor device.

       Kernel Execution

       libstdcl provides simplified interfaces for setting up the  index-space
       and arguments for kernel execution.  Executing a kernel on a particular
       CL co-processor device is supported using clfork() which allows  block-
       ing and non-blocking execution behavior.

       Management of Asynchronous Operations

       libstdcl  provides  event  management per device within each context to
       simplify the management of asynchronous multi-device  operations.   The
       function clwait() can be used to block on selected events within one of
       several per device event lists managed transparently.

EXAMPLE
       The following example shows a very simple program for  calculating  the
       outer product of two vectors using a GPU:

           #include <stdcl.h>

           int main() {

                int n = 1024;

                cl_float* aa = (cl_float*)clmalloc(stdgpu,n,0);
                cl_float* bb = (cl_float*)clmalloc(stdgpu,n,0);
                cl_float* cc = (cl_float*)clmalloc(stdgpu,n,0);

                /* initialize aa and bb */

                void* h = clopen(stdgpu,"outer_prod_kern.cl",0);
                cl_kernel krn = clsym(stdgpu,h,"outer_prod_kern");

                clndrange_t ndr = clndrange_init1d(0,n,4);

                clarg_set(krn,0,n);
                clarg_set_global(krn,1,aa);
                clarg_set_global(krn,2,bb);
                clarg_set_global(krn,3,cc);

                clfork(stdgpu,0,krn,ndr,CL_EVENT_NOWAIT);

                clmsync(stdgpu,0,cc,CL_EVENT_NOWAIT);

                clwait(stdgpu,0,CL_ALL_EVENTS|CL_EVENT_RELEASE);

                clclose(h);

                clfree(aa);
                clfree(bb);
                clfree(cc);

           }

ENVIRONMENT
       Executables  that  use the libstdcl library are affected by environment
       variables that control the behavior of the API.  The environment  vari-
       ables  STDDEV,  STDCPU, STDGPU, STDRPU may be set to pass a string used
       to control the behavior of the respective default contexts when a  pro-
       gram  is executed.  Each string may contain one or more colon-separated
       clauses.

       As an example, the following would force the stdgpu context to use  the
       ATI Stream platform:

              setenv STDGPU platform_name="ATI STREAM"

           A context can be disabled by setting the respective envinoment variable to 0,
           for example, the following will disable the stddev context:

                  setenv STDDEV 0


       The allowed clauses are platform and context dependent.

AUTHOR
       Written by David Richie.

REPORTING BUGS
       Report bugs to <support@browndeertechnology.com>

COPYRIGHT
       Copyright  (C) 2009 Brown Deer Technology, LLC.  Licensed under the GNU
       Lesser General Public License version 3.  There is NO WARRANTY  to  the
       extent permitted by law.

SEE ALSO
       clld(1),   clopen(3),  clsym(3),  clclose(3),  clmalloc(3),  clmsync(),
       clfork(3), clwait(3)



     "libstdcl-0.7"               2009-11-10                          STDLC(3)