1Standard debugger interface
2===========================
3
4The run-time linker exposes a rendezvous structure to allow debuggers
5to interface with it.  This structure, r_debug, is defined in link.h.
6If the executable's dynamic section has a DT_DEBUG element, the
7run-time linker sets that element's value to the address where this
8structure can be found.
9
10The r_debug structure contains (amongst others) the following fields:
11
12  int r_version:
13    Version number for this protocol.  It should be greater than 0.
14
15  struct link_map *r_map:
16    A linked list of loaded objects.
17
18  enum { RT_CONSISTENT, RT_ADD, RT_DELETE } r_state:
19    The current state of the r_map list.  RT_CONSISTENT means that r_map
20    is not currently being modified and may safely be inspected.  RT_ADD
21    means that an object is being added to r_map, and that the list is
22    not guaranteed to be consistent.  Likewise RT_DELETE means that an
23    object is being removed from the list.
24
25  ElfW(Addr) r_brk:
26    The address of a function internal to the run-time linker which is
27    called whenever r_state is changed.  The debugger should set a
28    breakpoint at this address if it wants to notice mapping changes.
29
30This protocol is widely supported, but somewhat limited in that it
31has no provision to provide access to multiple namespaces, and that
32the notifications (via r_brk) only refer to changes to r_map--the
33debugger is notified that a new object has been added, for instance,
34but there is no way for the debugger to discover whether any of the
35objects in the link-map have been relocated or not.
36
37
38Extension to the r_debug structure
39==================================
40
41The r_debug_extended structure is an extension of the r_debug interface.
42If r_version is 2, one additional field is available:
43
44  struct r_debug_extended *r_next;
45    Link to the next r_debug_extended structure.  Each r_debug_extended
46    structure represents a different namespace.  A namespace is active
47    if its r_map field isn't NULL.  The first r_debug_extended structure
48    is for the default namespace.
49
50Probe-based debugger interface
51==============================
52
53Systemtap is a dynamic tracing/instrumenting tool available on Linux.
54Probes that are not fired at run time have close to zero overhead.
55glibc contains a number of probes that debuggers can set breakpoints
56on in order to notice certain events.
57
58All rtld probes have the following arguments:
59
60  arg1: Lmid_t lmid:
61    The link-map ID of the link-map list that the object was loaded
62    into.  This will be LM_ID_BASE for the application's main link-map
63    list, or some other value for different namespaces.
64
65  arg2: struct r_debug *r_debug:
66    A pointer to the r_debug structure containing the link-map list
67    that the object was loaded into.  This will be the value stored in
68    DT_DEBUG for the application's main link-map list, or some other
69    value for different namespaces.
70
71map_complete and reloc_complete may have the following additional
72argument:
73
74  arg3: struct link_map *new:
75    A pointer which, if not NULL, points to the entry in the specified
76    r_debug structure's link-map list corresponding to the first new
77    object to have been mapped or relocated, with new->l_next pointing
78    to the link-map of the next new object to have been mapped or
79    relocated, and so on.  Note that because `new' is an entry in a
80    larger list, new->l_prev (if not NULL) will point to what was the
81    last link-map in the link-map list prior to the new objects being
82    mapped or relocated.
83
84The following probes are available:
85
86  init_start:
87    This is called once, when the linker is about to fill in the main
88    r_debug structure at application startup.  init_start always has
89    lmid set to LM_ID_BASE and r_debug set to the value stored in
90    DT_DEBUG.  r_debug is not guaranteed to be consistent until
91    init_complete is fired.
92
93  init_complete:
94    This is called once, when the linker has filled in the main
95    r_debug structure at application startup. init_complete always
96    has lmid set to LM_ID_BASE and r_debug set to the value stored
97    in DT_DEBUG.  The r_debug structure is consistent and may be
98    inspected, and all objects in the link-map are guaranteed to
99    have been relocated.
100
101  map_start:
102    The linker is about to map new objects into the specified
103    namespace.  The namespace's r_debug structure is not guaranteed
104    to be consistent until a corresponding map_complete is fired.
105
106  map_complete:
107    The linker has finished mapping new objects into the specified
108    namespace.  The namespace's r_debug structure is consistent and
109    may be inspected, although objects in the namespace's link-map
110    are not guaranteed to have been relocated.
111
112  map_failed:
113    The linker failed while attempting to map new objects into
114    the specified namespace.  The namespace's r_debug structure
115    is consistent and may be inspected.
116
117  reloc_start:
118    The linker is about to relocate all unrelocated objects in the
119    specified namespace.  The namespace's r_debug structure is not
120    guaranteed to be consistent until a corresponding reloc_complete
121    is fired.
122
123  reloc_complete:
124    The linker has relocated all objects in the specified namespace.
125    The namespace's r_debug structure is consistent and may be
126    inspected, and all objects in the namespace's link-map are
127    guaranteed to have been relocated.
128
129  unmap_start:
130    The linker is about to remove objects from the specified
131    namespace.  The namespace's r_debug structure is not guaranteed to
132    be consistent until a corresponding unmap_complete is fired.
133
134  unmap_complete:
135    The linker has finished removing objects into the specified
136    namespace.  The namespace's r_debug structure is consistent and
137    may be inspected.
138