Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mmcloughlin/avo

Generate x86 Assembly with Go
https://github.com/mmcloughlin/avo

assembly code-generation go golang x86-64

Last synced: 20 days ago
JSON representation

Generate x86 Assembly with Go

Lists

README 

        


  avo

  


  Build Status

  go.dev

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



* Introductory talk ["Better `x86` Assembly Generation with Go"](https://www.youtube.com/watch?v=6Y5CZ7_tyA4) at [dotGo 2019](https://2019.dotgo.eu/) ([slides](https://speakerdeck.com/mmcloughlin/better-x86-assembly-generation-with-go))

* [Longer tutorial at Gophercon 2019](https://www.youtube.com/watch?v=WaD8sNqroAw) showing a highly-optimized dot product ([slides](https://speakerdeck.com/mmcloughlin/better-x86-assembly-generation-with-go-gophercon-2019))

* Watch [Filippo Valsorda](https://filippo.io/) live code the [rewrite of `filippo.io/edwards25519` assembly with `avo`](https://vimeo.com/679848853)

* Explore [projects using `avo`](doc/adopters.md)

* Discuss `avo` and general Go assembly topics in the [#assembly](https://gophers.slack.com/archives/C6WDZJ70S) channel of [Gophers Slack](https://invite.slack.golangbridge.org/)



_Note: APIs subject to change while `avo` is still in an experimental phase. You can use it to build [real things](examples) 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

//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`](https://blog.golang.org/generate) line to produce the assembly and the corresponding Go stub file.



```go

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

```



After running `go generate` the [`add.s`](examples/add/add.s) file will contain the Go assembly.



```s

// 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`](examples/add/stub.go) which will enable the function to be called from your Go code.



```go

// 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`](examples/add) directory for the complete working example.



## Examples



See [`examples`](examples) for the full suite of examples.



### Slice Sum



Sum a slice of `uint64`s:



```go

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:



```s

// 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`](examples/sum).



### Features



For demonstrations of `avo` features:



* **[args](examples/args):** Loading function arguments.

* **[returns](examples/returns):** Building return values.

* **[complex](examples/complex):** Working with `complex{64,128}` types.

* **[data](examples/data):** Defining `DATA` sections.

* **[ext](examples/ext):** Interacting with types from external packages.

* **[pragma](examples/pragma):** Apply compiler directives to generated functions.



### Real Examples



Implementations of full algorithms:



* **[sha1](examples/sha1):** [SHA-1](https://en.wikipedia.org/wiki/SHA-1) cryptographic hash.

* **[fnv1a](examples/fnv1a):** [FNV-1a](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV-1a_hash) hash function.

* **[dot](examples/dot):** Vector dot product.

* **[md5x16](examples/md5x16):** AVX-512 accelerated [MD5](https://en.wikipedia.org/wiki/MD5).

* **[geohash](examples/geohash):** Integer [geohash](https://en.wikipedia.org/wiki/Geohash) encoding.

* **[stadtx](examples/stadtx):** [`StadtX` hash](https://github.com/demerphq/BeagleHash) port from [dgryski/go-stadtx](https://github.com/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 May 1, 2024.



 [golang / **go**](https://github.com/golang/go)

:star: 119.7k

> The Go programming language



 [klauspost / **compress**](https://github.com/klauspost/compress)

:star: 4.5k

> Optimized Go Compression Packages



 [golang / **crypto**](https://github.com/golang/crypto)

:star: 2.9k

> [mirror] Go supplementary cryptography libraries



 [klauspost / **reedsolomon**](https://github.com/klauspost/reedsolomon)

:star: 1.8k

> Reed-Solomon Erasure Coding in Go



 [bytedance / **gopkg**](https://github.com/bytedance/gopkg)

:star: 1.6k

> Universal Utilities for Go



 [cloudflare / **circl**](https://github.com/cloudflare/circl)

:star: 1.2k

> CIRCL: Cloudflare Interoperable Reusable Cryptographic Library



 [segmentio / **asm**](https://github.com/segmentio/asm)

:star: 850

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



 [zeebo / **xxh3**](https://github.com/zeebo/xxh3)

:star: 382

> XXH3 algorithm in Go



 [zeebo / **blake3**](https://github.com/zeebo/blake3)

:star: 368

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



 [lukechampine / **blake3**](https://github.com/lukechampine/blake3)

:star: 332

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



See the [full list of projects using `avo`](doc/adopters.md).



## Contributing



Contributions to `avo` are welcome:



* Feedback from using `avo` in a real project is incredibly valuable. Consider [porting an existing project to `avo`](https://github.com/mmcloughlin/avo/issues/40).

* [Submit bug reports](https://github.com/mmcloughlin/avo/issues/new) to the issues page.

* Pull requests accepted. Take a look at outstanding [issues](https://github.com/mmcloughlin/avo/issues) for ideas (especially the ["good first issue"](https://github.com/mmcloughlin/avo/labels/good%20first%20issue) label).

* Join us in the [#assembly](https://gophers.slack.com/archives/C6WDZJ70S) channel of [Gophers Slack](https://invite.slack.golangbridge.org/).



## Credits



Inspired by the [PeachPy](https://github.com/Maratyszcza/PeachPy) and [asmjit](https://github.com/asmjit/asmjit) projects. Thanks to [Damian Gryski](https://github.com/dgryski) for advice, and his [extensive library of PeachPy Go projects](https://github.com/mmcloughlin/avo/issues/40).



## License



`avo` is available under the [BSD 3-Clause License](LICENSE).