llvm-project/llvm/include/llvm-c/Remarks.h

203 lines
5.5 KiB
C
Raw Normal View History

/*===-- llvm-c/Remarks.h - Remarks Public C Interface -------------*- C -*-===*\
|* *|
|* Part of the LLVM Project, under the Apache License v2.0 with LLVM *|
|* Exceptions. *|
|* See https://llvm.org/LICENSE.txt for license information. *|
|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception *|
|* *|
|*===----------------------------------------------------------------------===*|
|* *|
|* This header provides a public interface to a remark diagnostics library. *|
|* LLVM provides an implementation of this interface. *|
|* *|
\*===----------------------------------------------------------------------===*/
#ifndef LLVM_C_REMARKS_H
#define LLVM_C_REMARKS_H
#include "llvm-c/Core.h"
#include "llvm-c/Types.h"
#ifdef __cplusplus
#include <cstddef>
extern "C" {
#else
#include <stddef.h>
#endif /* !defined(__cplusplus) */
/**
* @defgroup LLVMCREMARKS Remarks
* @ingroup LLVMC
*
* @{
*/
#define REMARKS_API_VERSION 0
/**
* String containing a buffer and a length. The buffer is not guaranteed to be
* zero-terminated.
*
* \since REMARKS_API_VERSION=0
*/
typedef struct {
const char *Str;
uint32_t Len;
} LLVMRemarkStringRef;
/**
* DebugLoc containing File, Line and Column.
*
* \since REMARKS_API_VERSION=0
*/
typedef struct {
// File:
LLVMRemarkStringRef SourceFile;
// Line:
uint32_t SourceLineNumber;
// Column:
uint32_t SourceColumnNumber;
} LLVMRemarkDebugLoc;
/**
* Element of the "Args" list. The key might give more information about what
* are the semantics of the value, e.g. "Callee" will tell you that the value
* is a symbol that names a function.
*
* \since REMARKS_API_VERSION=0
*/
typedef struct {
// e.g. "Callee"
LLVMRemarkStringRef Key;
// e.g. "malloc"
LLVMRemarkStringRef Value;
// "DebugLoc": Optional
LLVMRemarkDebugLoc DebugLoc;
} LLVMRemarkArg;
/**
* One remark entry.
*
* \since REMARKS_API_VERSION=0
*/
typedef struct {
// e.g. !Missed, !Passed
LLVMRemarkStringRef RemarkType;
// "Pass": Required
LLVMRemarkStringRef PassName;
// "Name": Required
LLVMRemarkStringRef RemarkName;
// "Function": Required
LLVMRemarkStringRef FunctionName;
// "DebugLoc": Optional
LLVMRemarkDebugLoc DebugLoc;
// "Hotness": Optional
uint32_t Hotness;
// "Args": Optional. It is an array of `num_args` elements.
uint32_t NumArgs;
LLVMRemarkArg *Args;
} LLVMRemarkEntry;
typedef struct LLVMRemarkOpaqueParser *LLVMRemarkParserRef;
/**
* Creates a remark parser that can be used to read and parse the buffer located
* in \p Buf of size \p Size.
*
* \p Buf cannot be NULL.
*
* This function should be paired with LLVMRemarkParserDispose() to avoid
* leaking resources.
*
* \since REMARKS_API_VERSION=0
*/
extern LLVMRemarkParserRef LLVMRemarkParserCreate(const void *Buf,
uint64_t Size);
/**
* Returns the next remark in the file.
*
* The value pointed to by the return value is invalidated by the next call to
* LLVMRemarkParserGetNext().
*
* If the parser reaches the end of the buffer, the return value will be NULL.
*
* In the case of an error, the return value will be NULL, and:
*
* 1) LLVMRemarkParserHasError() will return `1`.
*
* 2) LLVMRemarkParserGetErrorMessage() will return a descriptive error
* message.
*
* An error may occur if:
*
* 1) An argument is invalid.
*
* 2) There is a YAML parsing error. This type of error aborts parsing
* immediately and returns `1`. It can occur on malformed YAML.
*
* 3) Remark parsing error. If this type of error occurs, the parser won't call
* the handler and will continue to the next one. It can occur on malformed
* remarks, like missing or extra fields in the file.
*
* Here is a quick example of the usage:
*
* ```
* LLVMRemarkParserRef Parser = LLVMRemarkParserCreate(Buf, Size);
* LLVMRemarkEntry *Remark = NULL;
* while ((Remark == LLVMRemarkParserGetNext(Parser))) {
* // use Remark
* }
* bool HasError = LLVMRemarkParserHasError(Parser);
* LLVMRemarkParserDispose(Parser);
* ```
*
* \since REMARKS_API_VERSION=0
*/
extern LLVMRemarkEntry *LLVMRemarkParserGetNext(LLVMRemarkParserRef Parser);
/**
* Returns `1` if the parser encountered an error while parsing the buffer.
*
* \since REMARKS_API_VERSION=0
*/
extern LLVMBool LLVMRemarkParserHasError(LLVMRemarkParserRef Parser);
/**
* Returns a null-terminated string containing an error message.
*
* In case of no error, the result is `NULL`.
*
* The memory of the string is bound to the lifetime of \p Parser. If
* LLVMRemarkParserDispose() is called, the memory of the string will be
* released.
*
* \since REMARKS_API_VERSION=0
*/
extern const char *LLVMRemarkParserGetErrorMessage(LLVMRemarkParserRef Parser);
/**
* Releases all the resources used by \p Parser.
*
* \since REMARKS_API_VERSION=0
*/
extern void LLVMRemarkParserDispose(LLVMRemarkParserRef Parser);
/**
* Returns the version of the remarks dylib.
*
* \since REMARKS_API_VERSION=0
*/
extern uint32_t LLVMRemarkVersion(void);
/**
* @} // endgoup LLVMCREMARKS
*/
#ifdef __cplusplus
}
#endif /* !defined(__cplusplus) */
#endif /* LLVM_C_REMARKS_H */