translator: expand multi-architecture coverage from ecosystem discovery

.gitignore

@@ -0,0 +1 @@
+/_out/

AGENTS.md

@@ -0,0 +1,98 @@
+# plan9asm development guide
+
+plan9asm translates Go Plan 9 assembly to LLVM IR. A change is complete only
+when its accepted forms match Go, LLVM 22 compiles the affected targets, and
+tests establish the relevant runtime semantics.
+
+## Start here
+
+1. Inspect `git status --short`, `git worktree list`, and `git remote -v`.
+   Preserve existing changes and use a persistent development worktree.
+2. Read [current work](docs/development/current-work.md) when continuing PR 40.
+3. Read the guide for the task before editing:
+   - [Instruction families](docs/development/instructions.md): TDD, Go tables,
+     typed grammars, raw decoding, platform and semantic tests.
+   - [Validation and PR completion](docs/development/validation.md): tool setup,
+     full tests, benchmark, frozen reports, CI and review gates.
+   - [Discovery operations](testdata/discovery/README.md): scanning, automatic
+     deduplication/sorting, bidirectional cursors, traffic and ledger format.
+   - [Discovery verification](docs/development/discovery-verification.md):
+     standalone inventory, imports, applicability, cache cleanup and provenance.
+
+## Non-negotiable rules
+
+- Inspect the destination remote before writing. Push this contribution only
+  to the allowed `cpunion` fork, never to `origin` or `xgo-dev`. Do not merge,
+  approve or close upstream PRs, publish tags/releases, or change upstream
+  settings. Creating/updating this contribution PR is allowed.
+- Keep code and fixtures readable: use multi-line control flow and moderate
+  blank lines between logical phases. Use `apply_patch`, then `gofmt`.
+- Never commit personal paths, private hostnames/accounts or deployment
+  settings. Use relative paths, configurable variables and placeholders.
+- Develop with current Go 1.27 and LLVM 22 **only**. Never fall back to another
+  LLVM release. Missing required compilers, linkers or backends fail tests.
+- All five architectures are supported: `386`, `amd64`, `arm`, `arm64`,
+  `wasm`. Do not skip a form because it differs from the host architecture.
+  Host-inapplicable runtime tests need a required cross-runtime counterpart.
+- Run tests with Go while llgo support is incomplete; do not add `!llgo` tags.
+  Never generate LLVM `blockaddress` for wasm.
+- Use TDD and implement complete instruction families and Go operand formats,
+  not just an observed spelling. Consult full Go tables before implementation.
+- Never disguise unsupported instructions, translation/LLVM failures, missing
+  tools or infrastructure errors as success or source N/A.
+- An exact external module version may be `skipped_invalid_source` only when
+  `testdata/corpus/invalid-machine-code.json` pins the source SHA-256 and
+  executable evidence: either LLVM 22 rejects the evaluated raw ARM64 WORD,
+  or Go's own object places an unrelocated raw AMD64 RIP target outside every
+  TEXT symbol with its named constant absent. The report/ledger retain the
+  reason. A skip is never a pass.
+- A frozen historical mirror/fork may be `skipped_superseded` only when
+  `testdata/corpus/superseded-modules.json` names an exact newer version
+  already in the scan ledger and gives reviewable project-identity evidence.
+  This is separate from both source N/A and assembly success; the replacement
+  is independently scanned and, if it has assembly, tested.
+- A private-extension gap may be `skipped_private_extension` only for the
+  exact file and target pinned in `testdata/corpus/private-extensions.json`.
+  Verify the source hash and current Go assembler, compile every other
+  applicable file, and count the candidate separately from passes.
+- Freeze source, tools and ledger during corpus verification. A changed input
+  invalidates the run. Do not rebase, rewrite or import records into that tree
+  while tests are running; use a separate persistent worktree for development.
+- Keep reports/binaries under ignored `_out/`. Never commit caches, ZIPs,
+  compressed discovery results or obsolete per-run ledgers, even in history.
+- Commit verified development promptly. Keep PR 40 draft until current-head
+  tests, CI, review and coverage meet the completion gates.
+
+## Common commands
+
+Run from the repository root after selecting the tools described in
+[validation](docs/development/validation.md). Keep focused red/green logs.
+
+```sh
+go test . -run '<focused-family-regex>' -count=1
+go test ./... -count=1 -timeout=20m
+(cd cmd/plan9asm && go test ./... -count=1)
+(cd cmd/plan9asmll && go test ./... -count=1)
+
+scripts/check-go-asm-coverage.sh
+scripts/check-arm64-plan9-corpus.sh
+scripts/check-stdlib-corpus.sh
+scripts/benchmark-compile.sh
+
+go run ./cmd/plan9asmdiscover -status -out-dir testdata/discovery/ledger
+bash scripts/discovery-status.sh
+scripts/update-assembly-ledger.sh
+```
+
+New external-library scans and compilation use current Go 1.27, not the whole
+Go 1.20–1.27 matrix. That compatibility matrix belongs to the official corpus.
+Discovery records prove inspection; corpus reports prove translation/object
+compilation; runtime tests prove only their executed semantics. Keep these
+claims separate.
+
+## Documentation maintenance
+
+Keep this file a short entry point. Put durable procedures in the linked
+guides and replace, rather than append to, the current-work checkpoint. Keep
+scan/coverage funnel tables in the PR body; derive them from validated reports.
+Old progress narratives remain in Git history, not in this guide.

