cpuid

package
v0.0.0-...-0a9b7a7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 23, 2024 License: Apache-2.0, MIT Imports: 12 Imported by: 30

Documentation

Overview

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

Each architecture should define its own FeatureSet type, that must be savable, along with an allFeatures map, appropriate arch hooks and a HostFeatureSet function. This file contains common functionality to all architectures, which is essentially string munging and some errors.

Individual architectures may export methods on FeatureSet that are relevant, e.g. FeatureSet.Vendor(). Common to all architectures, FeatureSets include HasFeature, which provides a trivial mechanism to test for the presence of specific hardware features. The hardware features are also defined on a per-architecture basis.

Index

Constants

View Source 
const (
	XSAVEFeatureX87         = 1 << 0
	XSAVEFeatureSSE         = 1 << 1
	XSAVEFeatureAVX         = 1 << 2
	XSAVEFeatureBNDREGS     = 1 << 3
	XSAVEFeatureBNDCSR      = 1 << 4
	XSAVEFeatureAVX512op    = 1 << 5
	XSAVEFeatureAVX512zmm0  = 1 << 6
	XSAVEFeatureAVX512zmm16 = 1 << 7
	XSAVEFeaturePKRU        = 1 << 9
)

These are the extended floating point state features. They are used to enumerate floating point features in XCR0, XSTATE_BV, etc.

View Source 
const (
	HWCAP2_RING3MWAIT = 1 << 0
	HWCAP2_FSGSBASE   = 1 << 1
)

See arch/x86/include/uapi/asm/hwcap2.h

View Source 
const (
	// CtxFeatureSet is the FeatureSet for the context.
	CtxFeatureSet contextID = iota
)
View Source 
const (
	// XCR0AMXMask are the bits that enable xsave to operate on AMX TILECFG
	// and TILEDATA.
	//
	// Note: TILECFG and TILEDATA are always either both enabled or both
	//       disabled.
	//
	// See Intel® 64 and IA-32 Architectures Software Developer’s Manual Vol.1
	// section 13.3 for details.
	XCR0AMXMask = uint64((1 << 17) | (1 << 18))
)

Variables

This section is empty.

Functions

func Initialize 

func Initialize()

Initialize initializes the global data structures used by this package. Must be called prior to using anything else in this package.

Types

type Cache 

type Cache struct {
	// Level is the hierarchical level of this cache (L1, L2, etc).
	Level uint32

	// Type is the type of cache.
	Type CacheType

	// FullyAssociative indicates that entries may be placed in any block.
	FullyAssociative bool

	// Partitions is the number of physical partitions in the cache.
	Partitions uint32

	// Ways is the number of ways of associativity in the cache.
	Ways uint32

	// Sets is the number of sets in the cache.
	Sets uint32

	// InvalidateHierarchical indicates that WBINVD/INVD from threads
	// sharing this cache acts upon lower level caches for threads sharing
	// this cache.
	InvalidateHierarchical bool

	// Inclusive indicates that this cache is inclusive of lower cache
	// levels.
	Inclusive bool

	// DirectMapped indicates that this cache is directly mapped from
	// address, rather than using a hash function.
	DirectMapped bool
}

Cache describes the parameters of a single cache on the system.

This is returned by the Caches method on FeatureSet.

type CacheType 

type CacheType uint8

CacheType describes the type of a cache, as returned in eax[4:0] for eax=4. 

const (

	// CacheData is a data cache.
	CacheData CacheType

	// CacheInstruction is an instruction cache.
	CacheInstruction

	// CacheUnified is a unified instruction and data cache.
	CacheUnified
)

type ChangeableSet 

type ChangeableSet interface {
	Query(in In) Out
	Set(in In, out Out)
}

ChangeableSet is a feature set that can allows changes.

type ErrIncompatible 

type ErrIncompatible struct {
	// contains filtered or unexported fields
}

ErrIncompatible is returned for incompatible feature sets.

func (*ErrIncompatible) Error 

func (e *ErrIncompatible) Error() string

Error implements error.Error.

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 and arm64.

On x86, features are numbered according to "blocks". Each block is 32 bits, and feature bits from the same source (cpuid leaf/level) are in the same block.

On arm64, features are numbered according to the ELF HWCAP definition, from arch/arm64/include/uapi/asm/hwcap.h. 

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
	X86FeatureHypervisor
)

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
	X86FeatureOSPKE
	X86FeatureWAITPKG
	X86FeatureAVX512_VBMI2
	X86FeatureCET_SS
	X86FeatureGFNI
	X86FeatureVAES
	X86FeatureVPCLMULQDQ
	X86FeatureAVX512_VNNI
	X86FeatureAVX512_BITALG
	X86FeatureTME
	X86FeatureAVX512_VPOPCNTDQ

	X86FeatureLA57

	X86FeatureRDPID

	X86FeatureCLDEMOTE

	X86FeatureMOVDIRI
	X86FeatureMOVDIR64B
)

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 + iota
	X86FeatureCMP_LEGACY
	X86FeatureSVM
	X86FeatureEXTAPIC
	X86FeatureCR8_LEGACY
	X86FeatureLZCNT
	X86FeatureSSE4A
	X86FeatureMISALIGNSSE
	X86FeaturePREFETCHW
	X86FeatureOSVW
	X86FeatureIBS
	X86FeatureXOP
	X86FeatureSKINIT
	X86FeatureWDT

	X86FeatureLWP
	X86FeatureFMA4
	X86FeatureTCE

	X86FeatureTBM
	X86FeatureTOPOLOGY
	X86FeaturePERFCTR_CORE
	X86FeaturePERFCTR_NB

	X86FeatureBPEXT
	X86FeaturePERFCTR_TSC
	X86FeaturePERFCTR_LLC
	X86FeatureMWAITX
	X86FeatureADMSKEXTN
)

