1// Copyright 2018 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5The codegen directory contains code generation tests for the gc
6compiler.
7
8
9- Introduction
10
11The test harness compiles Go code inside files in this directory and
12matches the generated assembly (the output of `go tool compile -S`)
13against a set of regexps to be specified in comments that follow a
14special syntax (described below). The test driver is implemented as
15an action within the GOROOT/test test suite, called "asmcheck".
16
17The codegen harness is part of the all.bash test suite, but for
18performance reasons only the codegen tests for the host machine's
19GOARCH are enabled by default, and only on GOOS=linux.
20
21To perform comprehensive tests for all the supported architectures
22(even on a non-Linux system), one can run the following command:
23
24 $ ../../bin/go test cmd/internal/testdir -run='Test/codegen' -all_codegen -v
25
26This is recommended after any change that affect the compiler's code.
27
28The test harness compiles the tests with the same go toolchain that is
29used to run the test. After writing tests for a newly added codegen
30transformation, it can be useful to first run the test harness with a
31toolchain from a released Go version (and verify that the new tests
32fail), and then re-running the tests using the devel toolchain.
33
34
35- Regexps comments syntax
36
37Instructions to match are specified inside plain comments that start
38with an architecture tag, followed by a colon and a quoted Go-style
39regexp to be matched. For example, the following test:
40
41 func Sqrt(x float64) float64 {
42 // amd64:"SQRTSD"
43 // arm64:"FSQRTD"
44 return math.Sqrt(x)
45 }
46
47verifies that math.Sqrt calls are intrinsified to a SQRTSD instruction
48on amd64, and to a FSQRTD instruction on arm64.
49
50It is possible to put multiple architectures checks into the same
51line, as:
52
53 // amd64:"SQRTSD" arm64:"FSQRTD"
54
55although this form should be avoided when doing so would make the
56regexps line excessively long and difficult to read.
57
58Comments that are on their own line will be matched against the first
59subsequent non-comment line. Inline comments are also supported; the
60regexp will be matched against the code found on the same line:
61
62 func Sqrt(x float64) float64 {
63 return math.Sqrt(x) // arm:"SQRTD"
64 }
65
66It's possible to specify a comma-separated list of regexps to be
67matched. For example, the following test:
68
69 func TZ8(n uint8) int {
70 // amd64:"BSFQ","ORQ\t\\$256"
71 return bits.TrailingZeros8(n)
72 }
73
74verifies that the code generated for a bits.TrailingZeros8 call on
75amd64 contains both a "BSFQ" instruction and an "ORQ $256".
76
77Note how the ORQ regex includes a tab char (\t). In the Go assembly
78syntax, operands are separated from opcodes by a tabulation.
79
80Regexps can be quoted using either " or `. Special characters must be
81escaped accordingly. Both of these are accepted, and equivalent:
82
83 // amd64:"ADDQ\t\\$3"
84 // amd64:`ADDQ\t\$3`
85
86and they'll match this assembly line:
87
88 ADDQ $3
89
90Negative matches can be specified using a - before the quoted regexp.
91For example:
92
93 func MoveSmall() {
94 x := [...]byte{1, 2, 3, 4, 5, 6, 7}
95 copy(x[1:], x[:]) // arm64:-".*memmove"
96 }
97
98verifies that NO memmove call is present in the assembly generated for
99the copy() line.
100
101
102- Architecture specifiers
103
104There are three different ways to specify on which architecture a test
105should be run:
106
107* Specify only the architecture (eg: "amd64"). This indicates that the
108 check should be run on all the supported architecture variants. For
109 instance, arm checks will be run against all supported GOARM
110 variations (5,6,7).
111* Specify both the architecture and a variant, separated by a slash
112 (eg: "arm/7"). This means that the check will be run only on that
113 specific variant.
114* Specify the operating system, the architecture and the variant,
115 separated by slashes (eg: "plan9/386/sse2", "plan9/amd64/"). This is
116 needed in the rare case that you need to do a codegen test affected
117 by a specific operating system; by default, tests are compiled only
118 targeting linux.
119
120
121- Remarks, and Caveats
122
123-- Write small test functions
124
125As a general guideline, test functions should be small, to avoid
126possible interactions between unrelated lines of code that may be
127introduced, for example, by the compiler's optimization passes.
128
129Any given line of Go code could get assigned more instructions than it
130may appear from reading the source. In particular, matching all MOV
131instructions should be avoided; the compiler may add them for
132unrelated reasons and this may render the test ineffective.
133
134-- Line matching logic
135
136Regexps are always matched from the start of the instructions line.
137This means, for example, that the "MULQ" regexp is equivalent to
138"^MULQ" (^ representing the start of the line), and it will NOT match
139the following assembly line:
140
141 IMULQ $99, AX
142
143To force a match at any point of the line, ".*MULQ" should be used.
144
145For the same reason, a negative regexp like -"memmove" is not enough
146to make sure that no memmove call is included in the assembly. A
147memmove call looks like this:
148
149 CALL runtime.memmove(SB)
150
151To make sure that the "memmove" symbol does not appear anywhere in the
152assembly, the negative regexp to be used is -".*memmove".
153