cpuid

Documentation

Overview

Package cpuid provides basic functionality for creating and adjusting CPU feature sets.

To use FeatureSets, one should start with an existing FeatureSet (either a known platform, or HostFeatureSet()) and then add, remove, and test for features as desired.

For example: Test for hardware extended state saving, and if we don't have it, don't expose AVX, which cannot be saved with fxsave.

if !HostFeatureSet().HasFeature(X86FeatureXSAVE) {
  exposedFeatures.Remove(X86FeatureAVX)
}

Index

• Constants
• func HostID(axArg, cxArg uint32) (ax, bx, cx, dx uint32)
• type Feature
  • func FeatureFromString(s string) (Feature, bool)
  • func (f Feature) String() string
• type FeatureSet
  • func HostFeatureSet() *FeatureSet
  • func (fs *FeatureSet) Add(feature Feature)
  • func (fs FeatureSet) CPUInfo(cpu uint) string
  • func (fs *FeatureSet) EmulateID(origAx, origCx uint32) (ax, bx, cx, dx uint32)
  • func (fs *FeatureSet) ExtendedStateSize() (size, align uint)
  • func (fs *FeatureSet) FlagsString(cpuinfoOnly bool) string
  • func (fs *FeatureSet) HasFeature(feature Feature) bool
  • func (fs *FeatureSet) IsSubset(other *FeatureSet) bool
  • func (fs *FeatureSet) Remove(feature Feature)
  • func (fs *FeatureSet) Subtract(other *FeatureSet) (diff map[Feature]bool)
  • func (fs *FeatureSet) TakeFeatureIntersection(other *FeatureSet)
  • func (fs *FeatureSet) UseXsave() bool
  • func (fs *FeatureSet) UseXsaveopt() bool
  • func (fs *FeatureSet) ValidXCR0Mask() uint64

Constants

const (
	DCAParams cpuidFunction // Returns direct cache access information.

)

The constants below are the lower or "standard" cpuid functions. See Intel AN485 for detailed information about each one.

Functions

func HostID

func HostID(axArg, cxArg uint32) (ax, bx, cx, dx uint32)

HostID executes a native CPUID instruction.

Types

type Feature

type Feature int

Feature is a unique identifier for a particular cpu feature. We just use an int as a feature number on x86. It corresponds to the bit position in the basic feature mask returned by a cpuid with eax=1.

const (
	X86FeatureSSE3 Feature = iota
	X86FeaturePCLMULDQ
	X86FeatureDTES64
	X86FeatureMONITOR
	X86FeatureDSCPL
	X86FeatureVMX
	X86FeatureSMX
	X86FeatureEST
	X86FeatureTM2
	X86FeatureSSSE3 // Not a typo, "supplemental" SSE3.
	X86FeatureCNXTID
	X86FeatureSDBG
	X86FeatureFMA
	X86FeatureCX16
	X86FeatureXTPR
	X86FeaturePDCM

	X86FeaturePCID
	X86FeatureDCA
	X86FeatureSSE4_1
	X86FeatureSSE4_2
	X86FeatureX2APIC
	X86FeatureMOVBE
	X86FeaturePOPCNT
	X86FeatureTSCD
	X86FeatureAES
	X86FeatureXSAVE
	X86FeatureOSXSAVE
	X86FeatureAVX
	X86FeatureF16C
	X86FeatureRDRAND
)

Block 0 constants are all of the "basic" feature bits returned by a cpuid in ecx with eax=1.

