silk.simd.cpu.

When to use#

Use CpuFeatures.detect when one binary must pick a faster kernel on machines that have a feature the build does not select. Use Target.hasCpuFeature with static if when the build itself selects the feature, which costs nothing at run time.

Details#

A CpuFeatures value is a set of feature names of the target architecture, spelled as in the compilation profile, such as "avx2", "dotprod" or "simd128". CpuFeatures.selected is the set the build selects. CpuFeatures.detect asks the machine and always includes the selected set:

• x86-64 reads cpuid, and counts AVX and AVX-512 features only when the operating system saves their registers (xgetbv).

• AArch64 Linux with GNU libc reads getauxval. AArch64 Darwin reads sysctlbyname.

• wasm32 cannot ask the engine, and other profiles cannot ask the system, so they report the selected set.

Silk has no mutable global storage, so detection is not cached. Call detect once at start and keep the value, for example in a service.

Gotchas#

• A name from another architecture, or an unknown name, is never present.

• A detected feature does not make Target.hasCpuFeature true. Code that uses the feature's instructions must still be compiled for it.

Examples#

Ask the machine once#

import silk.simd.cpu { CpuFeatures }

pub fn main() -> i32 {
  let machine = CpuFeatures.detect()
  let build = CpuFeatures.selected()
  // The machine has every feature the build selects.
  if CpuFeatures.has(&build, "sse2") && !CpuFeatures.has(&machine, "sse2") {
    return 1
  }
  if !CpuFeatures.containsAll(&machine, &build) {
    return 1
  }
  if CpuFeatures.has(&machine, "no-such-feature") {
    return 1
  }
  return 0
}

Import as CpuFeatures with import silk.simd.cpu { CpuFeatures }.

Public declarations: 1.

CpuFeatures#

pub struct CpuFeatures

A set of CPU features of the target architecture.

When to use#

Use CpuFeatures.detect when one binary must pick a faster kernel on machines that have a feature the build does not select. Use Target.hasCpuFeature with static if when the build itself selects the feature, which costs nothing at run time.

Details#

The names are spelled as in the compilation profile, such as "avx2", "dotprod" or "simd128". CpuFeatures.selected is the set the build selects. CpuFeatures.detect asks the machine and always includes the selected set.

Gotchas#

• A name from another architecture, or an unknown name, is never present.

• A detected feature does not make Target.hasCpuFeature true. Code that uses the feature's instructions must still be compiled for it.

Implementation Copy for CpuFeatures#

impl Copy for CpuFeatures

Implementation CpuFeatures#

impl CpuFeatures

Associated function selected#

pub fn selected() -> CpuFeatures

Returns the features that the build selects, from the compilation profile.

Associated function detect#

pub fn detect() -> CpuFeatures

Returns the features of the running machine, which include CpuFeatures.selected.

Details#

Each call asks the machine again:

• x86-64 reads cpuid, and counts AVX and AVX-512 features only when the operating system saves their registers (xgetbv).

• AArch64 Linux with GNU libc reads getauxval. AArch64 Darwin reads sysctlbyname.

• wasm32 cannot ask the engine, and other profiles cannot ask the system, so they report the selected set.

Silk has no mutable global storage, so the result is not cached. Call detect once at start and keep the value, for example in a service.

Gotchas#

A detected feature does not make Target.hasCpuFeature true. Code that uses the feature's instructions must still be compiled for it.

Method has#

pub fn has(self: &Self, name: string) -> bool

Returns true if the set contains the feature name.

Method containsAll#

pub fn containsAll(self: &Self, other: &CpuFeatures) -> bool

Returns true if the set contains every feature of other.

Category: SIMD.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.