1 //===- SampleProfReader.cpp - Read LLVM sample profile data ---------------===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // This file implements the class that reads LLVM sample profiles. It
11 // supports two file formats: text and bitcode. The textual representation
12 // is useful for debugging and testing purposes. The bitcode representation
13 // is more compact, resulting in smaller file sizes. However, they can
14 // both be used interchangeably.
16 // NOTE: If you are making changes to the file format, please remember
17 // to document them in the Clang documentation at
18 // tools/clang/docs/UsersManual.rst.
23 // Sample profiles are written as ASCII text. The file is divided into
24 // sections, which correspond to each of the functions executed at runtime.
25 // Each section has the following format
27 // function1:total_samples:total_head_samples
28 // offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
29 // offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
31 // offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
33 // The file may contain blank lines between sections and within a
34 // section. However, the spacing within a single line is fixed. Additional
35 // spaces will result in an error while reading the file.
37 // Function names must be mangled in order for the profile loader to
38 // match them in the current translation unit. The two numbers in the
39 // function header specify how many total samples were accumulated in the
40 // function (first number), and the total number of samples accumulated
41 // in the prologue of the function (second number). This head sample
42 // count provides an indicator of how frequently the function is invoked.
44 // Each sampled line may contain several items. Some are optional (marked
47 // a. Source line offset. This number represents the line number
48 // in the function where the sample was collected. The line number is
49 // always relative to the line where symbol of the function is
50 // defined. So, if the function has its header at line 280, the offset
51 // 13 is at line 293 in the file.
53 // Note that this offset should never be a negative number. This could
54 // happen in cases like macros. The debug machinery will register the
55 // line number at the point of macro expansion. So, if the macro was
56 // expanded in a line before the start of the function, the profile
57 // converter should emit a 0 as the offset (this means that the optimizers
58 // will not be able to associate a meaningful weight to the instructions
61 // b. [OPTIONAL] Discriminator. This is used if the sampled program
62 // was compiled with DWARF discriminator support
63 // (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
64 // DWARF discriminators are unsigned integer values that allow the
65 // compiler to distinguish between multiple execution paths on the
66 // same source line location.
68 // For example, consider the line of code ``if (cond) foo(); else bar();``.
69 // If the predicate ``cond`` is true 80% of the time, then the edge
70 // into function ``foo`` should be considered to be taken most of the
71 // time. But both calls to ``foo`` and ``bar`` are at the same source
72 // line, so a sample count at that line is not sufficient. The
73 // compiler needs to know which part of that line is taken more
76 // This is what discriminators provide. In this case, the calls to
77 // ``foo`` and ``bar`` will be at the same line, but will have
78 // different discriminator values. This allows the compiler to correctly
79 // set edge weights into ``foo`` and ``bar``.
81 // c. Number of samples. This is an integer quantity representing the
82 // number of samples collected by the profiler at this source
85 // d. [OPTIONAL] Potential call targets and samples. If present, this
86 // line contains a call instruction. This models both direct and
87 // number of samples. For example,
89 // 130: 7 foo:3 bar:2 baz:7
91 // The above means that at relative line offset 130 there is a call
92 // instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
93 // with ``baz()`` being the relatively more frequently called target.
95 //===----------------------------------------------------------------------===//
97 #include "llvm/ProfileData/SampleProfReader.h"
98 #include "llvm/Support/Debug.h"
99 #include "llvm/Support/ErrorOr.h"
100 #include "llvm/Support/MemoryBuffer.h"
101 #include "llvm/Support/LineIterator.h"
102 #include "llvm/Support/Regex.h"
104 using namespace sampleprof;
105 using namespace llvm;
107 /// \brief Print the samples collected for a function on stream \p OS.
109 /// \param OS Stream to emit the output to.
110 void FunctionSamples::print(raw_ostream &OS) {
111 OS << TotalSamples << ", " << TotalHeadSamples << ", " << BodySamples.size()
112 << " sampled lines\n";
113 for (BodySampleMap::const_iterator SI = BodySamples.begin(),
114 SE = BodySamples.end();
116 OS << "\tline offset: " << SI->first.LineOffset
117 << ", discriminator: " << SI->first.Discriminator
118 << ", number of samples: " << SI->second << "\n";
122 /// \brief Print the function profile for \p FName on stream \p OS.
124 /// \param OS Stream to emit the output to.
125 /// \param FName Name of the function to print.
126 void SampleProfileReader::printFunctionProfile(raw_ostream &OS,
128 OS << "Function: " << FName << ":\n";
129 Profiles[FName].print(OS);
132 /// \brief Dump the function profile for \p FName.
134 /// \param FName Name of the function to print.
135 void SampleProfileReader::dumpFunctionProfile(StringRef FName) {
136 printFunctionProfile(dbgs(), FName);
139 /// \brief Dump all the function profiles found.
140 void SampleProfileReader::dump() {
141 for (StringMap<FunctionSamples>::const_iterator I = Profiles.begin(),
144 dumpFunctionProfile(I->getKey());
147 /// \brief Load samples from a text file.
149 /// See the documentation at the top of the file for an explanation of
150 /// the expected format.
152 /// \returns true if the file was loaded successfully, false otherwise.
153 bool SampleProfileReader::loadText() {
154 ErrorOr<std::unique_ptr<MemoryBuffer>> BufferOrErr =
155 MemoryBuffer::getFile(Filename);
156 if (std::error_code EC = BufferOrErr.getError()) {
157 std::string Msg(EC.message());
158 M.getContext().diagnose(DiagnosticInfoSampleProfile(Filename.data(), Msg));
161 MemoryBuffer &Buffer = *BufferOrErr.get();
162 line_iterator LineIt(Buffer, /*SkipBlanks=*/true, '#');
164 // Read the profile of each function. Since each function may be
165 // mentioned more than once, and we are collecting flat profiles,
166 // accumulate samples as we parse them.
167 Regex HeadRE("^([^0-9].*):([0-9]+):([0-9]+)$");
168 Regex LineSample("^([0-9]+)\\.?([0-9]+)?: ([0-9]+)(.*)$");
169 while (!LineIt.is_at_eof()) {
170 // Read the header of each function.
172 // Note that for function identifiers we are actually expecting
173 // mangled names, but we may not always get them. This happens when
174 // the compiler decides not to emit the function (e.g., it was inlined
175 // and removed). In this case, the binary will not have the linkage
176 // name for the function, so the profiler will emit the function's
177 // unmangled name, which may contain characters like ':' and '>' in its
178 // name (member functions, templates, etc).
180 // The only requirement we place on the identifier, then, is that it
181 // should not begin with a number.
182 SmallVector<StringRef, 3> Matches;
183 if (!HeadRE.match(*LineIt, &Matches)) {
184 reportParseError(LineIt.line_number(),
185 "Expected 'mangled_name:NUM:NUM', found " + *LineIt);
188 assert(Matches.size() == 4);
189 StringRef FName = Matches[1];
190 unsigned NumSamples, NumHeadSamples;
191 Matches[2].getAsInteger(10, NumSamples);
192 Matches[3].getAsInteger(10, NumHeadSamples);
193 Profiles[FName] = FunctionSamples();
194 FunctionSamples &FProfile = Profiles[FName];
195 FProfile.addTotalSamples(NumSamples);
196 FProfile.addHeadSamples(NumHeadSamples);
199 // Now read the body. The body of the function ends when we reach
200 // EOF or when we see the start of the next function.
201 while (!LineIt.is_at_eof() && isdigit((*LineIt)[0])) {
202 if (!LineSample.match(*LineIt, &Matches)) {
204 LineIt.line_number(),
205 "Expected 'NUM[.NUM]: NUM[ mangled_name:NUM]*', found " + *LineIt);
208 assert(Matches.size() == 5);
209 unsigned LineOffset, NumSamples, Discriminator = 0;
210 Matches[1].getAsInteger(10, LineOffset);
211 if (Matches[2] != "")
212 Matches[2].getAsInteger(10, Discriminator);
213 Matches[3].getAsInteger(10, NumSamples);
215 // FIXME: Handle called targets (in Matches[4]).
217 // When dealing with instruction weights, we use the value
218 // zero to indicate the absence of a sample. If we read an
219 // actual zero from the profile file, return it as 1 to
220 // avoid the confusion later on.
223 FProfile.addBodySamples(LineOffset, Discriminator, NumSamples);
231 /// \brief Load execution samples from a file.
233 /// This function examines the header of the given file to determine
234 /// whether to use the text or the bitcode loader.
235 bool SampleProfileReader::load() {
236 // TODO Actually detect the file format.