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