LLVM  4.0.0
SampleProfReader.h
Go to the documentation of this file.
1 //===- SampleProfReader.h - Read LLVM sample profile data -----------------===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This file contains definitions needed for reading sample profiles.
11 //
12 // NOTE: If you are making changes to this file format, please remember
13 // to document them in the Clang documentation at
14 // tools/clang/docs/UsersManual.rst.
15 //
16 // Text format
17 // -----------
18 //
19 // Sample profiles are written as ASCII text. The file is divided into
20 // sections, which correspond to each of the functions executed at runtime.
21 // Each section has the following format
22 //
23 // function1:total_samples:total_head_samples
24 // offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
25 // offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
26 // ...
27 // offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
28 // offsetA[.discriminator]: fnA:num_of_total_samples
29 // offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]
30 // ...
31 //
32 // This is a nested tree in which the identation represents the nesting level
33 // of the inline stack. There are no blank lines in the file. And the spacing
34 // within a single line is fixed. Additional spaces will result in an error
35 // while reading the file.
36 //
37 // Any line starting with the '#' character is completely ignored.
38 //
39 // Inlined calls are represented with indentation. The Inline stack is a
40 // stack of source locations in which the top of the stack represents the
41 // leaf function, and the bottom of the stack represents the actual
42 // symbol to which the instruction belongs.
43 //
44 // Function names must be mangled in order for the profile loader to
45 // match them in the current translation unit. The two numbers in the
46 // function header specify how many total samples were accumulated in the
47 // function (first number), and the total number of samples accumulated
48 // in the prologue of the function (second number). This head sample
49 // count provides an indicator of how frequently the function is invoked.
50 //
51 // There are two types of lines in the function body.
52 //
53 // * Sampled line represents the profile information of a source location.
54 // * Callsite line represents the profile information of a callsite.
55 //
56 // Each sampled line may contain several items. Some are optional (marked
57 // below):
58 //
59 // a. Source line offset. This number represents the line number
60 // in the function where the sample was collected. The line number is
61 // always relative to the line where symbol of the function is
62 // defined. So, if the function has its header at line 280, the offset
63 // 13 is at line 293 in the file.
64 //
65 // Note that this offset should never be a negative number. This could
66 // happen in cases like macros. The debug machinery will register the
67 // line number at the point of macro expansion. So, if the macro was
68 // expanded in a line before the start of the function, the profile
69 // converter should emit a 0 as the offset (this means that the optimizers
70 // will not be able to associate a meaningful weight to the instructions
71 // in the macro).
72 //
73 // b. [OPTIONAL] Discriminator. This is used if the sampled program
74 // was compiled with DWARF discriminator support
75 // (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
76 // DWARF discriminators are unsigned integer values that allow the
77 // compiler to distinguish between multiple execution paths on the
78 // same source line location.
79 //
80 // For example, consider the line of code ``if (cond) foo(); else bar();``.
81 // If the predicate ``cond`` is true 80% of the time, then the edge
82 // into function ``foo`` should be considered to be taken most of the
83 // time. But both calls to ``foo`` and ``bar`` are at the same source
84 // line, so a sample count at that line is not sufficient. The
85 // compiler needs to know which part of that line is taken more
86 // frequently.
87 //
88 // This is what discriminators provide. In this case, the calls to
89 // ``foo`` and ``bar`` will be at the same line, but will have
90 // different discriminator values. This allows the compiler to correctly
91 // set edge weights into ``foo`` and ``bar``.
92 //
93 // c. Number of samples. This is an integer quantity representing the
94 // number of samples collected by the profiler at this source
95 // location.
96 //
97 // d. [OPTIONAL] Potential call targets and samples. If present, this
98 // line contains a call instruction. This models both direct and
99 // number of samples. For example,
100 //
101 // 130: 7 foo:3 bar:2 baz:7
102 //
103 // The above means that at relative line offset 130 there is a call
104 // instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
105 // with ``baz()`` being the relatively more frequently called target.
106 //
107 // Each callsite line may contain several items. Some are optional.
108 //
109 // a. Source line offset. This number represents the line number of the
110 // callsite that is inlined in the profiled binary.
111 //
112 // b. [OPTIONAL] Discriminator. Same as the discriminator for sampled line.
113 //
114 // c. Number of samples. This is an integer quantity representing the
115 // total number of samples collected for the inlined instance at this
116 // callsite
117 //
118 //
119 // Binary format
120 // -------------
121 //
122 // This is a more compact encoding. Numbers are encoded as ULEB128 values
123 // and all strings are encoded in a name table. The file is organized in
124 // the following sections:
125 //
126 // MAGIC (uint64_t)
127 // File identifier computed by function SPMagic() (0x5350524f463432ff)
128 //
129 // VERSION (uint32_t)
130 // File format version number computed by SPVersion()
131 //
132 // SUMMARY
133 // TOTAL_COUNT (uint64_t)
134 // Total number of samples in the profile.
135 // MAX_COUNT (uint64_t)
136 // Maximum value of samples on a line.
137 // MAX_FUNCTION_COUNT (uint64_t)
138 // Maximum number of samples at function entry (head samples).
139 // NUM_COUNTS (uint64_t)
140 // Number of lines with samples.
141 // NUM_FUNCTIONS (uint64_t)
142 // Number of functions with samples.
143 // NUM_DETAILED_SUMMARY_ENTRIES (size_t)
144 // Number of entries in detailed summary
145 // DETAILED_SUMMARY
146 // A list of detailed summary entry. Each entry consists of
147 // CUTOFF (uint32_t)
148 // Required percentile of total sample count expressed as a fraction
149 // multiplied by 1000000.
150 // MIN_COUNT (uint64_t)
151 // The minimum number of samples required to reach the target
152 // CUTOFF.
153 // NUM_COUNTS (uint64_t)
154 // Number of samples to get to the desrired percentile.
155 //
156 // NAME TABLE
157 // SIZE (uint32_t)
158 // Number of entries in the name table.
159 // NAMES
160 // A NUL-separated list of SIZE strings.
161 //
162 // FUNCTION BODY (one for each uninlined function body present in the profile)
163 // HEAD_SAMPLES (uint64_t) [only for top-level functions]
164 // Total number of samples collected at the head (prologue) of the
165 // function.
166 // NOTE: This field should only be present for top-level functions
167 // (i.e., not inlined into any caller). Inlined function calls
168 // have no prologue, so they don't need this.
169 // NAME_IDX (uint32_t)
170 // Index into the name table indicating the function name.
171 // SAMPLES (uint64_t)
172 // Total number of samples collected in this function.
173 // NRECS (uint32_t)
174 // Total number of sampling records this function's profile.
175 // BODY RECORDS
176 // A list of NRECS entries. Each entry contains:
177 // OFFSET (uint32_t)
178 // Line offset from the start of the function.
179 // DISCRIMINATOR (uint32_t)
180 // Discriminator value (see description of discriminators
181 // in the text format documentation above).
182 // SAMPLES (uint64_t)
183 // Number of samples collected at this location.
184 // NUM_CALLS (uint32_t)
185 // Number of non-inlined function calls made at this location. In the
186 // case of direct calls, this number will always be 1. For indirect
187 // calls (virtual functions and function pointers) this will
188 // represent all the actual functions called at runtime.
189 // CALL_TARGETS
190 // A list of NUM_CALLS entries for each called function:
191 // NAME_IDX (uint32_t)
192 // Index into the name table with the callee name.
193 // SAMPLES (uint64_t)
194 // Number of samples collected at the call site.
195 // NUM_INLINED_FUNCTIONS (uint32_t)
196 // Number of callees inlined into this function.
197 // INLINED FUNCTION RECORDS
198 // A list of NUM_INLINED_FUNCTIONS entries describing each of the inlined
199 // callees.
200 // OFFSET (uint32_t)
201 // Line offset from the start of the function.
202 // DISCRIMINATOR (uint32_t)
203 // Discriminator value (see description of discriminators
204 // in the text format documentation above).
205 // FUNCTION BODY
206 // A FUNCTION BODY entry describing the inlined function.
207 //===----------------------------------------------------------------------===//
208 #ifndef LLVM_PROFILEDATA_SAMPLEPROFREADER_H
209 #define LLVM_PROFILEDATA_SAMPLEPROFREADER_H
210 
211 #include "llvm/ADT/StringMap.h"
212 #include "llvm/ADT/StringRef.h"
213 #include "llvm/ADT/Twine.h"
214 #include "llvm/IR/DiagnosticInfo.h"
215 #include "llvm/IR/Function.h"
216 #include "llvm/IR/LLVMContext.h"
219 #include "llvm/Support/Debug.h"
221 #include "llvm/Support/ErrorOr.h"
222 #include "llvm/Support/GCOV.h"
225 
226 namespace llvm {
227 
228 namespace sampleprof {
229 
230 /// \brief Sample-based profile reader.
231 ///
232 /// Each profile contains sample counts for all the functions
233 /// executed. Inside each function, statements are annotated with the
234 /// collected samples on all the instructions associated with that
235 /// statement.
236 ///
237 /// For this to produce meaningful data, the program needs to be
238 /// compiled with some debug information (at minimum, line numbers:
239 /// -gline-tables-only). Otherwise, it will be impossible to match IR
240 /// instructions to the line numbers collected by the profiler.
241 ///
242 /// From the profile file, we are interested in collecting the
243 /// following information:
244 ///
245 /// * A list of functions included in the profile (mangled names).
246 ///
247 /// * For each function F:
248 /// 1. The total number of samples collected in F.
249 ///
250 /// 2. The samples collected at each line in F. To provide some
251 /// protection against source code shuffling, line numbers should
252 /// be relative to the start of the function.
253 ///
254 /// The reader supports two file formats: text and binary. The text format
255 /// is useful for debugging and testing, while the binary format is more
256 /// compact and I/O efficient. They can both be used interchangeably.
258 public:
259  SampleProfileReader(std::unique_ptr<MemoryBuffer> B, LLVMContext &C)
260  : Profiles(0), Ctx(C), Buffer(std::move(B)) {}
261 
262  virtual ~SampleProfileReader() {}
263 
264  /// \brief Read and validate the file header.
265  virtual std::error_code readHeader() = 0;
266 
267  /// \brief Read sample profiles from the associated file.
268  virtual std::error_code read() = 0;
269 
270  /// \brief Print the profile for \p FName on stream \p OS.
271  void dumpFunctionProfile(StringRef FName, raw_ostream &OS = dbgs());
272 
273  /// \brief Print all the profiles on stream \p OS.
274  void dump(raw_ostream &OS = dbgs());
275 
276  /// \brief Return the samples collected for function \p F.
278  return &Profiles[F.getName()];
279  }
280 
281  /// \brief Return all the profiles.
283 
284  /// \brief Report a parse error message.
285  void reportError(int64_t LineNumber, Twine Msg) const {
286  Ctx.diagnose(DiagnosticInfoSampleProfile(Buffer->getBufferIdentifier(),
287  LineNumber, Msg));
288  }
289 
290  /// \brief Create a sample profile reader appropriate to the file format.
292  create(const Twine &Filename, LLVMContext &C);
293 
294  /// \brief Create a sample profile reader from the supplied memory buffer.
296  create(std::unique_ptr<MemoryBuffer> &B, LLVMContext &C);
297 
298  /// \brief Return the profile summary.
299  ProfileSummary &getSummary() { return *(Summary.get()); }
300 
301 protected:
302  /// \brief Map every function to its associated profile.
303  ///
304  /// The profile of every function executed at runtime is collected
305  /// in the structure FunctionSamples. This maps function objects
306  /// to their corresponding profiles.
308 
309  /// \brief LLVM context used to emit diagnostics.
311 
312  /// \brief Memory buffer holding the profile file.
313  std::unique_ptr<MemoryBuffer> Buffer;
314 
315  /// \brief Profile summary information.
316  std::unique_ptr<ProfileSummary> Summary;
317 
318  /// \brief Compute summary for this profile.
319  void computeSummary();
320 };
321 
323 public:
324  SampleProfileReaderText(std::unique_ptr<MemoryBuffer> B, LLVMContext &C)
325  : SampleProfileReader(std::move(B), C) {}
326 
327  /// \brief Read and validate the file header.
328  std::error_code readHeader() override { return sampleprof_error::success; }
329 
330  /// \brief Read sample profiles from the associated file.
331  std::error_code read() override;
332 
333  /// \brief Return true if \p Buffer is in the format supported by this class.
334  static bool hasFormat(const MemoryBuffer &Buffer);
335 };
336 
338 public:
339  SampleProfileReaderBinary(std::unique_ptr<MemoryBuffer> B, LLVMContext &C)
340  : SampleProfileReader(std::move(B), C), Data(nullptr), End(nullptr) {}
341 
342  /// \brief Read and validate the file header.
343  std::error_code readHeader() override;
344 
345  /// \brief Read sample profiles from the associated file.
346  std::error_code read() override;
347 
348  /// \brief Return true if \p Buffer is in the format supported by this class.
349  static bool hasFormat(const MemoryBuffer &Buffer);
350 
351 protected:
352  /// \brief Read a numeric value of type T from the profile.
353  ///
354  /// If an error occurs during decoding, a diagnostic message is emitted and
355  /// EC is set.
356  ///
357  /// \returns the read value.
358  template <typename T> ErrorOr<T> readNumber();
359 
360  /// \brief Read a string from the profile.
361  ///
362  /// If an error occurs during decoding, a diagnostic message is emitted and
363  /// EC is set.
364  ///
365  /// \returns the read value.
367 
368  /// Read a string indirectly via the name table.
370 
371  /// \brief Return true if we've reached the end of file.
372  bool at_eof() const { return Data >= End; }
373 
374  /// Read the contents of the given profile instance.
375  std::error_code readProfile(FunctionSamples &FProfile);
376 
377  /// \brief Points to the current location in the buffer.
378  const uint8_t *Data;
379 
380  /// \brief Points to the end of the buffer.
381  const uint8_t *End;
382 
383  /// Function name table.
384  std::vector<StringRef> NameTable;
385 
386 private:
387  std::error_code readSummaryEntry(std::vector<ProfileSummaryEntry> &Entries);
388 
389  /// \brief Read profile summary.
390  std::error_code readSummary();
391 };
392 
394 
395 // Supported histogram types in GCC. Currently, we only need support for
396 // call target histograms.
397 enum HistType {
406 };
407 
409 public:
410  SampleProfileReaderGCC(std::unique_ptr<MemoryBuffer> B, LLVMContext &C)
411  : SampleProfileReader(std::move(B), C), GcovBuffer(Buffer.get()) {}
412 
413  /// \brief Read and validate the file header.
414  std::error_code readHeader() override;
415 
416  /// \brief Read sample profiles from the associated file.
417  std::error_code read() override;
418 
419  /// \brief Return true if \p Buffer is in the format supported by this class.
420  static bool hasFormat(const MemoryBuffer &Buffer);
421 
422 protected:
423  std::error_code readNameTable();
424  std::error_code readOneFunctionProfile(const InlineCallStack &InlineStack,
425  bool Update, uint32_t Offset);
426  std::error_code readFunctionProfiles();
427  std::error_code skipNextWord();
428  template <typename T> ErrorOr<T> readNumber();
430 
431  /// \brief Read the section tag and check that it's the same as \p Expected.
432  std::error_code readSectionTag(uint32_t Expected);
433 
434  /// GCOV buffer containing the profile.
436 
437  /// Function names in this profile.
438  std::vector<std::string> Names;
439 
440  /// GCOV tags used to separate sections in the profile file.
441  static const uint32_t GCOVTagAFDOFileNames = 0xaa000000;
442  static const uint32_t GCOVTagAFDOFunction = 0xac000000;
443 };
444 
445 } // End namespace sampleprof
446 
447 } // End namespace llvm
448 
449 #endif // LLVM_PROFILEDATA_SAMPLEPROFREADER_H
std::vector< std::string > Names
Function names in this profile.
std::unique_ptr< MemoryBuffer > Buffer
Memory buffer holding the profile file.
Represents either an error or a value T.
Definition: ErrorOr.h:68
std::error_code read() override
Read sample profiles from the associated file.
const uint8_t * Data
Points to the current location in the buffer.
std::error_code readHeader() override
Read and validate the file header.
static ErrorOr< std::unique_ptr< SampleProfileReader > > create(const Twine &Filename, LLVMContext &C)
Create a sample profile reader appropriate to the file format.
std::error_code read() override
Read sample profiles from the associated file.
std::error_code readProfile(FunctionSamples &FProfile)
Read the contents of the given profile instance.
GCOVBuffer - A wrapper around MemoryBuffer to provide GCOV specific read operations.
Definition: GCOV.h:64
static bool hasFormat(const MemoryBuffer &Buffer)
Return true if Buffer is in the format supported by this class.
StringRef getName() const
Return a constant reference to the value's name.
Definition: Value.cpp:191
Representation of the samples collected for a function.
Definition: SampleProf.h:181
virtual std::error_code read()=0
Read sample profiles from the associated file.
Twine - A lightweight data structure for efficiently representing the concatenation of temporary valu...
Definition: Twine.h:81
StringMap< FunctionSamples > Profiles
Map every function to its associated profile.
Tagged union holding either a T or a Error.
#define F(x, y, z)
Definition: MD5.cpp:51
SampleProfileReaderGCC(std::unique_ptr< MemoryBuffer > B, LLVMContext &C)
static bool hasFormat(const MemoryBuffer &Buffer)
Return true if Buffer is in the format supported by this class.
static GCRegistry::Add< OcamlGC > B("ocaml","ocaml 3.10-compatible GC")
SampleProfileReader(std::unique_ptr< MemoryBuffer > B, LLVMContext &C)
std::error_code readOneFunctionProfile(const InlineCallStack &InlineStack, bool Update, uint32_t Offset)
SmallVector< FunctionSamples *, 10 > InlineCallStack
void reportError(int64_t LineNumber, Twine Msg) const
Report a parse error message.
This is an important class for using LLVM in a threaded context.
Definition: LLVMContext.h:48
FunctionSamples * getSamplesFor(const Function &F)
Return the samples collected for function F.
ErrorOr< T > readNumber()
Read a numeric value of type T from the profile.
LLVMContext & Ctx
LLVM context used to emit diagnostics.
uint32_t Offset
ErrorOr< StringRef > readString()
Read a string from the profile.
void dumpFunctionProfile(StringRef FName, raw_ostream &OS=dbgs())
Print the profile for FName on stream OS.
bool at_eof() const
Return true if we've reached the end of file.
virtual std::error_code readHeader()=0
Read and validate the file header.
This is a 'vector' (really, a variable-sized array), optimized for the case when the array is small...
Definition: SmallVector.h:843
std::vector< StringRef > NameTable
Function name table.
static GCRegistry::Add< ShadowStackGC > C("shadow-stack","Very portable GC for uncooperative code generators")
This interface provides simple read-only access to a block of memory, and provides simple methods for...
Definition: MemoryBuffer.h:40
raw_ostream & dbgs()
dbgs() - This returns a reference to a raw_ostream for debugging messages.
Definition: Debug.cpp:132
StringMap - This is an unconventional map that is specialized for handling keys that are "strings"...
Definition: StringMap.h:223
static const uint32_t GCOVTagAFDOFileNames
GCOV tags used to separate sections in the profile file.
StringMap< FunctionSamples > & getProfiles()
Return all the profiles.
static bool hasFormat(const MemoryBuffer &Buffer)
Return true if Buffer is in the format supported by this class.
SampleProfileReaderBinary(std::unique_ptr< MemoryBuffer > B, LLVMContext &C)
const uint8_t * End
Points to the end of the buffer.
std::error_code readHeader() override
Read and validate the file header.
void diagnose(const DiagnosticInfo &DI)
Report a message to the currently installed diagnostic handler.
Provides ErrorOr<T> smart pointer.
std::error_code readSectionTag(uint32_t Expected)
Read the section tag and check that it's the same as Expected.
SampleProfileReaderText(std::unique_ptr< MemoryBuffer > B, LLVMContext &C)
Sample-based profile reader.
This class implements an extremely fast bulk output stream that can only output to a stream...
Definition: raw_ostream.h:44
ErrorOr< StringRef > readStringFromTable()
Read a string indirectly via the name table.
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:47
GCOVBuffer GcovBuffer
GCOV buffer containing the profile.
Diagnostic information for the sample profiler.
std::error_code readHeader() override
Read and validate the file header.
void computeSummary()
Compute summary for this profile.
void dump(raw_ostream &OS=dbgs())
Print all the profiles on stream OS.
std::error_code read() override
Read sample profiles from the associated file.
ProfileSummary & getSummary()
Return the profile summary.
std::unique_ptr< ProfileSummary > Summary
Profile summary information.