Files
externals/linux/include/celoxica/cpu_timestamp.h
T
2017-10-04 14:16:02 -04:00

131 lines
5.1 KiB
C

/****************************************************************
* *
* Copyright (C) 1991-2008 Celoxica Ltd. All rights reserved. *
* *
*****************************************************************
* *
* Project : CPU Timestamps *
* Date : 12 JUN 2008 *
* File : cpu_timestamp.h *
* Author : Will Benfold (WB) *
* Contributors: *
* *
* Description: *
* Reads CPU timestamp using RDTSCP *
* - Corrects for TSC skew *
* - Measures CPU freq for conversion to nsecs *
* *
* Date Version Author Reason for change *
* *
* 12 JUN 2008 1.00 WB Created *
* *
****************************************************************/
#include <stdint.h>
#ifndef __CELOXICA_CPU_TIMESTAMP_H__
#define __CELOXICA_CPU_TIMESTAMP_H__
#ifdef __cplusplus
extern "C" {
#endif
/* These routines require the 'RDTSC' instruction, which may not be present
* on some architectures.
*/
/* Measure the TSC rate and per-CPU skew. This must be called before the
* other functions.
*
* The calibration process involves creating extra threads, and requires
* true concurrent execution. Non-preemptible processes may delay
* calibration indefinitely. Calibration takes significant time, so should
* be performed as part of initialisation, outside of performance-critical
* code.
*
* CAVEAT: Calibration will produce inaccurate results without warning if
* the process is pre-empted at precisely the wrong moment. The
* workaround to prevent this rather rare problem is to switch to
* the SCHED_FIFO scheduler for calibration.
*
*
* There is some useful information on the validity of TSC measuresments at:
* - http://opensolaris.org/os/community/performance/technical_docs/amd_tsc_power
*
* To summarize, the CPU frequency must be kept constant. Errors will
* creep in as a result of
* - "C-state" changes (enter/exit idle loop) (small rounding error)
* - The STPCLK mechanism (throttling initiated by chipset)
*
* Arguments:
* Force Perform calibration even if it has already been done
* Debug List timestamp skews on stderr
*
* Returns:
* Zero on success, nonzero on failure (e.g. clock_gettime failed).
*/
int CPUTimestampCalibrate (int Force, int Debug);
/*
* Returns whether the library was calibrated or not.
*/
int CPUTimestampIsCalibrated ();
/* Read a corrected timestamp.
*
* CPUTimestampCalibrate should be called at some point before this function
* is used, or results may be inaccurate.
*
* The caller is responsible for ensuring that the CurrentCPU parameter is
* accurate, and that the process is not migrated during this call.
*
* Arguments:
* CurrentCPU The CPU to which the current process is confined
*/
uint64_t CPUTimestampReadTicks (int CurrentCPU);
/* Read an uncorrected timestamp
*
* Calibration is not required. May be used if all timestamps will be taken
* from the same CPU core, or if skew is known to be insignificant. Note
* that this will often be true of the skew between two cores on the same
* die.
*
* The caller is responsible for ensuring that the process is not migrated
* during this call.
*
*/
uint64_t CPUTimestampReadTicksRaw (void);
/* Approximately convert timestamp ticks to nanoseconds.
*
* CPUTimestampCalibrate must be called at some point before this function
* is used.
*
* Calibration is imperfect, and will provide a conversion factor accurate
* only to a few decimal places. The result of this function is therefore
* suitable for presenting a result in human-readable form, but may not be
* appropriate as input to a calculation, especially if combined with other
* results from independent calibrations.
*
* For instance, two processes which independently convert absolute
* timestamps to nsecs prior to comparison will see unexpected results, as,
* the difference will be very small compared to the absolute values, and
* will be insignificant compared to the error introduced by using slightly
* different conversion factors. The simple solution is to subtract the
* timestamps and then convert the result.
*/
int64_t CPUTimestampTicksToNS (int64_t Ticks);
double CPUTimestampTicksToNSEx (int64_t Ticks);
int64_t CPUTimestampNSToTicks (int64_t NanoSecs);
double CPUTimestampNSToTicksEx (int64_t NanoSecs);
#ifdef __cplusplus
}
#endif
#endif //__CELOXICA_CPU_TIMESTAMP_H__