compiler-rt/include/profile/instr_prof_interface.h

   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