1//===------------ DebugInfo.h - LLVM C API Debug Info API -----------------===//
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/// This file declares the C API endpoints for generating DWARF Debug Info
10///
11/// Note: This interface is experimental. It is *NOT* stable, and may be
12///       changed without warning.
13///
14//===----------------------------------------------------------------------===//
15
16#ifndef LLVM_C_DEBUGINFO_H
17#define LLVM_C_DEBUGINFO_H
18
19#include "llvm-c/Core.h"
20#include "llvm-c/ExternC.h"
21
22LLVM_C_EXTERN_C_BEGIN
23
24/**
25 * Debug info flags.
26 */
27typedef enum {
28  LLVMDIFlagZero = 0,
29  LLVMDIFlagPrivate = 1,
30  LLVMDIFlagProtected = 2,
31  LLVMDIFlagPublic = 3,
32  LLVMDIFlagFwdDecl = 1 << 2,
33  LLVMDIFlagAppleBlock = 1 << 3,
34  LLVMDIFlagReservedBit4 = 1 << 4,
35  LLVMDIFlagVirtual = 1 << 5,
36  LLVMDIFlagArtificial = 1 << 6,
37  LLVMDIFlagExplicit = 1 << 7,
38  LLVMDIFlagPrototyped = 1 << 8,
39  LLVMDIFlagObjcClassComplete = 1 << 9,
40  LLVMDIFlagObjectPointer = 1 << 10,
41  LLVMDIFlagVector = 1 << 11,
42  LLVMDIFlagStaticMember = 1 << 12,
43  LLVMDIFlagLValueReference = 1 << 13,
44  LLVMDIFlagRValueReference = 1 << 14,
45  LLVMDIFlagReserved = 1 << 15,
46  LLVMDIFlagSingleInheritance = 1 << 16,
47  LLVMDIFlagMultipleInheritance = 2 << 16,
48  LLVMDIFlagVirtualInheritance = 3 << 16,
49  LLVMDIFlagIntroducedVirtual = 1 << 18,
50  LLVMDIFlagBitField = 1 << 19,
51  LLVMDIFlagNoReturn = 1 << 20,
52  LLVMDIFlagTypePassByValue = 1 << 22,
53  LLVMDIFlagTypePassByReference = 1 << 23,
54  LLVMDIFlagEnumClass = 1 << 24,
55  LLVMDIFlagFixedEnum = LLVMDIFlagEnumClass, // Deprecated.
56  LLVMDIFlagThunk = 1 << 25,
57  LLVMDIFlagNonTrivial = 1 << 26,
58  LLVMDIFlagBigEndian = 1 << 27,
59  LLVMDIFlagLittleEndian = 1 << 28,
60  LLVMDIFlagIndirectVirtualBase = (1 << 2) | (1 << 5),
61  LLVMDIFlagAccessibility = LLVMDIFlagPrivate | LLVMDIFlagProtected |
62                            LLVMDIFlagPublic,
63  LLVMDIFlagPtrToMemberRep = LLVMDIFlagSingleInheritance |
64                             LLVMDIFlagMultipleInheritance |
65                             LLVMDIFlagVirtualInheritance
66} LLVMDIFlags;
67
68/**
69 * Source languages known by DWARF.
70 */
71typedef enum {
72  LLVMDWARFSourceLanguageC89,
73  LLVMDWARFSourceLanguageC,
74  LLVMDWARFSourceLanguageAda83,
75  LLVMDWARFSourceLanguageC_plus_plus,
76  LLVMDWARFSourceLanguageCobol74,
77  LLVMDWARFSourceLanguageCobol85,
78  LLVMDWARFSourceLanguageFortran77,
79  LLVMDWARFSourceLanguageFortran90,
80  LLVMDWARFSourceLanguagePascal83,
81  LLVMDWARFSourceLanguageModula2,
82  // New in DWARF v3:
83  LLVMDWARFSourceLanguageJava,
84  LLVMDWARFSourceLanguageC99,
85  LLVMDWARFSourceLanguageAda95,
86  LLVMDWARFSourceLanguageFortran95,
87  LLVMDWARFSourceLanguagePLI,
88  LLVMDWARFSourceLanguageObjC,
89  LLVMDWARFSourceLanguageObjC_plus_plus,
90  LLVMDWARFSourceLanguageUPC,
91  LLVMDWARFSourceLanguageD,
92  // New in DWARF v4:
93  LLVMDWARFSourceLanguagePython,
94  // New in DWARF v5:
95  LLVMDWARFSourceLanguageOpenCL,
96  LLVMDWARFSourceLanguageGo,
97  LLVMDWARFSourceLanguageModula3,
98  LLVMDWARFSourceLanguageHaskell,
99  LLVMDWARFSourceLanguageC_plus_plus_03,
100  LLVMDWARFSourceLanguageC_plus_plus_11,
101  LLVMDWARFSourceLanguageOCaml,
102  LLVMDWARFSourceLanguageRust,
103  LLVMDWARFSourceLanguageC11,
104  LLVMDWARFSourceLanguageSwift,
105  LLVMDWARFSourceLanguageJulia,
106  LLVMDWARFSourceLanguageDylan,
107  LLVMDWARFSourceLanguageC_plus_plus_14,
108  LLVMDWARFSourceLanguageFortran03,
109  LLVMDWARFSourceLanguageFortran08,
110  LLVMDWARFSourceLanguageRenderScript,
111  LLVMDWARFSourceLanguageBLISS,
112  // Vendor extensions:
113  LLVMDWARFSourceLanguageMips_Assembler,
114  LLVMDWARFSourceLanguageGOOGLE_RenderScript,
115  LLVMDWARFSourceLanguageBORLAND_Delphi
116} LLVMDWARFSourceLanguage;
117
118/**
119 * The amount of debug information to emit.
120 */
121typedef enum {
122    LLVMDWARFEmissionNone = 0,
123    LLVMDWARFEmissionFull,
124    LLVMDWARFEmissionLineTablesOnly
125} LLVMDWARFEmissionKind;
126
127/**
128 * The kind of metadata nodes.
129 */
130enum {
131  LLVMMDStringMetadataKind,
132  LLVMConstantAsMetadataMetadataKind,
133  LLVMLocalAsMetadataMetadataKind,
134  LLVMDistinctMDOperandPlaceholderMetadataKind,
135  LLVMMDTupleMetadataKind,
136  LLVMDILocationMetadataKind,
137  LLVMDIExpressionMetadataKind,
138  LLVMDIGlobalVariableExpressionMetadataKind,
139  LLVMGenericDINodeMetadataKind,
140  LLVMDISubrangeMetadataKind,
141  LLVMDIEnumeratorMetadataKind,
142  LLVMDIBasicTypeMetadataKind,
143  LLVMDIDerivedTypeMetadataKind,
144  LLVMDICompositeTypeMetadataKind,
145  LLVMDISubroutineTypeMetadataKind,
146  LLVMDIFileMetadataKind,
147  LLVMDICompileUnitMetadataKind,
148  LLVMDISubprogramMetadataKind,
149  LLVMDILexicalBlockMetadataKind,
150  LLVMDILexicalBlockFileMetadataKind,
151  LLVMDINamespaceMetadataKind,
152  LLVMDIModuleMetadataKind,
153  LLVMDITemplateTypeParameterMetadataKind,
154  LLVMDITemplateValueParameterMetadataKind,
155  LLVMDIGlobalVariableMetadataKind,
156  LLVMDILocalVariableMetadataKind,
157  LLVMDILabelMetadataKind,
158  LLVMDIObjCPropertyMetadataKind,
159  LLVMDIImportedEntityMetadataKind,
160  LLVMDIMacroMetadataKind,
161  LLVMDIMacroFileMetadataKind,
162  LLVMDICommonBlockMetadataKind
163};
164typedef unsigned LLVMMetadataKind;
165
166/**
167 * An LLVM DWARF type encoding.
168 */
169typedef unsigned LLVMDWARFTypeEncoding;
170
171/**
172 * Describes the kind of macro declaration used for LLVMDIBuilderCreateMacro.
173 * @see llvm::dwarf::MacinfoRecordType
174 * @note Values are from DW_MACINFO_* constants in the DWARF specification.
175 */
176typedef enum {
177  LLVMDWARFMacinfoRecordTypeDefine = 0x01,
178  LLVMDWARFMacinfoRecordTypeMacro = 0x02,
179  LLVMDWARFMacinfoRecordTypeStartFile = 0x03,
180  LLVMDWARFMacinfoRecordTypeEndFile = 0x04,
181  LLVMDWARFMacinfoRecordTypeVendorExt = 0xff
182} LLVMDWARFMacinfoRecordType;
183
184/**
185 * The current debug metadata version number.
186 */
187unsigned LLVMDebugMetadataVersion(void);
188
189/**
190 * The version of debug metadata that's present in the provided \c Module.
191 */
192unsigned LLVMGetModuleDebugMetadataVersion(LLVMModuleRef Module);
193
194/**
195 * Strip debug info in the module if it exists.
196 * To do this, we remove all calls to the debugger intrinsics and any named
197 * metadata for debugging. We also remove debug locations for instructions.
198 * Return true if module is modified.
199 */
200LLVMBool LLVMStripModuleDebugInfo(LLVMModuleRef Module);
201
202/**
203 * Construct a builder for a module, and do not allow for unresolved nodes
204 * attached to the module.
205 */
206LLVMDIBuilderRef LLVMCreateDIBuilderDisallowUnresolved(LLVMModuleRef M);
207
208/**
209 * Construct a builder for a module and collect unresolved nodes attached
210 * to the module in order to resolve cycles during a call to
211 * \c LLVMDIBuilderFinalize.
212 */
213LLVMDIBuilderRef LLVMCreateDIBuilder(LLVMModuleRef M);
214
215/**
216 * Deallocates the \c DIBuilder and everything it owns.
217 * @note You must call \c LLVMDIBuilderFinalize before this
218 */
219void LLVMDisposeDIBuilder(LLVMDIBuilderRef Builder);
220
221/**
222 * Construct any deferred debug info descriptors.
223 */
224void LLVMDIBuilderFinalize(LLVMDIBuilderRef Builder);
225
226/**
227 * A CompileUnit provides an anchor for all debugging
228 * information generated during this instance of compilation.
229 * \param Lang          Source programming language, eg.
230 *                      \c LLVMDWARFSourceLanguageC99
231 * \param FileRef       File info.
232 * \param Producer      Identify the producer of debugging information
233 *                      and code.  Usually this is a compiler
234 *                      version string.
235 * \param ProducerLen   The length of the C string passed to \c Producer.
236 * \param isOptimized   A boolean flag which indicates whether optimization
237 *                      is enabled or not.
238 * \param Flags         This string lists command line options. This
239 *                      string is directly embedded in debug info
240 *                      output which may be used by a tool
241 *                      analyzing generated debugging information.
242 * \param FlagsLen      The length of the C string passed to \c Flags.
243 * \param RuntimeVer    This indicates runtime version for languages like
244 *                      Objective-C.
245 * \param SplitName     The name of the file that we'll split debug info
246 *                      out into.
247 * \param SplitNameLen  The length of the C string passed to \c SplitName.
248 * \param Kind          The kind of debug information to generate.
249 * \param DWOId         The DWOId if this is a split skeleton compile unit.
250 * \param SplitDebugInlining    Whether to emit inline debug info.
251 * \param DebugInfoForProfiling Whether to emit extra debug info for
252 *                              profile collection.
253 * \param SysRoot         The Clang system root (value of -isysroot).
254 * \param SysRootLen      The length of the C string passed to \c SysRoot.
255 * \param SDK           The SDK. On Darwin, the last component of the sysroot.
256 * \param SDKLen        The length of the C string passed to \c SDK.
257 */
258LLVMMetadataRef LLVMDIBuilderCreateCompileUnit(
259    LLVMDIBuilderRef Builder, LLVMDWARFSourceLanguage Lang,
260    LLVMMetadataRef FileRef, const char *Producer, size_t ProducerLen,
261    LLVMBool isOptimized, const char *Flags, size_t FlagsLen,
262    unsigned RuntimeVer, const char *SplitName, size_t SplitNameLen,
263    LLVMDWARFEmissionKind Kind, unsigned DWOId, LLVMBool SplitDebugInlining,
264    LLVMBool DebugInfoForProfiling, const char *SysRoot, size_t SysRootLen,
265    const char *SDK, size_t SDKLen);
266
267/**
268 * Create a file descriptor to hold debugging information for a file.
269 * \param Builder      The \c DIBuilder.
270 * \param Filename     File name.
271 * \param FilenameLen  The length of the C string passed to \c Filename.
272 * \param Directory    Directory.
273 * \param DirectoryLen The length of the C string passed to \c Directory.
274 */
275LLVMMetadataRef
276LLVMDIBuilderCreateFile(LLVMDIBuilderRef Builder, const char *Filename,
277                        size_t FilenameLen, const char *Directory,
278                        size_t DirectoryLen);
279
280/**
281 * Creates a new descriptor for a module with the specified parent scope.
282 * \param Builder         The \c DIBuilder.
283 * \param ParentScope     The parent scope containing this module declaration.
284 * \param Name            Module name.
285 * \param NameLen         The length of the C string passed to \c Name.
286 * \param ConfigMacros    A space-separated shell-quoted list of -D macro
287                          definitions as they would appear on a command line.
288 * \param ConfigMacrosLen The length of the C string passed to \c ConfigMacros.
289 * \param IncludePath     The path to the module map file.
290 * \param IncludePathLen  The length of the C string passed to \c IncludePath.
291 * \param APINotesFile    The path to an API notes file for the module.
292 * \param APINotesFileLen The length of the C string passed to \c APINotestFile.
293 */
294LLVMMetadataRef
295LLVMDIBuilderCreateModule(LLVMDIBuilderRef Builder, LLVMMetadataRef ParentScope,
296                          const char *Name, size_t NameLen,
297                          const char *ConfigMacros, size_t ConfigMacrosLen,
298                          const char *IncludePath, size_t IncludePathLen,
299                          const char *APINotesFile, size_t APINotesFileLen);
300
301/**
302 * Creates a new descriptor for a namespace with the specified parent scope.
303 * \param Builder          The \c DIBuilder.
304 * \param ParentScope      The parent scope containing this module declaration.
305 * \param Name             NameSpace name.
306 * \param NameLen          The length of the C string passed to \c Name.
307 * \param ExportSymbols    Whether or not the namespace exports symbols, e.g.
308 *                         this is true of C++ inline namespaces.
309 */
310LLVMMetadataRef
311LLVMDIBuilderCreateNameSpace(LLVMDIBuilderRef Builder,
312                             LLVMMetadataRef ParentScope,
313                             const char *Name, size_t NameLen,
314                             LLVMBool ExportSymbols);
315
316/**
317 * Create a new descriptor for the specified subprogram.
318 * \param Builder         The \c DIBuilder.
319 * \param Scope           Function scope.
320 * \param Name            Function name.
321 * \param NameLen         Length of enumeration name.
322 * \param LinkageName     Mangled function name.
323 * \param LinkageNameLen  Length of linkage name.
324 * \param File            File where this variable is defined.
325 * \param LineNo          Line number.
326 * \param Ty              Function type.
327 * \param IsLocalToUnit   True if this function is not externally visible.
328 * \param IsDefinition    True if this is a function definition.
329 * \param ScopeLine       Set to the beginning of the scope this starts
330 * \param Flags           E.g.: \c LLVMDIFlagLValueReference. These flags are
331 *                        used to emit dwarf attributes.
332 * \param IsOptimized     True if optimization is ON.
333 */
334LLVMMetadataRef LLVMDIBuilderCreateFunction(
335    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
336    size_t NameLen, const char *LinkageName, size_t LinkageNameLen,
337    LLVMMetadataRef File, unsigned LineNo, LLVMMetadataRef Ty,
338    LLVMBool IsLocalToUnit, LLVMBool IsDefinition,
339    unsigned ScopeLine, LLVMDIFlags Flags, LLVMBool IsOptimized);
340
341/**
342 * Create a descriptor for a lexical block with the specified parent context.
343 * \param Builder      The \c DIBuilder.
344 * \param Scope        Parent lexical block.
345 * \param File         Source file.
346 * \param Line         The line in the source file.
347 * \param Column       The column in the source file.
348 */
349LLVMMetadataRef LLVMDIBuilderCreateLexicalBlock(
350    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope,
351    LLVMMetadataRef File, unsigned Line, unsigned Column);
352
353/**
354 * Create a descriptor for a lexical block with a new file attached.
355 * \param Builder        The \c DIBuilder.
356 * \param Scope          Lexical block.
357 * \param File           Source file.
358 * \param Discriminator  DWARF path discriminator value.
359 */
360LLVMMetadataRef
361LLVMDIBuilderCreateLexicalBlockFile(LLVMDIBuilderRef Builder,
362                                    LLVMMetadataRef Scope,
363                                    LLVMMetadataRef File,
364                                    unsigned Discriminator);
365
366/**
367 * Create a descriptor for an imported namespace. Suitable for e.g. C++
368 * using declarations.
369 * \param Builder    The \c DIBuilder.
370 * \param Scope      The scope this module is imported into
371 * \param File       File where the declaration is located.
372 * \param Line       Line number of the declaration.
373 */
374LLVMMetadataRef
375LLVMDIBuilderCreateImportedModuleFromNamespace(LLVMDIBuilderRef Builder,
376                                               LLVMMetadataRef Scope,
377                                               LLVMMetadataRef NS,
378                                               LLVMMetadataRef File,
379                                               unsigned Line);
380
381/**
382 * Create a descriptor for an imported module that aliases another
383 * imported entity descriptor.
384 * \param Builder        The \c DIBuilder.
385 * \param Scope          The scope this module is imported into
386 * \param ImportedEntity Previous imported entity to alias.
387 * \param File           File where the declaration is located.
388 * \param Line           Line number of the declaration.
389 */
390LLVMMetadataRef
391LLVMDIBuilderCreateImportedModuleFromAlias(LLVMDIBuilderRef Builder,
392                                           LLVMMetadataRef Scope,
393                                           LLVMMetadataRef ImportedEntity,
394                                           LLVMMetadataRef File,
395                                           unsigned Line);
396
397/**
398 * Create a descriptor for an imported module.
399 * \param Builder    The \c DIBuilder.
400 * \param Scope      The scope this module is imported into
401 * \param M          The module being imported here
402 * \param File       File where the declaration is located.
403 * \param Line       Line number of the declaration.
404 */
405LLVMMetadataRef
406LLVMDIBuilderCreateImportedModuleFromModule(LLVMDIBuilderRef Builder,
407                                            LLVMMetadataRef Scope,
408                                            LLVMMetadataRef M,
409                                            LLVMMetadataRef File,
410                                            unsigned Line);
411
412/**
413 * Create a descriptor for an imported function, type, or variable.  Suitable
414 * for e.g. FORTRAN-style USE declarations.
415 * \param Builder    The DIBuilder.
416 * \param Scope      The scope this module is imported into.
417 * \param Decl       The declaration (or definition) of a function, type,
418                     or variable.
419 * \param File       File where the declaration is located.
420 * \param Line       Line number of the declaration.
421 * \param Name       A name that uniquely identifies this imported declaration.
422 * \param NameLen    The length of the C string passed to \c Name.
423 */
424LLVMMetadataRef
425LLVMDIBuilderCreateImportedDeclaration(LLVMDIBuilderRef Builder,
426                                       LLVMMetadataRef Scope,
427                                       LLVMMetadataRef Decl,
428                                       LLVMMetadataRef File,
429                                       unsigned Line,
430                                       const char *Name, size_t NameLen);
431
432/**
433 * Creates a new DebugLocation that describes a source location.
434 * \param Line The line in the source file.
435 * \param Column The column in the source file.
436 * \param Scope The scope in which the location resides.
437 * \param InlinedAt The scope where this location was inlined, if at all.
438 *                  (optional).
439 * \note If the item to which this location is attached cannot be
440 *       attributed to a source line, pass 0 for the line and column.
441 */
442LLVMMetadataRef
443LLVMDIBuilderCreateDebugLocation(LLVMContextRef Ctx, unsigned Line,
444                                 unsigned Column, LLVMMetadataRef Scope,
445                                 LLVMMetadataRef InlinedAt);
446
447/**
448 * Get the line number of this debug location.
449 * \param Location     The debug location.
450 *
451 * @see DILocation::getLine()
452 */
453unsigned LLVMDILocationGetLine(LLVMMetadataRef Location);
454
455/**
456 * Get the column number of this debug location.
457 * \param Location     The debug location.
458 *
459 * @see DILocation::getColumn()
460 */
461unsigned LLVMDILocationGetColumn(LLVMMetadataRef Location);
462
463/**
464 * Get the local scope associated with this debug location.
465 * \param Location     The debug location.
466 *
467 * @see DILocation::getScope()
468 */
469LLVMMetadataRef LLVMDILocationGetScope(LLVMMetadataRef Location);
470
471/**
472 * Get the "inline at" location associated with this debug location.
473 * \param Location     The debug location.
474 *
475 * @see DILocation::getInlinedAt()
476 */
477LLVMMetadataRef LLVMDILocationGetInlinedAt(LLVMMetadataRef Location);
478
479/**
480 * Get the metadata of the file associated with a given scope.
481 * \param Scope     The scope object.
482 *
483 * @see DIScope::getFile()
484 */
485LLVMMetadataRef LLVMDIScopeGetFile(LLVMMetadataRef Scope);
486
487/**
488 * Get the directory of a given file.
489 * \param File     The file object.
490 * \param Len      The length of the returned string.
491 *
492 * @see DIFile::getDirectory()
493 */
494const char *LLVMDIFileGetDirectory(LLVMMetadataRef File, unsigned *Len);
495
496/**
497 * Get the name of a given file.
498 * \param File     The file object.
499 * \param Len      The length of the returned string.
500 *
501 * @see DIFile::getFilename()
502 */
503const char *LLVMDIFileGetFilename(LLVMMetadataRef File, unsigned *Len);
504
505/**
506 * Get the source of a given file.
507 * \param File     The file object.
508 * \param Len      The length of the returned string.
509 *
510 * @see DIFile::getSource()
511 */
512const char *LLVMDIFileGetSource(LLVMMetadataRef File, unsigned *Len);
513
514/**
515 * Create a type array.
516 * \param Builder        The DIBuilder.
517 * \param Data           The type elements.
518 * \param NumElements    Number of type elements.
519 */
520LLVMMetadataRef LLVMDIBuilderGetOrCreateTypeArray(LLVMDIBuilderRef Builder,
521                                                  LLVMMetadataRef *Data,
522                                                  size_t NumElements);
523
524/**
525 * Create subroutine type.
526 * \param Builder        The DIBuilder.
527 * \param File            The file in which the subroutine resides.
528 * \param ParameterTypes  An array of subroutine parameter types. This
529 *                        includes return type at 0th index.
530 * \param NumParameterTypes The number of parameter types in \c ParameterTypes
531 * \param Flags           E.g.: \c LLVMDIFlagLValueReference.
532 *                        These flags are used to emit dwarf attributes.
533 */
534LLVMMetadataRef
535LLVMDIBuilderCreateSubroutineType(LLVMDIBuilderRef Builder,
536                                  LLVMMetadataRef File,
537                                  LLVMMetadataRef *ParameterTypes,
538                                  unsigned NumParameterTypes,
539                                  LLVMDIFlags Flags);
540
541/**
542 * Create debugging information entry for a macro.
543 * @param Builder         The DIBuilder.
544 * @param ParentMacroFile Macro parent (could be NULL).
545 * @param Line            Source line number where the macro is defined.
546 * @param RecordType      DW_MACINFO_define or DW_MACINFO_undef.
547 * @param Name            Macro name.
548 * @param NameLen         Macro name length.
549 * @param Value           Macro value.
550 * @param ValueLen        Macro value length.
551 */
552LLVMMetadataRef LLVMDIBuilderCreateMacro(LLVMDIBuilderRef Builder,
553                                         LLVMMetadataRef ParentMacroFile,
554                                         unsigned Line,
555                                         LLVMDWARFMacinfoRecordType RecordType,
556                                         const char *Name, size_t NameLen,
557                                         const char *Value, size_t ValueLen);
558
559/**
560 * Create debugging information temporary entry for a macro file.
561 * List of macro node direct children will be calculated by DIBuilder,
562 * using the \p ParentMacroFile relationship.
563 * @param Builder         The DIBuilder.
564 * @param ParentMacroFile Macro parent (could be NULL).
565 * @param Line            Source line number where the macro file is included.
566 * @param File            File descriptor containing the name of the macro file.
567 */
568LLVMMetadataRef
569LLVMDIBuilderCreateTempMacroFile(LLVMDIBuilderRef Builder,
570                                 LLVMMetadataRef ParentMacroFile, unsigned Line,
571                                 LLVMMetadataRef File);
572
573/**
574 * Create debugging information entry for an enumerator.
575 * @param Builder        The DIBuilder.
576 * @param Name           Enumerator name.
577 * @param NameLen        Length of enumerator name.
578 * @param Value          Enumerator value.
579 * @param IsUnsigned     True if the value is unsigned.
580 */
581LLVMMetadataRef LLVMDIBuilderCreateEnumerator(LLVMDIBuilderRef Builder,
582                                              const char *Name, size_t NameLen,
583                                              int64_t Value,
584                                              LLVMBool IsUnsigned);
585
586/**
587 * Create debugging information entry for an enumeration.
588 * \param Builder        The DIBuilder.
589 * \param Scope          Scope in which this enumeration is defined.
590 * \param Name           Enumeration name.
591 * \param NameLen        Length of enumeration name.
592 * \param File           File where this member is defined.
593 * \param LineNumber     Line number.
594 * \param SizeInBits     Member size.
595 * \param AlignInBits    Member alignment.
596 * \param Elements       Enumeration elements.
597 * \param NumElements    Number of enumeration elements.
598 * \param ClassTy        Underlying type of a C++11/ObjC fixed enum.
599 */
600LLVMMetadataRef LLVMDIBuilderCreateEnumerationType(
601    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
602    size_t NameLen, LLVMMetadataRef File, unsigned LineNumber,
603    uint64_t SizeInBits, uint32_t AlignInBits, LLVMMetadataRef *Elements,
604    unsigned NumElements, LLVMMetadataRef ClassTy);
605
606/**
607 * Create debugging information entry for a union.
608 * \param Builder      The DIBuilder.
609 * \param Scope        Scope in which this union is defined.
610 * \param Name         Union name.
611 * \param NameLen      Length of union name.
612 * \param File         File where this member is defined.
613 * \param LineNumber   Line number.
614 * \param SizeInBits   Member size.
615 * \param AlignInBits  Member alignment.
616 * \param Flags        Flags to encode member attribute, e.g. private
617 * \param Elements     Union elements.
618 * \param NumElements  Number of union elements.
619 * \param RunTimeLang  Optional parameter, Objective-C runtime version.
620 * \param UniqueId     A unique identifier for the union.
621 * \param UniqueIdLen  Length of unique identifier.
622 */
623LLVMMetadataRef LLVMDIBuilderCreateUnionType(
624    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
625    size_t NameLen, LLVMMetadataRef File, unsigned LineNumber,
626    uint64_t SizeInBits, uint32_t AlignInBits, LLVMDIFlags Flags,
627    LLVMMetadataRef *Elements, unsigned NumElements, unsigned RunTimeLang,
628    const char *UniqueId, size_t UniqueIdLen);
629
630
631/**
632 * Create debugging information entry for an array.
633 * \param Builder      The DIBuilder.
634 * \param Size         Array size.
635 * \param AlignInBits  Alignment.
636 * \param Ty           Element type.
637 * \param Subscripts   Subscripts.
638 * \param NumSubscripts Number of subscripts.
639 */
640LLVMMetadataRef
641LLVMDIBuilderCreateArrayType(LLVMDIBuilderRef Builder, uint64_t Size,
642                             uint32_t AlignInBits, LLVMMetadataRef Ty,
643                             LLVMMetadataRef *Subscripts,
644                             unsigned NumSubscripts);
645
646/**
647 * Create debugging information entry for a vector type.
648 * \param Builder      The DIBuilder.
649 * \param Size         Vector size.
650 * \param AlignInBits  Alignment.
651 * \param Ty           Element type.
652 * \param Subscripts   Subscripts.
653 * \param NumSubscripts Number of subscripts.
654 */
655LLVMMetadataRef
656LLVMDIBuilderCreateVectorType(LLVMDIBuilderRef Builder, uint64_t Size,
657                              uint32_t AlignInBits, LLVMMetadataRef Ty,
658                              LLVMMetadataRef *Subscripts,
659                              unsigned NumSubscripts);
660
661/**
662 * Create a DWARF unspecified type.
663 * \param Builder   The DIBuilder.
664 * \param Name      The unspecified type's name.
665 * \param NameLen   Length of type name.
666 */
667LLVMMetadataRef
668LLVMDIBuilderCreateUnspecifiedType(LLVMDIBuilderRef Builder, const char *Name,
669                                   size_t NameLen);
670
671/**
672 * Create debugging information entry for a basic
673 * type.
674 * \param Builder     The DIBuilder.
675 * \param Name        Type name.
676 * \param NameLen     Length of type name.
677 * \param SizeInBits  Size of the type.
678 * \param Encoding    DWARF encoding code, e.g. \c LLVMDWARFTypeEncoding_float.
679 * \param Flags       Flags to encode optional attribute like endianity
680 */
681LLVMMetadataRef
682LLVMDIBuilderCreateBasicType(LLVMDIBuilderRef Builder, const char *Name,
683                             size_t NameLen, uint64_t SizeInBits,
684                             LLVMDWARFTypeEncoding Encoding,
685                             LLVMDIFlags Flags);
686
687/**
688 * Create debugging information entry for a pointer.
689 * \param Builder     The DIBuilder.
690 * \param PointeeTy         Type pointed by this pointer.
691 * \param SizeInBits        Size.
692 * \param AlignInBits       Alignment. (optional, pass 0 to ignore)
693 * \param AddressSpace      DWARF address space. (optional, pass 0 to ignore)
694 * \param Name              Pointer type name. (optional)
695 * \param NameLen           Length of pointer type name. (optional)
696 */
697LLVMMetadataRef LLVMDIBuilderCreatePointerType(
698    LLVMDIBuilderRef Builder, LLVMMetadataRef PointeeTy,
699    uint64_t SizeInBits, uint32_t AlignInBits, unsigned AddressSpace,
700    const char *Name, size_t NameLen);
701
702/**
703 * Create debugging information entry for a struct.
704 * \param Builder     The DIBuilder.
705 * \param Scope        Scope in which this struct is defined.
706 * \param Name         Struct name.
707 * \param NameLen      Struct name length.
708 * \param File         File where this member is defined.
709 * \param LineNumber   Line number.
710 * \param SizeInBits   Member size.
711 * \param AlignInBits  Member alignment.
712 * \param Flags        Flags to encode member attribute, e.g. private
713 * \param Elements     Struct elements.
714 * \param NumElements  Number of struct elements.
715 * \param RunTimeLang  Optional parameter, Objective-C runtime version.
716 * \param VTableHolder The object containing the vtable for the struct.
717 * \param UniqueId     A unique identifier for the struct.
718 * \param UniqueIdLen  Length of the unique identifier for the struct.
719 */
720LLVMMetadataRef LLVMDIBuilderCreateStructType(
721    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
722    size_t NameLen, LLVMMetadataRef File, unsigned LineNumber,
723    uint64_t SizeInBits, uint32_t AlignInBits, LLVMDIFlags Flags,
724    LLVMMetadataRef DerivedFrom, LLVMMetadataRef *Elements,
725    unsigned NumElements, unsigned RunTimeLang, LLVMMetadataRef VTableHolder,
726    const char *UniqueId, size_t UniqueIdLen);
727
728/**
729 * Create debugging information entry for a member.
730 * \param Builder      The DIBuilder.
731 * \param Scope        Member scope.
732 * \param Name         Member name.
733 * \param NameLen      Length of member name.
734 * \param File         File where this member is defined.
735 * \param LineNo       Line number.
736 * \param SizeInBits   Member size.
737 * \param AlignInBits  Member alignment.
738 * \param OffsetInBits Member offset.
739 * \param Flags        Flags to encode member attribute, e.g. private
740 * \param Ty           Parent type.
741 */
742LLVMMetadataRef LLVMDIBuilderCreateMemberType(
743    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
744    size_t NameLen, LLVMMetadataRef File, unsigned LineNo,
745    uint64_t SizeInBits, uint32_t AlignInBits, uint64_t OffsetInBits,
746    LLVMDIFlags Flags, LLVMMetadataRef Ty);
747
748/**
749 * Create debugging information entry for a
750 * C++ static data member.
751 * \param Builder      The DIBuilder.
752 * \param Scope        Member scope.
753 * \param Name         Member name.
754 * \param NameLen      Length of member name.
755 * \param File         File where this member is declared.
756 * \param LineNumber   Line number.
757 * \param Type         Type of the static member.
758 * \param Flags        Flags to encode member attribute, e.g. private.
759 * \param ConstantVal  Const initializer of the member.
760 * \param AlignInBits  Member alignment.
761 */
762LLVMMetadataRef
763LLVMDIBuilderCreateStaticMemberType(
764    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
765    size_t NameLen, LLVMMetadataRef File, unsigned LineNumber,
766    LLVMMetadataRef Type, LLVMDIFlags Flags, LLVMValueRef ConstantVal,
767    uint32_t AlignInBits);
768
769/**
770 * Create debugging information entry for a pointer to member.
771 * \param Builder      The DIBuilder.
772 * \param PointeeType  Type pointed to by this pointer.
773 * \param ClassType    Type for which this pointer points to members of.
774 * \param SizeInBits   Size.
775 * \param AlignInBits  Alignment.
776 * \param Flags        Flags.
777 */
778LLVMMetadataRef
779LLVMDIBuilderCreateMemberPointerType(LLVMDIBuilderRef Builder,
780                                     LLVMMetadataRef PointeeType,
781                                     LLVMMetadataRef ClassType,
782                                     uint64_t SizeInBits,
783                                     uint32_t AlignInBits,
784                                     LLVMDIFlags Flags);
785/**
786 * Create debugging information entry for Objective-C instance variable.
787 * \param Builder      The DIBuilder.
788 * \param Name         Member name.
789 * \param NameLen      The length of the C string passed to \c Name.
790 * \param File         File where this member is defined.
791 * \param LineNo       Line number.
792 * \param SizeInBits   Member size.
793 * \param AlignInBits  Member alignment.
794 * \param OffsetInBits Member offset.
795 * \param Flags        Flags to encode member attribute, e.g. private
796 * \param Ty           Parent type.
797 * \param PropertyNode Property associated with this ivar.
798 */
799LLVMMetadataRef
800LLVMDIBuilderCreateObjCIVar(LLVMDIBuilderRef Builder,
801                            const char *Name, size_t NameLen,
802                            LLVMMetadataRef File, unsigned LineNo,
803                            uint64_t SizeInBits, uint32_t AlignInBits,
804                            uint64_t OffsetInBits, LLVMDIFlags Flags,
805                            LLVMMetadataRef Ty, LLVMMetadataRef PropertyNode);
806
807/**
808 * Create debugging information entry for Objective-C property.
809 * \param Builder            The DIBuilder.
810 * \param Name               Property name.
811 * \param NameLen            The length of the C string passed to \c Name.
812 * \param File               File where this property is defined.
813 * \param LineNo             Line number.
814 * \param GetterName         Name of the Objective C property getter selector.
815 * \param GetterNameLen      The length of the C string passed to \c GetterName.
816 * \param SetterName         Name of the Objective C property setter selector.
817 * \param SetterNameLen      The length of the C string passed to \c SetterName.
818 * \param PropertyAttributes Objective C property attributes.
819 * \param Ty                 Type.
820 */
821LLVMMetadataRef
822LLVMDIBuilderCreateObjCProperty(LLVMDIBuilderRef Builder,
823                                const char *Name, size_t NameLen,
824                                LLVMMetadataRef File, unsigned LineNo,
825                                const char *GetterName, size_t GetterNameLen,
826                                const char *SetterName, size_t SetterNameLen,
827                                unsigned PropertyAttributes,
828                                LLVMMetadataRef Ty);
829
830/**
831 * Create a uniqued DIType* clone with FlagObjectPointer and FlagArtificial set.
832 * \param Builder   The DIBuilder.
833 * \param Type      The underlying type to which this pointer points.
834 */
835LLVMMetadataRef
836LLVMDIBuilderCreateObjectPointerType(LLVMDIBuilderRef Builder,
837                                     LLVMMetadataRef Type);
838
839/**
840 * Create debugging information entry for a qualified
841 * type, e.g. 'const int'.
842 * \param Builder     The DIBuilder.
843 * \param Tag         Tag identifying type,
844 *                    e.g. LLVMDWARFTypeQualifier_volatile_type
845 * \param Type        Base Type.
846 */
847LLVMMetadataRef
848LLVMDIBuilderCreateQualifiedType(LLVMDIBuilderRef Builder, unsigned Tag,
849                                 LLVMMetadataRef Type);
850
851/**
852 * Create debugging information entry for a c++
853 * style reference or rvalue reference type.
854 * \param Builder   The DIBuilder.
855 * \param Tag       Tag identifying type,
856 * \param Type      Base Type.
857 */
858LLVMMetadataRef
859LLVMDIBuilderCreateReferenceType(LLVMDIBuilderRef Builder, unsigned Tag,
860                                 LLVMMetadataRef Type);
861
862/**
863 * Create C++11 nullptr type.
864 * \param Builder   The DIBuilder.
865 */
866LLVMMetadataRef
867LLVMDIBuilderCreateNullPtrType(LLVMDIBuilderRef Builder);
868
869/**
870 * Create debugging information entry for a typedef.
871 * \param Builder    The DIBuilder.
872 * \param Type       Original type.
873 * \param Name       Typedef name.
874 * \param File       File where this type is defined.
875 * \param LineNo     Line number.
876 * \param Scope      The surrounding context for the typedef.
877 */
878LLVMMetadataRef
879LLVMDIBuilderCreateTypedef(LLVMDIBuilderRef Builder, LLVMMetadataRef Type,
880                           const char *Name, size_t NameLen,
881                           LLVMMetadataRef File, unsigned LineNo,
882                           LLVMMetadataRef Scope, uint32_t AlignInBits);
883
884/**
885 * Create debugging information entry to establish inheritance relationship
886 * between two types.
887 * \param Builder       The DIBuilder.
888 * \param Ty            Original type.
889 * \param BaseTy        Base type. Ty is inherits from base.
890 * \param BaseOffset    Base offset.
891 * \param VBPtrOffset  Virtual base pointer offset.
892 * \param Flags         Flags to describe inheritance attribute, e.g. private
893 */
894LLVMMetadataRef
895LLVMDIBuilderCreateInheritance(LLVMDIBuilderRef Builder,
896                               LLVMMetadataRef Ty, LLVMMetadataRef BaseTy,
897                               uint64_t BaseOffset, uint32_t VBPtrOffset,
898                               LLVMDIFlags Flags);
899
900/**
901 * Create a permanent forward-declared type.
902 * \param Builder             The DIBuilder.
903 * \param Tag                 A unique tag for this type.
904 * \param Name                Type name.
905 * \param NameLen             Length of type name.
906 * \param Scope               Type scope.
907 * \param File                File where this type is defined.
908 * \param Line                Line number where this type is defined.
909 * \param RuntimeLang         Indicates runtime version for languages like
910 *                            Objective-C.
911 * \param SizeInBits          Member size.
912 * \param AlignInBits         Member alignment.
913 * \param UniqueIdentifier    A unique identifier for the type.
914 * \param UniqueIdentifierLen Length of the unique identifier.
915 */
916LLVMMetadataRef LLVMDIBuilderCreateForwardDecl(
917    LLVMDIBuilderRef Builder, unsigned Tag, const char *Name,
918    size_t NameLen, LLVMMetadataRef Scope, LLVMMetadataRef File, unsigned Line,
919    unsigned RuntimeLang, uint64_t SizeInBits, uint32_t AlignInBits,
920    const char *UniqueIdentifier, size_t UniqueIdentifierLen);
921
922/**
923 * Create a temporary forward-declared type.
924 * \param Builder             The DIBuilder.
925 * \param Tag                 A unique tag for this type.
926 * \param Name                Type name.
927 * \param NameLen             Length of type name.
928 * \param Scope               Type scope.
929 * \param File                File where this type is defined.
930 * \param Line                Line number where this type is defined.
931 * \param RuntimeLang         Indicates runtime version for languages like
932 *                            Objective-C.
933 * \param SizeInBits          Member size.
934 * \param AlignInBits         Member alignment.
935 * \param Flags               Flags.
936 * \param UniqueIdentifier    A unique identifier for the type.
937 * \param UniqueIdentifierLen Length of the unique identifier.
938 */
939LLVMMetadataRef
940LLVMDIBuilderCreateReplaceableCompositeType(
941    LLVMDIBuilderRef Builder, unsigned Tag, const char *Name,
942    size_t NameLen, LLVMMetadataRef Scope, LLVMMetadataRef File, unsigned Line,
943    unsigned RuntimeLang, uint64_t SizeInBits, uint32_t AlignInBits,
944    LLVMDIFlags Flags, const char *UniqueIdentifier,
945    size_t UniqueIdentifierLen);
946
947/**
948 * Create debugging information entry for a bit field member.
949 * \param Builder             The DIBuilder.
950 * \param Scope               Member scope.
951 * \param Name                Member name.
952 * \param NameLen             Length of member name.
953 * \param File                File where this member is defined.
954 * \param LineNumber          Line number.
955 * \param SizeInBits          Member size.
956 * \param OffsetInBits        Member offset.
957 * \param StorageOffsetInBits Member storage offset.
958 * \param Flags               Flags to encode member attribute.
959 * \param Type                Parent type.
960 */
961LLVMMetadataRef
962LLVMDIBuilderCreateBitFieldMemberType(LLVMDIBuilderRef Builder,
963                                      LLVMMetadataRef Scope,
964                                      const char *Name, size_t NameLen,
965                                      LLVMMetadataRef File, unsigned LineNumber,
966                                      uint64_t SizeInBits,
967                                      uint64_t OffsetInBits,
968                                      uint64_t StorageOffsetInBits,
969                                      LLVMDIFlags Flags, LLVMMetadataRef Type);
970
971/**
972 * Create debugging information entry for a class.
973 * \param Scope               Scope in which this class is defined.
974 * \param Name                Class name.
975 * \param NameLen             The length of the C string passed to \c Name.
976 * \param File                File where this member is defined.
977 * \param LineNumber          Line number.
978 * \param SizeInBits          Member size.
979 * \param AlignInBits         Member alignment.
980 * \param OffsetInBits        Member offset.
981 * \param Flags               Flags to encode member attribute, e.g. private.
982 * \param DerivedFrom         Debug info of the base class of this type.
983 * \param Elements            Class members.
984 * \param NumElements         Number of class elements.
985 * \param VTableHolder        Debug info of the base class that contains vtable
986 *                            for this type. This is used in
987 *                            DW_AT_containing_type. See DWARF documentation
988 *                            for more info.
989 * \param TemplateParamsNode  Template type parameters.
990 * \param UniqueIdentifier    A unique identifier for the type.
991 * \param UniqueIdentifierLen Length of the unique identifier.
992 */
993LLVMMetadataRef LLVMDIBuilderCreateClassType(LLVMDIBuilderRef Builder,
994    LLVMMetadataRef Scope, const char *Name, size_t NameLen,
995    LLVMMetadataRef File, unsigned LineNumber, uint64_t SizeInBits,
996    uint32_t AlignInBits, uint64_t OffsetInBits, LLVMDIFlags Flags,
997    LLVMMetadataRef DerivedFrom,
998    LLVMMetadataRef *Elements, unsigned NumElements,
999    LLVMMetadataRef VTableHolder, LLVMMetadataRef TemplateParamsNode,
1000    const char *UniqueIdentifier, size_t UniqueIdentifierLen);
1001
1002/**
1003 * Create a uniqued DIType* clone with FlagArtificial set.
1004 * \param Builder     The DIBuilder.
1005 * \param Type        The underlying type.
1006 */
1007LLVMMetadataRef
1008LLVMDIBuilderCreateArtificialType(LLVMDIBuilderRef Builder,
1009                                  LLVMMetadataRef Type);
1010
1011/**
1012 * Get the name of this DIType.
1013 * \param DType     The DIType.
1014 * \param Length    The length of the returned string.
1015 *
1016 * @see DIType::getName()
1017 */
1018const char *LLVMDITypeGetName(LLVMMetadataRef DType, size_t *Length);
1019
1020/**
1021 * Get the size of this DIType in bits.
1022 * \param DType     The DIType.
1023 *
1024 * @see DIType::getSizeInBits()
1025 */
1026uint64_t LLVMDITypeGetSizeInBits(LLVMMetadataRef DType);
1027
1028/**
1029 * Get the offset of this DIType in bits.
1030 * \param DType     The DIType.
1031 *
1032 * @see DIType::getOffsetInBits()
1033 */
1034uint64_t LLVMDITypeGetOffsetInBits(LLVMMetadataRef DType);
1035
1036/**
1037 * Get the alignment of this DIType in bits.
1038 * \param DType     The DIType.
1039 *
1040 * @see DIType::getAlignInBits()
1041 */
1042uint32_t LLVMDITypeGetAlignInBits(LLVMMetadataRef DType);
1043
1044/**
1045 * Get the source line where this DIType is declared.
1046 * \param DType     The DIType.
1047 *
1048 * @see DIType::getLine()
1049 */
1050unsigned LLVMDITypeGetLine(LLVMMetadataRef DType);
1051
1052/**
1053 * Get the flags associated with this DIType.
1054 * \param DType     The DIType.
1055 *
1056 * @see DIType::getFlags()
1057 */
1058LLVMDIFlags LLVMDITypeGetFlags(LLVMMetadataRef DType);
1059
1060/**
1061 * Create a descriptor for a value range.
1062 * \param Builder    The DIBuilder.
1063 * \param LowerBound Lower bound of the subrange, e.g. 0 for C, 1 for Fortran.
1064 * \param Count      Count of elements in the subrange.
1065 */
1066LLVMMetadataRef LLVMDIBuilderGetOrCreateSubrange(LLVMDIBuilderRef Builder,
1067                                                 int64_t LowerBound,
1068                                                 int64_t Count);
1069
1070/**
1071 * Create an array of DI Nodes.
1072 * \param Builder        The DIBuilder.
1073 * \param Data           The DI Node elements.
1074 * \param NumElements    Number of DI Node elements.
1075 */
1076LLVMMetadataRef LLVMDIBuilderGetOrCreateArray(LLVMDIBuilderRef Builder,
1077                                              LLVMMetadataRef *Data,
1078                                              size_t NumElements);
1079
1080/**
1081 * Create a new descriptor for the specified variable which has a complex
1082 * address expression for its address.
1083 * \param Builder     The DIBuilder.
1084 * \param Addr        An array of complex address operations.
1085 * \param Length      Length of the address operation array.
1086 */
1087LLVMMetadataRef LLVMDIBuilderCreateExpression(LLVMDIBuilderRef Builder,
1088                                              int64_t *Addr, size_t Length);
1089
1090/**
1091 * Create a new descriptor for the specified variable that does not have an
1092 * address, but does have a constant value.
1093 * \param Builder     The DIBuilder.
1094 * \param Value       The constant value.
1095 */
1096LLVMMetadataRef
1097LLVMDIBuilderCreateConstantValueExpression(LLVMDIBuilderRef Builder,
1098                                           int64_t Value);
1099
1100/**
1101 * Create a new descriptor for the specified variable.
1102 * \param Scope       Variable scope.
1103 * \param Name        Name of the variable.
1104 * \param NameLen     The length of the C string passed to \c Name.
1105 * \param Linkage     Mangled  name of the variable.
1106 * \param LinkLen     The length of the C string passed to \c Linkage.
1107 * \param File        File where this variable is defined.
1108 * \param LineNo      Line number.
1109 * \param Ty          Variable Type.
1110 * \param LocalToUnit Boolean flag indicate whether this variable is
1111 *                    externally visible or not.
1112 * \param Expr        The location of the global relative to the attached
1113 *                    GlobalVariable.
1114 * \param Decl        Reference to the corresponding declaration.
1115 *                    variables.
1116 * \param AlignInBits Variable alignment(or 0 if no alignment attr was
1117 *                    specified)
1118 */
1119LLVMMetadataRef LLVMDIBuilderCreateGlobalVariableExpression(
1120    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
1121    size_t NameLen, const char *Linkage, size_t LinkLen, LLVMMetadataRef File,
1122    unsigned LineNo, LLVMMetadataRef Ty, LLVMBool LocalToUnit,
1123    LLVMMetadataRef Expr, LLVMMetadataRef Decl, uint32_t AlignInBits);
1124
1125/**
1126 * Retrieves the \c DIVariable associated with this global variable expression.
1127 * \param GVE    The global variable expression.
1128 *
1129 * @see llvm::DIGlobalVariableExpression::getVariable()
1130 */
1131LLVMMetadataRef LLVMDIGlobalVariableExpressionGetVariable(LLVMMetadataRef GVE);
1132
1133/**
1134 * Retrieves the \c DIExpression associated with this global variable expression.
1135 * \param GVE    The global variable expression.
1136 *
1137 * @see llvm::DIGlobalVariableExpression::getExpression()
1138 */
1139LLVMMetadataRef LLVMDIGlobalVariableExpressionGetExpression(
1140    LLVMMetadataRef GVE);
1141
1142/**
1143 * Get the metadata of the file associated with a given variable.
1144 * \param Var     The variable object.
1145 *
1146 * @see DIVariable::getFile()
1147 */
1148LLVMMetadataRef LLVMDIVariableGetFile(LLVMMetadataRef Var);
1149
1150/**
1151 * Get the metadata of the scope associated with a given variable.
1152 * \param Var     The variable object.
1153 *
1154 * @see DIVariable::getScope()
1155 */
1156LLVMMetadataRef LLVMDIVariableGetScope(LLVMMetadataRef Var);
1157
1158/**
1159 * Get the source line where this \c DIVariable is declared.
1160 * \param Var     The DIVariable.
1161 *
1162 * @see DIVariable::getLine()
1163 */
1164unsigned LLVMDIVariableGetLine(LLVMMetadataRef Var);
1165
1166/**
1167 * Create a new temporary \c MDNode.  Suitable for use in constructing cyclic
1168 * \c MDNode structures. A temporary \c MDNode is not uniqued, may be RAUW'd,
1169 * and must be manually deleted with \c LLVMDisposeTemporaryMDNode.
1170 * \param Ctx            The context in which to construct the temporary node.
1171 * \param Data           The metadata elements.
1172 * \param NumElements    Number of metadata elements.
1173 */
1174LLVMMetadataRef LLVMTemporaryMDNode(LLVMContextRef Ctx, LLVMMetadataRef *Data,
1175                                    size_t NumElements);
1176
1177/**
1178 * Deallocate a temporary node.
1179 *
1180 * Calls \c replaceAllUsesWith(nullptr) before deleting, so any remaining
1181 * references will be reset.
1182 * \param TempNode    The temporary metadata node.
1183 */
1184void LLVMDisposeTemporaryMDNode(LLVMMetadataRef TempNode);
1185
1186/**
1187 * Replace all uses of temporary metadata.
1188 * \param TempTargetMetadata    The temporary metadata node.
1189 * \param Replacement           The replacement metadata node.
1190 */
1191void LLVMMetadataReplaceAllUsesWith(LLVMMetadataRef TempTargetMetadata,
1192                                    LLVMMetadataRef Replacement);
1193
1194/**
1195 * Create a new descriptor for the specified global variable that is temporary
1196 * and meant to be RAUWed.
1197 * \param Scope       Variable scope.
1198 * \param Name        Name of the variable.
1199 * \param NameLen     The length of the C string passed to \c Name.
1200 * \param Linkage     Mangled  name of the variable.
1201 * \param LnkLen      The length of the C string passed to \c Linkage.
1202 * \param File        File where this variable is defined.
1203 * \param LineNo      Line number.
1204 * \param Ty          Variable Type.
1205 * \param LocalToUnit Boolean flag indicate whether this variable is
1206 *                    externally visible or not.
1207 * \param Decl        Reference to the corresponding declaration.
1208 * \param AlignInBits Variable alignment(or 0 if no alignment attr was
1209 *                    specified)
1210 */
1211LLVMMetadataRef LLVMDIBuilderCreateTempGlobalVariableFwdDecl(
1212    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
1213    size_t NameLen, const char *Linkage, size_t LnkLen, LLVMMetadataRef File,
1214    unsigned LineNo, LLVMMetadataRef Ty, LLVMBool LocalToUnit,
1215    LLVMMetadataRef Decl, uint32_t AlignInBits);
1216
1217/**
1218 * Insert a new llvm.dbg.declare intrinsic call before the given instruction.
1219 * \param Builder     The DIBuilder.
1220 * \param Storage     The storage of the variable to declare.
1221 * \param VarInfo     The variable's debug info descriptor.
1222 * \param Expr        A complex location expression for the variable.
1223 * \param DebugLoc    Debug info location.
1224 * \param Instr       Instruction acting as a location for the new intrinsic.
1225 */
1226LLVMValueRef LLVMDIBuilderInsertDeclareBefore(
1227  LLVMDIBuilderRef Builder, LLVMValueRef Storage, LLVMMetadataRef VarInfo,
1228  LLVMMetadataRef Expr, LLVMMetadataRef DebugLoc, LLVMValueRef Instr);
1229
1230/**
1231 * Insert a new llvm.dbg.declare intrinsic call at the end of the given basic
1232 * block. If the basic block has a terminator instruction, the intrinsic is
1233 * inserted before that terminator instruction.
1234 * \param Builder     The DIBuilder.
1235 * \param Storage     The storage of the variable to declare.
1236 * \param VarInfo     The variable's debug info descriptor.
1237 * \param Expr        A complex location expression for the variable.
1238 * \param DebugLoc    Debug info location.
1239 * \param Block       Basic block acting as a location for the new intrinsic.
1240 */
1241LLVMValueRef LLVMDIBuilderInsertDeclareAtEnd(
1242    LLVMDIBuilderRef Builder, LLVMValueRef Storage, LLVMMetadataRef VarInfo,
1243    LLVMMetadataRef Expr, LLVMMetadataRef DebugLoc, LLVMBasicBlockRef Block);
1244
1245/**
1246 * Insert a new llvm.dbg.value intrinsic call before the given instruction.
1247 * \param Builder     The DIBuilder.
1248 * \param Val         The value of the variable.
1249 * \param VarInfo     The variable's debug info descriptor.
1250 * \param Expr        A complex location expression for the variable.
1251 * \param DebugLoc    Debug info location.
1252 * \param Instr       Instruction acting as a location for the new intrinsic.
1253 */
1254LLVMValueRef LLVMDIBuilderInsertDbgValueBefore(LLVMDIBuilderRef Builder,
1255                                               LLVMValueRef Val,
1256                                               LLVMMetadataRef VarInfo,
1257                                               LLVMMetadataRef Expr,
1258                                               LLVMMetadataRef DebugLoc,
1259                                               LLVMValueRef Instr);
1260
1261/**
1262 * Insert a new llvm.dbg.value intrinsic call at the end of the given basic
1263 * block. If the basic block has a terminator instruction, the intrinsic is
1264 * inserted before that terminator instruction.
1265 * \param Builder     The DIBuilder.
1266 * \param Val         The value of the variable.
1267 * \param VarInfo     The variable's debug info descriptor.
1268 * \param Expr        A complex location expression for the variable.
1269 * \param DebugLoc    Debug info location.
1270 * \param Block       Basic block acting as a location for the new intrinsic.
1271 */
1272LLVMValueRef LLVMDIBuilderInsertDbgValueAtEnd(LLVMDIBuilderRef Builder,
1273                                              LLVMValueRef Val,
1274                                              LLVMMetadataRef VarInfo,
1275                                              LLVMMetadataRef Expr,
1276                                              LLVMMetadataRef DebugLoc,
1277                                              LLVMBasicBlockRef Block);
1278
1279/**
1280 * Create a new descriptor for a local auto variable.
1281 * \param Builder         The DIBuilder.
1282 * \param Scope           The local scope the variable is declared in.
1283 * \param Name            Variable name.
1284 * \param NameLen         Length of variable name.
1285 * \param File            File where this variable is defined.
1286 * \param LineNo          Line number.
1287 * \param Ty              Metadata describing the type of the variable.
1288 * \param AlwaysPreserve  If true, this descriptor will survive optimizations.
1289 * \param Flags           Flags.
1290 * \param AlignInBits     Variable alignment.
1291 */
1292LLVMMetadataRef LLVMDIBuilderCreateAutoVariable(
1293    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
1294    size_t NameLen, LLVMMetadataRef File, unsigned LineNo, LLVMMetadataRef Ty,
1295    LLVMBool AlwaysPreserve, LLVMDIFlags Flags, uint32_t AlignInBits);
1296
1297/**
1298 * Create a new descriptor for a function parameter variable.
1299 * \param Builder         The DIBuilder.
1300 * \param Scope           The local scope the variable is declared in.
1301 * \param Name            Variable name.
1302 * \param NameLen         Length of variable name.
1303 * \param ArgNo           Unique argument number for this variable; starts at 1.
1304 * \param File            File where this variable is defined.
1305 * \param LineNo          Line number.
1306 * \param Ty              Metadata describing the type of the variable.
1307 * \param AlwaysPreserve  If true, this descriptor will survive optimizations.
1308 * \param Flags           Flags.
1309 */
1310LLVMMetadataRef LLVMDIBuilderCreateParameterVariable(
1311    LLVMDIBuilderRef Builder, LLVMMetadataRef Scope, const char *Name,
1312    size_t NameLen, unsigned ArgNo, LLVMMetadataRef File, unsigned LineNo,
1313    LLVMMetadataRef Ty, LLVMBool AlwaysPreserve, LLVMDIFlags Flags);
1314
1315/**
1316 * Get the metadata of the subprogram attached to a function.
1317 *
1318 * @see llvm::Function::getSubprogram()
1319 */
1320LLVMMetadataRef LLVMGetSubprogram(LLVMValueRef Func);
1321
1322/**
1323 * Set the subprogram attached to a function.
1324 *
1325 * @see llvm::Function::setSubprogram()
1326 */
1327void LLVMSetSubprogram(LLVMValueRef Func, LLVMMetadataRef SP);
1328
1329/**
1330 * Get the line associated with a given subprogram.
1331 * \param Subprogram     The subprogram object.
1332 *
1333 * @see DISubprogram::getLine()
1334 */
1335unsigned LLVMDISubprogramGetLine(LLVMMetadataRef Subprogram);
1336
1337/**
1338 * Get the debug location for the given instruction.
1339 *
1340 * @see llvm::Instruction::getDebugLoc()
1341 */
1342LLVMMetadataRef LLVMInstructionGetDebugLoc(LLVMValueRef Inst);
1343
1344/**
1345 * Set the debug location for the given instruction.
1346 *
1347 * To clear the location metadata of the given instruction, pass NULL to \p Loc.
1348 *
1349 * @see llvm::Instruction::setDebugLoc()
1350 */
1351void LLVMInstructionSetDebugLoc(LLVMValueRef Inst, LLVMMetadataRef Loc);
1352
1353/**
1354 * Obtain the enumerated type of a Metadata instance.
1355 *
1356 * @see llvm::Metadata::getMetadataID()
1357 */
1358LLVMMetadataKind LLVMGetMetadataKind(LLVMMetadataRef Metadata);
1359
1360LLVM_C_EXTERN_C_END
1361
1362#endif
1363