Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ library live in their own repositories.

## Current shipped status

The tip describes the shipped v1 line. The current release is **v1.20.0**;
The tip describes the shipped v1 line. The current release is **v1.21.0**;
the exported-function and generated-kernel counts are the machine-checked
ones in README.md and docs/platforms.md, held to the sources by
`internal/tests/docs`. The tier targets are sse2, avx2, avx512, neon, sve2,
Expand Down
47 changes: 47 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,50 @@
# Changelog

## v1.21.0


**The kernel guide's worked example is now checked against the tree.**
`docs/kernels.md` is the answer to "the operation I need isn't in the 403",
and its centre is one `spec.Kernel` literal whose eight annotated fields a
reader copies. Nothing looked inside it: the link gate checks its links and
the test-name gate checks the tests it cites, and neither reads a code block.
A renamed manifest field would leave the guide teaching a literal that does
not compile, in generated code the reader did not write. The gate reads the
field list out of the document rather than restating it, parses `spec.Kernel`
from source (`tools/` is a separate module and must never become a consumer
dependency), and also resolves the example's `RefFunc` against
`internal/ref` and its `Field` against `internal/kernel` -- the two wirings
that are easiest to forget, one of which once shipped past the whole normal
lane. Four mutations, all red: a field renamed in the guide, the same field
renamed in the struct, an unexported `RefFunc`, an unwired `Field`.

**`PolyEval`, `Convolve`, `Correlate` and `MovingAverage` now vectorize.**
Their kernels accumulate per output, so the innermost loop carried a
dependence LLVM cannot break without reassociating -- which the numerical
contract forbids -- and all eight symbols emitted zero packed arithmetic
instructions on every amd64 tier. Blocking the *outer* loop by 16 makes the
innermost loop independent while each output still evaluates the same terms
in the same order, so the results are bit-identical rather than close: 8-40
packed instructions per symbol now, and loong64 gains `simd_movavg_f32/f64`,
6,931 -> 6,933 kernels. Verified over 3.29M cases per tier on all nine tiers
including catastrophic cancellation and mid-accumulation overflow, where any
regrouping would show. Speed is not measured, and on arm64 the vectorizer
takes a different shape that costs stack frames -- `docs/wrong.md` entry 77
records both.

**Complex operations now run the generated assembly.** They never did:
`complexOps` returned the portable reference set directly, and the
generator emitted no complex entries into the per-tier dispatch tables, so
`DotComplex`, `DotComplexConj`, `ScaleComplex`, `SumComplex` and the
complex arithmetic set ran ordinary Go on every architecture while nine
tiers of generated complex assembly sat linked into a test-only aggregator.
Measured on amd64/avx512, scalar against the tier in one binary: 1.9x-12.9x
depending on operation and length. Results are unchanged -- the numerical
contract is the same fixed accumulation order, and the reference and every
tier agree bit for bit. No API change. `docs/wrong.md` records the finding,
the measurement, and the generator assertion that now refuses to emit a
dispatch file for a kernel group it cannot route.

## v1.20.0

**The columnar codec tier.** **`BitUnpackInto`** gains a width-
Expand Down Expand Up @@ -669,6 +714,8 @@ stops paying.
The README's function table claimed every entry had a runnable example. It was
false for 100 of 109 rows. All 109 have one now, and
`TestReadmeTableHasExamples` fails the build if a row appears without one.
(It is `TestOperationCatalogHasExamples` now; the guarantee did not change,
the name did, and this entry is left as it was written.)
`TestGuidesNameRealFunctions` does the same for the prose.

Writing them found three documentation bugs that only executing catches: the
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ live in their own repositories.

## Current shipped status

The current release is **v1.20.0**; the exported-function and
The current release is **v1.21.0**; the exported-function and
generated-kernel counts are the machine-checked ones in README.md and
docs/platforms.md. The v1 API is stable — every exported
function keeps its name, signature, and meaning, and so does the numerical
Expand Down
51 changes: 40 additions & 11 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -71,24 +71,53 @@ test-vec: ## Run the suite with GOEXPERIMENT=simd, which compiles vec.go
test-tiers: ## Run the suite once per instruction-set tier this CPU has
@for t in $(TIERS); do \
echo "--- GOSIMD=$$t"; \
GOSIMD=$$t $(GO) test $(PKG) || exit 1; \
GOSIMD=$$t $(GO) test -count=1 $(PKG) || exit 1; \
done

.PHONY: test-race
test-race: ## Full suite under the race detector
$(GO) test -race $(PKG)

