doc.go

     1  // Copyright 2026 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  /*
     8  Package simd implements portable and vector-size-agnostic SIMD types,
     9  and functions and methods for working with these types.  SIMD types
    10  are either implemented in hardware (for example, arm64 "Neon" or
    11  amd64 "AVX/AVX2/AVX512") using the corresponding types in the
    12  [simd/archsimd] package, or emulated in pure Go.  In all cases, the
    13  vector length is at least 128 bits, and within a given program
    14  execution, all vectors have the same length.
    15  
    16  # SIMD Types
    17  
    18  There is a simd type corresponding to each primitive numeric type,
    19  except for complex64 and complex128.  Each of these is the type name,
    20  capitalized, with an "s" suffix, for example [Int8s], [Uint16s],
    21  or [Float64s].
    22  
    23  There are also simd "mask" types that abstract the mask registers
    24  present in some architectures, otherwise these will be implemented
    25  as bit masks.
    26  
    27  # Obtaining SIMD values
    28  
    29  The zero value of a SIMD vector type is valid and represents a zero vector.
    30  
    31  For each SIMD type, "Load<Types>(s []<type>) <Types>"
    32  loads a full verctor of the type from a long-enough slice.
    33  
    34  For slices that are not long enough, "Load<Types>Part(s []<type>) (<Types>, int)"
    35  will load as many elements as are available from the slice, fill the remainder
    36  with zero, and also return the number that were loaded.
    37  
    38  For each SIMD type, "Broadcast<Types>(x type) <Types>"
    39  returns a vector whose elements are all initialized to x.
    40  
    41  Examples:
    42    - [LoadInt8s]
    43    - [LoadUint16sPart]
    44    - [BroadcastFloat32s]
    45  
    46  # Operations
    47  
    48  SIMD types provide methods for unary ([Float32s.Abs], [Int16s.Not]), binary
    49  ([Float64s.Add], [Uint32s.GreaterEqual]), and ternary operations ([Int64s.IfElse], [Float32s.MulAdd]).
    50  Relational operations produce masks.
    51  
    52  SIMD types also support conversions between types, both those that are
    53  mostly value-preserving ([Int32s.ConvertToFloat32], [Float32s.ConvertToInt32]) and
    54  those that change types without altering the underlying vector bit
    55  pattern.
    56  
    57  Signed integer types convert to mask types ([Int16s.ToMask]), but this is a
    58  comparison against zero, not a simple bitwise conversion.  Mask types
    59  convert to signed integers in an operation ([Mask32s.ToInt32s]) that may be a
    60  zero-cost bitwise conversion, or not, depending on the underlying hardware.
    61  
    62  # Storing
    63  
    64  SIMD vector types have two methods, one for storing the entire vector into a slice
    65  "Store([]<type>)"" and a second for storing part of a vector into a slice "StorePart([]<type>) int".
    66  StorePart returns the number of elements actually stored.
    67  
    68  # String conversion
    69  
    70  Vectors and masks provide a String method for conversion to strings.
    71  
    72  # Conversion to and from simd/archsimd types.
    73  
    74  Each SIMD vector type has a "ToArch() any" method that returns the type
    75  supported by the current hardware as an "any".  Code using
    76  these methods must be build-tagged to the relevant architecture(s)
    77  and type-assert the returned value to the appropriate type.
    78  
    79  The simd package also includes generic functions for converting an
    80  architecture-dependent simd/archsimd value (e.g. [archsimd.Float32x4])
    81  into the corresponding simd type.  This function will panic if the
    82  correspondence is incorrect.
    83  
    84  For an example of converting between [simd] and [arch/simd] types,
    85  see the test file sum_amd64_test.go.
    86  */
    87  package simd
    88  
    89  // BUG(reflection): Calls won't work, and there may be other bugs.
    90  // BUG(global initialization): SIMD-dependent var initializers don't work.
    91  // BUG(modified names): Modified names may appear in stack traces and debugging.
    92
View as plain text