|
|
@@ -0,0 +1,358 @@
|
|
|
+/* StarPU --- Runtime system for heterogeneous multicore architectures.
|
|
|
+ *
|
|
|
+ * Copyright (C) 2018 Inria
|
|
|
+ *
|
|
|
+ * 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.
|
|
|
+ */
|
|
|
+
|
|
|
+/*! \defgroup API_Interop_Support Interoperability Support
|
|
|
+
|
|
|
+\brief This section describes the interface supplied by StarPU to interoperate with other runtime systems.
|
|
|
+
|
|
|
+\enum e_starpurm_drs_ret
|
|
|
+\ingroup API_Interop_Support
|
|
|
+StarPU Resource Manager return type.
|
|
|
+\var starpurm_drs_ret::starpurm_DRS_SUCCESS
|
|
|
+ Dynamic resource sharing operation succeeded.
|
|
|
+\var starpurm_drs_ret::starpurm_DRS_DISABLD
|
|
|
+ Dynamic resource sharing is disabled.
|
|
|
+\var starpurm_drs_ret::starpurm_DRS_PERM
|
|
|
+ Dynamic resource sharing operation is not authorized or implemented.
|
|
|
+\var starpurm_drs_ret::starpurm_DRS_EINVAL
|
|
|
+ Dynamic resource sharing operation has been called with one or more invalid parameters.
|
|
|
+
|
|
|
+@name Initialisation
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+\fn void starpurm_initialize(void)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Initialize StarPU and the StarPU-RM resource management module. The \ref starpu_init function should not have been called before the call to \c starpurm_initialize. The \c starpurm_initialize function will take care of this
|
|
|
+
|
|
|
+\fn void starpurm_shutdown(void)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Shutdown StarPU-RM and StarPU. The \ref starpu_shutdown function should not be called before. The \c starpurm_shutdown function will take care of this.
|
|
|
+
|
|
|
+
|
|
|
+@name Spawn
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+\fn void starpurm_spawn_kernel_on_cpus(void *data, void(*f)(void *), void *args, hwloc_cpuset_t cpuset)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Allocate a temporary context spanning the units selected in the cpuset bitmap,
|
|
|
+set it as the default context for the current thread, and call user function \c f.
|
|
|
+Upon the return of user function \c f, the temporary context is freed and the previous
|
|
|
+default context for the current thread is restored.
|
|
|
+
|
|
|
+\fn void starpurm_spawn_kernel_on_cpus_callback(void *data, void(*f)(void *), void *args, hwloc_cpuset_t cpuset, void(*cb_f)(void *), void *cb_args)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Spawn a POSIX thread and returns immediately. The thread spawned will allocate
|
|
|
+a temporary context spanning the units selected in the cpuset bitmap, set it as
|
|
|
+the default context for the current thread, and call user function \c f. Upon
|
|
|
+the return of user function \c f, the temporary context will be freed and the
|
|
|
+previous default context for the current thread restored. A user specified callback \c cb_f
|
|
|
+will be called just before the termination of the thread.
|
|
|
+
|
|
|
+
|
|
|
+@name DynamicResourceSharing
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_set_drs_enable(starpurm_drs_desc_t *spd)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Turn-on dynamic resource sharing support.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_set_drs_disable(starpurm_drs_desc_t *spd)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Turn-off dynamic resource sharing support.
|
|
|
+
|
|
|
+\fn int starpurm_drs_enabled_p(void)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Return the state of the dynamic resource sharing support (\c =!0 enabled, \c =0 disabled).
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_set_max_parallelism(starpurm_drs_desc_t *spd, int max)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Set the maximum number of CPU computing units available for StarPU computations
|
|
|
+to \c max. This number cannot exceed the maximum number of StarPU's CPU worker
|
|
|
+allocated at start-up time.
|
|
|
+
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_assign_cpu_to_starpu(starpurm_drs_desc_t *spd, int cpuid)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Extend StarPU's default scheduling context to execute tasks on worker
|
|
|
+corresponding to logical unit \c cpuid. If StarPU does not have a worker
|
|
|
+thread initialized for logical unit \c cpuid, do nothing.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_assign_cpus_to_starpu(starpurm_drs_desc_t *spd, int ncpus)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Extend StarPU's default scheduling context to execute tasks on \c ncpus
|
|
|
+more workers, up to the number of StarPU worker threads initialized.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_assign_cpu_mask_to_starpu(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Extend StarPU's default scheduling context to execute tasks on the
|
|
|
+additional logical units selected in \c mask. Logical units of \c mask for which no
|
|
|
+StarPU worker is initialized are silently ignored.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_assign_all_cpus_to_starpu(starpurm_drs_desc_t *spd)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Set StarPU's default scheduling context to execute tasks on all
|
|
|
+available logical units for which a StarPU worker has been initialized.
|
|
|
+
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_withdraw_cpu_from_starpu(starpurm_drs_desc_t *spd, int cpuid)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Shrink StarPU's default scheduling context so as to not execute tasks on worker
|
|
|
+corresponding to logical unit \c cpuid. If StarPU does not have a worker
|
|
|
+thread initialized for logical unit \c cpuid, do nothing.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_withdraw_cpus_from_starpu(starpurm_drs_desc_t *spd, int ncpus)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Shrink StarPU's default scheduling context to execute tasks on \c ncpus
|
|
|
+less workers.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_withdraw_cpu_mask_from_starpu(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Shrink StarPU's default scheduling context so as to not execute tasks on the
|
|
|
+logical units selected in \c mask. Logical units of \c mask for which no
|
|
|
+StarPU worker is initialized are silently ignored.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_withdraw_all_cpus_from_starpu(starpurm_drs_desc_t *spd)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Shrink StarPU's default scheduling context so as to remove all logical units.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_lend(starpurm_drs_desc_t *spd)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_all_cpus_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_lend_cpu(starpurm_drs_desc_t *spd, int cpuid)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Synonym for \ref starpurm_assign_cpu_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_lend_cpus(starpurm_drs_desc_t *spd, int ncpus)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_cpus_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_lend_cpu_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_cpu_mask_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_reclaim(starpurm_drs_desc_t *spd)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_all_cpus_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_reclaim_cpu(starpurm_drs_desc_t *spd, int cpuid)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_cpu_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_reclaim_cpus(starpurm_drs_desc_t *spd, int ncpus)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_cpus_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_reclaim_cpu_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_cpu_mask_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_acquire(starpurm_drs_desc_t *spd)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_all_cpus_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_acquire_cpu(starpurm_drs_desc_t *spd, int cpuid)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_cpu_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_acquire_cpus(starpurm_drs_desc_t *spd, int ncpus)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_cpus_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_acquire_cpu_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_cpu_mask_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_return_all(starpurm_drs_desc_t *spd)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_all_cpus_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_return_cpu(starpurm_drs_desc_t *spd, int cpuid)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_cpu_to_starpu.
|
|
|
+
|
|
|
+
|
|
|
+@name Devices
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+\fn int starpurm_get_device_type_id(const char *type_str)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Return the device type ID constant associated to the device type name.
|
|
|
+Valid names for \c type_str are:
|
|
|
+- \c "cpu": regular CPU unit;
|
|
|
+- \c "opencl": OpenCL device unit;
|
|
|
+- \c "cuda": nVidia CUDA device unit;
|
|
|
+- \c "mic": Intel KNC type device unit.
|
|
|
+
|
|
|
+\fn const char *starpurm_get_device_type_name(int type_id)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Return the device type name associated to the device type ID constant.
|
|
|
+
|
|
|
+\fn int starpurm_get_nb_devices_by_type(int type_id)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Return the number of initialized StarPU worker for the device type \c type_id.
|
|
|
+
|
|
|
+\fn int starpurm_get_device_id(int type_id, int device_rank)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Return the unique ID assigned to the \c device_rank nth device of type
|
|
|
+\c type_id.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_assign_device_to_starpu(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Extend StarPU's default scheduling context to use \c unit_rank nth
|
|
|
+device of type \c type_id.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_assign_devices_to_starpu(starpurm_drs_desc_t *spd, int type_id, int ndevices)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Extend StarPU's default scheduling context to use \c ndevices more
|
|
|
+devices of type \c type_id, up to the number of StarPU workers
|
|
|
+initialized for such device type.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_assign_device_mask_to_starpu(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Extend StarPU's default scheduling context to use additional devices as
|
|
|
+designated by their corresponding StarPU worker thread(s) CPU-set \c mask.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_assign_all_devices_to_starpu(starpurm_drs_desc_t *spd, int type_id)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Extend StarPU's default scheduling context to use all devices of type \c
|
|
|
+type_id for which it has a worker thread initialized.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_withdraw_device_from_starpu(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Shrink StarPU's default scheduling context to not use \c unit_rank nth
|
|
|
+device of type \c type_id.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_withdraw_devices_from_starpu(starpurm_drs_desc_t *spd, int type_id, int ndevices)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Shrink StarPU's default scheduling context to use \c ndevices less
|
|
|
+devices of type \c type_id.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_withdraw_device_mask_from_starpu(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Shrink StarPU's default scheduling context to not use devices
|
|
|
+designated by their corresponding StarPU worker thread(s) CPU-set \c mask.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_withdraw_all_devices_from_starpu(starpurm_drs_desc_t *spd, int type_id)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Shrink StarPU's default scheduling context to use no devices of type \c
|
|
|
+type_id.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_lend_device(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_device_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_lend_devices(starpurm_drs_desc_t *spd, int type_id, int ndevices)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_devices_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_lend_device_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_device_mask_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_lend_all_devices(starpurm_drs_desc_t *spd, int type_id)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_all_devices_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_reclaim_device(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_device_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_reclaim_devices(starpurm_drs_desc_t *spd, int type_id, int ndevices)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_devices_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_reclaim_device_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_device_mask_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_reclaim_all_devices(starpurm_drs_desc_t *spd, int type_id)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_all_devices_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_acquire_device(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_device_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_acquire_devices(starpurm_drs_desc_t *spd, int type_id, int ndevices)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_devices_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_acquire_device_mask(starpurm_drs_desc_t *spd, const hwloc_cpuset_t mask)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_device_mask_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_acquire_all_devices(starpurm_drs_desc_t *spd, int type_id)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_withdraw_all_devices_from_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_return_all_devices(starpurm_drs_desc_t *spd, int type_id)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_all_devices_to_starpu.
|
|
|
+
|
|
|
+\fn starpurm_drs_ret_t starpurm_return_device(starpurm_drs_desc_t *spd, int type_id, int unit_rank)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Synonym for \ref starpurm_assign_device_to_starpu.
|
|
|
+
|
|
|
+
|
|
|
+@name CpusetsQueries
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+\fn hwloc_cpuset_t starpurm_get_device_worker_cpuset(int type_id, int unit_rank)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Return the CPU-set of the StarPU worker associated to the \c unit_rank
|
|
|
+nth unit of type \c type_id.
|
|
|
+
|
|
|
+\fn hwloc_cpuset_t starpurm_get_global_cpuset(void)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+Return the cumulated CPU-set of all StarPU worker threads.
|
|
|
+
|
|
|
+\fn hwloc_cpuset_t starpurm_get_selected_cpuset(void)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Return the CPU-set of the StarPU worker threads currently selected in
|
|
|
+the default StarPU's scheduling context.
|
|
|
+
|
|
|
+\fn hwloc_cpuset_t starpurm_get_all_cpu_workers_cpuset(void)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Return the cumulated CPU-set of all CPU StarPU worker threads.
|
|
|
+
|
|
|
+\fn hwloc_cpuset_t starpurm_get_all_device_workers_cpuset(void)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Return the cumulated CPU-set of all "non-CPU" StarPU worker threads.
|
|
|
+
|
|
|
+\fn hwloc_cpuset_t starpurm_get_all_device_workers_cpuset_by_type(int typeid)
|
|
|
+\ingroup API_Interop_Support
|
|
|
+
|
|
|
+Return the cumulated CPU-set of all StarPU worker threads for devices of
|
|
|
+type \c typeid.
|
|
|
+
|
|
|
+*/
|
