libcpuid(3) Library Functions Manual libcpuid(3)

libcpuid - LibCPUID


- LibCPUID provides CPU identification.


struct cpu_raw_data_t
Contains just the raw CPUID data. struct cpu_raw_data_array_t
Contains an array of raw CPUID data. struct cpu_sgx_t
This contains information about SGX features of the processor Example usage: struct x86_id_t
Contains x86 specific info. struct arm_id_t
Contains ARM specific info. struct cpu_id_t
This contains the recognized CPU features/info. struct system_id_t
This contains the recognized features/info for all CPUs on the system. 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


#define LIBCPUID_DEPRECATED(message)
#define NUM_CPU_VENDORS NUM_CPU_VENDORS
#define NUM_CPU_ARCHITECTURES NUM_CPU_ARCHITECTURES
#define NUM_FEATURE_LEVELS NUM_FEATURE_LEVELS
#define NUM_CPU_PURPOSES NUM_CPU_PURPOSES
#define NUM_HYPERVISOR_VENDORS NUM_HYPERVISOR_VENDORS
#define CPU_INVALID_VALUE 0x3fffffff


typedef void(* libcpuid_warn_fn_t) (const char *msg)


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, VENDOR_ARM, VENDOR_BROADCOM, VENDOR_CAVIUM, VENDOR_DEC, VENDOR_FUJITSU, VENDOR_HISILICON, VENDOR_INFINEON, VENDOR_FREESCALE, VENDOR_NVIDIA, VENDOR_APM, VENDOR_QUALCOMM, VENDOR_SAMSUNG, VENDOR_MARVELL, VENDOR_APPLE, VENDOR_FARADAY, VENDOR_MICROSOFT, VENDOR_PHYTIUM, VENDOR_AMPERE, NUM_CPU_VENDORS, VENDOR_UNKNOWN = -1 }
CPU vendor, as guessed from the Vendor String. enum cpu_architecture_t { ARCHITECTURE_X86 = 0, ARCHITECTURE_ARM, NUM_CPU_ARCHITECTURES, ARCHITECTURE_UNKNOWN = -1 }
CPU architecture. enum cpu_feature_level_t { FEATURE_LEVEL_I386, FEATURE_LEVEL_I486, FEATURE_LEVEL_I586, FEATURE_LEVEL_I686, FEATURE_LEVEL_X86_64_V1, FEATURE_LEVEL_X86_64_V2, FEATURE_LEVEL_X86_64_V3, FEATURE_LEVEL_X86_64_V4, FEATURE_LEVEL_ARM_V1 = 100, FEATURE_LEVEL_ARM_V2, FEATURE_LEVEL_ARM_V3, FEATURE_LEVEL_ARM_V4, FEATURE_LEVEL_ARM_V4T, FEATURE_LEVEL_ARM_V5, FEATURE_LEVEL_ARM_V5T, FEATURE_LEVEL_ARM_V5TE, FEATURE_LEVEL_ARM_V5TEJ, FEATURE_LEVEL_ARM_V6, FEATURE_LEVEL_ARM_V6_M, FEATURE_LEVEL_ARM_V7_A, FEATURE_LEVEL_ARM_V7_M, FEATURE_LEVEL_ARM_V7_R, FEATURE_LEVEL_ARM_V7E_M, FEATURE_LEVEL_ARM_V8_0_A, FEATURE_LEVEL_ARM_V8_0_M, FEATURE_LEVEL_ARM_V8_0_R, FEATURE_LEVEL_ARM_V8_1_A, FEATURE_LEVEL_ARM_V8_1_M, FEATURE_LEVEL_ARM_V8_2_A, FEATURE_LEVEL_ARM_V8_3_A, FEATURE_LEVEL_ARM_V8_4_A, FEATURE_LEVEL_ARM_V8_5_A, FEATURE_LEVEL_ARM_V8_6_A, FEATURE_LEVEL_ARM_V8_7_A, FEATURE_LEVEL_ARM_V8_8_A, FEATURE_LEVEL_ARM_V8_9_A, FEATURE_LEVEL_ARM_V9_0_A, FEATURE_LEVEL_ARM_V9_1_A, FEATURE_LEVEL_ARM_V9_2_A, FEATURE_LEVEL_ARM_V9_3_A, FEATURE_LEVEL_ARM_V9_4_A, NUM_FEATURE_LEVELS, FEATURE_LEVEL_UNKNOWN = -1 }
CPU feature level. enum cpu_purpose_t { PURPOSE_GENERAL = 0, PURPOSE_PERFORMANCE, PURPOSE_EFFICIENCY, PURPOSE_LP_EFFICIENCY, PURPOSE_U_PERFORMANCE, NUM_CPU_PURPOSES }
CPU purpose. enum hypervisor_vendor_t { HYPERVISOR_NONE = 0, HYPERVISOR_BHYVE, HYPERVISOR_HYPERV, HYPERVISOR_KVM, HYPERVISOR_PARALLELS, HYPERVISOR_QEMU, HYPERVISOR_VIRTUALBOX, HYPERVISOR_VMWARE, HYPERVISOR_XEN, NUM_HYPERVISOR_VENDORS, HYPERVISOR_UNKNOWN = -1 }
Hypervisor vendor, as guessed from the CPU_FEATURE_HYPERVISOR flag. 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, CPU_FEATURE_HYPERVISOR, CPU_FEATURE_SWAP, CPU_FEATURE_THUMB, CPU_FEATURE_ADVMULTU, CPU_FEATURE_ADVMULTS, CPU_FEATURE_JAZELLE, CPU_FEATURE_DEBUGV6, CPU_FEATURE_DEBUGV6P1, CPU_FEATURE_THUMB2, CPU_FEATURE_DEBUGV7, CPU_FEATURE_DEBUGV7P1, CPU_FEATURE_THUMBEE, CPU_FEATURE_DIVIDE, CPU_FEATURE_LPAE, CPU_FEATURE_PMUV1, CPU_FEATURE_PMUV2, CPU_FEATURE_ASID16, CPU_FEATURE_ADVSIMD, CPU_FEATURE_CRC32, CPU_FEATURE_CSV2_1P1, CPU_FEATURE_CSV2_1P2, CPU_FEATURE_CSV2_2, CPU_FEATURE_CSV2_3, CPU_FEATURE_DOUBLELOCK, CPU_FEATURE_ETS2, CPU_FEATURE_FP, CPU_FEATURE_MIXEDEND, CPU_FEATURE_MIXEDENDEL0, CPU_FEATURE_PMULL, CPU_FEATURE_PMUV3, CPU_FEATURE_SHA1, CPU_FEATURE_SHA256, CPU_FEATURE_NTLBPA, CPU_FEATURE_HAFDBS, CPU_FEATURE_HPDS, CPU_FEATURE_LOR, CPU_FEATURE_LSE, CPU_FEATURE_PAN, CPU_FEATURE_PMUV3P1, CPU_FEATURE_RDM, CPU_FEATURE_VHE, CPU_FEATURE_VMID16, CPU_FEATURE_AA32HPD, CPU_FEATURE_AA32I8MM, CPU_FEATURE_DPB, CPU_FEATURE_DEBUGV8P2, CPU_FEATURE_F32MM, CPU_FEATURE_F64MM, CPU_FEATURE_FP16, CPU_FEATURE_HPDS2, CPU_FEATURE_I8MM, CPU_FEATURE_IESB, CPU_FEATURE_LPA, CPU_FEATURE_LSMAOC, CPU_FEATURE_LVA, CPU_FEATURE_PAN2, CPU_FEATURE_RAS, CPU_FEATURE_SHA3, CPU_FEATURE_SHA512, CPU_FEATURE_SM3, CPU_FEATURE_SM4, CPU_FEATURE_SPE, CPU_FEATURE_SVE, CPU_FEATURE_TTCNP, CPU_FEATURE_UAO, CPU_FEATURE_XNX, CPU_FEATURE_CCIDX, CPU_FEATURE_CONSTPACFIELD, CPU_FEATURE_EPAC, CPU_FEATURE_FCMA, CPU_FEATURE_FPAC, CPU_FEATURE_FPACCOMBINE, CPU_FEATURE_JSCVT, CPU_FEATURE_LRCPC, CPU_FEATURE_PACIMP, CPU_FEATURE_PACQARMA3, CPU_FEATURE_PACQARMA5, CPU_FEATURE_PAUTH, CPU_FEATURE_SPEV1P1, CPU_FEATURE_AMUV1, CPU_FEATURE_BBM, CPU_FEATURE_DIT, CPU_FEATURE_DEBUGV8P4, CPU_FEATURE_DOTPROD, CPU_FEATURE_DOUBLEFAULT, CPU_FEATURE_FHM, CPU_FEATURE_FLAGM, CPU_FEATURE_IDST, CPU_FEATURE_LRCPC2, CPU_FEATURE_LSE2, CPU_FEATURE_MPAM, CPU_FEATURE_PMUV3P4, CPU_FEATURE_RASV1P1, CPU_FEATURE_S2FWB, CPU_FEATURE_SEL2, CPU_FEATURE_TLBIOS, CPU_FEATURE_TLBIRANGE, CPU_FEATURE_TRF, CPU_FEATURE_TTL, CPU_FEATURE_TTST, CPU_FEATURE_BTI, CPU_FEATURE_CSV2, CPU_FEATURE_CSV3, CPU_FEATURE_DPB2, CPU_FEATURE_E0PD, CPU_FEATURE_EVT, CPU_FEATURE_EXS, CPU_FEATURE_FRINTTS, CPU_FEATURE_FLAGM2, CPU_FEATURE_MTE, CPU_FEATURE_MTE2, CPU_FEATURE_PMUV3P5, CPU_FEATURE_RNG, CPU_FEATURE_RNG_TRAP, CPU_FEATURE_SB, CPU_FEATURE_SPECRES, CPU_FEATURE_SSBS, CPU_FEATURE_SSBS2, CPU_FEATURE_AA32BF16, CPU_FEATURE_AMUV1P1, CPU_FEATURE_BF16, CPU_FEATURE_DGH, CPU_FEATURE_ECV, CPU_FEATURE_FGT, CPU_FEATURE_HPMN0, CPU_FEATURE_MPAMV0P1, CPU_FEATURE_MPAMV1P1, CPU_FEATURE_MTPMU, CPU_FEATURE_PAUTH2, CPU_FEATURE_TWED, CPU_FEATURE_AFP, CPU_FEATURE_EBF16, CPU_FEATURE_HCX, CPU_FEATURE_LPA2, CPU_FEATURE_LS64, CPU_FEATURE_LS64_ACCDATA, CPU_FEATURE_LS64_V, CPU_FEATURE_MTE3, CPU_FEATURE_MTE_ASYM_FAULT, CPU_FEATURE_PAN3, CPU_FEATURE_PMUV3P7, CPU_FEATURE_RPRES, CPU_FEATURE_SPEV1P2, CPU_FEATURE_WFXT, CPU_FEATURE_XS, CPU_FEATURE_CMOW, CPU_FEATURE_DEBUGV8P8, CPU_FEATURE_HBC, CPU_FEATURE_MOPS, CPU_FEATURE_NMI, CPU_FEATURE_PMUV3P8, CPU_FEATURE_SCTLR2, CPU_FEATURE_SPEV1P3, CPU_FEATURE_TCR2, CPU_FEATURE_TIDCP1, CPU_FEATURE_ADERR, CPU_FEATURE_AIE, CPU_FEATURE_ANERR, CPU_FEATURE_ATS1A, CPU_FEATURE_CLRBHB, CPU_FEATURE_CSSC, CPU_FEATURE_DEBUGV8P9, CPU_FEATURE_DOUBLEFAULT2, CPU_FEATURE_ECBHB, CPU_FEATURE_FGT2, CPU_FEATURE_HAFT, CPU_FEATURE_LRCPC3, CPU_FEATURE_MTE4, CPU_FEATURE_MTE_ASYNC, CPU_FEATURE_MTE_CANONICAL_TAGS, CPU_FEATURE_MTE_NO_ADDRESS_TAGS, CPU_FEATURE_MTE_PERM, CPU_FEATURE_MTE_STORE_ONLY, CPU_FEATURE_MTE_TAGGED_FAR, CPU_FEATURE_PFAR, CPU_FEATURE_PMUV3_ICNTR, CPU_FEATURE_PMUV3_SS, CPU_FEATURE_PMUV3P9, CPU_FEATURE_PRFMSLC, CPU_FEATURE_RASV2, CPU_FEATURE_RPRFM, CPU_FEATURE_S1PIE, CPU_FEATURE_S1POE, CPU_FEATURE_S2PIE, CPU_FEATURE_S2POE, CPU_FEATURE_SPECRES2, CPU_FEATURE_SPE_DPFZS, CPU_FEATURE_SPEV1P4, CPU_FEATURE_SPMU, CPU_FEATURE_THE, CPU_FEATURE_SVE2, CPU_FEATURE_SVE_AES, CPU_FEATURE_SVE_BITPERM, CPU_FEATURE_SVE_PMULL128, CPU_FEATURE_SVE_SHA3, CPU_FEATURE_SVE_SM4, CPU_FEATURE_TME, CPU_FEATURE_TRBE, CPU_FEATURE_BRBE, CPU_FEATURE_RME, CPU_FEATURE_SME, CPU_FEATURE_SME_F64F64, CPU_FEATURE_SME_FA64, CPU_FEATURE_SME_I16I64, CPU_FEATURE_BRBEV1P1, CPU_FEATURE_MEC, CPU_FEATURE_SME2, CPU_FEATURE_ABLE, CPU_FEATURE_BWE, CPU_FEATURE_D128, CPU_FEATURE_EBEP, CPU_FEATURE_GCS, CPU_FEATURE_ITE, CPU_FEATURE_LSE128, CPU_FEATURE_LVA3, CPU_FEATURE_SEBEP, CPU_FEATURE_SME2P1, CPU_FEATURE_SME_F16F16, CPU_FEATURE_SVE2P1, CPU_FEATURE_SVE_B16B16, CPU_FEATURE_SYSINSTR128, CPU_FEATURE_SYSREG128, CPU_FEATURE_TRBE_EXT, 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, ERR_NOT_FOUND = -17, ERR_IOCTL = -18, ERR_REQUEST = -19 }
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 }


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_get_raw_data_core (struct cpu_raw_data_t *data, logical_cpu_t logical_cpu)
Obtains the raw CPUID data from the specified CPU. int cpuid_get_all_raw_data (struct cpu_raw_data_array_t *data)
Obtains the raw CPUID data from all CPUs. 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_serialize_all_raw_data (struct cpu_raw_data_array_t *data, const char *filename)
Writes all 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 cpuid_deserialize_all_raw_data (struct cpu_raw_data_array_t *data, const char *filename)
Reads all raw CPUID data from file. int cpu_identify (struct cpu_raw_data_t *raw, struct cpu_id_t *data)
Identifies the CPU. int cpu_identify_all (struct cpu_raw_data_array_t *raw_array, struct system_id_t *system)
Identifies all the CPUs. int cpu_request_core_type (cpu_purpose_t purpose, struct cpu_raw_data_array_t *raw_array, struct cpu_id_t *data)
Identifies a given CPU type. const char * cpu_architecture_str (cpu_architecture_t architecture)
Returns the short textual representation of a CPU architecture. const char * cpu_feature_level_str (cpu_feature_level_t level)
Returns the short textual representation of a CPU feature level. const char * cpu_purpose_str (cpu_purpose_t purpose)
Returns the short textual representation of a CPU purpose. char * affinity_mask_str_r (cpu_affinity_mask_t *affinity_mask, char *buffer, uint32_t buffer_len)
Returns textual representation of a CPU affinity mask (thread-safe) char * affinity_mask_str (cpu_affinity_mask_t *affinity_mask)
Returns textual representation of a CPU affinity mask. 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_by_tsc (struct cpu_raw_data_t *raw)
Measure the CPU clock frequency using TSC frequency from CPUID. 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. hypervisor_vendor_t cpuid_get_hypervisor (struct cpu_raw_data_t *raw, struct cpu_id_t *data)
Obtains the hypervisor 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. void cpuid_free_raw_data_array (struct cpu_raw_data_array_t *raw_array)
Frees a raw array. void cpuid_free_system_id (struct system_id_t *system)
Frees a system ID type. 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.

