avo/README.md

High-level Golang x86 Assembly Generator

avo aims to make high-performance Go assembly easier to write, review and maintain. It's a Go package that presents a familiar assembly-like interface, together with features to simplify development without sacrificing performance:

• avo programs are Go programs: use control structures for assembly generation
• Register allocation: write your kernels with virtual registers and avo assigns physical registers for you
• Automatic parameter load/stores: ensure memory offsets are always correct even for complex data structures
• Generation of stub files to interface with your Go package

Inspired by the PeachPy and asmjit projects.

Note: avo is still in an experimental phase. APIs subject to change.

Install

Install avo with go get:

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

Quick Start

avo assembly generators are pure Go programs. Let's get started with a function that adds two uint64 values.

// +build ignore

package main

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

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

You can 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.

// func Add(x uint64, y uint64) uint64
TEXT ·Add(SB), $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.

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).

License

avo is available under the BSD 3-Clause License.