93 lines
2.7 KiB
Markdown
93 lines
2.7 KiB
Markdown
<p align="center">
|
|
<img src="logo.svg" width="40%" border="0" alt="avo" />
|
|
<br />
|
|
<a href="https://app.shippable.com/github/mmcloughlin/avo/dashboard"><img src="https://api.shippable.com/projects/5bf9e8f059e32e0700ec360f/badge?branch=master" alt="Build Status" /></a>
|
|
<a href="http://godoc.org/github.com/mmcloughlin/avo"><img src="http://img.shields.io/badge/godoc-reference-5272B4.svg" alt="GoDoc" /></a>
|
|
</p>
|
|
|
|
High-level Golang x86 assembly generator. Inspired by [PeachPy](https://github.com/Maratyszcza/PeachPy).
|
|
|
|
_Warning: `avo` is experimental. APIs are 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).
|