Documentation/utrace.txt

   1 DRAFT DRAFT DRAFT       WORK IN PROGRESS        DRAFT DRAFT DRAFT
   2
   3 This is work in progress and likely to change.
   4
   5
   6         Roland McGrath <roland@redhat.com>
   7
   8 ---
   9
  10                 User Debugging Data & Event Rendezvous
  11                 ---- --------- ---- - ----- ----------
  12
  13 See linux/utrace.h for all the declarations used here.
  14 See also linux/tracehook.h for the utrace_regset declarations.
  15
  16 The UTRACE is infrastructure code for tracing and controlling user
  17 threads.  This is the foundation for writing tracing engines, which
  18 can be loadable kernel modules.  The UTRACE interfaces provide three
  19 basic facilities:
  20
  21 * Thread event reporting
  22
  23   Tracing engines can request callbacks for events of interest in
  24   the thread: signals, system calls, exit, exec, clone, etc.
  25
  26 * Core thread control
  27
  28   Tracing engines can prevent a thread from running (keeping it in
  29   TASK_TRACED state), or make it single-step or block-step (when
  30   hardware supports it).  Engines can cause a thread to abort system
  31   calls, they change the behaviors of signals, and they can inject
  32   signal-style actions at will.
  33
  34 * Thread machine state access
  35
  36   Tracing engines can read and write a thread's registers and
  37   similar per-thread CPU state.
  38
  39
  40         Tracing engines
  41         ------- -------
  42
  43 The basic actors in UTRACE are the thread and the tracing engine.
  44 A tracing engine is some body of code that calls into the utrace_*
  45 interfaces, represented by a struct utrace_engine_ops.  (Usually it's a
  46 kernel module, though the legacy ptrace support is a tracing engine
  47 that is not in a kernel module.)  The UTRACE interface operates on
  48 individual threads (struct task_struct).  If an engine wants to
  49 treat several threads as a group, that is up to its higher-level
  50 code.  Using the UTRACE starts out by attaching an engine to a thread.
  51
  52         struct utrace_attached_engine *
  53         utrace_attach(struct task_struct *target, int flags,
  54                       const struct utrace_engine_ops *ops, unsigned long data);
  55
  56 Calling utrace_attach is what sets up a tracing engine to trace a
  57 thread.  Use UTRACE_ATTACH_CREATE in flags, and pass your engine's ops.
  58 Check the return value with IS_ERR.  If successful, it returns a
  59 struct pointer that is the handle used in all other utrace_* calls.
  60 The data argument is stored in the utrace_attached_engine structure,
  61 for your code to use however it wants.
  62
  63         int utrace_detach(struct task_struct *target,
  64                           struct utrace_attached_engine *engine);
  65
  66 The utrace_detach call removes an engine from a thread.
  67 No more callbacks will be made after this returns success.
  68
  69
  70 An attached engine does nothing by default.
  71 An engine makes something happen by setting its flags.
  72
  73         int utrace_set_flags(struct task_struct *target,
  74                              struct utrace_attached_engine *engine,
  75                              unsigned long flags);
  76
  77 The synchronization issues related to these two calls
  78 are discussed further below in "Teardown Races".
  79
  80
  81         Action Flags
  82         ------ -----
  83
  84 There are two kinds of flags that an attached engine can set: event
  85 flags, and action flags.  Event flags register interest in particular
  86 events; when an event happens and an engine has the right event flag
  87 set, it gets a callback.  Action flags change the normal behavior of
  88 the thread.  The action flags available are:
  89
  90         UTRACE_ACTION_QUIESCE
  91
  92                 The thread will stay quiescent (see below).  As long as
  93                 any engine asserts the QUIESCE action flag, the thread
  94                 will not resume running in user mode.  (Usually it will
  95                 be in TASK_TRACED state.)  Nothing will wake the thread
  96                 up except for SIGKILL (and implicit SIGKILLs such as a
  97                 core dump in another thread sharing the same address
  98                 space, or a group exit, fatal signal, or exec in another
  99                 thread in the same thread group).
 100
 101         UTRACE_ACTION_SINGLESTEP
 102
 103                 When the thread runs, it will run one instruction and
 104                 then trap.  (Exiting a system call or entering a signal
 105                 handler is considered "an instruction" for this.)  This
 106                 is available on most machines.  This can be used only if
 107                 ARCH_HAS_SINGLE_STEP is #define'd by <asm/tracehook.h>
 108                 and evaluates to nonzero.
 109
 110         UTRACE_ACTION_BLOCKSTEP
 111
 112                 When the thread runs, it will run until the next branch
 113                 taken, and then trap.  (Exiting a system call or
 114                 entering a signal handler is considered taking a branch
 115                 for this.)  When the SINGLESTEP flag is set, BLOCKSTEP
 116                 has no effect.  This is only available on some machines.
 117                 This can be used only if ARCH_HAS_BLOCK_STEP is
 118                 #define'd by <asm/tracehook.h> and evaluates to nonzero.
 119
 120         UTRACE_ACTION_NOREAP
 121
 122                 When the thread exits or stops for job control, its
 123                 parent process will not receive a SIGCHLD and the
 124                 parent's wait calls will not wake up or report the child
 125                 as dead.  Even a self-reaping thread will remain a
 126                 zombie.  Note that this cannot prevent the reaping done
 127                 when an exec is done by another thread in the same
 128                 thread group; in that event, a REAP event (and callback
 129                 if requested) will happen regardless of this flag.
 130                 A well-behaved tracing engine does not want to interfere
 131                 with the parent's normal notifications.  This is
 132                 provided mainly for the ptrace compatibility code to
 133                 implement the traditional behavior.
 134
 135 Event flags are specified using the macro UTRACE_EVENT(TYPE).
 136 Each event type is associated with a report_* callback in struct
 137 utrace_engine_ops.  A tracing engine can leave unused callbacks NULL.
 138 The only callbacks required are those used by the event flags it sets.
 139
 140 Many engines can be attached to each thread.  When a thread has an
 141 event, each engine gets a report_* callback if it has set the event flag
 142 for that event type.  Engines are called in the order they attached.
 143
 144 Each callback takes arguments giving the details of the particular
 145 event.  The first two arguments two every callback are the struct
 146 utrace_attached_engine and struct task_struct pointers for the engine
 147 and the thread producing the event.  Usually this will be the current
 148 thread that is running the callback functions.
 149
 150 The return value of report_* callbacks is a bitmask.  Some bits are
 151 common to all callbacks, and some are particular to that callback and
 152 event type.  The value zero (UTRACE_ACTION_RESUME) always means the
 153 simplest thing: do what would have happened with no tracing engine here.
 154 These are the flags that can be set in any report_* return value:
 155
 156         UTRACE_ACTION_NEWSTATE
 157
 158                 Update the action state flags, described above.  Those
 159                 bits from the return value (UTRACE_ACTION_STATE_MASK)
 160                 replace those bits in the engine's flags.  This has the
 161                 same effect as calling utrace_set_flags, but is a more
 162                 efficient short-cut.  To change the event flags, you must
 163                 call utrace_set_flags.
 164
 165         UTRACE_ACTION_DETACH
 166
 167                 Detach this engine.  This has the effect of calling
 168                 utrace_detach, but is a more efficient short-cut.
 169
 170         UTRACE_ACTION_HIDE
 171
 172                 Hide this event from other tracing engines.  This is
 173                 only appropriate to do when the event was induced by
 174                 some action of this engine, such as a breakpoint trap.
 175                 Some events cannot be hidden, since every engine has to
 176                 know about them: exit, death, reap.
 177
 178 The return value bits in UTRACE_ACTION_OP_MASK indicate a change to the
 179 normal behavior of the event taking place.  If zero, the thread does
 180 whatever that event normally means.  For report_signal, other values
 181 control the disposition of the signal.
 182
 183
 184         Quiescence
 185         ----------
 186
 187 To control another thread and access its state, it must be "quiescent".
 188 This means that it is stopped and won't start running again while we access
 189 it.  A quiescent thread is stopped in a place close to user mode, where the
 190 user state can be accessed safely; either it's about to return to user
 191 mode, or it's just entered the kernel from user mode, or it has already
 192 finished exiting (EXIT_ZOMBIE).  Setting the UTRACE_ACTION_QUIESCE action
 193 flag will force the attached thread to become quiescent soon.  After
 194 setting the flag, an engine must wait for an event callback when the thread
 195 becomes quiescent.  The thread may be running on another CPU, or may be in
 196 an uninterruptible wait.  When it is ready to be examined, it will make
 197 callbacks to engines that set the UTRACE_EVENT(QUIESCE) event flag.
 198
 199 As long as some engine has UTRACE_ACTION_QUIESCE set, then the thread will
 200 remain stopped.  SIGKILL will wake it up, but it will not run user code.
 201 When the flag is cleared via utrace_set_flags or a callback return value,
 202 the thread starts running again.  (See also "Teardown Races", below.)
 203
 204 During the event callbacks (report_*), the thread in question makes the
 205 callback from a safe place.  It is not quiescent, but it can safely access
 206 its own state.  Callbacks can access thread state directly without setting
 207 the QUIESCE action flag.  If a callback does want to prevent the thread
 208 from resuming normal execution, it *must* use the QUIESCE action state
 209 rather than simply blocking; see "Core Events & Callbacks", below.
 210
 211
 212         Thread control
 213         ------ -------
 214
 215 These calls must be made on a quiescent thread (or the current thread):
 216
 217         int utrace_inject_signal(struct task_struct *target,
 218                                  struct utrace_attached_engine *engine,
 219                                  u32 action, siginfo_t *info,
 220                                  const struct k_sigaction *ka);
 221
 222 Cause a specified signal delivery in the target thread.  This is not
 223 like kill, which generates a signal to be dequeued and delivered later.
 224 Injection directs the thread to deliver a signal now, before it next
 225 resumes in user mode or dequeues any other pending signal.  It's as if
 226 the tracing engine intercepted a signal event and its report_signal
 227 callback returned the action argument as its value (see below).  The
 228 info and ka arguments serve the same purposes as their counterparts in
 229 a report_signal callback.
 230
 231         const struct utrace_regset *
 232         utrace_regset(struct task_struct *target,
 233                       struct utrace_attached_engine *engine,
 234                       const struct utrace_regset_view *view,
 235                       int which);
 236
 237 Get access to machine state for the thread.  The struct utrace_regset_view
 238 indicates a view of machine state, corresponding to a user mode
 239 architecture personality (such as 32-bit or 64-bit versions of a machine).
 240 The which argument selects one of the register sets available in that view.
 241 The utrace_regset call must be made before accessing any machine state,
 242 each time the thread has been running and has then become quiescent.
 243 It ensures that the thread's state is ready to be accessed, and returns
 244 the struct utrace_regset giving its accessor functions.
 245
 246 XXX needs front ends for argument checks, export utrace_native_view
 247
 248
 249         Core Events & Callbacks
 250         ---- ------ - ---------
 251
 252 Event reporting callbacks have details particular to the event type, but
 253 are all called in similar environments and have the same constraints.
 254 Callbacks are made from safe spots, where no locks are held, no special
 255 resources are pinned, and the user-mode state of the thread is accessible.
 256 So, callback code has a pretty free hand.  But to be a good citizen,
 257 callback code should never block for long periods.  It is fine to block in
 258 kmalloc and the like, but never wait for i/o or for user mode to do
 259 something.  If you need the thread to wait, set UTRACE_ACTION_QUIESCE and
 260 return from the callback quickly.  When your i/o finishes or whatever, you
 261 can use utrace_set_flags to resume the thread.
 262
 263 Well-behaved callbacks are important to maintain two essential properties
 264 of the interface.  The first of these is that unrelated tracing engines not
 265 interfere with each other.  If your engine's event callback does not return
 266 quickly, then another engine won't get the event notification in a timely
 267 manner.  The second important property is that tracing be as noninvasive as
 268 possible to the normal operation of the system overall and of the traced
 269 thread in particular.  That is, attached tracing engines should not perturb
 270 a thread's behavior, except to the extent that changing its user-visible
 271 state is explicitly what you want to do.  (Obviously some perturbation is
 272 unavoidable, primarily timing changes, ranging from small delays due to the
 273 overhead of tracing, to arbitrary pauses in user code execution when a user
 274 stops a thread with a debugger for examination.  When doing asynchronous
 275 utrace_attach to a thread doing a system call, more troublesome side
 276 effects are possible.)  Even when you explicitly want the pertrubation of
 277 making the traced thread block, just blocking directly in your callback has
 278 more unwanted effects.  For example, the CLONE event callbacks are called
 279 when the new child thread has been created but not yet started running; the
 280 child can never be scheduled until the CLONE tracing callbacks return.
 281 (This allows engines tracing the parent to attach to the child.)  If a
 282 CLONE event callback blocks the parent thread, it also prevents the child
 283 thread from running (even to process a SIGKILL).  If what you want is to
 284 make both the parent and child block, then use utrace_attach on the child
 285 and then set the QUIESCE action state flag on both threads.  A more crucial
 286 problem with blocking in callbacks is that it can prevent SIGKILL from
 287 working.  A thread that is blocking due to UTRACE_ACTION_QUIESCE will still
 288 wake up and die immediately when sent a SIGKILL, as all threads should.
 289 Relying on the utrace infrastructure rather than on private synchronization
 290 calls in event callbacks is an important way to help keep tracing robustly
 291 noninvasive.
 292
 293
 294 EVENT(REAP)             Dead thread has been reaped
 295 Callback:
 296         void (*report_reap)(struct utrace_attached_engine *engine,
 297                             struct task_struct *tsk);
 298
 299 This means the parent called wait, or else this was a detached thread or
 300 a process whose parent ignores SIGCHLD.  This cannot happen while the
 301 UTRACE_ACTION_NOREAP flag is set.  This is the only callback you are
 302 guaranteed to get (if you set the flag; but see "Teardown Races", below).
 303
 304 Unlike other callbacks, this can be called from the parent's context
 305 rather than from the traced thread itself--it must not delay the parent by
 306 blocking.  This callback is different from all others, it returns void.
 307 Once you get this callback, your engine is automatically detached and you
 308 cannot access this thread or use this struct utrace_attached_engine handle
 309 any longer.  This is the place to clean up your data structures and
 310 synchronize with your code that might try to make utrace_* calls using this
 311 engine data structure.  The struct is still valid during this callback,
 312 but will be freed soon after it returns (via RCU).
 313
 314 In all other callbacks, the return value is as described above.
 315 The common UTRACE_ACTION_* flags in the return value are always observed.
 316 Unless otherwise specified below, other bits in the return value are ignored.
 317
 318
 319 EVENT(QUIESCE)          Thread is quiescent
 320 Callback:
 321         u32 (*report_quiesce)(struct utrace_attached_engine *engine,
 322                               struct task_struct *tsk);
 323
 324 This is the least interesting callback.  It happens at any safe spot,
 325 including after any other event callback.  This lets the tracing engine
 326 know that it is safe to access the thread's state, or to report to users
 327 that it has stopped running user code.
 328
 329 EVENT(CLONE)            Thread is creating a child
 330 Callback:
 331         u32 (*report_clone)(struct utrace_attached_engine *engine,
 332                             struct task_struct *parent,
 333                             unsigned long clone_flags,
 334                             struct task_struct *child);
 335
 336 A clone/clone2/fork/vfork system call has succeeded in creating a new
 337 thread or child process.  The new process is fully formed, but not yet
 338 running.  During this callback, other tracing engines are prevented from
 339 using utrace_attach asynchronously on the child, so that engines tracing
 340 the parent get the first opportunity to attach.  After this callback
 341 returns, the child will start and the parent's system call will return.
 342 If CLONE_VFORK is set, the parent will block before returning.
 343
 344 EVENT(VFORK_DONE)       Finished waiting for CLONE_VFORK child
 345 Callback:
 346         u32 (*report_vfork_done)(struct utrace_attached_engine *engine,
 347                                  struct task_struct *parent, pid_t child_pid);
 348
 349 Event reported for parent using CLONE_VFORK or vfork system call.
 350 The child has died or exec'd, so the vfork parent has unblocked
 351 and is about to return child_pid.
 352
 353 UTRACE_EVENT(EXEC)              Completed exec
 354 Callback:
 355         u32 (*report_exec)(struct utrace_attached_engine *engine,
 356                            struct task_struct *tsk,
 357                            const struct linux_binprm *bprm,
 358                            struct pt_regs *regs);
 359
 360 An execve system call has succeeded and the new program is about to
 361 start running.  The initial user register state is handy to be tweaked
 362 directly, or utrace_regset can be used for full machine state access.
 363
 364 UTRACE_EVENT(EXIT)              Thread is exiting
 365 Callback:
 366         u32 (*report_exit)(struct utrace_attached_engine *engine,
 367                            struct task_struct *tsk,
 368                            long orig_code, long *code);
 369
 370 The thread is exiting and cannot be prevented from doing so, but all its
 371 state is still live.  The *code value will be the wait result seen by
 372 the parent, and can be changed by this engine or others.  The orig_code
 373 value is the real status, not changed by any tracing engine.
 374
 375 UTRACE_EVENT(DEATH)             Thread has finished exiting
 376 Callback:
 377         u32 (*report_death)(struct utrace_attached_engine *engine,
 378                             struct task_struct *tsk);
 379
 380 The thread is really dead now.  If the UTRACE_ACTION_NOREAP flag remains
 381 set after this callback, it remains an unreported zombie; If the flag was
 382 not set already, then it is too late to set it now--its parent has already
 383 been sent SIGCHLD.  Otherwise, it might be reaped by its parent, or
 384 self-reap immediately.  Though the actual reaping may happen in parallel, a
 385 report_reap callback will always be ordered after a report_death callback.
 386
 387 UTRACE_EVENT(SYSCALL_ENTRY)     Thread has entered kernel for a system call
 388 Callback:
 389         u32 (*report_syscall_entry)(struct utrace_attached_engine *engine,
 390                                     struct task_struct *tsk,
 391                                     struct pt_regs *regs);
 392
 393 The system call number and arguments can be seen and modified in the
 394 registers.  The return value register has -ENOSYS, which will be
 395 returned for an invalid system call.  The macro tracehook_abort_syscall(regs)
 396 will abort the system call so that we go immediately to syscall exit,
 397 and return -ENOSYS (or whatever the register state is changed to).  If
 398 tracing enginges keep the thread quiescent here, the system call will
 399 not be performed until it resumes.
 400
 401 UTRACE_EVENT(SYSCALL_EXIT)      Thread is leaving kernel after a system call
 402 Callback:
 403         u32 (*report_syscall_exit)(struct utrace_attached_engine *engine,
 404                                    struct task_struct *tsk,
 405                                    struct pt_regs *regs);
 406
 407 The return value can be seen and modified in the registers.  If the
 408 thread is allowed to resume, it will see any pending signals and then
 409 return to user mode.
 410
 411 UTRACE_EVENT(SIGNAL)            Signal caught by user handler
 412 UTRACE_EVENT(SIGNAL_IGN)                Signal with no effect (SIG_IGN or default)
 413 UTRACE_EVENT(SIGNAL_STOP)       Job control stop signal
 414 UTRACE_EVENT(SIGNAL_TERM)       Fatal termination signal
 415 UTRACE_EVENT(SIGNAL_CORE)       Fatal core-dump signal
 416 UTRACE_EVENT_SIGNAL_ALL         All of the above (bitmask)
 417 Callback:
 418         u32 (*report_signal)(struct utrace_attached_engine *engine,
 419                              struct task_struct *tsk,
 420                              u32 action, siginfo_t *info,
 421                              const struct k_sigaction *orig_ka,
 422                              struct k_sigaction *return_ka);
 423
 424 There are five types of signal events, but all use the same callback.
 425 These happen when a thread is dequeuing a signal to be delivered.
 426 (Not immediately when the signal is sent, and not when the signal is
 427 blocked.)  No signal event is reported for SIGKILL; no tracing engine
 428 can prevent it from killing the thread immediately.  The specific
 429 event types allow an engine to trace signals based on what they do.
 430 UTRACE_EVENT_SIGNAL_ALL is all of them OR'd together, to trace all
 431 signals (except SIGKILL).  A subset of these event flags can be used
 432 e.g. to catch only fatal signals, not handled ones, or to catch only
 433 core-dump signals, not normal termination signals.
 434
 435 The action argument says what the signal's default disposition is:
 436
 437         UTRACE_SIGNAL_DELIVER   Run the user handler from sigaction.
 438         UTRACE_SIGNAL_IGN       Do nothing, ignore the signal.
 439         UTRACE_SIGNAL_TERM      Terminate the process.
 440         UTRACE_SIGNAL_CORE      Terminate the process a write a core dump.
 441         UTRACE_SIGNAL_STOP      Absolutely stop the process, a la SIGSTOP.
 442         UTRACE_SIGNAL_TSTP      Job control stop (no stop if orphaned).
 443
 444 This selection is made from consulting the process's sigaction and the
 445 default action for the signal number, but may already have been changed by
 446 an earlier tracing engine (in which case you see its override).  A return
 447 value of UTRACE_ACTION_RESUME means to carry out this action.  If instead
 448 UTRACE_SIGNAL_* bits are in the return value, that overrides the normal
 449 behavior of the signal.
 450
 451 The signal number and other details of the signal are in info, and
 452 this data can be changed to make the thread see a different signal.
 453 A return value of UTRACE_SIGNAL_DELIVER says to follow the sigaction in
 454 return_ka, which can specify a user handler or SIG_IGN to ignore the
 455 signal or SIG_DFL to follow the default action for info->si_signo.
 456 The orig_ka parameter shows the process's sigaction at the time the
 457 signal was dequeued, and return_ka initially contains this.  Tracing
 458 engines can modify return_ka to change the effects of delivery.
 459 For other UTRACE_SIGNAL_* return values, return_ka is ignored.
 460
 461 UTRACE_SIGNAL_HOLD is a flag bit that can be OR'd into the return
 462 value.  It says to push the signal back on the thread's queue, with
 463 the signal number and details possibly changed in info.  When the
 464 thread is allowed to resume, it will dequeue and report it again.
 465
 466
 467         Teardown Races
 468         -------- -----
 469
 470 Ordinarily synchronization issues for tracing engines are kept fairly
 471 straightforward by using quiescence (see above): you make a thread
 472 quiescent and then once it makes the report_quiesce callback it cannot
 473 do anything else that would result in another callback, until you let
 474 it.  This simple arrangement avoids complex and error-prone code in
 475 each one of a tracing engine's event callbacks to keep them serialized
 476 with the engine's other operations done on that thread from another
 477 thread of control.  However, giving tracing engines complete power to
 478 keep a traced thread stuck in place runs afoul of a more important
 479 kind of simplicity that the kernel overall guarantees: nothing can
 480 prevent or delay SIGKILL from making a thread die and release its
 481 resources.  To preserve this important property of SIGKILL, it as a
 482 special case can break quiescence like nothing else normally can.
 483 This includes both explicit SIGKILL signals and the implicit SIGKILL
 484 sent to each other thread in the same thread group by a thread doing
 485 an exec, or processing a fatal signal, or making an exit_group system
 486 call.  A tracing engine can prevent a thread from beginning the exit
 487 or exec or dying by signal (other than SIGKILL) if it is attached to
 488 that thread, but once the operation begins, no tracing engine can
 489 prevent or delay all other threads in the same thread group dying.
 490
 491 As described above, the report_reap callback is always the final event
 492 in the life cycle of a traced thread.  Tracing engines can use this as
 493 the trigger to clean up their own data structures.  The report_death
 494 callback is always the penultimate event a tracing engine might see,
 495 except when the thread was already in the midst of dying when the
 496 engine attached.  Many tracing engines will have no interest in when a
 497 parent reaps a dead process, and nothing they want to do with a zombie
 498 thread once it dies; for them, the report_death callback is the
 499 natural place to clean up data structures and detach.  To facilitate
 500 writing such engines robustly, given the asynchrony of SIGKILL, and
 501 without error-prone manual implementation of synchronization schemes,
 502 the utrace infrastructure provides some special guarantees about the
 503 report_death and report_reap callbacks.  It still takes some care to
 504 be sure your tracing engine is robust to teardown races, but these
 505 rules make it reasonably straightforward and concise to handle a lot
 506 of corner cases correctly.
 507
 508 The first sort of guarantee concerns the core data structures
 509 themselves.  struct utrace_attached_engine is allocated using RCU, as
 510 is task_struct.  If you call utrace_attach under rcu_read_lock, then
 511 the pointer it returns will always be valid while in the RCU critical
 512 section.  (Note that utrace_attach can block doing memory allocation,
 513 so you must consider the real critical section to start when
 514 utrace_attach returns.  utrace_attach can never block when not given
 515 the UTRACE_ATTACH_CREATE flag bit).  Conversely, you can call
 516 utrace_attach outside of rcu_read_lock and though the pointer can
 517 become stale asynchronously if the thread dies and is reaped, you can
 518 safely pass it to a subsequent utrace_set_flags or utrace_detach call
 519 and will just get an -ESRCH error return.  However, you must be sure
 520 the task_struct remains valid, either via get_task_struct or via RCU.
 521 The utrace infrastructure never holds task_struct references of its
 522 own.  Though neither rcu_read_lock nor any other lock is held while
 523 making a callback, it's always guaranteed that the task_struct and
 524 the struct utrace_attached_engine passed as arguments remain valid
 525 until the callback function returns.
 526
 527 The second guarantee is the serialization of death and reap event
 528 callbacks for a given thread.  The actual reaping by the parent
 529 (release_task call) can occur simultaneously while the thread is
 530 still doing the final steps of dying, including the report_death
 531 callback.  If a tracing engine has requested both DEATH and REAP
 532 event reports, it's guaranteed that the report_reap callback will not
 533 be made until after the report_death callback has returned.  If the
 534 report_death callback itself detaches from the thread (with
 535 utrace_detach or with UTRACE_ACTION_DETACH in its return value), then
 536 the report_reap callback will never be made.  Thus it is safe for a
 537 report_death callback to clean up data structures and detach.
 538
 539 The final sort of guarantee is that a tracing engine will know for
 540 sure whether or not the report_death and/or report_reap callbacks
 541 will be made for a certain thread.  These teardown races are
 542 disambiguated by the error return values of utrace_set_flags and
 543 utrace_detach.  Normally utrace_detach returns zero, and this means
 544 that no more callbacks will be made.  If the thread is in the midst
 545 of dying, utrace_detach returns -EALREADY to indicate that the
 546 report_death callback may already be in progress; when you get this
 547 error, you know that any cleanup your report_death callback does is
 548 about to happen or has just happened--note that if the report_death
 549 callback does not detach, the engine remains attached until the
 550 thread gets reaped.  If the thread is in the midst of being reaped,
 551 utrace_detach returns -ESRCH to indicate that the report_reap
 552 callback may already be in progress; this means the engine is
 553 implicitly detached when the callback completes.  This makes it
 554 possible for a tracing engine that has decided asynchronously to
 555 detach from a thread to safely clean up its data structures, knowing
 556 that no report_death or report_reap callback will try to do the
 557 same.  utrace_detach returns -ESRCH when the struct
 558 utrace_attached_engine has already been detached, but is still a
 559 valid pointer because of rcu_read_lock.  If RCU is used properly, a
 560 tracing engine can use this to safely synchronize its own
 561 independent multiple threads of control with each other and with its
 562 event callbacks that detach.
 563
 564 In the same vein, utrace_set_flags normally returns zero; if the
 565 target thread was quiescent before the call, then after a successful
 566 call, no event callbacks not requested in the new flags will be made,
 567 and a report_quiesce callback will always be made if requested.  It
 568 fails with -EALREADY if you try to clear UTRACE_EVENT(DEATH) when the
 569 report_death callback may already have begun, if you try to clear
 570 UTRACE_EVENT(REAP) when the report_reap callback may already have
 571 begun, if you try to newly set UTRACE_ACTION_NOREAP when the target
 572 may already have sent its parent SIGCHLD, or if you try to newly set
 573 UTRACE_EVENT(DEATH), UTRACE_EVENT(QUIESCE), or UTRACE_ACTION_QUIESCE,
 574 when the target is already dead or dying.  Like utrace_detach, it
 575 returns -ESRCH when the thread has already been detached (including
 576 forcible detach on reaping).  This lets the tracing engine know for
 577 sure which event callbacks it will or won't see after utrace_set_flags
 578 has returned.  By checking for errors, it can know whether to clean up
 579 its data structures immediately or to let its callbacks do the work.