1 /**************************************************************************/
2 /*                                                                        */
3 /*                                 OCaml                                  */
4 /*                                                                        */
5 /*             Xavier Leroy, projet Cristal, INRIA Rocquencourt           */
6 /*                                                                        */
7 /*   Copyright 2001 Institut National de Recherche en Informatique et     */
8 /*     en Automatique.                                                    */
9 /*                                                                        */
10 /*   All rights reserved.  This file is distributed under the terms of    */
11 /*   the GNU Lesser General Public License version 2.1, with the          */
12 /*   special exception on linking described in the file LICENSE.          */
13 /*                                                                        */
14 /**************************************************************************/
15 
16 #ifndef CAML_BACKTRACE_PRIM_H
17 #define CAML_BACKTRACE_PRIM_H
18 
19 #ifdef CAML_INTERNALS
20 
21 #include "backtrace.h"
22 
23 /* Backtrace generation is split in [backtrace.c] and [backtrace_prim.c].
24  *
25  * [backtrace_prim.c] contains all backend-specific code, and has two different
26  * implementations in [byterun/backtrace_prim.c] and [asmrun/backtrace_prim.c].
27  *
28  * [backtrace.c] has a unique implementation, and expose a uniform
29  * higher level API above [backtrace_prim.c].
30  */
31 
32 /* Extract location information for the given raw_backtrace_slot */
33 
34 struct caml_loc_info {
35   int loc_valid;
36   int loc_is_raise;
37   char * loc_filename;
38   int loc_lnum;
39   int loc_startchr;
40   int loc_endchr;
41   int loc_is_inlined;
42 };
43 
44 /* When compiling with -g, backtrace slots have debug info associated.
45  * When a call is inlined in native mode, debuginfos form a linked list.
46  */
47 typedef void * debuginfo;
48 
49 /* Check availability of debug information before extracting a trace.
50  * Relevant for bytecode, always true for native code. */
51 int caml_debug_info_available(void);
52 
53 /* Return debuginfo associated to a slot or NULL. */
54 debuginfo caml_debuginfo_extract(backtrace_slot slot);
55 
56 /* In case of an inlined call return next debuginfo or NULL otherwise. */
57 debuginfo caml_debuginfo_next(debuginfo dbg);
58 
59 /* Extract locations from backtrace_slot */
60 void caml_debuginfo_location(debuginfo dbg, /*out*/ struct caml_loc_info * li);
61 
62 /* In order to prevent the GC from walking through the debug
63    information (which have no headers), we transform slots to 31/63 bits
64    ocaml integers by shifting them by 1 to the right. We do not lose
65    information as slots are aligned.
66 
67    In particular, we do not need to use [caml_modify] when setting
68    an array element with such a value.
69  */
70 #define Val_backtrace_slot(bslot) (Val_long(((uintnat)(bslot))>>1))
71 #define Backtrace_slot_val(vslot) ((backtrace_slot)(Long_val(vslot) << 1))
72 
73 /* Allocate the caml_backtrace_buffer. Returns 0 on success, -1 otherwise */
74 int caml_alloc_backtrace_buffer(void);
75 
76 #define BACKTRACE_BUFFER_SIZE 1024
77 
78 /* Besides decoding backtrace info, [backtrace_prim] has two other
79  * responsibilities:
80  *
81  * It defines the [caml_stash_backtrace] function, which is called to quickly
82  * fill the backtrace buffer by walking the stack when an exception is raised.
83  *
84  * It also defines the [caml_get_current_callstack] OCaml primitive, which also
85  * walks the stack but directly turns it into a [raw_backtrace] and is called
86  * explicitly.
87  */
88 
89 #endif /* CAML_INTERNALS */
90 
91 #endif /* CAML_BACKTRACE_PRIM_H */
92