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_ */ 252