1 /*===- InstrProfiling.h- Support library for PGO instrumentation ----------===*\
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 #ifndef PROFILE_INSTRPROFILING_H_
11 #define PROFILE_INSTRPROFILING_H_
13 #include "InstrProfilingPort.h"
15 #define INSTR_PROF_VISIBILITY COMPILER_RT_VISIBILITY
16 #include "InstrProfData.inc"
19 #define VALUE_PROF_KIND(Enumerator, Value) Enumerator = Value,
20 #include "InstrProfData.inc"
23 typedef void *IntPtrT;
24 typedef struct COMPILER_RT_ALIGNAS(INSTR_PROF_DATA_ALIGNMENT)
26 #define INSTR_PROF_DATA(Type, LLVMType, Name, Initializer) Type Name;
27 #include "InstrProfData.inc"
28 } __llvm_profile_data;
30 typedef struct __llvm_profile_header {
31 #define INSTR_PROF_RAW_HEADER(Type, Name, Initializer) Type Name;
32 #include "InstrProfData.inc"
33 } __llvm_profile_header;
35 typedef struct ValueProfNode * PtrToNodeT;
36 typedef struct ValueProfNode {
37 #define INSTR_PROF_VALUE_NODE(Type, LLVMType, Name, Initializer) Type Name;
38 #include "InstrProfData.inc"
42 * \brief Get number of bytes necessary to pad the argument to eight
45 uint8_t __llvm_profile_get_num_padding_bytes(uint64_t SizeInBytes);
48 * \brief Get required size for profile buffer.
50 uint64_t __llvm_profile_get_size_for_buffer(void);
53 * \brief Write instrumentation data to the given buffer.
55 * \pre \c Buffer is the start of a buffer at least as big as \a
56 * __llvm_profile_get_size_for_buffer().
58 int __llvm_profile_write_buffer(char *Buffer);
60 const __llvm_profile_data *__llvm_profile_begin_data(void);
61 const __llvm_profile_data *__llvm_profile_end_data(void);
62 const char *__llvm_profile_begin_names(void);
63 const char *__llvm_profile_end_names(void);
64 uint64_t *__llvm_profile_begin_counters(void);
65 uint64_t *__llvm_profile_end_counters(void);
66 ValueProfNode *__llvm_profile_begin_vnodes();
67 ValueProfNode *__llvm_profile_end_vnodes();
70 * \brief Clear profile counters to zero.
73 void __llvm_profile_reset_counters(void);
76 * \brief Merge profile data from buffer.
78 * Read profile data form buffer \p Profile and merge with
79 * in-process profile counters. The client is expected to
80 * have checked or already knows the profile data in the
81 * buffer matches the in-process counter structure before
84 void __llvm_profile_merge_from_buffer(const char *Profile, uint64_t Size);
86 /*! \brief Check if profile in buffer matches the current binary.
88 * Returns 0 (success) if the profile data in buffer \p Profile with size
89 * \p Size was generated by the same binary and therefore matches
90 * structurally the in-process counters. If the profile data in buffer is
91 * not compatible, the interface returns 1 (failure).
93 int __llvm_profile_check_compatibility(const char *Profile,
97 * \brief Counts the number of times a target value is seen.
99 * Records the target value for the CounterIndex if not seen before. Otherwise,
100 * increments the counter associated w/ the target value.
101 * void __llvm_profile_instrument_target(uint64_t TargetValue, void *Data,
102 * uint32_t CounterIndex);
104 void INSTR_PROF_VALUE_PROF_FUNC(
105 #define VALUE_PROF_FUNC_PARAM(ArgType, ArgName, ArgLLVMType) ArgType ArgName
106 #include "InstrProfData.inc"
109 void __llvm_profile_instrument_target_value(uint64_t TargetValue, void *Data,
110 uint32_t CounterIndex,
111 uint64_t CounterValue);
114 * \brief Write instrumentation data to the current file.
116 * Writes to the file with the last name given to \a *
117 * __llvm_profile_set_filename(),
118 * or if it hasn't been called, the \c LLVM_PROFILE_FILE environment variable,
119 * or if that's not set, the last name set to INSTR_PROF_PROFILE_NAME_VAR,
120 * or if that's not set, \c "default.profraw".
122 int __llvm_profile_write_file(void);
125 * \brief this is a wrapper interface to \c __llvm_profile_write_file.
126 * After this interface is invoked, a arleady dumped flag will be set
127 * so that profile won't be dumped again during program exit.
128 * Invocation of interface __llvm_profile_reset_counters will clear
129 * the flag. This interface is designed to be used to collect profile
130 * data from user selected hot regions. The use model is
131 * __llvm_profile_reset_counters();
133 * __llvm_profile_dump();
135 * __llvm_profile_reset_counters();
137 * __llvm_profile_dump();
139 * It is expected that on-line profile merging is on with \c %m specifier
140 * used in profile filename . If merging is not turned on, user is expected
141 * to invoke __llvm_profile_set_filename to specify different profile names
142 * for different regions before dumping to avoid profile write clobbering.
144 int __llvm_profile_dump(void);
147 * \brief Set the filename for writing instrumentation data.
149 * Sets the filename to be used for subsequent calls to
150 * \a __llvm_profile_write_file().
152 * \c Name is not copied, so it must remain valid. Passing NULL resets the
153 * filename logic to the default behaviour.
155 void __llvm_profile_set_filename(const char *Name);
157 /*! \brief Register to write instrumentation data to file at exit. */
158 int __llvm_profile_register_write_file_atexit(void);
160 /*! \brief Initialize file handling. */
161 void __llvm_profile_initialize_file(void);
164 * \brief Return path prefix (excluding the base filename) of the profile data.
165 * This is useful for users using \c -fprofile-generate=./path_prefix who do
166 * not care about the default raw profile name. It is also useful to collect
167 * more than more profile data files dumped in the same directory (Online
168 * merge mode is turned on for instrumented programs with shared libs).
169 * Side-effect: this API call will invoke malloc with dynamic memory allocation.
171 const char *__llvm_profile_get_path_prefix();
174 * \brief Return filename (including path) of the profile data. Note that if the
175 * user calls __llvm_profile_set_filename later after invoking this interface,
176 * the actual file name may differ from what is returned here.
177 * Side-effect: this API call will invoke malloc with dynamic memory allocation.
179 const char *__llvm_profile_get_filename();
181 /*! \brief Get the magic token for the file format. */
182 uint64_t __llvm_profile_get_magic(void);
184 /*! \brief Get the version of the file format. */
185 uint64_t __llvm_profile_get_version(void);
187 /*! \brief Get the number of entries in the profile data section. */
188 uint64_t __llvm_profile_get_data_size(const __llvm_profile_data *Begin,
189 const __llvm_profile_data *End);
192 * This variable is defined in InstrProfilingRuntime.cc as a hidden
193 * symbol. Its main purpose is to enable profile runtime user to
194 * bypass runtime initialization code -- if the client code explicitly
195 * define this variable, then InstProfileRuntime.o won't be linked in.
196 * Note that this variable's visibility needs to be hidden so that the
197 * definition of this variable in an instrumented shared library won't
198 * affect runtime initialization decision of the main program.
199 * __llvm_profile_profile_runtime. */
200 COMPILER_RT_VISIBILITY extern int INSTR_PROF_PROFILE_RUNTIME_VAR;
203 * This variable is defined in InstrProfiling.c. Its main purpose is to
204 * encode the raw profile version value and other format related information
205 * such as whether the profile is from IR based instrumentation. The variable
206 * is defined as weak so that compiler can emit an overriding definition
207 * depending on user option. Since we don't support mixing FE and IR based
208 * data in the same raw profile data file (in other words, shared libs and
209 * main program are expected to be instrumented in the same way), there is
210 * no need for this variable to be hidden.
212 extern uint64_t INSTR_PROF_RAW_VERSION_VAR; /* __llvm_profile_raw_version */
215 * This variable is a weak symbol defined in InstrProfiling.c. It allows
216 * compiler instrumentation to provide overriding definition with value
217 * from compiler command line. This variable has default visibility.
219 extern char INSTR_PROF_PROFILE_NAME_VAR[1]; /* __llvm_profile_filename. */
221 #endif /* PROFILE_INSTRPROFILING_H_ */