Block 5 constants are the extended feature bits in CPUID.(EAX=0x80000001):ECX. 

const (
	X86FeatureSYSCALL  Feature = 6*32 + 11
	X86FeatureNX       Feature = 6*32 + 20
	X86FeatureMMXEXT   Feature = 6*32 + 22
	X86FeatureFXSR_OPT Feature = 6*32 + 25
	X86FeatureGBPAGES  Feature = 6*32 + 26
	X86FeatureRDTSCP   Feature = 6*32 + 27
	X86FeatureLM       Feature = 6*32 + 29
	X86Feature3DNOWEXT Feature = 6*32 + 30
	X86Feature3DNOW    Feature = 6*32 + 31
)

Block 6 constants are the extended feature bits in CPUID.(EAX=0x80000001):EDX.

These are sparse, and so the bit positions are assigned manually. 

const (
	X86FeatureAVX512_4VNNIW Feature
	X86FeatureAVX512_4FMAPS
	X86FeatureFSRM

	X86FeatureAVX512_VP2INTERSECT
	X86FeatureSRBDS_CTRL
	X86FeatureMD_CLEAR
	X86FeatureRTM_ALWAYS_ABORT

	X86FeatureTSX_FORCE_ABORT
	X86FeatureSERIALIZE
	X86FeatureHYBRID_CPU
	X86FeatureTSXLDTRK

	X86FeaturePCONFIG
	X86FeatureARCH_LBR
	X86FeatureIBT

	X86FeatureAMX_BF16
	X86FeatureAVX512_FP16
	X86FeatureAMX_TILE
	X86FeatureAMX_INT8
	X86FeatureSPEC_CTRL
	X86FeatureINTEL_STIBP
	X86FeatureFLUSH_L1D
	X86FeatureARCH_CAPABILITIES
	X86FeatureCORE_CAPABILITIES
	X86FeatureSPEC_CTRL_SSBD
)

Block 7 constants are the extended features bits in CPUID.(EAX=07H,ECX=0):EDX.

func AllFeatures 

func AllFeatures() (features []Feature)

AllFeatures returns the full set of all possible features.

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) Set 

func (f Feature) Set(s ChangeableSet)

Set sets the given feature.

func (Feature) String 

func (f Feature) String() string

String implements fmt.Stringer.String.

func (Feature) Unset 

func (f Feature) Unset(s ChangeableSet)

Unset unsets the given feature.

type FeatureSet 

type FeatureSet struct {
	// Function is the underlying CPUID Function.
	//
	// This is exported to allow direct calls of the underlying CPUID
	// function, where required.
	Function `state:".(Static)"`
	// contains filtered or unexported fields
}

FeatureSet defines features in terms of CPUID leaves and bits. The kernel also exposes the presence of features to userspace through a set of flags(HWCAP/HWCAP2) bits, exposed in the auxiliary vector, which are necessary to read for some features (e.g. FSGSBASE).

Common references:

Intel:

  • Intel SDM Volume 2, Chapter 3.2 "CPUID" (more up-to-date)
  • Intel Application Note 485 (more detailed)

AMD:

  • AMD64 APM Volume 3, Appendix 3 "Obtaining Processor Information ..."

+stateify savable

func FromContext 

func FromContext(ctx anyContext) FeatureSet

FromContext returns the FeatureSet from the context, if available.

func HostFeatureSet 

func HostFeatureSet() FeatureSet

HostFeatureSet returns a host CPUID.

func (FeatureSet) AMD 

func (fs FeatureSet) AMD() bool

AMD returns true if fs describes an AMD CPU.

func (FeatureSet) AMXExtendedStateSize 

func (fs FeatureSet) AMXExtendedStateSize() uint

AMXExtendedStateSize returns the number of bytes within the "extended state" area that is used for AMX.

func (FeatureSet) AllowedHWCap1 

func (fs FeatureSet) AllowedHWCap1() uint64

AllowedHWCap1 returns the HWCAP1 bits that the guest is allowed to depend on.

func (FeatureSet) AllowedHWCap2 

func (fs FeatureSet) AllowedHWCap2() uint64

AllowedHWCap2 returns the HWCAP2 bits that the guest is allowed to depend on.

func (FeatureSet) CacheLine 

func (fs FeatureSet) CacheLine() uint32

CacheLine is the size of a cache line in bytes.

