runtime/objc-gdb.h

   1 /*
   2  * Copyright (c) 2008 Apple 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
  24 #ifndef _OBJC_GDB_H
  25 #define _OBJC_GDB_H
  26
  27 /*
  28  * WARNING  DANGER  HAZARD  BEWARE  EEK
  29  *
  30  * Everything in this file is for debugger and developer tool use only.
  31  * These will change in arbitrary OS updates and in unpredictable ways.
  32  * When your program breaks, you get to keep both pieces.
  33  */
  34
  35 #ifdef __APPLE_API_PRIVATE
  36
  37 #define _OBJC_PRIVATE_H_
  38 #include <stdint.h>
  39 #include <objc/hashtable.h>
  40 #include <objc/maptable.h>
  41
  42 __BEGIN_DECLS
  43
  44 /***********************************************************************
  45 * Trampoline descriptors for gdb.
  46 **********************************************************************/
  47
  48 #if __OBJC2__  &&  defined(__x86_64__)
  49
  50 typedef struct {
  51     uint32_t offset;  // 0 = unused, else code = (uintptr_t)desc + desc->offset
  52     uint32_t flags;
  53 } objc_trampoline_descriptor;
  54 #define OBJC_TRAMPOLINE_MESSAGE (1<<0)   // trampoline acts like objc_msgSend
  55 #define OBJC_TRAMPOLINE_STRET   (1<<1)   // trampoline is struct-returning
  56 #define OBJC_TRAMPOLINE_VTABLE  (1<<2)   // trampoline is vtable dispatcher
  57
  58 typedef struct objc_trampoline_header {
  59     uint16_t headerSize;  // sizeof(objc_trampoline_header)
  60     uint16_t descSize;    // sizeof(objc_trampoline_descriptor)
  61     uint32_t descCount;   // number of descriptors following this header
  62     struct objc_trampoline_header *next;
  63 } objc_trampoline_header;
  64
  65 OBJC_EXPORT objc_trampoline_header *gdb_objc_trampolines
  66     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
  67
  68 OBJC_EXPORT void gdb_objc_trampolines_changed(objc_trampoline_header *thdr)
  69     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_NA);
  70 // Notify gdb that gdb_objc_trampolines has changed.
  71 // thdr itself includes the new descriptors; thdr->next is not new.
  72
  73 #endif
  74
  75
  76 /***********************************************************************
  77 * Debugger mode.
  78 **********************************************************************/
  79
  80 // Start debugger mode.
  81 // Returns non-zero if debugger mode was successfully started.
  82 // In debugger mode, you can try to use the runtime without deadlocking
  83 // on other threads. All other threads must be stopped during debugger mode.
  84 // OBJC_DEBUGMODE_FULL requires more locks so later operations are less
  85 // likely to fail.
  86 #define OBJC_DEBUGMODE_FULL (1<<0)
  87 OBJC_EXPORT int gdb_objc_startDebuggerMode(uint32_t flags)
  88     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_1);
  89
  90 // Stop debugger mode. Do not call if startDebuggerMode returned zero.
  91 OBJC_EXPORT void gdb_objc_endDebuggerMode(void)
  92     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_1);
  93
  94 // Failure hook when debugger mode tries something that would block.
  95 // Set a breakpoint here to handle it before the runtime causes a trap.
  96 // Debugger mode is still active; call endDebuggerMode to end it.
  97 OBJC_EXPORT void gdb_objc_debuggerModeFailure(void)
  98     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_1);
  99
 100 // Older debugger-mode mechanism. Too simplistic.
 101 OBJC_EXPORT BOOL gdb_objc_isRuntimeLocked(void)
 102     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_1);
 103
 104 // Return cls if it's a valid class, or crash.
 105 OBJC_EXPORT Class gdb_class_getClass(Class cls)
 106 #if __OBJC2__
 107     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_1);
 108 #else
 109     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_3_1);
 110 #endif
 111
 112 // Same as gdb_class_getClass(object_getClass(cls)).
 113 OBJC_EXPORT Class gdb_object_getClass(id obj)
 114     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
 115
 116
 117 /***********************************************************************
 118 * Class lists for heap.
 119 **********************************************************************/
 120
 121 #if __OBJC2__
 122
 123 // Maps class name to Class, for in-use classes only. NXStrValueMapPrototype.
 124 OBJC_EXPORT NXMapTable *gdb_objc_realized_classes
 125     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_1);
 126
 127 #else
 128
 129 // Hashes Classes, for all known classes. Custom prototype.
 130 OBJC_EXPORT NXHashTable *_objc_debug_class_hash
 131     __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA);
 132
 133 #endif
 134
 135
 136 #ifndef OBJC_NO_GC
 137
 138 /***********************************************************************
 139  * Garbage Collector heap dump
 140 **********************************************************************/
 141
 142 /* Dump GC heap; if supplied the name is returned in filenamebuffer.  Returns YES on success. */
 143 OBJC_EXPORT BOOL objc_dumpHeap(char *filenamebuffer, unsigned long length)
 144     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 145
 146 #define OBJC_HEAP_DUMP_FILENAME_FORMAT "/tmp/objc-gc-heap-dump-%d-%d"
 147
 148 #endif
 149
 150 __END_DECLS
 151
 152 #endif
 153
 154 #endif