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// Make sure __LLVM_INSTR_PROFILE_GENERATE is always defined before
16// including instr_prof_interface.h so the interface functions are
17// declared correctly for the runtime.
18// __LLVM_INSTR_PROFILE_GENERATE is always `#undef`ed after the header,
19// because compiler-rt does not support profiling the profiling runtime itself.
20#ifndef __LLVM_INSTR_PROFILE_GENERATE
21#define __LLVM_INSTR_PROFILE_GENERATE
22#endif
23#include "profile/instr_prof_interface.h"
24#undef __LLVM_INSTR_PROFILE_GENERATE
25
26#define INSTR_PROF_VISIBILITY COMPILER_RT_VISIBILITY
27#include "profile/InstrProfData.inc"
28
29enum ValueKind {
30#define VALUE_PROF_KIND(Enumerator, Value, Descr) Enumerator = Value,
31#include "profile/InstrProfData.inc"
32};
33
34typedef void *IntPtrT;
35typedef struct COMPILER_RT_ALIGNAS(INSTR_PROF_DATA_ALIGNMENT)
36 __llvm_profile_data {
37#define INSTR_PROF_DATA(Type, LLVMType, Name, Initializer) Type Name;
38#include "profile/InstrProfData.inc"
39} __llvm_profile_data;
40
41typedef struct __llvm_profile_header {
42#define INSTR_PROF_RAW_HEADER(Type, Name, Initializer) Type Name;
43#include "profile/InstrProfData.inc"
44} __llvm_profile_header;
45
46typedef struct ValueProfNode * PtrToNodeT;
47typedef struct ValueProfNode {
48#define INSTR_PROF_VALUE_NODE(Type, LLVMType, Name, Initializer) Type Name;
49#include "profile/InstrProfData.inc"
50} ValueProfNode;
51
52typedef void *IntPtrT;
53typedef struct COMPILER_RT_ALIGNAS(INSTR_PROF_DATA_ALIGNMENT) VTableProfData {
54#define INSTR_PROF_VTABLE_DATA(Type, LLVMType, Name, Initializer) Type Name;
55#include "profile/InstrProfData.inc"
56} VTableProfData;
57
58/*!
59 * \brief Return 1 if profile counters are continuously synced to the raw
60 * profile via an mmap(). This is in contrast to the default mode, in which
61 * the raw profile is written out at program exit time.
62 */
63int __llvm_profile_is_continuous_mode_enabled(void);
64
65/*!
66 * \brief Enable continuous mode.
67 *
68 * See \ref __llvm_profile_is_continuous_mode_enabled. The behavior is undefined
69 * if continuous mode is already enabled, or if it cannot be enable due to
70 * conflicting options.
71 */
72void __llvm_profile_enable_continuous_mode(void);
73
74/*!
75 * \brief Disable continuous mode.
76 *
77 */
78void __llvm_profile_disable_continuous_mode(void);
79
80/*!
81 * \brief Set the page size.
82 *
83 * This is a pre-requisite for enabling continuous mode. The buffer size
84 * calculation code inside of libprofile cannot simply call getpagesize(), as
85 * it is not allowed to depend on libc.
86 */
87void __llvm_profile_set_page_size(unsigned PageSize);
88
89/*!
90 * \brief Get number of bytes necessary to pad the argument to eight
91 * byte boundary.
92 */
93uint8_t __llvm_profile_get_num_padding_bytes(uint64_t SizeInBytes);
94
95/*!
96 * \brief Get required size for profile buffer.
97 */
98uint64_t __llvm_profile_get_size_for_buffer(void);
99
100/*!
101 * \brief Write instrumentation data to the given buffer.
102 *
103 * \pre \c Buffer is the start of a buffer at least as big as \a
104 * __llvm_profile_get_size_for_buffer().
105 */
106int __llvm_profile_write_buffer(char *Buffer);
107
108const __llvm_profile_data *__llvm_profile_begin_data(void);
109const __llvm_profile_data *__llvm_profile_end_data(void);
110const char *__llvm_profile_begin_names(void);
111const char *__llvm_profile_end_names(void);
112const char *__llvm_profile_begin_vtabnames(void);
113const char *__llvm_profile_end_vtabnames(void);
114char *__llvm_profile_begin_counters(void);
115char *__llvm_profile_end_counters(void);
116char *__llvm_profile_begin_bitmap(void);
117char *__llvm_profile_end_bitmap(void);
118ValueProfNode *__llvm_profile_begin_vnodes();
119ValueProfNode *__llvm_profile_end_vnodes();
120const VTableProfData *__llvm_profile_begin_vtables();
121const VTableProfData *__llvm_profile_end_vtables();
122uint32_t *__llvm_profile_begin_orderfile();
123
124/*!
125 * \brief Merge profile data from buffer.
126 *
127 * Read profile data from buffer \p Profile and merge with in-process profile
128 * counters and bitmaps. The client is expected to have checked or already
129 * know the profile data in the buffer matches the in-process counter
130 * structure before calling it. Returns 0 (success) if the profile data is
131 * valid. Upon reading invalid/corrupted profile data, returns 1 (failure).
132 */
133int __llvm_profile_merge_from_buffer(const char *Profile, uint64_t Size);
134
135/*! \brief Check if profile in buffer matches the current binary.
136 *
137 * Returns 0 (success) if the profile data in buffer \p Profile with size
138 * \p Size was generated by the same binary and therefore matches
139 * structurally the in-process counters and bitmaps. If the profile data in
140 * buffer is not compatible, the interface returns 1 (failure).
141 */
142int __llvm_profile_check_compatibility(const char *Profile,
143 uint64_t Size);
144
145/*!
146 * \brief Counts the number of times a target value is seen.
147 *
148 * Records the target value for the CounterIndex if not seen before. Otherwise,
149 * increments the counter associated w/ the target value.
150 * void __llvm_profile_instrument_target(uint64_t TargetValue, void *Data,
151 * uint32_t CounterIndex);
152 */
153void INSTR_PROF_VALUE_PROF_FUNC(
154#define VALUE_PROF_FUNC_PARAM(ArgType, ArgName, ArgLLVMType) ArgType ArgName
155#include "profile/InstrProfData.inc"
156 );
157
158void __llvm_profile_instrument_target_value(uint64_t TargetValue, void *Data,
159 uint32_t CounterIndex,
160 uint64_t CounterValue);
161
162/*!
163 * \brief Write instrumentation data to the current file.
164 *
165 * Writes to the file with the last name given to \a *
166 * __llvm_profile_set_filename(),
167 * or if it hasn't been called, the \c LLVM_PROFILE_FILE environment variable,
168 * or if that's not set, the last name set to INSTR_PROF_PROFILE_NAME_VAR,
169 * or if that's not set, \c "default.profraw".
170 */
171int __llvm_profile_write_file(void);
172
173int __llvm_orderfile_write_file(void);
174
175/*!
176 * \brief Set the FILE object for writing instrumentation data. Return 0 if set
177 * successfully or return 1 if failed.
178 *
179 * Sets the FILE object to be used for subsequent calls to
180 * \a __llvm_profile_write_file(). The profile file name set by environment
181 * variable, command-line option, or calls to \a __llvm_profile_set_filename
182 * will be ignored.
183 *
184 * \c File will not be closed after a call to \a __llvm_profile_write_file() but
185 * it may be flushed. Passing NULL restores default behavior.
186 *
187 * If \c EnableMerge is nonzero, the runtime will always merge profiling data
188 * with the contents of the profiling file. If EnableMerge is zero, the runtime
189 * may still merge the data if it would have merged for another reason (for
190 * example, because of a %m specifier in the file name).
191 *
192 * Note: There may be multiple copies of the profile runtime (one for each
193 * instrumented image/DSO). This API only modifies the file object within the
194 * copy of the runtime available to the calling image.
195 *
196 * Warning: This is a no-op if EnableMerge is 0 in continuous mode (\ref
197 * __llvm_profile_is_continuous_mode_enabled), because disable merging requires
198 * copying the old profile file to new profile file and this function is usually
199 * used when the proess doesn't have permission to open file.
200 */
201int __llvm_profile_set_file_object(FILE *File, int EnableMerge);
202
203/*! \brief Register to write instrumentation data to file at exit. */
204int __llvm_profile_register_write_file_atexit(void);
205
206/*! \brief Initialize file handling. */
207void __llvm_profile_initialize_file(void);
208
209/*! \brief Initialize the profile runtime. */
210void __llvm_profile_initialize(void);
211
212/*!
213 * \brief Return path prefix (excluding the base filename) of the profile data.
214 * This is useful for users using \c -fprofile-generate=./path_prefix who do
215 * not care about the default raw profile name. It is also useful to collect
216 * more than more profile data files dumped in the same directory (Online
217 * merge mode is turned on for instrumented programs with shared libs).
218 * Side-effect: this API call will invoke malloc with dynamic memory allocation.
219 */
220const char *__llvm_profile_get_path_prefix();
221
222/*!
223 * \brief Return filename (including path) of the profile data. Note that if the
224 * user calls __llvm_profile_set_filename later after invoking this interface,
225 * the actual file name may differ from what is returned here.
226 * Side-effect: this API call will invoke malloc with dynamic memory allocation
227 * (the returned pointer must be passed to `free` to avoid a leak).
228 *
229 * Note: There may be multiple copies of the profile runtime (one for each
230 * instrumented image/DSO). This API only retrieves the filename from the copy
231 * of the runtime available to the calling image.
232 */
233const char *__llvm_profile_get_filename();
234
235/*! \brief Get the magic token for the file format. */
236uint64_t __llvm_profile_get_magic(void);
237
238/*! \brief Get the version of the file format. */
239uint64_t __llvm_profile_get_version(void);
240
241/*! \brief Get the number of entries in the profile data section. */
242uint64_t __llvm_profile_get_num_data(const __llvm_profile_data *Begin,
243 const __llvm_profile_data *End);
244
245/*! \brief Get the size of the profile data section in bytes. */
246uint64_t __llvm_profile_get_data_size(const __llvm_profile_data *Begin,
247 const __llvm_profile_data *End);
248
249/*! \brief Get the size in bytes of a single counter entry. */
250size_t __llvm_profile_counter_entry_size(void);
251
252/*! \brief Get the number of entries in the profile counters section. */
253uint64_t __llvm_profile_get_num_counters(const char *Begin, const char *End);
254
255/*! \brief Get the size of the profile counters section in bytes. */
256uint64_t __llvm_profile_get_counters_size(const char *Begin, const char *End);
257
258/*! \brief Get the number of bytes in the profile bitmap section. */
259uint64_t __llvm_profile_get_num_bitmap_bytes(const char *Begin,
260 const char *End);
261
262/*! \brief Get the size of the profile name section in bytes. */
263uint64_t __llvm_profile_get_name_size(const char *Begin, const char *End);
264
265/*! \brief Get the number of virtual table profile data entries */
266uint64_t __llvm_profile_get_num_vtable(const VTableProfData *Begin,
267 const VTableProfData *End);
268
269/*! \brief Get the size of virtual table profile data in bytes. */
270uint64_t __llvm_profile_get_vtable_section_size(const VTableProfData *Begin,
271 const VTableProfData *End);
272
273/* ! \brief Given the sizes of the data and counter information, computes the
274 * number of padding bytes before and after the counter section, as well as the
275 * number of padding bytes after other setions in the raw profile.
276 * Returns -1 upon errors and 0 upon success. Output parameters should be used
277 * iff return value is 0.
278 *
279 * Note: When mmap() mode is disabled, no padding bytes before/after counters
280 * are needed. However, in mmap() mode, the counter section in the raw profile
281 * must be page-aligned: this API computes the number of padding bytes
282 * needed to achieve that.
283 */
284int __llvm_profile_get_padding_sizes_for_counters(
285 uint64_t DataSize, uint64_t CountersSize, uint64_t NumBitmapBytes,
286 uint64_t NamesSize, uint64_t VTableSize, uint64_t VNameSize,
287 uint64_t *PaddingBytesBeforeCounters, uint64_t *PaddingBytesAfterCounters,
288 uint64_t *PaddingBytesAfterBitmap, uint64_t *PaddingBytesAfterNames,
289 uint64_t *PaddingBytesAfterVTable, uint64_t *PaddingBytesAfterVNames);
290
291/*!
292 * \brief Set the flag that profile data has been dumped to the file.
293 * This is useful for users to disable dumping profile data to the file for
294 * certain processes in case the processes don't have permission to write to
295 * the disks, and trying to do so would result in side effects such as crashes.
296 */
297void __llvm_profile_set_dumped();
298
299/*!
300 * This variable is defined in InstrProfilingRuntime.cpp as a hidden
301 * symbol. Its main purpose is to enable profile runtime user to
302 * bypass runtime initialization code -- if the client code explicitly
303 * define this variable, then InstProfileRuntime.o won't be linked in.
304 * Note that this variable's visibility needs to be hidden so that the
305 * definition of this variable in an instrumented shared library won't
306 * affect runtime initialization decision of the main program.
307 * __llvm_profile_profile_runtime. */
308COMPILER_RT_VISIBILITY extern int INSTR_PROF_PROFILE_RUNTIME_VAR;
309
310/*!
311 * This variable is defined in InstrProfilingVersionVar.c as a hidden symbol
312 * (except on Apple platforms where this symbol is checked by TAPI). Its main
313 * purpose is to encode the raw profile version value and other format related
314 * information such as whether the profile is from IR based instrumentation. The
315 * variable is defined as weak so that compiler can emit an overriding
316 * definition depending on user option.
317 */
318COMPILER_RT_VISIBILITY extern uint64_t
319 INSTR_PROF_RAW_VERSION_VAR; /* __llvm_profile_raw_version */
320
321/*!
322 * This variable is a weak symbol defined in InstrProfiling.c. It allows
323 * compiler instrumentation to provide overriding definition with value
324 * from compiler command line. This variable has default visibility.
325 */
326extern char INSTR_PROF_PROFILE_NAME_VAR[1]; /* __llvm_profile_filename. */
327
328#endif /* PROFILE_INSTRPROFILING_H_ */
329

source code of compiler-rt/lib/profile/InstrProfiling.h