1/*===---- instr_prof_interface.h - Instrumentation PGO User Program API ----===
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 * This header provides a public interface for fine-grained control of counter
10 * reset and profile dumping. These interface functions can be directly called
11 * in user programs.
12 *
13\*===---------------------------------------------------------------------===*/
14
15#ifndef COMPILER_RT_INSTR_PROFILING
16#define COMPILER_RT_INSTR_PROFILING
17
18#include <stdint.h>
19
20#ifdef __cplusplus
21extern "C" {
22#endif
23
24#ifdef __LLVM_INSTR_PROFILE_GENERATE
25// Profile file reset and dump interfaces.
26// When `-fprofile[-instr]-generate`/`-fcs-profile-generate` is in effect,
27// clang defines __LLVM_INSTR_PROFILE_GENERATE to pick up the API calls.
28
29/*! \brief Initialize file handling. */
30void __llvm_profile_initialize_file(void);
31
32/*!
33 * \brief Write instrumentation data to the current file.
34 *
35 * Writes to the file with the last name given to \a
36 * __llvm_profile_set_filename(),
37 * or if it hasn't been called, the \c LLVM_PROFILE_FILE environment variable,
38 * or if that's not set, the last name set to INSTR_PROF_PROFILE_NAME_VAR,
39 * or if that's not set, \c "default.profraw".
40 */
41int __llvm_profile_write_file(void);
42
43/*!
44 * \brief Set the filename for writing instrumentation data.
45 *
46 * Sets the filename to be used for subsequent calls to
47 * \a __llvm_profile_write_file().
48 *
49 * \c Name is not copied, so it must remain valid. Passing NULL resets the
50 * filename logic to the default behaviour.
51 *
52 * Note: There may be multiple copies of the profile runtime (one for each
53 * instrumented image/DSO). This API only modifies the filename within the
54 * copy of the runtime available to the calling image.
55 *
56 * Warning: This is a no-op if continuous mode (\ref
57 * __llvm_profile_is_continuous_mode_enabled) is on. The reason for this is
58 * that in continuous mode, profile counters are mmap()'d to the profile at
59 * program initialization time. Support for transferring the mmap'd profile
60 * counts to a new file has not been implemented.
61 */
62void __llvm_profile_set_filename(const char *Name);
63
64/*!
65 * \brief Return filename (including path) of the profile data. Note that if the
66 * user calls __llvm_profile_set_filename later after invoking this interface,
67 * the actual file name may differ from what is returned here.
68 * Side-effect: this API call will invoke malloc with dynamic memory allocation
69 * (the returned pointer must be passed to `free` to avoid a leak, unless
70 * allocation fails, in which case a static `""` is returned).
71 *
72 * Note: There may be multiple copies of the profile runtime (one for each
73 * instrumented image/DSO). This API only retrieves the filename from the copy
74 * of the runtime available to the calling image.
75 */
76const char *__llvm_profile_get_filename(void);
77
78/*!
79 * \brief Interface to set all PGO counters to zero for the current process.
80 *
81 */
82void __llvm_profile_reset_counters(void);
83
84/*!
85 * \brief this is a wrapper interface to \c __llvm_profile_write_file.
86 * After this interface is invoked, an already dumped flag will be set
87 * so that profile won't be dumped again during program exit.
88 * Invocation of interface __llvm_profile_reset_counters will clear
89 * the flag. This interface is designed to be used to collect profile
90 * data from user selected hot regions. The use model is
91 * __llvm_profile_reset_counters();
92 * ... hot region 1
93 * __llvm_profile_dump();
94 * .. some other code
95 * __llvm_profile_reset_counters();
96 * ... hot region 2
97 * __llvm_profile_dump();
98 *
99 * It is expected that on-line profile merging is on with \c %m specifier
100 * used in profile filename . If merging is not turned on, user is expected
101 * to invoke __llvm_profile_set_filename to specify different profile names
102 * for different regions before dumping to avoid profile write clobbering.
103 */
104int __llvm_profile_dump(void);
105
106/*!
107 * \brief Get required size for profile buffer.
108 */
109uint64_t __llvm_profile_get_size_for_buffer(void);
110
111/*!
112 * \brief Write instrumentation data to the given buffer.
113 *
114 * \pre \c Buffer is the start of a buffer at least as big as \a
115 * __llvm_profile_get_size_for_buffer().
116 */
117int __llvm_profile_write_buffer(char *Buffer);
118
119/*!
120 * \brief Merge profile data from buffer.
121 *
122 * Read profile data from buffer \p Profile and merge with in-process profile
123 * counters and bitmaps. The client is expected to have checked or already
124 * know the profile data in the buffer matches the in-process counter
125 * structure before calling it. Returns 0 (success) if the profile data is
126 * valid. Upon reading invalid/corrupted profile data, returns 1 (failure).
127 */
128int __llvm_profile_merge_from_buffer(const char *Profile, uint64_t Size);
129
130/*! \brief Check if profile in buffer matches the current binary.
131 *
132 * Returns 0 (success) if the profile data in buffer \p Profile with size
133 * \p Size was generated by the same binary and therefore matches
134 * structurally the in-process counters and bitmaps. If the profile data in
135 * buffer is not compatible, the interface returns 1 (failure).
136 */
137int __llvm_profile_check_compatibility(const char *Profile, uint64_t Size);
138
139#else
140
141#define __llvm_profile_initialize_file()
142#define __llvm_profile_write_file() (0)
143#define __llvm_profile_set_filename(Name)
144#define __llvm_profile_get_filename() ((const char *)0)
145#define __llvm_profile_reset_counters()
146#define __llvm_profile_dump() (0)
147#define __llvm_profile_get_size_for_buffer() ((uint64_t)0)
148#define __llvm_profile_write_buffer(Buffer) (0)
149#define __llvm_profile_merge_from_buffer(Profile, Size) (0)
150#define __llvm_profile_check_compatibility(Profile, Size) (0)
151
152#endif
153
154#ifdef __cplusplus
155} // extern "C"
156#endif
157
158#endif
159