dyld-43.tar.gz
[apple/dyld.git] / include / mach-o / dyld_gdb.h
1 /*
2 * Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23 #ifndef _DYLD_GDB_
24 #define _DYLD_GDB_
25 /*
26 * This file describes the interface between gdb and dyld created for
27 * MacOS X GM. Prior to MacOS X GM gdb used the dyld_debug interfaces
28 * described in <mach-o/dyld_debug.h>.
29 */
30
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36
37 #define OLD_GDB_DYLD_INTERFACE __ppc__ || __i386__
38
39 #if OLD_GDB_DYLD_INTERFACE
40 /*
41 * gdb_dyld_version is the version of gdb interface that dyld is currently
42 * exporting. For the interface described in this header file gdb_dyld_version
43 * is 2. As the gdb/dyld interface changes this number will be incremented and
44 * comments will be added as to what are the are changes for the various
45 * versions.
46 */
47 extern unsigned int gdb_dyld_version;
48
49 /*
50 * gdb_dyld_state_changed is the internal dyld routine called by dyld to notify
51 * gdb that the state of the data structures has changed. gdb is expected to
52 * put a break point on this routine and re-read the internal dyld data
53 * structures below when this break point is hit.
54 */
55 extern void gdb_dyld_state_changed(void);
56
57 /*
58 * gdb looks directly at parts of two of dyld's internal data structures. The
59 * list of object file images and the list of library images. The parts of
60 * these structures that gdb looks at will not change unless the value of
61 * gdb_dyld_version changes. The size of these structures and the other fields
62 * that gdb does not look at may change.
63 *
64 * struct object_images {
65 * struct object_image images[NOBJECT_IMAGES];
66 * unsigned long nimages;
67 * struct object_images *next_images;
68 * ...
69 * };
70 *
71 * struct library_images {
72 * struct library_image images[NLIBRARY_IMAGES];
73 * unsigned long nimages;
74 * struct library_images *next_images;
75 * ...
76 * };
77 *
78 * Both the object_image structure and the library_image structure
79 * start with a structure containing the following fields:
80 *
81 * struct image {
82 * char *physical_name; physical image name (file name)
83 * unsigned long vmaddr_slide; the slide from the staticly linked address
84 * struct mach_header *mh; address of the mach header of the image
85 * unsigned long valid; TRUE if this is struct is valid
86 * char *name; image name for reporting errors
87 * ...
88 * };
89 *
90 * In gdb_dyld_version 1 the first field was "name". In gdb_dyld_version 2 the
91 * first field was changed to "physical_name" and a new fifth field "name" was
92 * added. These two fields are set to the same values except in the case of
93 * zero-link. In zero-link the NSLinkModule() option
94 * NSLINKMODULE_OPTION_TRAILING_PHYS_NAME is used and then the physical_name is
95 * the file name of the module zero-link loaded that is part of the logical
96 * image "name".
97 */
98
99 /* object_images is the global object_images structure */
100
101 /* the number of gdb_object_image structures present per bucket */
102 extern unsigned int gdb_nobject_images;
103
104 /* the size of each gdb_object_image structure */
105 extern unsigned int gdb_object_image_size;
106
107 /* library_images is the global library_images structure */
108
109 /* the number of gdb_library_image structures present per bucket */
110 extern unsigned int gdb_nlibrary_images;
111
112 /* the size of each gdb_library_image structure */
113 extern unsigned int gdb_library_image_size;
114
115 #endif /* OLD_GDB_DYLD_INTERFACE */
116
117
118 /*
119 * Beginning in Mac OS X 10.4, there is a new mechanism for dyld to notify gdb and other about new images.
120 *
121 *
122 */
123
124 enum dyld_image_mode { dyld_image_adding=0, dyld_image_removing=1 };
125
126 struct dyld_image_info {
127 const struct mach_header* imageLoadAddress; /* base address image is mapped into */
128 const char* imageFilePath; /* path dyld used to load the image */
129 uintptr_t imageFileModDate; /* time_t of image file */
130 /* if stat().st_mtime of imageFilePath does not match imageFileModDate, */
131 /* then file has been modified since dyld loaded it */
132 };
133
134
135 typedef void (*dyld_image_notifier)(enum dyld_image_mode mode, uint32_t infoCount, const struct dyld_image_info info[]);
136
137 /*
138 * gdb looks for the symbol "_dyld_all_image_infos" in dyld. It contains the fields below.
139 *
140 * For a snap shot of what images are currently loaded, the infoArray fields contain a pointer
141 * to an array of all images. If infoArray is NULL, it means it is being modified, come back later.
142 *
143 * To be notified of changes, gdb sets a break point on the notification field. The function
144 * it points to is called by dyld with an array of information about what images have been added
145 * (dyld_image_adding) or are about to be removed (dyld_image_removing).
146 *
147 * The notification is called after infoArray is updated. This means that if gdb attaches to a process
148 * and infoArray is NULL, gdb can set a break point on notification and let the proccess continue to
149 * run until the break point. Then gdb can inspect the full infoArray.
150 */
151 struct dyld_all_image_infos {
152 uint32_t version; /* == 1 in Mac OS X 10.4 */
153 uint32_t infoArrayCount;
154 const struct dyld_image_info* infoArray;
155 dyld_image_notifier notification;
156 bool processDetachedFromSharedRegion;
157 };
158 extern struct dyld_all_image_infos dyld_all_image_infos;
159
160
161
162
163 #ifdef __cplusplus
164 }
165 #endif
166
167 #endif /* _DYLD_GDB_ */