1Checker is a testing tool which compiles a given test file and compares the 2state of the control-flow graph before and after each optimization pass 3against a set of statements specified alongside the tests. 4 5Tests are written in Java or Smali, turned into DEX and compiled with the 6Optimizing compiler. "Check lines" are statements formatted as comments of the 7source file. They begin with prefix "/// CHECK" or "## CHECK", respectively, 8followed by a pattern that the engine attempts to match in the compiler output. 9 10Statements are tested in groups which correspond to the individual compiler 11passes. Each group of check lines therefore must start with a 'CHECK-START' 12header which specifies the output group it should be tested against. The group 13name must exactly match one of the groups recognized in the output (they can 14be listed with the '--list-passes' command-line flag). 15 16Matching of check lines is carried out in the order of appearance in the 17source file. There are five types of check lines. Branching instructions are 18also supported and documented later in this file. 19 - CHECK: Must match an output line which appears in the output group 20 later than lines matched against any preceeding checks. Output 21 lines must therefore match the check lines in the same order. 22 These are referred to as "in-order" checks in the code. 23 - CHECK-DAG: Must match an output line which appears in the output group 24 later than lines matched against any preceeding in-order checks. 25 In other words, the order of output lines does not matter 26 between consecutive DAG checks. 27 - CHECK-NOT: Must not match any output line which appears in the output group 28 later than lines matched against any preceeding checks and 29 earlier than lines matched against any subsequent checks. 30 Surrounding non-negative checks (or boundaries of the group) 31 therefore create a scope within which the statement is verified. 32 - CHECK-NEXT: Must match the output line which comes right after the line which 33 matched the previous check. Can only be used after a CHECK or 34 another CHECK-NEXT. 35 - CHECK-EVAL: Specifies a Python expression which must evaluate to 'True'. 36 37Check-line patterns are treated as plain text rather than regular expressions 38but are whitespace agnostic. 39 40Actual regex patterns can be inserted enclosed in '{{' and '}}' brackets. If 41curly brackets need to be used inside the body of the regex, they need to be 42enclosed in round brackets. For example, the pattern '{{foo{2}}}' will parse 43the invalid regex 'foo{2', but '{{(fo{2})}}' will match 'foo'. 44 45Regex patterns can be named and referenced later. A new variable is defined 46with '<<name:regex>>' and can be referenced with '<<name>>'. Variables are 47only valid within the scope of the defining group. Within a group they cannot 48be redefined or used undefined. 49 50Example: 51 The following statements can be placed in a Java source file: 52 53 /// CHECK-START: int MyClass.MyMethod() constant_folding (after) 54 /// CHECK: <<ID:i\d+>> IntConstant {{11|22}} 55 /// CHECK: Return [<<ID>>] 56 57 The engine will attempt to match the check lines against the output of the 58 group named on the first line. Together they verify that the CFG after 59 constant folding returns an integer constant with value either 11 or 22. 60 61 62Of the language constructs above, 'CHECK-EVAL' lines support only referencing of 63variables. Any other surrounding text will be passed to Python's `eval` as is. 64 65Example: 66 /// CHECK-START: int MyClass.MyMethod() liveness (after) 67 /// CHECK: InstructionA liveness:<<VarA:\d+>> 68 /// CHECK: InstructionB liveness:<<VarB:\d+>> 69 /// CHECK-EVAL: <<VarA>> != <<VarB>> 70 71 72A group of check lines can be made architecture-specific by inserting '-<arch>' 73after the 'CHECK-START' keyword. The previous example can be updated to run for 74arm64 only with: 75 76Example: 77 /// CHECK-START-ARM64: int MyClass.MyMethod() constant_folding (after) 78 /// CHECK: <<ID:i\d+>> IntConstant {{11|22}} 79 /// CHECK: Return [<<ID>>] 80 81For convenience, several architectures can be specified as set after the 82'CHECK-START' keyword. Any listed architecture will match in that case, 83thereby avoiding to repeat the check lines if some, but not all architectures 84match. An example line looks like: 85 86 /// CHECK-START-{X86_64,ARM,ARM64}: int MyClass.MyMethod() constant_folding (after) 87 88 89Branching is possible thanks to the following statements: 90 - CHECK-IF: 91 - CHECK-ELIF: 92 - CHECK-ELSE: 93 - CHECK-FI: 94 95CHECK-IF and CHECK-ELIF take a Python expression as input that will be evaluated by `eval`. 96 97A possible use case of branching is to check whether the generated code exploits the instruction 98architecture features enabled at compile time. For that purpose, you can call the custom made 99function isaHasFeature("feature_name"). 100 101Example: 102 /// CHECK-START-ARM64: int other.TestByte.testDotProdComplex(byte[], byte[]) disassembly (after) 103 /// CHECK: VecDotProd 104 /// CHECK-IF: isaHasFeature("dotprod") 105 /// CHECK: sdot 106 /// CHECK-ELSE: 107 /// CHECK-NOT: sdot 108 /// CHECK-FI: 109 110Like CHECK-EVAL, CHECK-IF and CHECK-ELIF support only referencing of variables, defining new 111variables as part of the statement input is not allowed. Any other surrounding text will be passed 112to Python's `eval` as is. CHECK-ELSE and CHECK-FI must not have any input. 113 114Example: 115 /// CHECK-START: int MyClass.MyMethod() constant_folding (after) 116 /// CHECK: {{i\d+}} IntConstant <<MyConst:(0|1|2)>> 117 /// CHECK-IF: <<MyConst>> == 0 118 /// CHECK-NEXT: FooBar01 119 /// CHECK-ELIF: <<MyConst>> == 1 120 /// CHECK-NOT: FooBar01 121 /// CHECK-FI: 122 123Branch blocks can contain any statement, including CHECK-NEXT and CHECK-DAG. 124Notice the CHECK-NEXT statement within the IF branch. When a CHECK-NEXT is encountered, 125Checker expects that the previously executed statement was either a CHECK or a CHECK-NEXT. 126This condition is enforced at runtime, and an error is thrown if it's not respected. 127 128Statements inside branches can define new variables. If a new variable gets defined inside a branch 129(of any depth, since nested branching is allowed), that variable will become global within the scope 130of the defining group. In other words, it will be valid everywhere after its definition within the 131block defined by the CHECK-START statement. The absence of lexical scoping for Checker variables 132seems a bit inelegant at first, but is probably more practical. 133 134Example: 135 /// CHECK-START: void MyClass.FooBar() liveness (after) 136 /// CHECK-IF: os.environ.get('ART_READ_BARRIER_TYPE') != 'TABLELOOKUP' 137 /// CHECK: <<MyID:i\d+>> IntConstant 3 138 /// CHECK-ELSE: 139 /// CHECK: <<MyID:i\d+>> IntConstant 5 140 /// CHECK-FI: 141 /// CHECK-NEXT: Return [<<MyID>>] 142 143Notice that the variable MyID remained valid outside the branch where it was defined. 144Furthermore, in this example, the definition of MyID depends on which branch gets selected at 145runtime. Attempting to re-define a variable or referencing an undefined variable is not allowed, 146Checker will throw a runtime error. 147The example above also shows how we can use environment variables to perform custom checks. 148 149It is possible to combine IF, (multiple) ELIF and ELSE statements together. Nested branching is 150also supported. 151