ir,build: pragma support (#97)

Adds support for arbitrary compiler directives.

Fixes #15

examples/pragma/README.md

@@ -0,0 +1,33 @@
+# pragma
+
+Apply [compiler directives](https://golang.org/pkg/cmd/compile/#hdr-Compiler_Directives) to `avo` functions.
+
+The [code generator](asm.go) uses the `Pragma` function to apply the `//go:noescape` directive to the `Add` function:
+
+[embedmd]:# (asm.go go /func main/ /^}/)
+```go
+func main() {
+	TEXT("Add", NOSPLIT, "func(z, x, y *uint64)")
+	Pragma("noescape")
+	Doc("Add adds the values at x and y and writes the result to z.")
+	zptr := Mem{Base: Load(Param("z"), GP64())}
+	xptr := Mem{Base: Load(Param("x"), GP64())}
+	yptr := Mem{Base: Load(Param("y"), GP64())}
+	x, y := GP64(), GP64()
+	MOVQ(xptr, x)
+	MOVQ(yptr, y)
+	ADDQ(x, y)
+	MOVQ(y, zptr)
+	RET()
+	Generate()
+}
+```
+
+Note the directive is applied in the generated stub file:
+
+[embedmd]:# (stub.go go /\/\/ Add/ /func/)
+```go
+// Add adds the values at x and y and writes the result to z.
+//go:noescape
+func
+```

examples/pragma/asm.go

@@ -0,0 +1,24 @@
+// +build ignore
+
+package main
+
+import (
+	. "github.com/mmcloughlin/avo/build"
+	. "github.com/mmcloughlin/avo/operand"
+)
+
+func main() {
+	TEXT("Add", NOSPLIT, "func(z, x, y *uint64)")
+	Pragma("noescape")
+	Doc("Add adds the values at x and y and writes the result to z.")
+	zptr := Mem{Base: Load(Param("z"), GP64())}
+	xptr := Mem{Base: Load(Param("x"), GP64())}
+	yptr := Mem{Base: Load(Param("y"), GP64())}
+	x, y := GP64(), GP64()
+	MOVQ(xptr, x)
+	MOVQ(yptr, y)
+	ADDQ(x, y)
+	MOVQ(y, zptr)
+	RET()
+	Generate()
+}

examples/pragma/doc.go

@@ -0,0 +1,2 @@
+// Package pragma demonstrates the use of compiler directives.
+package pragma

examples/pragma/pragma.s

@@ -0,0 +1,14 @@
+// Code generated by command: go run asm.go -out pragma.s -stubs stub.go. DO NOT EDIT.
+
+#include "textflag.h"
+
+// func Add(z *uint64, x *uint64, y *uint64)
+TEXT ·Add(SB), NOSPLIT, $0-24
+	MOVQ z+0(FP), AX
+	MOVQ x+8(FP), CX
+	MOVQ y+16(FP), DX
+	MOVQ (CX), CX
+	MOVQ (DX), DX
+	ADDQ CX, DX
+	MOVQ DX, (AX)
+	RET

examples/pragma/pragma_test.go

@@ -0,0 +1,16 @@
+package pragma
+
+import (
+	"testing"
+	"testing/quick"
+)
+
+//go:generate go run asm.go -out pragma.s -stubs stub.go
+
+func TestAdd(t *testing.T) {
+	got := func(x, y uint64) (z uint64) { Add(&z, &x, &y); return }
+	expect := func(x, y uint64) uint64 { return x + y }
+	if err := quick.CheckEqual(got, expect, nil); err != nil {
+		t.Fatal(err)
+	}
+}

examples/pragma/stub.go

@@ -0,0 +1,7 @@
+// Code generated by command: go run asm.go -out pragma.s -stubs stub.go. DO NOT EDIT.
+
+package pragma
+
+// Add adds the values at x and y and writes the result to z.
+//go:noescape
+func Add(z *uint64, x *uint64, y *uint64)