LibCPUID provides CPU identification.

enum cpu_architecture_t

CPU architecture.

Enumerator

x86 CPU
ARM CPU
Valid CPU architecture ids: 0..NUM_CPU_ARCHITECTURES - 1

enum cpu_error_t

Describes common library error codes.

Enumerator

No error
CPUID instruction is not supported
RDTSC instruction is not supported
Memory allocation failed
File open operation failed
Bad file format
Not implemented
Unsupported processor
RDMSR instruction is not supported
RDMSR driver error (generic)
No permissions to install RDMSR driver
Cannot extract RDMSR driver (read only media?)
Bad handle
Invalid MSR
Invalid core number
Error on handle read
Invalid given range
Requested type not found
Error on ioctl
Invalid request

enum cpu_feature_level_t

CPU feature level.

Enumerator

i386
i486
i586
i686
x86-64-v1
x86-64-v2
x86-64-v3
x86-64-v4
ARMv1
ARMv2
ARMv3
ARMv4
ARMv4T
ARMv5 (obsolete)
ARMv5T
ARMv5TE
ARMv5TEJ
ARMv6
ARMv6-M
ARMv7-A
ARMv7-M
ARMv7-R
ARMv7E-M
ARMv8.0-A
ARMv8.0-M
ARMv8.0-R
ARMv8.1-A
ARMv8.1-M
ARMv8.2-A
ARMv8.3-A
ARMv8.4-A
ARMv8.5-A
ARMv8.6-A
ARMv8.7-A
ARMv8.8-A
ARMv8.9-A
ARMv9.0-A
ARMv9.1-A
ARMv9.2-A
ARMv9.3-A
ARMv9.4-A
Valid feature level ids: 0..NUM_FEATURE_LEVELS - 1

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

