Source file src/simd/archsimd/doc.go
1 // Copyright 2025 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 //go:build goexperiment.simd 6 7 // Package archsimd provides access to architecture-specific SIMD operations. 8 // 9 // This is a low-level package that exposes hardware-specific functionality. 10 // It currently supports AMD64. 11 // 12 // This package is experimental, and not subject to the Go 1 compatibility promise. 13 // It only exists when building with the GOEXPERIMENT=simd environment variable set. 14 // 15 // # Vector types and operations 16 // 17 // Vector types are defined as structs, such as Int8x16 and Float64x8, corresponding 18 // to the hardware's vector registers. On AMD64, 128-, 256-, and 512-bit vectors are 19 // supported. 20 // 21 // Mask types are defined similarly, such as Mask8x16, and are represented as 22 // opaque types, handling the differences in the underlying representations. 23 // A mask can be converted to/from the corresponding integer vector type, or 24 // to/from a bitmask. 25 // 26 // Operations are mostly defined as methods on the vector types. Most of them 27 // are compiler intrinsics and correspond directly to hardware instructions. 28 // 29 // Common operations include: 30 // - Load/Store: Load a vector from memory or store a vector to memory. 31 // - Arithmetic: Add, Sub, Mul, etc. 32 // - Bitwise: And, Or, Xor, etc. 33 // - Comparison: Equal, Greater, etc., which produce a mask. 34 // - Conversion: Convert between different vector types. 35 // - Field selection and rearrangement: GetElem, Permute, etc. 36 // - Masking: Masked, Merge. 37 // 38 // The compiler recognizes certain patterns of operations and may optimize 39 // them to more performant instructions. For example, on AVX512, an Add operation 40 // followed by Masked may be optimized to a masked add instruction. 41 // For this reason, not all hardware instructions are available as APIs. 42 // 43 // # CPU feature checks 44 // 45 // The package provides global variables to check for CPU features available 46 // at runtime. For example, on AMD64, the [X86] variable provides methods to 47 // check for AVX2, AVX512, etc. 48 // It is recommended to check for CPU features before using the corresponding 49 // vector operations. 50 // 51 // # Notes 52 // 53 // - This package is not portable, as the available types and operations depend 54 // on the target architecture. It is not recommended to expose the SIMD types 55 // defined in this package in public APIs. 56 // - For performance reasons, it is recommended to use the vector types directly 57 // as values. It is not recommended to take the address of a vector type, 58 // allocate it in the heap, or put it in an aggregate type. 59 package archsimd 60 61 // BUG(cherry): Using a vector type as a type parameter may not work. 62 63 // BUG(cherry): Using reflect Call to call a vector function/method may not work. 64