355 lines · c
1/*===-- llvm-c/Remarks.h - Remarks Public C Interface -------------*- C -*-===*\2|* *|3|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|4|* Exceptions. *|5|* See https://llvm.org/LICENSE.txt for license information. *|6|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|7|* *|8|*===----------------------------------------------------------------------===*|9|* *|10|* This header provides a public interface to a remark diagnostics library. *|11|* LLVM provides an implementation of this interface. *|12|* *|13\*===----------------------------------------------------------------------===*/14 15#ifndef LLVM_C_REMARKS_H16#define LLVM_C_REMARKS_H17 18#include "llvm-c/ExternC.h"19#include "llvm-c/Types.h"20#include "llvm-c/Visibility.h"21#ifdef __cplusplus22#include <cstddef>23#else24#include <stddef.h>25#endif /* !defined(__cplusplus) */26 27LLVM_C_EXTERN_C_BEGIN28 29/**30 * @defgroup LLVMCREMARKS Remarks31 * @ingroup LLVMC32 *33 * @{34 */35 36// 0 -> 1: Bitstream remarks support.37#define REMARKS_API_VERSION 138 39/**40 * The type of the emitted remark.41 */42enum LLVMRemarkType {43 LLVMRemarkTypeUnknown,44 LLVMRemarkTypePassed,45 LLVMRemarkTypeMissed,46 LLVMRemarkTypeAnalysis,47 LLVMRemarkTypeAnalysisFPCommute,48 LLVMRemarkTypeAnalysisAliasing,49 LLVMRemarkTypeFailure50};51 52/**53 * String containing a buffer and a length. The buffer is not guaranteed to be54 * zero-terminated.55 *56 * \since REMARKS_API_VERSION=057 */58typedef struct LLVMRemarkOpaqueString *LLVMRemarkStringRef;59 60/**61 * Returns the buffer holding the string.62 *63 * \since REMARKS_API_VERSION=064 */65LLVM_C_ABI extern const char *66LLVMRemarkStringGetData(LLVMRemarkStringRef String);67 68/**69 * Returns the size of the string.70 *71 * \since REMARKS_API_VERSION=072 */73LLVM_C_ABI extern uint32_t LLVMRemarkStringGetLen(LLVMRemarkStringRef String);74 75/**76 * DebugLoc containing File, Line and Column.77 *78 * \since REMARKS_API_VERSION=079 */80typedef struct LLVMRemarkOpaqueDebugLoc *LLVMRemarkDebugLocRef;81 82/**83 * Return the path to the source file for a debug location.84 *85 * \since REMARKS_API_VERSION=086 */87LLVM_C_ABI extern LLVMRemarkStringRef88LLVMRemarkDebugLocGetSourceFilePath(LLVMRemarkDebugLocRef DL);89 90/**91 * Return the line in the source file for a debug location.92 *93 * \since REMARKS_API_VERSION=094 */95LLVM_C_ABI extern uint32_t96LLVMRemarkDebugLocGetSourceLine(LLVMRemarkDebugLocRef DL);97 98/**99 * Return the column in the source file for a debug location.100 *101 * \since REMARKS_API_VERSION=0102 */103LLVM_C_ABI extern uint32_t104LLVMRemarkDebugLocGetSourceColumn(LLVMRemarkDebugLocRef DL);105 106/**107 * Element of the "Args" list. The key might give more information about what108 * the semantics of the value are, e.g. "Callee" will tell you that the value109 * is a symbol that names a function.110 *111 * \since REMARKS_API_VERSION=0112 */113typedef struct LLVMRemarkOpaqueArg *LLVMRemarkArgRef;114 115/**116 * Returns the key of an argument. The key defines what the value is, and the117 * same key can appear multiple times in the list of arguments.118 *119 * \since REMARKS_API_VERSION=0120 */121LLVM_C_ABI extern LLVMRemarkStringRef LLVMRemarkArgGetKey(LLVMRemarkArgRef Arg);122 123/**124 * Returns the value of an argument. This is a string that can contain newlines.125 *126 * \since REMARKS_API_VERSION=0127 */128LLVM_C_ABI extern LLVMRemarkStringRef129LLVMRemarkArgGetValue(LLVMRemarkArgRef Arg);130 131/**132 * Returns the debug location that is attached to the value of this argument.133 *134 * If there is no debug location, the return value will be `NULL`.135 *136 * \since REMARKS_API_VERSION=0137 */138LLVM_C_ABI extern LLVMRemarkDebugLocRef139LLVMRemarkArgGetDebugLoc(LLVMRemarkArgRef Arg);140 141/**142 * A remark emitted by the compiler.143 *144 * \since REMARKS_API_VERSION=0145 */146typedef struct LLVMRemarkOpaqueEntry *LLVMRemarkEntryRef;147 148/**149 * Free the resources used by the remark entry.150 *151 * \since REMARKS_API_VERSION=0152 */153LLVM_C_ABI extern void LLVMRemarkEntryDispose(LLVMRemarkEntryRef Remark);154 155/**156 * The type of the remark. For example, it can allow users to only keep the157 * missed optimizations from the compiler.158 *159 * \since REMARKS_API_VERSION=0160 */161LLVM_C_ABI extern enum LLVMRemarkType162LLVMRemarkEntryGetType(LLVMRemarkEntryRef Remark);163 164/**165 * Get the name of the pass that emitted this remark.166 *167 * \since REMARKS_API_VERSION=0168 */169LLVM_C_ABI extern LLVMRemarkStringRef170LLVMRemarkEntryGetPassName(LLVMRemarkEntryRef Remark);171 172/**173 * Get an identifier of the remark.174 *175 * \since REMARKS_API_VERSION=0176 */177LLVM_C_ABI extern LLVMRemarkStringRef178LLVMRemarkEntryGetRemarkName(LLVMRemarkEntryRef Remark);179 180/**181 * Get the name of the function being processed when the remark was emitted.182 *183 * \since REMARKS_API_VERSION=0184 */185LLVM_C_ABI extern LLVMRemarkStringRef186LLVMRemarkEntryGetFunctionName(LLVMRemarkEntryRef Remark);187 188/**189 * Returns the debug location that is attached to this remark.190 *191 * If there is no debug location, the return value will be `NULL`.192 *193 * \since REMARKS_API_VERSION=0194 */195LLVM_C_ABI extern LLVMRemarkDebugLocRef196LLVMRemarkEntryGetDebugLoc(LLVMRemarkEntryRef Remark);197 198/**199 * Return the hotness of the remark.200 *201 * A hotness of `0` means this value is not set.202 *203 * \since REMARKS_API_VERSION=0204 */205LLVM_C_ABI extern uint64_t LLVMRemarkEntryGetHotness(LLVMRemarkEntryRef Remark);206 207/**208 * The number of arguments the remark holds.209 *210 * \since REMARKS_API_VERSION=0211 */212LLVM_C_ABI extern uint32_t LLVMRemarkEntryGetNumArgs(LLVMRemarkEntryRef Remark);213 214/**215 * Get a new iterator to iterate over a remark's argument.216 *217 * If there are no arguments in \p Remark, the return value will be `NULL`.218 *219 * The lifetime of the returned value is bound to the lifetime of \p Remark.220 *221 * \since REMARKS_API_VERSION=0222 */223LLVM_C_ABI extern LLVMRemarkArgRef224LLVMRemarkEntryGetFirstArg(LLVMRemarkEntryRef Remark);225 226/**227 * Get the next argument in \p Remark from the position of \p It.228 *229 * Returns `NULL` if there are no more arguments available.230 *231 * The lifetime of the returned value is bound to the lifetime of \p Remark.232 *233 * \since REMARKS_API_VERSION=0234 */235LLVM_C_ABI extern LLVMRemarkArgRef236LLVMRemarkEntryGetNextArg(LLVMRemarkArgRef It, LLVMRemarkEntryRef Remark);237 238typedef struct LLVMRemarkOpaqueParser *LLVMRemarkParserRef;239 240/**241 * Creates a remark parser that can be used to parse the buffer located in \p242 * Buf of size \p Size bytes.243 *244 * \p Buf cannot be `NULL`.245 *246 * This function should be paired with LLVMRemarkParserDispose() to avoid247 * leaking resources.248 *249 * \since REMARKS_API_VERSION=0250 */251LLVM_C_ABI extern LLVMRemarkParserRef252LLVMRemarkParserCreateYAML(const void *Buf, uint64_t Size);253 254/**255 * Creates a remark parser that can be used to parse the buffer located in \p256 * Buf of size \p Size bytes.257 *258 * \p Buf cannot be `NULL`.259 *260 * This function should be paired with LLVMRemarkParserDispose() to avoid261 * leaking resources.262 *263 * \since REMARKS_API_VERSION=1264 */265LLVM_C_ABI extern LLVMRemarkParserRef266LLVMRemarkParserCreateBitstream(const void *Buf, uint64_t Size);267 268/**269 * Returns the next remark in the file.270 *271 * The value pointed to by the return value needs to be disposed using a call to272 * LLVMRemarkEntryDispose().273 *274 * All the entries in the returned value that are of LLVMRemarkStringRef type275 * will become invalidated once a call to LLVMRemarkParserDispose is made.276 *277 * If the parser reaches the end of the buffer, the return value will be `NULL`.278 *279 * In the case of an error, the return value will be `NULL`, and:280 *281 * 1) LLVMRemarkParserHasError() will return `1`.282 *283 * 2) LLVMRemarkParserGetErrorMessage() will return a descriptive error284 * message.285 *286 * An error may occur if:287 *288 * 1) An argument is invalid.289 *290 * 2) There is a parsing error. This can occur on things like malformed YAML.291 *292 * 3) There is a Remark semantic error. This can occur on well-formed files with293 * missing or extra fields.294 *295 * Here is a quick example of the usage:296 *297 * ```298 * LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);299 * LLVMRemarkEntryRef Remark = NULL;300 * while ((Remark = LLVMRemarkParserGetNext(Parser))) {301 * // use Remark302 * LLVMRemarkEntryDispose(Remark); // Release memory.303 * }304 * bool HasError = LLVMRemarkParserHasError(Parser);305 * LLVMRemarkParserDispose(Parser);306 * ```307 *308 * \since REMARKS_API_VERSION=0309 */310LLVM_C_ABI extern LLVMRemarkEntryRef311LLVMRemarkParserGetNext(LLVMRemarkParserRef Parser);312 313/**314 * Returns `1` if the parser encountered an error while parsing the buffer.315 *316 * \since REMARKS_API_VERSION=0317 */318LLVM_C_ABI extern LLVMBool LLVMRemarkParserHasError(LLVMRemarkParserRef Parser);319 320/**321 * Returns a null-terminated string containing an error message.322 *323 * In case of no error, the result is `NULL`.324 *325 * The memory of the string is bound to the lifetime of \p Parser. If326 * LLVMRemarkParserDispose() is called, the memory of the string will be327 * released.328 *329 * \since REMARKS_API_VERSION=0330 */331LLVM_C_ABI extern const char *332LLVMRemarkParserGetErrorMessage(LLVMRemarkParserRef Parser);333 334/**335 * Releases all the resources used by \p Parser.336 *337 * \since REMARKS_API_VERSION=0338 */339LLVM_C_ABI extern void LLVMRemarkParserDispose(LLVMRemarkParserRef Parser);340 341/**342 * Returns the version of the remarks library.343 *344 * \since REMARKS_API_VERSION=0345 */346extern uint32_t LLVMRemarkVersion(void);347 348/**349 * @} // endgoup LLVMCREMARKS350 */351 352LLVM_C_EXTERN_C_END353 354#endif /* LLVM_C_REMARKS_H */355