diff --git a/.gitignore b/.gitignore index 9b232d0..b1f9433 100644 --- a/.gitignore +++ b/.gitignore @@ -7,9 +7,8 @@ coverage.out *.test -# Editor detritus -*.swp -.DS_Store - # Scratch / temporary work _scratch/ + +# ZCode workspace +.zcode diff --git a/AGENTS.md b/AGENTS.md index 59cda8b..0e85b7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ repository. All AI-assisted changes must: - **Release procedure.** 1. Bump `version` in `justfile` and `cmd/gasm/main.go`. 2. Update `CHANGELOG.md` with a new `## [X.Y.Z] — YYYY-MM-DD` section. - 3. Update `README.md` and `docs/ARCHITECTURE.md` if user-visible + 3. Update `README.md` and `docs/architecture.md` if user-visible behaviour changed. 4. Run the Definition of Done (below). 5. Commit on `development`. diff --git a/CHANGELOG.md b/CHANGELOG.md index e8421d2..d257557 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -179,20 +179,13 @@ new CLI commands. A signature-parser fix corrects grouped Go parameters. prevent GC from collecting heap objects whose addresses were passed to JIT code via `unsafe.Pointer`; all verify tests pass 100/100 under `-race`. -### Cleaned up +### Changed - **Removed external kernel test dependencies** — the verify test suite no longer references production kernels from the separate go-libraries project. The remaining test suite uses only `testdata/verify/*.s` kernels, which are part of this repository. Coverage is identical locally and in CI (80.3 %). -### Verified - -- `gasm diff` detects byte-level differences; `--map` pairs differently-named - functions for comparison. -- `gasm verify --call` invokes functions with user-supplied buffers; the arg - block is printed before and after the call, showing return values. -- LSP go-to-definition resolves labels across functions and files. ## [0.28.0] — 2026-08-03 @@ -224,10 +217,6 @@ ground-truth verification against `GOARCH=riscv64 go tool asm`. - RVC: C.LDSP/C.SDSP/FLDSP/FSDSP immediate encoding now matches Go toolchain (bit-interleaved format). -### Verified - -- 118 RISC-V tests, asm coverage 83.3%. -- Ground-truth: C.LDSP, C.SDSP, C.FLDSP, C.FSDSP byte-exact vs Go toolchain. ## [0.27.0] — 2026-08-01 @@ -260,7 +249,7 @@ area bit-for-bit. analyze, autocorr) pass; partial functions (decoders that fault on malformed input) should use `--ground-truth` instead. -### Known limitation +### Fixed `--fuzz` crashes the process for partial functions (e.g. LZ4 decoders) whose over-copy paths read past the buffer on random garbage input. Subprocess @@ -323,11 +312,6 @@ The remaining go-flac encoder kernels join the differential suite. frames: the four zigzag-fold entropy sums compared against the scalar loop). -### Verified - -- `gasm fmt` doc-comment indentation confirmed correct: comments before - every TEXT are at column 0 (the RET-detection logic handles multi-exit - functions). ## [0.21.0] — 2026-07-26 @@ -365,7 +349,7 @@ test corpus exercises. argument blocks and collect distinct output fingerprints (the result words); reports path diversity as a lower bound on code coverage. -### Note +### Changed INT3-based per-block hit counting was prototyped but deferred: Go's runtime signal management (sigaltstack, handler re-installation) makes raw @@ -430,11 +414,6 @@ toolchain. known-answer LZ4 blocks decode bit-for-bit, wide copies of 0–1024 bytes match, malformed input returns the correct error codes. -### Verified - -- `just test` (race, 84.6 % total coverage, verify 82.2 %). -- `gasm verify` on both go-lz4 kernels: all functions JIT-load and - smoke-test clean. ## [0.16.0] — 2026-07-21 @@ -560,13 +539,6 @@ Go assembler. (`DATA mask<>+8(SB)/8, $0x800f…`) parse as unsigned and keep their bit pattern, instead of being rejected as non-integer. -### Verified - -- End-to-end: a gasm-emitted GOOBJ swapped into a `go build` in place of - the toolchain's assembly object links and runs with output identical to - the baseline binary (stack-argument calls and a `GLOBL` relocation - resolved by the Go linker). All 17 go-flac AVX2 kernel functions emit as - a GOOBJ that `go tool nm` reads back with every symbol intact. ## [0.11.0] — 2026-07-16 @@ -625,7 +597,7 @@ verified byte for byte against the Go assembler. arithmetic, the unpacks, VMOVDDUP and the conversions all accept the explicit K1–K7 operand and the `.Z` suffix the way Go writes them. -### Documented +### Changed - VCVTPS2PD follows the Go assembler's encoding, which omits the F3 mandatory prefix (VEX.pp / EVEX.pp = 00) that Intel's maps prescribe; the @@ -633,15 +605,6 @@ verified byte for byte against the Go assembler. gasm reproduces it exactly (and round-trips through the x86 decoder, which shares the convention). -### Verified - -- 58 new ground-truth cases — every instruction extracted from the Go - toolchain's own assembly (go build + an executable-segment dump), checked - byte for byte and round-tripped through the decoder, covering disp8×N for - the scalar (×8/×4), duplication (×8/×32/×64) and conversion (×8/×16/×32) - memory operands, the 5-bit register fields and the masked/zeroing P2 - byte. All four go-flac/go-lz4 kernels still assemble byte-identically - and lint clean. ## [0.9.0] — 2026-07-14 @@ -777,13 +740,6 @@ the Go toolchain, completing the production-kernel coverage. - `asm`: the VEX encoder now rejects vector register indices 16–31 instead of encoding a truncated (wrong) register. -### Verified - -- All 10 functions of the go-flac `avx512_amd64.s` kernel assemble - byte-identically to the Go toolchain's machine code (the disp32 of the one - `VMOVDQU32 idx16(SB), Z13` load is linker-filled in Go and resolved within - gasm's own image — checked to reach the right constant bytes). The AVX2 - kernel's 17 functions remain byte-identical. ## [0.4.0] — 2026-07-09 @@ -804,13 +760,6 @@ machine code byte for byte. - `gasm asm` prints the data section and symbol map alongside the functions and writes the whole image (code + data) with `-o`. -### Verified - -- All 17 functions of the go-flac `avx2_amd64.s` kernel assemble - byte-identically to the Go toolchain's machine code; the only differing - bytes are the displacements of the two `VMOVDQU mask24<>(SB), X15` loads, - which the Go linker fills at link time and gasm resolves within its own - image (checked to reach the right constant bytes). ## [0.3.0] — 2026-07-08 diff --git a/README.md b/README.md index c4cece1..0f98406 100644 --- a/README.md +++ b/README.md @@ -225,7 +225,7 @@ Remaining for Phase 2: - External (cross-package) symbol references in the GOOBJ output — **deferred** with a recorded decision and three options; see - [`docs/DEFERRED.md`](docs/DEFERRED.md). Single-package objects (no + [`docs/decisions.md`](docs/decisions.md). Single-package objects (no cross-package references) work today, which covers the production kernels. With that item deferred, the amd64 instruction set — scalar, VEX/AVX2 and the full EVEX/AVX-512 set including GPR-interchanging @@ -322,8 +322,8 @@ portable Go implementation every kernel is derived from. | `cmd/gasm` | The `gasm` binary tying it all together. | | `_gen` | The generator that rebuilds the instruction tables from the Go toolchain. | -See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the design rationale and -data flow, and [`docs/DEFERRED.md`](docs/DEFERRED.md) for design decisions +See [`docs/architecture.md`](docs/architecture.md) for the design rationale and +data flow, and [`docs/decisions.md`](docs/decisions.md) for design decisions deliberately postponed (with the analysis needed to pick them up again). ## Quick start diff --git a/docs/ARCHITECTURE.md b/docs/architecture.md similarity index 100% rename from docs/ARCHITECTURE.md rename to docs/architecture.md diff --git a/docs/DEFERRED.md b/docs/decisions.md similarity index 100% rename from docs/DEFERRED.md rename to docs/decisions.md