feat(fmt): go-fmt-style recursive formatting and canonical blank-line layout

Assisted-by: Qwen 3.8 Max Preview

asm/encode.go

@@ -93,6 +93,8 @@ func (e *enc) encode(mnem string, ops []Operand) error {
 		return e.encodeMovExtend(base, ops)
 	case "CVTSL2SD", "CVTSQ2SD":
 		return e.encodeCvtsi2sd(base == "CVTSQ2SD", ops)
+	case "MOVOU", "MOVO", "MOVUPS", "MOVAPS", "MOVUPD", "MOVAPD", "MOVSD", "MOVSS":
+		return e.encodeSSEMove(sseMoveTable[base], ops)
 	}
 	return fmt.Errorf("unsupported instruction %q", mnem)
 }

asm/encode_test.go

@@ -127,6 +127,52 @@ func TestControl(t *testing.T) {
 	checkOp(t, x86asm.JBE, "JLS", Imm(0))
 }
 
+// TestSSEMoveGroundTruth checks the legacy (non-VEX) SSE moves byte for byte
+// against the Go assembler.  wantOp is the decoder's name, which differs from
+// the Plan 9 spelling for the octa moves (MOVOU = MOVDQU, MOVO = MOVDQA).
+func TestSSEMoveGroundTruth(t *testing.T) {
+	cases := []struct {
+		name   string
+		mnem   string
+		ops    []Operand
+		want   string
+		wantOp string
+	}{
+		{"MOVOU (SI),X1", "MOVOU", []Operand{Ptr(SI, 0, 16), vreg(t, "X1")}, "f30f6f0e", "MOVDQU"},
+		{"MOVOU X3,(DI)", "MOVOU", []Operand{vreg(t, "X3"), Ptr(DI, 0, 16)}, "f30f7f1f", "MOVDQU"},
+		{"MOVOU X1,X2", "MOVOU", []Operand{vreg(t, "X1"), vreg(t, "X2")}, "f30f6fd1", "MOVDQU"},
+		{"MOVOU (SI)(BX*4),X9", "MOVOU", []Operand{Idx(SI, BX, 4, 0, 16), vreg(t, "X9")}, "f3440f6f0c9e", "MOVDQU"},
+		{"MOVO (SI),X1", "MOVO", []Operand{Ptr(SI, 0, 16), vreg(t, "X1")}, "660f6f0e", "MOVDQA"},
+		{"MOVO X3,(DI)", "MOVO", []Operand{vreg(t, "X3"), Ptr(DI, 0, 16)}, "660f7f1f", "MOVDQA"},
+		{"MOVUPS (SI),X1", "MOVUPS", []Operand{Ptr(SI, 0, 16), vreg(t, "X1")}, "0f100e", "MOVUPS"},
+		{"MOVAPS X3,(DI)", "MOVAPS", []Operand{vreg(t, "X3"), Ptr(DI, 0, 16)}, "0f291f", "MOVAPS"},
+		{"MOVUPD (SI),X1", "MOVUPD", []Operand{Ptr(SI, 0, 16), vreg(t, "X1")}, "660f100e", "MOVUPD"},
+		{"MOVAPD X3,(DI)", "MOVAPD", []Operand{vreg(t, "X3"), Ptr(DI, 0, 16)}, "660f291f", "MOVAPD"},
+		{"MOVSD (SI),X1", "MOVSD", []Operand{Ptr(SI, 0, 8), vreg(t, "X1")}, "f20f100e", "MOVSD_XMM"},
+		{"MOVSD X1,X2", "MOVSD", []Operand{vreg(t, "X1"), vreg(t, "X2")}, "f20f10d1", "MOVSD_XMM"},
+		{"MOVSS X3,(DI)", "MOVSS", []Operand{vreg(t, "X3"), Ptr(DI, 0, 4)}, "f30f111f", "MOVSS"},
+	}
+	for _, c := range cases {
+		code, err := Encode(c.mnem, c.ops...)
+		if err != nil {
+			t.Errorf("%s: Encode: %v", c.name, err)
+			continue
+		}
+		if got := hexCompact(code); got != c.want {
+			t.Errorf("%s: bytes %s, want %s", c.name, got, c.want)
+			continue
+		}
+		inst, err := x86asm.Decode(code, 64)
+		if err != nil {
+			t.Errorf("%s: Decode(%x): %v", c.name, code, err)
+			continue
+		}
+		if inst.Op.String() != c.wantOp {
+			t.Errorf("%s: decoded as %s", c.name, inst.Op.String())
+		}
+	}
+}
+
 // TestGoFlacScalarTail encodes the scalar tail of an analyze kernel to confirm
 // the encoder handles a realistic instruction sequence.
 func TestGoFlacScalarTail(t *testing.T) {

asm/evex.go

@@ -115,6 +115,8 @@ type evexMoveSpec struct {
 var evexMoveTable = map[string]evexMoveSpec{
 	// EVEX.128/256/512.F3.0F.W0 — unaligned integer move.
 	"VMOVDQU32": {1, 2, 0x6F, 0x7F, 0, [3]int{16, 32, 64}},
+	// EVEX.128/256/512.F3.0F.W1 — unaligned qword move.
+	"VMOVDQU64": {1, 2, 0x6F, 0x7F, 1, [3]int{16, 32, 64}},
 	// EVEX.128/256/512.66.0F.W1 — unaligned packed double move.
 	"VMOVUPD": {1, 1, 0x10, 0x11, 1, [3]int{16, 32, 64}},
 }

asm/evex_test.go

@@ -61,6 +61,10 @@ func TestEvexGroundTruth(t *testing.T) {
 		{"VMOVDQU32 16(SI)(R15*4),Z4", "VMOVDQU32", []Operand{Idx(SI, vreg(t, "R15"), 4, 16, 64), vreg(t, "Z4")}, "62b17e486fa4be10000000"},
 		{"VMOVDQU32 Z0,4(SI)(AX*1)", "VMOVDQU32", []Operand{vreg(t, "Z0"), Idx(SI, AX, 1, 4, 64)}, "62f17e487f840604000000"},
 		{"VMOVDQU32 Z3,(DI)(R15*4)", "VMOVDQU32", []Operand{vreg(t, "Z3"), Idx(DI, vreg(t, "R15"), 4, 0, 64)}, "62b17e487f1cbf"},
+		// VMOVDQU64 — the W1 qword variant.
+		{"VMOVDQU64 (SI)(R15*4),Z3", "VMOVDQU64", []Operand{Idx(SI, vreg(t, "R15"), 4, 0, 64), vreg(t, "Z3")}, "62b1fe486f1cbe"},
+		{"VMOVDQU64 Z0,4(SI)(AX*1)", "VMOVDQU64", []Operand{vreg(t, "Z0"), Idx(SI, AX, 1, 4, 64)}, "62f1fe487f840604000000"},
+		{"VMOVDQU64 Z1,Z2", "VMOVDQU64", []Operand{vreg(t, "Z1"), vreg(t, "Z2")}, "62f1fe487fca"},
 		{"VMOVUPD (DI),Z14", "VMOVUPD", []Operand{Ptr(DI, 0, 64), vreg(t, "Z14")}, "6271fd481037"},
 		{"VMOVUPD 64(DI),Z14", "VMOVUPD", []Operand{Ptr(DI, 64, 64), vreg(t, "Z14")}, "6271fd48107701"},
 		// Conversions and narrowing stores (reg = wide source).

asm/instrs.go

@@ -661,6 +661,66 @@ func (e *enc) encodeMovExtend(base string, ops []Operand) error {
 	return e.emit(i)
 }
 
+// --- legacy SSE moves --------------------------------------------------------
+
+// sseMove describes a legacy (non-VEX) SSE move: a mandatory prefix plus a
+// load opcode (reg = destination, rm = source) and a store opcode (the
+// reverse).  The Plan 9 names MOVOU/MOVO are the integer unaligned/aligned
+// octa moves (MOVDQU/MOVDQA), not the packed-single ones.
+type sseMove struct {
+	prefix byte // 0, 0x66, 0xF2 or 0xF3
+	load   byte
+	store  byte
+}
+
+var sseMoveTable = map[string]sseMove{
+	"MOVOU":  {0xF3, 0x6F, 0x7F}, // MOVDQU — unaligned octa
+	"MOVO":   {0x66, 0x6F, 0x7F}, // MOVDQA — aligned octa
+	"MOVUPS": {0x00, 0x10, 0x11}, // unaligned packed single
+	"MOVAPS": {0x00, 0x28, 0x29}, // aligned packed single
+	"MOVUPD": {0x66, 0x10, 0x11}, // unaligned packed double
+	"MOVAPD": {0x66, 0x28, 0x29}, // aligned packed double
+	"MOVSD":  {0xF2, 0x10, 0x11}, // scalar double
+	"MOVSS":  {0xF3, 0x10, 0x11}, // scalar single
+}
+
+// encodeSSEMove encodes a legacy SSE move: a vector-to-vector move uses the
+// load form (reg = destination), matching the Go assembler.
+func (e *enc) encodeSSEMove(m sseMove, ops []Operand) error {
+	if len(ops) != 2 {
+		return fmt.Errorf("SSE move expects 2 operands, got %d", len(ops))
+	}
+	src, dst := ops[0], ops[1]
+	srcReg, srcVec := vecReg(src)
+	dstReg, dstVec := vecReg(dst)
+	op := m.store
+	var reg Reg
+	var rm Operand
+	switch {
+	case srcVec && dstVec:
+		op = m.load
+		reg, rm = dstReg, src
+	case srcVec:
+		if _, ok := dst.(Mem); !ok {
+			return fmt.Errorf("SSE move: invalid destination operand")
+		}
+		reg, rm = srcReg, dst
+	case dstVec:
+		if _, ok := src.(Mem); !ok {
+			return fmt.Errorf("SSE move: invalid source operand")
+		}
+		op = m.load
+		reg, rm = dstReg, src
+	default:
+		return fmt.Errorf("SSE move needs a vector register operand")
+	}
+	i := &instr{prefix: m.prefix, opcode: []byte{0x0F, op}, modrm: -1, sib: -1}
+	if err := setRM(i, reg, rm, 8); err != nil {
+		return err
+	}
+	return e.emit(i)
+}
+
 // --- CVTSL2SD / CVTSQ2SD -----------------------------------------------------
 
 // encodeCvtsi2sd encodes a signed integer to scalar double conversion

cmd/gasm/main.go

@@ -11,7 +11,9 @@ import (
 	"flag"
 	"fmt"
 	"io"
+	"io/fs"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"sourcedock.dev/petrbalvin/gasm-devkit/arch"
@@ -26,7 +28,7 @@ import (
 
 // version is the release version, stamped at build time via
 // -ldflags "-X main.version=…" (defaulting to the current release).
-var version = "0.5.0"
+var version = "0.7.0"
 
 func main() {
 	if len(os.Args) < 2 {
@@ -63,7 +65,8 @@ func usage(w io.Writer) {
 Usage:
   gasm tokens <file>          print the lexical token stream
   gasm parse  <file>          parse and report syntax errors
-  gasm fmt    [-w] <file...>  canonicalise formatting (-w writes in place)
+  gasm fmt    [-w] [path...]  canonicalise formatting (no path or a directory:
+                              reformat every .s below it in place, like go fmt)
   gasm lint   <file...>       run static checks
   gasm asm    [-o out.bin] <file>  assemble to machine code (amd64, Phase 2)
   gasm lsp                    run the language server over stdio
@@ -130,15 +133,39 @@ func cmdParse(args []string) int {
 }
 
 func cmdFmt(args []string) int {
-	fs := flag.NewFlagSet("fmt", flag.ExitOnError)
+	fs_ := flag.NewFlagSet("fmt", flag.ExitOnError)
-	write := fs.Bool("w", false, "write result to the source file")
+	write := fs_.Bool("w", false, "write result to the source file")
-	fs.Parse(args)
+	fs_.Parse(args)
-	if fs.NArg() == 0 {
+	// Like go fmt: with no arguments, or with a directory argument, every .s
-		fmt.Fprintln(os.Stderr, "usage: gasm fmt [-w] <file...>")
+	// file below the directory is formatted in place and the names of the
-		return 2
+	// changed files are listed; explicit file arguments keep the -w / stdout
+	// behaviour.
+	paths := fs_.Args()
+	dirMode := len(paths) == 0
+	if dirMode {
+		paths = []string{"."}
+	}
+	var files []string
+	for _, p := range paths {
+		info, err := os.Stat(p)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "gasm:", err)
+			return 1
+		}
+		if info.IsDir() {
+			dirMode = true
+			found, err := asmFiles(p)
+			if err != nil {
+				fmt.Fprintln(os.Stderr, "gasm:", err)
+				return 1
+			}
+			files = append(files, found...)
+			continue
+		}
+		files = append(files, p)
 	}
 	rc := 0
-	for _, path := range fs.Args() {
+	for _, path := range files {
 		src, err := readSource(path)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, "gasm:", err)
@@ -146,11 +173,15 @@ func cmdFmt(args []string) int {
 			continue
 		}
 		out := format.Source(path, src)
-		if *write {
+		if dirMode || *write {
 			if out != src {
 				if err := os.WriteFile(path, []byte(out), 0o644); err != nil {
 					fmt.Fprintln(os.Stderr, "gasm:", err)
 					rc = 1
+					continue
+				}
+				if dirMode {
+					fmt.Println(path)
 				}
 			}
 			continue
@@ -160,6 +191,29 @@ func cmdFmt(args []string) int {
 	return rc
 }
 
+// asmFiles collects the .s files below dir, skipping directories whose name
+// starts with "." or "_" — as the go tooling does, which keeps .git and
+// scratch or reference trees (e.g. _refs) untouched.
+func asmFiles(dir string) ([]string, error) {
+	var out []string
+	err := filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			if path != dir && (strings.HasPrefix(d.Name(), ".") || strings.HasPrefix(d.Name(), "_")) {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if strings.HasSuffix(d.Name(), ".s") {
+			out = append(out, path)
+		}
+		return nil
+	})
+	return out, err
+}
+
 func cmdLint(args []string) int {
 	fs := flag.NewFlagSet("lint", flag.ExitOnError)
 	disable := fs.String("disable", "", "comma-separated rule codes to disable")

cmd/gasm/main_test.go

@@ -52,6 +52,54 @@ func capture(fn func() int) (stdout, stderr string, code int) {
 	return string(ob), string(eb), code
 }
 
+// TestCmdFmtRecursive checks the go-fmt-style directory mode: with no
+// arguments every .s file below the working directory is formatted in place
+// ("." and "_" directories skipped), changed files are listed, and a second
+// run is a no-op.
+func TestCmdFmtRecursive(t *testing.T) {
+	tmp := t.TempDir()
+	t.Chdir(tmp)
+	unformatted := []byte("TEXT ·f(SB),NOSPLIT,$0\nRET\n")
+	write := func(path string) {
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, unformatted, 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write("a_amd64.s")
+	write(filepath.Join("sub", "b_amd64.s"))
+	write(filepath.Join("_refs", "c_amd64.s"))
+	write(filepath.Join(".git", "d_amd64.s"))
+
+	out, errOut, code := capture(func() int { return cmdFmt(nil) })
+	if code != 0 {
+		t.Fatalf("code = %d (%s)", code, errOut)
+	}
+	if out != "a_amd64.s\n"+filepath.Join("sub", "b_amd64.s")+"\n" {
+		t.Errorf("listed files unexpected:\n%s", out)
+	}
+	for _, p := range []string{"a_amd64.s", filepath.Join("sub", "b_amd64.s")} {
+		b, _ := os.ReadFile(p)
+		if !strings.Contains(string(b), "\tRET") {
+			t.Errorf("%s not formatted in place:\n%s", p, b)
+		}
+	}
+	for _, p := range []string{filepath.Join("_refs", "c_amd64.s"), filepath.Join(".git", "d_amd64.s")} {
+		b, _ := os.ReadFile(p)
+		if string(b) != string(unformatted) {
+			t.Errorf("%s must not be touched:\n%s", p, b)
+		}
+	}
+
+	// Second pass: everything is canonical, nothing is listed.
+	out, _, code = capture(func() int { return cmdFmt(nil) })
+	if code != 0 || out != "" {
+		t.Errorf("second pass: code=%d out=%q, want a no-op", code, out)
+	}
+}
+
 func TestCmdTokens(t *testing.T) {
 	path := writeTemp(t, "f_amd64.s", clean)
 	out, _, code := capture(func() int { return cmdTokens([]string{path}) })
@@ -158,9 +206,10 @@ func TestUsage(t *testing.T) {
 }
 
 func TestCmdArgErrors(t *testing.T) {
-	// Missing file arguments produce a usage error (code 2).
+	// A missing path is an error (code 1); cmdFmt with no arguments is the
-	if _, _, code := capture(func() int { return cmdFmt(nil) }); code != 2 {
+	// recursive mode now, covered by TestCmdFmtRecursive.
-		t.Errorf("cmdFmt() code = %d, want 2", code)
+	if _, _, code := capture(func() int { return cmdFmt([]string{"no/such/path"}) }); code != 1 {
+		t.Errorf("cmdFmt(missing path) code = %d, want 1", code)
 	}
 	if _, _, code := capture(func() int { return cmdLint(nil) }); code != 2 {
 		t.Errorf("cmdLint() code = %d, want 2", code)

docs/ARCHITECTURE.md

@@ -136,13 +136,18 @@ Two deeper analyses sit on top of the AST:
   control-flow graph (basic blocks split at labels and after branches, with
   fall-through and jump-target edges), computes a conservative per-instruction
   register def/use, and runs the standard backward liveness iteration to a fixed
-  point.  On top of that it flags a **callee-saved register that is written but
+  point.  On top of that it flags writes to the registers the **Go ABI** fixes
-  never saved and restored** — the per-architecture callee-saved set is amd64
+  across calls that are never saved and restored — calibrated from
-  `BX/BP/R12–R15`, arm64 `R19–R30`, riscv64 `X1/X8/X9/X18–X27`, loong64
+  `cmd/compile/abi-internal.md`, *not* the platform ABI: Go's stack-based ABI0
-  `R1/R22–R31`.  This is an *audit*: the runtime's own assembly clobbers these
+  has no System V style callee-saved registers (amd64 `BX`, `R12`–`R15` and
-  registers freely (it controls both sides of the call), so the rule is
+  the like are caller-saved or permanent scratch, and hand-written kernels may
-  advisory there, but in hand-written kernels called from ordinary Go code a
+  clobber them freely).  The audited set is the frame pointer and the
-  clobber is a genuine ABI violation.  It runs only on macro-free files, where
+  goroutine pointer per architecture (amd64 `BP`/`R14`, arm64 `R18`/`R28`/
+  `R29`, riscv64 `X27`, loong64 `R22`); the goroutine pointer is reported only
+  when the function can reach the runtime — it is not `NOSPLIT` or makes a
+  call — since the ABI0 transition machinery restores it on those paths, and
+  NOSPLIT call-free leaves may use it (the runtime's own assembly does).  It
+  runs only on macro-free files, where
   no opaque macro can perform the save/restore.
 - **`funcdata-pcdata`.**  `FUNCDATA $idx, sym(SB)` and `PCDATA $idx, $val` are
   checked for well-formed operands (arity, immediate index and value, symbol
@@ -152,9 +157,15 @@ Two deeper analyses sit on top of the AST:
 ### `format`
 
 The formatter works on the **token stream, not the AST**, so it preserves
-every line — comments and blanks included.  It only normalises indentation,
+every line — comments and blanks included.  It normalises indentation, operand
-operand spacing and per-function mnemonic alignment.  It is idempotent and its
+spacing, per-function mnemonic alignment and blank-line layout: a new block
-output always round-trips through the parser.
+(a label, `TEXT` or `GLOBL`) is preceded by exactly one blank line (comments
+leading a block stay with it), runs of blanks collapse to one, and a `RET`
+terminates the body so the next function's doc comment stays at column 0.  It
+is idempotent and its output always round-trips through the parser.  With a
+directory argument — or none — it reformats every `.s` file below it in
+place and lists the files changed, the way `go fmt` does (`.` and `_`
+directories are skipped).
 
 ### `lsp`
 

format/format.go

@@ -27,14 +27,6 @@ func Source(path, src string) string {
 		mnemLen int
 		funcID  int
 	}
-	const (
-		kBlank = iota
-		kComment
-		kPreproc
-		kDirective
-		kLabel
-		kInstr
-	)
 
 	infos := make([]info, len(lines))
 	funcID := -1
@@ -70,8 +62,8 @@ func Source(path, src string) string {
 		infos[i] = inf
 	}
 
-	// Second pass: render.
+	// Second pass: render each line.
-	var b strings.Builder
+	outs := make([]outLine, 0, len(lines))
 	inBody := false
 	for i, line := range lines {
 		inf := infos[i]
@@ -99,11 +91,94 @@ func Source(path, src string) string {
 			}
 		case kInstr:
 			out = renderInstr(line, maxWidth[inf.funcID])
+			// A RET ends the body for indentation purposes: comments that
+			// follow it — typically the next function's doc comment — belong
+			// at column 0, not inside the finished function.
+			if strings.EqualFold(line[0].Text, "RET") {
+				inBody = false
+			}
 		}
-		b.WriteString(strings.TrimRight(out, " \t"))
+		outs = append(outs, outLine{kind: inf.kind, text: strings.TrimRight(out, " \t")})
-		b.WriteByte('\n')
 	}
-	return b.String()
+	return normalizeSpacing(outs)
+}
+
+// Line classification, shared by the formatting passes.
+const (
+	kBlank = iota
+	kComment
+	kPreproc
+	kDirective
+	kLabel
+	kInstr
+)
+
+// outLine is one rendered line together with its classification.
+type outLine struct {
+	kind int
+	text string
+}
+
+// normalizeSpacing enforces the canonical blank-line layout: runs of blank
+// lines collapse to one, and a new block — a label, or a TEXT or GLOBL
+// directive — is preceded by exactly one blank line.  Comments immediately
+// above a block belong to it, so the blank line is inserted before them.  No
+// blank line is forced at the top of the file, right after a TEXT (the
+// function's first label), or between stacked labels that share an address.
+func normalizeSpacing(outs []outLine) string {
+	blockStart := func(ol outLine) bool {
+		switch ol.kind {
+		case kLabel:
+			return true
+		case kDirective:
+			// TEXT and GLOBL open a block; DATA continues a GLOBL block.
+			return strings.HasPrefix(ol.text, "TEXT") || strings.HasPrefix(ol.text, "GLOBL")
+		}
+		return false
+	}
+	insert := make([]bool, len(outs))
+	for i, ol := range outs {
+		if !blockStart(ol) {
+			continue
+		}
+		j := i
+		for j > 0 && outs[j-1].kind == kComment {
+			j--
+		}
+		if j == 0 {
+			continue // top of file
+		}
+		switch prev := outs[j-1]; {
+		case prev.kind == kBlank, prev.kind == kLabel:
+			continue // already separated, or stacked labels
+		case prev.kind == kDirective && strings.HasPrefix(prev.text, "TEXT"):
+			continue // the function's first label
+		}
+		insert[j] = true
+	}
+
+	var b strings.Builder
+	prevBlank := true // also suppresses leading blanks
+	for i, ol := range outs {
+		if insert[i] && !prevBlank {
+			b.WriteByte('\n')
+		}
+		if ol.kind == kBlank {
+			if !prevBlank {
+				b.WriteByte('\n')
+			}
+			prevBlank = true
+			continue
+		}
+		b.WriteString(ol.text)
+		b.WriteByte('\n')
+		prevBlank = false
+	}
+	out := strings.TrimRight(b.String(), "\n")
+	if out == "" {
+		return ""
+	}
+	return out + "\n"
 }
 
 // renderInstr renders an instruction line: a tab, the mnemonic padded to the

format/format_test.go

@@ -39,6 +39,102 @@ func TestGolden(t *testing.T) {
 	}
 }
 
+// TestDocCommentIndent checks that a doc comment preceding a TEXT directive
+// sits at column 0 even when another function (ending in RET) precedes it —
+// the RET must terminate the previous body for indentation purposes.
+func TestDocCommentIndent(t *testing.T) {
+	in := "#include \"textflag.h\"\n" +
+		"\n" +
+		"// func first()\n" +
+		"TEXT ·first(SB), NOSPLIT, $0\n" +
+		"XORQ AX, AX\n" +
+		"RET\n" +
+		"\n" +
+		"// func second()\n" +
+		"TEXT ·second(SB), NOSPLIT, $0\n" +
+		"RET\n"
+
+	want := "#include \"textflag.h\"\n" +
+		"\n" +
+		"// func first()\n" +
+		"TEXT ·first(SB), NOSPLIT, $0\n" +
+		"\tXORQ AX, AX\n" +
+		"\tRET\n" +
+		"\n" +
+		"// func second()\n" +
+		"TEXT ·second(SB), NOSPLIT, $0\n" +
+		"\tRET\n"
+
+	got := Source("d_amd64.s", in)
+	if got != want {
+		t.Fatalf("formatting mismatch:\n--- got ---\n%q\n--- want ---\n%q", got, want)
+	}
+	// Body comments stay indented.
+	body := "#include \"textflag.h\"\nTEXT ·f(SB), NOSPLIT, $0\n// inside the body\nXORQ AX, AX\nRET\n"
+	gotBody := Source("b_amd64.s", body)
+	if !strings.Contains(gotBody, "\t// inside the body\n") {
+		t.Fatalf("body comment must stay indented:\n%q", gotBody)
+	}
+}
+
+// TestBlankLines checks the blank-line canonicalisation: exactly one blank
+// line before a new block (a label, or TEXT/GLOBL), runs of blanks collapsed
+// to one, and no blank forced after TEXT, between stacked labels, or at the
+// top of the file.  Leading comments belong to the block they precede.
+func TestBlankLines(t *testing.T) {
+	in := "#include \"textflag.h\"\n" +
+		"TEXT ·f(SB), NOSPLIT, $0\n" +
+		"first:\n" + // first label: no blank after TEXT
+		"XORQ AX, AX\n" +
+		"JMP next\n" + // unlabeled glue: fmt inserts a blank before next:
+		"next:\n" +
+		"stacked:\n" + // stacked labels share an address: no blank between
+		"INCQ AX\n" +
+		"\n" +
+		"\n" + // two blanks collapse to one
+		"// separated block\n" + // comment belongs to the label below
+		"later:\n" +
+		"RET\n" +
+		"// func g()\n" + // doc comment: blank goes before it
+		"TEXT ·g(SB), NOSPLIT, $0\n" +
+		"RET\n" +
+		"GLOBL ·mask(SB), RODATA, $8\n" + // blank before GLOBL…
+		"DATA ·mask+0(SB)/4, $1\n" + // …but not before DATA
+		"\n" +
+		"\n" +
+		"\n" // trailing blanks dropped
+
+	want := "#include \"textflag.h\"\n" +
+		"\n" +
+		"TEXT ·f(SB), NOSPLIT, $0\n" +
+		"first:\n" +
+		"\tXORQ AX, AX\n" +
+		"\tJMP  next\n" +
+		"\n" +
+		"next:\n" +
+		"stacked:\n" +
+		"\tINCQ AX\n" +
+		"\n" +
+		"\t// separated block\n" + // body comment before a label stays indented
+		"later:\n" +
+		"\tRET\n" +
+		"\n" +
+		"// func g()\n" +
+		"TEXT ·g(SB), NOSPLIT, $0\n" +
+		"\tRET\n" +
+		"\n" +
+		"GLOBL ·mask(SB), RODATA, $8\n" +
+		"DATA ·mask+0(SB)/4, $1\n"
+
+	got := Source("b_amd64.s", in)
+	if got != want {
+		t.Fatalf("formatting mismatch:\n--- got ---\n%q\n--- want ---\n%q", got, want)
+	}
+	if again := Source("b_amd64.s", got); again != got {
+		t.Fatalf("not idempotent:\n%q", again)
+	}
+}
+
 func TestOperandSpacing(t *testing.T) {
 	cases := map[string]string{
 		"4(SI)":           "4(SI)",

justfile

@@ -3,7 +3,7 @@
 
 # gasm-devkit — developer tooling for Go's Plan 9 assembler (GAsm).
 
-version := "0.5.0"
+version := "0.7.0"
 
 default:
     @just --list

lint/lint.go

@@ -319,18 +319,27 @@ func lintText(t *ast.Text, tab *arch.Table, archKnown bool, cfg Config, macros m
 		}
 	}
 
-	// Register liveness: a callee-saved register that is written but never
+	// Register liveness: a register the Go ABI fixes across calls that is
-	// saved and restored is clobbered across the call.  The check runs over the
+	// written but never saved and restored is clobbered.  The check runs over
-	// control-flow graph and is skipped for macro-using files, where an opaque
+	// the control-flow graph and is skipped for macro-using files, where an
-	// macro may perform the save/restore.
+	// opaque macro may perform the save/restore.
 	if doLabelChecks && archKnown && !cfg.Disable[CodeRegisterClobber] {
 		live := analyzeLiveness(t, cfg.Arch)
-		if clobbered := clobberedCalleeSaved(live, cfg.Arch); len(clobbered) > 0 {
+		always, rt := clobberedGoFixed(live, cfg.Arch, reachesRuntime(t))
+		if len(always) > 0 {
 			out = append(out, Diagnostic{
 				Pos:      t.Keyword.Pos,
 				Severity: Warning,
 				Code:     CodeRegisterClobber,
-				Message:  fmt.Sprintf("callee-saved register(s) %s written but never saved/restored", strings.Join(clobbered, ", ")),
+				Message:  fmt.Sprintf("register(s) %s written but never saved/restored: fixed by the Go ABI (frame/goroutine pointer)", strings.Join(always, ", ")),
+			})
+		}
+		if len(rt) > 0 {
+			out = append(out, Diagnostic{
+				Pos:      t.Keyword.Pos,
+				Severity: Warning,
+				Code:     CodeRegisterClobber,
+				Message:  fmt.Sprintf("goroutine-pointer register(s) %s written but never saved/restored in a function that can reach the Go runtime", strings.Join(rt, ", ")),
 			})
 		}
 	}
@@ -341,6 +350,29 @@ func lintText(t *ast.Text, tab *arch.Table, archKnown bool, cfg Config, macros m
 	return out
 }
 
+// reachesRuntime reports whether a function can reach the Go runtime: it is
+// not NOSPLIT (so the stack-split and traceback machinery runs) or it makes a
+// CALL.  Goroutine-pointer registers must survive such functions; a NOSPLIT
+// leaf may clobber them, since the ABI0 transition restores them (the
+// runtime's own assembly relies on this, e.g. R14 on amd64).
+func reachesRuntime(t *ast.Text) bool {
+	nosplit := false
+	for _, f := range t.Flags {
+		if strings.EqualFold(f, "NOSPLIT") {
+			nosplit = true
+		}
+	}
+	for _, s := range t.Body {
+		if in, ok := s.(*ast.Instr); ok {
+			switch strings.ToUpper(in.Mnemonic.Text) {
+			case "CALL", "BL", "JAL": // amd64, arm64/loong64, riscv64 calls
+				return true
+			}
+		}
+	}
+	return !nosplit
+}
+
 // usesFPArgs reports whether a function references its arguments through the FP
 // pseudo-register — i.e. it uses the stack-based ABI0 layout, where the
 // declared argument size must match the signature.

lint/lint_test.go

@@ -48,11 +48,11 @@ func TestFixtureIsClean(t *testing.T) {
 	if len(errs) > 0 {
 		t.Fatalf("parse: %v", errs)
 	}
-	// The fixture mirrors the go-flac kernels, which use callee-saved registers
+	// The fixture mirrors the go-flac kernels, which write the Go ABI0
-	// (BX, R13) without saving them; the register-clobber audit flags that by
+	// scratch registers (BX, R13) without saving them — legal under Go's
-	// design.  This test targets the other rules, so the audit is disabled here
+	// stack-based ABI, so the register-clobber audit stays silent and the
-	// (it is covered by TestRegisterClobber).
+	// fixture must lint entirely clean.
-	diags := File(f, Config{Arch: arch.AMD64, Disable: map[string]bool{CodeRegisterClobber: true}})
+	diags := File(f, Config{Arch: arch.AMD64})
 	if len(diags) != 0 {
 		t.Fatalf("expected no diagnostics on the fixture, got %+v", diags)
 	}

lint/liveness.go

@@ -4,7 +4,6 @@
 package lint
 
 import (
-	"fmt"
 	"sort"
 	"strings"
 
@@ -248,7 +247,7 @@ func instrEffect(in *ast.Instr, a arch.Arch) regEffect {
 	}
 
 	compare := isCompare(mnem)
-	dstIdx := dstIndex(in, a)
+	dstIdx := dstIndex(in)
 
 	for i, op := range in.Operands {
 		r := gprName(op, a)
@@ -281,13 +280,11 @@ func instrEffect(in *ast.Instr, a arch.Arch) regEffect {
 	return eff
 }
 
-// dstIndex returns the operand index of the destination register: last for the
+// dstIndex returns the operand index of the destination register: in Plan 9
-// Plan 9 (amd64) spelling, first for arm64/riscv64/loong64.
+// notation the destination is the last operand on every architecture Go
-func dstIndex(in *ast.Instr, a arch.Arch) int {
+// supports (amd64, arm64, riscv64 and loong64 alike).
-	if a == arch.AMD64 {
+func dstIndex(in *ast.Instr) int {
-		return len(in.Operands) - 1
+	return len(in.Operands) - 1
-	}
-	return 0
 }
 
 // isCompare reports whether the mnemonic only reads its operands (setting flags).
@@ -372,41 +369,37 @@ func sameSet(a, b map[string]bool) bool {
 	return true
 }
 
-// calleeSavedGPRs returns the general-purpose registers an assembly function
+// goFixedGPRs returns the general-purpose registers the Go ABI designates as
-// must preserve for its caller, using the register names the assembler accepts
+// fixed across calls — the ones hand-written assembly must not permanently
-// for each architecture.
+// clobber.  This follows cmd/compile/abi-internal.md, not the platform ABI:
-func calleeSavedGPRs(a arch.Arch) map[string]bool {
+// Go's stack-based ABI0 (which hand-written assembly uses) has no System V
+// style callee-saved registers, so clobbering the argument and scratch
+// registers (amd64 BX, R12, R13, R15, …) is legal.
+//
+// Two groups are returned.  always holds registers whose loss is never safe.
+// runtime holds registers that survive an ABI0 leaf only because the
+// transition machinery restores them (on amd64 the g pointer is reloaded
+// from TLS): clobbering them is safe exactly in NOSPLIT functions that make
+// no calls, which is how the runtime's own assembly uses them.
+func goFixedGPRs(a arch.Arch) (always, runtime map[string]bool) {
 	switch a {
 	case arch.AMD64:
-		return gprSet("BX", "BP", "R12", "R13", "R14", "R15")
+		// BP maintains the frame chain; R14 holds the current goroutine.
+		// R15 is scratch except in dynamically linked binaries, so it is not
+		// flagged.
+		return gprSet("BP"), gprSet("R14")
 	case arch.ARM64:
-		names := []string{"R29", "R30"} // FP, LR
+		// R18 is reserved for the OS on some platforms, R28 holds the current
-		for i := 19; i <= 28; i++ {
+		// goroutine, R29 is the frame pointer.
-			names = append(names, fmt.Sprintf("R%d", i))
+		return gprSet("R18", "R28", "R29"), nil
-		}
-		return gprSet(names...)
 	case arch.RISCV:
-		// RA (X1) and the S registers (X8, X9, X18–X27) are callee-saved.
+		// X27 holds the current goroutine.
-		names := []string{"X1", "RA", "X8", "X9", "S0", "S1", "FP"}
+		return gprSet("X27"), nil
-		for i := 18; i <= 27; i++ {
-			names = append(names, fmt.Sprintf("X%d", i))
-		}
-		for i := 2; i <= 11; i++ {
-			names = append(names, fmt.Sprintf("S%d", i))
-		}
-		return gprSet(names...)
 	case arch.LOONG64:
-		// RA (R1), FP (R22) and S0–S8 (R23–R31) are callee-saved.
+		// R22 holds the current goroutine.
-		names := []string{"R1", "RA", "R22", "FP"}
+		return gprSet("R22"), nil
-		for i := 23; i <= 31; i++ {
-			names = append(names, fmt.Sprintf("R%d", i))
-		}
-		for i := 0; i <= 8; i++ {
-			names = append(names, fmt.Sprintf("S%d", i))
-		}
-		return gprSet(names...)
 	}
-	return nil
+	return nil, nil
 }
 
 func gprSet(names ...string) map[string]bool {
@@ -417,15 +410,16 @@ func gprSet(names ...string) map[string]bool {
 	return m
 }
 
-// clobberedCalleeSaved returns the callee-saved registers a function writes
+// clobberedGoFixed returns the Go-ABI-fixed registers a function writes
-// without also saving and restoring them — i.e. registers whose caller-owned
+// without also saving and restoring them.  The first result lists registers
-// value is lost across the call.  It walks the blocks of the liveness analysis
+// whose loss is never safe; the second lists the goroutine-pointer class,
-// (so the control-flow graph is what supplies the instruction set) and
+// whose loss is reported only when reachesRuntime is true (a non-NOSPLIT
-// aggregates each instruction's register effects.
+// function, or one that makes calls — the ABI0 transition machinery restores
-func clobberedCalleeSaved(l *liveness, a arch.Arch) []string {
+// the g pointer only on such paths).
-	callee := calleeSavedGPRs(a)
+func clobberedGoFixed(l *liveness, a arch.Arch, reachesRuntime bool) (always, runtime []string) {
-	if len(callee) == 0 {
+	alwaysSet, runtimeSet := goFixedGPRs(a)
-		return nil
+	if len(alwaysSet) == 0 && len(runtimeSet) == 0 {
+		return nil, nil
 	}
 	def := map[string]bool{}
 	saved := map[string]bool{}
@@ -444,12 +438,19 @@ func clobberedCalleeSaved(l *liveness, a arch.Arch) []string {
 			}
 		}
 	}
-	var out []string
+	clobbered := func(set map[string]bool) []string {
-	for r := range callee {
+		var out []string
-		if def[r] && !(saved[r] && restored[r]) {
+		for r := range set {
-			out = append(out, r)
+			if def[r] && !(saved[r] && restored[r]) {
+				out = append(out, r)
+			}
 		}
+		sort.Strings(out)
+		return out
 	}
-	sort.Strings(out)
+	always = clobbered(alwaysSet)
-	return out
+	if reachesRuntime {
+		runtime = clobbered(runtimeSet)
+	}
+	return always, runtime
 }

lint/liveness_test.go

@@ -5,36 +5,132 @@ package lint
 
 import "testing"
 
-// TestRegisterClobber detects writes to callee-saved registers that are not
+// TestRegisterClobber checks the register-clobber audit is calibrated to the
-// saved and restored.
+// Go ABI (cmd/compile/abi-internal.md), not the platform ABI: Go's
+// stack-based ABI0 — which hand-written assembly uses — has no System V
+// style callee-saved registers, so argument and scratch registers may be
+// clobbered freely.  Only the registers the ABI fixes across calls (the
+// frame pointer, the goroutine pointer, OS-reserved registers) are audited.
 func TestRegisterClobber(t *testing.T) {
-	// BX (callee-saved on amd64) is written but never saved → clobbered.
+	// amd64: BX, R12, R13 and R15 are argument/permanent-scratch registers in
-	clob := lintSrc(t, "#include \"textflag.h\"\n"+
+	// Go ABI0 — writing them unsaved is legal (a System V calibration would
+	// report all of these).
+	scratch := lintSrc(t, "#include \"textflag.h\"\n"+
 		"TEXT ·f(SB), NOSPLIT, $0\n"+
 		"\tMOVQ CX, BX\n"+
+		"\tXORL R12, R12\n"+
+		"\tXORL R13, R13\n"+
+		"\tXORL R15, R15\n"+
 		"\tRET\n")
-	if codes(clob)[CodeRegisterClobber] != 1 {
+	if codes(scratch)[CodeRegisterClobber] != 0 {
-		t.Fatalf("unsaved callee-saved write should be flagged: %+v", clob)
+		t.Fatalf("Go ABI0 scratch registers must not be flagged: %+v", scratch)
 	}
 
-	// Saved and restored → preserved.
+	// amd64: R14 (the goroutine pointer) in a NOSPLIT function without calls
+	// is the runtime's own pattern — the ABI0 transition restores it — so it
+	// is not flagged.
+	leaf := lintSrc(t, "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), NOSPLIT, $0\n"+
+		"\tXORL R14, R14\n"+
+		"\tRET\n")
+	if codes(leaf)[CodeRegisterClobber] != 0 {
+		t.Fatalf("R14 in a NOSPLIT leaf must not be flagged: %+v", leaf)
+	}
+
+	// amd64: R14 in a function that makes a call is a genuine hazard.
+	withCall := lintSrc(t, "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), NOSPLIT, $0\n"+
+		"\tXORL R14, R14\n"+
+		"\tCALL ·g(SB)\n"+
+		"\tRET\n")
+	if codes(withCall)[CodeRegisterClobber] != 1 {
+		t.Fatalf("unsaved R14 with a call should be flagged: %+v", withCall)
+	}
+
+	// amd64: R14 in a non-NOSPLIT function is a hazard regardless of calls.
+	split := lintSrc(t, "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), $0\n"+
+		"\tMOVQ CX, R14\n"+
+		"\tRET\n")
+	if codes(split)[CodeRegisterClobber] != 1 {
+		t.Fatalf("unsaved R14 in a non-NOSPLIT function should be flagged: %+v", split)
+	}
+
+	// amd64: R14 saved and restored around the call is preserved.
 	saved := lintSrc(t, "#include \"textflag.h\"\n"+
 		"TEXT ·f(SB), NOSPLIT, $8\n"+
-		"\tPUSHQ BX\n"+
+		"\tPUSHQ R14\n"+
-		"\tMOVQ CX, BX\n"+
+		"\tXORL R14, R14\n"+
-		"\tPOPQ BX\n"+
+		"\tCALL ·g(SB)\n"+
+		"\tPOPQ R14\n"+
 		"\tRET\n")
 	if codes(saved)[CodeRegisterClobber] != 0 {
-		t.Fatalf("saved/restored register must not be flagged: %+v", saved)
+		t.Fatalf("saved/restored R14 must not be flagged: %+v", saved)
 	}
 
-	// A caller-saved register (CX) is fine to write.
+	// amd64: BP maintains the frame chain and is always audited.
-	caller := lintSrc(t, "#include \"textflag.h\"\n"+
+	bp := lintSrc(t, "#include \"textflag.h\"\n"+
 		"TEXT ·f(SB), NOSPLIT, $0\n"+
-		"\tMOVQ $1, CX\n"+
+		"\tMOVQ CX, BP\n"+
 		"\tRET\n")
-	if codes(caller)[CodeRegisterClobber] != 0 {
+	if codes(bp)[CodeRegisterClobber] != 1 {
-		t.Fatalf("caller-saved register must not be flagged: %+v", caller)
+		t.Fatalf("unsaved BP write should be flagged: %+v", bp)
+	}
+
+	// arm64: R20 is scratch; R28 (goroutine pointer) and R18 (OS-reserved)
+	// are fixed by the Go ABI.
+	armScratch := lintSrcArch(t, "t_arm64.s", "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), NOSPLIT, $0\n"+
+		"\tMOVD R0, R20\n"+
+		"\tRET\n")
+	if codes(armScratch)[CodeRegisterClobber] != 0 {
+		t.Fatalf("arm64 scratch register must not be flagged: %+v", armScratch)
+	}
+	armG := lintSrcArch(t, "t_arm64.s", "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), NOSPLIT, $0\n"+
+		"\tMOVD R0, R28\n"+
+		"\tRET\n")
+	if codes(armG)[CodeRegisterClobber] != 1 {
+		t.Fatalf("unsaved arm64 R28 write should be flagged: %+v", armG)
+	}
+	armReserved := lintSrcArch(t, "t_arm64.s", "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), NOSPLIT, $0\n"+
+		"\tMOVD R0, R18\n"+
+		"\tRET\n")
+	if codes(armReserved)[CodeRegisterClobber] != 1 {
+		t.Fatalf("arm64 R18 write should be flagged: %+v", armReserved)
+	}
+
+	// riscv64: X27 holds the goroutine; X5–X7 are scratch.
+	riscScratch := lintSrcArch(t, "t_riscv64.s", "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), NOSPLIT, $0\n"+
+		"\tMOV X5, X6\n"+
+		"\tRET\n")
+	if codes(riscScratch)[CodeRegisterClobber] != 0 {
+		t.Fatalf("riscv64 scratch register must not be flagged: %+v", riscScratch)
+	}
+	riscG := lintSrcArch(t, "t_riscv64.s", "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), NOSPLIT, $0\n"+
+		"\tMOV X5, X27\n"+
+		"\tRET\n")
+	if codes(riscG)[CodeRegisterClobber] != 1 {
+		t.Fatalf("unsaved riscv64 X27 write should be flagged: %+v", riscG)
+	}
+
+	// loong64: R22 holds the goroutine; R5–R19 are argument/scratch.
+	loongScratch := lintSrcArch(t, "t_loong64.s", "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), NOSPLIT, $0\n"+
+		"\tMOVV R5, R6\n"+
+		"\tRET\n")
+	if codes(loongScratch)[CodeRegisterClobber] != 0 {
+		t.Fatalf("loong64 scratch register must not be flagged: %+v", loongScratch)
+	}
+	loongG := lintSrcArch(t, "t_loong64.s", "#include \"textflag.h\"\n"+
+		"TEXT ·f(SB), NOSPLIT, $0\n"+
+		"\tMOVV R5, R22\n"+
+		"\tRET\n")
+	if codes(loongG)[CodeRegisterClobber] != 1 {
+		t.Fatalf("unsaved loong64 R22 write should be flagged: %+v", loongG)
 	}
 }