trace.h File Reference

---

Detailed Description

Implements a database for keeping track of kernel calls.

#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_t *	oski_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.

---

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

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]  trace  Trace to search. [in]  kernel_id  ID# of the kernel to find. [in]  args  Kernel-specific argument list. If set to NULL, then match any record with kernel ID# kernel_id. [in]  args_bytes  Size of object pointed to by 'args' in bytes. [in]  func_compare  Function 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.

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]  rec  Trace record to test. [in]  kernel_id  Kernel to match, or INVALID_ID to match any kernel. [in]  args  Arguments of the given kernel. (Ignored if kernel_id == INVALID_ID.) [in]  args_bytes  Size of 'args' in bytes. (Ignored if kernel_id == INVALID_ID.) [in]  func_compare  A pointer to a user-defined function to compare two kernel-specific argument lists, and . 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.

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]  trace  Trace to search and update. [in]  kernel_id  ID# of the kernel. [in]  args  Kernel-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_bytes  Size of the data pointed to by args, in bytes. [in]  func_compare  Function to perform record-matching comparison. If set to NULL, then a default function that performs bit-wise equality comparison is used. [in]  num_new_calls  Number of calls to record. [in]  time_elapsed  Number 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: func_compare(record->args, args) == 0 OR record->args == NULL OR args == NULL. (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.

---