diff --git a/AssemblyPolicy.md b/AssemblyPolicy.md index f7fb8a22..a762f47b 100644 --- a/AssemblyPolicy.md +++ b/AssemblyPolicy.md @@ -4,18 +4,16 @@ This document describes when and how to add assembly code to routines in the Go- 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. +* We prefer portable Go, not assembly. Code in assembly means (N packages * M architectures) to maintain, rather than just N packages. -* assembly code needs benchmarks showing it's worth it +* 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, and support it with benchmarks. -* 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. +* Explain the root causes. What changes in the compiler and standard library would allow you to replace this assembly with Go? (New intrinsics, SSA pattern matching, other optimizations.) -* explain why you need the assembly. 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. -* make your assembly easy to review, and ideally auto-generated from a Go program so we can review the generator program. Comment it well. - -* test it well. The bar for new assembly code is high. It needs commensurate test coverage. The generic existing high-level tests are often not enough to test hundreds of lines of assembly. Test subroutines individually. Fuzz it against the Go implementation. +* 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. +* If possible, port existing reviewed implementations. A tool should make it easy to review diffs from decompiler output. Consider the license implications.