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](https://github.com/Maratyszcza/PeachPy) and [asmjit](https://github.com/asmjit/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. [embedmd]:# (examples/add/asm.go) ```go // +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`](https://blog.golang.org/generate) line to produce the assembly and the corresponding Go stub file. [embedmd]:# (examples/add/add_test.go go /.*go:generate.*/) ```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. [embedmd]:# (examples/add/add.s) ```s // 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`](examples/add/stub.go) which will enable the function to be called from your Go code. [embedmd]:# (examples/add/stub.go) ```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. ## Contributing Contributions to `avo` are welcome: * Feedback from using `avo` in a real project is incredibly valuable. * [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). ## License `avo` is available under the [BSD 3-Clause License](LICENSE).