Generate x86 Assembly with Go

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

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

Quick Start

install avo with go get:

$ go get -u sources.truenas.cloud/code/avo

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

//go:build ignore

package main

import . "sources.truenas.cloud/code/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] (https://blog.golang.org/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 stubs.go. DO NOT EDIT

#include "text.flag.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 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 for this code generator is:

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

#include "text.flag.h"

// func Sum(xs []uint64) uint64

TEXT ·Sum(SB), NOSPLIT, $0-32
    MOVQ xs_base+0(FP), AX
    MOVQ xs_len+8(FP), CX

    // Intitialize 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:

• sha1: SHA-1 cryptographic hash.
• fnv1a: FNV-1a hash function.
• dot: Vector dot product.
• md5x16: AVX-512 accelerated MD5.
• 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. Consider porting an existing project to avo.
• 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. Thanks to Damian Gryski for advice, and his extensive library of PeachPy Go projects.

License

avo is available under the BSD 3-Clause License.