cpu

Documentation

Overview

Package cpu detects which SIMD instruction-set tier the running CPU supports.

Detection uses golang.org/x/sys/cpu rather than the standard library's internal/cpu, which is not importable from third-party modules. x/sys/cpu is also the only source of ARM64.HasSVE and HasSVE2; internal/cpu exposes neither.

Nothing in this package executes a SIMD instruction. That is deliberate: a package-level variable initializer that runs a vector instruction executes before the dispatch check that is supposed to guard it, which is how go-highway#69 produced SIGILL on non-AVX2 CPUs.

Index

• func Describe() string
• func SetBackendTier(name string)
• type Selection
  • func Detail() Selection
• type Tier
  • func ParseTier(s string) (Tier, bool)
  • func Selected() Tier
  • func (t Tier) String() string

Functions

func Describe

func Describe() string

Describe renders the selection for logs and test failure messages.

func SetBackendTier

func SetBackendTier(name string)

SetBackendTier is called once by the dispatcher after it has chosen.

Types

type Selection

type Selection struct {
	// Tier is the selected tier.
	Tier Tier
	// Available lists every tier this CPU supports, weakest first. It always
	// begins with Scalar.
	Available []Tier
	// Forced is true if GOSIMD selected the tier rather than detection.
	Forced bool
	// Disabled lists tiers masked out by SIMD_DISABLE.
	Disabled []Tier
	// Reason explains a fallback to Scalar caused by an override. Empty when
	// selection proceeded normally.
	Reason string
}

Selection records the outcome of tier selection, including why a tier was chosen. Tests and diagnostics use it; the hot path does not.

func Detail

func Detail() Selection

Detail returns the full selection outcome, for diagnostics and tests.

type Tier

type Tier uint8

Tier identifies a SIMD instruction-set level. Tiers are architecture specific; only those belonging to the running GOARCH are ever reported. Within an architecture the constants are ordered weakest to strongest, so the highest available tier is the numerically largest one.

const (
	// Scalar is the portable Go fallback. Available on every architecture.
	Scalar Tier = iota

	// amd64
	SSE2   // baseline on amd64; no runtime check needed
	AVX2   // requires AVX2 + FMA
	AVX512 // requires the F+CD+BW+DQ+VL bundle

	// arm64
	NEON // ASIMD, architecturally mandatory on AArch64
	SVE2 // scalable; vector length is a runtime property

	// riscv64
	RVV // RVV 1.0; scalable, like SVE2

	// s390x
	VX  // z13 vector facility
	VXE // vector enhancements

	// loong64
	LSX  // 128-bit
	LASX // 256-bit

	// ppc64/ppc64le
	VSX // VMX/VSX, POWER8+

)

func ParseTier

func ParseTier(s string) (Tier, bool)

ParseTier maps a tier name to a Tier. Names are the lowercase strings returned by Tier.String.

func Selected

func Selected() Tier

Selected returns the tier this process will dispatch to.

func (Tier) String

func (t Tier) String() string