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