private/platform/introspection_private.h

   1 #ifndef __PLATFORM_INTROSPECTION_H__
   2 #define __PLATFORM_INTROSPECTION_H__
   3
   4 #include <mach/mach_types.h>
   5 #include <mach/thread_info.h>
   6 #include <mach/thread_status.h>
   7
   8 #include <sys/types.h>
   9
  10 #include <stdbool.h>
  11
  12 typedef struct platform_task_s *platform_task_t;
  13 typedef struct platform_thread_s *platform_thread_t;
  14
  15 /*!
  16  * @typedef platform_thread_id_t
  17  *
  18  * @discussion
  19  * The type of the 64-bit system-wide unique thread ID.
  20  */
  21 typedef uint64_t platform_thread_id_t;
  22
  23 /*! @functiongroup Tasks */
  24
  25 /*!
  26  * @function platform_task_attach
  27  *
  28  * @discussion
  29  * Attach to a process (specified by its mach task port) for debugging. This
  30  * function creates a new task handle which must be disposed by a call to
  31  * platform_task_detach().
  32  *
  33  * @param task
  34  * On output, a newly created task handle.
  35  *
  36  * @param target
  37  * The mach task port of the target process.
  38  *
  39  * @return
  40  * KERN_SUCCESS if the process was successfully attached, otherwise a mach
  41  * error code.
  42  */
  43 kern_return_t
  44 platform_task_attach(platform_task_t *task, task_t target);
  45
  46 /*!
  47  * @function platform_task_detach
  48  *
  49  * @discussion
  50  * Detaches from the target task and deallocates all memory associated with
  51  * the task handle.
  52  *
  53  * @param task
  54  * The task handle to detach.
  55  *
  56  * @return
  57  * KERN_SUCCESS if the process was successfully detached, otherwise a mach
  58  * error code.
  59  */
  60 kern_return_t
  61 platform_task_detach(platform_task_t task);
  62
  63 /*!
  64  * @function platform_task_is_64_bit
  65  *
  66  * @discussion
  67  * Returns true if the target task is LP64.
  68  *
  69  * @param task
  70  * A handle to the target task.
  71  *
  72  * @return
  73  * true if the target task is LP64, otherwise false.
  74  */
  75 bool
  76 platform_task_is_64_bit(platform_task_t task);
  77
  78 /*!
  79  * @function platform_task_suspend_threads
  80  *
  81  * @discussion
  82  * Suspends all the threads in the target task. This differs from task_suspend
  83  * in that the task itself is not suspended, only the individual threads. While
  84  * this suspension is in effect, any newly created threads will be created in
  85  * a suspended state. The debuger may resume an individual thread for execution
  86  * using platform_thread_resume() or evaluate an expression in the context of
  87  * the task or a specific thread using platform_task_perform() and
  88  * platform_thread_perform(), respectively. All threads in the task may be
  89  * resumed with platform_task_resume_threads().
  90  *
  91  * @param task
  92  * A handle to the target task.
  93  *
  94  * @return
  95  * KERN_SUCCESS if the threads were successfully suspended, otherwise a mach
  96  * error code.
  97  */
  98 kern_return_t
  99 platform_task_suspend_threads(platform_task_t task);
 100
 101 /*!
 102  * @function platform_task_resume_threads
 103  *
 104  * @discussion
 105  * Resumes the threads in the target task. See platform_task_suspend_threads().
 106  *
 107  * @param task
 108  * A handle to the target task.
 109  */
 110 kern_return_t
 111 platform_task_resume_threads(platform_task_t task);
 112
 113 /*!
 114  * @function platform_task_perform
 115  *
 116  * @discussion
 117  * Performs the specified function on a newly created thread in the target task.
 118  * This newly created thread will execute even if the threads in the task are
 119  * suspended as the result of a call to platform_task_suspend_threads().
 120  *
 121  * The function and context addresses are in the virtual address space of the
 122  * target task. It is the responsiblity of the debugger to have previously
 123  * mapped executable text and data at these addresses in the target task.
 124  *
 125  * @param task
 126  * A handle to the target task.
 127  *
 128  * @param func_addr
 129  * The address (in the virtual address space of the target task) of the
 130  * function to perform. The function should be of type (void (*)(void *))
 131  * and will be passed the value of the data_addr parameter.
 132  *
 133  * @param data_addr
 134  * The address (in the virtual address space of the target task) of the
 135  * data to pass as a parameter to the function to perform.
 136  *
 137  * @return
 138  * KERN_SUCCESS if the function was successfully performed, otherwise a mach
 139  * error code.
 140  */
 141 kern_return_t
 142 platform_task_perform(platform_task_t task,
 143                       mach_vm_address_t func_addr,
 144                       mach_vm_address_t data_addr);
 145
 146 /*!
 147  * @function platform_task_update_threads
 148  *
 149  * @discussion
 150  * Updates an internal representation of all threads in the target task. The
 151  * list of threads may then be iterated using platform_task_copy_next_thread().
 152  *
 153  * Calling this function resets any iteration currently in progress and a
 154  * subsequent call to platform_task_copy_next_thread() will return the first
 155  * thread in the list.
 156  *
 157  * @param task
 158  * A handle to the target task.
 159  *
 160  * @return
 161  * KERN_SUCCESS if the threads were successfully updated, otherwise a mach
 162  * error code.
 163  */
 164 kern_return_t
 165 platform_task_update_threads(platform_task_t task);
 166
 167 /*!
 168  * @function platform_task_copy_next_thread
 169  *
 170  * @discussion
 171  * Iterates the list of threads in the task. Returns a copied thread handle
 172  * which must subsequently be released using platform_thread_release().
 173  *
 174  * The platform_task_update_threads() function must be called before this
 175  * function will return any thread handles. A NULL pointer is returned to
 176  * signify the end of the list
 177  *
 178  * @param task
 179  * A handle to the target task.
 180  *
 181  * @return
 182  * A thread handle which must be released using platform_thread_release(),
 183  * or NULL, signifying the end of the list.
 184  */
 185 platform_thread_t
 186 platform_task_copy_next_thread(platform_task_t task);
 187
 188 /*! @functiongroup Threads */
 189
 190 /*!
 191  * @function platform_thread_get_unique_id
 192  *
 193  * @discussion
 194  * Returns the 64-bit system-wide unique ID of the target thread.
 195  *
 196  * @param thread
 197  * A handle to the target thread.
 198  *
 199  * @return
 200  * The unique ID of the thread.
 201  */
 202 platform_thread_id_t
 203 platform_thread_get_unique_id(platform_thread_t thread);
 204
 205 /*!
 206  * @function platform_thread_release
 207  *
 208  * @discussion
 209  * Releases a thread handle obtained by platform_task_copy_next_thread().
 210  *
 211  * @param thread
 212  * The thread handle to release.
 213  */
 214 void
 215 platform_thread_release(platform_thread_t thread);
 216
 217 /*!
 218  * @function platform_thread_abort_safely
 219  *
 220  * @discussion
 221  * Similar to thread_abort_safely().
 222  *
 223  * @param thread
 224  * A handle to the thread to signal.
 225  *
 226  * @return
 227  * KERN_SUCCESS if the thread was successfully signaled, otherwise a mach
 228  * error code.
 229  */
 230 kern_return_t
 231 platform_thread_abort_safely(platform_thread_t thread);
 232
 233 /*!
 234  * @function platform_thread_suspend
 235  *
 236  * @discussion
 237  * Suspends execution of a thread similar to thread_suspend(). See also
 238  * platform_task_suspend_threads().
 239  *
 240  * @param thread
 241  * A handle to the thread to suspend.
 242  *
 243  * @return
 244  * KERN_SUCCESS if the thread was successfully suspended, otherwise a mach
 245  * error code.
 246  */
 247 kern_return_t
 248 platform_thread_suspend(platform_thread_t thread);
 249
 250 /*!
 251  * @function platform_thread_resume
 252  *
 253  * @discussion
 254  * Suspends execution of a thread similar to thread_suspend(). See also
 255  * platform_task_suspend_threads() and platform_task_resume_threads().
 256  *
 257  * @param thread
 258  * A handle to the thread to resume.
 259  *
 260  * @return
 261  * KERN_SUCCESS if the thread was successfully resumed, otherwise a mach
 262  * error code.
 263 */
 264 kern_return_t
 265 platform_thread_resume(platform_thread_t thread);
 266
 267 /*!
 268  * @function platform_thread_info
 269  *
 270  * @discussion
 271  * Similar to thread_info. Supported flavor structures:
 272  * - THREAD_BASIC_INFO: struct thread_basic_info
 273  * - THREAD_IDENTIFIER_INFO: struct thread_identifier_info
 274  *
 275  * @param thread
 276  * A handle to the target thread.
 277  *
 278  * @param flavor
 279  * The desired thread info structure.
 280  *
 281  * @param info
 282  * A pointer to storage where the thread info structure should be written.
 283  *
 284  * @param size
 285  * On input, the size in bytes of the storage where the thread info structure
 286  * is to be written. On output, the size of the thread info structure in bytes.
 287  *
 288  * @return
 289  * KERN_SUCCESS if the function was successfully performed, otherwise a mach
 290  * error code.
 291  */
 292 kern_return_t
 293 platform_thread_info(platform_thread_t thread,
 294                        thread_flavor_t flavor,
 295                        void *info,
 296                        size_t *size);
 297
 298 /*!
 299  * @function platform_thread_get_state
 300  *
 301  * @discussion
 302  * Similar to thread_get_state. Supported flavor structures:
 303  * - x86_THREAD_STATE32: struct ...
 304  * - x86_FLOAT_STATE32: struct ...
 305  * - x86_EXCEPTION_STATE32: struct ...
 306  * - x86_DEBUG_STATE32: struct ...
 307  * - x86_AVX_STATE32: struct ...
 308  * - x86_THREAD_STATE64: struct ...
 309  * - x86_FLOAT_STATE64: struct ...
 310  * - x86_EXCEPTION_STATE64: struct ...
 311  * - x86_DEBUG_STATE64: struct ...
 312  * - x86_AVX_STATE64: struct ...
 313  * - ARM_THREAD_STATE32: struct ...
 314  * - ARM_FLOAT_STATE32: struct ...
 315  * - ARM_EXCEPTION_STATE32: struct ...
 316  * - ARM_DEBUG_STATE32: struct ...
 317  * - ARM_THREAD_STATE64: struct ...
 318  * - ARM_FLOAT_STATE64: struct ...
 319  * - ARM_EXCEPTION_STATE64: struct ...
 320  * - ARM_DEBUG_STATE64: struct ...
 321  * - ...
 322  *
 323  * @param thread
 324  * A handle to the target thread.
 325  *
 326  * @param flavor
 327  * The desired thread state structure.
 328  *
 329  * @param state
 330  * A pointer to storage where the thread state structure should be written.
 331  *
 332  * @param size
 333  * On input, the size in bytes of the storage where the thread state structure
 334  * is to be written. On output, the size of the thread state structure in bytes.
 335  *
 336  * @return
 337  * KERN_SUCCESS if the function was successfully performed, otherwise a mach
 338  * error code.
 339  */
 340 kern_return_t
 341 platform_thread_get_state(platform_thread_t thread,
 342                           thread_state_flavor_t flavor,
 343                           void *state,
 344                           size_t *size);
 345
 346 /*!
 347  * @function platform_thread_set_state
 348  *
 349  * @discussion
 350  * Similar to thread_set_state. Supported flavor structures:
 351  * - x86_THREAD_STATE32: struct ...
 352  * - x86_FLOAT_STATE32: struct ...
 353  * - x86_EXCEPTION_STATE32: struct ...
 354  * - x86_DEBUG_STATE32: struct ...
 355  * - x86_AVX_STATE32: struct ...
 356  * - x86_THREAD_STATE64: struct ...
 357  * - x86_FLOAT_STATE64: struct ...
 358  * - x86_EXCEPTION_STATE64: struct ...
 359  * - x86_DEBUG_STATE64: struct ...
 360  * - x86_AVX_STATE64: struct ...
 361  * - ARM_THREAD_STATE32: struct ...
 362  * - ARM_FLOAT_STATE32: struct ...
 363  * - ARM_EXCEPTION_STATE32: struct ...
 364  * - ARM_DEBUG_STATE32: struct ...
 365  * - ARM_THREAD_STATE64: struct ...
 366  * - ARM_FLOAT_STATE64: struct ...
 367  * - ARM_EXCEPTION_STATE64: struct ...
 368  * - ARM_DEBUG_STATE64: struct ...
 369  * - ...
 370  *
 371  * @param thread
 372  * A handle to the target thread.
 373  *
 374  * @param flavor
 375  * The desired thread state structure.
 376  *
 377  * @param state
 378  * A pointer to storage where the thread state structure should be written.
 379  *
 380  * @param size
 381  * The size of the thread state structure in bytes.
 382  *
 383  * @return
 384  * KERN_SUCCESS if the function was successfully performed, otherwise a mach
 385  * error code.
 386  */
 387 kern_return_t
 388 platform_thread_set_state(platform_thread_t thread,
 389                           thread_state_flavor_t flavor,
 390                           const void *state,
 391                           size_t size);
 392
 393 /*!
 394  * @function platform_thread_perform
 395  *
 396  * @discussion
 397  * Performs the specified function within the context of the specified thread
 398  * in the target task. The function will execute in the style of an
 399  * asynchronous signal handler even if the thread is suspended as the result
 400  * of a call to platform_task_suspend_threads() or platform_thread_suspend().
 401  * The original state of the thread will be restored when the function returns.
 402  *
 403  * The function and context addresses are in the virtual address space of the
 404  * target task. It is the responsiblity of the debugger to have previously
 405  * mapped executable text and data at these addresses in the target task.
 406  *
 407  * See also platform_task_perform().
 408  *
 409  * @param thread
 410  * A handle to the target thread.
 411  *
 412  * @param func_addr
 413  * The address (in the virtual address space of the target task) of the
 414  * function to perform. The function should be of type (void (*)(void *))
 415  * and will be passed the value of the data_addr parameter.
 416  *
 417  * @param data_addr
 418  * The address (in the virtual address space of the target task) of the
 419  * data to pass as a parameter to the function to perform.
 420  *
 421  * @return
 422  * KERN_SUCCESS if the function was successfully performed, otherwise a mach
 423  * error code.
 424  */
 425 kern_return_t
 426 platform_thread_perform(platform_thread_t thread,
 427                         mach_vm_address_t func_addr,
 428                         mach_vm_address_t data_addr);
 429
 430 /*!
 431  * @function platform_thread_get_pthread
 432  *
 433  * @discussion
 434  * Returns a pointer to mapped memory which represents the pthread_t of the
 435  * target process. Any embedded pointers will need to be mapped into the current
 436  * process space on a case-by-case basis.
 437  *
 438  * @param thread
 439  * A handle to the target thread.
 440  *
 441  * @return
 442  * A valid pointer.
 443  */
 444 const void *
 445 platform_thread_get_pthread(platform_thread_t thread);
 446
 447 #endif // __PLATFORM_INTROSPECTION_H__