BeBOP Optimized Sparse Kernel Interface Library  1.0.1h
Data Structures | Defines | Typedefs | Functions
trace.h File Reference

Implements a database for keeping track of kernel calls. More...

#include <oski/common.h>
#include <oski/simplelist.h>

Go to the source code of this file.

Data Structures

struct  oski_tracerec_t
 A trace record that stores the number of times a kernel has been (and/or will be) called with a particular argument list. More...

Defines

#define INC_OSKI_TRACE_H
 oski/trace.h included.
#define INVALID_TRACEREC   ((oski_tracerec_t *)NULL)
 NULL trace record.
#define INVALID_TRACE   ((oski_trace_t)NULL)
 NULL trace.
#define TIME_NOT_AVAIL   ((double)(-1.0))
 Time not available.
#define oski_RecordCall(trace, id, args, args_size, func, time_elapsed)   oski_RecordCalls(trace, id, args, args_size, func, 1, time_elapsed)
 Wrapper around oski_RecordCalls assuming just 1 call.

Typedefs

typedef int(* oski_traceargscmp_funcpt )(const void *a, const void *b)
 Type for a function to compare two trace arguments of the same type.
typedef simplelist_toski_trace_t
 A trace is a list of kernel calls and their argument signatures.

Functions

oski_trace_t oski_CreateTrace (void)
 Create and return a new trace.
void oski_DestroyTrace (oski_trace_t trace)
 Destroy a trace.
int oski_RecordCalls (oski_trace_t trace, oski_id_t kernel_id, const void *args, size_t args_bytes, oski_traceargscmp_funcpt func_compare, size_t num_new_calls, double time_elapsed)
 Save a kernel call to a trace.
size_t oski_GetNumCalls (const oski_trace_t trace, oski_id_t kernel_id, const void *args, size_t args_bytes, oski_traceargscmp_funcpt func_compare)
 Returns the frequency of a particular kernel call for all matching records.
int oski_MatchesTraceRecord (const oski_tracerec_t *rec, oski_id_t kernel_id, const void *args, size_t args_bytes, oski_traceargscmp_funcpt func_compare)
 Returns 1 if a given trace record matches a query request, or 0 otherwise.

Detailed Description

Implements a database for keeping track of kernel calls.


Define Documentation

oski/trace.h included.

#define INVALID_TRACE   ((oski_trace_t)NULL)
#define oski_RecordCall (   trace,
  id,
  args,
  args_size,
  func,
  time_elapsed 
)    oski_RecordCalls(trace, id, args, args_size, func, 1, time_elapsed)

Wrapper around oski_RecordCalls assuming just 1 call.

Referenced by oski_MatMult(), oski_MatMultAndMatTransMult(), oski_MatPowMult(), oski_MatTransMatMult(), and oski_MatTrisolve().

#define TIME_NOT_AVAIL   ((double)(-1.0))

Typedef Documentation

typedef int(* oski_traceargscmp_funcpt)(const void *a, const void *b)

Type for a function to compare two trace arguments of the same type.

This type is a pointer to a comparison function f(a, b) where a and b are pointers to kernel-specific argument lists (i.e., the 'args' field of a oski_tracerec_t structure).

When an object of this type is passed to one of the routines below, then the first argument `a' is ALWAYS the trace argument list for the record stored in the trace, and second argument `b' is the trace argument list being sought.


Function Documentation

Create and return a new trace.

References oski_CreateTrace(), and simplelist_Create().

Referenced by oski_CreateMatStruct(), and oski_CreateTrace().

size_t oski_GetNumCalls ( const oski_trace_t  trace,
oski_id_t  kernel_id,
const void *  args,
size_t  args_bytes,
oski_traceargscmp_funcpt  func_compare 
)

Returns the frequency of a particular kernel call for all matching records.

Parameters:
[in]traceTrace to search.
[in]kernel_idID# of the kernel to find.
[in]argsKernel-specific argument list. If set to NULL, then match any record with kernel ID# kernel_id.
[in]args_bytesSize of object pointed to by 'args' in bytes.
[in]func_compareFunction to perform record-matching comparison. If NULL, then do a byte-wise comparison.
Returns:
The total number of calls across all records that match according to the comparison function, func_compare.