All caches use the same line size. This is not enforced in the CPUID encoding, but is true on all known x86 processors.

func (FeatureSet) Caches 

func (fs FeatureSet) Caches() (caches []Cache)

Caches describes the caches on the CPU.

Only supported on Intel; requires allocation.

func (FeatureSet) CheckHostCompatible 

func (fs FeatureSet) CheckHostCompatible() error

CheckHostCompatible returns nil if fs is a subset of the host feature set.

func (FeatureSet) ExtendedFamily 

func (fs FeatureSet) ExtendedFamily() uint8

ExtendedFamily is part of the processor signature.

func (FeatureSet) ExtendedModel 

func (fs FeatureSet) ExtendedModel() uint8

ExtendedModel is part of the processor signature.

func (FeatureSet) ExtendedStateSize 

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

ExtendedStateSize returns the number of bytes needed to save the "extended state" for the enabled features 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: the return value matches the size of signal FP state frames. Look at check_xstate_in_sigframe() in the kernel sources for more details.

func (FeatureSet) Family 

func (fs FeatureSet) Family() uint8

Family is part of the processor signature.

func (FeatureSet) Fixed 

func (fs FeatureSet) Fixed() FeatureSet

Fixed converts the FeatureSet to a fixed set.

func (FeatureSet) FlagString 

func (fs FeatureSet) FlagString() string

FlagString prints out supported CPU flags.

func (FeatureSet) HasFeature 

func (fs FeatureSet) HasFeature(feature Feature) bool

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

This function is safe to call from a nosplit context, as long as the FeatureSet does not have any masked features.

func (FeatureSet) Intel 

func (fs FeatureSet) Intel() bool

Intel returns true if fs describes an Intel CPU.

func (FeatureSet) Model 

func (fs FeatureSet) Model() uint8

Model is part of the processor signature.

func (FeatureSet) PhysicalAddressBits 

func (fs FeatureSet) PhysicalAddressBits() uint32

PhysicalAddressBits returns the number of bits available for physical addresses.

func (FeatureSet) ProcessorType 

func (fs FeatureSet) ProcessorType() uint8

ProcessorType is part of the processor signature.

func (FeatureSet) SteppingID 

func (fs FeatureSet) SteppingID() uint8

SteppingID is part of the processor signature.

func (FeatureSet) Subtract 

func (fs FeatureSet) Subtract(other FeatureSet) (left map[Feature]struct{})

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.

This does not check for any kinds of incompatibility.

func (FeatureSet) ToStatic 

func (fs FeatureSet) ToStatic() Static

ToStatic converts a FeatureSet to a Static function.

You can create a new static feature set as: 

fs := otherFeatureSet.ToStatic().ToFeatureSet()

func (FeatureSet) UseFSGSBASE 

func (fs FeatureSet) UseFSGSBASE() bool

UseFSGSBASE returns true if 'fs' supports the (RD|WR)(FS|GS)BASE instructions.

func (FeatureSet) UseXsave 

func (fs FeatureSet) UseXsave() bool

UseXsave returns the choice of fp state saving instruction.

func (FeatureSet) UseXsavec 

func (fs FeatureSet) UseXsavec() bool

UseXsavec returns true if 'fs' supports the "xsavec" 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 valid bits in control register XCR0.

Always exclude AMX bits, because we do not support it. TODO(gvisor.dev/issues/9896): Implement AMX Support.

func (FeatureSet) VendorID 

func (fs FeatureSet) VendorID() [12]byte

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

func (FeatureSet) VirtualAddressBits 

func (fs FeatureSet) VirtualAddressBits() uint32

VirtualAddressBits returns the number of bits available for virtual addresses.

func (FeatureSet) WriteCPUInfoTo 

func (fs FeatureSet) WriteCPUInfoTo(cpu, numCPU uint, w io.Writer)

WriteCPUInfoTo 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. Several fields are simply made up.

type Function 

type Function interface {
	Query(In) Out
}

Function executes a CPUID function.

This is typically the native function or a Static definition.

type In 

type In struct {
	Eax uint32
	Ecx uint32
}

In is input to the Query function.

+stateify savable

type Native 

type Native struct{}

Native is a native Function.

This implements Function.

func (*Native) Query 

func (*Native) Query(in In) Out

Query executes CPUID natively.

This implements Function.

type Out 

type Out struct {
	Eax uint32
	Ebx uint32
	Ecx uint32
	Edx uint32
}

Out is output from the Query function.

+stateify savable

type Static 

type Static map[In]Out

Static is a static CPUID function.

+stateify savable

func (Static) Add 

func (s Static) Add(feature Feature) Static

Add adds a feature.

func (Static) Query 

func (s Static) Query(in In) Out

Query implements Function.Query.

func (Static) Remove 

func (s Static) Remove(feature Feature) Static

Remove removes a feature.

func (Static) Set 

func (s Static) Set(in In, out Out)

Set implements ChangeableSet.Set.

func (Static) ToFeatureSet 

func (s Static) ToFeatureSet() FeatureSet

ToFeatureSet converts a static specification to a FeatureSet.

This overloads some local values, where required.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.