cf4ocl (C Framework for OpenCL)  v2.1.0
Object-oriented framework for developing and benchmarking OpenCL projects in C/C++
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
ccl_profiler.h
Go to the documentation of this file.
1 /*
2  * This file is part of cf4ocl (C Framework for OpenCL).
3  *
4  * cf4ocl is free software: you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License as
6  * published by the Free Software Foundation, either version 3 of the
7  * License, or (at your option) any later version.
8  *
9  * cf4ocl is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12  * GNU Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with cf4ocl. If not, see
16  * <http://www.gnu.org/licenses/>.
17  * */
18 
29 #ifndef _CCL_PROFILER_H_
30 #define _CCL_PROFILER_H_
31 
32 #include <string.h>
33 #include "ccl_errors.h"
34 #include "ccl_common.h"
35 #include "ccl_queue_wrapper.h"
36 
210 typedef struct ccl_prof CCLProf;
211 
215 typedef enum {
221 
222 
226 typedef struct ccl_prof_agg {
227 
232  const char* event_name;
233 
239  cl_ulong absolute_time;
240 
246  double relative_time;
247 
248 } CCLProfAgg;
249 
250 
254 typedef enum {
255 
258 
261 
263 
267 typedef struct ccl_prof_info {
268 
273  const char* event_name;
274 
279  cl_command_type command_type;
280 
285  const char* queue_name;
286 
292  cl_ulong t_queued;
293 
300  cl_ulong t_submit;
301 
307  cl_ulong t_start;
308 
314  cl_ulong t_end;
315 
316 } CCLProfInfo;
317 
321 typedef enum {
322 
325 
328 
331 
334 
337 
340 
342 
343 
347 typedef enum {
348 
351 
354 
356 
360 typedef struct ccl_prof_inst {
361 
366  const char* event_name;
367 
372  const char* queue_name;
373 
378  cl_uint id;
379 
384  cl_ulong instant;
385 
392 
393 } CCLProfInst;
394 
398 typedef enum {
399 
402 
405 
407 
411 typedef struct ccl_prof_overlap {
412 
417  const char* event1_name;
418 
423  const char* event2_name;
424 
429  cl_ulong duration;
430 
432 
436 typedef enum {
437 
440 
443 
445 
449 typedef struct ccl_prof_export_options {
450 
455  const char* separator;
456 
461  const char* newline;
462 
467  const char* queue_delim;
468 
473  const char* evname_delim;
474 
479  cl_bool zero_start;
480 
482 
483 /* Create a new profile object. */
484 CCL_EXPORT
486 
487 /* Destroy a profile object. */
488 CCL_EXPORT
489 void ccl_prof_destroy(CCLProf* prof);
490 
491 /* Starts the global profiler timer. Only required if client
492 * wishes to compare the effectively ellapsed time with the OpenCL
493 * kernels time. */
494 CCL_EXPORT
495 void ccl_prof_start(CCLProf* prof);
496 
497 /* Stops the global profiler timer. Only required if
498  * ccl_prof_start() was called. */
499 CCL_EXPORT
500 void ccl_prof_stop(CCLProf* prof);
501 
502 /* If profiling has started but not stopped, returns the time
503  * since the profiling started. If profiling has been stopped, returns
504  * the elapsed time between the time it started and the time it stopped. */
505 CCL_EXPORT
506 double ccl_prof_time_elapsed(CCLProf* prof);
507 
508 /* Add a command queue wrapper for profiling. */
509 CCL_EXPORT
510 void ccl_prof_add_queue(
511  CCLProf* prof, const char* cq_name, CCLQueue* cq);
512 
513 /* Determine aggregate statistics for the given profile object. */
514 CCL_EXPORT
515 cl_bool ccl_prof_calc(CCLProf* prof, CCLErr** err);
516 
517 /* Return aggregate statistics for events with the given name. */
518 CCL_EXPORT
520  CCLProf* prof, const char* event_name);
521 
522 /* Initialize an iterator for profiled aggregate event
523  * instances. */
524 CCL_EXPORT
525 void ccl_prof_iter_agg_init(CCLProf* prof, int sort);
526 
527 /* Return the next profiled aggregate event instance. */
528 CCL_EXPORT
530 
531 /* Initialize an iterator for event profiling info instances. */
532 CCL_EXPORT
533 void ccl_prof_iter_info_init(CCLProf* prof, int sort);
534 
535 /* Return the next event profiling info instance. */
536 CCL_EXPORT
538 
539 /* Initialize an iterator for event instant instances. */
540 CCL_EXPORT
541 void ccl_prof_iter_inst_init(CCLProf* prof, int sort);
542 
543 /* Return the next event instant instance. */
544 CCL_EXPORT
546 
547 /* Initialize an iterator for overlap instances. */
548 CCL_EXPORT
549 void ccl_prof_iter_overlap_init(CCLProf* prof, int sort);
550 
551 /* Return the next overlap instance. */
552 CCL_EXPORT
554 
555 /* Get duration of all events in nanoseconds. */
556 CCL_EXPORT
557 cl_ulong ccl_prof_get_duration(CCLProf* prof);
558 
559 /* Get effective duration of all events in nanoseconds, i.e. the
560  * duration of all events minus event overlaps. */
561 CCL_EXPORT
562 cl_ulong ccl_prof_get_eff_duration(CCLProf* prof);
563 
564 /* Print a summary of the profiling info. More specifically,
565  * this function prints a table of aggregate event statistics (sorted
566  * by absolute time), and a table of event overlaps (sorted by overlap
567  * duration). */
568 CCL_EXPORT
569 void ccl_prof_print_summary(CCLProf* prof);
570 
571 /* Get a summary with the profiling info. More specifically,
572  * this function returns a string containing a table of aggregate event
573  * statistics and a table of event overlaps. The order of the returned
574  * information can be specified in the function arguments. */
575 CCL_EXPORT
576 const char* ccl_prof_get_summary(
577  CCLProf* prof, int agg_sort, int ovlp_sort);
578 
579 /* Export profiling info to a given stream. */
580 CCL_EXPORT
581 cl_bool ccl_prof_export_info(CCLProf* profile, FILE* stream, CCLErr** err);
582 
583 /* Helper function which exports profiling info to a given file,
584  * automatically opening and closing the file. Check the
585  * ccl_prof_export_info() for more information. */
586 CCL_EXPORT
588  CCLProf* profile, const char* filename, CCLErr** err);
589 
590 /* Set export options using a ::CCLProfExportOptions struct. */
591 CCL_EXPORT
593 
594 /* Get current export options. */
595 CCL_EXPORT
597 
600 #endif
Export options.
Definition: ccl_profiler.h:449
struct ccl_prof_info CCLProfInfo
Event profiling info.
Sort event profiling info instances by end time.
Definition: ccl_profiler.h:339
Sort descending.
Definition: ccl_profiler.h:219
cl_bool ccl_prof_export_info_file(CCLProf *prof, const char *filename, CCLErr **err)
Helper function which exports profiling info to a given file, automatically opening and closing the f...
const char * queue_name
Name of command queue which generated this event.
Definition: ccl_profiler.h:285
cl_ulong t_submit
Device time counter in nanoseconds when the command identified by event that has been enqueued is sub...
Definition: ccl_profiler.h:300
Sort event profiling info instances by queued time.
Definition: ccl_profiler.h:330
struct ccl_prof_overlap CCLProfOverlap
Representation of an overlap of events.
void ccl_prof_iter_overlap_init(CCLProf *prof, int sort)
Initialize an iterator for overlap instances.
double ccl_prof_time_elapsed(CCLProf *prof)
If profiling has started but not stopped, returns the time since the profiling started.
Start event instant.
Definition: ccl_profiler.h:350
cl_ulong duration
Overlap duration in nanoseconds.
Definition: ccl_profiler.h:429
CCLProfAggSort
Sort criteria for aggregate event info instances.
Definition: ccl_profiler.h:254
cl_ulong ccl_prof_get_duration(CCLProf *prof)
Get duration of all events in nanoseconds.
Representation of an overlap of events.
Definition: ccl_profiler.h:411
Sort overlaps by event name.
Definition: ccl_profiler.h:439
const char * event_name
Name of event which the instant refers to.
Definition: ccl_profiler.h:232
cl_bool ccl_prof_calc(CCLProf *prof, CCLErr **err)
Determine aggregate statistics for the given profile object.
void ccl_prof_iter_agg_init(CCLProf *prof, int sort)
Initialize an iterator for profiled aggregate event instances.
cl_bool zero_start
Start at instant 0 (TRUE, default), or start at oldest instant returned by OpenCL (FALSE)...
Definition: ccl_profiler.h:479
Sort ascending (default).
Definition: ccl_profiler.h:217
Sort overlaps by overlap duration.
Definition: ccl_profiler.h:442
Command queue wrapper class.
End event instant.
Definition: ccl_profiler.h:353
CCLProf * ccl_prof_new()
Create a new profile object.
Sort event profiling info instances by event name.
Definition: ccl_profiler.h:324
const char * evname_delim
Event name delimiter, defaults to empty string.
Definition: ccl_profiler.h:473
cl_ulong t_start
Device time in nanoseconds when the command identified by event starts execution on the device...
Definition: ccl_profiler.h:307
cl_ulong ccl_prof_get_eff_duration(CCLProf *prof)
Get effective duration of all events in nanoseconds, i.e.
Sort event profiling info instances by submit time.
Definition: ccl_profiler.h:333
void ccl_prof_stop(CCLProf *prof)
Stops the global profiler timer.
Sort event instants by event id.
Definition: ccl_profiler.h:404
const CCLProfInfo * ccl_prof_iter_info_next(CCLProf *prof)
Return the next event profiling info instance.
void ccl_prof_start(CCLProf *prof)
Starts the global profiler timer.
const char * ccl_prof_get_summary(CCLProf *prof, int agg_sort, int ovlp_sort)
Get a summary with the profiling info.
const CCLProfAgg * ccl_prof_get_agg(CCLProf *prof, const char *event_name)
Return aggregate statistics for events with the given name.
const CCLProfOverlap * ccl_prof_iter_overlap_next(CCLProf *prof)
Return the next overlap instance.
Sort aggregate event data instances by name.
Definition: ccl_profiler.h:257
cl_command_type command_type
Type of command which produced the event.
Definition: ccl_profiler.h:279
cl_uint id
Event instant ID.
Definition: ccl_profiler.h:378
Sort event profiling info instances by start time.
Definition: ccl_profiler.h:336
struct ccl_prof_inst CCLProfInst
Event instant.
CCLProfOverlapSort
Sort criteria for overlaps (CCLProfOverlap).
Definition: ccl_profiler.h:436
struct ccl_prof_export_options CCLProfExportOptions
Export options.
Sort aggregate event data instances by time.
Definition: ccl_profiler.h:260
Aggregate event info.
Definition: ccl_profiler.h:226
void ccl_prof_destroy(CCLProf *prof)
Destroy a profile object.
cl_bool ccl_prof_export_info(CCLProf *prof, FILE *stream, CCLErr **err)
Export event profiling information to a given stream.
void ccl_prof_iter_inst_init(CCLProf *prof, int sort)
Initialize an iterator for event instant instances.
const char * queue_delim
Queue name delimiter, defaults to empty string.
Definition: ccl_profiler.h:467
CCLProfExportOptions ccl_prof_get_export_opts()
Get current export options.
void ccl_prof_set_export_opts(CCLProfExportOptions export_opts)
Set export options using a CCLProfExportOptions struct.
cl_ulong t_queued
Device time in nanoseconds when the command identified by event is enqueued in a command-queue by the...
Definition: ccl_profiler.h:292
const CCLProfInst * ccl_prof_iter_inst_next(CCLProf *prof)
Return the next event instant instance.
void ccl_prof_add_queue(CCLProf *prof, const char *cq_name, CCLQueue *cq)
Add a command queue wrapper for profiling.
const char * event2_name
Name of second overlapping event.
Definition: ccl_profiler.h:423
cl_ulong instant
Event instant in nanoseconds from current device time counter.
Definition: ccl_profiler.h:384
Sort event profiling info instances by queue name.
Definition: ccl_profiler.h:327
struct ccl_prof_agg CCLProfAgg
Aggregate event info.
void ccl_prof_iter_info_init(CCLProf *prof, int sort)
Initialize an iterator for event profiling info instances.
GError CCLErr
Error handling class.
Definition: ccl_common.h:291
Definition of a wrapper class and its methods for OpenCL queue objects.
Common cf4ocl definitions.
Event profiling info.
Definition: ccl_profiler.h:267
const char * event1_name
Name of first overlapping event.
Definition: ccl_profiler.h:417
Event instant.
Definition: ccl_profiler.h:360
const char * separator
Field separator, defaults to tab (\t).
Definition: ccl_profiler.h:455
CCLProfInfoSort
Sort criteria for event profiling info instances.
Definition: ccl_profiler.h:321
void ccl_prof_print_summary(CCLProf *prof)
Print a summary of the profiling info.
CCLProfSortOrder
Sort order for the profile module iterators.
Definition: ccl_profiler.h:215
double relative_time
Relative time of events with name equal to CCLProfAgg::event_name.
Definition: ccl_profiler.h:246
Profile class, contains profiling information of OpenCL queues and events.
Definition: ccl_profiler.c:91
Convert OpenCL error codes to readable strings (function header).
CCLProfInstSort
Sort criteria for event instants (CCLProfInst).
Definition: ccl_profiler.h:398
cl_ulong t_end
Device time in nanoseconds when the command identified by event has finished execution on the device...
Definition: ccl_profiler.h:314
CCLProfInstType type
Type of event instant (CCL_PROF_INST_TYPE_START or CCL_PROF_INST_TYPE_END).
Definition: ccl_profiler.h:391
const char * newline
Newline character, Defaults to Unix newline (\n).
Definition: ccl_profiler.h:461
cl_ulong absolute_time
Total (absolute) time of events with name equal to CCLProfAgg::event_name.
Definition: ccl_profiler.h:239
CCLProfInstType
Type of event instant (CCLProfInst).
Definition: ccl_profiler.h:347
const CCLProfAgg * ccl_prof_iter_agg_next(CCLProf *prof)
Return the next aggregate statistic instance.
Sort event instants by instant.
Definition: ccl_profiler.h:401