1(*===-- llvm_debuginfo.mli - LLVM OCaml Interface -------------*- OCaml -*-===*
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
9type lldibuilder
10
11(** Source languages known by DWARF. *)
12module DWARFSourceLanguageKind : sig
13  type t =
14    | C89
15    | C
16    | Ada83
17    | C_plus_plus
18    | Cobol74
19    | Cobol85
20    | Fortran77
21    | Fortran90
22    | Pascal83
23    | Modula2
24    (*  New in DWARF v3: *)
25    | LLVMJava
26    | C99
27    | Ada95
28    | Fortran95
29    | PLI
30    | ObjC
31    | ObjC_plus_plus
32    | UPC
33    | D
34    (*  New in DWARF v4: *)
35    | LLVMPython
36    (*  New in DWARF v5: *)
37    | LLVMOpenCL
38    | Go
39    | Modula3
40    | Haskell
41    | C_plus_plus_03
42    | C_plus_plus_11
43    | OCaml
44    | Rust
45    | C11
46    | Swift
47    | Julia
48    | Dylan
49    | C_plus_plus_14
50    | Fortran03
51    | Fortran08
52    | RenderScript
53    | BLISS
54    (*  Vendor extensions: *)
55    | LLVMMips_Assembler
56    | GOOGLE_RenderScript
57    | BORLAND_Delphi
58end
59
60module DIFlag : sig
61  type t =
62    | Zero
63    | Private
64    | Protected
65    | Public
66    | FwdDecl
67    | AppleBlock
68    | ReservedBit4
69    | Virtual
70    | Artificial
71    | Explicit
72    | Prototyped
73    | ObjcClassComplete
74    | ObjectPointer
75    | Vector
76    | StaticMember
77    | LValueReference
78    | RValueReference
79    | Reserved
80    | SingleInheritance
81    | MultipleInheritance
82    | VirtualInheritance
83    | IntroducedVirtual
84    | BitField
85    | NoReturn
86    | TypePassByValue
87    | TypePassByReference
88    | EnumClass
89    | FixedEnum
90    | Thunk
91    | NonTrivial
92    | BigEndian
93    | LittleEndian
94    | IndirectVirtualBase
95    | Accessibility
96    | PtrToMemberRep
97end
98
99type lldiflags
100(** An opaque type to represent OR of multiple DIFlag.t. *)
101
102val diflags_get : DIFlag.t -> lldiflags
103(** [diflags_set f] Construct an lldiflags value with a single flag [f]. *)
104
105val diflags_set : lldiflags -> DIFlag.t -> lldiflags
106(** [diflags_set fs f] Include flag [f] in [fs] and return the new value. *)
107
108val diflags_test : lldiflags -> DIFlag.t -> bool
109(** [diflags_test fs f] Does [fs] contain flag [f]? *)
110
111(** The kind of metadata nodes. *)
112module MetadataKind : sig
113  type t =
114    | MDStringMetadataKind
115    | ConstantAsMetadataMetadataKind
116    | LocalAsMetadataMetadataKind
117    | DistinctMDOperandPlaceholderMetadataKind
118    | MDTupleMetadataKind
119    | DILocationMetadataKind
120    | DIExpressionMetadataKind
121    | DIGlobalVariableExpressionMetadataKind
122    | GenericDINodeMetadataKind
123    | DISubrangeMetadataKind
124    | DIEnumeratorMetadataKind
125    | DIBasicTypeMetadataKind
126    | DIDerivedTypeMetadataKind
127    | DICompositeTypeMetadataKind
128    | DISubroutineTypeMetadataKind
129    | DIFileMetadataKind
130    | DICompileUnitMetadataKind
131    | DISubprogramMetadataKind
132    | DILexicalBlockMetadataKind
133    | DILexicalBlockFileMetadataKind
134    | DINamespaceMetadataKind
135    | DIModuleMetadataKind
136    | DITemplateTypeParameterMetadataKind
137    | DITemplateValueParameterMetadataKind
138    | DIGlobalVariableMetadataKind
139    | DILocalVariableMetadataKind
140    | DILabelMetadataKind
141    | DIObjCPropertyMetadataKind
142    | DIImportedEntityMetadataKind
143    | DIMacroMetadataKind
144    | DIMacroFileMetadataKind
145    | DICommonBlockMetadataKind
146end
147
148(** The amount of debug information to emit. *)
149module DWARFEmissionKind : sig
150  type t = None | Full | LineTablesOnly
151end
152
153val debug_metadata_version : unit -> int
154(** [debug_metadata_version ()] The current debug metadata version number *)
155
156val get_module_debug_metadata_version : Llvm.llmodule -> int
157(** [get_module_debug_metadata_version m] Version of metadata present in [m]. *)
158
159val dibuilder : Llvm.llmodule -> lldibuilder
160(** [dibuilder m] Create a debug info builder for [m]. *)
161
162val dibuild_finalize : lldibuilder -> unit
163(** [dibuild_finalize dib] Construct any deferred debug info descriptors. *)
164
165val dibuild_create_compile_unit :
166  lldibuilder ->
167  DWARFSourceLanguageKind.t ->
168  file_ref:Llvm.llmetadata ->
169  producer:string ->
170  is_optimized:bool ->
171  flags:string ->
172  runtime_ver:int ->
173  split_name:string ->
174  DWARFEmissionKind.t ->
175  dwoid:int ->
176  di_inlining:bool ->
177  di_profiling:bool ->
178  sys_root:string ->
179  sdk:string ->
180  Llvm.llmetadata
181(** [dibuild_create_compile_unit] A CompileUnit provides an anchor for all
182    debugging information generated during this instance of compilation.
183    See LLVMDIBuilderCreateCompileUnit. *)
184
185val dibuild_create_file :
186  lldibuilder -> filename:string -> directory:string -> Llvm.llmetadata
187(** [dibuild_create_file] Create a file descriptor to hold debugging information
188    for a file. See LLVMDIBuilderCreateFile. *)
189
190val dibuild_create_module :
191  lldibuilder ->
192  parent_ref:Llvm.llmetadata ->
193  name:string ->
194  config_macros:string ->
195  include_path:string ->
196  sys_root:string ->
197  Llvm.llmetadata
198(** [dibuild_create_module] Create a new descriptor for a module with the
199    specified parent scope. See LLVMDIBuilderCreateModule. *)
200
201val dibuild_create_namespace :
202  lldibuilder ->
203  parent_ref:Llvm.llmetadata ->
204  name:string ->
205  export_symbols:bool ->
206  Llvm.llmetadata
207(** [dibuild_create_namespace] Create a new descriptor for a namespace with
208    the specified parent scope. See LLVMDIBuilderCreateNameSpace *)
209
210val dibuild_create_function :
211  lldibuilder ->
212  scope:Llvm.llmetadata ->
213  name:string ->
214  linkage_name:string ->
215  file:Llvm.llmetadata ->
216  line_no:int ->
217  ty:Llvm.llmetadata ->
218  is_local_to_unit:bool ->
219  is_definition:bool ->
220  scope_line:int ->
221  flags:lldiflags ->
222  is_optimized:bool ->
223  Llvm.llmetadata
224(** [dibuild_create_function] Create a new descriptor for the specified
225    subprogram. See LLVMDIBuilderCreateFunction. *)
226
227val dibuild_create_lexical_block :
228  lldibuilder ->
229  scope:Llvm.llmetadata ->
230  file:Llvm.llmetadata ->
231  line:int ->
232  column:int ->
233  Llvm.llmetadata
234(** [dibuild_create_lexical_block] Create a descriptor for a lexical block with
235    the specified parent context. See LLVMDIBuilderCreateLexicalBlock *)
236
237val llmetadata_null : unit -> Llvm.llmetadata
238(** [llmetadata_null ()] llmetadata is a wrapper around "llvm::Metadata *".
239    This function returns a nullptr valued llmetadata. For example, it
240    can be used to convey an llmetadata for "void" type. *)
241
242val dibuild_create_debug_location :
243  ?inlined_at:Llvm.llmetadata ->
244  Llvm.llcontext ->
245  line:int ->
246  column:int ->
247  scope:Llvm.llmetadata ->
248  Llvm.llmetadata
249(** [dibuild_create] Create a new DebugLocation that describes a source
250    location. See LLVMDIBuilderCreateDebugLocation *)
251
252val di_location_get_line : location:Llvm.llmetadata -> int
253(** [di_location_get_line l] Get the line number of debug location [l]. *)
254
255val di_location_get_column : location:Llvm.llmetadata -> int
256(** [di_location_get_column l] Get the column number of debug location [l]. *)
257
258val di_location_get_scope : location:Llvm.llmetadata -> Llvm.llmetadata
259(** [di_location_get_scope l] Get the local scope associated with
260    debug location [l]. *)
261
262val di_location_get_inlined_at :
263  location:Llvm.llmetadata -> Llvm.llmetadata option
264(** [di_location_get_inlined_at l] Get the "inlined at" location associated with
265    debug location [l], if it exists. *)
266
267val di_scope_get_file : scope:Llvm.llmetadata -> Llvm.llmetadata option
268(** [di_scope_get_file l] Get the metadata of the file associated with scope [s]
269    if it exists. *)
270
271val di_file_get_directory : file:Llvm.llmetadata -> string
272(** [di_file_get_directory f] Get the directory of file [f]. *)
273
274val di_file_get_filename : file:Llvm.llmetadata -> string
275(** [di_file_get_filename f] Get the name of file [f]. *)
276
277val di_file_get_source : file:Llvm.llmetadata -> string
278(** [di_file_get_source f] Get the source of file [f]. *)
279
280val dibuild_get_or_create_type_array :
281  lldibuilder -> data:Llvm.llmetadata array -> Llvm.llmetadata
282(** [dibuild_get_or_create_type_array] Create a type array.
283    See LLVMDIBuilderGetOrCreateTypeArray. *)
284
285val dibuild_get_or_create_array :
286  lldibuilder -> data:Llvm.llmetadata array -> Llvm.llmetadata
287(** [dibuild_get_or_create_array] Create an array of DI Nodes.
288    See LLVMDIBuilderGetOrCreateArray. *)
289
290val dibuild_create_constant_value_expression :
291  lldibuilder -> int -> Llvm.llmetadata
292(** [dibuild_create_constant_value_expression] Create a new descriptor for
293    the specified variable that does not have an address, but does have
294    a constant value. See LLVMDIBuilderCreateConstantValueExpression. *)
295
296val dibuild_create_global_variable_expression :
297  lldibuilder ->
298  scope:Llvm.llmetadata ->
299  name:string ->
300  linkage:string ->
301  file:Llvm.llmetadata ->
302  line:int ->
303  ty:Llvm.llmetadata ->
304  is_local_to_unit:bool ->
305  expr:Llvm.llmetadata ->
306  decl:Llvm.llmetadata ->
307  align_in_bits:int ->
308  Llvm.llmetadata
309(** [dibuild_create_global_variable_expression] Create a new descriptor for
310    the specified variable. See LLVMDIBuilderCreateGlobalVariableExpression. *)
311
312val di_global_variable_expression_get_variable :
313  Llvm.llmetadata -> Llvm.llmetadata option
314(** [di_global_variable_expression_get_variable gve] returns the debug variable
315    of [gve], which must be a [DIGlobalVariableExpression].
316    See LLVMDIGlobalVariableExpressionGetVariable. *)
317
318val di_variable_get_line : Llvm.llmetadata -> int
319(** [di_variable_get_line v] returns the line number of the variable [v].
320    See LLVMDIVariableGetLine. *)
321
322val di_variable_get_file : Llvm.llmetadata -> Llvm.llmetadata option
323(** [di_variable_get_file v] returns the file of the variable [v].
324    See LLVMDIVariableGetFile. *)
325
326val dibuild_create_subroutine_type :
327  lldibuilder ->
328  file:Llvm.llmetadata ->
329  param_types:Llvm.llmetadata array ->
330  lldiflags ->
331  Llvm.llmetadata
332(** [dibuild_create_subroutine_type] Create subroutine type.
333    See LLVMDIBuilderCreateSubroutineType *)
334
335val dibuild_create_enumerator :
336  lldibuilder -> name:string -> value:int -> is_unsigned:bool -> Llvm.llmetadata
337(** [dibuild_create_enumerator] Create debugging information entry for an
338    enumerator. See LLVMDIBuilderCreateEnumerator *)
339
340val dibuild_create_enumeration_type :
341  lldibuilder ->
342  scope:Llvm.llmetadata ->
343  name:string ->
344  file:Llvm.llmetadata ->
345  line_number:int ->
346  size_in_bits:int ->
347  align_in_bits:int ->
348  elements:Llvm.llmetadata array ->
349  class_ty:Llvm.llmetadata ->
350  Llvm.llmetadata
351(** [dibuild_create_enumeration_type] Create debugging information entry for
352    an enumeration. See LLVMDIBuilderCreateEnumerationType. *)
353
354val dibuild_create_union_type :
355  lldibuilder ->
356  scope:Llvm.llmetadata ->
357  name:string ->
358  file:Llvm.llmetadata ->
359  line_number:int ->
360  size_in_bits:int ->
361  align_in_bits:int ->
362  lldiflags ->
363  elements:Llvm.llmetadata array ->
364  run_time_language:int ->
365  unique_id:string ->
366  Llvm.llmetadata
367(** [dibuild_create_union_type] Create debugging information entry for a union.
368    See LLVMDIBuilderCreateUnionType. *)
369
370val dibuild_create_array_type :
371  lldibuilder ->
372  size:int ->
373  align_in_bits:int ->
374  ty:Llvm.llmetadata ->
375  subscripts:Llvm.llmetadata array ->
376  Llvm.llmetadata
377(** [dibuild_create_array_type] Create debugging information entry for an array.
378    See LLVMDIBuilderCreateArrayType. *)
379
380val dibuild_create_vector_type :
381  lldibuilder ->
382  size:int ->
383  align_in_bits:int ->
384  ty:Llvm.llmetadata ->
385  subscripts:Llvm.llmetadata array ->
386  Llvm.llmetadata
387(** [dibuild_create_vector_type] Create debugging information entry for a
388    vector type. See LLVMDIBuilderCreateVectorType. *)
389
390val dibuild_create_unspecified_type :
391  lldibuilder -> name:string -> Llvm.llmetadata
392(** [dibuild_create_unspecified_type] Create a DWARF unspecified type. *)
393
394val dibuild_create_basic_type :
395  lldibuilder ->
396  name:string ->
397  size_in_bits:int ->
398  encoding:int ->
399  lldiflags ->
400  Llvm.llmetadata
401(** [dibuild_create_basic_type] Create debugging information entry for a basic
402    type. See LLVMDIBuilderCreateBasicType. *)
403
404val dibuild_create_pointer_type :
405  lldibuilder ->
406  pointee_ty:Llvm.llmetadata ->
407  size_in_bits:int ->
408  align_in_bits:int ->
409  address_space:int ->
410  name:string ->
411  Llvm.llmetadata
412(** [dibuild_create_pointer_type] Create debugging information entry for a
413    pointer. See LLVMDIBuilderCreatePointerType. *)
414
415val dibuild_create_struct_type :
416  lldibuilder ->
417  scope:Llvm.llmetadata ->
418  name:string ->
419  file:Llvm.llmetadata ->
420  line_number:int ->
421  size_in_bits:int ->
422  align_in_bits:int ->
423  lldiflags ->
424  derived_from:Llvm.llmetadata ->
425  elements:Llvm.llmetadata array ->
426  DWARFSourceLanguageKind.t ->
427  vtable_holder:Llvm.llmetadata ->
428  unique_id:string ->
429  Llvm.llmetadata
430(** [dibuild_create_struct_type] Create debugging information entry for a
431    struct. See LLVMDIBuilderCreateStructType *)
432
433val dibuild_create_member_type :
434  lldibuilder ->
435  scope:Llvm.llmetadata ->
436  name:string ->
437  file:Llvm.llmetadata ->
438  line_number:int ->
439  size_in_bits:int ->
440  align_in_bits:int ->
441  offset_in_bits:int ->
442  lldiflags ->
443  ty:Llvm.llmetadata ->
444  Llvm.llmetadata
445(** [dibuild_create_member_type] Create debugging information entry for a
446    member. See LLVMDIBuilderCreateMemberType. *)
447
448val dibuild_create_static_member_type :
449  lldibuilder ->
450  scope:Llvm.llmetadata ->
451  name:string ->
452  file:Llvm.llmetadata ->
453  line_number:int ->
454  ty:Llvm.llmetadata ->
455  lldiflags ->
456  const_val:Llvm.llvalue ->
457  align_in_bits:int ->
458  Llvm.llmetadata
459(** [dibuild_create_static_member_type] Create debugging information entry for
460    a C++ static data member. See LLVMDIBuilderCreateStaticMemberType *)
461
462val dibuild_create_member_pointer_type :
463  lldibuilder ->
464  pointee_type:Llvm.llmetadata ->
465  class_type:Llvm.llmetadata ->
466  size_in_bits:int ->
467  align_in_bits:int ->
468  lldiflags ->
469  Llvm.llmetadata
470(** [dibuild_create_member_pointer_type] Create debugging information entry for
471    a pointer to member. See LLVMDIBuilderCreateMemberPointerType *)
472
473val dibuild_create_object_pointer_type :
474  lldibuilder -> Llvm.llmetadata -> Llvm.llmetadata
475(** [dibuild_create_object_pointer_type dib ty] Create a uniqued DIType* clone
476  with FlagObjectPointer and FlagArtificial set. [dib] is the dibuilder
477  value and [ty] the underlying type to which this pointer points. *)
478
479val dibuild_create_qualified_type :
480  lldibuilder -> tag:int -> Llvm.llmetadata -> Llvm.llmetadata
481(** [dibuild_create_qualified_type dib tag ty] Create debugging information
482    entry for a qualified type, e.g. 'const int'. [dib] is the dibuilder value,
483    [tag] identifyies the type and [ty] is the base type. *)
484
485val dibuild_create_reference_type :
486  lldibuilder -> tag:int -> Llvm.llmetadata -> Llvm.llmetadata
487(** [dibuild_create_reference_type dib tag ty] Create debugging information
488    entry for a reference type. [dib] is the dibuilder value, [tag] identifyies
489    the type and [ty] is the base type. *)
490
491val dibuild_create_null_ptr_type : lldibuilder -> Llvm.llmetadata
492(** [dibuild_create_null_ptr_type dib] Create C++11 nullptr type. *)
493
494val dibuild_create_typedef :
495  lldibuilder ->
496  ty:Llvm.llmetadata ->
497  name:string ->
498  file:Llvm.llmetadata ->
499  line_no:int ->
500  scope:Llvm.llmetadata ->
501  align_in_bits:int ->
502  Llvm.llmetadata
503(** [dibuild_create_typedef] Create debugging information entry for a typedef.
504    See LLVMDIBuilderCreateTypedef. *)
505
506val dibuild_create_inheritance :
507  lldibuilder ->
508  ty:Llvm.llmetadata ->
509  base_ty:Llvm.llmetadata ->
510  base_offset:int ->
511  vb_ptr_offset:int ->
512  lldiflags ->
513  Llvm.llmetadata
514(** [dibuild_create_inheritance] Create debugging information entry
515    to establish inheritance relationship between two types.
516    See LLVMDIBuilderCreateInheritance. *)
517
518val dibuild_create_forward_decl :
519  lldibuilder ->
520  tag:int ->
521  name:string ->
522  scope:Llvm.llmetadata ->
523  file:Llvm.llmetadata ->
524  line:int ->
525  runtime_lang:int ->
526  size_in_bits:int ->
527  align_in_bits:int ->
528  unique_identifier:string ->
529  Llvm.llmetadata
530(** [dibuild_create_forward_decl] Create a permanent forward-declared type.
531    See LLVMDIBuilderCreateForwardDecl. *)
532
533val dibuild_create_replaceable_composite_type :
534  lldibuilder ->
535  tag:int ->
536  name:string ->
537  scope:Llvm.llmetadata ->
538  file:Llvm.llmetadata ->
539  line:int ->
540  runtime_lang:int ->
541  size_in_bits:int ->
542  align_in_bits:int ->
543  lldiflags ->
544  unique_identifier:string ->
545  Llvm.llmetadata
546(** [dibuild_create_replaceable_composite_type] Create a temporary
547    forward-declared type. See LLVMDIBuilderCreateReplaceableCompositeType. *)
548
549val dibuild_create_bit_field_member_type :
550  lldibuilder ->
551  scope:Llvm.llmetadata ->
552  name:string ->
553  file:Llvm.llmetadata ->
554  line_num:int ->
555  size_in_bits:int ->
556  offset_in_bits:int ->
557  storage_offset_in_bits:int ->
558  lldiflags ->
559  ty:Llvm.llmetadata ->
560  Llvm.llmetadata
561(** [dibuild_create_bit_field_member_type] Create debugging information entry
562    for a bit field member. See LLVMDIBuilderCreateBitFieldMemberType. *)
563
564val dibuild_create_class_type :
565  lldibuilder ->
566  scope:Llvm.llmetadata ->
567  name:string ->
568  file:Llvm.llmetadata ->
569  line_number:int ->
570  size_in_bits:int ->
571  align_in_bits:int ->
572  offset_in_bits:int ->
573  lldiflags ->
574  derived_from:Llvm.llmetadata ->
575  elements:Llvm.llmetadata array ->
576  vtable_holder:Llvm.llmetadata ->
577  template_params_node:Llvm.llmetadata ->
578  unique_identifier:string ->
579  Llvm.llmetadata
580(** [dibuild_create_class_type] Create debugging information entry for a class.
581    See LLVMDIBuilderCreateClassType. *)
582
583val dibuild_create_artificial_type :
584  lldibuilder -> ty:Llvm.llmetadata -> Llvm.llmetadata
585(** [dibuild_create_artificial_type dib ty] Create a uniqued DIType* clone with
586    FlagArtificial set.
587    [dib] is the dibuilder value and [ty] the underlying type. *)
588
589val di_type_get_name : Llvm.llmetadata -> string
590(** [di_type_get_name m] Get the name of DIType [m]. *)
591
592val di_type_get_size_in_bits : Llvm.llmetadata -> int
593(** [di_type_get_size_in_bits m] Get size in bits of DIType [m]. *)
594
595val di_type_get_offset_in_bits : Llvm.llmetadata -> int
596(** [di_type_get_offset_in_bits m] Get offset in bits of DIType [m]. *)
597
598val di_type_get_align_in_bits : Llvm.llmetadata -> int
599(** [di_type_get_align_in_bits m] Get alignment in bits of DIType [m]. *)
600
601val di_type_get_line : Llvm.llmetadata -> int
602(** [di_type_get_line m] Get source line where DIType [m] is declared. *)
603
604val di_type_get_flags : Llvm.llmetadata -> lldiflags
605(** [di_type_get_flags m] Get the flags associated with DIType [m]. *)
606
607val get_subprogram : Llvm.llvalue -> Llvm.llmetadata option
608(** [get_subprogram f] Get the metadata of the subprogram attached to
609    function [f]. *)
610
611val set_subprogram : Llvm.llvalue -> Llvm.llmetadata -> unit
612(** [set_subprogram f m] Set the subprogram [m] attached to function [f]. *)
613
614val di_subprogram_get_line : Llvm.llmetadata -> int
615(** [di_subprogram_get_line m] Get the line associated with subprogram [m]. *)
616
617val instr_get_debug_loc : Llvm.llvalue -> Llvm.llmetadata option
618(** [instr_get_debug_loc i] Get the debug location for instruction [i]. *)
619
620val instr_set_debug_loc : Llvm.llvalue -> Llvm.llmetadata option -> unit
621(** [instr_set_debug_loc i mopt] If [mopt] is None location metadata of [i]
622    is cleared, Otherwise location of [i] is set to the value in [mopt]. *)
623
624val get_metadata_kind : Llvm.llmetadata -> MetadataKind.t
625(** [get_metadata_kind] Obtain the enumerated type of a Metadata instance. *)
626