References oski_tracerec_t::num_calls, oski_GetNumCalls(), oski_MatchesTraceRecord(), simplelist_GetElem(), and simplelist_GetLength().

Referenced by oski_GetNumCalls().

int oski_MatchesTraceRecord ( const oski_tracerec_t rec,
oski_id_t  kernel_id,
const void *  args,
size_t  args_bytes,
oski_traceargscmp_funcpt  func_compare 
)

Returns 1 if a given trace record matches a query request, or 0 otherwise.

Parameters:
[in]recTrace record to test.
[in]kernel_idKernel to match, or INVALID_ID to match any kernel.
[in]argsArguments of the given kernel. (Ignored if kernel_id == INVALID_ID.)
[in]args_bytesSize of 'args' in bytes. (Ignored if kernel_id == INVALID_ID.)
[in]func_compareA pointer to a user-defined function $f(a, b)$ to compare two kernel-specific argument lists, $a$ and $b$. If func_compare == NULL, then byte-wise comparisons are used by default. (Ignored if kernel_id == INVALID_ID.)
Returns:
1 if 'rec' matches the query request, ('kernel_id', 'args', 'args_bytes', 'func_compare'), or 0 otherwise. If 'rec' == INVALID_TRACREC, this routine returns 0.

References oski_tracerec_t::args, INVALID_ID, INVALID_TRACEREC, oski_tracerec_t::kernel_id, and oski_MatchesTraceRecord().

Referenced by oski_CountTraceFlopsPerNz(), oski_EstimateTraceTime(), oski_GetNumCalls(), oski_MatchesTraceRecord(), and oski_RecordCalls().

int oski_RecordCalls ( oski_trace_t  trace,
oski_id_t  kernel_id,
const void *  args,
size_t  args_bytes,
oski_traceargscmp_funcpt  func_compare,
size_t  num_new_calls,
double  time_elapsed 
)

Save a kernel call to a trace.

Parameters:
[in,out]traceTrace to search and update.
[in]kernel_idID# of the kernel.
[in]argsKernel-specific argument list. If set to NULL, then the caller requests that the update occur to the first record matching just kernel_id.
[in]args_bytesSize of the data pointed to by args, in bytes.
[in]func_compareFunction to perform record-matching comparison. If set to NULL, then a default function that performs bit-wise equality comparison is used.
[in]num_new_callsNumber of calls to record.
[in]time_elapsedNumber of seconds of execution time due to these calls, or TIME_NOT_AVAIL.

This routine searches for the first record (one with lowest ID#) in the trace that "matches" the given kernel. A match means that the following two conditions hold:

  1. func_compare(record->args, args) == 0 OR record->args == NULL OR args == NULL.
  2. (time_elapsed < 0) == (record->time_elapsed < 0)

If a matching record cannot be found, then a new one is created.

Returns:
0 on success. If trace of kernel_id are invalid, returns an error code (ERR_BAD_ARG) and takes no action. If there is not enough memory to create a new trace record, returns ERR_OUT_OF_MEMORY.

References oski_tracerec_t::args, oski_tracerec_t::args_bytes, ERR_BAD_ARG, ERR_OUT_OF_MEMORY, oski_tracerec_t::id, INVALID_ID, INVALID_TRACE, oski_tracerec_t::kernel_id, oski_tracerec_t::num_calls, oski_CopyMem, oski_Free, oski_Malloc, oski_MatchesTraceRecord(), oski_RecordCalls(), simplelist_Append(), simplelist_GetElem(), simplelist_GetLength(), and oski_tracerec_t::time_elapsed.

Referenced by oski_RecordCalls(), oski_SetHintMatMult(), oski_SetHintMatMultAndMatTransMult(), oski_SetHintMatPowMult(), oski_SetHintMatTransMatMult(), and oski_SetHintMatTrisolve().