const (
	X86FeatureFPU Feature = 32 + iota
	X86FeatureVME
	X86FeatureDE
	X86FeaturePSE
	X86FeatureTSC
	X86FeatureMSR
	X86FeaturePAE
	X86FeatureMCE
	X86FeatureCX8
	X86FeatureAPIC

	X86FeatureSEP
	X86FeatureMTRR
	X86FeaturePGE
	X86FeatureMCA
	X86FeatureCMOV
	X86FeaturePAT
	X86FeaturePSE36
	X86FeaturePSN
	X86FeatureCLFSH

	X86FeatureDS
	X86FeatureACPI
	X86FeatureMMX
	X86FeatureFXSR
	X86FeatureSSE
	X86FeatureSSE2
	X86FeatureSS
	X86FeatureHTT
	X86FeatureTM
	X86FeatureIA64
	X86FeaturePBE
)

Block 1 constants are all of the "basic" feature bits returned by a cpuid in edx with eax=1.

const (
	X86FeatureFSGSBase Feature = 2*32 + iota
	X86FeatureTSC_ADJUST

	X86FeatureBMI1
	X86FeatureHLE
	X86FeatureAVX2
	X86FeatureFDP_EXCPTN_ONLY
	X86FeatureSMEP
	X86FeatureBMI2
	X86FeatureERMS
	X86FeatureINVPCID
	X86FeatureRTM
	X86FeatureCQM
	X86FeatureFPCSDS
	X86FeatureMPX
	X86FeatureRDT
	X86FeatureAVX512F
	X86FeatureAVX512DQ
	X86FeatureRDSEED
	X86FeatureADX
	X86FeatureSMAP
	X86FeatureAVX512IFMA
	X86FeaturePCOMMIT
	X86FeatureCLFLUSHOPT
	X86FeatureCLWB
	X86FeatureIPT // Intel processor trace.
	X86FeatureAVX512PF
	X86FeatureAVX512ER
	X86FeatureAVX512CD
	X86FeatureSHA
	X86FeatureAVX512BW
	X86FeatureAVX512VL
)

Block 2 bits are the "structured extended" features returned in ebx for eax=7, ecx=0.

const (
	X86FeaturePREFETCHWT1 Feature = 3*32 + iota
	X86FeatureAVX512VBMI
	X86FeatureUMIP
	X86FeaturePKU
)

Block 3 bits are the "extended" features returned in ecx for eax=7, ecx=0.

const (
	X86FeatureXSAVEOPT Feature = 4*32 + iota
	X86FeatureXSAVEC
	X86FeatureXGETBV1
	X86FeatureXSAVES
)

Block 4 constants are for xsave capabilities in CPUID.(EAX=0DH,ECX=01H):EAX. The CPUID leaf is available only if 'X86FeatureXSAVE' is present.

const (
	X86FeatureLAHF64    Feature = 5*32 + 0
	X86FeatureLZCNT     Feature = 5*32 + 5
	X86FeaturePREFETCHW Feature = 5*32 + 8
)

Block 5 constants are the extended feature bits in CPUID.(EAX=0x80000001):ECX. These are very sparse, and so the bit positions are assigned manually.

const (
	X86FeatureSYSCALL Feature = 6*32 + 11
	X86FeatureNX      Feature = 6*32 + 20
	X86FeatureGBPAGES Feature = 6*32 + 26
	X86FeatureRDTSCP  Feature = 6*32 + 27
	X86FeatureLM      Feature = 6*32 + 29
)

Block 6 constants are the extended feature bits in CPUID.(EAX=0x80000001):EDX. These are very sparse, and so the bit positions are assigned manually.

func FeatureFromString

func FeatureFromString(s string) (Feature, bool)

FeatureFromString returns the Feature associated with the given feature string plus a bool to indicate if it could find the feature.

func (Feature) String

func (f Feature) String() string

String implements fmt.Stringer.

type FeatureSet

type FeatureSet struct {
	// Set is the set of features that are enabled in this FeatureSet.
	Set map[Feature]bool

	// VendorID is the 12-char string returned in ebx:edx:ecx for eax=0.
	VendorID string

	// ExtendedFamily is part of the processor signature.
	ExtendedFamily uint8

	// ExtendedModel is part of the processor signature.
	ExtendedModel uint8

	// ProcessorType is part of the processor signature.
	ProcessorType uint8

	// Family is part of the processor signature.
	Family uint8

	// Model is part of the processor signature.
	Model uint8

	// SteppingID is part of the processor signature.
	SteppingID uint8
}

