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 #ifndef _OBJC_PRIVATE_H_
  38 #   define _OBJC_PRIVATE_H_
  39 #endif
  40 #include <stdint.h>
  41 #include <objc/hashtable.h>
  42 #include <objc/maptable.h>
  43
  44 __BEGIN_DECLS
  45
  46
  47 /***********************************************************************
  48 * Class pointer preflighting
  49 **********************************************************************/
  50
  51 // Return cls if it's a valid class, or crash.
  52 OBJC_EXPORT Class _Nonnull
  53 gdb_class_getClass(Class _Nonnull cls)
  54 #if __OBJC2__
  55     OBJC_AVAILABLE(10.6, 3.1, 9.0, 1.0, 2.0);
  56 #else
  57     OBJC_AVAILABLE(10.7, 3.1, 9.0, 1.0, 2.0);
  58 #endif
  59
  60 // Same as gdb_class_getClass(object_getClass(cls)).
  61 OBJC_EXPORT Class _Nonnull gdb_object_getClass(id _Nullable obj)
  62     OBJC_AVAILABLE(10.7, 4.3, 9.0, 1.0, 2.0);
  63
  64 /***********************************************************************
  65 * Class inspection
  66 **********************************************************************/
  67
  68 #if __OBJC2__
  69
  70 // Return the raw, mangled name of cls.
  71 OBJC_EXPORT const char * _Nonnull
  72 objc_debug_class_getNameRaw(Class _Nullable cls)
  73 OBJC_AVAILABLE(10.15, 13.0, 13.0, 6.0, 5.0);
  74
  75 #endif
  76
  77 /***********************************************************************
  78 * Class lists for heap.
  79 **********************************************************************/
  80
  81 #if __OBJC2__
  82
  83 // Maps class name to Class, for in-use classes only. NXStrValueMapPrototype.
  84 OBJC_EXPORT NXMapTable * _Nullable gdb_objc_realized_classes
  85     OBJC_AVAILABLE(10.6, 3.1, 9.0, 1.0, 2.0);
  86
  87 // A generation count of realized classes. Increments when new classes
  88 // are realized. This is NOT an exact count of the number of classes.
  89 // It's not guaranteed by how much it increases when classes are
  90 // realized, only that it increases by something. When classes are
  91 // removed (unloading bundles or destroying dynamically allocated
  92 // classes) the number will also increase to signal that there has
  93 // been a change.
  94 OBJC_EXPORT uintptr_t objc_debug_realized_class_generation_count;
  95
  96 #else
  97
  98 // Hashes Classes, for all known classes. Custom prototype.
  99 OBJC_EXPORT NXHashTable * _Nullable _objc_debug_class_hash
 100     __OSX_AVAILABLE(10.2)
 101     __IOS_UNAVAILABLE __TVOS_UNAVAILABLE
 102     __WATCHOS_UNAVAILABLE __BRIDGEOS_UNAVAILABLE;
 103
 104 #endif
 105
 106
 107 /***********************************************************************
 108 * Non-pointer isa
 109 **********************************************************************/
 110
 111 #if __OBJC2__
 112
 113 // Extract isa pointer from an isa field.
 114 // (Class)(isa & mask) == class pointer
 115 OBJC_EXPORT const uintptr_t objc_debug_isa_class_mask
 116     OBJC_AVAILABLE(10.10, 7.0, 9.0, 1.0, 2.0);
 117
 118 // Extract magic cookie from an isa field.
 119 // (isa & magic_mask) == magic_value
 120 OBJC_EXPORT const uintptr_t objc_debug_isa_magic_mask
 121     OBJC_AVAILABLE(10.10, 7.0, 9.0, 1.0, 2.0);
 122 OBJC_EXPORT const uintptr_t objc_debug_isa_magic_value
 123     OBJC_AVAILABLE(10.10, 7.0, 9.0, 1.0, 2.0);
 124
 125 // Use indexed ISAs for targets which store index of the class in the ISA.
 126 // This index can be used to index the array of classes.
 127 OBJC_EXPORT const uintptr_t objc_debug_indexed_isa_magic_mask;
 128 OBJC_EXPORT const uintptr_t objc_debug_indexed_isa_magic_value;
 129
 130 // Then these are used to extract the index from the ISA.
 131 OBJC_EXPORT const uintptr_t objc_debug_indexed_isa_index_mask;
 132 OBJC_EXPORT const uintptr_t objc_debug_indexed_isa_index_shift;
 133
 134 // And then we can use that index to get the class from this array.  Note
 135 // the size is provided so that clients can ensure the index they get is in
 136 // bounds and not read off the end of the array.
 137 OBJC_EXPORT Class _Nullable objc_indexed_classes[];
 138
 139 // When we don't have enough bits to store a class*, we can instead store an
 140 // index in to this array.  Classes are added here when they are realized.
 141 // Note, an index of 0 is illegal.
 142 OBJC_EXPORT uintptr_t objc_indexed_classes_count;
 143
 144 // Absolute symbols for some of the above values are in objc-abi.h.
 145
 146 #endif
 147
 148
 149 /***********************************************************************
 150 * Class structure decoding
 151 **********************************************************************/
 152 #if __OBJC2__
 153
 154 // Mask for the pointer from class struct to class rw data.
 155 // Other bits may be used for flags.
 156 // Use 0x00007ffffffffff8UL or 0xfffffffcUL when this variable is unavailable.
 157 OBJC_EXPORT const uintptr_t objc_debug_class_rw_data_mask
 158     OBJC_AVAILABLE(10.13, 11.0, 11.0, 4.0, 2.0);
 159
 160 // The ABI version for the internal runtime representations
 161 // lldb, CoreSymbolication and debugging tools need to know
 162 OBJC_EXTERN const uint32_t objc_class_abi_version
 163         OBJC_AVAILABLE(10.15, 13.0, 13.0, 6.0, 5.0);
 164
 165 // the maximum ABI version in existence for now
 166 #define OBJC_CLASS_ABI_VERSION_MAX 1
 167
 168 // Used when objc_class_abi_version is absent or 0
 169 struct class_rw_v0_t {
 170     uint32_t  flags;
 171     uint32_t  version;
 172     uintptr_t ro;                   // class_ro_t
 173     uintptr_t methods;              // method_array_t
 174     uintptr_t properties;           // property_array_t
 175     uintptr_t protocols;            // protocol_array_t
 176     Class _Nullable firstSubclass;
 177     Class _Nullable nextSiblingClass;
 178     char *_Nullable demangledName;
 179
 180     // uint32_t index;              // only when indexed-isa is used
 181 };
 182
 183 // Used when objc_class_abi_version is 1
 184 struct class_rw_v1_t {
 185     uint32_t  flags;
 186     uint16_t  witness;
 187     uint16_t  index;                // only when indexed-isa is used
 188     uintptr_t ro_or_rw_ext;         // tagged union based on the low bit:
 189                                     // 0: class_ro_t  1: class_rw_ext_t
 190     Class _Nullable firstSubclass;
 191     Class _Nullable nextSiblingClass;
 192 };
 193
 194 struct class_rw_ext_v1_t {
 195     uintptr_t ro;                   // class_ro_t
 196     uintptr_t methods;              // method_array_t
 197     uintptr_t properties;           // property_array_t
 198     uintptr_t protocols;            // protocol_array_t
 199     char *_Nullable demangledName;
 200     uint32_t version;
 201 };
 202
 203 #endif
 204
 205
 206 /***********************************************************************
 207 * Tagged pointer decoding
 208 **********************************************************************/
 209 #if __OBJC2__
 210
 211 // Basic tagged pointers (7 classes, 60-bit payload).
 212
 213 // if (obj & mask) obj is a tagged pointer object
 214 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_mask
 215     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0, 2.0);
 216
 217 // tagged pointers are obfuscated by XORing with a random value
 218 // decoded_obj = (obj ^ obfuscator)
 219 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_obfuscator
 220     OBJC_AVAILABLE(10.14, 12.0, 12.0, 5.0, 3.0);
 221
 222 #if OBJC_SPLIT_TAGGED_POINTERS
 223 OBJC_EXPORT uint8_t objc_debug_tag60_permutations[8];
 224 #endif
 225
 226
 227 // tag_slot = (obj >> slot_shift) & slot_mask
 228 OBJC_EXPORT unsigned int objc_debug_taggedpointer_slot_shift
 229     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0, 2.0);
 230 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_slot_mask
 231     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0, 2.0);
 232
 233 // class = classes[tag_slot]
 234 OBJC_EXPORT Class _Nullable objc_debug_taggedpointer_classes[]
 235     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0, 2.0);
 236
 237 // payload = (decoded_obj << payload_lshift) >> payload_rshift
 238 // Payload signedness is determined by the signedness of the right-shift.
 239 OBJC_EXPORT unsigned int objc_debug_taggedpointer_payload_lshift
 240     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0, 2.0);
 241 OBJC_EXPORT unsigned int objc_debug_taggedpointer_payload_rshift
 242     OBJC_AVAILABLE(10.9, 7.0, 9.0, 1.0, 2.0);
 243
 244
 245 // Extended tagged pointers (255 classes, 52-bit payload).
 246
 247 // If you interrogate an extended tagged pointer using the basic
 248 // tagged pointer scheme alone, it will appear to have an isa
 249 // that is either nil or class __NSUnrecognizedTaggedPointer.
 250
 251 // if (ext_mask != 0  &&  (decoded_obj & ext_mask) == ext_mask)
 252 //   obj is a ext tagged pointer object
 253 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_ext_mask
 254     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0, 2.0);
 255
 256 // ext_tag_slot = (obj >> ext_slot_shift) & ext_slot_mask
 257 OBJC_EXPORT unsigned int objc_debug_taggedpointer_ext_slot_shift
 258     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0, 2.0);
 259 OBJC_EXPORT uintptr_t objc_debug_taggedpointer_ext_slot_mask
 260     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0, 2.0);
 261
 262 // class = ext_classes[ext_tag_slot]
 263 OBJC_EXPORT Class _Nullable objc_debug_taggedpointer_ext_classes[]
 264     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0, 2.0);
 265
 266 // payload = (decoded_obj << ext_payload_lshift) >> ext_payload_rshift
 267 // Payload signedness is determined by the signedness of the right-shift.
 268 OBJC_EXPORT unsigned int objc_debug_taggedpointer_ext_payload_lshift
 269     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0, 2.0);
 270 OBJC_EXPORT unsigned int objc_debug_taggedpointer_ext_payload_rshift
 271     OBJC_AVAILABLE(10.12, 10.0, 10.0, 3.0, 2.0);
 272
 273 OBJC_EXPORT uintptr_t objc_debug_constant_cfstring_tag_bits
 274     OBJC_AVAILABLE(10.16, 14.0, 14.0, 7.0, 6.0);
 275
 276 #endif
 277
 278
 279 /***********************************************************************
 280 * Swift marker bits
 281 **********************************************************************/
 282 #if __OBJC2__
 283 OBJC_EXPORT const uintptr_t objc_debug_swift_stable_abi_bit
 284 OBJC_AVAILABLE(10.14.4, 12.2, 12.2, 5.2, 3.2);
 285 #endif
 286
 287
 288
 289 /***********************************************************************
 290 * AutoreleasePoolPage
 291 **********************************************************************/
 292 OBJC_EXTERN const uint32_t objc_debug_autoreleasepoolpage_magic_offset  OBJC_AVAILABLE(10.15, 13.0, 13.0, 6.0, 5.0);
 293 OBJC_EXTERN const uint32_t objc_debug_autoreleasepoolpage_next_offset   OBJC_AVAILABLE(10.15, 13.0, 13.0, 6.0, 5.0);
 294 OBJC_EXTERN const uint32_t objc_debug_autoreleasepoolpage_thread_offset OBJC_AVAILABLE(10.15, 13.0, 13.0, 6.0, 5.0);
 295 OBJC_EXTERN const uint32_t objc_debug_autoreleasepoolpage_parent_offset OBJC_AVAILABLE(10.15, 13.0, 13.0, 6.0, 5.0);
 296 OBJC_EXTERN const uint32_t objc_debug_autoreleasepoolpage_child_offset  OBJC_AVAILABLE(10.15, 13.0, 13.0, 6.0, 5.0);
 297 OBJC_EXTERN const uint32_t objc_debug_autoreleasepoolpage_depth_offset  OBJC_AVAILABLE(10.15, 13.0, 13.0, 6.0, 5.0);
 298 OBJC_EXTERN const uint32_t objc_debug_autoreleasepoolpage_hiwat_offset  OBJC_AVAILABLE(10.15, 13.0, 13.0, 6.0, 5.0);
 299 #if __OBJC2__
 300 OBJC_EXTERN const uintptr_t objc_debug_autoreleasepoolpage_ptr_mask     OBJC_AVAILABLE(10.16, 14.0, 14.0, 7.0, 6.0);
 301 #endif
 302
 303 __END_DECLS
 304
 305 // APPLE_API_PRIVATE
 306 #endif
 307
 308 // _OBJC_GDB_H
 309 #endif