Avo

<p align="center"> <img src="logo.svg" width="40%" border="0" alt="avo" /> <br /> <img src="https://img.shields.io/github/actions/workflow/status/mmcloughlin/avo/ci.yml?style=flat-square" alt="Build Status" /> <a href="https://pkg.go.dev/github.com/mmcloughlin/avo"><img src="https://img.shields.io/badge/doc-reference-007d9b?logo=go&style=flat-square" alt="go.dev" /></a> <a href="https://goreportcard.com/report/github.com/mmcloughlin/avo"><img src="https://goreportcard.com/badge/github.com/mmcloughlin/avo?style=flat-square" alt="Go Report Card" /></a> </p> <p align="center">Generate x86 Assembly with Go</p>

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 more about avo:

• Introductory talk "Better x86 Assembly Generation with Go" at dotGo 2019 (slides)
• Longer tutorial at Gophercon 2019 showing a highly-optimized dot product (slides)
• Watch Filippo Valsorda live code the rewrite of filippo.io/edwards25519 assembly with avo
• Explore projects using avo
• Discuss avo and general Go assembly topics in the #assembly channel of Gophers Slack

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:

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

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

Adopters

Popular projects[^projects] using avo:

[^projects]: Projects drawn from the avo third-party test suite. Popularity estimated from Github star count collected on Mar 1, 2026.

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fgolang.png&w=24" width="24" height="24" hspace="4" valign="middle" /> golang / go :star: 132.8k

The Go programming language

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fklauspost.png&w=24" width="24" height="24" hspace="4" valign="middle" /> klauspost / compress :star: 5.4k

Optimized Go Compression Packages

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fgolang.png&w=24" width="24" height="24" hspace="4" valign="middle" /> golang / crypto :star: 3.3k

[mirror] Go supplementary cryptography libraries

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fklauspost.png&w=24" width="24" height="24" hspace="4" valign="middle" /> klauspost / reedsolomon :star: 2k

Reed-Solomon Erasure Coding in Go

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fbytedance.png&w=24" width="24" height="24" hspace="4" valign="middle" /> bytedance / gopkg :star: 2k

Universal Utilities for Go

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fcloudflare.png&w=24" width="24" height="24" hspace="4" valign="middle" /> cloudflare / circl :star: 1.6k

CIRCL: Cloudflare Interoperable Reusable Cryptographic Library

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fsegmentio.png&w=24" width="24" height="24" hspace="4" valign="middle" /> segmentio / asm :star: 911

Go library providing algorithms optimized to leverage the characteristics of modern CPUs

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fzeebo.png&w=24" width="24" height="24" hspace="4" valign="middle" /> zeebo / xxh3 :star: 538

XXH3 algorithm in Go

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Fzeebo.png&w=24" width="24" height="24" hspace="4" valign="middle" /> zeebo / blake3 :star: 463

Pure Go implementation of BLAKE3 with AVX2 and SSE4.1 acceleration

<img src="https://images.weserv.nl?fit=cover&h=24&mask=circle&maxage=7d&url=https%3A%2F%2Fgithub.com%2Flukechampine.png&w=24" width="24" height="24" hspace="4" valign="middle" /> lukechampine / blake3 :star: 411

An AVX-512 accelerated implementation of the BLAKE3 cryptographic hash function

See the full list of projects using avo.

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](https://github.com/m