amd64_abi.go

@@ -0,0 +1,92 @@
+package plan9asm
+
+import "fmt"
+
+func (c *amd64Ctx) abi0CallStackPtr(off int64) (string, error) {
+	sp, err := c.loadReg(SP)
+	if err != nil {
+		return "", fmt.Errorf("ABI0 call stack: %w", err)
+	}
+	addr := sp
+	if off != 0 {
+		next := c.newTmp()
+		fmt.Fprintf(c.b, "  %%%s = add i64 %s, %d\n", next, sp, off)
+		addr = "%" + next
+	}
+	ptr := c.newTmp()
+	fmt.Fprintf(c.b, "  %%%s = inttoptr i64 %s to ptr\n", ptr, addr)
+	return "%" + ptr, nil
+}
+
+func (c *amd64Ctx) abi0CallArgs(callee string, sig FuncSig) ([]string, error) {
+	slotsByArg := make([][]FrameSlot, len(sig.Args))
+	for _, slot := range sig.Frame.Params {
+		if slot.Index < 0 || slot.Index >= len(sig.Args) {
+			return nil, fmt.Errorf("amd64 call %q: ABI0 parameter at +%d has invalid argument index %d", callee, slot.Offset, slot.Index)
+		}
+		slotsByArg[slot.Index] = append(slotsByArg[slot.Index], slot)
+	}
+	args := make([]string, 0, len(sig.Args))
+	for argIndex, argType := range sig.Args {
+		slots := slotsByArg[argIndex]
+		if len(slots) == 0 {
+			return nil, fmt.Errorf("amd64 call %q: ABI0 argument %d has no frame slot", callee, argIndex)
+		}
+		if len(slots) == 1 && len(frameSlotFields(slots[0])) == 0 {
+			if slots[0].Type != argType {
+				return nil, fmt.Errorf("amd64 call %q: ABI0 argument %d frame type %s does not match %s", callee, argIndex, slots[0].Type, argType)
+			}
+			ptr, err := c.abi0CallStackPtr(slots[0].Offset)
+			if err != nil {
+				return nil, err
+			}
+			value := c.newTmp()
+			fmt.Fprintf(c.b, "  %%%s = load %s, ptr %s, align 1\n", value, argType, ptr)
+			args = append(args, fmt.Sprintf("%s %%%s", argType, value))
+			continue
+		}
+		aggregate := "undef"
+		for _, slot := range slots {
+			if len(frameSlotFields(slot)) == 0 {
+				return nil, fmt.Errorf("amd64 call %q: ABI0 aggregate argument %d has a scalar frame slot", callee, argIndex)
+			}
+			ptr, err := c.abi0CallStackPtr(slot.Offset)
+			if err != nil {
+				return nil, err
+			}
+			value := c.newTmp()
+			fmt.Fprintf(c.b, "  %%%s = load %s, ptr %s, align 1\n", value, slot.Type, ptr)
+			inserted := c.newTmp()
+			fmt.Fprintf(c.b, "  %%%s = insertvalue %s %s, %s %%%s%s\n", inserted, argType, aggregate, slot.Type, value, frameSlotExtractSuffix(slot))
+			aggregate = "%" + inserted
+		}
+		args = append(args, fmt.Sprintf("%s %s", argType, aggregate))
+	}
+	return args, nil
+}
+
+func (c *amd64Ctx) storeABI0CallResult(callee string, sig FuncSig, result string) error {
+	if len(sig.Frame.Results) == 0 {
+		return fmt.Errorf("amd64 call %q: ABI0 result %s has no frame slot", callee, sig.Ret)
+	}
+	fields, aggregate := parseLiteralStructFields(sig.Ret)
+	for _, slot := range sig.Frame.Results {
+		value := result
+		if aggregate {
+			if slot.Index < 0 || slot.Index >= len(fields) || fields[slot.Index] != slot.Type {
+				return fmt.Errorf("amd64 call %q: ABI0 result slot %d does not match %s", callee, slot.Index, sig.Ret)
+			}
+			extracted := c.newTmp()
+			fmt.Fprintf(c.b, "  %%%s = extractvalue %s %s, %d\n", extracted, sig.Ret, result, slot.Index)
+			value = "%" + extracted
+		} else if slot.Index != 0 || slot.Type != sig.Ret {
+			return fmt.Errorf("amd64 call %q: ABI0 scalar result frame does not match %s", callee, sig.Ret)
+		}
+		ptr, err := c.abi0CallStackPtr(slot.Offset)
+		if err != nil {
+			return err
+		}
+		fmt.Fprintf(c.b, "  store %s %s, ptr %s, align 1\n", slot.Type, value, ptr)
+	}
+	return nil
+}

