Generate x86 Assembly with Go

avo makes high-performance Go assembly easier to write, review and maintain. The avo package presents a familiar assembly-like interface that simplifies development without sacrificing performance:

• Use Go control structures for assembly generation; avo programs are Go programs
• Register allocation: write functions with virtual registers and avo assigns physical registers for you
• Automatically load arguments and store return values: ensure memory offsets are correct for complex structures
• Generation of stub files to interface with your Go package

Note: APIs subject to change while avo is still in an experimental phase. You can use it to build real things but we suggest you pin a version with your package manager of choice.

Quick Start

Install avo with go get:

$ go get -u github.com/mmcloughlin/avo

avo assembly generators are pure Go programs. Here's a function that adds two uint64 values:

// +build ignore

package main

import (
	. "github.com/mmcloughlin/avo/build"
)

func main() {
	TEXT("Add", NOSPLIT, "func(x, y uint64) uint64")
	Doc("Add adds x and y.")
	x := Load(Param("x"), GP64())
	y := Load(Param("y"), GP64())
	ADDQ(x, y)
	Store(y, ReturnIndex(0))
	RET()
	Generate()
}

go run this code to see the assembly output. To integrate this into the rest of your Go package we recommend a go:generate line to produce the assembly and the corresponding Go stub file.

//go:generate go run asm.go -out add.s -stubs stub.go

After running go generate the add.s file will contain the Go assembly.

// Code generated by command: go run asm.go -out add.s -stubs stub.go. DO NOT EDIT.

#include "textflag.h"

// func Add(x uint64, y uint64) uint64
TEXT ·Add(SB), NOSPLIT, $0-24
	MOVQ	x(FP), AX
	MOVQ	y+8(FP), CX
	ADDQ	AX, CX
	MOVQ	CX, ret+16(FP)
	RET

The same call will produce the stub file stub.go which will enable the function to be called from your Go code.

// Code generated by command: go run asm.go -out add.s -stubs stub.go. DO NOT EDIT.

package add

// Add adds x and y.
func Add(x uint64, y uint64) uint64

See the examples/add directory for the complete working example.

Examples

See examples for the full suite of examples.

Slice Sum

Sum a slice of uint64s:

func main() {
	TEXT("Sum", NOSPLIT, "func(xs []uint64) uint64")
	Doc("Sum returns the sum of the elements in xs.")
	ptr := Load(Param("xs").Base(), GP64())
	n := Load(Param("xs").Len(), GP64())

	// Initialize sum register to zero.
	s := GP64()
	XORQ(s, s)

	// Loop until zero bytes remain.
	Label("loop")
	CMPQ(n, Imm(0))
	JE(LabelRef("done"))

	// Load from pointer and add to running sum.
	ADDQ(Mem{Base: ptr}, s)

	// Advance pointer, decrement byte count.
	ADDQ(Imm(8), ptr)
	DECQ(n)
	JMP(LabelRef("loop"))

	// Store sum to return value.
	Label("done")
	Store(s, ReturnIndex(0))
	RET()
	Generate()
}

The result from this code generator is:

// Code generated by command: go run asm.go -out sum.s -stubs stub.go. DO NOT EDIT.

#include "textflag.h"

// func Sum(xs []uint64) uint64
TEXT ·Sum(SB), NOSPLIT, $0-32
	MOVQ	xs_base(FP), AX
	MOVQ	xs_len+8(FP), CX
	XORQ	DX, DX
loop:
	CMPQ	CX, $0x00
	JE	done
	ADDQ	(AX), DX
	ADDQ	$0x08, AX
	DECQ	CX
	JMP	loop
done:
	MOVQ	DX, ret+24(FP)
	RET

Full example at examples/sum.

Features

For demonstrations of avo features:

• args: Loading function arguments.
• returns: Building return values.
• data: Defining DATA sections.
• complex: Working with complex{64,128} types.

Real Examples

Implementations of full algorithms:

• sha1: SHA-1 cryptographic hash.
• fnv1a: FNV-1a hash function.
• dot: Vector dot product.
• geohash: Integer geohash encoding.
• stadtx: StadtX hash port from dgryski/go-stadtx.

Contributing

Contributions to avo are welcome:

• Feedback from using avo in a real project is incredibly valuable.
• Submit bug reports to the issues page.
• Pull requests accepted. Take a look at outstanding issues for ideas (especially the "good first issue" label).

Credits

Inspired by the PeachPy and asmjit projects.

License

avo is available under the BSD 3-Clause License.