Floating point unit
Virtual mode extension
Debugging extension
Page size extension
Time-stamp counter
Model-specific regsisters, RDMSR/WRMSR supported
Physical address extension
Machine check exception
CMPXCHG8B instruction supported
APIC support
Memory type range registers
SYSENTER / SYSEXIT instructions supported
Page global enable
Machine check architecture
CMOVxx instructions supported
Page attribute table
36-bit page address extension
Processor serial # implemented (Intel P3 only)
CLFLUSH instruction supported
Debug store supported
ACPI support (power states)
MMX instruction set supported
FXSAVE / FXRSTOR supported
Streaming-SIMD Extensions (SSE) supported
SSE2 instructions supported
Self-snoop
Hyper-threading supported (but might be disabled)
Thermal monitor
IA64 supported (Itanium only)
Pending-break enable
PNI (SSE3) instructions supported
PCLMULQDQ instruction supported
64-bit Debug store supported
MONITOR / MWAIT supported
CPL Qualified Debug Store
Virtualization technology supported
Safer mode exceptions
Enhanced SpeedStep
Thermal monitor 2
SSSE3 instructionss supported (this is different from SSE3!)
Context ID supported
CMPXCHG16B instruction supported
Send Task Priority Messages disable
Performance capabilities MSR supported
Direct cache access supported
SSE 4.1 instructions supported
SSE 4.2 instructions supported
SYSCALL / SYSRET instructions supported
Execute disable bit supported
MOVBE instruction supported
POPCNT instruction supported
AES* instructions supported
XSAVE/XRSTOR/etc instructions supported
non-privileged copy of OSXSAVE supported
Advanced vector extensions supported
AMD MMX-extended instructions supported
AMD 3DNow! instructions supported
AMD 3DNow! extended instructions supported
No-execute bit supported
FFXSR: FXSAVE and FXRSTOR optimizations
RDTSCP instruction supported (AMD-only)
Long mode (x86_64/EM64T) supported
LAHF/SAHF supported in 64-bit mode
core multi-processing legacy mode
AMD Secure virtual machine
LZCNT instruction support
Misaligned SSE supported
SSE 4a from AMD
PREFETCH/PREFETCHW support
OS Visible Workaround (AMD)
Instruction-based sampling
SSE 5 instructions supported (deprecated, will never be 1)
SKINIT / STGI supported
Watchdog timer support
Temperature sensor
Frequency ID control
Voltage ID control
THERMTRIP
AMD-specified hardware thermal control
Software thermal control
100 MHz multiplier control
Hardware P-state control
TSC ticks at constant rate
The XOP instruction set (same as the old CPU_FEATURE_SSE5)
The FMA3 instruction set
The FMA4 instruction set
Trailing bit manipulation instruction support
16-bit FP convert instruction support
RdRand instruction
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
Core performance boost
MPERF/APERF MSRs support
Processor Feedback Interface support
Processor accumulator
AVX2 instructions
BMI1 instructions
BMI2 instructions
Hardware Lock Elision prefixes
Restricted Transactional Memory instructions
AVX-512 Foundation
AVX-512 Double/Quad granular insns
AVX-512 Prefetch
AVX-512 Exponential/Reciprocal
AVX-512 Conflict detection
SHA-1/SHA-256 instructions
AVX-512 Byte/Word granular insns
AVX-512 128/256 vector length extensions
SGX extensions. Non-autoritative, check cpu_id_t::sgx::present to verify presence
RDSEED instruction
ADX extensions (arbitrary precision)
AVX-512 Vector Neural Network Instructions
AVX-512 Vector Bit ManipulationInstructions (version 1)
AVX-512 Vector Bit ManipulationInstructions (version 2)
Hypervisor present (always zero on physical CPUs)
ARM: Swap instructions in the ARM instruction set
ARM: Thumb instruction set support
ARM: Advanced unsigned Multiply instructions
ARM: Advanced signed Multiply instructions
ARM: Jazelle extension support
ARM: Support for v6 Debug architecture
ARM: Support for v6.1 Debug architecture
ARM: Thumb-2, instruction set support
ARM: Support for v7 Debug architecture
ARM: Support for v7.1 Debug architecture
ARM: ThumbEE instruction set support
ARM: Divide instructions
ARM: Large Physical Address Extension
ARM: PMU extension version 1
ARM: PMU extension version 2
ARM: 16 bit ASID
ARM: Advanced SIMD Extension
ARM: CRC32 instructions
ARM: Cache Speculation Variant 2
ARM: Cache Speculation Variant 2 version 1.2
ARM: Cache Speculation Variant 2 version 2
ARM: Cache Speculation Variant 2 version 3
ARM: Double Lock
ARM: Enhanced Translation Synchronization
ARM: Floating Point extensions
ARM: Mixed-endian support
ARM: Mixed-endian support at EL0
ARM: Advanced SIMD PMULL instructions
ARM: PMU extension version 3
ARM: Advanced SIMD SHA1 instructions
ARM: Advanced SIMD SHA256 instructions
ARM: Intermediate caching of translation table walks
ARM: Hardware management of the Access flag and dirty state
ARM: Hierarchical permission disables in translations tables
ARM: Limited ordering regions
ARM: Large System Extensions
ARM: Privileged access never
ARM: Armv8.1 PMU extensions
ARM: Advanced SIMD rounding double multiply accumulate instructions
ARM: Virtualization Host Extensions
ARM: 16-bit VMID
ARM: AArch32 Hierarchical permission disables
ARM: AArch32 Int8 matrix multiplication instructions
ARM: DC CVAP instruction
ARM: Debug v8.2
ARM: Single-precision Matrix Multiplication
ARM: Double-precision Matrix Multiplication
ARM: Half-precision floating-point data processing
ARM: Hierarchical permission disables
ARM: AArch64 Int8 matrix multiplication instructions
ARM: Implicit Error Synchronization event
ARM: Large PA and IPA support
ARM: AArch32 Load/Store Multiple instruction atomicity and ordering controls
ARM: Large VA support
ARM: AT S1E1R and AT S1E1W instruction variants affected by PSTATE.PAN
ARM: Reliability, Availability and Serviceability (RAS) Extension
ARM: Advanced SIMD SHA3 instructions (ARMv8.2 architecture extension)
ARM: Advanced SIMD SHA512 instructions (ARMv8.1 architecture extension)
ARM: Advanced SIMD SM3 instructions
ARM: Advanced SIMD SM4 instructions
ARM: Statistical Profiling Extension
ARM: Scalable Vector Extension
ARM: Translation table Common not private translations
ARM: Unprivileged Access Override control
ARM: Translation table stage 2 Unprivileged Execute-never
ARM: Extended cache index
ARM: PAC algorithm enhancement
ARM: Enhanced pointer authentication
ARM: Floating-point complex number instructions
ARM: Faulting on AUT* instructions
ARM: Faulting on combined pointer authentication instructions
ARM: JavaScript conversion instructions
ARM: Load-Acquire RCpc instructions
ARM: Pointer authentication - IMPLEMENTATION DEFINED algorithm
ARM: Pointer authentication - QARMA3 algorithm
ARM: Pointer authentication - QARMA5 algorithm
ARM: Pointer authentication
ARM: Statistical Profiling Extension version 1
ARM: Activity Monitors Extension version 1
ARM: Translation table break-before-make levels
ARM: Data Independent Timing instructions
ARM: Debug v8.4
ARM: Advanced SIMD dot product instructions
ARM: Double Fault Extension
ARM: Floating-point half-precision to single-precision multiply-add instructions
ARM: Condition flag manipulation instructions
ARM: ID space trap handling
ARM: Load-Acquire RCpc instructions version 2
ARM: Large System Extensions version 2
ARM: Memory Partitioning and Monitoring Extension
ARM: Arm8.4 PMU extensions
ARM: RAS extension v1.1
ARM: Stage 2 forced Write-Back
ARM: Secure EL2
ARM: TLB invalidate instructions in Outer Shareable domain
ARM: TLB invalidate range instructions
ARM: Self-hosted Trace extensions
ARM: Translation Table Level
ARM: Small translation tables
ARM: Branch Target Identification
ARM: Cache Speculation Variant 2
ARM: Cache Speculation Variant 3
ARM: DC CVADP instruction
ARM: Preventing EL0 access to halves of address maps
ARM: Enhanced Virtualization Traps
ARM: Context synchronization and exception handling
ARM: Floating-point to integer instructions
ARM: Enhancements to flag manipulation instructions
ARM: Memory Tagging Extension
ARM: Memory Tagging Extension
ARM: Arm8.5 PMU extensions
ARM: Random number generator
ARM: Trapping support for RNDR/RNDRRS
ARM: Speculation Barrier
ARM: Speculation restriction instructions
ARM: Speculative Store Bypass Safe
ARM: MRS and MSR instructions for SSBS version 2
ARM: AArch32 BFloat16 instructions
ARM: Activity Monitors Extension version 1.1
ARM: AArch64 BFloat16 instructions
ARM: Data Gathering Hint
ARM: Enhanced Counter Virtualization
ARM: Fine Grain Traps
ARM: Setting of MDCR_EL2.HPMN to zero
ARM: Memory Partitioning and Monitoring version 0.1
ARM: Memory Partitioning and Monitoring version 1.1
ARM: Multi-threaded PMU extensions
ARM: Enhancements to pointer authentication
ARM: Delayed Trapping of WFE
ARM: Alternate floating-point behavior
ARM: AArch64 Extended BFloat16 instructions
ARM: Support for the HCRX_EL2 register
ARM: Larger physical address for 4KB and 16KB translation granules
ARM: Support for 64-byte loads and stores without status
ARM: Support for 64-byte EL0 stores with status
ARM: Support for 64-byte stores with status
ARM: MTE Asymmetric Fault Handling
ARM: Memory tagging asymmetric faults
ARM: Support for SCTLR_ELx.EPAN
ARM: Armv8.7 PMU extensions
ARM: Increased precision of FRECPE and FRSQRTE
ARM: Statistical Profiling Extensions version 1.2
ARM: WFE and WFI instructions with timeout
ARM: XS attribute
ARM: Control for cache maintenance permission
ARM: Debug v8.8
ARM: Hinted conditional branches
ARM: Standardization of memory operations
ARM: Non-maskable Interrupts
ARM: Armv8.8 PMU extensions
ARM: Extension to SCTLR_ELx
ARM: Statistical Profiling Extensions version 1.3
ARM: Support for TCR2_ELx
ARM: EL0 use of IMPLEMENTATION DEFINED functionality
ARM: Asynchronous Device Error Exceptions
ARM: Memory Attribute Index Enhancement
ARM: Asynchronous Normal Error Exceptions
ARM: Address Translation operations that ignore stage 1 permissions
ARM: Support for Clear Branch History instruction
ARM: Common Short Sequence Compression instructions
ARM: Debug v8.9
ARM: Double Fault Extension v2
ARM: Exploitative control using branch history information
ARM: Fine-grained traps 2
ARM: Hardware managed Access Flag for Table descriptors
ARM: Load-Acquire RCpc instructions version 3
ARM: Enhanced Memory Tagging Extension
ARM: Asynchronous reporting of Tag Check Fault
ARM: Canonical Tag checking for Untagged memory
ARM: Memory tagging with Address tagging disabled
ARM: Allocation tag access permission
ARM: Store-only Tag Checking
ARM: FAR_ELx on a Tag Check Fault
ARM: Physical Fault Address Register Extension
ARM: Fixed-function instruction counter
ARM: PMU Snapshot extension
ARM: Armv8.9 PMU extensions
ARM: SLC target support for PRFM instructions
ARM: RAS Extension v2
ARM: Support for Range Prefetch Memory instruction
ARM: Stage 1 permission indirections
ARM: Stage 1 permission overlays
ARM: Stage 2 permission indirections
ARM: Stage 1 permission overlays
ARM: Enhanced speculation restriction instructions
ARM: Disable Cycle Counter on SPE Freeze
ARM: Statistical Profiling Extension version 1.4
ARM: System Performance Monitors Extension
ARM: Translation Hardening Extension
ARM: Scalable Vector Extension version 2
ARM: Scalable Vector AES instructions
ARM: Scalable Vector Bit Permutes instructions
ARM: Scalable Vector PMULL instructions
ARM: Scalable Vector SHA3 instructions
ARM: Scalable Vector SM4 instructions
ARM: Transactional Memory Extension
ARM: Trace Buffer Extension
ARM: Branch Record Buffer Extension
ARM: Realm Management Extension
ARM: Scalable Matrix Extension
ARM: Double-precision floating-point outer product instructions
ARM: Full A64 instruction set support in Streaming SVE mode
ARM: 16-bit to 64-bit integer widening outer product instructions
ARM: Branch Record Buffer Extension version 1.1
ARM: Memory Encryption Contexts
ARM: Scalable Matrix Extensions version 2
ARM: Address Breakpoint Linking Extension
ARM: Breakpoint and watchpoint enhancements
ARM: 128-bit Translation Tables, 56 bit PA
ARM: Exception-based Event Profiling
ARM: Guarded Control Stack Extension
ARM: Instrumentation Trace Extension
ARM: 128-bit Atomics
ARM: 56-bit VA
ARM: Synchronous Exception-based Event Profiling
ARM: Scalable Matrix Extension version 2.1
ARM: Non-widening half-precision FP16 to FP16 arithmetic for SME2.
ARM: Scalable Vector Extensions version 2.1
ARM: Non-widening BFloat16 to BFloat16 arithmetic for SVE2 and SME2.
ARM: 128-bit System instructions
ARM: 128-bit System registers
ARM: Trace Buffer external mode

