You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: test/hotspot/jtreg/compiler/lib/ir_framework/README.md
+17-15Lines changed: 17 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,17 +10,17 @@ The framework is intended to be used in JTreg tests. The JTreg header of the tes
10
10
* @library /test/lib /
11
11
* @run driver my.package.MySimpleTest
12
12
*/
13
-
13
+
14
14
package my.package;
15
-
15
+
16
16
import compiler.lib.ir_framework.*;
17
17
18
18
public class MySimpleTest {
19
-
19
+
20
20
public static void main(String[] args) {
21
21
TestFramework.run(); // The framework runs all tests of this class.
22
22
}
23
-
23
+
24
24
@Test
25
25
@IR(failOn = IRNode.STORE) // Fail if the IR of myTest() contains any stores.
26
26
public void myTest() {
@@ -29,14 +29,14 @@ The framework is intended to be used in JTreg tests. The JTreg header of the tes
29
29
}
30
30
31
31
There are various ways how to set up and run a test within the `main()` method of a JTreg test. These are described and can be found in the [TestFramework](./TestFramework.java) class.
32
-
32
+
33
33
## 2. Features
34
34
The framework offers various annotations and flags to control how your test code should be invoked and being checked. This section gives an overview over all these features.
35
35
36
36
### 2.1 Different Tests
37
37
There are three kinds of tests depending on how much control is needed over the test invocation.
38
38
#### Base Tests
39
-
The simplest form of testing provides a single `@Test` annotated method which the framework will invoke as part of the testing. The test method has no or well-defined arguments that the framework can automatically provide.
39
+
The simplest form of testing provides a single `@Test` annotated method which the framework will invoke as part of the testing. The test method has no or well-defined arguments that the framework can automatically provide.
40
40
41
41
More information on base tests with a precise definition can be found in the Javadocs of [Test](./Test.java). Concrete examples on how to specify a base test can be found in [BaseTestsExample](../../../testlibrary_tests/ir_framework/examples/BaseTestExample.java).
42
42
@@ -57,12 +57,12 @@ The user has the possibility to add an additional `@IR` annotation to any `@Test
57
57
58
58
- A `failOn` check that verifies that the provided regex is not matched in the C2 IR.
59
59
- A `counts` check that verifies that the provided regex is matched a user defined number of times in the C2 IR.
60
-
60
+
61
61
A regex can either be a custom string or any of the default regexes provided by the framework in [IRNode](./IRNode.java) for some commonly used IR nodes (also provides the possibility of composite regexes).
62
62
63
-
An IR verification cannot always be performed. For example, a JTreg test could be run with _-Xint_ or not a debug build (_-XX:+PrintIdeal_ and _-XX:+PrintOptoAssembly_ are debug build flags). But also CI tier testing could add additional JTreg VM and Javaoptions flags which could make an IR rule unstable.
63
+
An IR verification cannot always be performed. For example, a JTreg test could be run with _-Xint_ or not a debug build (_-XX:+PrintIdeal_ and _-XX:+PrintOptoAssembly_ are debug build flags). But also CI tier testing could add additional JTreg VM and Javaoptions flags which could make an IR rule unstable.
64
64
65
-
In general, the framework will only perform IR verification if the used VM flags allow a C2 compilation and if non-critical additional JTreg VM and Javaoptions are provided (see whiteflag list in [TestFramework](./TestFramework.java)). The user test code, however, can specify any flags which still allow an IR verification to be performed if a C2 compilation is done (expected flags by user defined `@IR` annotations).
65
+
In general, the framework will only perform IR verification if the used VM flags allow a C2 compilation and if non-critical additional JTreg VM and Javaoptions are provided (see whiteflag list in [TestFramework](./TestFramework.java)). The user test code, however, can specify any flags which still allow an IR verification to be performed if a C2 compilation is done (expected flags by user defined `@IR` annotations).
66
66
67
67
An `@IR` annotation allows additional preconditions/restrictions on the currently present VM flags to enable or disable rules when certain flags are present or have a specific value (see `applyIfXX` properties of an `@IR` annotation).
68
68
@@ -90,6 +90,7 @@ The framework provides various stress and debug flags. They should mainly be use
90
90
-`-DExclude=test3`: Provide a list of `@Test` method names which should be excluded from execution.
91
91
-`-DScenarios=1,2`: Provide a list of scenario indexes to specify which scenarios should be executed.
92
92
-`-DWarmup=200`: Provide a new default value of the number of warm-up iterations (framework default is 2000). This might have an influence on the resulting IR and could lead to matching failures (the user can also set a fixed default warm-up value in a test with `testFrameworkObject.setDefaultWarmup(200)`).
93
+
-`-DReportStdout=true`: Print the standard output of the test VM.
93
94
-`-DVerbose=true`: Enable more fain-grained logging (slows the execution down).
94
95
-`-DReproduce=true`: Flag to use when directly running a test VM to bypass dependencies to the driver VM state (for example, when reproducing an issue).
95
96
-`-DPrintTimes=true`: Print the execution time measurements of each executed test.
@@ -99,25 +100,26 @@ The framework provides various stress and debug flags. They should mainly be use
99
100
-`-DShuffleTests=false`: Disables the random execution order of all tests (such a shuffling is always done by default).
100
101
-`-DDumpReplay=true`: Add the `DumpReplay` directive to the test VM.
101
102
-`-DGCAfter=true`: Perform `System.gc()` after each test (slows the execution down).
102
-
-`-TestCompilationTimeout=20`: Change the default waiting time (default: 10s) for a compilation of a normal `@Test` annotated method.
103
+
-`-DTestCompilationTimeout=20`: Change the default waiting time (default: 10s) for a compilation of a normal `@Test` annotated method.
103
104
-`-DWaitForCompilationTimeout=20`: Change the default waiting time (default: 10s) for a compilation of a `@Test` annotated method with compilation level [WAIT\_FOR\_COMPILATION](./CompLevel.java).
104
-
-`-DIgnoreCompilerControls=false`: Ignore all compiler controls applied in the framework. This includes any compiler control annotations (`@DontCompile`, `@DontInline`, `@ForceCompile`, `@ForceInline`, `@ForceCompileStaticInitializer`), the exclusion of `@Run` and `@Check` methods from compilation, and the directive to not inline `@Test` annotated methods.
105
-
105
+
-`-DIgnoreCompilerControls=true`: Ignore all compiler controls applied in the framework. This includes any compiler control annotations (`@DontCompile`, `@DontInline`, `@ForceCompile`, `@ForceInline`, `@ForceCompileStaticInitializer`), the exclusion of `@Run` and `@Check` methods from compilation, and the directive to not inline `@Test` annotated methods.
106
+
-`-DExcludeRandom=true`: Randomly exclude some methods from compilation.
107
+
-`-DPreferCommandLineFlags=true`: Prefer flags set via the command line over flags specified by the tests.
106
108
107
109
## 3. Test Framework Execution
108
110
This section gives an overview of how the framework is executing a JTreg test that calls the framework from within its `main()` method.
109
111
110
112
The framework will spawn a new "test VM" to execute the user defined tests. The test VM collects all tests of the test class specified by the user code in `main()` and ensures that there is no violation of the required format by the framework. In a next step, the framework does the following for each test in general:
111
-
1. Warm the test up for a predefined number of times (default 2000). This can also be adapted for all tests by using `testFrameworkobject.setDefaultWarmup(100)` or for individual tests with an additional [@Warmup](./Warmup.java) annotation.
113
+
1. Warm the test up for a predefined number of times (default 2000). This can also be adapted for all tests by using `testFrameworkobject.setDefaultWarmup(100)` or for individual tests with an additional [@Warmup](./Warmup.java) annotation.
112
114
2. After the warm-up is finished, the framework compiles the associated `@Test` annotated method at the specified compilation level (default: C2).
113
115
3. After the compilation, the test is invoked one more time.
114
116
115
117
Once the test VM terminates, IR verification (if possible) is performed on the output of the test VM. If any test throws an exception during its execution or if IR matching fails, the failures are collected and reported in a pretty format. Check the standard error and output for more information and how to reproduce these failures.
116
118
117
119
Some of the steps above can be different due to the kind of the test or due to using non-default annotation properties. These details and differences are described in the Javadocs for the three tests (see section 2.1 Different Tests).
118
120
119
-
More information about the internals and the workflow of the framework can be found in the Javadocs of [TestFramework](./TestFramework.java).
120
-
121
+
More information about the internals and the workflow of the framework can be found in the Javadocs of [TestFramework](./TestFramework.java).
122
+
121
123
## 4. Internal Framework Tests
122
124
There are various tests to verify the correctness of the test framework. These tests can be found in [ir_framework](../../../testlibrary_tests/ir_framework) and can directly be run with JTreg. The tests are part of the normal JTreg tests of HotSpot and should be run upon changing the framework code as a minimal form of testing.
0 commit comments