doc/doxygen/chapters: delete files which are no longer needed (they have been renamed in previous merges)

doc/doxygen/chapters/15environment_variables.doxy

@@ -1,655 +0,0 @@
-/*
- * This file is part of the StarPU Handbook.
- * Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
- * Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
- * Copyright (C) 2011, 2012 Institut National de Recherche en Informatique et Automatique
- * See the file version.doxy for copying conditions.
- */
-
-/*! \page ExecutionConfigurationThroughEnvironmentVariables Execution Configuration Through Environment Variables
-
-The behavior of the StarPU library and tools may be tuned thanks to
-the following environment variables.
-
-\section ConfiguringWorkers Configuring Workers
-
-<dl>
-
-<dt>STARPU_NCPU</dt>
-<dd>
-\anchor STARPU_NCPU
-\addindex __env__STARPU_NCPU
-Specify the number of CPU workers (thus not including workers
-dedicated to control accelerators). Note that by default, StarPU will
-not allocate more CPU workers than there are physical CPUs, and that
-some CPUs are used to control the accelerators.
-</dd>
-
-<dt>STARPU_NCPUS</dt>
-<dd>
-\anchor STARPU_NCPUS
-\addindex __env__STARPU_NCPUS
-This variable is deprecated. You should use \ref STARPU_NCPU.
-</dd>
-
-<dt>STARPU_NCUDA</dt>
-<dd>
-\anchor STARPU_NCUDA
-\addindex __env__STARPU_NCUDA
-Specify the number of CUDA devices that StarPU can use. If
-\ref STARPU_NCUDA is lower than the number of physical devices, it is
-possible to select which CUDA devices should be used by the means of the
-environment variable \ref STARPU_WORKERS_CUDAID. By default, StarPU will
-create as many CUDA workers as there are CUDA devices.
-</dd>
-
-<dt>STARPU_NOPENCL</dt>
-<dd>
-\anchor STARPU_NOPENCL
-\addindex __env__STARPU_NOPENCL
-OpenCL equivalent of the environment variable \ref STARPU_NCUDA.
-</dd>
-
-<dt>STARPU_OPENCL_ON_CPUS</dt>
-<dd>
-\anchor STARPU_OPENCL_ON_CPUS
-\addindex __env__STARPU_OPENCL_ON_CPUS
-By default, the OpenCL driver only enables GPU and accelerator
-devices. By setting the environment variable \ref
-STARPU_OPENCL_ON_CPUS to 1, the OpenCL driver will also enable CPU
-devices.
-</dd>
-
-<dt>STARPU_OPENCL_ONLY_ON_CPUS</dt>
-<dd>
-\anchor STARPU_OPENCL_ONLY_ON_CPUS
-\addindex __env__STARPU_OPENCL_ONLY_ON_CPUS
-By default, the OpenCL driver enables GPU and accelerator
-devices. By setting the environment variable \ref
-STARPU_OPENCL_ONLY_ON_CPUS to 1, the OpenCL driver will ONLY enable
-CPU devices.
-</dd>
-
-<dt>STARPU_NMIC</dt>
-<dd>
-\anchor STARPU_NMIC
-\addindex __env__STARPU_NMIC
-MIC equivalent of the environment variable \ref STARPU_NCUDA.
-</dd>
-
-<dt>STARPU_NSCC</dt>
-<dd>
-\anchor STARPU_NSCC
-\addindex __env__STARPU_NSCC
-SCC equivalent of the environment variable \ref STARPU_NCUDA.
-</dd>
-
-<dt>STARPU_WORKERS_NOBIND</dt>
-<dd>
-\anchor STARPU_WORKERS_NOBIND
-\addindex __env__STARPU_WORKERS_NOBIND
-Setting it to non-zero will prevent StarPU from binding its threads to
-CPUs. This is for instance useful when running the testsuite in parallel.
-</dd>
-
-<dt>STARPU_WORKERS_CPUID</dt>
-<dd>
-\anchor STARPU_WORKERS_CPUID
-\addindex __env__STARPU_WORKERS_CPUID
-Passing an array of integers (starting from 0) in \ref STARPU_WORKERS_CPUID
-specifies on which logical CPU the different workers should be
-bound. For instance, if <c>STARPU_WORKERS_CPUID = "0 1 4 5"</c>, the first
-worker will be bound to logical CPU #0, the second CPU worker will be bound to
-logical CPU #1 and so on.  Note that the logical ordering of the CPUs is either
-determined by the OS, or provided by the library <c>hwloc</c> in case it is
-available.
-
-Note that the first workers correspond to the CUDA workers, then come the
-OpenCL workers, and finally the CPU workers. For example if
-we have <c>STARPU_NCUDA=1</c>, <c>STARPU_NOPENCL=1</c>, <c>STARPU_NCPU=2</c>
-and <c>STARPU_WORKERS_CPUID = "0 2 1 3"</c>, the CUDA device will be controlled
-by logical CPU #0, the OpenCL device will be controlled by logical CPU #2, and
-the logical CPUs #1 and #3 will be used by the CPU workers.
-
-If the number of workers is larger than the array given in \ref
-STARPU_WORKERS_CPUID, the workers are bound to the logical CPUs in a
-round-robin fashion: if <c>STARPU_WORKERS_CPUID = "0 1"</c>, the first
-and the third (resp. second and fourth) workers will be put on CPU #0
-(resp. CPU #1).
-
-This variable is ignored if the field
-starpu_conf::use_explicit_workers_bindid passed to starpu_init() is
-set.
-
-</dd>
-
-<dt>STARPU_WORKERS_CUDAID</dt>
-<dd>
-\anchor STARPU_WORKERS_CUDAID
-\addindex __env__STARPU_WORKERS_CUDAID
-Similarly to the \ref STARPU_WORKERS_CPUID environment variable, it is
-possible to select which CUDA devices should be used by StarPU. On a machine
-equipped with 4 GPUs, setting <c>STARPU_WORKERS_CUDAID = "1 3"</c> and
-<c>STARPU_NCUDA=2</c> specifies that 2 CUDA workers should be created, and that
-they should use CUDA devices #1 and #3 (the logical ordering of the devices is
-the one reported by CUDA).
-
-This variable is ignored if the field
-starpu_conf::use_explicit_workers_cuda_gpuid passed to starpu_init()
-is set.
-</dd>
-
-<dt>STARPU_WORKERS_OPENCLID</dt>
-<dd>
-\anchor STARPU_WORKERS_OPENCLID
-\addindex __env__STARPU_WORKERS_OPENCLID
-OpenCL equivalent of the \ref STARPU_WORKERS_CUDAID environment variable.
-
-This variable is ignored if the field
-starpu_conf::use_explicit_workers_opencl_gpuid passed to starpu_init()
-is set.
-</dd>
-
-<dt>STARPU_WORKERS_MICID</dt>
-<dd>
-\anchor STARPU_WORKERS_MICID
-\addindex __env__STARPU_WORKERS_MICID
-MIC equivalent of the \ref STARPU_WORKERS_CUDAID environment variable.
-
-This variable is ignored if the field
-starpu_conf::use_explicit_workers_mic_deviceid passed to starpu_init()
-is set.
-</dd>
-
-<dt>STARPU_WORKERS_SCCID</dt>
-<dd>
-\anchor STARPU_WORKERS_SCCID
-\addindex __env__STARPU_WORKERS_SCCID
-SCC equivalent of the \ref STARPU_WORKERS_CUDAID environment variable.
-
-This variable is ignored if the field
-starpu_conf::use_explicit_workers_scc_deviceid passed to starpu_init()
-is set.
-</dd>
-
-<dt>STARPU_SINGLE_COMBINED_WORKER</dt>
-<dd>
-\anchor STARPU_SINGLE_COMBINED_WORKER
-\addindex __env__STARPU_SINGLE_COMBINED_WORKER
-If set, StarPU will create several workers which won't be able to work
-concurrently. It will by default create combined workers which size goes from 1
-to the total number of CPU workers in the system. \ref STARPU_MIN_WORKERSIZE
-and \ref STARPU_MAX_WORKERSIZE can be used to change this default.
-</dd>
-
-<dt>STARPU_MIN_WORKERSIZE</dt>
-<dd>
-\anchor STARPU_MIN_WORKERSIZE
-\addindex __env__STARPU_MIN_WORKERSIZE
-\ref STARPU_MIN_WORKERSIZE
-permits to specify the minimum size of the combined workers (instead of the default 2)
-</dd>
-
-<dt>STARPU_MAX_WORKERSIZE</dt>
-<dd>
-\anchor STARPU_MAX_WORKERSIZE
-\addindex __env__STARPU_MAX_WORKERSIZE
-\ref STARPU_MAX_WORKERSIZE
-permits to specify the minimum size of the combined workers (instead of the
-number of CPU workers in the system)
-</dd>
-
-<dt>STARPU_SYNTHESIZE_ARITY_COMBINED_WORKER</dt>
-<dd>
-\anchor STARPU_SYNTHESIZE_ARITY_COMBINED_WORKER
-\addindex __env__STARPU_SYNTHESIZE_ARITY_COMBINED_WORKER
-Let the user decide how many elements are allowed between combined workers
-created from hwloc information. For instance, in the case of sockets with 6
-cores without shared L2 caches, if \ref STARPU_SYNTHESIZE_ARITY_COMBINED_WORKER is
-set to 6, no combined worker will be synthesized beyond one for the socket
-and one per core. If it is set to 3, 3 intermediate combined workers will be
-synthesized, to divide the socket cores into 3 chunks of 2 cores. If it set to
-2, 2 intermediate combined workers will be synthesized, to divide the the socket
-cores into 2 chunks of 3 cores, and then 3 additional combined workers will be
-synthesized, to divide the former synthesized workers into a bunch of 2 cores,
-and the remaining core (for which no combined worker is synthesized since there
-is already a normal worker for it).
-
-The default, 2, thus makes StarPU tend to building a binary trees of combined
-workers.
-</dd>
-
-<dt>STARPU_DISABLE_ASYNCHRONOUS_COPY</dt>
-<dd>
-\anchor STARPU_DISABLE_ASYNCHRONOUS_COPY
-\addindex __env__STARPU_DISABLE_ASYNCHRONOUS_COPY
-Disable asynchronous copies between CPU and GPU devices.
-The AMD implementation of OpenCL is known to
-fail when copying data asynchronously. When using this implementation,
-it is therefore necessary to disable asynchronous data transfers.
-</dd>
-
-<dt>STARPU_DISABLE_ASYNCHRONOUS_CUDA_COPY</dt>
-<dd>
-\anchor STARPU_DISABLE_ASYNCHRONOUS_CUDA_COPY
-\addindex __env__STARPU_DISABLE_ASYNCHRONOUS_CUDA_COPY
-Disable asynchronous copies between CPU and CUDA devices.
-</dd>
-
-<dt>STARPU_DISABLE_ASYNCHRONOUS_OPENCL_COPY</dt>
-<dd>
-\anchor STARPU_DISABLE_ASYNCHRONOUS_OPENCL_COPY
-\addindex __env__STARPU_DISABLE_ASYNCHRONOUS_OPENCL_COPY
-Disable asynchronous copies between CPU and OpenCL devices.
-The AMD implementation of OpenCL is known to
-fail when copying data asynchronously. When using this implementation,
-it is therefore necessary to disable asynchronous data transfers.
-</dd>
-
-<dt>STARPU_DISABLE_ASYNCHRONOUS_MIC_COPY</dt>
-<dd>
-\anchor STARPU_DISABLE_ASYNCHRONOUS_MIC_COPY
-\addindex __env__STARPU_DISABLE_ASYNCHRONOUS_MIC_COPY
-Disable asynchronous copies between CPU and MIC devices.
-</dd>
-
-<dt>STARPU_ENABLE_CUDA_GPU_GPU_DIRECT</dt>
-<dd>
-\anchor STARPU_ENABLE_CUDA_GPU_GPU_DIRECT
-\addindex __env__STARPU_ENABLE_CUDA_GPU_GPU_DIRECT
-Enable (1) or Disable (0) direct CUDA transfers from GPU to GPU, without copying
-through RAM. The default is Enabled.
-This permits to test the performance effect of GPU-Direct.
-</dd>
-
-</dl>
-
-\section ConfiguringTheSchedulingEngine Configuring The Scheduling Engine
-
-<dl>
-
-<dt>STARPU_SCHED</dt>
-<dd>
-\anchor STARPU_SCHED
-\addindex __env__STARPU_SCHED
-Choose between the different scheduling policies proposed by StarPU: work
-random, stealing, greedy, with performance models, etc.
-
-Use <c>STARPU_SCHED=help</c> to get the list of available schedulers.
-</dd>
-
-<dt>STARPU_CALIBRATE</dt>
-<dd>
-\anchor STARPU_CALIBRATE
-\addindex __env__STARPU_CALIBRATE
-If this variable is set to 1, the performance models are calibrated during
-the execution. If it is set to 2, the previous values are dropped to restart
-calibration from scratch. Setting this variable to 0 disable calibration, this
-is the default behaviour.
-
-Note: this currently only applies to <c>dm</c> and <c>dmda</c> scheduling policies.
-</dd>
-
-<dt>STARPU_BUS_CALIBRATE</dt>
-<dd>
-\anchor STARPU_BUS_CALIBRATE
-\addindex __env__STARPU_BUS_CALIBRATE
-If this variable is set to 1, the bus is recalibrated during intialization.
-</dd>
-
-<dt>STARPU_PREFETCH</dt>
-<dd>
-\anchor STARPU_PREFETCH
-\addindex __env__STARPU_PREFETCH
-This variable indicates whether data prefetching should be enabled (0 means
-that it is disabled). If prefetching is enabled, when a task is scheduled to be
-executed e.g. on a GPU, StarPU will request an asynchronous transfer in
-advance, so that data is already present on the GPU when the task starts. As a
-result, computation and data transfers are overlapped.
-Note that prefetching is enabled by default in StarPU.
-</dd>
-
-<dt>STARPU_SCHED_ALPHA</dt>
-<dd>
-\anchor STARPU_SCHED_ALPHA
-\addindex __env__STARPU_SCHED_ALPHA
-To estimate the cost of a task StarPU takes into account the estimated
-computation time (obtained thanks to performance models). The alpha factor is
-the coefficient to be applied to it before adding it to the communication part.
-</dd>
-
-<dt>STARPU_SCHED_BETA</dt>
-<dd>
-\anchor STARPU_SCHED_BETA
-\addindex __env__STARPU_SCHED_BETA
-To estimate the cost of a task StarPU takes into account the estimated
-data transfer time (obtained thanks to performance models). The beta factor is
-the coefficient to be applied to it before adding it to the computation part.
-</dd>
-
-<dt>STARPU_SCHED_GAMMA</dt>
-<dd>
-\anchor STARPU_SCHED_GAMMA
-\addindex __env__STARPU_SCHED_GAMMA
-Define the execution time penalty of a joule (\ref Power-basedScheduling).
-</dd>
-
-<dt>STARPU_IDLE_POWER</dt>
-<dd>
-\anchor STARPU_IDLE_POWER
-\addindex __env__STARPU_IDLE_POWER
-Define the idle power of the machine (\ref Power-basedScheduling).
-</dd>
-
-<dt>STARPU_PROFILING</dt>
-<dd>
-\anchor STARPU_PROFILING
-\addindex __env__STARPU_PROFILING
-Enable on-line performance monitoring (\ref EnablingOn-linePerformanceMonitoring).
-</dd>
-
-</dl>
-
-\section Extensions Extensions
-
-<dl>
-
-<dt>SOCL_OCL_LIB_OPENCL</dt>
-<dd>
-\anchor SOCL_OCL_LIB_OPENCL
-\addindex __env__SOCL_OCL_LIB_OPENCL
-THE SOCL test suite is only run when the environment variable \ref
-SOCL_OCL_LIB_OPENCL is defined. It should contain the location
-of the file <c>libOpenCL.so</c> of the OCL ICD implementation.
-</dd>
-
-<dt>OCL_ICD_VENDORS</dt>
-<dd>
-\anchor OCL_ICD_VENDORS
-\addindex __env__OCL_ICD_VENDORS
-When using SOCL with OpenCL ICD
-(https://forge.imag.fr/projects/ocl-icd/), this variable may be used
-to point to the directory where ICD files are installed. The default
-directory is <c>/etc/OpenCL/vendors</c>. StarPU installs ICD
-files in the directory <c>$prefix/share/starpu/opencl/vendors</c>.
-</dd>
-
-<dt>STARPU_COMM_STATS</dt>
-<dd>
-\anchor STARPU_COMM_STATS
-\addindex __env__STARPU_COMM_STATS
-Communication statistics for starpumpi (\ref MPISupport)
-will be enabled when the environment variable \ref STARPU_COMM_STATS
-is defined to an value other than 0.
-</dd>
-
-<dt>STARPU_MPI_CACHE</dt>
-<dd>
-\anchor STARPU_MPI_CACHE
-\addindex __env__STARPU_MPI_CACHE
-Communication cache for starpumpi (\ref MPISupport) will be
-disabled when the environment variable \ref STARPU_MPI_CACHE is set
-to 0. It is enabled by default or for any other values of the variable
-\ref STARPU_MPI_CACHE.
-</dd>
-
-</dl>
-
-\section MiscellaneousAndDebug Miscellaneous And Debug
-
-<dl>
-
-<dt>STARPU_HOME</dt>
-<dd>
-\anchor STARPU_HOME
-\addindex __env__STARPU_HOME
-This specifies the main directory in which StarPU stores its
-configuration files. The default is <c>$HOME</c> on Unix environments,
-and <c>$USERPROFILE</c> on Windows environments.
-</dd>
-
-<dt>STARPU_HOSTNAME</dt>
-<dd>
-\anchor STARPU_HOSTNAME
-\addindex __env__STARPU_HOSTNAME
-When set, force the hostname to be used when dealing performance model
-files. Models are indexed by machine name. When running for example on
-a homogenenous cluster, it is possible to share the models between
-machines by setting <c>export STARPU_HOSTNAME=some_global_name</c>.
-</dd>
-
-<dt>STARPU_OPENCL_PROGRAM_DIR</dt>
-<dd>
-\anchor STARPU_OPENCL_PROGRAM_DIR
-\addindex __env__STARPU_OPENCL_PROGRAM_DIR
-This specifies the directory where the OpenCL codelet source files are
-located. The function starpu_opencl_load_program_source() looks
-for the codelet in the current directory, in the directory specified
-by the environment variable \ref STARPU_OPENCL_PROGRAM_DIR, in the
-directory <c>share/starpu/opencl</c> of the installation directory of
-StarPU, and finally in the source directory of StarPU.
-</dd>
-
-<dt>STARPU_SILENT</dt>
-<dd>
-\anchor STARPU_SILENT
-\addindex __env__STARPU_SILENT
-This variable allows to disable verbose mode at runtime when StarPU
-has been configured with the option \ref enable-verbose "--enable-verbose". It also
-disables the display of StarPU information and warning messages.
-</dd>
-
-<dt>STARPU_LOGFILENAME</dt>
-<dd>
-\anchor STARPU_LOGFILENAME
-\addindex __env__STARPU_LOGFILENAME
-This variable specifies in which file the debugging output should be saved to.
-</dd>
-
-<dt>STARPU_FXT_PREFIX</dt>
-<dd>
-\anchor STARPU_FXT_PREFIX
-\addindex __env__STARPU_FXT_PREFIX
-This variable specifies in which directory to save the trace generated if FxT is enabled. It needs to have a trailing '/' character.
-</dd>
-
-<dt>STARPU_LIMIT_CUDA_devid_MEM</dt>
-<dd>
-\anchor STARPU_LIMIT_CUDA_devid_MEM
-\addindex __env__STARPU_LIMIT_CUDA_devid_MEM
-This variable specifies the maximum number of megabytes that should be
-available to the application on the CUDA device with the identifier
-<c>devid</c>. This variable is intended to be used for experimental
-purposes as it emulates devices that have a limited amount of memory.
-When defined, the variable overwrites the value of the variable
-\ref STARPU_LIMIT_CUDA_MEM.
-</dd>
-
-<dt>STARPU_LIMIT_CUDA_MEM</dt>
-<dd>
-\anchor STARPU_LIMIT_CUDA_MEM
-\addindex __env__STARPU_LIMIT_CUDA_MEM
-This variable specifies the maximum number of megabytes that should be
-available to the application on each CUDA devices. This variable is
-intended to be used for experimental purposes as it emulates devices
-that have a limited amount of memory.
-</dd>
-
-<dt>STARPU_LIMIT_OPENCL_devid_MEM</dt>
-<dd>
-\anchor STARPU_LIMIT_OPENCL_devid_MEM
-\addindex __env__STARPU_LIMIT_OPENCL_devid_MEM
-This variable specifies the maximum number of megabytes that should be
-available to the application on the OpenCL device with the identifier
-<c>devid</c>. This variable is intended to be used for experimental
-purposes as it emulates devices that have a limited amount of memory.
-When defined, the variable overwrites the value of the variable
-\ref STARPU_LIMIT_OPENCL_MEM.
-</dd>
-
-<dt>STARPU_LIMIT_OPENCL_MEM</dt>
-<dd>
-\anchor STARPU_LIMIT_OPENCL_MEM
-\addindex __env__STARPU_LIMIT_OPENCL_MEM
-This variable specifies the maximum number of megabytes that should be
-available to the application on each OpenCL devices. This variable is
-intended to be used for experimental purposes as it emulates devices
-that have a limited amount of memory.
-</dd>
-
-<dt>STARPU_LIMIT_CPU_MEM</dt>
-<dd>
-\anchor STARPU_LIMIT_CPU_MEM
-\addindex __env__STARPU_LIMIT_CPU_MEM
-This variable specifies the maximum number of megabytes that should be
-available to the application on each CPU device. This variable is
-intended to be used for experimental purposes as it emulates devices
-that have a limited amount of memory.
-</dd>
-
-<dt>STARPU_GENERATE_TRACE</dt>
-<dd>
-\anchor STARPU_GENERATE_TRACE
-\addindex __env__STARPU_GENERATE_TRACE
-When set to <c>1</c>, this variable indicates that StarPU should automatically
-generate a Paje trace when starpu_shutdown() is called.
-</dd>
-
-<dt>STARPU_MEMORY_STATS</dt>
-<dd>
-\anchor STARPU_MEMORY_STATS
-\addindex __env__STARPU_MEMORY_STATS
-When set to 0, disable the display of memory statistics on data which
-have not been unregistered at the end of the execution (\ref MemoryFeedback).
-</dd>
-
-<dt>STARPU_BUS_STATS</dt>
-<dd>
-\anchor STARPU_BUS_STATS
-\addindex __env__STARPU_BUS_STATS
-When defined, statistics about data transfers will be displayed when calling
-starpu_shutdown() (\ref Profiling).
-</dd>
-
-<dt>STARPU_WORKER_STATS</dt>
-<dd>
-\anchor STARPU_WORKER_STATS
-\addindex __env__STARPU_WORKER_STATS
-When defined, statistics about the workers will be displayed when calling
-starpu_shutdown() (\ref Profiling). When combined with the
-environment variable \ref STARPU_PROFILING, it displays the power
-consumption (\ref Power-basedScheduling).
-</dd>
-
-<dt>STARPU_STATS</dt>
-<dd>
-\anchor STARPU_STATS
-\addindex __env__STARPU_STATS
-When set to 0, data statistics will not be displayed at the
-end of the execution of an application (\ref DataStatistics).
-</dd>
-
-<dt>STARPU_WATCHDOG_TIMEOUT</dt>
-<dd>
-\anchor STARPU_WATCHDOG_TIMEOUT
-\addindex __env__STARPU_WATCHDOG_TIMEOUT
-When set to a value other than 0, allows to make StarPU print an error
-message whenever StarPU does not terminate any task for 10ms. Should
-be used in combination with \ref STARPU_WATCHDOG_CRASH (see \ref
-DetectionStuckConditions).
-</dd>
-
-<dt>STARPU_WATCHDOG_CRASH</dt>
-<dd>
-\anchor STARPU_WATCHDOG_CRASH
-\addindex __env__STARPU_WATCHDOG_CRASH
-When set to a value other than 0, it triggers a crash when the watch
-dog is reached, thus allowing to catch the situation in gdb, etc
-(see \ref DetectionStuckConditions)
-</dd>
-
-<dt>STARPU_HISTORY_MAX_ERROR</dt>
-<dd>
-\anchor STARPU_HISTORY_MAX_ERROR
-\addindex __env__STARPU_HISTORY_MAX_ERROR
-History-based performance models will drop measurements which are really far
-froom the measured average. This specifies the allowed variation. The default is
-10, i.e. the measurement is allowed to be 110% faster or 110% slower than the
-average.
-</dd>
-
-</dl>
-
-\section ConfiguringTheHypervisor Configuring The Hypervisor
-
-<dl>
-
-<dt>SC_HYPERVISOR_POLICY</dt>
-<dd>
-\anchor SC_HYPERVISOR_POLICY
-\addindex __env__SC_HYPERVISOR_POLICY
-Choose between the different resizing policies proposed by StarPU for the hypervisor: 
-idle, app_driven, feft_lp, teft_lp; ispeed_lp, throughput_lp etc.
-
-Use <c>SC_HYPERVISOR_POLICY=help</c> to get the list of available policies for the hypervisor
-</dd>
-
-<dt>SC_HYPERVISOR_TRIGGER_RESIZE</dt>
-<dd>
-\anchor SC_HYPERVISOR_TRIGGER_RESIZE
-\addindex __env__SC_HYPERVISOR_TRIGGER_RESIZE
-Choose how should the hypervisor be triggered: <c>speed</c> if the resizing algorithm should
-be called whenever the speed of the context does not correspond to an optimal precomputed value,
-<c>idle</c> it the resizing algorithm should be called whenever the workers are idle for a period
-longer than the value indicated when configuring the hypervisor.
-</dd>
-
-<dt>SC_HYPERVISOR_START_RESIZE</dt>
-<dd>
-\anchor SC_HYPERVISOR_START_RESIZE
-\addindex __env__SC_HYPERVISOR_START_RESIZE
-Indicate the moment when the resizing should be available. The value correspond to the percentage
-of the total time of execution of the application. The default value is the resizing frame.
-</dd>
-
-<dt>SC_HYPERVISOR_MAX_SPEED_GAP</dt>
-<dd>
-\anchor SC_HYPERVISOR_MAX_SPEED_GAP
-\addindex __env__SC_HYPERVISOR_MAX_SPEED_GAP
-Indicate the ratio of speed difference between contexts that should trigger the hypervisor.
-This situation may occur only when a theoretical speed could not be computed and the hypervisor
-has no value to compare the speed to. Otherwise the resizing of a context is not influenced by the 
-the speed of the other contexts, but only by the the value that a context should have.
-</dd>
-
-<dt>SC_HYPERVISOR_STOP_PRINT</dt>
-<dd>
-\anchor SC_HYPERVISOR_STOP_PRINT
-\addindex __env__SC_HYPERVISOR_STOP_PRINT
-By default the values of the speed of the workers is printed during the execution
-of the application. If the value 1 is given to this environment variable this printing
-is not done.
-</dd>
-
-<dt>SC_HYPERVISOR_LAZY_RESIZE</dt>
-<dd>
-\anchor SC_HYPERVISOR_LAZY_RESIZE
-\addindex __env__SC_HYPERVISOR_LAZY_RESIZE
-By default the hypervisor resizes the contexts in a lazy way, that is workers are firstly added to a new context
-before removing them from the previous one. Once this workers are clearly taken into account 
-into the new context (a task was poped there) we remove them from the previous one. However if the application
-would like that the change in the distribution of workers should change right away this variable should be set to 0
-</dd>
-
-<dt>SC_HYPERVISOR_SAMPLE_CRITERIA</dt>
-<dd>
-\anchor SC_HYPERVISOR_SAMPLE_CRITERIA
-\addindex __env__SC_HYPERVISOR_SAMPLE_CRITERIA
-By default the hypervisor uses a sample of flops when computing the speed of the contexts and of the workers.
-If this variable is set to <c>time</c> the hypervisor uses a sample of time (10% of an aproximation of the total
-execution time of the application)
-</dd>
-
-</dl>
-
-*/

