diff options
Diffstat (limited to 'docs/TestingGuide.rst')
| -rw-r--r-- | docs/TestingGuide.rst | 198 |
1 files changed, 4 insertions, 194 deletions
diff --git a/docs/TestingGuide.rst b/docs/TestingGuide.rst index 69d24225c9..329003f089 100644 --- a/docs/TestingGuide.rst +++ b/docs/TestingGuide.rst @@ -335,200 +335,10 @@ to verify that the output of a tools contains a series of different output in a specific order. The FileCheck tool was designed to help with these problems. -FileCheck (whose basic command line arguments are described in `the -FileCheck man page <http://llvm.org/cmds/FileCheck.html>`_ is designed -to read a file to check from standard input, and the set of things to -verify from a file specified as a command line argument. A simple -example of using FileCheck from a RUN line looks like this: - -.. code-block:: llvm - - ; RUN: llvm-as < %s | llc -march=x86-64 | FileCheck %s - -This syntax says to pipe the current file ("%s") into llvm-as, pipe that -into llc, then pipe the output of llc into FileCheck. This means that -FileCheck will be verifying its standard input (the llc output) against -the filename argument specified (the original .ll file specified by -"%s"). To see how this works, let's look at the rest of the .ll file -(after the RUN line): - -.. code-block:: llvm - - define void @sub1(i32* %p, i32 %v) { - entry: - ; CHECK: sub1: - ; CHECK: subl - %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v) - ret void - } - - define void @inc4(i64* %p) { - entry: - ; CHECK: inc4: - ; CHECK: incq - %0 = tail call i64 @llvm.atomic.load.add.i64.p0i64(i64* %p, i64 1) - ret void - } - -Here you can see some "CHECK:" lines specified in comments. Now you can -see how the file is piped into llvm-as, then llc, and the machine code -output is what we are verifying. FileCheck checks the machine code -output to verify that it matches what the "CHECK:" lines specify. - -The syntax of the CHECK: lines is very simple: they are fixed strings -that must occur in order. FileCheck defaults to ignoring horizontal -whitespace differences (e.g. a space is allowed to match a tab) but -otherwise, the contents of the CHECK: line is required to match some -thing in the test file exactly. - -One nice thing about FileCheck (compared to grep) is that it allows -merging test cases together into logical groups. For example, because -the test above is checking for the "sub1:" and "inc4:" labels, it will -not match unless there is a "subl" in between those labels. If it -existed somewhere else in the file, that would not count: "grep subl" -matches if subl exists anywhere in the file. - -The FileCheck -check-prefix option -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The FileCheck -check-prefix option allows multiple test configurations -to be driven from one .ll file. This is useful in many circumstances, -for example, testing different architectural variants with llc. Here's a -simple example: - -.. code-block:: llvm - - ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \ - ; RUN: | FileCheck %s -check-prefix=X32 - ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \ - ; RUN: | FileCheck %s -check-prefix=X64 - - define <4 x i32> @pinsrd_1(i32 %s, <4 x i32> %tmp) nounwind { - %tmp1 = insertelement <4 x i32> %tmp, i32 %s, i32 1 - ret <4 x i32> %tmp1 - ; X32: pinsrd_1: - ; X32: pinsrd $1, 4(%esp), %xmm0 - - ; X64: pinsrd_1: - ; X64: pinsrd $1, %edi, %xmm0 - } - -In this case, we're testing that we get the expected code generation -with both 32-bit and 64-bit code generation. - -The "CHECK-NEXT:" directive -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Sometimes you want to match lines and would like to verify that matches -happen on exactly consecutive lines with no other lines in between them. -In this case, you can use CHECK: and CHECK-NEXT: directives to specify -this. If you specified a custom check prefix, just use "<PREFIX>-NEXT:". -For example, something like this works as you'd expect: - -.. code-block:: llvm - - define void @t2(<2 x double>* %r, <2 x double>* %A, double %B) { - %tmp3 = load <2 x double>* %A, align 16 - %tmp7 = insertelement <2 x double> undef, double %B, i32 0 - %tmp9 = shufflevector <2 x double> %tmp3, - <2 x double> %tmp7, - <2 x i32> < i32 0, i32 2 > - store <2 x double> %tmp9, <2 x double>* %r, align 16 - ret void - - ; CHECK: t2: - ; CHECK: movl 8(%esp), %eax - ; CHECK-NEXT: movapd (%eax), %xmm0 - ; CHECK-NEXT: movhpd 12(%esp), %xmm0 - ; CHECK-NEXT: movl 4(%esp), %eax - ; CHECK-NEXT: movapd %xmm0, (%eax) - ; CHECK-NEXT: ret - } - -CHECK-NEXT: directives reject the input unless there is exactly one -newline between it an the previous directive. A CHECK-NEXT cannot be the -first directive in a file. - -The "CHECK-NOT:" directive -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The CHECK-NOT: directive is used to verify that a string doesn't occur -between two matches (or the first match and the beginning of the file). -For example, to verify that a load is removed by a transformation, a -test like this can be used: - -.. code-block:: llvm - - define i8 @coerce_offset0(i32 %V, i32* %P) { - store i32 %V, i32* %P - - %P2 = bitcast i32* %P to i8* - %P3 = getelementptr i8* %P2, i32 2 - - %A = load i8* %P3 - ret i8 %A - ; CHECK: @coerce_offset0 - ; CHECK-NOT: load - ; CHECK: ret i8 - } - -FileCheck Pattern Matching Syntax -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The CHECK: and CHECK-NOT: directives both take a pattern to match. For -most uses of FileCheck, fixed string matching is perfectly sufficient. -For some things, a more flexible form of matching is desired. To support -this, FileCheck allows you to specify regular expressions in matching -strings, surrounded by double braces: ``{{yourregex}}``. Because we want -to use fixed string matching for a majority of what we do, FileCheck has -been designed to support mixing and matching fixed string matching with -regular expressions. This allows you to write things like this: - -.. code-block:: llvm - - ; CHECK: movhpd {{[0-9]+}}(%esp), {{%xmm[0-7]}} - -In this case, any offset from the ESP register will be allowed, and any -xmm register will be allowed. - -Because regular expressions are enclosed with double braces, they are -visually distinct, and you don't need to use escape characters within -the double braces like you would in C. In the rare case that you want to -match double braces explicitly from the input, you can use something -ugly like ``{{[{][{]}}`` as your pattern. - -FileCheck Variables -^^^^^^^^^^^^^^^^^^^ - -It is often useful to match a pattern and then verify that it occurs -again later in the file. For codegen tests, this can be useful to allow -any register, but verify that that register is used consistently later. -To do this, FileCheck allows named variables to be defined and -substituted into patterns. Here is a simple example: - -.. code-block:: llvm - - ; CHECK: test5: - ; CHECK: notw [[REGISTER:%[a-z]+]] - ; CHECK: andw {{.*}}[[REGISTER]] - -The first check line matches a regex (``%[a-z]+``) and captures it into -the variables "REGISTER". The second line verifies that whatever is in -REGISTER occurs later in the file after an "andw". FileCheck variable -references are always contained in ``[[ ]]`` pairs, are named, and their -names can be formed with the regex "``[a-zA-Z][a-zA-Z0-9]*``". If a -colon follows the name, then it is a definition of the variable, if not, -it is a use. - -FileCheck variables can be defined multiple times, and uses always get -the latest value. Note that variables are all read at the start of a -"CHECK" line and are all defined at the end. This means that if you have -something like "``CHECK: [[XYZ:.*]]x[[XYZ]]``" that the check line will -read the previous value of the XYZ variable and define a new one after -the match is performed. If you need to do something like this you can -probably take advantage of the fact that FileCheck is not actually -line-oriented when it matches, this allows you to define two separate -CHECK lines that match on the same line. +FileCheck is designed to read a file to check from standard input, and the set +of things to verify from a file specified as a command line argument. +FileCheck is described in :doc:`the FileCheck man page +<CommandGuide/FileCheck>`. Variables and substitutions --------------------------- |