cctools/include/mach-o/dyld_debug.h

   1 /*
   2  * Copyright (c) 1999 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_DEBUG_
  24 #define _DYLD_DEBUG_
  25
  26 #include <mach/mach.h>
  27 #ifndef DYLD_BUILD /* do not include this when building dyld itself */
  28 #include <mach-o/dyld.h>
  29 #endif /* !defined(DYLD_BUILD) */
  30 /*
  31  * The dyld debugging API.
  32  */
  33 enum dyld_debug_return {
  34     DYLD_SUCCESS,
  35     DYLD_INCONSISTENT_DATA,
  36     DYLD_INVALID_ARGUMENTS,
  37     DYLD_FAILURE
  38 };
  39
  40 struct dyld_debug_module {
  41     struct mach_header *header;
  42     unsigned long vmaddr_slide;
  43     unsigned long module_index;
  44 };
  45
  46 enum dyld_event_type {
  47     DYLD_IMAGE_ADDED,
  48     DYLD_MODULE_BOUND,
  49     DYLD_MODULE_REMOVED,
  50     DYLD_MODULE_REPLACED,
  51     DYLD_PAST_EVENTS_END,
  52     DYLD_IMAGE_REMOVED
  53 };
  54
  55 struct dyld_event {
  56     enum dyld_event_type type;
  57     struct dyld_debug_module arg[2];
  58 };
  59
  60 extern enum dyld_debug_return _dyld_debug_defining_module(
  61     mach_port_t target_task,
  62     unsigned long send_timeout,
  63     unsigned long rcv_timeout,
  64     boolean_t inconsistent_data_ok,
  65     char *name,
  66     struct dyld_debug_module *module);
  67
  68 extern enum dyld_debug_return _dyld_debug_is_module_bound(
  69     mach_port_t target_task,
  70     unsigned long send_timeout,
  71     unsigned long rcv_timeout,
  72     boolean_t inconsistent_data_ok,
  73     struct dyld_debug_module module,
  74     boolean_t *bound);
  75
  76 extern enum dyld_debug_return _dyld_debug_bind_module(
  77     mach_port_t target_task,
  78     unsigned long send_timeout,
  79     unsigned long rcv_timeout,
  80     boolean_t inconsistent_data_ok,
  81     struct dyld_debug_module module);
  82
  83 extern enum dyld_debug_return _dyld_debug_module_name(
  84     mach_port_t target_task,
  85     unsigned long send_timeout,
  86     unsigned long rcv_timeout,
  87     boolean_t inconsistent_data_ok,
  88     struct dyld_debug_module module,
  89     char **image_name,
  90     unsigned long *image_nameCnt,
  91     char **module_name,
  92     unsigned long *module_nameCnt);
  93
  94 extern enum dyld_debug_return _dyld_debug_subscribe_to_events(
  95     mach_port_t target_task,
  96     unsigned long send_timeout,
  97     unsigned long rcv_timeout,
  98     boolean_t inconsistent_data_ok,
  99     void (*dyld_event_routine)(struct dyld_event event));
 100
 101 /*
 102  * _dyld_debug_add_event_subscriber() uses the mig interface functions below
 103  * to dispatch the dyld event messages from the subscriber port specified.
 104  */
 105 extern enum dyld_debug_return _dyld_debug_add_event_subscriber(
 106     mach_port_t target_task,
 107     unsigned long send_timeout,
 108     unsigned long rcv_timeout,
 109     boolean_t inconsistent_data_ok,
 110     mach_port_t subscriber);
 111
 112 /*
 113  * These structures should be produced by mig(1) from the mig generated files
 114  * but they are not.  These are really only needed so the correct size of the
 115  * request and reply messages can be allocated.
 116  */
 117 struct _dyld_event_message_request {
 118 #ifdef __MACH30__
 119     mach_msg_header_t head;
 120     NDR_record_t NDR;
 121     struct dyld_event event;
 122     mach_msg_trailer_t trailer;
 123 #else
 124     msg_header_t head;
 125     msg_type_t eventType;
 126     struct dyld_event event;
 127 #endif
 128 };
 129 struct _dyld_event_message_reply {
 130 #ifdef __MACH30__
 131     mach_msg_header_t head;
 132     NDR_record_t NDR;
 133     struct dyld_event event;
 134 #else
 135     msg_header_t head;
 136     msg_type_t RetCodeType;
 137     kern_return_t RetCode;
 138 #endif
 139 };
 140 #ifndef mig_internal
 141 /*
 142  * _dyld_event_server() is the mig generated routine to dispatch dyld event
 143  * messages.
 144  */
 145 extern boolean_t _dyld_event_server(
 146 #ifdef __MACH30__
 147     mach_msg_header_t *request,
 148     mach_msg_header_t *reply);
 149 #else
 150     struct _dyld_event_message_request *request,
 151     struct _dyld_event_message_reply *reply);
 152 #endif
 153 #endif /* mig_internal */
 154
 155 #ifndef SHLIB
 156 /*
 157  * _dyld_event_server_callback() is the routine called by _dyld_event_server()
 158  * that must be written by users of _dyld_event_server().
 159  */
 160 extern
 161 #ifdef __MACH30__
 162 kern_return_t
 163 #else
 164 void
 165 #endif
 166 _dyld_event_server_callback(
 167 #ifdef __MACH30__
 168     mach_port_t subscriber,
 169 #else
 170     port_t subscriber,
 171 #endif
 172     struct dyld_event event);
 173 #endif /* SHLIB */
 174
 175 /*
 176  * This is the state of the target task while we are sending a message to it.
 177  */
 178 struct _dyld_debug_task_state {
 179     mach_port_t    debug_port;
 180     mach_port_t    debug_thread;
 181     unsigned int   debug_thread_resume_count;
 182     unsigned int   task_resume_count;
 183     mach_port_t   *threads;
 184     unsigned int   thread_count;
 185 };
 186
 187 /*
 188  * _dyld_debug_make_runnable() is called before sending messages to the
 189  * dynamic link editor.  Basically it assures that the debugging
 190  * thread is the only runnable thread in the task to receive the
 191  * message.  It also assures that the debugging thread is indeed
 192  * runnable if it was suspended.  The function will make sure each
 193  * thread in the remote task is suspended and resumed the same number
 194  * of times, so in the end the suspend count of each individual thread
 195  * is the same.
 196  */
 197 extern enum dyld_debug_return _dyld_debug_make_runnable(
 198     mach_port_t target_task,
 199     struct _dyld_debug_task_state *state);
 200
 201 /*
 202  * _dyld_debug_restore_runnable() is called after sending messages to the
 203  * dynamic link editor.  It undoes what _dyld_debug_make_runnable() did to the
 204  * task and put it back the way it was.
 205  */
 206 extern enum dyld_debug_return _dyld_debug_restore_runnable(
 207     mach_port_t target_task,
 208     struct _dyld_debug_task_state *state);
 209
 210 /*
 211  * To provide more detailed information when the APIs of the dyld debug
 212  * interfaces fail (return DYLD_FAILURE) the following structure is filled in.
 213  * After it is filled in the function registered with
 214  * set_dyld_debug_error_func() is called with a pointer to that struct.
 215  *
 216  * The local_error field is a unique number for each possible error condition
 217  * in the source code in that makes up the dyld debug APIs.  The source file
 218  * and line number in the cctools libdyld directory where the dyld debug APIs
 219  * are implemented are set into the file_name and line_number fields.  The
 220  * field dyld_debug_return is filled in with that would be returned by the
 221  * API (usually DYLD_FAILURE).  The other fields will be zero or filled in by
 222  * the error code from the mach system call, or UNIX system call that failed.
 223  */
 224 struct dyld_debug_error_data {
 225     enum dyld_debug_return dyld_debug_return;
 226     kern_return_t mach_error;
 227     int dyld_debug_errno;
 228     unsigned long local_error;
 229     char *file_name;
 230     unsigned long line_number;
 231 };
 232
 233 extern void _dyld_debug_set_error_func(
 234     void (*func)(struct dyld_debug_error_data *e));
 235
 236 #ifndef DYLD_BUILD /* do not include this when building dyld itself */
 237
 238 extern enum dyld_debug_return _dyld_debug_task_from_core(
 239     NSObjectFileImage coreFileImage,
 240     mach_port_t *core_task);
 241
 242 #endif /* !defined(DYLD_BUILD) */
 243
 244 #endif /* _DYLD_DEBUG_ */