starpu-max/doc/starpu.texi

\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename starpu.info
@settitle StarPU
@c %**end of header

@setchapternewpage odd

@titlepage
@title StarPU
@page
@vskip 0pt plus 1filll
@comment For the @value{version-GCC} Version*
@end titlepage

@summarycontents
@contents
@page

@node Top
@top Preface
@cindex Preface

This manual documents the usage of StarPU


@comment
@comment  When you add a new menu item, please keep the right hand
@comment  aligned to the same column.  Do not use tabs.  This provides
@comment  better formatting.
@comment
@menu
* Introduction::       A basic introduction to using StarPU.
* Installing StarPU::  How to configure, build and install StarPU
* StarPU API::         The API to use StarPU
* Basic Examples::     Basic examples of the use of StarPU
@end menu

@c ---------------------------------------------------------------------
@c Introduction to StarPU
@c ---------------------------------------------------------------------

@node Introduction
@chapter Introduction to StarPU

@section Motivation

@c DSM

@c explain the notion of codelet and task (ie. g(A, B)

@c ---------------------------------------------------------------------
@c Installing StarPU
@c ---------------------------------------------------------------------

@node Installing StarPU
@chapter Installing StarPU

StarPU can be built and install by the standard means of the GNU autotools. The
following chapter is intended to briefly remind how these tools can be used to
install StarPU.

@section Configuring StarPU

@subsection Generating Makefiles and configuration scripts

This step is not necessary when using the tarball releases of StarPU.  If you
are using the source code from the svn repository, you first need to generate
the configure scripts and the Makefiles.

@example
$ autoreconf -i
@end example

@subsection Configuring StarPU

@example
$ configure
@end example

@c TODO enumerate the list of interesting options

@section Building and Installing StarPU

@subsection Building

@example
$ make
@end example

@subsection Sanity Checks

In order to make sure that StarPU is working properly on the system, it is also
possible to run a test suite.

@example
$ make check
@end example

@subsection Installing

In order to install StarPU at the location that was specified during
configuration:

@example
$ make install
@end example

@subsection pkg-config configuration

It is possible that compiling and linking an application against StarPU
requires to use specific flags or libraries (for instance @code{CUDA} or
@code{libspe2}). Therefore, it is possible to use the @code{pkg-config} tool.

If StarPU was not installed at some standard location, the path of StarPU's
library must be specified in the @code{PKG_CONFIG_PATH} environment variable so
that @code{pkg-config} can find it. So if StarPU was installed in
@code{$(prefix_dir)}:

@example
$ PKG_CONFIG_PATH = @{PKG_CONFIG_PATH@}:$(prefix_dir)/lib/
@end example

The flags required to compiled or linked against StarPU are then
accessible with the following commands:

@example
$ pkg-config --cflags libstarpu  # options for the compiler
$ pkg-config --libs libstarpu    # options for the linker
@end example

@c ---------------------------------------------------------------------
@c StarPU API
@c ---------------------------------------------------------------------

@node StarPU API
@chapter StarPU API

@menu
* Initialization and Termination::       Initialization and Termination methods
* Data Library::                         Methods to manipulate data
* Codelets and Tasks::                   Methods to construct tasks
@end menu

@node Initialization and Termination
@section Initialization and Termination

@menu
* starpu_init::            Initialize StarPU
* starpu_shutdown::        Terminate StarPU
@end menu

@node starpu_init
@subsection @code{starpu_init} -- Initialize StarPU
@table @asis

@item @emph{Description}:
This is StarPU initialization method, which must be called prior to any other
StarPU call.  It is possible to specify StarPU's configuration (eg. scheduling
policy, number of cores, ...) by passing a non-null argument. Default
configuration is used if the passed argument is @code{NULL}.

@item @emph{Prototype}:
@code{void starpu_init(struct starpu_conf *conf);}

@end table


@node starpu_shutdown
@subsection @code{starpu_shutdown} -- Terminate StarPU
@table @asis

@item @emph{Description}:
This is StarPU termination method. It must be called at the end of the
application: statistics and other post-mortem debugging information are not
garanteed to be available until this method has been called.

@item @emph{Prototype}:
@code{void starpu_shutdown(void);}

@end table


@node Data Library
@section Data Library

@node Codelets and Tasks
@section Codelets and Tasks

@c TODO
@node starpu_task_create

@c Callbacks : what can we put in callbacks ?

@section Extensions

@subsection CUDA extensions

@subsection Cell extensions

@c ---------------------------------------------------------------------
@c Basic Examples
@c ---------------------------------------------------------------------

@node Basic Examples
@chapter Basic Examples

@section Compiling and linking options

The Makefile could for instance contain the following lines to define which
options must be given to the compiler and to the linker:

