// Copyright 2018 The Go Authors. All rights reserved.

// Use of this source code is governed by a BSD-style

// license that can be found in the LICENSE file.

The codegen directory contains code generation tests for the gc

compiler.

- Introduction

The test harness compiles Go code inside files in this directory and

matches the generated assembly (the output of `go tool compile -S`)

against a set of regexps to be specified in comments that follow a

special syntax (described below). The test driver is implemented as

an action within the GOROOT/test test suite, called "asmcheck".

The codegen harness is part of the all.bash test suite, but for

performance reasons only the codegen tests for the host machine's

GOARCH are enabled by default, and only on GOOS=linux.

To perform comprehensive tests for all the supported architectures

(even on a non-Linux system), one can run the following command:

$ ../../bin/go test cmd/internal/testdir -run='Test/codegen' -all_codegen -v

This is recommended after any change that affect the compiler's code.

The test harness compiles the tests with the same go toolchain that is

used to run the test. After writing tests for a newly added codegen

transformation, it can be useful to first run the test harness with a

toolchain from a released Go version (and verify that the new tests

fail), and then re-running the tests using the devel toolchain.

- Regexps comments syntax

Instructions to match are specified inside plain comments that start

with an architecture tag, followed by a colon and a quoted Go-style

regexp to be matched. For example, the following test:

func Sqrt(x float64) float64 {

// amd64:"SQRTSD"

// arm64:"FSQRTD"

return math.Sqrt(x)

}

verifies that math.Sqrt calls are intrinsified to a SQRTSD instruction

on amd64, and to a FSQRTD instruction on arm64.

It is possible to put multiple architectures checks into the same

line, as:

// amd64:"SQRTSD" arm64:"FSQRTD"

although this form should be avoided when doing so would make the

regexps line excessively long and difficult to read.

Comments that are on their own line will be matched against the first

subsequent non-comment line. Inline comments are also supported; the

regexp will be matched against the code found on the same line:

func Sqrt(x float64) float64 {

return math.Sqrt(x) // arm:"SQRTD"

}

It's possible to specify a space-separated list of regexps to be

matched. For example, the following test:

func TZ8(n uint8) int {

// amd64:"BSFL" "ORL [$]256"

return bits.TrailingZeros8(n)

}

verifies that the code generated for a bits.TrailingZeros8 call on

amd64 contains both a "BSFL" instruction and an "ORL $256".

Note that spaces are special - they will match any sequence of

whitespace (including tabs) in the printed assembly.

Regexps can be quoted using either " or `. Special characters must be

escaped accordingly. All of these are accepted, and equivalent:

// amd64:"ADDQ \\$3"

// amd64:`ADDQ \$3`

// amd64:"ADDQ [$]3"

and they'll match this assembly line:

ADDQ $3

Negative matches can be specified using a - before the quoted regexp.

For example:

func MoveSmall() {

x := [...]byte{1, 2, 3, 4, 5, 6, 7}

copy(x[1:], x[:]) // arm64:-".*memmove"

}

verifies that NO memmove call is present in the assembly generated for

the copy() line.

The expected number of matches for the regexp can be specified using a

positive number:

func fb(a [4]int) (r [4]int) {

// amd64:2`MOVUPS[^,]+, X0$` 2`MOVUPS X0,[^\n]+$`

return a

}

- Architecture specifiers

There are three different ways to specify on which architecture a test

should be run:

* Specify only the architecture (eg: "amd64"). This indicates that the

check should be run on all the supported architecture variants. For

instance, arm checks will be run against all supported GOARM

variations (5,6,7).

* Specify both the architecture and a variant, separated by a slash

(eg: "arm/7"). This means that the check will be run only on that

specific variant.

* Specify the operating system, the architecture and the variant,

separated by slashes (eg: "plan9/386/sse2", "plan9/amd64/"). This is

needed in the rare case that you need to do a codegen test affected

by a specific operating system; by default, tests are compiled only

targeting linux.

- Remarks, and Caveats

-- Write small test functions

As a general guideline, test functions should be small, to avoid

possible interactions between unrelated lines of code that may be

introduced, for example, by the compiler's optimization passes.

Any given line of Go code could get assigned more instructions than it

may appear from reading the source. In particular, matching all MOV

instructions should be avoided; the compiler may add them for

unrelated reasons and this may render the test ineffective.

-- Line matching logic

Regexps are always matched from the start of the instructions line.

This means, for example, that the "MULQ" regexp is equivalent to

"^MULQ" (^ representing the start of the line), and it will NOT match

the following assembly line:

IMULQ $99, AX

To force a match at any point of the line, ".*MULQ" should be used.

For the same reason, a negative regexp like -"memmove" is not enough

to make sure that no memmove call is included in the assembly. A

memmove call looks like this:

CALL runtime.memmove(SB)

To make sure that the "memmove" symbol does not appear anywhere in the

assembly, the negative regexp to be used is -".*memmove".