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#ifdef __cplusplus
19extern "C" {
20#endif
21
22#ifdef __LLVM_INSTR_PROFILE_GENERATE
23// Profile file reset and dump interfaces.
24// When `-fprofile[-instr]-generate`/`-fcs-profile-generate` is in effect,
25// clang defines __LLVM_INSTR_PROFILE_GENERATE to pick up the API calls.
26
27/*!
28 * \brief Set the filename for writing instrumentation data.
29 *
30 * Sets the filename to be used for subsequent calls to
31 * \a __llvm_profile_write_file().
32 *
33 * \c Name is not copied, so it must remain valid. Passing NULL resets the
34 * filename logic to the default behaviour.
35 *
36 * Note: There may be multiple copies of the profile runtime (one for each
37 * instrumented image/DSO). This API only modifies the filename within the
38 * copy of the runtime available to the calling image.
39 *
40 * Warning: This is a no-op if continuous mode (\ref
41 * __llvm_profile_is_continuous_mode_enabled) is on. The reason for this is
42 * that in continuous mode, profile counters are mmap()'d to the profile at
43 * program initialization time. Support for transferring the mmap'd profile
44 * counts to a new file has not been implemented.
45 */
46void __llvm_profile_set_filename(const char *Name);
47
48/*!
49 * \brief Interface to set all PGO counters to zero for the current process.
50 *
51 */
52void __llvm_profile_reset_counters(void);
53
54/*!
55 * \brief this is a wrapper interface to \c __llvm_profile_write_file.
56 * After this interface is invoked, an already dumped flag will be set
57 * so that profile won't be dumped again during program exit.
58 * Invocation of interface __llvm_profile_reset_counters will clear
59 * the flag. This interface is designed to be used to collect profile
60 * data from user selected hot regions. The use model is
61 * __llvm_profile_reset_counters();
62 * ... hot region 1
63 * __llvm_profile_dump();
64 * .. some other code
65 * __llvm_profile_reset_counters();
66 * ... hot region 2
67 * __llvm_profile_dump();
68 *
69 * It is expected that on-line profile merging is on with \c %m specifier
70 * used in profile filename . If merging is not turned on, user is expected
71 * to invoke __llvm_profile_set_filename to specify different profile names
72 * for different regions before dumping to avoid profile write clobbering.
73 */
74int __llvm_profile_dump(void);
75
76#else
77
78#define __llvm_profile_set_filename(Name)
79#define __llvm_profile_reset_counters()
80#define __llvm_profile_dump() (0)
81
82#endif
83
84#ifdef __cplusplus
85} // extern "C"
86#endif
87
88#endif
89