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 /***********************************************************************
  46 * Class pointer preflighting
  47 **********************************************************************/
  48
  49 // Return cls if it's a valid class, or crash.
  50 OBJC_EXPORT Class gdb_class_getClass(Class cls)
  51 #if __OBJC2__
  52     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_1);
  53 #else
  54     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_3_1);
  55 #endif
  56
  57 // Same as gdb_class_getClass(object_getClass(cls)).
  58 OBJC_EXPORT Class gdb_object_getClass(id obj)
  59     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
  60
  61
  62 /***********************************************************************
  63 * Class lists for heap.
  64 **********************************************************************/
  65
  66 #if __OBJC2__
  67
  68 // Maps class name to Class, for in-use classes only. NXStrValueMapPrototype.
  69 OBJC_EXPORT NXMapTable *gdb_objc_realized_classes
  70     __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_1);
  71
  72 #else
  73
  74 // Hashes Classes, for all known classes. Custom prototype.
  75 OBJC_EXPORT NXHashTable *_objc_debug_class_hash
  76     __OSX_AVAILABLE_STARTING(__MAC_10_2, __IPHONE_NA);
  77
  78 #endif
  79
  80
  81 /***********************************************************************
  82 * Non-pointer isa
  83 **********************************************************************/
  84
  85 #if __OBJC2__
  86
  87 // Extract isa pointer from an isa field.
  88 // (Class)(isa & mask) == class pointer
  89 OBJC_EXPORT const uintptr_t objc_debug_isa_class_mask
  90     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0);
  91
  92 // Extract magic cookie from an isa field.
  93 // (isa & magic_mask) == magic_value
  94 OBJC_EXPORT const uintptr_t objc_debug_isa_magic_mask
  95     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0);
  96 OBJC_EXPORT const uintptr_t objc_debug_isa_magic_value
  97     __OSX_AVAILABLE_STARTING(__MAC_10_10, __IPHONE_7_0);
  98
  99 #endif
 100
 101
 102 /***********************************************************************
 103 * Tagged pointer decoding
 104 **********************************************************************/
 105 #if __OBJC2__
 106
 107 // if (obj & mask) obj is a tagged pointer object
 108 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_mask
 109     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 110
 111 // tag_slot = (obj >> slot_shift) & slot_mask
 112 OBJC_EXPORT unsigned int objc_debug_taggedpointer_slot_shift
 113     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 114 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_slot_mask
 115     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 116
 117 // class = classes[tag_slot]
 118 OBJC_EXPORT Class objc_debug_taggedpointer_classes[]
 119     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 120
 121 // payload = (obj << payload_lshift) >> payload_rshift
 122 // Payload signedness is determined by the signedness of the right-shift.
 123 OBJC_EXPORT unsigned int objc_debug_taggedpointer_payload_lshift
 124     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 125 OBJC_EXPORT unsigned int objc_debug_taggedpointer_payload_rshift
 126     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 127
 128 #endif
 129
 130
 131 /***********************************************************************
 132 * Breakpoints in objc_msgSend for debugger stepping.
 133 * The array is a {0,0} terminated list of addresses.
 134 * Each address is one of the following:
 135 * OBJC_MESSENGER_START:    Address is the start of a messenger function.
 136 * OBJC_MESSENGER_END_FAST: Address is a jump insn that calls an IMP.
 137 * OBJC_MESSENGER_END_SLOW: Address is some insn in the slow lookup path.
 138 * OBJC_MESSENGER_END_NIL:  Address is a return insn for messages to nil.
 139 *
 140 * Every path from OBJC_MESSENGER_START should reach some OBJC_MESSENGER_END.
 141 * At all ENDs, the stack and parameter register state is the same as START.
 142 *
 143 * In some cases, the END_FAST case jumps to something other than the
 144 * method's implementation. In those cases the jump's destination will
 145 * be another function that is marked OBJC_MESSENGER_START.
 146 **********************************************************************/
 147 #if __OBJC2__
 148
 149 #define OBJC_MESSENGER_START    1
 150 #define OBJC_MESSENGER_END_FAST 2
 151 #define OBJC_MESSENGER_END_SLOW 3
 152 #define OBJC_MESSENGER_END_NIL  4
 153
 154 struct objc_messenger_breakpoint {
 155     uintptr_t address;
 156     uintptr_t kind;
 157 };
 158
 159 OBJC_EXPORT struct objc_messenger_breakpoint
 160 gdb_objc_messenger_breakpoints[]
 161     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 162
 163 #endif
 164
 165
 166 #ifndef OBJC_NO_GC
 167
 168 /***********************************************************************
 169  * Garbage Collector heap dump
 170 **********************************************************************/
 171
 172 /* Dump GC heap; if supplied the name is returned in filenamebuffer.  Returns YES on success. */
 173 OBJC_EXPORT BOOL objc_dumpHeap(char *filenamebuffer, unsigned long length)
 174     __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 175
 176 #define OBJC_HEAP_DUMP_FILENAME_FORMAT "/tmp/objc-gc-heap-dump-%d-%d"
 177
 178 #endif
 179
 180 __END_DECLS
 181
 182 #endif
 183
 184 #endif