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