Provided by: libcpuid-dev_0.5.1+repack1-1_amd64 
NAME
libcpuid - LibCPUID
- LibCPUID provides CPU identification.
SYNOPSIS
Data Structures
struct cpu_raw_data_t
Contains just the raw CPUID data.
struct cpu_sgx_t
This contains information about SGX features of the processor Example usage:
struct cpu_id_t
This contains the recognized CPU features/info.
struct cpu_mark_t
Internal structure, used in cpu_tsc_mark, cpu_tsc_unmark and cpu_clock_by_mark.
struct cpu_epc_t
The return value of cpuid_get_epc().
struct cpu_list_t
a structure that holds a list of processor names
Macros
#define NUM_CPU_VENDORS NUM_CPU_VENDORS
#define CPU_INVALID_VALUE 0x3fffffff
Typedefs
typedef void(* libcpuid_warn_fn_t) (const char *msg)
Enumerations
enum cpu_vendor_t { VENDOR_INTEL = 0, VENDOR_AMD, VENDOR_CYRIX, VENDOR_NEXGEN,
VENDOR_TRANSMETA, VENDOR_UMC, VENDOR_CENTAUR, VENDOR_RISE, VENDOR_SIS, VENDOR_NSC,
VENDOR_HYGON, NUM_CPU_VENDORS, VENDOR_UNKNOWN = -1 }
CPU vendor, as guessed from the Vendor String.
enum cpu_feature_t { CPU_FEATURE_FPU = 0, CPU_FEATURE_VME, CPU_FEATURE_DE,
CPU_FEATURE_PSE, CPU_FEATURE_TSC, CPU_FEATURE_MSR, CPU_FEATURE_PAE, CPU_FEATURE_MCE,
CPU_FEATURE_CX8, CPU_FEATURE_APIC, CPU_FEATURE_MTRR, CPU_FEATURE_SEP, CPU_FEATURE_PGE,
CPU_FEATURE_MCA, CPU_FEATURE_CMOV, CPU_FEATURE_PAT, CPU_FEATURE_PSE36, CPU_FEATURE_PN,
CPU_FEATURE_CLFLUSH, CPU_FEATURE_DTS, CPU_FEATURE_ACPI, CPU_FEATURE_MMX,
CPU_FEATURE_FXSR, CPU_FEATURE_SSE, CPU_FEATURE_SSE2, CPU_FEATURE_SS, CPU_FEATURE_HT,
CPU_FEATURE_TM, CPU_FEATURE_IA64, CPU_FEATURE_PBE, CPU_FEATURE_PNI,
CPU_FEATURE_PCLMUL, CPU_FEATURE_DTS64, CPU_FEATURE_MONITOR, CPU_FEATURE_DS_CPL,
CPU_FEATURE_VMX, CPU_FEATURE_SMX, CPU_FEATURE_EST, CPU_FEATURE_TM2, CPU_FEATURE_SSSE3,
CPU_FEATURE_CID, CPU_FEATURE_CX16, CPU_FEATURE_XTPR, CPU_FEATURE_PDCM,
CPU_FEATURE_DCA, CPU_FEATURE_SSE4_1, CPU_FEATURE_SSE4_2, CPU_FEATURE_SYSCALL,
CPU_FEATURE_XD, CPU_FEATURE_MOVBE, CPU_FEATURE_POPCNT, CPU_FEATURE_AES,
CPU_FEATURE_XSAVE, CPU_FEATURE_OSXSAVE, CPU_FEATURE_AVX, CPU_FEATURE_MMXEXT,
CPU_FEATURE_3DNOW, CPU_FEATURE_3DNOWEXT, CPU_FEATURE_NX, CPU_FEATURE_FXSR_OPT,
CPU_FEATURE_RDTSCP, CPU_FEATURE_LM, CPU_FEATURE_LAHF_LM, CPU_FEATURE_CMP_LEGACY,
CPU_FEATURE_SVM, CPU_FEATURE_ABM, CPU_FEATURE_MISALIGNSSE, CPU_FEATURE_SSE4A,
CPU_FEATURE_3DNOWPREFETCH, CPU_FEATURE_OSVW, CPU_FEATURE_IBS, CPU_FEATURE_SSE5,
CPU_FEATURE_SKINIT, CPU_FEATURE_WDT, CPU_FEATURE_TS, CPU_FEATURE_FID, CPU_FEATURE_VID,
CPU_FEATURE_TTP, CPU_FEATURE_TM_AMD, CPU_FEATURE_STC, CPU_FEATURE_100MHZSTEPS,
CPU_FEATURE_HWPSTATE, CPU_FEATURE_CONSTANT_TSC, CPU_FEATURE_XOP, CPU_FEATURE_FMA3,
CPU_FEATURE_FMA4, CPU_FEATURE_TBM, CPU_FEATURE_F16C, CPU_FEATURE_RDRAND,
CPU_FEATURE_X2APIC, CPU_FEATURE_CPB, CPU_FEATURE_APERFMPERF, CPU_FEATURE_PFI,
CPU_FEATURE_PA, CPU_FEATURE_AVX2, CPU_FEATURE_BMI1, CPU_FEATURE_BMI2, CPU_FEATURE_HLE,
CPU_FEATURE_RTM, CPU_FEATURE_AVX512F, CPU_FEATURE_AVX512DQ, CPU_FEATURE_AVX512PF,
CPU_FEATURE_AVX512ER, CPU_FEATURE_AVX512CD, CPU_FEATURE_SHA_NI, CPU_FEATURE_AVX512BW,
CPU_FEATURE_AVX512VL, CPU_FEATURE_SGX, CPU_FEATURE_RDSEED, CPU_FEATURE_ADX,
CPU_FEATURE_AVX512VNNI, CPU_FEATURE_AVX512VBMI, CPU_FEATURE_AVX512VBMI2,
NUM_CPU_FEATURES }
CPU feature identifiers.
enum cpu_hint_t { CPU_HINT_SSE_SIZE_AUTH = 0, NUM_CPU_HINTS }
CPU detection hints identifiers.
enum cpu_sgx_feature_t { INTEL_SGX1, INTEL_SGX2, NUM_SGX_FEATURES }
SGX features flags.
enum cpu_error_t { ERR_OK = 0, ERR_NO_CPUID = -1, ERR_NO_RDTSC = -2, ERR_NO_MEM = -3,
ERR_OPEN = -4, ERR_BADFMT = -5, ERR_NOT_IMP = -6, ERR_CPU_UNKN = -7, ERR_NO_RDMSR =
-8, ERR_NO_DRIVER = -9, ERR_NO_PERMS = -10, ERR_EXTRACT = -11, ERR_HANDLE = -12,
ERR_INVMSR = -13, ERR_INVCNB = -14, ERR_HANDLE_R = -15, ERR_INVRANGE = -16 }
Describes common library error codes.
enum cpu_msrinfo_request_t { INFO_MPERF, INFO_APERF, INFO_MIN_MULTIPLIER,
INFO_CUR_MULTIPLIER, INFO_MAX_MULTIPLIER, INFO_TEMPERATURE, INFO_THROTTLING,
INFO_VOLTAGE, INFO_BCLK, INFO_BUS_CLOCK }
Functions
int cpuid_get_total_cpus (void)
Returns the total number of logical CPU threads (even if CPUID is not present).
int cpuid_present (void)
Checks if the CPUID instruction is supported.
void cpu_exec_cpuid (uint32_t eax, uint32_t *regs)
Executes the CPUID instruction.
void cpu_exec_cpuid_ext (uint32_t *regs)
Executes the CPUID instruction with the given input registers.
int cpuid_get_raw_data (struct cpu_raw_data_t *data)
Obtains the raw CPUID data from the current CPU.
int cpuid_serialize_raw_data (struct cpu_raw_data_t *data, const char *filename)
Writes the raw CPUID data to a text file.
int cpuid_deserialize_raw_data (struct cpu_raw_data_t *data, const char *filename)
Reads raw CPUID data from file.
int cpu_identify (struct cpu_raw_data_t *raw, struct cpu_id_t *data)
Identifies the CPU.
const char * cpu_feature_str (cpu_feature_t feature)
Returns the short textual representation of a CPU flag.
const char * cpuid_error (void)
Returns textual description of the last error.
void cpu_rdtsc (uint64_t *result)
Executes RDTSC.
void cpu_tsc_mark (struct cpu_mark_t *mark)
Store TSC and timing info.
void cpu_tsc_unmark (struct cpu_mark_t *mark)
Calculate TSC and timing difference.
int cpu_clock_by_mark (struct cpu_mark_t *mark)
Calculates the CPU clock.
int cpu_clock_by_os (void)
Returns the CPU clock, as reported by the OS.
int cpu_clock_measure (int millis, int quad_check)
Measure the CPU clock frequency.
int cpu_clock_by_ic (int millis, int runs)
Measure the CPU clock frequency using instruction-counting.
int cpu_clock (void)
Get the CPU clock frequency (all-in-one method)
struct cpu_epc_t cpuid_get_epc (int index, const struct cpu_raw_data_t *raw)
Fetches information about an EPC (Enclave Page Cache) area.
const char * cpuid_lib_version (void)
Returns the libcpuid version.
libcpuid_warn_fn_t cpuid_set_warn_function (libcpuid_warn_fn_t warn_fun)
Sets the warning print function.
void cpuid_set_verbosiness_level (int level)
Sets the verbosiness level.
cpu_vendor_t cpuid_get_vendor (void)
Obtains the CPU vendor from CPUID from the current CPU.
void cpuid_get_cpu_list (cpu_vendor_t vendor, struct cpu_list_t *list)
Gets a list of all known CPU names from a specific vendor.
void cpuid_free_cpu_list (struct cpu_list_t *list)
Frees a CPU list.
struct msr_driver_t * cpu_msr_driver_open (void)
Starts/opens a driver, needed to read MSRs (Model Specific Registers)
struct msr_driver_t * cpu_msr_driver_open_core (unsigned core_num)
Similar to cpu_msr_driver_open, but accept one parameter.
int cpu_rdmsr (struct msr_driver_t *handle, uint32_t msr_index, uint64_t *result)
Reads a Model-Specific Register (MSR)
int cpu_rdmsr_range (struct msr_driver_t *handle, uint32_t msr_index, uint8_t highbit,
uint8_t lowbit, uint64_t *result)
Similar to cpu_rdmsr, but extract a range of bits.
int cpu_msrinfo (struct msr_driver_t *handle, cpu_msrinfo_request_t which)
Reads extended CPU information from Model-Specific Registers.
int msr_serialize_raw_data (struct msr_driver_t *handle, const char *filename)
Writes the raw MSR data to a text file.
int cpu_msr_driver_close (struct msr_driver_t *handle)
Closes an open MSR driver.
Detailed Description
LibCPUID provides CPU identification.
Enumeration Type Documentation
enum cpu_error_t
Describes common library error codes.
Enumerator
ERR_OK No error
ERR_NO_CPUID
CPUID instruction is not supported
ERR_NO_RDTSC
RDTSC instruction is not supported
ERR_NO_MEM
Memory allocation failed
ERR_OPEN
File open operation failed
ERR_BADFMT
Bad file format
ERR_NOT_IMP
Not implemented
ERR_CPU_UNKN
Unsupported processor
ERR_NO_RDMSR
RDMSR instruction is not supported
ERR_NO_DRIVER
RDMSR driver error (generic)
ERR_NO_PERMS
No permissions to install RDMSR driver
ERR_EXTRACT
Cannot extract RDMSR driver (read only media?)
ERR_HANDLE
Bad handle
ERR_INVMSR
Invalid MSR
ERR_INVCNB
Invalid core number
ERR_HANDLE_R
Error on handle read
ERR_INVRANGE
Invalid given range
enum cpu_feature_t
CPU feature identifiers. Usage:
...
struct cpu_raw_data_t raw;
struct cpu_id_t id;
if (cpuid_get_raw_data(&raw) == 0 && cpu_identify(&raw, &id) == 0) {
if (id.flags[CPU_FEATURE_SSE2]) {
// The CPU has SSE2...
...
} else {
// no SSE2
}
} else {
// processor cannot be determined.
}
Enumerator
CPU_FEATURE_FPU
Floating point unit
CPU_FEATURE_VME
Virtual mode extension
CPU_FEATURE_DE
Debugging extension
CPU_FEATURE_PSE
Page size extension
CPU_FEATURE_TSC
Time-stamp counter
CPU_FEATURE_MSR
Model-specific regsisters, RDMSR/WRMSR supported
CPU_FEATURE_PAE
Physical address extension
CPU_FEATURE_MCE
Machine check exception
CPU_FEATURE_CX8
CMPXCHG8B instruction supported
CPU_FEATURE_APIC
APIC support
CPU_FEATURE_MTRR
Memory type range registers
CPU_FEATURE_SEP
SYSENTER / SYSEXIT instructions supported
CPU_FEATURE_PGE
Page global enable
CPU_FEATURE_MCA
Machine check architecture
CPU_FEATURE_CMOV
CMOVxx instructions supported
CPU_FEATURE_PAT
Page attribute table
CPU_FEATURE_PSE36
36-bit page address extension
CPU_FEATURE_PN
Processor serial # implemented (Intel P3 only)
CPU_FEATURE_CLFLUSH
CLFLUSH instruction supported
CPU_FEATURE_DTS
Debug store supported
CPU_FEATURE_ACPI
ACPI support (power states)
CPU_FEATURE_MMX
MMX instruction set supported
CPU_FEATURE_FXSR
FXSAVE / FXRSTOR supported
CPU_FEATURE_SSE
Streaming-SIMD Extensions (SSE) supported
CPU_FEATURE_SSE2
SSE2 instructions supported
CPU_FEATURE_SS
Self-snoop
CPU_FEATURE_HT
Hyper-threading supported (but might be disabled)
CPU_FEATURE_TM
Thermal monitor
CPU_FEATURE_IA64
IA64 supported (Itanium only)
CPU_FEATURE_PBE
Pending-break enable
CPU_FEATURE_PNI
PNI (SSE3) instructions supported
CPU_FEATURE_PCLMUL
PCLMULQDQ instruction supported
CPU_FEATURE_DTS64
64-bit Debug store supported
CPU_FEATURE_MONITOR
MONITOR / MWAIT supported
CPU_FEATURE_DS_CPL
CPL Qualified Debug Store
CPU_FEATURE_VMX
Virtualization technology supported
CPU_FEATURE_SMX
Safer mode exceptions
CPU_FEATURE_EST
Enhanced SpeedStep
CPU_FEATURE_TM2
Thermal monitor 2
CPU_FEATURE_SSSE3
SSSE3 instructionss supported (this is different from SSE3!)
CPU_FEATURE_CID
Context ID supported
CPU_FEATURE_CX16
CMPXCHG16B instruction supported
CPU_FEATURE_XTPR
Send Task Priority Messages disable
CPU_FEATURE_PDCM
Performance capabilities MSR supported
CPU_FEATURE_DCA
Direct cache access supported
CPU_FEATURE_SSE4_1
SSE 4.1 instructions supported
CPU_FEATURE_SSE4_2
SSE 4.2 instructions supported
CPU_FEATURE_SYSCALL
SYSCALL / SYSRET instructions supported
CPU_FEATURE_XD
Execute disable bit supported
CPU_FEATURE_MOVBE
MOVBE instruction supported
CPU_FEATURE_POPCNT
POPCNT instruction supported
CPU_FEATURE_AES
AES* instructions supported
CPU_FEATURE_XSAVE
XSAVE/XRSTOR/etc instructions supported
CPU_FEATURE_OSXSAVE
non-privileged copy of OSXSAVE supported
CPU_FEATURE_AVX
Advanced vector extensions supported
CPU_FEATURE_MMXEXT
AMD MMX-extended instructions supported
CPU_FEATURE_3DNOW
AMD 3DNow! instructions supported
CPU_FEATURE_3DNOWEXT
AMD 3DNow! extended instructions supported
CPU_FEATURE_NX
No-execute bit supported
CPU_FEATURE_FXSR_OPT
FFXSR: FXSAVE and FXRSTOR optimizations
CPU_FEATURE_RDTSCP
RDTSCP instruction supported (AMD-only)
CPU_FEATURE_LM
Long mode (x86_64/EM64T) supported
CPU_FEATURE_LAHF_LM
LAHF/SAHF supported in 64-bit mode
CPU_FEATURE_CMP_LEGACY
core multi-processing legacy mode
CPU_FEATURE_SVM
AMD Secure virtual machine
CPU_FEATURE_ABM
LZCNT instruction support
CPU_FEATURE_MISALIGNSSE
Misaligned SSE supported
CPU_FEATURE_SSE4A
SSE 4a from AMD
CPU_FEATURE_3DNOWPREFETCH
PREFETCH/PREFETCHW support
CPU_FEATURE_OSVW
OS Visible Workaround (AMD)
CPU_FEATURE_IBS
Instruction-based sampling
CPU_FEATURE_SSE5
SSE 5 instructions supported (deprecated, will never be 1)
CPU_FEATURE_SKINIT
SKINIT / STGI supported
CPU_FEATURE_WDT
Watchdog timer support
CPU_FEATURE_TS
Temperature sensor
CPU_FEATURE_FID
Frequency ID control
CPU_FEATURE_VID
Voltage ID control
CPU_FEATURE_TTP
THERMTRIP
CPU_FEATURE_TM_AMD
AMD-specified hardware thermal control
CPU_FEATURE_STC
Software thermal control
CPU_FEATURE_100MHZSTEPS
100 MHz multiplier control
CPU_FEATURE_HWPSTATE
Hardware P-state control
CPU_FEATURE_CONSTANT_TSC
TSC ticks at constant rate
CPU_FEATURE_XOP
The XOP instruction set (same as the old CPU_FEATURE_SSE5)
CPU_FEATURE_FMA3
The FMA3 instruction set
CPU_FEATURE_FMA4
The FMA4 instruction set
CPU_FEATURE_TBM
Trailing bit manipulation instruction support
CPU_FEATURE_F16C
16-bit FP convert instruction support
CPU_FEATURE_RDRAND
RdRand instruction
CPU_FEATURE_X2APIC
x2APIC, APIC_BASE.EXTD, MSRs 0000_0800h...0000_0BFFh 64-bit ICR (+030h but not
+031h), no DFR (+00Eh), SELF_IPI (+040h) also see standard level 0000_000Bh
CPU_FEATURE_CPB
Core performance boost
CPU_FEATURE_APERFMPERF
MPERF/APERF MSRs support
CPU_FEATURE_PFI
Processor Feedback Interface support
CPU_FEATURE_PA
Processor accumulator
CPU_FEATURE_AVX2
AVX2 instructions
CPU_FEATURE_BMI1
BMI1 instructions
CPU_FEATURE_BMI2
BMI2 instructions
CPU_FEATURE_HLE
Hardware Lock Elision prefixes
CPU_FEATURE_RTM
Restricted Transactional Memory instructions
CPU_FEATURE_AVX512F
AVX-512 Foundation
CPU_FEATURE_AVX512DQ
AVX-512 Double/Quad granular insns
CPU_FEATURE_AVX512PF
AVX-512 Prefetch
CPU_FEATURE_AVX512ER
AVX-512 Exponential/Reciprocal
CPU_FEATURE_AVX512CD
AVX-512 Conflict detection
CPU_FEATURE_SHA_NI
SHA-1/SHA-256 instructions
CPU_FEATURE_AVX512BW
AVX-512 Byte/Word granular insns
CPU_FEATURE_AVX512VL
AVX-512 128/256 vector length extensions
CPU_FEATURE_SGX
SGX extensions. Non-autoritative, check cpu_id_t::sgx::present to verify presence
CPU_FEATURE_RDSEED
RDSEED instruction
CPU_FEATURE_ADX
ADX extensions (arbitrary precision)
CPU_FEATURE_AVX512VNNI
AVX-512 Vector Neural Network Instructions
CPU_FEATURE_AVX512VBMI
AVX-512 Vector Bit ManipulationInstructions (version 1)
CPU_FEATURE_AVX512VBMI2
AVX-512 Vector Bit ManipulationInstructions (version 2)
enum cpu_hint_t
CPU detection hints identifiers. Usage: similar to the flags usage
Enumerator
CPU_HINT_SSE_SIZE_AUTH
SSE unit size is authoritative (not only a Family/Model guesswork, but based on an
actual CPUID bit)
enum cpu_msrinfo_request_t
Enumerator
INFO_MPERF
Maximum performance frequency clock. This is a counter, which increments as a
proportion of the actual processor speed.
INFO_APERF
Actual performance frequency clock. This accumulates the core clock counts when the
core is active.
INFO_MIN_MULTIPLIER
Minimum CPU:FSB ratio for this CPU, multiplied by 100.
INFO_CUR_MULTIPLIER
Current CPU:FSB ratio, multiplied by 100. e.g., a CPU:FSB value of 18.5 reads as
'1850'.
INFO_MAX_MULTIPLIER
Maximum CPU:FSB ratio for this CPU, multiplied by 100.
INFO_TEMPERATURE
The current core temperature in Celsius.
INFO_THROTTLING
1 if the current logical processor is throttling. 0 if it is running normally.
INFO_VOLTAGE
The current core voltage in Volt, multiplied by 100.
INFO_BCLK
See INFO_BUS_CLOCK.
INFO_BUS_CLOCK
The main bus clock in MHz, e.g., FSB/QPI/DMI/HT base clock, multiplied by 100.
enum cpu_sgx_feature_t
SGX features flags.
See also
cpu_sgx_t
Usage:
...
struct cpu_raw_data_t raw;
struct cpu_id_t id;
if (cpuid_get_raw_data(&raw) == 0 && cpu_identify(&raw, &id) == 0 && id.sgx.present) {
if (id.sgx.flags[INTEL_SGX1])
// The CPU has SGX1 instructions support...
...
} else {
// no SGX
}
} else {
// processor cannot be determined.
}
Enumerator
INTEL_SGX1
SGX1 instructions support
INTEL_SGX2
SGX2 instructions support
enum cpu_vendor_t
CPU vendor, as guessed from the Vendor String.
Enumerator
VENDOR_INTEL
Intel CPU
VENDOR_AMD
AMD CPU
VENDOR_CYRIX
Cyrix CPU
VENDOR_NEXGEN
NexGen CPU
VENDOR_TRANSMETA
Transmeta CPU
VENDOR_UMC
x86 CPU by UMC
VENDOR_CENTAUR
x86 CPU by IDT
VENDOR_RISE
x86 CPU by Rise Technology
VENDOR_SIS
x86 CPU by SiS
VENDOR_NSC
x86 CPU by National Semiconductor
VENDOR_HYGON
Hygon CPU
NUM_CPU_VENDORS
Valid CPU vendor ids: 0..NUM_CPU_VENDORS - 1
Function Documentation
int cpu_clock (void)
Get the CPU clock frequency (all-in-one method) This is an all-in-one method for getting
the CPU clock frequency. It tries to use the OS for that. If the OS doesn't have this
info, it uses cpu_clock_measure with 200ms time interval and quadruple checking.
Returns
the CPU clock frequency in MHz. If every possible method fails, the result is -1.
int cpu_clock_by_ic (int millis, int runs)
Measure the CPU clock frequency using instruction-counting.
Parameters
millis - how much time to allocate for each run, in milliseconds
runs - how many runs to perform
The function performs a busy-wait cycle using a known number of 'heavy' (SSE)
instructions. These instructions run at (more or less guaranteed) 1 IPC rate, so by
running a busy loop for a fixed amount of time, and measuring the amount of instructions
done, the CPU clock is accurately measured.
Of course, this function is still affected by the power-saving schemes, so the warnings as
of cpu_clock_measure() still apply. However, this function is immune to problems with
detection, related to the Intel Nehalem's 'Turbo' mode, where the internal clock is
raised, but the RDTSC rate is unaffected.
The function will run for about (millis * runs) milliseconds. You can make only a single
busy-wait run (runs == 1); however, this can be affected by task scheduling (which will
break the counting), so allowing more than one run is recommended. As run length is not
imperative for accurate readings (e.g., 50ms is sufficient), you can afford a lot of short
runs, e.g. 10 runs of 50ms or 20 runs of 25ms.
Recommended values - millis = 50, runs = 4. For more robustness, increase the number of
runs.
NOTE: on Bulldozer and later CPUs, the busy-wait cycle runs at 1.4 IPC, thus the results
are skewed. This is corrected internally by dividing the resulting value by 1.4. However,
this only occurs if the thread is executed on a single CMT module - if there are other
threads competing for resources, the results are unpredictable. Make sure you run
cpu_clock_by_ic() on a CPU that is free from competing threads, or if there are such
threads, they shouldn't exceed the number of modules. On a Bulldozer X8, that means 4
threads.
Returns
the CPU clock frequency in MHz (within some measurement error margin). If SSE is not
supported, the result is -1. If the input parameters are incorrect, or some other
internal fault is detected, the result is -2.
int cpu_clock_by_mark (struct cpu_mark_t * mark)
Calculates the CPU clock.
Parameters
mark - pointer to a cpu_mark_t structure, which has been initialized with cpu_tsc_mark
and later `stopped' with cpu_tsc_unmark.
Note
For reliable results, the marked time interval should be at least about 10 ms.
Returns
the CPU clock frequency, in MHz. Due to measurement error, it will differ from the
true value in a few least-significant bits. Accuracy depends on the timing interval -
the more, the better. If the timing interval is insufficient, the result is -1. Also,
see the comment on cpu_clock_measure for additional issues and pitfalls in using RDTSC
for CPU frequency measurements.
int cpu_clock_by_os (void)
Returns the CPU clock, as reported by the OS. This function uses OS-specific functions to
obtain the CPU clock. It may differ from the true clock for several reasons:
i) The CPU might be in some power saving state, while the OS reports its full-power
frequency, or vice-versa.
ii) In some cases you can raise or lower the CPU frequency with overclocking utilities
and the OS will not notice.
Returns
the CPU clock frequency in MHz. If the OS is not (yet) supported or lacks the
necessary reporting machinery, the return value is -1
int cpu_clock_measure (int millis, int quad_check)
Measure the CPU clock frequency.
Parameters
millis - How much time to waste in the busy-wait cycle. In millisecs. Useful values 10
- 1000
quad_check - Do a more thorough measurement if nonzero (see the explanation).
The function performs a busy-wait cycle for the given time and calculates the CPU
frequency by the difference of the TSC values. The accuracy of the calculation depends on
the length of the busy-wait cycle: more is better, but 100ms should be enough for most
purposes.
While this will calculate the CPU frequency correctly in most cases, there are several
reasons why it might be incorrect:
i) RDTSC doesn't guarantee it will run at the same clock as the CPU. Apparently there
aren't CPUs at the moment, but still, there's no guarantee.
ii) The CPU might be in a low-frequency power saving mode, and the CPU might be switched
to higher frequency at any time. If this happens during the measurement, the result can be
anywhere between the low and high frequencies. Also, if you're interested in the high
frequency value only, this function might return the low one instead.
iii) On SMP systems exhibiting TSC drift (see cpu_rdtsc)
the quad_check option will run four consecutive measurements and then return the average
of the two most-consistent results. The total runtime of the function will still be
`millis' - consider using a bit more time for the timing interval.
Finally, for benchmarking / CPU intensive applications, the best strategy is to use the
cpu_tsc_mark() / cpu_tsc_unmark() / cpu_clock_by_mark() method. Begin by mark()-ing about
one second after application startup (allowing the power-saving manager to kick in and
rise the frequency during that time), then unmark() just before application finishing. The
result will most acurately represent at what frequency your app was running.
Returns
the CPU clock frequency in MHz (within some measurement error margin). If RDTSC is not
supported, the result is -1.
void cpu_exec_cpuid (uint32_t eax, uint32_t * regs)
Executes the CPUID instruction.
Parameters
eax - the value of the EAX register when executing CPUID
regs - the results will be stored here. regs[0] = EAX, regs[1] = EBX, ...
Note
CPUID will be executed with EAX set to the given value and EBX, ECX, EDX set to zero.
void cpu_exec_cpuid_ext (uint32_t * regs)
Executes the CPUID instruction with the given input registers.
Note
This is just a bit more generic version of cpu_exec_cpuid - it allows you to control
all the registers.
Parameters
regs - Input/output. Prior to executing CPUID, EAX, EBX, ECX and EDX will be set to
regs[0], regs[1], regs[2] and regs[3]. After CPUID, this array will contain the
results.
const char* cpu_feature_str (cpu_feature_t feature)
Returns the short textual representation of a CPU flag.
Parameters
feature - the feature, whose textual representation is wanted.
Returns
a constant string like 'fpu', 'tsc', 'sse2', etc.
Note
the names of the returned flags are compatible with those from /proc/cpuinfo in Linux,
with the exception of `tm_amd'
int cpu_identify (struct cpu_raw_data_t * raw, struct cpu_id_t * data)
Identifies the CPU.
Parameters
raw - Input - a pointer to the raw CPUID data, which is obtained either by
cpuid_get_raw_data or cpuid_deserialize_raw_data. Can also be NULL, in which case the
functions calls cpuid_get_raw_data itself.
data - Output - the decoded CPU features/info is written here.
Note
The function will not fail, even if some of the information cannot be obtained. Even
when the CPU is new and thus unknown to libcpuid, some generic info, such as 'AMD K9
family CPU' will be written to data.cpu_codename, and most other things, such as the
CPU flags, cache sizes, etc. should be detected correctly anyway. However, the
function CAN fail, if the CPU is completely alien to libcpuid.
While cpu_identify() and cpuid_get_raw_data() are fast for most purposes, running them
several thousand times per second can hamper performance significantly. Specifically,
avoid writing 'cpu feature
checker' wrapping function, which calls cpu_identify and returns the value of
some flag, if that function is going to be called frequently.
Returns
zero if successful, and some negative number on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
int cpu_msr_driver_close (struct msr_driver_t * handle)
Closes an open MSR driver. This function unloads the MSR driver opened by
cpu_msr_driver_open and frees any resources associated with it.
Parameters
handle - a handle to the MSR reader driver, as created by cpu_msr_driver_open
Returns
zero if successful, and some negative number on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
struct msr_driver_t* cpu_msr_driver_open (void)
Starts/opens a driver, needed to read MSRs (Model Specific Registers) On systems that
support it, this function will create a temporary system driver, that has privileges to
execute the RDMSR instruction. After the driver is created, you can read MSRs by calling
cpu_rdmsr
Returns
a handle to the driver on success, and NULL on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
struct msr_driver_t* cpu_msr_driver_open_core (unsigned core_num)
Similar to cpu_msr_driver_open, but accept one parameter. This function works on certain
operating systems (GNU/Linux, FreeBSD)
Parameters
core_num specify the core number for MSR. The first core number is 0. The last core
number is cpuid_get_total_cpus - 1.
Returns
a handle to the driver on success, and NULL on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
int cpu_msrinfo (struct msr_driver_t * handle, cpu_msrinfo_request_t which)
Reads extended CPU information from Model-Specific Registers.
Parameters
handle - a handle to an open MSR driver,
See also
cpu_msr_driver_open
Parameters
which - which info field should be returned. A list of available information entities
is listed in the cpu_msrinfo_request_t enum.
Return values
- if the requested information is available for the current processor model, the
respective value is returned. if no information is available, or the CPU doesn't
support the query, the special value CPU_INVALID_VALUE is returned
Note
This function is not MT-safe. If you intend to call it from multiple threads, guard it
through a mutex or a similar primitive.
int cpu_rdmsr (struct msr_driver_t * handle, uint32_t msr_index, uint64_t * result)
Reads a Model-Specific Register (MSR) If the CPU has MSRs (as indicated by the
CPU_FEATURE_MSR flag), you can read a MSR with the given index by calling this function.
There are several prerequisites you must do before reading MSRs: 1) You must ensure the
CPU has RDMSR. Check the CPU_FEATURE_MSR flag in cpu_id_t::flags 2) You must ensure that
the CPU implements the specific MSR you intend to read. 3) You must open a MSR-reader
driver. RDMSR is a privileged instruction and needs ring-0 access in order to work. This
temporary driver is created by calling cpu_msr_driver_open
Parameters
handle - a handle to the MSR reader driver, as created by cpu_msr_driver_open
msr_index - the numeric ID of the MSR you want to read
result - a pointer to a 64-bit integer, where the MSR value is stored
Returns
zero if successful, and some negative number on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
int cpu_rdmsr_range (struct msr_driver_t * handle, uint32_t msr_index, uint8_t highbit,
uint8_t lowbit, uint64_t * result)
Similar to cpu_rdmsr, but extract a range of bits.
Parameters
handle - a handle to the MSR reader driver, as created by cpu_msr_driver_open
msr_index - the numeric ID of the MSR you want to read
highbit - the high bit in range, must be inferior to 64
lowbit - the low bit in range, must be equal or superior to 0
result - a pointer to a 64-bit integer, where the MSR value is stored
Returns
zero if successful, and some negative number on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
void cpu_rdtsc (uint64_t * result)
Executes RDTSC. The RDTSC (ReaD Time Stamp Counter) instruction gives access to an
internal 64-bit counter, which usually increments at each clock cycle. This can be used
for various timing routines, and as a very precise clock source. It is set to zero on
system startup. Beware that may not increment at the same frequency as the CPU.
Consecutive calls of RDTSC are, however, guaranteed to return monotonically-increasing
values.
Parameters
result - a pointer to a 64-bit unsigned integer, where the TSC value will be stored
Note
If 100% compatibility is a concern, you must first check if the RDTSC instruction is
present (if it is not, your program will crash with 'invalid opcode' exception). Only
some very old processors (i486, early AMD K5 and some Cyrix CPUs) lack that
instruction - they should have become exceedingly rare these days. To verify RDTSC
presence, run cpu_identify() and check flags[CPU_FEATURE_TSC].
The monotonically increasing nature of the TSC may be violated on SMP systems, if
their TSC clocks run at different rate. If the OS doesn't account for that, the TSC
drift may become arbitrary large.
void cpu_tsc_mark (struct cpu_mark_t * mark)
Store TSC and timing info. This function stores the current TSC value and current time
info from a precise OS-specific clock source in the cpu_mark_t structure. The sys_clock
field contains time with microsecond resolution. The values can later be used to measure
time intervals, number of clocks, FPU frequency, etc.
See also
cpu_rdtsc
Parameters
mark [out] - a pointer to a cpu_mark_t structure
void cpu_tsc_unmark (struct cpu_mark_t * mark)
Calculate TSC and timing difference.
Parameters
mark - input/output: a pointer to a cpu_mark_t structure, which has already been
initialized by cpu_tsc_mark. The difference in TSC and time will be written here.
This function calculates the TSC and time difference, by obtaining the current TSC and
timing values and subtracting the contents of the `mark' structure from them. Results are
written in the same structure.
Example:
...
struct cpu_mark_t mark;
cpu_tsc_mark(&mark);
foo();
cpu_tsc_unmark(&mark);
printf("Foo finished. Executed in %llu cycles and %llu usecs0,
mark.tsc, mark.sys_clock);
...
int cpuid_deserialize_raw_data (struct cpu_raw_data_t * data, const char * filename)
Reads raw CPUID data from file.
Parameters
data - a pointer to cpu_raw_data_t structure. The deserialized data will be written
here.
filename - the path of the file, containing the serialized raw data. If empty, stdin
will be used.
Note
This function may fail, if the file is created by different version of the library.
Also, see the notes on cpuid_serialize_raw_data.
Returns
zero if successful, and some negative number on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
const char* cpuid_error (void)
Returns textual description of the last error. libcpuid stores an `errno'-style error
status, whose description can be obtained with this function.
Note
This function is not thread-safe
See also
cpu_error_t
void cpuid_free_cpu_list (struct cpu_list_t * list)
Frees a CPU list. This function deletes all the memory associated with a CPU list, as
obtained by cpuid_get_cpu_list()
Parameters
list - the list to be free()'d.
void cpuid_get_cpu_list (cpu_vendor_t vendor, struct cpu_list_t * list)
Gets a list of all known CPU names from a specific vendor. This function compiles a list
of all known CPU (code)names (i.e. the possible values of cpu_id_t::cpu_codename) for the
given vendor.
There are about 100 entries for Intel and AMD, and a few for the other vendors. The list
is written out in approximate chronological introduction order of the parts.
Parameters
vendor the vendor to be queried
list [out] the resulting list will be written here. NOTE: As the memory is dynamically
allocated, be sure to call cpuid_free_cpu_list() after you're done with the data
See also
cpu_list_t
struct cpu_epc_t cpuid_get_epc (int index, const struct cpu_raw_data_t * raw)
Fetches information about an EPC (Enclave Page Cache) area.
Parameters
index - zero-based index, valid range [0..cpu_id_t.egx.num_epc_sections)
raw - a pointer to fetched raw CPUID data. Needed only for testing, you can safely
pass NULL here (if you pass a real structure, it will be used for fetching the leaf
12h data if index < 2; otherwise the real CPUID instruction will be used).
Returns
the requested data. If the CPU doesn't support SGX, or if index >=
cpu_id_t.egx.num_epc_sections, both fields of the returned structure will be zeros.
int cpuid_get_raw_data (struct cpu_raw_data_t * data)
Obtains the raw CPUID data from the current CPU.
Parameters
data - a pointer to cpu_raw_data_t structure
Returns
zero if successful, and some negative number on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
int cpuid_get_total_cpus (void)
Returns the total number of logical CPU threads (even if CPUID is not present). Under VM,
this number (and total_logical_cpus, since they are fetched with the same code) may be
nonsensical, i.e. might not equal NumPhysicalCPUs*NumCoresPerCPU*HyperThreading. This is
because no matter how many logical threads the host machine has, you may limit them in the
VM to any number you like. This is the number returned by cpuid_get_total_cpus().
Returns
Number of logical CPU threads available. Equals the cpu_id_t::total_logical_cpus.
cpu_vendor_t cpuid_get_vendor (void)
Obtains the CPU vendor from CPUID from the current CPU.
Note
The result is cached.
Returns
VENDOR_UNKNOWN if failed, otherwise the CPU vendor type.
See also
cpu_vendor_t
const char* cpuid_lib_version (void)
Returns the libcpuid version.
Returns
the string representation of the libcpuid version, like '0.1.1'
int cpuid_present (void)
Checks if the CPUID instruction is supported.
Return values
1 if CPUID is present
0 the CPU doesn't have CPUID.
int cpuid_serialize_raw_data (struct cpu_raw_data_t * data, const char * filename)
Writes the raw CPUID data to a text file.
Parameters
data - a pointer to cpu_raw_data_t structure
filename - the path of the file, where the serialized data should be written. If
empty, stdout will be used.
Note
This is intended primarily for debugging. On some processor, which is not currently
supported or not completely recognized by cpu_identify, one can still successfully get
the raw data and write it to a file. libcpuid developers can later import this file
and debug the detection code as if running on the actual hardware. The file is simple
text format of 'something=value' pairs. Version info is also written, but the format
is not intended to be neither backward- nor forward compatible.
Returns
zero if successful, and some negative number on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
void cpuid_set_verbosiness_level (int level)
Sets the verbosiness level. When the verbosiness level is above zero, some functions might
print diagnostic information about what are they doing. The higher the level is, the more
detail is printed. Level zero is guaranteed to omit all such output. The output is written
using the same machinery as the warnings,
See also
cpuid_set_warn_function()
Parameters
level the desired verbosiness level. Useful values 0..2 inclusive
libcpuid_warn_fn_t cpuid_set_warn_function (libcpuid_warn_fn_t warn_fun)
Sets the warning print function. In some cases, the internal libcpuid machinery would like
to emit useful debug warnings. By default, these warnings are written to stderr. However,
you can set a custom function that will receive those warnings.
Parameters
warn_fun - the warning function you want to set. If NULL, warnings are disabled. The
function takes const char* argument.
Returns
the current warning function. You can use the return value to keep the previous
warning function and restore it at your discretion.
int msr_serialize_raw_data (struct msr_driver_t * handle, const char * filename)
Writes the raw MSR data to a text file.
Parameters
handle - a handle to the MSR reader driver, as created by cpu_msr_driver_open
filename - the path of the file, where the serialized data should be written. If
empty, stdout will be used.
Note
This is intended primarily for debugging. On some processor, which is not currently
supported or not completely recognized by cpu_identify, one can still successfully get
the raw data and write it to a file. libcpuid developers can later import this file
and debug the detection code as if running on the actual hardware. The file is simple
text format of 'something=value' pairs. Version info is also written, but the format
is not intended to be neither backward- nor forward compatible.
Returns
zero if successful, and some negative number on error. The error message can be
obtained by calling cpuid_error.
See also
cpu_error_t
Author
Generated automatically by Doxygen for libcpuid from the source code.