diff --git a/AssemblyPolicy.md b/AssemblyPolicy.md index a37e9425..1e7e7004 100644 --- a/AssemblyPolicy.md +++ b/AssemblyPolicy.md @@ -1,19 +1,12 @@ # Assembly Policy -This document describes when and how to add assembly code to routines in the Go-maintained packages. This document is a work in progress. +This document describes when and how to add assembly code to the Go cryptography packages. In general, the rules are: * We prefer portable Go, not assembly. Code in assembly means (N packages * M architectures) to maintain, rather than just N packages. - * Minimize use of assembly. We'd rather have a small amount of assembly for a 50% speedup rather than twice as much assembly for a 55% speedup. Explain the decision to place the assembly/Go boundary where it is in the commit message, and support it with benchmarks. - -* Explain the root causes in code comments or commit messages. What changes in the compiler and standard library would allow you to replace this assembly with Go? (New intrinsics, SSA pattern matching, other optimizations.) - -* Make your assembly easy to review; ideally, auto-generate it using a simpler Go program. Comment it well. - -* Test it well. The bar for new assembly code is high; it needs commensurate test coverage. Existing high-level tests for Go implementations are often inadequate for hundreds of lines of assembly. Test subroutines individually. Fuzz the assembly implementation against the Go implementation. - -## Future directions - -* If possible, port existing reviewed implementations. A tool should make it easy to review diffs from decompiler output. Consider the license implications. +* Use higher level programs to generate non-trivial amounts of assembly, either standalone Go programs or `go get`-able programs, like [avo](https://github.com/mmcloughlin/avo). Output of other reproducible processes (like formally verified code generators) will also be considered. Discuss the implementation strategy on the issue tracker in advance. +* Use small, testable units (25–75 lines) called from higher-level logic written in Go. If using small, testable functions called from logic written in Go is too slow, use small, testable assembly units with Go-compatible wrappers, so that Go tests can still test the individual units. +* Any assembly function needs a reference Go implementation, that’s tested and fuzzed side-by-side with the assembly. Follow [golang.org/wiki/TargetSpecific](https://golang.org/wiki/TargetSpecific) for structure and testing practices. +* Document in the Go code why the implementation requires assembly (specific performance benefit, access to instructions, etc), so we can reevaluate as the compiler improves. \ No newline at end of file