contrib/compiler-rt/lib/profile/InstrProfiling.h

   1 /*===- InstrProfiling.h- Support library for PGO instrumentation ----------===*\
   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 #ifndef PROFILE_INSTRPROFILING_H_
  10 #define PROFILE_INSTRPROFILING_H_
  11
  12 #include "InstrProfilingPort.h"
  13 #include <stdio.h>
  14
  15 #define INSTR_PROF_VISIBILITY COMPILER_RT_VISIBILITY
  16 #include "InstrProfData.inc"
  17
  18 enum ValueKind {
  19 #define VALUE_PROF_KIND(Enumerator, Value, Descr) Enumerator = Value,
  20 #include "InstrProfData.inc"
  21 };
  22
  23 typedef void *IntPtrT;
  24 typedef struct COMPILER_RT_ALIGNAS(INSTR_PROF_DATA_ALIGNMENT)
  25     __llvm_profile_data {
  26 #define INSTR_PROF_DATA(Type, LLVMType, Name, Initializer) Type Name;
  27 #include "InstrProfData.inc"
  28 } __llvm_profile_data;
  29
  30 typedef struct __llvm_profile_header {
  31 #define INSTR_PROF_RAW_HEADER(Type, Name, Initializer) Type Name;
  32 #include "InstrProfData.inc"
  33 } __llvm_profile_header;
  34
  35 typedef struct ValueProfNode * PtrToNodeT;
  36 typedef struct ValueProfNode {
  37 #define INSTR_PROF_VALUE_NODE(Type, LLVMType, Name, Initializer) Type Name;
  38 #include "InstrProfData.inc"
  39 } ValueProfNode;
  40
  41 /*!
  42  * \brief Get number of bytes necessary to pad the argument to eight
  43  * byte boundary.
  44  */
  45 uint8_t __llvm_profile_get_num_padding_bytes(uint64_t SizeInBytes);
  46
  47 /*!
  48  * \brief Get required size for profile buffer.
  49  */
  50 uint64_t __llvm_profile_get_size_for_buffer(void);
  51
  52 /*!
  53  * \brief Write instrumentation data to the given buffer.
  54  *
  55  * \pre \c Buffer is the start of a buffer at least as big as \a
  56  * __llvm_profile_get_size_for_buffer().
  57  */
  58 int __llvm_profile_write_buffer(char *Buffer);
  59
  60 const __llvm_profile_data *__llvm_profile_begin_data(void);
  61 const __llvm_profile_data *__llvm_profile_end_data(void);
  62 const char *__llvm_profile_begin_names(void);
  63 const char *__llvm_profile_end_names(void);
  64 uint64_t *__llvm_profile_begin_counters(void);
  65 uint64_t *__llvm_profile_end_counters(void);
  66 ValueProfNode *__llvm_profile_begin_vnodes();
  67 ValueProfNode *__llvm_profile_end_vnodes();
  68 uint32_t *__llvm_profile_begin_orderfile();
  69
  70 /*!
  71  * \brief Clear profile counters to zero.
  72  *
  73  */
  74 void __llvm_profile_reset_counters(void);
  75
  76 /*!
  77  * \brief Merge profile data from buffer.
  78  *
  79  * Read profile data form buffer \p Profile  and merge with
  80  * in-process profile counters. The client is expected to
  81  * have checked or already knows the profile data in the
  82  * buffer matches the in-process counter structure before
  83  * calling it.
  84  */
  85 void __llvm_profile_merge_from_buffer(const char *Profile, uint64_t Size);
  86
  87 /*! \brief Check if profile in buffer matches the current binary.
  88  *
  89  *  Returns 0 (success) if the profile data in buffer \p Profile with size
  90  *  \p Size was generated by the same binary and therefore matches
  91  *  structurally the in-process counters. If the profile data in buffer is
  92  *  not compatible, the interface returns 1 (failure).
  93  */
  94 int __llvm_profile_check_compatibility(const char *Profile,
  95                                        uint64_t Size);
  96
  97 /*!
  98  * \brief Counts the number of times a target value is seen.
  99  *
 100  * Records the target value for the CounterIndex if not seen before. Otherwise,
 101  * increments the counter associated w/ the target value.
 102  * void __llvm_profile_instrument_target(uint64_t TargetValue, void *Data,
 103  *                                       uint32_t CounterIndex);
 104  */
 105 void INSTR_PROF_VALUE_PROF_FUNC(
 106 #define VALUE_PROF_FUNC_PARAM(ArgType, ArgName, ArgLLVMType) ArgType ArgName
 107 #include "InstrProfData.inc"
 108     );
 109
 110 void __llvm_profile_instrument_target_value(uint64_t TargetValue, void *Data,
 111                                             uint32_t CounterIndex,
 112                                             uint64_t CounterValue);
 113
 114 /*!
 115  * \brief Write instrumentation data to the current file.
 116  *
 117  * Writes to the file with the last name given to \a *
 118  * __llvm_profile_set_filename(),
 119  * or if it hasn't been called, the \c LLVM_PROFILE_FILE environment variable,
 120  * or if that's not set, the last name set to INSTR_PROF_PROFILE_NAME_VAR,
 121  * or if that's not set,  \c "default.profraw".
 122  */
 123 int __llvm_profile_write_file(void);
 124
 125 int __llvm_orderfile_write_file(void);
 126 /*!
 127  * \brief this is a wrapper interface to \c __llvm_profile_write_file.
 128  * After this interface is invoked, a arleady dumped flag will be set
 129  * so that profile won't be dumped again during program exit.
 130  * Invocation of interface __llvm_profile_reset_counters will clear
 131  * the flag. This interface is designed to be used to collect profile
 132  * data from user selected hot regions. The use model is
 133  *      __llvm_profile_reset_counters();
 134  *      ... hot region 1
 135  *      __llvm_profile_dump();
 136  *      .. some other code
 137  *      __llvm_profile_reset_counters();
 138  *       ... hot region 2
 139  *      __llvm_profile_dump();
 140  *
 141  *  It is expected that on-line profile merging is on with \c %m specifier
 142  *  used in profile filename . If merging is  not turned on, user is expected
 143  *  to invoke __llvm_profile_set_filename  to specify different profile names
 144  *  for different regions before dumping to avoid profile write clobbering.
 145  */
 146 int __llvm_profile_dump(void);
 147
 148 int __llvm_orderfile_dump(void);
 149
 150 /*!
 151  * \brief Set the filename for writing instrumentation data.
 152  *
 153  * Sets the filename to be used for subsequent calls to
 154  * \a __llvm_profile_write_file().
 155  *
 156  * \c Name is not copied, so it must remain valid.  Passing NULL resets the
 157  * filename logic to the default behaviour.
 158  */
 159 void __llvm_profile_set_filename(const char *Name);
 160
 161 /*!
 162  * \brief Set the FILE object for writing instrumentation data.
 163  *
 164  * Sets the FILE object to be used for subsequent calls to
 165  * \a __llvm_profile_write_file(). The profile file name set by environment
 166  * variable, command-line option, or calls to \a  __llvm_profile_set_filename
 167  * will be ignored.
 168  *
 169  * \c File will not be closed after a call to \a __llvm_profile_write_file() but
 170  * it may be flushed. Passing NULL restores default behavior.
 171  *
 172  * If \c EnableMerge is nonzero, the runtime will always merge profiling data
 173  * with the contents of the profiling file. If EnableMerge is zero, the runtime
 174  * may still merge the data if it would have merged for another reason (for
 175  * example, because of a %m specifier in the file name).
 176  */
 177 void __llvm_profile_set_file_object(FILE *File, int EnableMerge);
 178
 179 /*! \brief Register to write instrumentation data to file at exit. */
 180 int __llvm_profile_register_write_file_atexit(void);
 181
 182 /*! \brief Initialize file handling. */
 183 void __llvm_profile_initialize_file(void);
 184
 185 /*!
 186  * \brief Return path prefix (excluding the base filename) of the profile data.
 187  * This is useful for users using \c -fprofile-generate=./path_prefix who do
 188  * not care about the default raw profile name. It is also useful to collect
 189  * more than more profile data files dumped in the same directory (Online
 190  * merge mode is turned on for instrumented programs with shared libs).
 191  * Side-effect: this API call will invoke malloc with dynamic memory allocation.
 192  */
 193 const char *__llvm_profile_get_path_prefix();
 194
 195 /*!
 196  * \brief Return filename (including path) of the profile data. Note that if the
 197  * user calls __llvm_profile_set_filename later after invoking this interface,
 198  * the actual file name may differ from what is returned here.
 199  * Side-effect: this API call will invoke malloc with dynamic memory allocation.
 200  */
 201 const char *__llvm_profile_get_filename();
 202
 203 /*! \brief Get the magic token for the file format. */
 204 uint64_t __llvm_profile_get_magic(void);
 205
 206 /*! \brief Get the version of the file format. */
 207 uint64_t __llvm_profile_get_version(void);
 208
 209 /*! \brief Get the number of entries in the profile data section. */
 210 uint64_t __llvm_profile_get_data_size(const __llvm_profile_data *Begin,
 211                                       const __llvm_profile_data *End);
 212
 213 /*!
 214  * \brief Set the flag that profile data has been dumped to the file.
 215  * This is useful for users to disable dumping profile data to the file for
 216  * certain processes in case the processes don't have permission to write to
 217  * the disks, and trying to do so would result in side effects such as crashes.
 218  */
 219 void __llvm_profile_set_dumped();
 220
 221 /*!
 222  * This variable is defined in InstrProfilingRuntime.cc as a hidden
 223  * symbol. Its main purpose is to enable profile runtime user to
 224  * bypass runtime initialization code -- if the client code explicitly
 225  * define this variable, then InstProfileRuntime.o won't be linked in.
 226  * Note that this variable's visibility needs to be hidden so that the
 227  * definition of this variable in an instrumented shared library won't
 228  * affect runtime initialization decision of the main program.
 229  *  __llvm_profile_profile_runtime. */
 230 COMPILER_RT_VISIBILITY extern int INSTR_PROF_PROFILE_RUNTIME_VAR;
 231
 232 /*!
 233  * This variable is defined in InstrProfiling.c. Its main purpose is to
 234  * encode the raw profile version value and other format related information
 235  * such as whether the profile is from IR based instrumentation. The variable
 236  * is defined as weak so that compiler can emit an overriding definition
 237  * depending on user option.  Since we don't support mixing FE and IR based
 238  * data in the same raw profile data file (in other words, shared libs and
 239  * main program are expected to be instrumented in the same way), there is
 240  * no need for this variable to be hidden.
 241  */
 242 extern uint64_t INSTR_PROF_RAW_VERSION_VAR; /* __llvm_profile_raw_version */
 243
 244 /*!
 245  * This variable is a weak symbol defined in InstrProfiling.c. It allows
 246  * compiler instrumentation to provide overriding definition with value
 247  * from compiler command line. This variable has default visibility.
 248  */
 249 extern char INSTR_PROF_PROFILE_NAME_VAR[1]; /* __llvm_profile_filename. */
 250
 251 #endif /* PROFILE_INSTRPROFILING_H_ */