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