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     OBJC_AVAILABLE(10.6, 3.1, 9.0, 1.0);
  53 #else
  54     OBJC_AVAILABLE(10.7, 3.1, 9.0, 1.0);
  55 #endif
  56
  57 // Same as gdb_class_getClass(object_getClass(cls)).
  58 OBJC_EXPORT Class gdb_object_getClass(id obj)
  59     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0);
  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     OBJC_AVAILABLE(10.6, 3.1, 9.0, 1.0);
  71
  72 #else
  73
  74 // Hashes Classes, for all known classes. Custom prototype.
  75 OBJC_EXPORT NXHashTable *_objc_debug_class_hash
  76     __OSX_AVAILABLE(10.2)
  77     __IOS_UNAVAILABLE __TVOS_UNAVAILABLE __WATCHOS_UNAVAILABLE;
  78
  79 #endif
  80
  81
  82 /***********************************************************************
  83 * Non-pointer isa
  84 **********************************************************************/
  85
  86 #if __OBJC2__
  87
  88 // Extract isa pointer from an isa field.
  89 // (Class)(isa & mask) == class pointer
  90 OBJC_EXPORT const uintptr_t objc_debug_isa_class_mask
  91     OBJC_AVAILABLE(10.10, 7.0, 9.0, 1.0);
  92
  93 // Extract magic cookie from an isa field.
  94 // (isa & magic_mask) == magic_value
  95 OBJC_EXPORT const uintptr_t objc_debug_isa_magic_mask
  96     OBJC_AVAILABLE(10.10, 7.0, 9.0, 1.0);
  97 OBJC_EXPORT const uintptr_t objc_debug_isa_magic_value
  98     OBJC_AVAILABLE(10.10, 7.0, 9.0, 1.0);
  99
 100 // Use indexed ISAs for targets which store index of the class in the ISA.
 101 // This index can be used to index the array of classes.
 102 OBJC_EXPORT const uintptr_t objc_debug_indexed_isa_magic_mask;
 103 OBJC_EXPORT const uintptr_t objc_debug_indexed_isa_magic_value;
 104
 105 // Then these are used to extract the index from the ISA.
 106 OBJC_EXPORT const uintptr_t objc_debug_indexed_isa_index_mask;
 107 OBJC_EXPORT const uintptr_t objc_debug_indexed_isa_index_shift;
 108
 109 // And then we can use that index to get the class from this array.  Note
 110 // the size is provided so that clients can ensure the index they get is in
 111 // bounds and not read off the end of the array.
 112 OBJC_EXPORT Class objc_indexed_classes[];
 113
 114 // When we don't have enough bits to store a class*, we can instead store an
 115 // index in to this array.  Classes are added here when they are realized.
 116 // Note, an index of 0 is illegal.
 117 OBJC_EXPORT uintptr_t objc_indexed_classes_count;
 118
 119 // Absolute symbols for some of the above values are in objc-abi.h.
 120
 121 #endif
 122
 123
 124 /***********************************************************************
 125 * Tagged pointer decoding
 126 **********************************************************************/
 127 #if __OBJC2__
 128
 129 // Basic tagged pointers (7 classes, 60-bit payload).
 130
 131 // if (obj & mask) obj is a tagged pointer object
 132 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_mask
 133     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0);
 134
 135 // tag_slot = (obj >> slot_shift) & slot_mask
 136 OBJC_EXPORT unsigned int objc_debug_taggedpointer_slot_shift
 137     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0);
 138 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_slot_mask
 139     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0);
 140
 141 // class = classes[tag_slot]
 142 OBJC_EXPORT Class objc_debug_taggedpointer_classes[]
 143     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0);
 144
 145 // payload = (obj << payload_lshift) >> payload_rshift
 146 // Payload signedness is determined by the signedness of the right-shift.
 147 OBJC_EXPORT unsigned int objc_debug_taggedpointer_payload_lshift
 148     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0);
 149 OBJC_EXPORT unsigned int objc_debug_taggedpointer_payload_rshift
 150     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0);
 151
 152
 153 // Extended tagged pointers (255 classes, 52-bit payload).
 154
 155 // If you interrogate an extended tagged pointer using the basic
 156 // tagged pointer scheme alone, it will appear to have an isa
 157 // that is either nil or class __NSUnrecognizedTaggedPointer.
 158
 159 // if (ext_mask != 0  &&  (obj & ext_mask) == ext_mask)
 160 //   obj is a ext tagged pointer object
 161 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_ext_mask
 162     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0);
 163
 164 // ext_tag_slot = (obj >> ext_slot_shift) & ext_slot_mask
 165 OBJC_EXPORT unsigned int objc_debug_taggedpointer_ext_slot_shift
 166     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0);
 167 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_ext_slot_mask
 168     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0);
 169
 170 // class = ext_classes[ext_tag_slot]
 171 OBJC_EXPORT Class objc_debug_taggedpointer_ext_classes[]
 172     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0);
 173
 174 // payload = (obj << ext_payload_lshift) >> ext_payload_rshift
 175 // Payload signedness is determined by the signedness of the right-shift.
 176 OBJC_EXPORT unsigned int objc_debug_taggedpointer_ext_payload_lshift
 177     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0);
 178 OBJC_EXPORT unsigned int objc_debug_taggedpointer_ext_payload_rshift
 179     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0);
 180
 181 #endif
 182
 183
 184 /***********************************************************************
 185 * Breakpoints in objc_msgSend for debugger stepping.
 186 * The array is a {0,0} terminated list of addresses.
 187 * Each address is one of the following:
 188 * OBJC_MESSENGER_START:    Address is the start of a messenger function.
 189 * OBJC_MESSENGER_END_FAST: Address is a jump insn that calls an IMP.
 190 * OBJC_MESSENGER_END_SLOW: Address is some insn in the slow lookup path.
 191 * OBJC_MESSENGER_END_NIL:  Address is a return insn for messages to nil.
 192 *
 193 * Every path from OBJC_MESSENGER_START should reach some OBJC_MESSENGER_END.
 194 * At all ENDs, the stack and parameter register state is the same as START.
 195 *
 196 * In some cases, the END_FAST case jumps to something other than the
 197 * method's implementation. In those cases the jump's destination will
 198 * be another function that is marked OBJC_MESSENGER_START.
 199 **********************************************************************/
 200 #if __OBJC2__
 201
 202 #define OBJC_MESSENGER_START    1
 203 #define OBJC_MESSENGER_END_FAST 2
 204 #define OBJC_MESSENGER_END_SLOW 3
 205 #define OBJC_MESSENGER_END_NIL  4
 206
 207 struct objc_messenger_breakpoint {
 208     uintptr_t address;
 209     uintptr_t kind;
 210 };
 211
 212 OBJC_EXPORT struct objc_messenger_breakpoint
 213 gdb_objc_messenger_breakpoints[]
 214     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0);
 215
 216 #endif
 217
 218
 219 __END_DECLS
 220
 221 #endif
 222
 223 #endif