ccl_profiler.h

Go to the documentation of this file.

/*
 * This file is part of cf4ocl (C Framework for OpenCL).
 *
 * cf4ocl 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 3 of the
 * License, or (at your option) any later version.
 *
 * cf4ocl 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 for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with cf4ocl. If not, see
 * <http://www.gnu.org/licenses/>.
 * */

#ifndef _CCL_PROFILER_H_
#define _CCL_PROFILER_H_

#include <string.h>
#include "ccl_errors.h"
#include "ccl_common.h"
#include "ccl_queue_wrapper.h"

typedef struct ccl_prof CCLProf;

typedef enum {
    CCL_PROF_SORT_ASC  = 0x0,
    CCL_PROF_SORT_DESC = 0x1
} CCLProfSortOrder;


typedef struct ccl_prof_agg {

    const char* event_name;

    cl_ulong absolute_time;

    double relative_time;

} CCLProfAgg;


typedef enum {

    CCL_PROF_AGG_SORT_NAME = 0x00,

    CCL_PROF_AGG_SORT_TIME = 0x10

} CCLProfAggSort;

typedef struct ccl_prof_info {

    const char* event_name;

    cl_command_type command_type;

    const char* queue_name;

    cl_ulong t_queued;

    cl_ulong t_submit;

    cl_ulong t_start;

    cl_ulong t_end;

} CCLProfInfo;

typedef enum {

    CCL_PROF_INFO_SORT_NAME_EVENT = 0x20,

    CCL_PROF_INFO_SORT_NAME_QUEUE = 0x30,

    CCL_PROF_INFO_SORT_T_QUEUED   = 0x40,

    CCL_PROF_INFO_SORT_T_SUBMIT   = 0x50,

    CCL_PROF_INFO_SORT_T_START    = 0x60,

    CCL_PROF_INFO_SORT_T_END      = 0x70

} CCLProfInfoSort;


typedef enum {

    CCL_PROF_INST_TYPE_START,

    CCL_PROF_INST_TYPE_END

} CCLProfInstType;

typedef struct ccl_prof_inst {

    const char* event_name;

    const char* queue_name;

    cl_uint id;

    cl_ulong instant;

    CCLProfInstType type;

} CCLProfInst;

typedef enum {

    CCL_PROF_INST_SORT_INSTANT = 0x80,

    CCL_PROF_INST_SORT_ID      = 0x90

} CCLProfInstSort;

typedef struct ccl_prof_overlap {

    const char* event1_name;

    const char* event2_name;

    cl_ulong duration;

} CCLProfOverlap;

typedef enum {

    CCL_PROF_OVERLAP_SORT_NAME     = 0xa0,

    CCL_PROF_OVERLAP_SORT_DURATION = 0xb0

} CCLProfOverlapSort;

typedef struct ccl_prof_export_options {

    const char* separator;

    const char* newline;

    const char* queue_delim;

    const char* evname_delim;

    cl_bool zero_start;

}  CCLProfExportOptions;

/* Create a new profile object. */
CCL_EXPORT
CCLProf* ccl_prof_new();

/* Destroy a profile object. */
CCL_EXPORT
void ccl_prof_destroy(CCLProf* prof);

/* Starts the global profiler timer. Only required if client
* wishes to compare the effectively ellapsed time with the OpenCL
* kernels time. */
CCL_EXPORT
void ccl_prof_start(CCLProf* prof);

/* Stops the global profiler timer. Only required if
 * ccl_prof_start() was called. */
CCL_EXPORT
void ccl_prof_stop(CCLProf* prof);

/* If profiling has started but not stopped, returns the time
 * since the profiling started. If profiling has been stopped, returns
 * the elapsed time between the time it started and the time it stopped. */
CCL_EXPORT
double ccl_prof_time_elapsed(CCLProf* prof);

/* Add a command queue wrapper for profiling. */
CCL_EXPORT
void ccl_prof_add_queue(
    CCLProf* prof, const char* cq_name, CCLQueue* cq);

/* Determine aggregate statistics for the given profile object. */
CCL_EXPORT
cl_bool ccl_prof_calc(CCLProf* prof, CCLErr** err);

/* Return aggregate statistics for events with the given name. */
CCL_EXPORT
const CCLProfAgg* ccl_prof_get_agg(
    CCLProf* prof, const char* event_name);

/* Initialize an iterator for profiled aggregate event
 * instances. */
CCL_EXPORT
void ccl_prof_iter_agg_init(CCLProf* prof, int sort);

/* Return the next profiled aggregate event instance. */
CCL_EXPORT
const CCLProfAgg* ccl_prof_iter_agg_next(CCLProf* prof);

/* Initialize an iterator for event profiling info instances. */
CCL_EXPORT
void ccl_prof_iter_info_init(CCLProf* prof, int sort);

/* Return the next event profiling info instance. */
CCL_EXPORT
const CCLProfInfo* ccl_prof_iter_info_next(CCLProf* prof);

/* Initialize an iterator for event instant instances. */
CCL_EXPORT
void ccl_prof_iter_inst_init(CCLProf* prof, int sort);

/* Return the next event instant instance. */
CCL_EXPORT
const CCLProfInst* ccl_prof_iter_inst_next(CCLProf* prof);

/* Initialize an iterator for overlap instances. */
CCL_EXPORT
void ccl_prof_iter_overlap_init(CCLProf* prof, int sort);

/* Return the next overlap instance. */
CCL_EXPORT
const CCLProfOverlap* ccl_prof_iter_overlap_next(CCLProf* prof);

/* Get duration of all events in nanoseconds. */
CCL_EXPORT
cl_ulong ccl_prof_get_duration(CCLProf* prof);

/* Get effective duration of all events in nanoseconds, i.e. the
 * duration of all events minus event overlaps. */
CCL_EXPORT
cl_ulong ccl_prof_get_eff_duration(CCLProf* prof);

/* Print a summary of the profiling info. More specifically,
 * this function prints a table of aggregate event statistics (sorted
 * by absolute time), and a table of event overlaps (sorted by overlap
 * duration). */
CCL_EXPORT
void ccl_prof_print_summary(CCLProf* prof);

/* Get a summary with the profiling info. More specifically,
 * this function returns a string containing a table of aggregate event
 * statistics and a table of event overlaps. The order of the returned
 * information can be specified in the function arguments. */
CCL_EXPORT
const char* ccl_prof_get_summary(
    CCLProf* prof, int agg_sort, int ovlp_sort);

/* Export profiling info to a given stream. */
CCL_EXPORT
cl_bool ccl_prof_export_info(CCLProf* profile, FILE* stream, CCLErr** err);

/* Helper function which exports profiling info to a given file,
 * automatically opening and closing the file. Check the
 * ccl_prof_export_info() for more information. */
CCL_EXPORT
cl_bool ccl_prof_export_info_file(
    CCLProf* profile, const char* filename, CCLErr** err);

/* Set export options using a ::CCLProfExportOptions struct. */
CCL_EXPORT
void ccl_prof_set_export_opts(CCLProfExportOptions export_opts);

/* Get current export options. */
CCL_EXPORT
CCLProfExportOptions ccl_prof_get_export_opts();

#endif