/* StarPU --- Runtime system for heterogeneous multicore architectures. * * Copyright (C) 2010-2019 CNRS * Copyright (C) 2011,2012,2018 Inria * Copyright (C) 2009-2011,2013-2016 Université de Bordeaux * * StarPU is free software; you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as published by * the Free Software Foundation; either version 2.1 of the License, or (at * your option) any later version. * * StarPU is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. * * See the GNU Lesser General Public License in COPYING.LGPL for more details. */ /*! \page BuildingAndInstallingStarPU Building and Installing StarPU \section InstallingABinaryPackage Installing a Binary Package One of the StarPU developers being a Debian Developer, the packages are well integrated and very uptodate. To see which packages are available, simply type: \verbatim $ apt-cache search starpu \endverbatim To install what you need, type for example: \verbatim $ sudo apt-get install libstarpu-1.3 libstarpu-dev \endverbatim \section InstallingFromSource Installing from Source StarPU can be built and installed 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. \subsection OptionalDependencies Optional Dependencies The hwloc (http://www.open-mpi.org/software/hwloc) topology discovery library is not mandatory to use StarPU but strongly recommended. It allows for topology aware scheduling, which improves performance. libhwloc is available in major free operating system distributions, and for most operating systems. If libhwloc is installed in a standard location, no option is required, it will be detected automatically, otherwise \ref with-hwloc "--with-hwloc=" should be used to specify its location. If libhwloc is not available on your system, the option \ref without-hwloc "--without-hwloc" should be explicitely given when calling the configure script. \subsection GettingSources Getting Sources StarPU's sources can be obtained from the download page of the StarPU website (http://starpu.gforge.inria.fr/files/). All releases and the development tree of StarPU are freely available on Inria's gforge under the LGPL license. Some releases are available under the BSD license. The latest release can be downloaded from the Inria's gforge (http://gforge.inria.fr/frs/?group_id=1570) or directly from the StarPU download page (http://starpu.gforge.inria.fr/files/). The latest nightly snapshot can be downloaded from the StarPU gforge website (http://starpu.gforge.inria.fr/testing/). \verbatim $ wget http://starpu.gforge.inria.fr/testing/starpu-nightly-latest.tar.gz \endverbatim And finally, current development version is also accessible via git. It should only be used if you need the very latest changes (i.e. less than a day old!). \verbatim $ git clone https://scm.gforge.inria.fr/anonscm/git/starpu/starpu.git \endverbatim \subsection ConfiguringStarPU Configuring StarPU Running autogen.sh is not necessary when using the tarball releases of StarPU. However when using the source code from the git repository, you first need to generate the configure scripts and the Makefiles. This requires the availability of autoconf and automake >= 2.60. \verbatim $ ./autogen.sh \endverbatim You then need to configure StarPU. Details about options that are useful to give to configure are given in \ref CompilationConfiguration. \verbatim $ ./configure \endverbatim If configure does not detect some software or produces errors, please make sure to post the contents of the file config.log when reporting the issue. By default, the files produced during the compilation are placed in the source directory. As the compilation generates a lot of files, it is advised to put them all in a separate directory. It is then easier to cleanup, and this allows to compile several configurations out of the same source tree. To do so, simply enter the directory where you want the compilation to produce its files, and invoke the configure script located in the StarPU source directory. \verbatim $ mkdir build $ cd build $ ../configure \endverbatim By default, StarPU will be installed in /usr/local/bin, /usr/local/lib, etc. You can specify an installation prefix other than /usr/local using the option --prefix, for instance: \verbatim $ ../configure --prefix=$HOME/starpu \endverbatim \subsection BuildingStarPU Building StarPU \verbatim $ make \endverbatim Once everything is built, you may want to test the result. An extensive set of regression tests is provided with StarPU. Running the tests is done by calling make check. These tests are run every night and the result from the main profile is publicly available (http://starpu.gforge.inria.fr/testing/). \verbatim $ make check \endverbatim \subsection InstallingStarPU Installing StarPU In order to install StarPU at the location which was specified during configuration: \verbatim $ make install \endverbatim Libtool interface versioning information are included in libraries names (libstarpu-1.3.so, libstarpumpi-1.3.so and libstarpufft-1.3.so). \section SettingUpYourOwnCode Setting up Your Own Code \subsection SettingFlagsForCompilingLinkingAndRunningApplications 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: \verbatim $ PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$STARPU_PATH/lib/pkgconfig \endverbatim The flags required to compile or link against StarPU are then accessible with the following commands: \verbatim $ pkg-config --cflags starpu-1.3 # options for the compiler $ pkg-config --libs starpu-1.3 # options for the linker \endverbatim 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.3 actually produces some output before going further: PKG_CONFIG_PATH has to point to the place where starpu-1.3.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. \verbatim $ LD_LIBRARY_PATH=$STARPU_PATH/lib:$LD_LIBRARY_PATH \endverbatim When using a Makefile, the following lines can be added to set the options for the compiler and the linker: \verbatim CFLAGS += $$(pkg-config --cflags starpu-1.3) LDFLAGS += $$(pkg-config --libs starpu-1.3) \endverbatim \subsection IntegratingStarPUInABuildSystem Integrating StarPU in a Build System \subsubsection StarPUInCMake 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: \code{.c} #include int main(void) { int ret; ret = starpu_init(NULL); if (ret != 0) { return 1; } starpu_shutdown(); return 0; } \endcode The \c 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. \code{File CMakeLists.txt} cmake_minimum_required (VERSION 3.2) project (hello_starpu) find_package(PkgConfig) pkg_check_modules(STARPU REQUIRED starpu-1.3) 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) \endcode The following \c 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 \c 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. \code{File CMakeLists.txt} cmake_minimum_required (VERSION 3.2) project (hello_starpu) find_package(PkgConfig) pkg_check_modules(STARPU REQUIRED starpu-1.3) # 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() \endcode \subsection RunningABasicStarPUApplication 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. \verbatim $ ./examples/basic_examples/vector_scal BEFORE: First element was 1.000000 AFTER: First element is 3.140000 \endverbatim When StarPU is used for the first time, the directory $STARPU_HOME/.starpu/ is created, performance models will be stored in this directory (\ref 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. \subsection RunningABasicStarPUApplicationOnMicrosoft 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 \ref STARPU_PATH. \verbatim 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 \endverbatim 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. \verbatim 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 \endverbatim \verbatim MSVC StarPU Execution ... /out:hello_world.exe ... Hello world (params = {1, 2.00000}) Callback function got argument 0000042 c:\....> \endverbatim \subsection KernelThreadsStartedByStarPU 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. TODO: add a StarPU function to bind an application thread (e.g. the main thread) to a dedicated core (and thus disable the corresponding StarPU CPU worker). \subsection EnablingOpenCL 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: \verbatim $ ./configure --disable-cuda \endverbatim or when running applications: \verbatim $ STARPU_NCUDA=0 ./application \endverbatim 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: \verbatim $ STARPU_NCUDA=2 ./application \endverbatim \section BenchmarkingStarPU Benchmarking StarPU Some interesting benchmarks are installed among examples in $STARPU_PATH/lib/starpu/examples/. Make sure to try various schedulers, for instance STARPU_SCHED=dmda. \subsection TaskSizeOverhead Task Size Overhead This benchmark gives a glimpse into how long a task should be (in µs) for StarPU overhead to be low enough to keep efficiency. Running tasks_size_overhead.sh generates a plot of the speedup of tasks of various sizes, depending on the number of CPUs being used. \image html tasks_size_overhead.png \image latex tasks_size_overhead.eps "" width=\textwidth \subsection DataTransferLatency Data Transfer Latency local_pingpong performs a ping-pong between the first two CUDA nodes, and prints the measured latency. \subsection MatrixMatrixMultiplication Matrix-Matrix Multiplication sgemm and dgemm perform a blocked matrix-matrix multiplication using BLAS and cuBLAS. They output the obtained GFlops. \subsection CholeskyFactorization Cholesky Factorization cholesky_* perform a Cholesky factorization (single precision). They use different dependency primitives. \subsection LUFactorization LU Factorization lu_* perform an LU factorization. They use different dependency primitives. \subsection SimulatedBenchmarks Simulated benchmarks It can also be convenient to try simulated benchmarks, if you want to give a try at CPU-GPU scheduling without actually having a GPU at hand. This can be done by using the simgrid version of StarPU: first install the simgrid simulator from http://simgrid.gforge.inria.fr/ (we tested with simgrid 3.11, 3.12 and 3.13, other versions may have compatibility issues), then configure StarPU with \ref enable-simgrid "--enable-simgrid" and rebuild and install it, and then you can simulate the performance for a few virtualized systems shipped along StarPU: attila, mirage, idgraf, and sirocco. For instance: \verbatim $ export STARPU_PERF_MODEL_DIR=$STARPU_PATH/share/starpu/perfmodels/sampling $ export STARPU_HOSTNAME=attila $ $STARPU_PATH/lib/starpu/examples/cholesky_implicit -size $((960*20)) -nblocks 20 \endverbatim Will show the performance of the cholesky factorization with the attila system. It will be interesting to try with different matrix sizes and schedulers. Performance models are available for cholesky_*, lu_*, *gemm, with block sizes 320, 640, or 960 (plus 1440 for sirocco), and for stencil with block size 128x128x128, 192x192x192, and 256x256x256. */