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