]>
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 | 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 | ||
30 | This protocol is widely supported, but somewhat limited in that it | |
31 | has no provision to provide access to multiple namespaces, and that | |
32 | the notifications (via r_brk) only refer to changes to r_map--the | |
33 | debugger is notified that a new object has been added, for instance, | |
34 | but there is no way for the debugger to discover whether any of the | |
35 | objects in the link-map have been relocated or not. | |
36 | ||
37 | ||
38 | Extension to the r_debug structure | |
39 | ================================== | |
40 | ||
41 | The r_debug_extended structure is an extension of the r_debug interface. | |
42 | If 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 | ||
50 | Probe-based debugger interface | |
51 | ============================== | |
52 | ||
53 | Systemtap is a dynamic tracing/instrumenting tool available on Linux. | |
54 | Probes that are not fired at run time have close to zero overhead. | |
55 | glibc contains a number of probes that debuggers can set breakpoints | |
56 | on in order to notice certain events. | |
57 | ||
58 | All 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 | ||
71 | map_complete and reloc_complete may have the following additional | |
72 | argument: | |
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 | ||
84 | The 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. |