[llvm-commits] [llvm] r84309 - /llvm/trunk/docs/CommandGuide/FileCheck.pod
Chris Lattner
sabre at nondot.org
Fri Oct 16 21:47:44 PDT 2009
Author: lattner
Date: Fri Oct 16 23:47:42 2009
New Revision: 84309
URL: http://llvm.org/viewvc/llvm-project?rev=84309&view=rev
Log:
check in a bunch of content from TestingGuide. Part of PR5216
Modified:
llvm/trunk/docs/CommandGuide/FileCheck.pod
Modified: llvm/trunk/docs/CommandGuide/FileCheck.pod
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CommandGuide/FileCheck.pod?rev=84309&r1=84308&r2=84309&view=diff
==============================================================================
--- llvm/trunk/docs/CommandGuide/FileCheck.pod (original)
+++ llvm/trunk/docs/CommandGuide/FileCheck.pod Fri Oct 16 23:47:42 2009
@@ -21,9 +21,6 @@
The I<match-filename> file specifies the file that contains the patterns to
match. The file to verify is always read from standard input.
-The input and output of B<FileCheck> is beyond the scope of this short
-introduction. Please see the I<TestingGuide> page in the LLVM documentation.
-
=head1 OPTIONS
=over
@@ -58,6 +55,189 @@
with 0. Otherwise, if not, or if an error occurs, it will exit with a non-zero
value.
+=head1 TUTORIAL
+
+FileCheck is typically used from LLVM regression tests, being invoked on the RUN
+line of the test. A simple example of using FileCheck from a RUN line looks
+like this:
+
+ ; 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,
+lets look at the rest of the .ll file (after the RUN line):
+
+ define void @sub1(i32* %p, i32 %v) {
+ entry:
+ ; <b>CHECK: sub1:</b>
+ ; <b>CHECK: subl</b>
+ %0 = tail call i32 @llvm.atomic.load.sub.i32.p0i32(i32* %p, i32 %v)
+ ret void
+ }
+
+ define void @inc4(i64* %p) {
+ entry:
+ ; <b>CHECK: inc4:</b>
+ ; <b>CHECK: incq</b>
+ %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.
+
+
+
+=head2 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:
+
+ ; RUN: llvm-as < %s | llc -mtriple=i686-apple-darwin9 -mattr=sse41 \
+ ; RUN: | <b>FileCheck %s -check-prefix=X32</b>
+ ; RUN: llvm-as < %s | llc -mtriple=x86_64-apple-darwin9 -mattr=sse41 \
+ ; RUN: | <b>FileCheck %s -check-prefix=X64</b>
+
+ 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
+ ; <b>X32:</b> pinsrd_1:
+ ; <b>X32:</b> pinsrd $1, 4(%esp), %xmm0
+
+ ; <b>X64:</b> pinsrd_1:
+ ; <b>X64:</b> 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.
+
+
+
+=head2 The "CHECK-NEXT:" directive
+
+Sometimes you want to match lines and would like to verify that matches
+happen on exactly consequtive 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:
+
+ 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
+
+ ; <b>CHECK:</b> t2:
+ ; <b>CHECK:</b> movl 8(%esp), %eax
+ ; <b>CHECK-NEXT:</b> movapd (%eax), %xmm0
+ ; <b>CHECK-NEXT:</b> movhpd 12(%esp), %xmm0
+ ; <b>CHECK-NEXT:</b> movl 4(%esp), %eax
+ ; <b>CHECK-NEXT:</b> movapd %xmm0, (%eax)
+ ; <b>CHECK-NEXT:</b> 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.
+
+
+
+=head2 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:
+
+ 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
+ ; <b>CHECK:</b> @coerce_offset0
+ ; <b>CHECK-NOT:</b> load
+ ; <b>CHECK:</b> ret i8
+ }
+
+
+
+=head2 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: B<{{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:
+
+ ; CHECK: movhpd <b>{{[0-9]+}}</b>(%esp), <b>{{%xmm[0-7]}}</b>
+
+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
+B<{{[{][{]}}> as your pattern.
+
+
+
+=head2 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:
+
+ ; CHECK: test5:
+ ; CHECK: notw <b>[[REGISTER:%[a-z]+]]</b>
+ ; CHECK: andw {{.*}}<b>[[REGISTER]]</b>
+
+The first check line matches a regex (<tt>%[a-z]+</tt>) 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 <tt>[[ ]]</tt> pairs, are named, and their names can be
+formed with the regex "<tt>[a-zA-Z][a-zA-Z0-9]*</tt>". 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
+"<tt>CHECK: [[XYZ:.*]]x[[XYZ]]<tt>" 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.
+
+
+
=head1 AUTHORS
Maintained by The LLVM Team (L<http://llvm.org>).
More information about the llvm-commits
mailing list