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 // Make sure __LLVM_INSTR_PROFILE_GENERATE is always defined before 16 // including instr_prof_interface.h so the interface functions are 17 // declared correctly for the runtime. 18 // __LLVM_INSTR_PROFILE_GENERATE is always `#undef`ed after the header, 19 // because compiler-rt does not support profiling the profiling runtime itself. 20 #ifndef __LLVM_INSTR_PROFILE_GENERATE 21 #define __LLVM_INSTR_PROFILE_GENERATE 22 #endif 23 #include "profile/instr_prof_interface.h" 24 #undef __LLVM_INSTR_PROFILE_GENERATE 25 26 #define INSTR_PROF_VISIBILITY COMPILER_RT_VISIBILITY 27 #include "profile/InstrProfData.inc" 28 29 enum ValueKind { 30 #define VALUE_PROF_KIND(Enumerator, Value, Descr) Enumerator = Value, 31 #include "profile/InstrProfData.inc" 32 }; 33 34 typedef void *IntPtrT; 35 typedef struct COMPILER_RT_ALIGNAS(INSTR_PROF_DATA_ALIGNMENT) 36 __llvm_profile_data { 37 #define INSTR_PROF_DATA(Type, LLVMType, Name, Initializer) Type Name; 38 #include "profile/InstrProfData.inc" 39 } __llvm_profile_data; 40 41 typedef struct __llvm_profile_header { 42 #define INSTR_PROF_RAW_HEADER(Type, Name, Initializer) Type Name; 43 #include "profile/InstrProfData.inc" 44 } __llvm_profile_header; 45 46 typedef struct ValueProfNode * PtrToNodeT; 47 typedef struct ValueProfNode { 48 #define INSTR_PROF_VALUE_NODE(Type, LLVMType, Name, Initializer) Type Name; 49 #include "profile/InstrProfData.inc" 50 } ValueProfNode; 51 52 typedef struct COMPILER_RT_ALIGNAS(INSTR_PROF_DATA_ALIGNMENT) VTableProfData { 53 #define INSTR_PROF_VTABLE_DATA(Type, LLVMType, Name, Initializer) Type Name; 54 #include "profile/InstrProfData.inc" 55 } VTableProfData; 56 57 typedef struct COMPILER_RT_ALIGNAS(INSTR_PROF_DATA_ALIGNMENT) 58 __llvm_gcov_init_func_struct { 59 #define COVINIT_FUNC(Type, LLVMType, Name, Initializer) Type Name; 60 #include "profile/InstrProfData.inc" 61 } __llvm_gcov_init_func_struct; 62 63 /*! 64 * \brief Return 1 if profile counters are continuously synced to the raw 65 * profile via an mmap(). This is in contrast to the default mode, in which 66 * the raw profile is written out at program exit time. 67 */ 68 int __llvm_profile_is_continuous_mode_enabled(void); 69 70 /*! 71 * \brief Enable continuous mode. 72 * 73 * See \ref __llvm_profile_is_continuous_mode_enabled. The behavior is undefined 74 * if continuous mode is already enabled, or if it cannot be enable due to 75 * conflicting options. 76 */ 77 void __llvm_profile_enable_continuous_mode(void); 78 79 /*! 80 * \brief Disable continuous mode. 81 * 82 */ 83 void __llvm_profile_disable_continuous_mode(void); 84 85 /*! 86 * \brief Set the page size. 87 * 88 * This is a pre-requisite for enabling continuous mode. The buffer size 89 * calculation code inside of libprofile cannot simply call getpagesize(), as 90 * it is not allowed to depend on libc. 91 */ 92 void __llvm_profile_set_page_size(unsigned PageSize); 93 94 /*! 95 * \brief Get number of bytes necessary to pad the argument to eight 96 * byte boundary. 97 */ 98 uint8_t __llvm_profile_get_num_padding_bytes(uint64_t SizeInBytes); 99 100 /*! 101 * \brief Get required size for profile buffer. 102 */ 103 uint64_t __llvm_profile_get_size_for_buffer(void); 104 105 /*! 106 * \brief Write instrumentation data to the given buffer. 107 * 108 * \pre \c Buffer is the start of a buffer at least as big as \a 109 * __llvm_profile_get_size_for_buffer(). 110 */ 111 int __llvm_profile_write_buffer(char *Buffer); 112 113 const __llvm_profile_data *__llvm_profile_begin_data(void); 114 const __llvm_profile_data *__llvm_profile_end_data(void); 115 const char *__llvm_profile_begin_names(void); 116 const char *__llvm_profile_end_names(void); 117 const char *__llvm_profile_begin_vtabnames(void); 118 const char *__llvm_profile_end_vtabnames(void); 119 char *__llvm_profile_begin_counters(void); 120 char *__llvm_profile_end_counters(void); 121 char *__llvm_profile_begin_bitmap(void); 122 char *__llvm_profile_end_bitmap(void); 123 ValueProfNode *__llvm_profile_begin_vnodes(void); 124 ValueProfNode *__llvm_profile_end_vnodes(void); 125 const VTableProfData *__llvm_profile_begin_vtables(void); 126 const VTableProfData *__llvm_profile_end_vtables(void); 127 128 /*! 129 * \brief Merge profile data from buffer. 130 * 131 * Read profile data from buffer \p Profile and merge with in-process profile 132 * counters and bitmaps. The client is expected to have checked or already 133 * know the profile data in the buffer matches the in-process counter 134 * structure before calling it. Returns 0 (success) if the profile data is 135 * valid. Upon reading invalid/corrupted profile data, returns 1 (failure). 136 */ 137 int __llvm_profile_merge_from_buffer(const char *Profile, uint64_t Size); 138 139 /*! \brief Check if profile in buffer matches the current binary. 140 * 141 * Returns 0 (success) if the profile data in buffer \p Profile with size 142 * \p Size was generated by the same binary and therefore matches 143 * structurally the in-process counters and bitmaps. If the profile data in 144 * buffer is not compatible, the interface returns 1 (failure). 145 */ 146 int __llvm_profile_check_compatibility(const char *Profile, 147 uint64_t Size); 148 149 /*! 150 * \brief Counts the number of times a target value is seen. 151 * 152 * Records the target value for the CounterIndex if not seen before. Otherwise, 153 * increments the counter associated w/ the target value. 154 * void __llvm_profile_instrument_target(uint64_t TargetValue, void *Data, 155 * uint32_t CounterIndex); 156 */ 157 void INSTR_PROF_VALUE_PROF_FUNC( 158 #define VALUE_PROF_FUNC_PARAM(ArgType, ArgName, ArgLLVMType) ArgType ArgName 159 #include "profile/InstrProfData.inc" 160 ); 161 162 void __llvm_profile_instrument_target_value(uint64_t TargetValue, void *Data, 163 uint32_t CounterIndex, 164 uint64_t CounterValue); 165 166 /*! 167 * \brief Write instrumentation data to the current file. 168 * 169 * Writes to the file with the last name given to \a * 170 * __llvm_profile_set_filename(), 171 * or if it hasn't been called, the \c LLVM_PROFILE_FILE environment variable, 172 * or if that's not set, the last name set to INSTR_PROF_PROFILE_NAME_VAR, 173 * or if that's not set, \c "default.profraw". 174 */ 175 int __llvm_profile_write_file(void); 176 177 /*! 178 * \brief Set the FILE object for writing instrumentation data. Return 0 if set 179 * successfully or return 1 if failed. 180 * 181 * Sets the FILE object to be used for subsequent calls to 182 * \a __llvm_profile_write_file(). The profile file name set by environment 183 * variable, command-line option, or calls to \a __llvm_profile_set_filename 184 * will be ignored. 185 * 186 * \c File will not be closed after a call to \a __llvm_profile_write_file() but 187 * it may be flushed. Passing NULL restores default behavior. 188 * 189 * If \c EnableMerge is nonzero, the runtime will always merge profiling data 190 * with the contents of the profiling file. If EnableMerge is zero, the runtime 191 * may still merge the data if it would have merged for another reason (for 192 * example, because of a %m specifier in the file name). 193 * 194 * Note: There may be multiple copies of the profile runtime (one for each 195 * instrumented image/DSO). This API only modifies the file object within the 196 * copy of the runtime available to the calling image. 197 * 198 * Warning: This is a no-op if EnableMerge is 0 in continuous mode (\ref 199 * __llvm_profile_is_continuous_mode_enabled), because disable merging requires 200 * copying the old profile file to new profile file and this function is usually 201 * used when the proess doesn't have permission to open file. 202 */ 203 int __llvm_profile_set_file_object(FILE *File, int EnableMerge); 204 205 /*! \brief Register to write instrumentation data to file at exit. */ 206 int __llvm_profile_register_write_file_atexit(void); 207 208 /*! \brief Initialize file handling. */ 209 void __llvm_profile_initialize_file(void); 210 211 /*! \brief Initialize the profile runtime. */ 212 void __llvm_profile_initialize(void); 213 214 /*! \brief Initialize the gcov profile runtime. */ 215 void __llvm_profile_gcov_initialize(void); 216 217 /*! 218 * \brief Return path prefix (excluding the base filename) of the profile data. 219 * This is useful for users using \c -fprofile-generate=./path_prefix who do 220 * not care about the default raw profile name. It is also useful to collect 221 * more than more profile data files dumped in the same directory (Online 222 * merge mode is turned on for instrumented programs with shared libs). 223 * Side-effect: this API call will invoke malloc with dynamic memory allocation. 224 */ 225 const char *__llvm_profile_get_path_prefix(void); 226 227 /*! 228 * \brief Return filename (including path) of the profile data. Note that if the 229 * user calls __llvm_profile_set_filename later after invoking this interface, 230 * the actual file name may differ from what is returned here. 231 * Side-effect: this API call will invoke malloc with dynamic memory allocation 232 * (the returned pointer must be passed to `free` to avoid a leak). 233 * 234 * Note: There may be multiple copies of the profile runtime (one for each 235 * instrumented image/DSO). This API only retrieves the filename from the copy 236 * of the runtime available to the calling image. 237 */ 238 const char *__llvm_profile_get_filename(void); 239 240 /*! \brief Get the magic token for the file format. */ 241 uint64_t __llvm_profile_get_magic(void); 242 243 /*! \brief Get the version of the file format. */ 244 uint64_t __llvm_profile_get_version(void); 245 246 /*! \brief Get the number of entries in the profile data section. */ 247 uint64_t __llvm_profile_get_num_data(const __llvm_profile_data *Begin, 248 const __llvm_profile_data *End); 249 250 /*! \brief Get the size of the profile data section in bytes. */ 251 uint64_t __llvm_profile_get_data_size(const __llvm_profile_data *Begin, 252 const __llvm_profile_data *End); 253 254 /*! \brief Get the size in bytes of a single counter entry. */ 255 size_t __llvm_profile_counter_entry_size(void); 256 257 /*! \brief Get the number of entries in the profile counters section. */ 258 uint64_t __llvm_profile_get_num_counters(const char *Begin, const char *End); 259 260 /*! \brief Get the size of the profile counters section in bytes. */ 261 uint64_t __llvm_profile_get_counters_size(const char *Begin, const char *End); 262 263 /*! \brief Get the number of bytes in the profile bitmap section. */ 264 uint64_t __llvm_profile_get_num_bitmap_bytes(const char *Begin, 265 const char *End); 266 267 /*! \brief Get the size of the profile name section in bytes. */ 268 uint64_t __llvm_profile_get_name_size(const char *Begin, const char *End); 269 270 /*! \brief Get the number of virtual table profile data entries */ 271 uint64_t __llvm_profile_get_num_vtable(const VTableProfData *Begin, 272 const VTableProfData *End); 273 274 /*! \brief Get the size of virtual table profile data in bytes. */ 275 uint64_t __llvm_profile_get_vtable_section_size(const VTableProfData *Begin, 276 const VTableProfData *End); 277 278 /* ! \brief Given the sizes of the data and counter information, computes the 279 * number of padding bytes before and after the counter section, as well as the 280 * number of padding bytes after other sections in the raw profile. 281 * Returns -1 upon errors and 0 upon success. Output parameters should be used 282 * iff return value is 0. 283 * 284 * Note: When mmap() mode is disabled, no padding bytes before/after counters 285 * are needed. However, in mmap() mode, the counter section in the raw profile 286 * must be page-aligned: this API computes the number of padding bytes 287 * needed to achieve that. 288 */ 289 int __llvm_profile_get_padding_sizes_for_counters( 290 uint64_t DataSize, uint64_t CountersSize, uint64_t NumBitmapBytes, 291 uint64_t NamesSize, uint64_t VTableSize, uint64_t VNameSize, 292 uint64_t *PaddingBytesBeforeCounters, uint64_t *PaddingBytesAfterCounters, 293 uint64_t *PaddingBytesAfterBitmap, uint64_t *PaddingBytesAfterNames, 294 uint64_t *PaddingBytesAfterVTable, uint64_t *PaddingBytesAfterVNames); 295 296 /*! 297 * \brief Set the flag that profile data has been dumped to the file. 298 * This is useful for users to disable dumping profile data to the file for 299 * certain processes in case the processes don't have permission to write to 300 * the disks, and trying to do so would result in side effects such as crashes. 301 */ 302 void __llvm_profile_set_dumped(void); 303 304 /*! 305 * \brief Write custom target-specific profiling data to a separate file. 306 * Used by offload PGO. 307 */ 308 int __llvm_write_custom_profile(const char *Target, 309 const __llvm_profile_data *DataBegin, 310 const __llvm_profile_data *DataEnd, 311 const char *CountersBegin, 312 const char *CountersEnd, const char *NamesBegin, 313 const char *NamesEnd, 314 const uint64_t *VersionOverride); 315 316 /*! 317 * This variable is defined in InstrProfilingRuntime.cpp as a hidden 318 * symbol. Its main purpose is to enable profile runtime user to 319 * bypass runtime initialization code -- if the client code explicitly 320 * define this variable, then InstProfileRuntime.o won't be linked in. 321 * Note that this variable's visibility needs to be hidden so that the 322 * definition of this variable in an instrumented shared library won't 323 * affect runtime initialization decision of the main program. 324 * __llvm_profile_profile_runtime. */ 325 COMPILER_RT_VISIBILITY extern int INSTR_PROF_PROFILE_RUNTIME_VAR; 326 327 /*! 328 * This variable is defined in InstrProfilingVersionVar.c as a hidden symbol 329 * (except on Apple platforms where this symbol is checked by TAPI). Its main 330 * purpose is to encode the raw profile version value and other format related 331 * information such as whether the profile is from IR based instrumentation. The 332 * variable is defined as weak so that compiler can emit an overriding 333 * definition depending on user option. 334 */ 335 COMPILER_RT_VISIBILITY extern uint64_t 336 INSTR_PROF_RAW_VERSION_VAR; /* __llvm_profile_raw_version */ 337 338 /*! 339 * This variable is a weak symbol defined in InstrProfiling.c. It allows 340 * compiler instrumentation to provide overriding definition with value 341 * from compiler command line. This variable has default visibility. 342 */ 343 extern char INSTR_PROF_PROFILE_NAME_VAR[1]; /* __llvm_profile_filename. */ 344 345 const __llvm_gcov_init_func_struct *__llvm_profile_begin_covinit(); 346 const __llvm_gcov_init_func_struct *__llvm_profile_end_covinit(); 347 #endif /* PROFILE_INSTRPROFILING_H_ */ 348