enum cpu_hint_t

CPU detection hints identifiers. Usage: similar to the flags usage

Enumerator

SSE unit size is authoritative (not only a Family/Model guesswork, but based on an actual CPUID bit)

enum cpu_msrinfo_request_t

Enumerator

Maximum performance frequency clock. This is a counter, which increments as a proportion of the actual processor speed.
Actual performance frequency clock. This accumulates the core clock counts when the core is active.
Minimum CPU:FSB ratio for this CPU, multiplied by 100.
Current CPU:FSB ratio, multiplied by 100. e.g., a CPU:FSB value of 18.5 reads as '1850'.
Maximum CPU:FSB ratio for this CPU, multiplied by 100.
The current core temperature in Celsius.
1 if the current logical processor is throttling. 0 if it is running normally.
The current core voltage in Volt, multiplied by 100.
See INFO_BUS_CLOCK.
The main bus clock in MHz, e.g., FSB/QPI/DMI/HT base clock, multiplied by 100.

enum cpu_purpose_t

CPU purpose.

Enumerator

general purpose CPU
performance CPU
efficiency CPU
low-power efficiency CPU
ultimate performance CPU
Valid CPU purpose ids: 0..NUM_CPU_PURPOSES - 1

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

SGX1 instructions support
SGX2 instructions support

