// Copyright 2026 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package spec describes all possible operations in the SIMD API.
//
// The SIMD spec describes the function and method signatures, documentation
// comments, and behavior (written as a reference Go implementation) of all
// possible Go SIMD APIs. The archsimd and simd packages are subsets of this
// specified API. This approach enforces that "one name means one thing" across
// all platforms and both packages.
//
// The spec is written as buildable and executable Go code, but isn't meant to
// be called directly. Rather, the specgen package interprets this spec package
// into a full API description, which can then be fed into other generators for
// the actual SIMD packages. The executable part of the spec serves to precisely
// specify the semantics of operations, and is intended for conformance testing.
//
// To see the spec-generated API and debug issues with it, use [cmd/specls].
//
// ## Basic operation specifications
//
// Spec operations are written in a stylized form that makes heavy use of type
// parameters so a single function can describe an operation generalized across
// many vector types. This is in contrast with the public SIMD API, where every
// function and method operates on concrete types. The specgen generator bridges
// this gap, instantiating a single parameterized spec function into many
// concrete methods.
//
// Consider a simple example, the Add operation:
//
//	// Add adds corresponding elements of two vectors.
//	func Add[E Nums, W Width](x, y Vec[E, W]) (z Vec[E, W]) {
//	    ...
//	}
//
// All spec operations are written as functions, but if the first parameter has
// type Vec, then they specify a method of a vector type. Since Add's first
// parameter (x) is a Vec, this describes a method on vector types.
//
// The "E Nums" type parameter controls the allowed element types of the three
// vector types. Here, it can be any numeric type of any size (uint8, float64,
// etc). The "W Width" type parameter controls the total bit width of the three
// vector types. The types that implement Width stand in for 128, 256, or 512
// bits, or "scalable", which can represent any power of two >= 128. The number
// of lanes of a vector is derived from the element size and the total vector
// width.
//
// The Add spec expands to all possible types that satisfy the E and W type
// parameters, which are in turn translated to types in the public API:
//
//	func (Int8x16) Add(Int8x16) Int8x16
//	func (Int8x32) Add(Int8x32) Int8x32
//	func (Int8x64) Add(Int8x64) Int8x64
//	func (Int8s) Add(Int8s) Int8s
//	...
//	func (Float64x8) Add(Float64x8) Float64x8
//	func (Float64s) Add(Float64s) Float64s
//
// ## Spec constraints
//
// For many operations, all possible combinations of their type parameters are
// valid, but some need to express constraints between type parameters that
// can't easily be described in the Go type system. For these, we support a
// `//specgen:requires` directive. Consider DotProductPairs:
//
//	// DotProductPairs computes the dot product of x and y.
//	//
//	//specgen:require z={xB}{xN*2}x{xL/2}
//	func DotProductPairs[E Nums, W Width, zE Nums](x, y Vec[E, W]) (z Vec[zE, W]) {
//	    ...
//	}
//
// The require expression refers to the types of each parameter and result by
// name. For Vec (and Array) arguments, each parameter and result also get
// several related variables:
//
//	v  = The whole vector type (e.g., Uint32x8)
//	vE = The element type (e.g., uint32)
//	vB = The base type (e.g., uint)
//	vN = The base type size (e.g., 32)
//	vL = The number of lanes in the vector or elements in the array (e.g., 8)
//	vW = The total bit width of the vector or array (e.g., 256)
//
// The full syntax for constraints is described in the [specgen/specexpr]
// package, but they often describe vector shapes like those in the
// DotProductPairs example. The form of these is:
//
//   - BaseNxL, which describes a vector with L elements of type BaseN;
//   - BaseNwW, which describes a vector of total width W; or
//   - BaseNs, which describes a scalable vector of BaseN elements.
//
// Base, N, L, or W can be either a literal or an expression in {}'s. For
// example, Uint32x{vL} or {zB}{zN}w128.
//
// For DotProductPairs, the constraint "z={vB}{vN*2}x{vL/2}" says the result z
// must have the same base type as v, but z's element type must be twice as
// wide, and z must have half the number of lanes of v.
//
// The DotProductPairs constraint could also have been written in any of the
// following equivalent ways:
//
//	z={vB}{vN*2}w{vW}       Constrain the total vector width
//	zB=vB zN=vN*2 zL=vL/2   Constrain each component separately
//	zE={vB}{vN*2} zW=vW     Constrain the element type and width separately
//
// ## Name and doc templates
//
// For some operations, the API name or documentation depends on type
// parameters. For these we support a simple template system where constraint
// variables can be referenced in curly braces, like {vE}, similar to {}
// expressions in shape constraints. For doc comments, these can be included
// directly in the doc comment. For names, we use a `//specgen:name` directive,
// such as
//
//	//specgen:name Load{z}
//	func LoadZ[E Elt, W Width](s []E) (z Vec[E, W]) {
//
// In this case, the spec function itself can be named anything (as long as it's
// exported), and the API name is generated from the directive. For example,
// when LoadZ is instantiated on uint32 and Width128, the API name generated
// from the template will be LoadUint32x4. This is particularly useful for
// constructor functions and conversion functions where types must appear in the
// name, such as LoadZ.
//
// ## The spec type system
//
// This package defines a set of types that translate to API types. We saw the
// [Vec] type above, which translates to a concrete BNxL (or BNs) vector type in
// the API, where L is determined from E and W.
//
// Masks are also represented using the [Vec] type, but with an element type
// from the [MaskElt] interface, such as Mask8, Mask16, etc. The generator
// translates these to Mask types in the API. Internal to the spec package,
// these are like a wide mask, where only 0 and ^0 are legal values for these
// elements.
//
// Similar to [Vec], there an [Array[E,W]] type that translates into a [L]E Go
// array type in the API.
//
// The type [UintN] stands for a uint type whose bit width is determined by spec
// constraints.
//
// Pointer and slice types translate directly to the API.
package spec