StarPU Handbook
Loading...
Searching...
No Matches
7. StarPU Applications, setting up Your Own Code

7.1 Setting Flags for Compiling, Linking and Running Applications

StarPU provides a pkg-config executable to obtain relevant compiler and linker flags. As compiling and linking an application against StarPU may require to use specific flags or libraries (for instance CUDA or libspe2).

If StarPU was not installed at some standard location, the path of StarPU's library must be specified in the environment variable PKG_CONFIG_PATH to allow pkg-config to find it. For example, if StarPU was installed in $STARPU_PATH:

$ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$STARPU_PATH/lib/pkgconfig

The flags required to compile or link against StarPU are then accessible with the following commands:

$ pkg-config --cflags starpu-1.4  # options for the compiler
$ pkg-config --libs starpu-1.4    # options for the linker

Note that it is still possible to use the API provided in the version 1.0 of StarPU by calling pkg-config with the starpu-1.0 package. Similar packages are provided for starpumpi-1.0 and starpufft-1.0. It is also possible to use the API provided in the version 0.9 of StarPU by calling pkg-config with the libstarpu package. Similar packages are provided for libstarpumpi and libstarpufft.

Make sure that pkg-config –libs starpu-1.4 actually produces some output before going further: PKG_CONFIG_PATH has to point to the place where starpu-1.4.pc was installed during make install.

Also pass the option –static if the application is to be linked statically.

It is also necessary to set the environment variable LD_LIBRARY_PATH to locate dynamic libraries at runtime.

$ export LD_LIBRARY_PATH=$STARPU_PATH/lib:$LD_LIBRARY_PATH

And it is useful to get access to the StarPU tools:

$ export PATH=$PATH:$STARPU_PATH/bin

It is then useful to check that StarPU executes correctly and finds your hardware:

$ starpu_machine_display

If it does not, please check the output of lstopo from hwloc and report the issue to the hwloc project, since this is what StarPU uses to detect the hardware.


A tool is provided to help set all the environment variables needed by StarPU. Once StarPU is installed in a specific directory, calling the script bin/starpu_env will set in your current environment the variables STARPU_PATH, LD_LIBRARY_PATH, PKG_CONFIG_PATH, PATH and MANPATH.

$ source $STARPU_PATH/bin/starpu_env

7.2 Integrating StarPU in a Build System

7.2.1 Integrating StarPU in a Make Build System

When using a Makefile, the following lines can be added to set the options for the compiler and the linker:

CFLAGS          +=      $$(pkg-config --cflags starpu-1.4)
LDLIBS          +=      $$(pkg-config --libs starpu-1.4)

If you have a test-starpu.c file containing for instance:

#include <starpu.h>
#include <stdio.h>
int main(void)
{
int ret;
ret = starpu_init(NULL);
if (ret != 0)
{
return 1;
}
return 0;
}
void starpu_shutdown(void)
int starpu_init(struct starpu_conf *conf)
int starpu_worker_get_count_by_type(enum starpu_worker_archtype type)
@ STARPU_CUDA_WORKER
Definition starpu_worker.h:68
@ STARPU_CPU_WORKER
Definition starpu_worker.h:67
@ STARPU_OPENCL_WORKER
Definition starpu_worker.h:69

You can build it with make test-starpu and run it with ./test-starpu

7.2.2 Integrating StarPU in a CMake Build System

This section shows a minimal example integrating StarPU in an existing application's CMake build system.

Let's assume we want to build an executable from the following source code using CMake:

#include <starpu.h>
#include <stdio.h>
int main(void)
{
int ret;
ret = starpu_init(NULL);
if (ret != 0)
{
return 1;
}
return 0;
}

The CMakeLists.txt file below uses the Pkg-Config support from CMake to autodetect the StarPU installation and library dependences (such as libhwloc) provided that the PKG_CONFIG_PATH variable is set, and is sufficient to build a statically-linked executable. This example has been successfully tested with CMake 3.2, though it may work with earlier CMake 3.x versions.