doc/doxygen/chapters/files.doxy

@@ -1,53 +0,0 @@
-/*
- * This file is part of the StarPU Handbook.
- * Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
- * Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
- * Copyright (C) 2011, 2012 Institut National de Recherche en Informatique et Automatique
- * See the file version.doxy for copying conditions.
-*/
-
-/*! \page Files Files
-
-\file starpu_deprecated_api.h
-\file starpu.h
-\file starpu_data_filters.h
-\file starpu_data_interfaces.h
-\file starpu_disk.h
-\file starpu_worker.h
-\file starpu_task.h
-\file starpu_task_bundle.h
-\file starpu_task_list.h
-\file starpu_task_util.h
-\file starpu_data.h
-\file starpu_perfmodel.h
-\file starpu_util.h
-\file starpu_fxt.h
-\file starpu_cuda.h
-\file starpu_opencl.h
-\file starpu_sink.h
-\file starpu_mic.h
-\file starpu_scc.h
-\file starpu_expert.h
-\file starpu_profiling.h
-\file starpu_bound.h
-\file starpu_scheduler.h
-\file starpu_sched_component.h
-\file starpu_sched_ctx.h
-\file starpu_sched_ctx_hypervisor.h
-\file starpu_top.h
-\file starpu_hash.h
-\file starpu_rand.h
-\file starpu_cublas.h
-\file starpu_driver.h
-\file starpu_stdlib.h
-\file starpu_thread.h
-\file starpu_thread_util.h
-\file starpu_mpi.h
-\file sc_hypervisor.h
-\file sc_hypervisor_config.h
-\file sc_hypervisor_lp.h
-\file sc_hypervisor_monitoring.h
-\file sc_hypervisor_policy.h
-\file starpu_config.h
-
-*/