enum cpu_vendor_t

CPU vendor, as guessed from the Vendor String.

Enumerator

Intel CPU
AMD CPU
Cyrix CPU
NexGen CPU
Transmeta CPU
x86 CPU by UMC
x86 CPU by IDT
x86 CPU by Rise Technology
x86 CPU by SiS
x86 CPU by National Semiconductor
Hygon CPU
ARM CPU
Broadcom Corporation CPU
Cavium Inc. CPU
Digital Equipment Corporation CPU
Fujitsu Ltd. CPU
HiSilicon Technology Co., Ltd. CPU
Infineon Technologies AG CPU
Motorola or Freescale Semiconductor Inc. CPU
NVIDIA Corporation CPU
Applied Micro Circuits Corporation CPU
Qualcomm Inc. CPU
Samsung Group CPU
Marvell International Ltd. CPU
Apple Inc. CPU
Faraday Technology CPU
Microsoft Corporation CPU
Phytium Technology Co., Ltd CPU
Ampere Computing CPU
Valid CPU vendor ids: 0..NUM_CPU_VENDORS - 1

enum hypervisor_vendor_t

Hypervisor vendor, as guessed from the CPU_FEATURE_HYPERVISOR flag.

Enumerator

no hypervisor
FreeBSD bhyve hypervisor
Microsoft Hyper-V or Windows Virtual PC hypervisor
KVM hypervisor
Parallels hypervisor
QEMU hypervisor
VirtualBox hypervisor
VMware hypervisor
Xen hypervisor
Valid hypervisor vendor ids: 0..NUM_HYPERVISOR_VENDORS - 1

