test/codegen/README

   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
   5 The codegen directory contains code generation tests for the gc
   6 compiler.
   7
   8
   9 - Introduction
  10
  11 The test harness compiles Go code inside files in this directory and
  12 matches the generated assembly (the output of `go tool compile -S`)
  13 against a set of regexps to be specified in comments that follow a
  14 special syntax (described below). The test driver is implemented as
  15 an action within the GOROOT/test test suite, called "asmcheck".
  16
  17 The codegen harness is part of the all.bash test suite, but for
  18 performance reasons only the codegen tests for the host machine's
  19 GOARCH are enabled by default, and only on GOOS=linux.
  20
  21 To 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
  26 This is recommended after any change that affect the compiler's code.
  27
  28 The test harness compiles the tests with the same go toolchain that is
  29 used to run the test. After writing tests for a newly added codegen
  30 transformation, it can be useful to first run the test harness with a
  31 toolchain from a released Go version (and verify that the new tests
  32 fail), and then re-running the tests using the devel toolchain.
  33
  34
  35 - Regexps comments syntax
  36
  37 Instructions to match are specified inside plain comments that start
  38 with an architecture tag, followed by a colon and a quoted Go-style
  39 regexp 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
  47 verifies that math.Sqrt calls are intrinsified to a SQRTSD instruction
  48 on amd64, and to a FSQRTD instruction on arm64.
  49
  50 It is possible to put multiple architectures checks into the same
  51 line, as:
  52
  53   // amd64:"SQRTSD" arm64:"FSQRTD"
  54
  55 although this form should be avoided when doing so would make the
  56 regexps line excessively long and difficult to read.
  57
  58 Comments that are on their own line will be matched against the first
  59 subsequent non-comment line. Inline comments are also supported; the
  60 regexp 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
  66 It's possible to specify a comma-separated list of regexps to be
  67 matched. 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
  74 verifies that the code generated for a bits.TrailingZeros8 call on
  75 amd64 contains both a "BSFQ" instruction and an "ORQ $256".
  76
  77 Note how the ORQ regex includes a tab char (\t). In the Go assembly
  78 syntax, operands are separated from opcodes by a tabulation.
  79
  80 Regexps can be quoted using either " or `. Special characters must be
  81 escaped accordingly. Both of these are accepted, and equivalent:
  82
  83   // amd64:"ADDQ\t\\$3"
  84   // amd64:`ADDQ\t\$3`
  85
  86 and they'll match this assembly line:
  87
  88   ADDQ  $3
  89
  90 Negative matches can be specified using a - before the quoted regexp.
  91 For example:
  92
  93   func MoveSmall() {
  94            x := [...]byte{1, 2, 3, 4, 5, 6, 7}
  95            copy(x[1:], x[:]) // arm64:-".*memmove"
  96   }
  97
  98 verifies that NO memmove call is present in the assembly generated for
  99 the copy() line.
 100
 101
 102 - Architecture specifiers
 103
 104 There are three different ways to specify on which architecture a test
 105 should 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
 125 As a general guideline, test functions should be small, to avoid
 126 possible interactions between unrelated lines of code that may be
 127 introduced, for example, by the compiler's optimization passes.
 128
 129 Any given line of Go code could get assigned more instructions than it
 130 may appear from reading the source. In particular, matching all MOV
 131 instructions should be avoided; the compiler may add them for
 132 unrelated reasons and this may render the test ineffective.
 133
 134 -- Line matching logic
 135
 136 Regexps are always matched from the start of the instructions line.
 137 This means, for example, that the "MULQ" regexp is equivalent to
 138 "^MULQ" (^ representing the start of the line), and it will NOT match
 139 the following assembly line:
 140
 141   IMULQ $99, AX
 142
 143 To force a match at any point of the line, ".*MULQ" should be used.
 144
 145 For the same reason, a negative regexp like -"memmove" is not enough
 146 to make sure that no memmove call is included in the assembly. A
 147 memmove call looks like this:
 148
 149   CALL  runtime.memmove(SB)
 150
 151 To make sure that the "memmove" symbol does not appear anywhere in the
 152 assembly, the negative regexp to be used is -".*memmove".