amd64_abi0_anchor_test.go

@@ -0,0 +1,111 @@
+package plan9asm
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+func TestAMD64ABI0AnchorPreservesTailJumpRelocation(t *testing.T) {
+	args := make([]LLVMType, 15)
+	for i := range args {
+		args[i] = I32
+	}
+	for _, anchorName := range []string{"gcasmABI0Keep", "relocationKeep"} {
+		source := fmt.Sprintf("TEXT ·%s(SB),NOSPLIT,$0-0\n", anchorName) +
+			"JMP ·Fn(SB)\nJMP ·FnTwo(SB)\nJMP ·FnThree(SB)\n"
+		file, err := Parse(ArchAMD64, source)
+		if err != nil {
+			t.Fatal(err)
+		}
+		sigs := map[string]FuncSig{
+			"example." + anchorName: {Name: "example." + anchorName, Ret: Void},
+			"example.Fn":            {Name: "example.Fn", Args: args, Ret: I32},
+			"example.FnTwo":         {Name: "example.FnTwo", Args: args, Ret: I32},
+			"example.FnThree":       {Name: "example.FnThree", Args: args, Ret: I32},
+		}
+		for _, target := range []struct {
+			goarch string
+			triple string
+		}{
+			{"amd64", "x86_64-unknown-linux-gnu"},
+			{"amd64", "x86_64-apple-darwin"},
+			{"amd64", "x86_64-pc-windows-msvc"},
+			{"386", "i386-unknown-linux-gnu"},
+			{"386", "i386-apple-darwin"},
+			{"386", "i686-pc-windows-msvc"},
+		} {
+			triple := target.triple
+			t.Run(anchorName+"/"+triple, func(t *testing.T) {
+				ir, err := Translate(file, Options{
+					Goarch: target.goarch, TargetTriple: triple,
+					ResolveSym: testResolveSym("example"), Sigs: sigs,
+				})
+				if err != nil {
+					t.Fatal(err)
+				}
+				for _, symbol := range []string{"example.Fn", "example.FnTwo", "example.FnThree"} {
+					if !strings.Contains(ir, "ptr @"+symbol) {
+						t.Fatalf("ABI0 anchor omitted direct symbol relocation for %s", symbol)
+					}
+				}
+				llc := findLLVM22Tool("llc")
+				if llc == "" {
+					t.Fatal("LLVM 22 llc not found")
+				}
+				objdump := findLLVM22Tool("llvm-objdump")
+				if objdump == "" {
+					t.Fatal("LLVM 22 llvm-objdump not found")
+				}
+				dir := t.TempDir()
+				llPath := filepath.Join(dir, "anchor.ll")
+				object := filepath.Join(dir, "anchor.o")
+				if err := os.WriteFile(llPath, []byte(ir), 0644); err != nil {
+					t.Fatal(err)
+				}
+				if output, err := exec.Command(llc, "-mtriple="+triple, "-filetype=obj", llPath, "-o", object).CombinedOutput(); err != nil {
+					t.Fatalf("LLVM 22 object compile: %v\n%s", err, output)
+				}
+				output, err := exec.Command(objdump, "-dr", object).CombinedOutput()
+				if err != nil {
+					t.Fatalf("LLVM 22 object dump: %v\n%s", err, output)
+				}
+				if !regexp.MustCompile(`(?m)^\s*0: e9 `).Match(output) {
+					t.Fatalf("anchor is not an entry-point tail jump with target relocation:\n%s", output)
+				}
+				for _, symbol := range []string{"example.Fn", "example.FnTwo", "example.FnThree"} {
+					if !strings.Contains(string(output), symbol) {
+						t.Fatalf("object omitted relocation for %s:\n%s", symbol, output)
+					}
+				}
+			})
+		}
+	}
+}
+
+func TestAMD64NonAnchorStillRejectsUnmappedTailArguments(t *testing.T) {
+	const source = "TEXT ·forward(SB),NOSPLIT,$0-0\nJMP ·Fn(SB)\n"
+	file, err := Parse(ArchAMD64, source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	args := make([]LLVMType, 7)
+	for i := range args {
+		args[i] = I32
+	}
+	_, err = Translate(file, Options{
+		Goarch: "amd64", TargetTriple: "x86_64-unknown-linux-gnu",
+		ResolveSym: testResolveSym("example"),
+		Sigs: map[string]FuncSig{
+			"example.forward": {Name: "example.forward", Ret: Void},
+			"example.Fn":      {Name: "example.Fn", Args: args, Ret: I32},
+		},
+	})
+	if err == nil || !strings.Contains(err.Error(), "missing arg reg") {
+		t.Fatalf("unmapped non-anchor tail arguments unexpectedly accepted: %v", err)
+	}
+}