# Two fuzz targets. FuzzDifferential drives the public API; the one under
# internal/conformance drives every generated kernel of every tier against the
# portable implementation, with the fuzzer choosing the bit patterns rather
# than a table choosing the values. For floating point that distinction is the
# whole point: the inputs that break a kernel are not large or small, they are
# a signalling NaN or a denormal at the exact exponent boundary.
# Every fuzz target in the tree, DISCOVERED rather than listed.
#
# FuzzDifferential drives the public API; the one under internal/conformance
# drives every generated kernel of every tier against the portable
# implementation, with the fuzzer choosing the bit patterns rather than a table
# choosing the values. For floating point that distinction is the whole point:
# the inputs that break a kernel are not large or small, they are a signalling
# NaN or a denormal at the exact exponent boundary.
#
# This comment used to open "Two fuzz targets" and the recipe named two. There
# are three, and TWO of them had never been fuzzed by this target:
#
# FuzzJSONMasksMatchesSeparateCalls never named; only its seed corpus ever
# ran, under `go test`
# FuzzDifferential named, and pointed at the ROOT package
# while the target lives in
# internal/tests/arrays
#
# The second is the dangerous one, because `go test -run '^$$' -fuzz X .` in a
# package with NO target called X exits 0 and prints `PASS ... 0.002s`. It does
# not error, so `make fuzz` had been reporting success for a step that fuzzed
# nothing. A gate that finishes in two milliseconds is not a fast gate.
#
# Discovery makes that unreachable: a target is only fuzzed in the package
# `go test -list` found it in. The counter below fails the target outright if
# it ends up running nothing at all.
.PHONY: fuzz
fuzz: ## Fuzz the public API and the tier-vs-reference differential
$(GO) test -run '^$$' -fuzz FuzzDifferential -fuzztime $(or $(FUZZTIME),60s) .
$(GO) test -run '^$$' -fuzz FuzzKernelsAgainstReference \
-fuzztime $(or $(FUZZTIME),60s) ./internal/conformance/
fuzz: ## Fuzz every target in the tree
@set -e; n=0; \
for pkg in $$($(GO) list ./...); do \
for t in $$($(GO) test -list '^Fuzz' $$pkg 2>/dev/null | grep '^Fuzz' || true); do \
echo "fuzz $$pkg $$t"; \
$(GO) test -run '^$$$$' -fuzz "^$$t$$" -fuzztime $(or $(FUZZTIME),60s) $$pkg; \
n=$$((n+1)); \
done; \
done; \
if [ "$$n" -eq 0 ]; then \
echo "make fuzz ran no targets" >&2; exit 1; \
fi; \
echo "fuzzed $$n target(s)"

# Every architecture with a backend, under emulation.
#
Expand Down
32 changes: 24 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
# simd.go
# simd.go — Fast Whole-Slice SIMD Vector Primitives & Text Scanning for Go (AVX-512, AVX2, NEON, SVE2, RVV)

