1/*===- InstrProfiling.h- Support library for PGO instrumentation ----------===*\
2|*
3|* Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4|* See https://llvm.org/LICENSE.txt for license information.
5|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6|*
7\*===----------------------------------------------------------------------===*/
8
9#ifndef PROFILE_INSTRPROFILING_H_
10#define PROFILE_INSTRPROFILING_H_
11
12#include "InstrProfilingPort.h"
13#include <stdio.h>
14
15#define INSTR_PROF_VISIBILITY COMPILER_RT_VISIBILITY
16#include "profile/InstrProfData.inc"
17
18enum ValueKind {
19#define VALUE_PROF_KIND(Enumerator, Value, Descr) Enumerator = Value,
20#include "profile/InstrProfData.inc"
21};
22
23typedef void *IntPtrT;
24typedef struct COMPILER_RT_ALIGNAS(INSTR_PROF_DATA_ALIGNMENT)
25    __llvm_profile_data {
26#define INSTR_PROF_DATA(Type, LLVMType, Name, Initializer) Type Name;
27#include "profile/InstrProfData.inc"
28} __llvm_profile_data;
29
30typedef struct __llvm_profile_header {
31#define INSTR_PROF_RAW_HEADER(Type, Name, Initializer) Type Name;
32#include "profile/InstrProfData.inc"
33} __llvm_profile_header;
34
35typedef struct ValueProfNode * PtrToNodeT;
36typedef struct ValueProfNode {
37#define INSTR_PROF_VALUE_NODE(Type, LLVMType, Name, Initializer) Type Name;
38#include "profile/InstrProfData.inc"
39} ValueProfNode;
40
41/*!
42 * \brief Return 1 if profile counters are continuously synced to the raw
43 * profile via an mmap(). This is in contrast to the default mode, in which
44 * the raw profile is written out at program exit time.
45 */
46int __llvm_profile_is_continuous_mode_enabled(void);
47
48/*!
49 * \brief Enable continuous mode.
50 *
51 * See \ref __llvm_profile_is_continuous_mode_enabled. The behavior is undefined
52 * if continuous mode is already enabled, or if it cannot be enable due to
53 * conflicting options.
54 */
55void __llvm_profile_enable_continuous_mode(void);
56
57/*!
58 * \brief Get number of bytes necessary to pad the argument to eight
59 * byte boundary.
60 */
61uint8_t __llvm_profile_get_num_padding_bytes(uint64_t SizeInBytes);
62
63/*!
64 * \brief Get required size for profile buffer.
65 */
66uint64_t __llvm_profile_get_size_for_buffer(void);
67
68/*!
69 * \brief Write instrumentation data to the given buffer.
70 *
71 * \pre \c Buffer is the start of a buffer at least as big as \a
72 * __llvm_profile_get_size_for_buffer().
73 */
74int __llvm_profile_write_buffer(char *Buffer);
75
76const __llvm_profile_data *__llvm_profile_begin_data(void);
77const __llvm_profile_data *__llvm_profile_end_data(void);
78const char *__llvm_profile_begin_names(void);
79const char *__llvm_profile_end_names(void);
80uint64_t *__llvm_profile_begin_counters(void);
81uint64_t *__llvm_profile_end_counters(void);
82ValueProfNode *__llvm_profile_begin_vnodes();
83ValueProfNode *__llvm_profile_end_vnodes();
84uint32_t *__llvm_profile_begin_orderfile();
85
86/*!
87 * \brief Clear profile counters to zero.
88 *
89 */
90void __llvm_profile_reset_counters(void);
91
92/*!
93 * \brief Merge profile data from buffer.
94 *
95 * Read profile data form buffer \p Profile  and merge with
96 * in-process profile counters. The client is expected to
97 * have checked or already knows the profile data in the
98 * buffer matches the in-process counter structure before
99 * calling it.
100 */
101void __llvm_profile_merge_from_buffer(const char *Profile, uint64_t Size);
102
103/*! \brief Check if profile in buffer matches the current binary.
104 *
105 *  Returns 0 (success) if the profile data in buffer \p Profile with size
106 *  \p Size was generated by the same binary and therefore matches
107 *  structurally the in-process counters. If the profile data in buffer is
108 *  not compatible, the interface returns 1 (failure).
109 */
110int __llvm_profile_check_compatibility(const char *Profile,
111                                       uint64_t Size);
112
113/*!
114 * \brief Counts the number of times a target value is seen.
115 *
116 * Records the target value for the CounterIndex if not seen before. Otherwise,
117 * increments the counter associated w/ the target value.
118 * void __llvm_profile_instrument_target(uint64_t TargetValue, void *Data,
119 *                                       uint32_t CounterIndex);
120 */
121void INSTR_PROF_VALUE_PROF_FUNC(
122#define VALUE_PROF_FUNC_PARAM(ArgType, ArgName, ArgLLVMType) ArgType ArgName
123#include "profile/InstrProfData.inc"
124    );
125
126void __llvm_profile_instrument_target_value(uint64_t TargetValue, void *Data,
127                                            uint32_t CounterIndex,
128                                            uint64_t CounterValue);
129
130/*!
131 * \brief Write instrumentation data to the current file.
132 *
133 * Writes to the file with the last name given to \a *
134 * __llvm_profile_set_filename(),
135 * or if it hasn't been called, the \c LLVM_PROFILE_FILE environment variable,
136 * or if that's not set, the last name set to INSTR_PROF_PROFILE_NAME_VAR,
137 * or if that's not set,  \c "default.profraw".
138 */
139int __llvm_profile_write_file(void);
140
141int __llvm_orderfile_write_file(void);
142/*!
143 * \brief this is a wrapper interface to \c __llvm_profile_write_file.
144 * After this interface is invoked, a arleady dumped flag will be set
145 * so that profile won't be dumped again during program exit.
146 * Invocation of interface __llvm_profile_reset_counters will clear
147 * the flag. This interface is designed to be used to collect profile
148 * data from user selected hot regions. The use model is
149 *      __llvm_profile_reset_counters();
150 *      ... hot region 1
151 *      __llvm_profile_dump();
152 *      .. some other code
153 *      __llvm_profile_reset_counters();
154 *       ... hot region 2
155 *      __llvm_profile_dump();
156 *
157 *  It is expected that on-line profile merging is on with \c %m specifier
158 *  used in profile filename . If merging is  not turned on, user is expected
159 *  to invoke __llvm_profile_set_filename  to specify different profile names
160 *  for different regions before dumping to avoid profile write clobbering.
161 */
162int __llvm_profile_dump(void);
163
164int __llvm_orderfile_dump(void);
165
166/*!
167 * \brief Set the filename for writing instrumentation data.
168 *
169 * Sets the filename to be used for subsequent calls to
170 * \a __llvm_profile_write_file().
171 *
172 * \c Name is not copied, so it must remain valid.  Passing NULL resets the
173 * filename logic to the default behaviour.
174 *
175 * Note: There may be multiple copies of the profile runtime (one for each
176 * instrumented image/DSO). This API only modifies the filename within the
177 * copy of the runtime available to the calling image.
178 *
179 * Warning: This is a no-op if continuous mode (\ref
180 * __llvm_profile_is_continuous_mode_enabled) is on. The reason for this is
181 * that in continuous mode, profile counters are mmap()'d to the profile at
182 * program initialization time. Support for transferring the mmap'd profile
183 * counts to a new file has not been implemented.
184 */
185void __llvm_profile_set_filename(const char *Name);
186
187/*!
188 * \brief Set the FILE object for writing instrumentation data.
189 *
190 * Sets the FILE object to be used for subsequent calls to
191 * \a __llvm_profile_write_file(). The profile file name set by environment
192 * variable, command-line option, or calls to \a  __llvm_profile_set_filename
193 * will be ignored.
194 *
195 * \c File will not be closed after a call to \a __llvm_profile_write_file() but
196 * it may be flushed. Passing NULL restores default behavior.
197 *
198 * If \c EnableMerge is nonzero, the runtime will always merge profiling data
199 * with the contents of the profiling file. If EnableMerge is zero, the runtime
200 * may still merge the data if it would have merged for another reason (for
201 * example, because of a %m specifier in the file name).
202 *
203 * Note: There may be multiple copies of the profile runtime (one for each
204 * instrumented image/DSO). This API only modifies the file object within the
205 * copy of the runtime available to the calling image.
206 *
207 * Warning: This is a no-op if continuous mode (\ref
208 * __llvm_profile_is_continuous_mode_enabled) is on. The reason for this is
209 * that in continuous mode, profile counters are mmap()'d to the profile at
210 * program initialization time. Support for transferring the mmap'd profile
211 * counts to a new file has not been implemented.
212 */
213void __llvm_profile_set_file_object(FILE *File, int EnableMerge);
214
215/*! \brief Register to write instrumentation data to file at exit. */
216int __llvm_profile_register_write_file_atexit(void);
217
218/*! \brief Initialize file handling. */
219void __llvm_profile_initialize_file(void);
220
221/*!
222 * \brief Return path prefix (excluding the base filename) of the profile data.
223 * This is useful for users using \c -fprofile-generate=./path_prefix who do
224 * not care about the default raw profile name. It is also useful to collect
225 * more than more profile data files dumped in the same directory (Online
226 * merge mode is turned on for instrumented programs with shared libs).
227 * Side-effect: this API call will invoke malloc with dynamic memory allocation.
228 */
229const char *__llvm_profile_get_path_prefix();
230
231/*!
232 * \brief Return filename (including path) of the profile data. Note that if the
233 * user calls __llvm_profile_set_filename later after invoking this interface,
234 * the actual file name may differ from what is returned here.
235 * Side-effect: this API call will invoke malloc with dynamic memory allocation
236 * (the returned pointer must be passed to `free` to avoid a leak).
237 *
238 * Note: There may be multiple copies of the profile runtime (one for each
239 * instrumented image/DSO). This API only retrieves the filename from the copy
240 * of the runtime available to the calling image.
241 */
242const char *__llvm_profile_get_filename();
243
244/*! \brief Get the magic token for the file format. */
245uint64_t __llvm_profile_get_magic(void);
246
247/*! \brief Get the version of the file format. */
248uint64_t __llvm_profile_get_version(void);
249
250/*! \brief Get the number of entries in the profile data section. */
251uint64_t __llvm_profile_get_data_size(const __llvm_profile_data *Begin,
252                                      const __llvm_profile_data *End);
253
254/* ! \brief Given the sizes of the data and counter information, return the
255 * number of padding bytes before and after the counters, and after the names,
256 * in the raw profile.
257 *
258 * Note: In this context, "size" means "number of entries", i.e. the first two
259 * arguments must be the result of __llvm_profile_get_data_size() and of
260 * (__llvm_profile_end_counters() - __llvm_profile_begin_counters()) resp.
261 *
262 * Note: When mmap() mode is disabled, no padding bytes before/after counters
263 * are needed. However, in mmap() mode, the counter section in the raw profile
264 * must be page-aligned: this API computes the number of padding bytes
265 * needed to achieve that.
266 */
267void __llvm_profile_get_padding_sizes_for_counters(
268    uint64_t DataSize, uint64_t CountersSize, uint64_t NamesSize,
269    uint64_t *PaddingBytesBeforeCounters, uint64_t *PaddingBytesAfterCounters,
270    uint64_t *PaddingBytesAfterNames);
271
272/*!
273 * \brief Set the flag that profile data has been dumped to the file.
274 * This is useful for users to disable dumping profile data to the file for
275 * certain processes in case the processes don't have permission to write to
276 * the disks, and trying to do so would result in side effects such as crashes.
277 */
278void __llvm_profile_set_dumped();
279
280/*!
281 * This variable is defined in InstrProfilingRuntime.cpp as a hidden
282 * symbol. Its main purpose is to enable profile runtime user to
283 * bypass runtime initialization code -- if the client code explicitly
284 * define this variable, then InstProfileRuntime.o won't be linked in.
285 * Note that this variable's visibility needs to be hidden so that the
286 * definition of this variable in an instrumented shared library won't
287 * affect runtime initialization decision of the main program.
288 *  __llvm_profile_profile_runtime. */
289COMPILER_RT_VISIBILITY extern int INSTR_PROF_PROFILE_RUNTIME_VAR;
290
291/*!
292 * This variable is defined in InstrProfiling.c. Its main purpose is to
293 * encode the raw profile version value and other format related information
294 * such as whether the profile is from IR based instrumentation. The variable
295 * is defined as weak so that compiler can emit an overriding definition
296 * depending on user option.  Since we don't support mixing FE and IR based
297 * data in the same raw profile data file (in other words, shared libs and
298 * main program are expected to be instrumented in the same way), there is
299 * no need for this variable to be hidden.
300 */
301extern uint64_t INSTR_PROF_RAW_VERSION_VAR; /* __llvm_profile_raw_version */
302
303/*!
304 * This variable is a weak symbol defined in InstrProfiling.c. It allows
305 * compiler instrumentation to provide overriding definition with value
306 * from compiler command line. This variable has default visibility.
307 */
308extern char INSTR_PROF_PROFILE_NAME_VAR[1]; /* __llvm_profile_filename. */
309
310#endif /* PROFILE_INSTRPROFILING_H_ */
311