doc/doxygen/chapters/introduction.doxy

@@ -1,246 +0,0 @@
-/*
- * This file is part of the StarPU Handbook.
- * Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
- * Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
- * Copyright (C) 2011, 2012 Institut National de Recherche en Informatique et Automatique
- * See the file version.doxy for copying conditions.
-*/
-
-/*! \mainpage Introduction
-
-\htmlonly
-<h1><a class="anchor" id="Foreword"></a>Foreword</h1>
-\endhtmlonly
-\htmlinclude version.html
-\htmlinclude foreword.html
-
-\section Motivation Motivation
-
-\internal
-complex machines with heterogeneous cores/devices
-\endinternal
-
-The use of specialized hardware such as accelerators or coprocessors offers an
-interesting approach to overcome the physical limits encountered by processor
-architects. As a result, many machines are now equipped with one or several
-accelerators (e.g. a GPU), in addition to the usual processor(s). While a lot of
-efforts have been devoted to offload computation onto such accelerators, very
-little attention as been paid to portability concerns on the one hand, and to the
-possibility of having heterogeneous accelerators and processors to interact on the other hand.
-
-StarPU is a runtime system that offers support for heterogeneous multicore
-architectures, it not only offers a unified view of the computational resources
-(i.e. CPUs and accelerators at the same time), but it also takes care of
-efficiently mapping and executing tasks onto an heterogeneous machine while
-transparently handling low-level issues such as data transfers in a portable
-fashion.
-
-\internal
-this leads to a complicated distributed memory design
-which is not (easily) manageable by hand
-
-added value/benefits of StarPU
-   - portability
-   - scheduling, perf. portability
-\endinternal
-
-\section StarPUInANutshell StarPU in a Nutshell
-
-StarPU is a software tool aiming to allow programmers to exploit the
-computing power of the available CPUs and GPUs, while relieving them
-from the need to specially adapt their programs to the target machine
-and processing units.
-
-At the core of StarPU is its run-time support library, which is
-responsible for scheduling application-provided tasks on heterogeneous
-CPU/GPU machines.  In addition, StarPU comes with programming language
-support, in the form of extensions to languages of the C family
-(\ref cExtensions), as well as an OpenCL front-end (\ref SOCLOpenclExtensions).
-
-StarPU's run-time and programming language extensions support a
-task-based programming model. Applications submit computational
-tasks, with CPU and/or GPU implementations, and StarPU schedules these
-tasks and associated data transfers on available CPUs and GPUs.  The
-data that a task manipulates are automatically transferred among
-accelerators and the main memory, so that programmers are freed from the
-scheduling issues and technical details associated with these transfers.
-
-StarPU takes particular care of scheduling tasks efficiently, using
-well-known algorithms from the literature (\ref TaskSchedulingPolicy).
-In addition, it allows scheduling experts, such as compiler or
-computational library developers, to implement custom scheduling
-policies in a portable fashion (\ref DefiningANewSchedulingPolicy).
-
-The remainder of this section describes the main concepts used in StarPU.
-
-\internal
-explain the notion of codelet and task (i.e. g(A, B)
-\endinternal
-
-\subsection CodeletAndTasks Codelet and Tasks
-
-One of the StarPU primary data structures is the \b codelet. A codelet describes a
-computational kernel that can possibly be implemented on multiple architectures
-such as a CPU, a CUDA device or an OpenCL device.
-
-\internal
-TODO insert illustration f: f_spu, f_cpu, ...
-\endinternal
-
-Another important data structure is the \b task. Executing a StarPU task
-consists in applying a codelet on a data set, on one of the architectures on
-which the codelet is implemented. A task thus describes the codelet that it
-uses, but also which data are accessed, and how they are
-accessed during the computation (read and/or write).
-StarPU tasks are asynchronous: submitting a task to StarPU is a non-blocking
-operation. The task structure can also specify a \b callback function that is
-called once StarPU has properly executed the task. It also contains optional
-fields that the application may use to give hints to the scheduler (such as
-priority levels).
-
-By default, task dependencies are inferred from data dependency (sequential
-coherence) by StarPU. The application can however disable sequential coherency
-for some data, and dependencies be expressed by hand.
-A task may be identified by a unique 64-bit number chosen by the application
-which we refer as a \b tag.
-Task dependencies can be enforced by hand either by the means of callback functions, by
-submitting other tasks, or by expressing dependencies
-between tags (which can thus correspond to tasks that have not been submitted
-yet).
-
-\internal
-TODO insert illustration f(Ar, Brw, Cr) + ..
-\endinternal
-
-\internal
-DSM
-\endinternal
-
-\subsection StarPUDataManagementLibrary StarPU Data Management Library
-
-Because StarPU schedules tasks at runtime, data transfers have to be
-done automatically and ``just-in-time'' between processing units,
-relieving the application programmer from explicit data transfers.
-Moreover, to avoid unnecessary transfers, StarPU keeps data
-where it was last needed, even if was modified there, and it
-allows multiple copies of the same data to reside at the same time on
-several processing units as long as it is not modified.
-
-\section ApplicationTaskification Application Taskification
-
-TODO
-
-\internal
-TODO: section describing what taskifying an application means: before
-porting to StarPU, turn the program into:
-"pure" functions, which only access data from their passed parameters
-a main function which just calls these pure functions
-
-and then it's trivial to use StarPU or any other kind of task-based library:
-simply replace calling the function with submitting a task.
-\endinternal
-
-\section Glossary Glossary
-
-A \b codelet records pointers to various implementations of the same
-theoretical function.
-
-A <b>memory node</b> can be either the main RAM, GPU-embedded memory or a disk memory.
-
-A \b bus is a link between memory nodes.
-
-A <b>data handle</b> keeps track of replicates of the same data (\b registered by the
-application) over various memory nodes. The data management library manages
-keeping them coherent.
-
-The \b home memory node of a data handle is the memory node from which the data
-was registered (usually the main memory node).
-
-A \b task represents a scheduled execution of a codelet on some data handles.
-
-A \b tag is a rendez-vous point. Tasks typically have their own tag, and can
-depend on other tags. The value is chosen by the application.
-
-A \b worker execute tasks. There is typically one per CPU computation core and
-one per accelerator (for which a whole CPU core is dedicated).
-
-A \b driver drives a given kind of workers. There are currently CPU, CUDA,
-and OpenCL drivers. They usually start several workers to actually drive
-them.
-
-A <b>performance model</b> is a (dynamic or static) model of the performance of a
-given codelet. Codelets can have execution time performance model as well as
-power consumption performance models.
-
-A data \b interface describes the layout of the data: for a vector, a pointer
-for the start, the number of elements and the size of elements ; for a matrix, a
-pointer for the start, the number of elements per row, the offset between rows,
-and the size of each element ; etc. To access their data, codelet functions are
-given interfaces for the local memory node replicates of the data handles of the
-scheduled task.
-
-\b Partitioning data means dividing the data of a given data handle (called
-\b father) into a series of \b children data handles which designate various
-portions of the former.
-
-A \b filter is the function which computes children data handles from a father
-data handle, and thus describes how the partitioning should be done (horizontal,
-vertical, etc.)
-
-\b Acquiring a data handle can be done from the main application, to safely
-access the data of a data handle from its home node, without having to
-unregister it.
-
-
-\section ResearchPapers Research Papers
-
-Research papers about StarPU can be found at
-http://runtime.bordeaux.inria.fr/Publis/Keyword/STARPU.html.
-
-A good overview is available in the research report at
-http://hal.archives-ouvertes.fr/inria-00467677.
-
-\section FurtherReading Further Reading
-
-The documentation chapters include
-
-<ol>
-<li> Part: Using StarPU
-<ul>
-<li> \ref BuildingAndInstallingStarPU
-<li> \ref BasicExamples
-<li> \ref AdvancedExamples
-<li> \ref HowToOptimizePerformanceWithStarPU
-<li> \ref PerformanceFeedback
-<li> \ref TipsAndTricksToKnowAbout
-<li> \ref OutOfCore
-<li> \ref MPISupport
-<li> \ref FFTSupport
-<li> \ref MICSCCSupport
-<li> \ref cExtensions
-<li> \ref SOCLOpenclExtensions
-<li> \ref SchedulingContexts
-<li> \ref ModularizedScheduler
-<li> \ref SchedulingContextHypervisor
-<li> \ref ModularizedScheduler
-</ul>
-</li>
-<li> Part: Inside StarPU
-<ul>
-<li> \ref ExecutionConfigurationThroughEnvironmentVariables
-<li> \ref CompilationConfiguration
-<li> \ref ModuleDocumentation
-<li> \ref FileDocumentation
-<li> \ref deprecated
-</ul>
-<li> Part: Appendix
-<ul>
-<li> \ref FullSourceCodeVectorScal
-<li> \ref GNUFreeDocumentationLicense
-</ul>
-</ol>
-
-
-Make sure to have had a look at those too!
-
-*/