1*7a6dacacSDimitry Andric /*===---- instr_prof_interface.h - Instrumentation PGO User Program API ----=== 2*7a6dacacSDimitry Andric * 3*7a6dacacSDimitry Andric * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4*7a6dacacSDimitry Andric * See https://llvm.org/LICENSE.txt for license information. 5*7a6dacacSDimitry Andric * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6*7a6dacacSDimitry Andric * 7*7a6dacacSDimitry Andric *===-----------------------------------------------------------------------=== 8*7a6dacacSDimitry Andric * 9*7a6dacacSDimitry Andric * This header provides a public interface for fine-grained control of counter 10*7a6dacacSDimitry Andric * reset and profile dumping. These interface functions can be directly called 11*7a6dacacSDimitry Andric * in user programs. 12*7a6dacacSDimitry Andric * 13*7a6dacacSDimitry Andric \*===---------------------------------------------------------------------===*/ 14*7a6dacacSDimitry Andric 15*7a6dacacSDimitry Andric #ifndef COMPILER_RT_INSTR_PROFILING 16*7a6dacacSDimitry Andric #define COMPILER_RT_INSTR_PROFILING 17*7a6dacacSDimitry Andric 18*7a6dacacSDimitry Andric #ifdef __cplusplus 19*7a6dacacSDimitry Andric extern "C" { 20*7a6dacacSDimitry Andric #endif 21*7a6dacacSDimitry Andric 22*7a6dacacSDimitry Andric #ifdef __LLVM_INSTR_PROFILE_GENERATE 23*7a6dacacSDimitry Andric // Profile file reset and dump interfaces. 24*7a6dacacSDimitry Andric // When `-fprofile[-instr]-generate`/`-fcs-profile-generate` is in effect, 25*7a6dacacSDimitry Andric // clang defines __LLVM_INSTR_PROFILE_GENERATE to pick up the API calls. 26*7a6dacacSDimitry Andric 27*7a6dacacSDimitry Andric /*! 28*7a6dacacSDimitry Andric * \brief Set the filename for writing instrumentation data. 29*7a6dacacSDimitry Andric * 30*7a6dacacSDimitry Andric * Sets the filename to be used for subsequent calls to 31*7a6dacacSDimitry Andric * \a __llvm_profile_write_file(). 32*7a6dacacSDimitry Andric * 33*7a6dacacSDimitry Andric * \c Name is not copied, so it must remain valid. Passing NULL resets the 34*7a6dacacSDimitry Andric * filename logic to the default behaviour. 35*7a6dacacSDimitry Andric * 36*7a6dacacSDimitry Andric * Note: There may be multiple copies of the profile runtime (one for each 37*7a6dacacSDimitry Andric * instrumented image/DSO). This API only modifies the filename within the 38*7a6dacacSDimitry Andric * copy of the runtime available to the calling image. 39*7a6dacacSDimitry Andric * 40*7a6dacacSDimitry Andric * Warning: This is a no-op if continuous mode (\ref 41*7a6dacacSDimitry Andric * __llvm_profile_is_continuous_mode_enabled) is on. The reason for this is 42*7a6dacacSDimitry Andric * that in continuous mode, profile counters are mmap()'d to the profile at 43*7a6dacacSDimitry Andric * program initialization time. Support for transferring the mmap'd profile 44*7a6dacacSDimitry Andric * counts to a new file has not been implemented. 45*7a6dacacSDimitry Andric */ 46*7a6dacacSDimitry Andric void __llvm_profile_set_filename(const char *Name); 47*7a6dacacSDimitry Andric 48*7a6dacacSDimitry Andric /*! 49*7a6dacacSDimitry Andric * \brief Interface to set all PGO counters to zero for the current process. 50*7a6dacacSDimitry Andric * 51*7a6dacacSDimitry Andric */ 52*7a6dacacSDimitry Andric void __llvm_profile_reset_counters(void); 53*7a6dacacSDimitry Andric 54*7a6dacacSDimitry Andric /*! 55*7a6dacacSDimitry Andric * \brief this is a wrapper interface to \c __llvm_profile_write_file. 56*7a6dacacSDimitry Andric * After this interface is invoked, an already dumped flag will be set 57*7a6dacacSDimitry Andric * so that profile won't be dumped again during program exit. 58*7a6dacacSDimitry Andric * Invocation of interface __llvm_profile_reset_counters will clear 59*7a6dacacSDimitry Andric * the flag. This interface is designed to be used to collect profile 60*7a6dacacSDimitry Andric * data from user selected hot regions. The use model is 61*7a6dacacSDimitry Andric * __llvm_profile_reset_counters(); 62*7a6dacacSDimitry Andric * ... hot region 1 63*7a6dacacSDimitry Andric * __llvm_profile_dump(); 64*7a6dacacSDimitry Andric * .. some other code 65*7a6dacacSDimitry Andric * __llvm_profile_reset_counters(); 66*7a6dacacSDimitry Andric * ... hot region 2 67*7a6dacacSDimitry Andric * __llvm_profile_dump(); 68*7a6dacacSDimitry Andric * 69*7a6dacacSDimitry Andric * It is expected that on-line profile merging is on with \c %m specifier 70*7a6dacacSDimitry Andric * used in profile filename . If merging is not turned on, user is expected 71*7a6dacacSDimitry Andric * to invoke __llvm_profile_set_filename to specify different profile names 72*7a6dacacSDimitry Andric * for different regions before dumping to avoid profile write clobbering. 73*7a6dacacSDimitry Andric */ 74*7a6dacacSDimitry Andric int __llvm_profile_dump(void); 75*7a6dacacSDimitry Andric 76*7a6dacacSDimitry Andric // Interface to dump the current process' order file to disk. 77*7a6dacacSDimitry Andric int __llvm_orderfile_dump(void); 78*7a6dacacSDimitry Andric 79*7a6dacacSDimitry Andric #else 80*7a6dacacSDimitry Andric 81*7a6dacacSDimitry Andric #define __llvm_profile_set_filename(Name) 82*7a6dacacSDimitry Andric #define __llvm_profile_reset_counters() 83*7a6dacacSDimitry Andric #define __llvm_profile_dump() (0) 84*7a6dacacSDimitry Andric #define __llvm_orderfile_dump() (0) 85*7a6dacacSDimitry Andric 86*7a6dacacSDimitry Andric #endif 87*7a6dacacSDimitry Andric 88*7a6dacacSDimitry Andric #ifdef __cplusplus 89*7a6dacacSDimitry Andric } // extern "C" 90*7a6dacacSDimitry Andric #endif 91*7a6dacacSDimitry Andric 92*7a6dacacSDimitry Andric #endif 93