NAME
Performance Counters
DESCRIPTION
The performance counters allows timing operations to benchmark
software performance and help identify potential bottlenecks.
All performance counters are NULL macros when disabled, preventing them
from adversly affecting performance in builds where the counters are not
used.
Each counter records elapsed time in micro-seconds, minimum time elapsed,
and total number of samples.
Each counter is independently protected by a spinlock, allowing use of
the counters in multi-processor environments.
The impact of serializing access to performance counters is measured,
allowing measurements to be corrected as necessary.
NOTES
Performance counters do impact performance, and should only be enabled
when gathering data. Counters can be enabled or disabled on a per-user
basis at compile time. To enable the counters, users should define
the PERF_TRACK_ON keyword before including the cl_perf.h file.
Undefining the PERF_TRACK_ON keyword disables the performance counters.
When disabled, all performance tracking calls resolve to no-ops.
When using performance counters, it is the user's responsibility to
maintain the counter indexes. It is recomended that users define an
enumerated type to use for counter indexes. It improves readability
and simplifies maintenance by reducing the work necessary in managing
the counter indexes.
SEE ALSO
Structures:
cl_perf_t
Initialization:
cl_perf_construct, cl_perf_init, cl_perf_destroy
Manipulation
cl_perf_reset, cl_perf_display, cl_perf_start, cl_perf_update,
cl_perf_log, cl_perf_stop
Macros:
PERF_DECLARE, PERF_DECLARE_START
NAME
cl_perf_clr
DESCRIPTION
The cl_perf_clr macro clears a counter variable.
SYNOPSIS
void
cl_perf_inc(
IN const uintn_t index );
PARAMETERS
index
[in] Index of the performance counter to set.
NOTES
This macro has no effect when performance counters are disabled.
SEE ALSO
Performance Counters, PERF_DECLARE, PERF_DECLARE_START, cl_perf_log,
cl_perf_update, cl_perf_stop
NAME
cl_perf_construct
DESCRIPTION
The cl_perf_construct macro constructs a performance
tracking container.
SYNOPSIS
void
cl_perf_construct(
IN cl_perf_t* const p_perf );
PARAMETERS
p_perf
[in] Pointer to a performance counter container to construct.
RETURN VALUE
This function does not return a value.
NOTES
cl_perf_construct allows calling cl_perf_destroy without first calling
cl_perf_init.
Calling cl_perf_construct is a prerequisite to calling any other
perfromance counter function except cl_perf_init.
This function is implemented as a macro and has no effect when
performance counters are disabled.
SEE ALSO
Performance Counters, cl_perf_init, cl_perf_destroy
NAME
cl_perf_destroy
DESCRIPTION
The cl_perf_destroy function destroys a performance tracking container.
SYNOPSIS
void
cl_perf_destroy(
IN cl_perf_t* const p_perf,
IN const boolean_t display );
PARAMETERS
p_perf
[in] Pointer to a performance counter container to destroy.
display
[in] If TRUE, causes the performance counters to be displayed.
RETURN VALUE
This function does not return a value.
NOTES
cl_perf_destroy frees all resources allocated in a call to cl_perf_init.
If the display parameter is set to TRUE, displays all counter values
before deallocating resources.
This function should only be called after a call to cl_perf_construct
or cl_perf_init.
This function is implemented as a macro and has no effect when
performance counters are disabled.
SEE ALSO
Performance Counters, cl_perf_construct, cl_perf_init
NAME
cl_perf_display
DESCRIPTION
The cl_perf_display function displays the current performance
counter values.
SYNOPSIS
void
cl_perf_display(
IN const cl_perf_t* const p_perf );
PARAMETERS
p_perf
[in] Pointer to a performance counter container whose counter
values to display.
RETURN VALUE
This function does not return a value.
NOTES
This function is implemented as a macro and has no effect when
performance counters are disabled.
SEE ALSO
Performance Counters, cl_perf_init
NAME
cl_perf_inc
DESCRIPTION
The cl_perf_inc macro increments a counter variable by one.
SYNOPSIS
void
cl_perf_inc(
IN const uintn_t index );
PARAMETERS
index
[in] Index of the performance counter to set.
NOTES
This macro has no effect when performance counters are disabled.
SEE ALSO
Performance Counters, PERF_DECLARE, PERF_DECLARE_START, cl_perf_log,
cl_perf_update, cl_perf_stop
NAME
cl_perf_init
DESCRIPTION
The cl_perf_init function initializes a performance counter container
for use.
SYNOPSIS
cl_status_t
cl_perf_init(
IN cl_perf_t* const p_perf,
IN const uintn_t num_counters );
PARAMETERS
p_perf
[in] Pointer to a performance counter container to initalize.
num_cntrs
[in] Number of counters to allocate in the container.
RETURN VALUES
CL_SUCCESS if initialization was successful.
CL_INSUFFICIENT_MEMORY if there was not enough memory to initialize
the container.
CL_ERROR if an error was encountered initializing the locks for the
performance counters.
NOTES
This function allocates all memory required for the requested number of
counters and initializes all locks protecting those counters. After a
successful initialization, cl_perf_init calibrates the counters and
resets their value.
This function is implemented as a macro and has no effect when
performance counters are disabled.
SEE ALSO
Performance Counters, cl_perf_construct, cl_perf_destroy, cl_perf_display
NAME
cl_perf_log
DESCRIPTION
The cl_perf_log macro adds a given timing sample to a
counter in a performance counter container.
SYNOPSIS
void
cl_perf_log(
IN cl_perf_t* const p_perf,
IN const uintn_t index,
IN const uint64_t pc_total_time );
PARAMETERS
p_perf
[in] Pointer to a performance counter container to whose counter
the sample should be added.
index
[in] Number of the performance counter to update with a new sample.
pc_total_time
[in] Total elapsed time for the sample being added.
RETURN VALUE
This function does not return a value.
NOTES
This macro has no effect when performance counters are disabled.
SEE ALSO
Performance Counters, PERF_DECLARE, PERF_DECLARE_START, cl_perf_start,
cl_perf_update, cl_perf_stop
NAME
cl_perf_reset
DESCRIPTION
The cl_perf_reset function resets the counters contained in
a performance tracking container.
SYNOPSIS
void
cl_perf_reset(
IN cl_perf_t* const p_perf );
PARAMETERS
p_perf
[in] Pointer to a performance counter container whose counters
to reset.
RETURN VALUE
This function does not return a value.
NOTES
This function is implemented as a macro and has no effect when
performance counters are disabled.
SEE ALSO
Performance Counters
NAME
cl_perf_start
DESCRIPTION
The cl_perf_start macro sets the starting value of a timed sequence.
SYNOPSIS
void
cl_perf_start(
IN const uintn_t index );
PARAMETERS
index
[in] Index of the performance counter to set.
NOTES
This macro has no effect when performance counters are disabled.
SEE ALSO
Performance Counters, PERF_DECLARE, PERF_DECLARE_START, cl_perf_log,
cl_perf_update, cl_perf_stop
NAME
cl_perf_stop
DESCRIPTION
The cl_perf_log macro updates a counter in a performance counter
container with a new timing sample.
SYNOPSIS
void
cl_perf_stop(
IN cl_perf_t* const p_perf,
IN const uintn_t index );
PARAMETERS
p_perf
[in] Pointer to a performance counter container to whose counter
a sample should be added.
index
[in] Number of the performance counter to update with a new sample.
RETURN VALUE
This function does not return a value.
NOTES
The ending time stamp is taken and elapsed time calculated before updating
the specified counter.
This macro has no effect when performance counters are disabled.
SEE ALSO
Performance Counters, PERF_DECLARE, PERF_DECLARE_START, cl_perf_start,
cl_perf_log
NAME
cl_perf_update
DESCRIPTION
The cl_perf_update macro adds a timing sample based on a provided start
time to a counter in a performance counter container.
SYNOPSIS
void
cl_perf_update(
IN cl_perf_t* const p_perf,
IN const uintn_t index,
IN const uint64_t start_time );
PARAMETERS
p_perf
[in] Pointer to a performance counter container to whose counter
the sample should be added.
index
[in] Number of the performance counter to update with a new sample.
start_time
[in] Timestamp to use as the start time for the timing sample.
RETURN VALUE
This function does not return a value.
NOTES
This macro has no effect when performance counters are disabled.
SEE ALSO
Performance Counters, PERF_DECLARE, PERF_DECLARE_START, cl_perf_start,
cl_perf_lob, cl_perf_stop
NAME
cl_perf_update_ctr
DESCRIPTION
The cl_perf_update_ctr macro updates a counter in a performance
counter container.
SYNOPSIS
void
cl_perf_update_ctr(
IN cl_perf_t* const p_perf,
IN const uintn_t index );
PARAMETERS
p_perf
[in] Pointer to a performance counter container to whose counter
the sample should be added.
index
[in] Number of the performance counter to update with a new sample.
RETURN VALUE
This function does not return a value.
NOTES
This macro has no effect when performance counters are disabled.
SEE ALSO
Performance Counters, PERF_DECLARE, PERF_DECLARE_START, cl_perf_start,
cl_perf_lob, cl_perf_stop
NAME
PERF_DECLARE
DESCRIPTION
The PERF_DECLARE macro declares a performance counter variable used
to store the starting time of a timing sequence.
SYNOPSIS
* PERF_DECLARE( index )
PARAMETERS
index
[in] Index of the performance counter for which to use this
variable.
NOTES
Variables should generally be declared on the stack to support
multi-threading. In cases where a counter needs to be used to
time operations accross multiple functions, care must be taken to
ensure that the start time stored in this variable is not overwritten
before the related performance counter has been updated.
This macro has no effect when performance counters are disabled.
SEE ALSO
Performance Counters, PERF_DECLARE_START, cl_perf_start, cl_perf_log,
cl_perf_stop
NAME
PERF_DECLARE_START
DESCRIPTION
The PERF_DECLARE_START macro declares a performance counter variable
and sets it to the starting time of a timed sequence.
SYNOPSIS
* PERF_DECLARE_START( index )
PARAMETERS
index
[in] Index of the performance counter for which to use this
variable.
NOTES
Variables should generally be declared on the stack to support
multi-threading.
This macro has no effect when performance counters are disabled.
SEE ALSO
Performance Counters, PERF_DECLARE, cl_perf_start, cl_perf_log,
cl_perf_stop