Yeppp!
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Functions

Functions

enum YepStatus yepLibrary_GetCpuCyclesAcquire (Yep64u *state)
 Initializes the processor cycle counter and starts counting the processor cycles. More...
 
enum YepStatus yepLibrary_GetCpuCyclesRelease (Yep64u *state, Yep64u *cycles)
 Stops counting the processor cycles, releases the system resources associated with the cycle counter, and returns the number of cycles elapsed. More...
 

Detailed Description

Function Documentation

enum YepStatus yepLibrary_GetCpuCyclesAcquire ( Yep64u state)

Initializes the processor cycle counter and starts counting the processor cycles.

In the current implementation this function can use:

  • RDTSC or RDTSCP instructions on x86 and x86-64.
  • ITC register on IA64.
  • Linux perf events subsystem on ARM and MIPS. This option requires unrestricted access to perf events subsystem (file /proc/sys/kernel/perf_event_paranoid should contain 0 or -1, if this file does not exist, the kernel is compiled without perf events subsystem).
  • PMCCNTR register on ARM if user-mode access to performance counters is enabled and the counter is properly configured. This option is intended for use with the kernel-mode driver in drivers/arm_pmu directory in Yeppp! distribution. This option provides only 32-bit cycle counter.
    Warning
    The state is not guaranteed to be the current processor cycle counter value, and should not be used as such.
    This function may allocate system resources. To avoid resource leak, always match a successfull call to yepLibrary_GetCpuCyclesAcquire with a call to yepLibrary_GetCpuCyclesRelease.
    The cycle counters are not guaranteed to be syncronized across different processors/cores in a multiprocessor/multicore system. It is recommended to bind the current thread to a particular logical processor before using this function.
    Parameters
    [out]statePointer to a variable where the state of the cycle counter will be stored. If the function fails, the value of the state variable is not changed.
    Return values
    YepStatusOkThe cycle counter successfully initialized and its state is stored to the variable pointed by state parameter.
    YepStatusNullPointerThe state pointer is null.
    YepStatusUnsupportedHardwareThe processor does not have cycle counter.
    YepStatusUnsupportedSoftwareThe operating system does not provide access to the CPU cycle counter.
    YepStatusSystemErrorAn attempt to initialize cycle counter failed inside the OS kernel.
    See Also
    yepLibrary_GetCpuCyclesRelease
Examples:
CpuCycles.c.
enum YepStatus yepLibrary_GetCpuCyclesRelease ( Yep64u state,
Yep64u cycles 
)

Stops counting the processor cycles, releases the system resources associated with the cycle counter, and returns the number of cycles elapsed.

Parameters
[in,out]statePointer to a variable with the state of the cycle counter saved by yepLibrary_GetCpuCyclesAcquire. The cycle counter should be released only once, and the function zeroes out the state variable.
[out]cyclesPointer to a variable where the number of cycles elapsed will be stored. The pointer can be the same as state pointer.
Return values
YepStatusOkThe number of cycles elapsed is saved to the variable pointed by cycles parameter, and the system resources are successfully released.
YepStatusNullPointerEither the state pointer or the cycles pointer is null.
YepStatusInvalidStateThe state variable does not specify a valid state of the cycle counter. This can happen if the state variable was not initialized, or it was released previously.
YepStatusUnsupportedHardwareThe processor does not have cycle counter.
YepStatusUnsupportedSoftwareThe operating system does not provide access to the CPU cycle counter.
YepStatusSystemErrorAn attempt to read the cycle counter or release the OS resources failed inside the OS kernel.
See Also
yepLibrary_GetCpuCyclesAcquire
Examples:
CpuCycles.c.