{File CMakeLists.txt}
cmake_minimum_required (VERSION 3.2)
project (hello_starpu)
find_package(PkgConfig)
pkg_check_modules(STARPU REQUIRED starpu-1.4)
if (STARPU_FOUND)
include_directories (${STARPU_INCLUDE_DIRS})
link_directories (${STARPU_STATIC_LIBRARY_DIRS})
link_libraries (${STARPU_STATIC_LIBRARIES})
else (STARPU_FOUND)
message(FATAL_ERROR "StarPU not found")
endif()
add_executable(hello_starpu hello_starpu.c)

The following CMakeLists.txt implements an alternative, more complex strategy, still relying on Pkg-Config, but also taking into account additional flags. While more complete, this approach makes CMake's build types (Debug, Release, ...) unavailable because of the direct affectation to variable CMAKE_C_FLAGS. If both the full flags support and the build types support are needed, the CMakeLists.txt below may be altered to work with CMAKE_C_FLAGS_RELEASE, CMAKE_C_FLAGS_DEBUG, and others as needed. This example has been successfully tested with CMake 3.2, though it may work with earlier CMake 3.x versions.

{File CMakeLists.txt}
cmake_minimum_required (VERSION 3.2)
project (hello_starpu)
find_package(PkgConfig)
pkg_check_modules(STARPU REQUIRED starpu-1.4)
# This section must appear before 'add_executable'
if (STARPU_FOUND)
# CFLAGS other than -I
foreach(CFLAG ${STARPU_CFLAGS_OTHER})
set (CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${CFLAG}")
endforeach()
# Static LDFLAGS other than -L
foreach(LDFLAG ${STARPU_STATIC_LDFLAGS_OTHER})
set (CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${LDFLAG}")
endforeach()
# -L directories
link_directories(${STARPU_STATIC_LIBRARY_DIRS})
else (STARPU_FOUND)
message(FATAL_ERROR "StarPU not found")
endif()
add_executable(hello_starpu hello_starpu.c)
# This section must appear after 'add_executable'
if (STARPU_FOUND)
# -I directories
target_include_directories(hello_starpu PRIVATE ${STARPU_INCLUDE_DIRS})
# Static -l libs
target_link_libraries(hello_starpu PRIVATE ${STARPU_STATIC_LIBRARIES})
endif()

7.3 Running a Basic StarPU Application

Basic examples using StarPU are built in the directory examples/basic_examples/ (and installed in $STARPU_PATH/lib/starpu/examples/). You can for example run the example vector_scal.

$ ./examples/basic_examples/vector_scal
BEFORE: First element was 1.000000
AFTER: First element is 3.140000

When StarPU is used for the first time, the directory $STARPU_HOME/.starpu/ is created, performance models will be stored in this directory (STARPU_HOME).

Please note that buses are benchmarked when StarPU is launched for the first time. This may take a few minutes, or less if libhwloc is installed. This step is done only once per user and per machine.

7.4 Running a Basic StarPU Application on Microsoft Visual C

Batch files are provided to run StarPU applications under Microsoft Visual C. They are installed in $STARPU_PATH/bin/msvc.

To execute a StarPU application, you first need to set the environment variable STARPU_PATH.

c:\....> cd c:\cygwin\home\ci\starpu\
c:\....> set STARPU_PATH=c:\cygwin\home\ci\starpu\
c:\....> cd bin\msvc
c:\....> starpu_open.bat starpu_simple.c

The batch script will run Microsoft Visual C with a basic project file to run the given application.

The batch script starpu_clean.bat can be used to delete all compilation generated files.

The batch script starpu_exec.bat can be used to compile and execute a StarPU application from the command prompt.

c:\....> cd c:\cygwin\home\ci\starpu\
c:\....> set STARPU_PATH=c:\cygwin\home\ci\starpu\
c:\....> cd bin\msvc
c:\....> starpu_exec.bat ..\..\..\..\examples\basic_examples\hello_world.c
MSVC StarPU Execution
...
/out:hello_world.exe
...
Hello world (params = {1, 2.00000})
Callback function got argument 0000042
c:\....>

7.5 Kernel Threads Started by StarPU

StarPU automatically binds one thread per CPU core. It does not use SMT/hyperthreading because kernels are usually already optimized for using a full core, and using hyperthreading would make kernel calibration rather random.

Since driving GPUs is a CPU-consuming task, StarPU dedicates one core per GPU.

While StarPU tasks are executing, the application is not supposed to do computations in the threads it starts itself, tasks should be used instead.

If the application needs to reserve some cores for its own computations, it can do so with the field starpu_conf::reserve_ncpus, get the core IDs with starpu_get_next_bindid(), and bind to them with starpu_bind_thread_on().

Another option is for the application to pause StarPU by calling starpu_pause(), then to perform its own computations, and then to resume StarPU by calling starpu_resume() so that StarPU can execute tasks.

7.6 Enabling OpenCL

When both CUDA and OpenCL drivers are enabled, StarPU will launch an OpenCL worker for NVIDIA GPUs only if CUDA is not already running on them. This design choice was necessary as OpenCL and CUDA can not run at the same time on the same NVIDIA GPU, as there is currently no interoperability between them.

To enable OpenCL, you need either to disable CUDA when configuring StarPU:

$ ./configure --disable-cuda

or when running applications:

$ STARPU_NCUDA=0 ./application

OpenCL will automatically be started on any device not yet used by CUDA. So on a machine running 4 GPUS, it is therefore possible to enable CUDA on 2 devices, and OpenCL on the 2 other devices by doing so:

$ STARPU_NCUDA=2 ./application

7.7 Performance Model Files

StarPU stores performance model files for bus benchmarking and codelet profiles in different directories.

By default, all files are stored in $STARPU_HOME/.starpu/sampling.

If the environment variable STARPU_HOME is not defined, its default value is $HOME on Unix environments, and $USERPROFILE on Windows environments.

Environment variables STARPU_PERF_MODEL_DIR and STARPU_PERF_MODEL_PATH can also be used to specify other directories in which to store performance files (Simulated Benchmarks).

The configure option --with-perf-model-dir can also be used to define a performance model directory.

When looking for performance files either for bus benchmarking or for codelet performances, StarPU

  • first looks in the directory specified by the environment variable STARPU_PERF_MODEL_DIR
  • then looks in the directory specified by the configure option --with-perf-model-dir
    or in $STARPU_HOME/.starpu/sampling if the option is not set
  • then looks in the directories specified by the environment variable STARPU_PERF_MODEL_PATH
  • and finally looks in $prefix/share/starpu/perfmodels/sampling

If the files are not present and must be created, they will be created in the first defined directory from the list above.

rm -rf $PWD/xxx && STARPU_PERF_MODEL_DIR=$PWD/xxx ./application

will use performance model files from the directory $STARPU_HOME/.starpu/sampling if they are available, otherwise will create these files in $STARPU_PERF_MODEL_DIR.

To know the list of directories StarPU will search for performances files, one can use the tool starpu_perfmodel_display

$ starpu_perfmodel_display -d
directory: </home/user1/.starpu/sampling/codelets/45/>
directory: </usr/local/install/share/starpu/perfmodels/sampling/codelets/45/>
$ STARPU_PERF_MODEL_DIR=/tmp/xxx starpu_perfmodel_display -d
directory: </tmp/xxx/codelets/45/>
directory: </home/user1/.starpu/sampling/codelets/45/>
directory: </usr/local/install/share/starpu/perfmodels/sampling/codelets/45/>

When using the variable STARPU_PERF_MODEL_DIR, the directory will be created if it does not exist when dumping new performance model files.

When using the variable STARPU_PERF_MODEL_PATH, only existing directories will be taken into account.

$ mkdir /tmp/yyy && STARPU_PERF_MODEL_DIR=/tmp/xxx STARPU_PERF_MODEL_PATH=/tmp/zzz:/tmp/yyy starpu_perfmodel_display -d
[starpu][adrets][_perf_model_add_dir] Warning: directory </tmp/zzz> as set by variable STARPU_PERF_MODEL_PATH does not exist
directory: </tmp/xxx/codelets/45/>
directory: </home/user1/.starpu/sampling/codelets/45/>
directory: </tmp/yyy/codelets/45/>
directory: </usr/local/install/share/starpu/perfmodels/sampling/codelets/45/>

Once your application has created the performance files in a given directory, it is thus possible to move these files in another location and keep using them.

./application
# files are created in $HOME/.starpu/sampling
mv $HOME/.starpu/sampling /usr/local/starpu/sampling
STARPU_PERF_MODEL_DIR=/usr/local/starpu/sampling ./application