Skip to content
Generate x86 Assembly with Go
Go Assembly Shell
Branch: master
Clone or download
zchee and mmcloughlin attr,build: add TOPFRAME attribute (#98)
Go added the TOPFRAME attribute in https://golang.org/cl/169726/. This diff adds the new attribute to avo, and also updates handling of the REFLECTMETHOD attribute.
Latest commit 15d6a9a Sep 26, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
attr attr,build: add TOPFRAME attribute (#98) Sep 27, 2019
build attr,build: add TOPFRAME attribute (#98) Sep 27, 2019
buildtags buildtags: doc exported symbols (#9) Jan 5, 2019
examples ir,build: pragma support (#97) Sep 16, 2019
gotypes lint: stop using deprecated go/packages api (#87) Jun 13, 2019
internal all: formatting (#93) Jul 31, 2019
ir ir,build: pragma support (#97) Sep 16, 2019
operand all: apply gofumpt (#79) Apr 14, 2019
pass pass: remove redundant jumps and dangling labels (#81) Apr 16, 2019
printer ir,build: pragma support (#97) Sep 16, 2019
reg reg: rename Bytes() to Size() (#74) Apr 2, 2019
script ci: fix build for go 1.13 (#96) Sep 15, 2019
src src: package level doc (#9) Jan 5, 2019
tests
x86 all: formatting (#93) Jul 31, 2019
.gitignore testing: coverage script Jan 3, 2019
.golangci.yml ci: fix build for go 1.13 (#96) Sep 15, 2019
.travis.yml ci: flag integration tests and unit tests Jan 10, 2019
LICENSE Initial commit Nov 4, 2018
README.md ir,build: pragma support (#97) Sep 16, 2019
doc.go doc: add package-level doc comments (#9) Jan 6, 2019
go.mod ci: fix build for go 1.13 (#96) Sep 15, 2019
go.sum ci: fix build for go 1.13 (#96) Sep 15, 2019
logo.svg meta: add logo Jan 3, 2019

README.md

avo
Build Status GoDoc Go Report Card

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

For a full introduction to avo watch the dotGo 2019 talk Better x86 Assembly Generation with Go (slides).

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+0(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())

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

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

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

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

	Label("done")
	Comment("Store sum to return value.")
	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+0(FP), AX
	MOVQ xs_len+8(FP), CX

	// Initialize sum register to zero.
	XORQ DX, DX

loop:
	// Loop until zero bytes remain.
	CMPQ CX, $0x00
	JE   done

	// Load from pointer and add to running sum.
	ADDQ (AX), DX

	// Advance pointer, decrement byte count.
	ADDQ $0x08, AX
	DECQ CX
	JMP  loop

done:
	// Store sum to return value.
	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.
  • complex: Working with complex{64,128} types.
  • data: Defining DATA sections.
  • ext: Interacting with types from external packages.
  • pragma: Apply compiler directives to generated functions.

Real Examples

Implementations of full algorithms:

Contributing

Contributions to avo are welcome:

Credits

Inspired by the PeachPy and asmjit projects. Thanks to Damian Gryski for advice, and his extensive library of PeachPy Go projects.

License

avo is available under the BSD 3-Clause License.

You can’t perform that action at this time.