← Back to branch summary

~ubuntu-branches/ubuntu/trusty/eglibc/trusty

« back to all changes in this revision

Viewing changes to elf/rtld-debugger-interface.txt

  • Committer: Package Import Robot
  • Author(s): Adam Conrad
  • Date: 2013-01-10 18:39:35 UTC
  • mfrom: (1.5.2) (4.4.24 experimental)
  • Revision ID: package-import@ubuntu.com-20130110183935-afsgfxkmg7wk5eaj
Tags: 2.17-0ubuntu1
https://launchpad.net/bugs/1085342
https://launchpad.net/bugs/613662
* Merge with Debian, bringing in a new upstream and many small fixes:
  - patches/any/cvs-malloc-deadlock.diff: Dropped, merged upstream.
  - patches/ubuntu/lddebug-scopes.diff: Rebase for upstream changes.
  - patches/ubuntu/local-CVE-2012-3406.diff: Rebased against upstream.
  - patches/ubuntu/no-asm-mtune-i686.diff: Fixed in recent binutils.
* This upstream merge fixes a nasty hang in pulseaudio (LP: #1085342)
* Bump MIN_KERNEL_SUPPORTED to 2.6.32 on ARM, now that we no longer
  have to support shonky 2.6.31 kernels on imx51 babbage builders.
* Drop patches/ubuntu/local-disable-nscd-host-caching.diff, as these
  issues were apparently resolved upstream a while ago (LP: #613662)
* Fix the compiled-in bug URL to point to launchpad.net, not Debian.

Show diffs side-by-side

added added

removed removed

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