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_ */