348 lines · c
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-exception6|*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 before16// including instr_prof_interface.h so the interface functions are17// 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_GENERATE21#define __LLVM_INSTR_PROFILE_GENERATE22#endif23#include "profile/instr_prof_interface.h"24#undef __LLVM_INSTR_PROFILE_GENERATE25 26#define INSTR_PROF_VISIBILITY COMPILER_RT_VISIBILITY27#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 52typedef 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 57typedef 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 raw65 * profile via an mmap(). This is in contrast to the default mode, in which66 * the raw profile is written out at program exit time.67 */68int __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 undefined74 * if continuous mode is already enabled, or if it cannot be enable due to75 * conflicting options.76 */77void __llvm_profile_enable_continuous_mode(void);78 79/*!80 * \brief Disable continuous mode.81 *82 */83void __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 size89 * calculation code inside of libprofile cannot simply call getpagesize(), as90 * it is not allowed to depend on libc.91 */92void __llvm_profile_set_page_size(unsigned PageSize);93 94/*!95 * \brief Get number of bytes necessary to pad the argument to eight96 * byte boundary.97 */98uint8_t __llvm_profile_get_num_padding_bytes(uint64_t SizeInBytes);99 100/*!101 * \brief Get required size for profile buffer.102 */103uint64_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 \a109 * __llvm_profile_get_size_for_buffer().110 */111int __llvm_profile_write_buffer(char *Buffer);112 113const __llvm_profile_data *__llvm_profile_begin_data(void);114const __llvm_profile_data *__llvm_profile_end_data(void);115const char *__llvm_profile_begin_names(void);116const char *__llvm_profile_end_names(void);117const char *__llvm_profile_begin_vtabnames(void);118const char *__llvm_profile_end_vtabnames(void);119char *__llvm_profile_begin_counters(void);120char *__llvm_profile_end_counters(void);121char *__llvm_profile_begin_bitmap(void);122char *__llvm_profile_end_bitmap(void);123ValueProfNode *__llvm_profile_begin_vnodes(void);124ValueProfNode *__llvm_profile_end_vnodes(void);125const VTableProfData *__llvm_profile_begin_vtables(void);126const 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 profile132 * counters and bitmaps. The client is expected to have checked or already133 * know the profile data in the buffer matches the in-process counter134 * structure before calling it. Returns 0 (success) if the profile data is135 * valid. Upon reading invalid/corrupted profile data, returns 1 (failure).136 */137int __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 size142 * \p Size was generated by the same binary and therefore matches143 * structurally the in-process counters and bitmaps. If the profile data in144 * buffer is not compatible, the interface returns 1 (failure).145 */146int __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 */157void INSTR_PROF_VALUE_PROF_FUNC(158#define VALUE_PROF_FUNC_PARAM(ArgType, ArgName, ArgLLVMType) ArgType ArgName159#include "profile/InstrProfData.inc"160 );161 162void __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 */175int __llvm_profile_write_file(void);176 177/*!178 * \brief Set the FILE object for writing instrumentation data. Return 0 if set179 * successfully or return 1 if failed.180 *181 * Sets the FILE object to be used for subsequent calls to182 * \a __llvm_profile_write_file(). The profile file name set by environment183 * variable, command-line option, or calls to \a __llvm_profile_set_filename184 * will be ignored.185 *186 * \c File will not be closed after a call to \a __llvm_profile_write_file() but187 * it may be flushed. Passing NULL restores default behavior.188 *189 * If \c EnableMerge is nonzero, the runtime will always merge profiling data190 * with the contents of the profiling file. If EnableMerge is zero, the runtime191 * may still merge the data if it would have merged for another reason (for192 * example, because of a %m specifier in the file name).193 *194 * Note: There may be multiple copies of the profile runtime (one for each195 * instrumented image/DSO). This API only modifies the file object within the196 * copy of the runtime available to the calling image.197 *198 * Warning: This is a no-op if EnableMerge is 0 in continuous mode (\ref199 * __llvm_profile_is_continuous_mode_enabled), because disable merging requires200 * copying the old profile file to new profile file and this function is usually201 * used when the proess doesn't have permission to open file.202 */203int __llvm_profile_set_file_object(FILE *File, int EnableMerge);204 205/*! \brief Register to write instrumentation data to file at exit. */206int __llvm_profile_register_write_file_atexit(void);207 208/*! \brief Initialize file handling. */209void __llvm_profile_initialize_file(void);210 211/*! \brief Initialize the profile runtime. */212void __llvm_profile_initialize(void);213 214/*! \brief Initialize the gcov profile runtime. */215void __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 do220 * not care about the default raw profile name. It is also useful to collect221 * more than more profile data files dumped in the same directory (Online222 * 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 */225const char *__llvm_profile_get_path_prefix(void);226 227/*!228 * \brief Return filename (including path) of the profile data. Note that if the229 * 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 allocation232 * (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 each235 * instrumented image/DSO). This API only retrieves the filename from the copy236 * of the runtime available to the calling image.237 */238const char *__llvm_profile_get_filename(void);239 240/*! \brief Get the magic token for the file format. */241uint64_t __llvm_profile_get_magic(void);242 243/*! \brief Get the version of the file format. */244uint64_t __llvm_profile_get_version(void);245 246/*! \brief Get the number of entries in the profile data section. */247uint64_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. */251uint64_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. */255size_t __llvm_profile_counter_entry_size(void);256 257/*! \brief Get the number of entries in the profile counters section. */258uint64_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. */261uint64_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. */264uint64_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. */268uint64_t __llvm_profile_get_name_size(const char *Begin, const char *End);269 270/*! \brief Get the number of virtual table profile data entries */271uint64_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. */275uint64_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 the279 * number of padding bytes before and after the counter section, as well as the280 * number of padding bytes after other sections in the raw profile.281 * Returns -1 upon errors and 0 upon success. Output parameters should be used282 * iff return value is 0.283 *284 * Note: When mmap() mode is disabled, no padding bytes before/after counters285 * are needed. However, in mmap() mode, the counter section in the raw profile286 * must be page-aligned: this API computes the number of padding bytes287 * needed to achieve that.288 */289int __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 for299 * certain processes in case the processes don't have permission to write to300 * the disks, and trying to do so would result in side effects such as crashes.301 */302void __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 */308int __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 hidden318 * symbol. Its main purpose is to enable profile runtime user to319 * bypass runtime initialization code -- if the client code explicitly320 * define this variable, then InstProfileRuntime.o won't be linked in.321 * Note that this variable's visibility needs to be hidden so that the322 * definition of this variable in an instrumented shared library won't323 * affect runtime initialization decision of the main program.324 * __llvm_profile_profile_runtime. */325COMPILER_RT_VISIBILITY extern int INSTR_PROF_PROFILE_RUNTIME_VAR;326 327/*!328 * This variable is defined in InstrProfilingVersionVar.c as a hidden symbol329 * (except on Apple platforms where this symbol is checked by TAPI). Its main330 * purpose is to encode the raw profile version value and other format related331 * information such as whether the profile is from IR based instrumentation. The332 * variable is defined as weak so that compiler can emit an overriding333 * definition depending on user option.334 */335COMPILER_RT_VISIBILITY extern uint64_t336 INSTR_PROF_RAW_VERSION_VAR; /* __llvm_profile_raw_version */337 338/*!339 * This variable is a weak symbol defined in InstrProfiling.c. It allows340 * compiler instrumentation to provide overriding definition with value341 * from compiler command line. This variable has default visibility.342 */343extern char INSTR_PROF_PROFILE_NAME_VAR[1]; /* __llvm_profile_filename. */344 345const __llvm_gcov_init_func_struct *__llvm_profile_begin_covinit();346const __llvm_gcov_init_func_struct *__llvm_profile_end_covinit();347#endif /* PROFILE_INSTRPROFILING_H_ */348