@example
@cartouche
CFLAGS+=$$(pkg-config --cflags libstarpu)
LIBS+=$$(pkg-config --libs libstarpu)
@end cartouche
@end example

@section Hello World

In this section, we show how to implement a simple program that submits a task to StarPU.

@subsection Required Headers

The @code{starpu.h} header should be included in any code using StarPU.

@example 
@cartouche
#include <starpu.h>
@end cartouche
@end example


@subsection Defining a Codelet

@example
@cartouche
void cpu_func(starpu_data_interface_t *buffers, void *func_arg)
@{
    float *array = func_arg;

    printf("Hello world (array = @{%f, %f@} )\n", array[0], array[1]);
@}

starpu_codelet cl =
@{
    .where = CORE,
    .core_func = cpu_func,
    .nbuffers = 0
@};
@end cartouche
@end example

A codelet is a structure that represents a computational kernel. Such a codelet
may contain an implementation of the same kernel on different architectures
(eg. CUDA, Cell's SPU, x86, ...).

The ''@code{.nbuffers}'' field specifies the number of data buffers that are
manipulated by the codelet: here the codelet does not access or modify any data
that is controlled by our data management library. Note that the argument
passed to the codelet (the ''@code{.cl_arg}'' field of the @code{starpu_task}
structure) does not count as a buffer since it is not managed by our data
management library. 

@c TODO need a crossref to the proper description of "where" see bla for more ...
We create a codelet which may only be executed on the CPUs. The ''@code{.where}''
field is a bitmask that defines where the codelet may be executed. Here, the
@code{CORE} value means that only CPUs can execute this codelet
(@pxref{Codelets and Tasks} for more details on that field).
When a CPU core executes a codelet, it calls the @code{.core_func} function,
which @emph{must} have the following prototype:

@code{void (*core_func)(starpu_data_interface_t *, void *)}

In this example, we can ignore the first argument of this function gives a
description of the input and output buffers (eg. the size and the location of
the matrices). The second argument is a pointer to a buffer passed as an
argument to the codelet by the means of the ''@code{.cl_arg}'' field of the
@code{starpu_task} structure. Be aware that this may be a pointer to a
@emph{copy} of the actual buffer, and not the pointer given by the programmer:
if the codelet modifies this buffer, there is no garantee that the initial
buffer will be modified as well: this for instance implies that the buffer
cannot be used as a synchronization medium.

@subsection Submitting a Task

@example
@cartouche
void callback_func(void *callback_arg)
@{
    printf("Callback function (arg %x)\n", callback_arg);
@}

int main(int argc, char **argv)
@{
    /* initialize StarPU */
    starpu_init(NULL);

    struct starpu_task *task = starpu_task_create();

    task->cl = &cl;
    
    float array[2] = @{1.0f, -1.0f@};
    task->cl_arg = &array;
    task->cl_arg_size = 2*sizeof(float);

    task->callback_func = callback_func;
    task->callback_arg = 0x42;

    /* starpu_submit_task will be a blocking call */
    task->synchronous = 1;

    /* submit the task to StarPU */
    starpu_submit_task(task);

    /* terminate StarPU */
    starpu_shutdown();

    return 0;
@}
@end cartouche
@end example

Before submitting any tasks to StarPU, @code{starpu_init} must be called. The
@code{NULL} arguments specifies that we use default configuration. Tasks cannot
be submitted after the termination of StarPU by a call to
@code{starpu_shutdown}.

In the example above, a task structure is allocated by a call to
@code{starpu_task_create}. This function only allocate and fills the
corresponding structure with the default settings (@pxref{starpu_task_create}),
but it does not submit the task to StarPU.

@c not really clear ;)
The ''@code{.cl}'' field is a pointer to the codelet which the task will
execute: in other words, the codelet structure describes which computational
kernel should be offloaded on the different architectures, and the task
structure is a wrapper containing a codelet and the piece of data on which the
codelet should operate.

The optional ''@code{.cl_arg}'' field is a pointer to a buffer (of size
@code{.cl_arg_size}) with some parameters for some parameters for the kernel
described by the codelet. For instance, if a codelet implements a computational
kernel that multiplies its input vector by a constant, the constant could be
specified by the means of this buffer.

Once a task has been executed, an optional callback function can be called.
While the computational kernel could be offloaded on various architectures, the
callback function is always executed on a CPU. The ''@code{.callback_arg}''
pointer is passed as an argument of the callback. The prototype of a callback
function must be:
@example
void (*callback_function)(void *);
@end example

If the @code{.synchronous} field is non-null, task submission will be
synchronous: the @code{starpu_submit_task} function will not return until the
task was executed. Note that the @code{starpu_shutdown} method does not
guaranty that asynchronous tasks have been executed before it returns.

@bye