Returns textual representation of a CPU affinity mask.

Parameters

affinity_mask - the affinity mask (in hexadecimal), whose textual representation is wanted.

Note

This function is not thread-safe

Returns

a string like '0000FFFF', '00FF0000', etc.

Returns textual representation of a CPU affinity mask (thread-safe)

Parameters

affinity_mask - Input - the affinity mask (in hexadecimal), whose textual representation is wanted.
buffer - Output - an allocated string where to store the textual representation, like '0000FFFF', '00FF0000', etc.
buffer_len - Input - the size of buffer.

Returns

a pointer on buffer

Returns the short textual representation of a CPU architecture.

Parameters

architecture - the architecture, whose textual representation is wanted.

Returns

a constant string like 'x86', 'ARM', etc.

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.

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.

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.

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

Measure the CPU clock frequency using TSC frequency from CPUID.

Parameters

raw - Optional 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.

The function read Time Stamp Counter and Nominal Core Crystal Clock Information Leaf from CPUID. It determines the processor base frequency.

NOTE: only x86 Intel CPUs since Skylake (6th generation of Intel Core processors) are supported. Other vendors do not support this feature.

Returns

the CPU clock frequency in MHz. If TSC frequency is not supported, the result is -1. If the input parameters are incorrect, or some other internal fault is detected, the result is -2.

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.

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.

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.

