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 19 extern "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 */ 46 void __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 */ 52 void __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 */ 74 int __llvm_profile_dump(void); 75 76 // Interface to dump the current process' order file to disk. 77 int __llvm_orderfile_dump(void); 78 79 #else 80 81 #define __llvm_profile_set_filename(Name) 82 #define __llvm_profile_reset_counters() 83 #define __llvm_profile_dump() (0) 84 #define __llvm_orderfile_dump() (0) 85 86 #endif 87 88 #ifdef __cplusplus 89 } // extern "C" 90 #endif 91 92 #endif 93