FeatureSet is a set of Features for a cpu.

func HostFeatureSet

func HostFeatureSet() *FeatureSet

HostFeatureSet uses cpuid to get host values and construct a feature set that matches that of the host machine. Note that there are several places where there appear to be some unecessary assignments between register names (ax, bx, cx, or dx) and featureBlockN variables. This is to explicitly show where the different feature blocks come from, to make the code easier to inspect and read.

func (*FeatureSet) Add

func (fs *FeatureSet) Add(feature Feature)

Add adds a Feature to a FeatureSet. It ignores duplicate features.

func (FeatureSet) CPUInfo

func (fs FeatureSet) CPUInfo(cpu uint) string

CPUInfo is to generate a section of one cpu in /proc/cpuinfo. This is a minimal /proc/cpuinfo, it is missing some fields like "microcode" that are not always printed in Linux. The bogomips field is simply made up.

func (*FeatureSet) EmulateID

func (fs *FeatureSet) EmulateID(origAx, origCx uint32) (ax, bx, cx, dx uint32)

EmulateID emulates a cpuid instruction based on the feature set.

func (*FeatureSet) ExtendedStateSize

func (fs *FeatureSet) ExtendedStateSize() (size, align uint)

ExtendedStateSize returns the number of bytes needed to save the "extended state" for this processor and the boundary it must be aligned to. Extended state includes floating point registers, and other cpu state that's not associated with the normal task context.

Note: We can save some space here with an optimiazation where we use a smaller chunk of memory depending on features that are actually enabled. Currently we just use the largest possible size for simplicity (which is about 2.5K worst case, with avx512).

func (*FeatureSet) FlagsString

func (fs *FeatureSet) FlagsString(cpuinfoOnly bool) string

FlagsString prints out supported CPU flags. If cpuinfoOnly is true, it is equivalent to the "flags" field in /proc/cpuinfo.

func (*FeatureSet) HasFeature

func (fs *FeatureSet) HasFeature(feature Feature) bool

HasFeature tests whether or not a feature is in the given feature set.

func (*FeatureSet) IsSubset

func (fs *FeatureSet) IsSubset(other *FeatureSet) bool

IsSubset returns true if the FeatureSet is a subset of the FeatureSet passed in. This is useful if you want to see if a FeatureSet is compatible with another FeatureSet, since you can only run with a given FeatureSet if it's a subset of the host's.

func (*FeatureSet) Remove

func (fs *FeatureSet) Remove(feature Feature)

Remove removes a Feature from a FeatureSet. It ignores features that are not in the FeatureSet.

func (*FeatureSet) Subtract

func (fs *FeatureSet) Subtract(other *FeatureSet) (diff map[Feature]bool)

Subtract returns the features present in fs that are not present in other. If all features in fs are present in other, Subtract returns nil.

func (*FeatureSet) TakeFeatureIntersection

func (fs *FeatureSet) TakeFeatureIntersection(other *FeatureSet)

TakeFeatureIntersection will set the features in `fs` to the intersection of the features in `fs` and `other` (effectively clearing any feature bits on `fs` that are not also set in `other`).

func (*FeatureSet) UseXsave

func (fs *FeatureSet) UseXsave() bool

UseXsave returns the choice of fp state saving instruction.

func (*FeatureSet) UseXsaveopt

func (fs *FeatureSet) UseXsaveopt() bool

UseXsaveopt returns true if 'fs' supports the "xsaveopt" instruction.

func (*FeatureSet) ValidXCR0Mask

func (fs *FeatureSet) ValidXCR0Mask() uint64

ValidXCR0Mask returns the bits that may be set to 1 in control register XCR0.