Returns the short textual representation of a CPU feature level.

Parameters

level - the feature level, whose textual representation is wanted.

Returns

a constant string like 'ARMv8.0-A', 'ARMv9.4-A', etc.

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'

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

Identifies all the CPUs.

Parameters

raw_array - Input - a pointer to the array of raw CPUID data, which is obtained either by cpuid_get_all_raw_data or cpuid_deserialize_all_raw_data. Can also be NULL, in which case the functions calls cpuid_get_all_raw_data itself.
system - Output - the decoded CPU features/info is written here for each CPU type.

Note

The function is similar to cpu_identify. Refer to cpu_identify notes.

As the memory is dynamically allocated, be sure to call cpuid_free_raw_data_array() and cpuid_free_system_id() after you're done with the 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

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

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

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

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.

Returns the short textual representation of a CPU purpose.

Parameters

purpose - the purpose, whose textual representation is wanted.

Returns

a constant string like 'general', 'performance', 'efficiency', etc.

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

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

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.

Identifies a given CPU type.

Parameters

purpose - Input - a cpu_purpose_t to request
raw_array - Optional input - a pointer to the array of raw CPUID data, which is obtained either by cpuid_get_all_raw_data or cpuid_deserialize_all_raw_data. Can also be NULL, in which case the functions calls cpuid_get_all_raw_data itself.
data - Output - the decoded CPU features/info is written here.

