Golang/go
1
0
Fork 0
mirror of https://github.com/golang/go.git synced 2024-11-21 21:11:11 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updated AssemblyPolicy (markdown)

Filippo Valsorda 2022-03-03 10:18:25 -05:00
parent c66c51623c
commit e12a169e4b
1 changed files with 1 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
AssemblyPolicy.md

@ -7,7 +7,7 @@ In general, the rules are:
* 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 side-by-side with the assembly. Follow [golang.org/wiki/TargetSpecific](https://go.dev/wiki/TargetSpecific) for structure and testing practices.
* The interface of the assembly units and of the reference Go implementation must be the same across architectures.
* The interface of the assembly units and of the reference Go implementation must be the same across architectures, unless the platforms have fundamentally different capabilities (such as high-level cryptographic instructions).
* Unless the Go Security team explicitly commits to owning the specific implementation, an external contributor must commit to maintaining it. If changes are required (for example as part of a broader refactor) and the maintainer is not available, the assembly will be removed.
* The code must be tested in our CI. This means there need to be builders that support the instructions, and if there are multiple (or fallback) paths they must be tested separately. (Tip: use `GODEBUG=cpu.X=off` to disable detection of CPU features.)
* 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.