]>
Commit | Line | Data |
---|---|---|
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. |