Returns

zero if successful, and some negative number on error (like ERR_NOT_FOUND if CPU type not found). The error message can be obtained by calling cpuid_error.

See also

cpu_error_t

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

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 usecs\n",
       mark.tsc, mark.sys_clock);
...

Reads all raw CPUID data from file.

Parameters

data - a pointer to cpu_raw_data_array_t structure. The deserialized array 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_all_raw_data.

As the memory is dynamically allocated, be sure to call cpuid_free_raw_data_array() after you're done with the 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

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

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

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.

Frees a raw array. This function deletes all the memory associated with a raw array, as obtained by cpuid_get_all_raw_data(), cpuid_deserialize_all_raw_data() and cpu_identify_all()

Parameters

raw_array - the raw array to be free()'d.

Frees a system ID type. This function deletes all the memory associated with a system ID, as obtained by cpu_identify_all()

Parameters

system - the system ID to be free()'d.

Obtains the raw CPUID data from all CPUs.

Parameters

data - a pointer to cpu_raw_data_array_t structure

Note

As the memory is dynamically allocated, be sure to call cpuid_free_raw_data_array() after you're done with the 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

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. On failure, num_entries is set to zero and names to NULL. The error message can be obtained by calling cpuid_error.

See also

cpu_error_t NOTE: As the memory is dynamically allocated, be sure to call cpuid_free_cpu_list() after you're done with the data

cpu_list_t

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.

hypervisor_vendor_t cpuid_get_hypervisor (struct cpu_raw_data_t * raw, struct cpu_id_t * data)

Obtains the hypervisor vendor from CPUID from the current CPU.

Parameters

raw - Optional 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 - Optional input - the decoded CPU features/info is written here. Can also be NULL, in which case the functions calls cpu_identify itself.

Note

If no hypervisor is detected, the hypervisor can be hidden in some cases. Refer to https://github.com/anrieff/libcpuid/issues/90#issuecomment-296568713.

Returns

HYPERVISOR_UNKNOWN if failed, HYPERVISOR_NONE if no hypervisor detected (or hidden), otherwise the hypervisor vendor type.

See also

hypervisor_vendor_t

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

Obtains the raw CPUID data from the specified CPU.

Parameters

data - a pointer to cpu_raw_data_t structure
logical_cpu specify the core number. The first core number is 0. The last core number is cpuid_get_total_cpus - 1.

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

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

Returns the libcpuid version.

Returns

the string representation of the libcpuid version, like '0.1.1'

Checks if the CPUID instruction is supported.

Return values

1 if CPUID is present
0 the CPU doesn't have CPUID.

Writes all the raw CPUID data to a text file.

Parameters

data - a pointer to cpu_raw_data_array_t structure
filename - the path of the file, where the serialized data for all CPUs 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_all, 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

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

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

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.

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

Generated automatically by Doxygen for libcpuid from the source code.

libcpuid