Generated from ./inc/complib/cl_perf.h with ROBODoc v4.99.17 on Sun Mar 04 2007 18:17:51

[Modules] Component Library/Performance Counters

[top][parent][index]

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

[Definitions] Component Library: Performance Counters/cl_perf_clr

[top][index]

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

[Functions] Component Library: Performance Counters/cl_perf_construct

[top][index]

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

[Functions] Component Library: Performance Counters/cl_perf_destroy

[top][index]

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

[Functions] Component Library: Performance Counters/cl_perf_display

[top][index]

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

[Definitions] Component Library: Performance Counters/cl_perf_inc

[top][index]

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

[Functions] Component Library: Performance Counters/cl_perf_init

[top][index]

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

[Definitions] Component Library: Performance Counters/cl_perf_log

[top][index]

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

[Functions] Component Library: Performance Counters/cl_perf_reset

[top][index]

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

[Definitions] Component Library: Performance Counters/cl_perf_start

[top][index]

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

[Definitions] Component Library: Performance Counters/cl_perf_stop

[top][index]

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

[Definitions] Component Library: Performance Counters/cl_perf_update

[top][index]

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

[Definitions] Component Library: Performance Counters/cl_perf_update_ctr

[top][index]

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

[Definitions] Component Library: Performance Counters/PERF_DECLARE

[top][index]

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

[Definitions] Component Library: Performance Counters/PERF_DECLARE_START

[top][index]

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