/* StarPU --- Runtime system for heterogeneous multicore architectures. * * Copyright (C) 2010-2015,2017 CNRS * Copyright (C) 2009-2011,2014,2016,2018-2019 Université de Bordeaux * Copyright (C) 2011,2012 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_Profiling Profiling \struct starpu_profiling_task_info \ingroup API_Profiling This structure contains information about the execution of a task. It is accessible from the field starpu_task::profiling_info if profiling was enabled. \var struct timespec starpu_profiling_task_info::submit_time Date of task submission (relative to the initialization of StarPU). \var struct timespec starpu_profiling_task_info::push_start_time Time when the task was submitted to the scheduler. \var struct timespec starpu_profiling_task_info::push_end_time Time when the scheduler finished with the task submission. \var struct timespec starpu_profiling_task_info::pop_start_time Time when the scheduler started to be requested for a task, and eventually gave that task. \var struct timespec starpu_profiling_task_info::pop_end_time Time when the scheduler finished providing the task for execution. \var struct timespec starpu_profiling_task_info::acquire_data_start_time Time when the worker started fetching input data. \var struct timespec starpu_profiling_task_info::acquire_data_end_time Time when the worker finished fetching input data. \var struct timespec starpu_profiling_task_info::start_time Date of task execution beginning (relative to the initialization of StarPU). \var struct timespec starpu_profiling_task_info::end_time Date of task execution termination (relative to the initialization of StarPU). \var struct timespec starpu_profiling_task_info::release_data_start_time Time when the worker started releasing data. \var struct timespec starpu_profiling_task_info::release_data_end_time Time when the worker finished releasing data. \var struct timespec starpu_profiling_task_info::callback_start_time Time when the worker started the application callback for the task. \var struct timespec starpu_profiling_task_info::callback_end_time Time when the worker finished the application callback for the task. \var int starpu_profiling_task_info::workerid Identifier of the worker which has executed the task. \var uint64_t starpu_profiling_task_info::used_cycles Number of cycles used by the task, only available in the MoviSim \var uint64_t starpu_profiling_task_info::stall_cycles Number of cycles stalled within the task, only available in the MoviSim \var double starpu_profiling_task_info::energy_consumed Energy consumed by the task, in Joules \struct starpu_profiling_worker_info This structure contains the profiling information associated to a worker. The timing is provided since the previous call to starpu_profiling_worker_get_info() \ingroup API_Profiling \var struct timespec starpu_profiling_worker_info::start_time Starting date for the reported profiling measurements. \var struct timespec starpu_profiling_worker_info::total_time Duration of the profiling measurement interval. \var struct timespec starpu_profiling_worker_info::executing_time Time spent by the worker to execute tasks during the profiling measurement interval. \var struct timespec starpu_profiling_worker_info::sleeping_time Time spent idling by the worker during the profiling measurement interval. \var int starpu_profiling_worker_info::executed_tasks Number of tasks executed by the worker during the profiling measurement interval. \var uint64_t starpu_profiling_worker_info::used_cycles Number of cycles used by the worker, only available in the MoviSim \var uint64_t starpu_profiling_worker_info::stall_cycles Number of cycles stalled within the worker, only available in the MoviSim \var double starpu_profiling_worker_info::energy_consumed Energy consumed by the worker, in Joules \struct starpu_profiling_bus_info todo \ingroup API_Profiling \var struct timespec starpu_profiling_bus_info::start_time Time of bus profiling startup. \var struct timespec starpu_profiling_bus_info::total_time Total time of bus profiling. \var int long long starpu_profiling_bus_info::transferred_bytes Number of bytes transferred during profiling. \var int starpu_profiling_bus_info::transfer_count Number of transfers during profiling. \typedef STARPU_PROFILING_DISABLE \ingroup API_Profiling Used when calling the function starpu_profiling_status_set() to disable profiling. \typedef STARPU_PROFILING_ENABLE \ingroup API_Profiling Used when calling the function starpu_profiling_status_set() to enable profiling. \fn int starpu_profiling_status_set(int status) \ingroup API_Profiling Set the profiling status. Profiling is activated by passing \ref STARPU_PROFILING_ENABLE in \p status. Passing \ref STARPU_PROFILING_DISABLE disables profiling. Calling this function resets all profiling measurements. When profiling is enabled, the field starpu_task::profiling_info points to a valid structure starpu_profiling_task_info containing information about the execution of the task. Negative return values indicate an error, otherwise the previous status is returned. \fn int starpu_profiling_status_get(void) \ingroup API_Profiling Return the current profiling status or a negative value in case there was an error. \fn void starpu_profiling_init(void) \ingroup API_Profiling Reset performance counters and enable profiling if the environment variable \ref STARPU_PROFILING is set to a positive value. \fn void starpu_profiling_set_id(int new_id) \ingroup API_Profiling Set the ID used for profiling trace filename. HAS to be called before starpu_init(). \fn int starpu_profiling_worker_get_info(int workerid, struct starpu_profiling_worker_info *worker_info) \ingroup API_Profiling Get the profiling info associated to the worker identified by \p workerid, and reset the profiling measurements. If the argument \p worker_info is NULL, only reset the counters associated to worker \p workerid. Upon successful completion, this function returns 0. Otherwise, a negative value is returned. \fn int starpu_bus_get_profiling_info(int busid, struct starpu_profiling_bus_info *bus_info) \ingroup API_Profiling todo See _starpu_profiling_bus_helper_display_summary in src/profiling/profiling_helpers.c for a usage example. Note that calling starpu_bus_get_profiling_info resets the counters to zero. \fn int starpu_bus_get_count(void) \ingroup API_Profiling Return the number of buses in the machine \fn int starpu_bus_get_id(int src, int dst) \ingroup API_Profiling Return the identifier of the bus between \p src and \p dst \fn int starpu_bus_get_src(int busid) \ingroup API_Profiling Return the source point of bus \p busid \fn int starpu_bus_get_dst(int busid) \ingroup API_Profiling Return the destination point of bus \p busid \fn double starpu_timing_timespec_delay_us(struct timespec *start, struct timespec *end) \ingroup API_Profiling Return the time elapsed between \p start and \p end in microseconds. \fn double starpu_timing_timespec_to_us(struct timespec *ts) \ingroup API_Profiling Convert the given timespec \p ts into microseconds \fn void starpu_profiling_bus_helper_display_summary(void) \ingroup API_Profiling Display statistics about the bus on \c stderr. if the environment variable \ref STARPU_BUS_STATS is defined. The function is called automatically by starpu_shutdown(). \fn void starpu_profiling_worker_helper_display_summary(void) \ingroup API_Profiling Displays statistic about the workers on \c stderr if the environment variable \ref STARPU_WORKER_STATS is defined. The function is called automatically by starpu_shutdown(). \fn void starpu_data_display_memory_stats() \ingroup API_Profiling Display statistics about the current data handles registered within StarPU. StarPU must have been configured with the configure option \ref enable-memory-stats "--enable-memory-stats" (see \ref MemoryFeedback). */