[![Latest Release](docs/assets/badges/release.svg)](https://github.com/sebishogun/simd/releases/latest)
[![Go Reference](https://pkg.go.dev/badge/github.com/sebishogun/simd.svg)](https://pkg.go.dev/github.com/sebishogun/simd)
[![CI](https://github.com/sebishogun/simd/actions/workflows/ci-local.yml/badge.svg)](https://github.com/sebishogun/simd/actions/workflows/ci-local.yml)

**Fast slice math and text scanning for Go, using the vector unit your CPU
already has — without cgo.**
**Hardware-accelerated SIMD vector math, text scanning, matrix operations, and columnar codecs for Go — using the vector unit your CPU already has, without cgo.**

`simd` applies runtime-selected SIMD kernels to ordinary Go slices. The v1.20.0
tree contains 493 exported functions and 6,931 generated kernels for SSE2,
`simd` applies runtime-selected SIMD kernels to ordinary Go slices. The v1.21.0
tree contains 493 exported functions and 6,933 generated kernels for SSE2,
AVX2, AVX-512, NEON, SVE2, RVV, VSX, VX, and LASX. A portable Go path covers
every operation and every unsupported target.

Expand All @@ -23,7 +22,7 @@ kernels are compiled ahead of time and committed as assembly, so this is an
ordinary Go dependency with one transitive import (`golang.org/x/sys`, for CPU
feature detection). Dispatch is one static table per operation, so the linker
keeps only the operations a program actually calls: a binary using three
operation families does not retain all 6,931 kernels.
operation families does not retain all 6,933 kernels.

## Quick start

Expand Down Expand Up @@ -389,7 +388,7 @@ cgo.

## Engineering record

[**docs/wrong.md**](docs/wrong.md) records 79 things that measurement disproved,
[**docs/wrong.md**](docs/wrong.md) records 87 things that measurement disproved,
including changes that were deleted rather than shipped. Examples:

- Green test lanes had executed no accelerated code for months.
Expand All @@ -403,9 +402,26 @@ including changes that were deleted rather than shipped. Examples:
`docs/research/` carries the longer reasoning behind design decisions;
`05-decisions.md` is the decision record.

## Frequently asked questions

- **Does Go support SIMD vectorization natively without cgo?**
Yes. `simd` provides whole-slice SIMD vector acceleration in pure Go without cgo, C toolchains, or custom build tags. Ahead-of-time generated Plan 9 assembly kernels execute directly under Go's internal register ABI (ABIInternal).

- **Which SIMD instruction sets and CPU architectures are supported?**
`simd` ships 6,933 generated kernels across 10 ISA tiers: x86-64 (SSE2, AVX2, AVX-512), ARM64 (NEON, SVE2), RISC-V (RVV 1.0), PowerPC (VSX), SystemZ (VX), and LoongArch (LASX), with a portable Go fallback for all unsupported targets.

- **How does `simd.go` compare to `GOEXPERIMENT=simd` intrinsics in Go 1.26 and Go 1.27?**
Go 1.26 introduced experimental intrinsics (`simd/archsimd` on `amd64`), and Go 1.27 expanded it to `arm64` NEON and `wasm`. However, `GOEXPERIMENT=simd` requires consumers to set a build-time flag, does not support scalable vector units (ARM SVE2, RISC-V RVV 1.0), and lacks Clang unrolling optimizations ($4.4\times$ slower on whole-slice loops at $N=256$). `simd.go` requires zero build flags, supports 10 ISA tiers, and delivers optimal whole-slice throughput.

- **Does `simd.go` support WebAssembly (WASM)?**
On `GOARCH=wasm`, `simd` automatically executes the portable Go fallback path. Go's WASM assembler (`cmd/internal/obj/wasm`) lacks SIMD128 opcodes and raw byte lifting breaks WebAssembly stack validation, so WebAssembly SIMD is left to Go 1.27's internal compiler intrinsics.

- **What is the minimum slice length (crossover threshold) for SIMD in Go?**
The assembly call overhead is roughly 0.45 ns to 1.4 ns. For slice sizes under 16 to 64 elements, scalar Go is faster; for batches of hundreds to millions of elements, `simd` delivers up to $109\times$ speedups.

## Status

**v1.20.0.** The API is stable: every exported function keeps its name,
**v1.21.0.** The API is stable: every exported function keeps its name,
signature and meaning for the life of v1, and so does the numerical contract
above. [CHANGELOG.md](CHANGELOG.md) states exactly what compatibility covers
and what it excludes. [ROADMAP.md](ROADMAP.md) lists what is still open.
Expand Down
8 changes: 4 additions & 4 deletions complex.go
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@ func complexOps[C Complex]() *kernel.Complex[C] {
var zero C
switch any(zero).(type) {
case complex64:
return any(&refBase.C64).(*kernel.Complex[C])
return any(cacheC64.get(&refBase.C64, cplxC64ByTier[:])).(*kernel.Complex[C])
case complex128:
return any(&refBase.C128).(*kernel.Complex[C])
return any(cacheC128.get(&refBase.C128, cplxC128ByTier[:])).(*kernel.Complex[C])
}
panic("simd: unsupported complex type")
}
Expand All @@ -44,11 +44,11 @@ func complexParts[C Complex, R Float]() *kernel.ComplexParts[C, R] {
var zero C
switch any(zero).(type) {
case complex64:
if p, ok := any(&refBase.C64Parts).(*kernel.ComplexParts[C, R]); ok {
if p, ok := any(cacheC64Parts.get(&refBase.C64Parts, partsC64PartsByTier[:])).(*kernel.ComplexParts[C, R]); ok {
return p
}
case complex128:
if p, ok := any(&refBase.C128Parts).(*kernel.ComplexParts[C, R]); ok {
if p, ok := any(cacheC128Parts.get(&refBase.C128Parts, partsC128PartsByTier[:])).(*kernel.ComplexParts[C, R]); ok {
return p
}
}
Expand Down
Loading
Loading