include/linux/utrace.h

   1 /*
   2  * User Debugging Data & Event Rendezvous
   3  *
   4  * This interface allows for notification of interesting events in a thread.
   5  * It also mediates access to thread state such as registers.
   6  * Multiple unrelated users can be associated with a single thread.
   7  * We call each of these a tracing engine.
   8  *
   9  * A tracing engine starts by calling utrace_attach on the chosen thread,
  10  * passing in a set of hooks (struct utrace_engine_ops), and some associated
  11  * data.  This produces a struct utrace_attached_engine, which is the handle
  12  * used for all other operations.  An attached engine has its ops vector,
  13  * its data, and a flags word controlled by utrace_set_flags.
  14  *
  15  * Each engine's flags word contains two kinds of flags: events of
  16  * interest, and action state flags.
  17  *
  18  * For each event flag that is set, that engine will get the
  19  * appropriate ops->report_* callback when the event occurs.  The
  20  * struct utrace_engine_ops need not provide callbacks for an event
  21  * unless the engine sets one of the associated event flags.
  22  *
  23  * Action state flags change the normal behavior of the thread.
  24  * These bits are in UTRACE_ACTION_STATE_MASK; these can be OR'd into
  25  * flags set with utrace_set_flags.  Also, every callback that return
  26  * an action value can reset these bits for the engine (see below).
  27  *
  28  * The bits UTRACE_ACTION_STATE_MASK of all attached engines are OR'd
  29  * together, so each action is in force as long as any engine requests it.
  30  * As long as some engine sets the UTRACE_ACTION_QUIESCE flag, the thread
  31  * will block and not resume running user code.  When the last engine
  32  * clears its UTRACE_ACTION_QUIESCE flag, the thread will resume running.
  33  */
  34
  35 #ifndef _LINUX_UTRACE_H
  36 #define _LINUX_UTRACE_H 1
  37
  38 #include <linux/list.h>
  39 #include <linux/rcupdate.h>
  40 #include <linux/signal.h>
  41
  42 struct linux_binprm;
  43 struct pt_regs;
  44 struct utrace_regset;
  45 struct utrace_regset_view;
  46
  47
  48 /*
  49  * Flags in task_struct.utrace_flags and utrace_attached_engine.flags.
  50  * Low four bits are UTRACE_ACTION_STATE_MASK bits (below).
  51  * Higher bits are events of interest.
  52  */
  53
  54 #define UTRACE_FIRST_EVENT      4
  55 #define UTRACE_EVENT_BITS       (BITS_PER_LONG - UTRACE_FIRST_EVENT)
  56 #define UTRACE_EVENT_MASK       (-1UL &~ UTRACE_ACTION_STATE_MASK)
  57
  58 enum utrace_events {
  59         _UTRACE_EVENT_QUIESCE,  /* Tracing requests stop.  */
  60         _UTRACE_EVENT_REAP,     /* Zombie reaped, no more tracing possible.  */
  61         _UTRACE_EVENT_CLONE,    /* Successful clone/fork/vfork just done.  */
  62         _UTRACE_EVENT_VFORK_DONE, /* vfork woke from waiting for child.  */
  63         _UTRACE_EVENT_EXEC,     /* Successful execve just completed.  */
  64         _UTRACE_EVENT_EXIT,     /* Thread exit in progress.  */
  65         _UTRACE_EVENT_DEATH,    /* Thread has died.  */
  66         _UTRACE_EVENT_SYSCALL_ENTRY, /* User entered kernel for system call. */
  67         _UTRACE_EVENT_SYSCALL_EXIT, /* Returning to user after system call.  */
  68         _UTRACE_EVENT_SIGNAL,   /* Signal delivery will run a user handler.  */
  69         _UTRACE_EVENT_SIGNAL_IGN, /* No-op signal to be delivered.  */
  70         _UTRACE_EVENT_SIGNAL_STOP, /* Signal delivery will suspend.  */
  71         _UTRACE_EVENT_SIGNAL_TERM, /* Signal delivery will terminate.  */
  72         _UTRACE_EVENT_SIGNAL_CORE, /* Signal delivery will dump core.  */
  73         _UTRACE_EVENT_JCTL,     /* Job control stop or continue completed.  */
  74         _UTRACE_NEVENTS
  75 };
  76 #define UTRACE_EVENT_BIT(type)  (UTRACE_FIRST_EVENT + _UTRACE_EVENT_##type)
  77 #define UTRACE_EVENT(type)      (1UL << UTRACE_EVENT_BIT(type))
  78
  79 /*
  80  * All the kinds of signal events.  These all use the report_signal callback.
  81  */
  82 #define UTRACE_EVENT_SIGNAL_ALL (UTRACE_EVENT(SIGNAL) \
  83                                  | UTRACE_EVENT(SIGNAL_IGN) \
  84                                  | UTRACE_EVENT(SIGNAL_STOP) \
  85                                  | UTRACE_EVENT(SIGNAL_TERM) \
  86                                  | UTRACE_EVENT(SIGNAL_CORE))
  87 /*
  88  * Both kinds of syscall events; these call the report_syscall_entry and
  89  * report_syscall_exit callbacks, respectively.
  90  */
  91 #define UTRACE_EVENT_SYSCALL    \
  92         (UTRACE_EVENT(SYSCALL_ENTRY) | UTRACE_EVENT(SYSCALL_EXIT))
  93
  94
  95 /*
  96  * Action flags, in return value of callbacks.
  97  *
  98  * UTRACE_ACTION_RESUME (zero) is the return value to do nothing special.
  99  * For each particular callback, some bits in UTRACE_ACTION_OP_MASK can
 100  * be set in the return value to change the thread's behavior (see below).
 101  *
 102  * If UTRACE_ACTION_NEWSTATE is set, then the UTRACE_ACTION_STATE_MASK
 103  * bits in the return value replace the engine's flags as in utrace_set_flags
 104  * (but the event flags remained unchanged).
 105  *
 106  * If UTRACE_ACTION_HIDE is set, then the callbacks to other engines
 107  * should be suppressed for this event.  This is appropriate only when
 108  * the event was artificially provoked by something this engine did,
 109  * such as setting a breakpoint.
 110  *
 111  * If UTRACE_ACTION_DETACH is set, this engine is detached as by utrace_detach.
 112  * The action bits in UTRACE_ACTION_OP_MASK work as normal, but the engine's
 113  * UTRACE_ACTION_STATE_MASK bits will no longer affect the thread.
 114  */
 115 #define UTRACE_ACTION_RESUME    0x0000 /* Continue normally after event.  */
 116 #define UTRACE_ACTION_HIDE      0x0010 /* Hide event from other tracing.  */
 117 #define UTRACE_ACTION_DETACH    0x0020 /* Detach me, state flags ignored.  */
 118 #define UTRACE_ACTION_NEWSTATE  0x0040 /* Replace state bits.  */
 119
 120 /*
 121  * These flags affect the state of the thread until they are changed via
 122  * utrace_set_flags or by the next callback to the same engine that uses
 123  * UTRACE_ACTION_NEWSTATE.
 124  */
 125 #define UTRACE_ACTION_QUIESCE   0x0001 /* Stay quiescent after callbacks.  */
 126 #define UTRACE_ACTION_SINGLESTEP 0x0002 /* Resume for one instruction.  */
 127 #define UTRACE_ACTION_BLOCKSTEP 0x0004 /* Resume until next branch.  */
 128 #define UTRACE_ACTION_NOREAP    0x0008 /* Inhibit parent SIGCHLD and wait.  */
 129 #define UTRACE_ACTION_STATE_MASK 0x000f /* Lasting state bits.  */
 130
 131 /* These flags have meanings specific to the particular event report hook.  */
 132 #define UTRACE_ACTION_OP_MASK   0xff00
 133
 134 /*
 135  * Action flags in return value and argument of report_signal callback.
 136  */
 137 #define UTRACE_SIGNAL_DELIVER   0x0100 /* Deliver according to sigaction.  */
 138 #define UTRACE_SIGNAL_IGN       0x0200 /* Ignore the signal.  */
 139 #define UTRACE_SIGNAL_TERM      0x0300 /* Terminate the process.  */
 140 #define UTRACE_SIGNAL_CORE      0x0400 /* Terminate with core dump.  */
 141 #define UTRACE_SIGNAL_STOP      0x0500 /* Deliver as absolute stop.  */
 142 #define UTRACE_SIGNAL_TSTP      0x0600 /* Deliver as job control stop.  */
 143 #define UTRACE_SIGNAL_HOLD      0x1000 /* Flag, push signal back on queue.  */
 144 /*
 145  * This value is passed to a report_signal callback after a signal
 146  * handler is entered while UTRACE_ACTION_SINGLESTEP is in force.
 147  * For this callback, no signal will never actually be delivered regardless
 148  * of the return value, and the other callback parameters are null.
 149  */
 150 #define UTRACE_SIGNAL_HANDLER   0x0700
 151
 152 /* Action flag in return value of report_jctl.  */
 153 #define UTRACE_JCTL_NOSIGCHLD   0x0100 /* Do not notify the parent.  */
 154
 155
 156 /*
 157  * Flags for utrace_attach.  If UTRACE_ATTACH_CREATE is not specified,
 158  * you only look up an existing engine already attached to the
 159  * thread.  If UTRACE_ATTACH_MATCH_* bits are set, only consider
 160  * matching engines.  If UTRACE_ATTACH_EXCLUSIVE is set, attempting to
 161  * attach a second (matching) engine fails with -EEXIST.
 162  */
 163 #define UTRACE_ATTACH_CREATE            0x0010 /* Attach a new engine.  */
 164 #define UTRACE_ATTACH_EXCLUSIVE         0x0020 /* Refuse if existing match.  */
 165 #define UTRACE_ATTACH_MATCH_OPS         0x0001 /* Match engines on ops.  */
 166 #define UTRACE_ATTACH_MATCH_DATA        0x0002 /* Match engines on data.  */
 167 #define UTRACE_ATTACH_MATCH_MASK        0x000f
 168
 169
 170 /*
 171  * Per-thread structure task_struct.utrace points to.
 172  *
 173  * The task itself never has to worry about this going away after
 174  * some event is found set in task_struct.utrace_flags.
 175  * Once created, this pointer is changed only when the task is quiescent
 176  * (TASK_TRACED or TASK_STOPPED with the siglock held, or dead).
 177  *
 178  * For other parties, the pointer to this is protected by RCU and
 179  * task_lock.  Since call_rcu is never used while the thread is alive and
 180  * using this struct utrace, we can overlay the RCU data structure used
 181  * only for a dead struct with some local state used only for a live utrace
 182  * on an active thread.
 183  */
 184 struct utrace
 185 {
 186         union {
 187                 struct rcu_head dead;
 188                 struct {
 189                         struct task_struct *cloning;
 190                         struct utrace_signal *signal;
 191                 } live;
 192                 struct {
 193                         int notified;
 194                         int reap;
 195                 } exit;
 196         } u;
 197
 198         struct list_head engines;
 199         spinlock_t lock;
 200 };
 201 #define utrace_lock(utrace)     spin_lock(&(utrace)->lock)
 202 #define utrace_unlock(utrace)   spin_unlock(&(utrace)->lock)
 203
 204
 205 /*
 206  * Per-engine per-thread structure.
 207  *
 208  * The task itself never has to worry about engines detaching while
 209  * it's doing event callbacks.  These structures are freed only when
 210  * the task is quiescent.  For other parties, the list is protected
 211  * by RCU and utrace_lock.
 212  */
 213 struct utrace_attached_engine
 214 {
 215         struct list_head entry; /* Entry on thread's utrace.engines list.  */
 216         struct rcu_head rhead;
 217
 218         const struct utrace_engine_ops *ops;
 219         unsigned long data;
 220
 221         unsigned long flags;
 222 };
 223
 224
 225 struct utrace_engine_ops
 226 {
 227         /*
 228          * Event reporting hooks.
 229          *
 230          * Return values contain UTRACE_ACTION_* flag bits.
 231          * The UTRACE_ACTION_OP_MASK bits are specific to each kind of event.
 232          *
 233          * All report_* hooks are called with no locks held, in a generally
 234          * safe environment when we will be returning to user mode soon.
 235          * It is fine to block for memory allocation and the like, but all
 236          * hooks are *asynchronous* and must not block on external events.
 237          * If you want the thread to block, request UTRACE_ACTION_QUIESCE in
 238          * your hook; then later wake it up with utrace_set_flags.
 239          *
 240          */
 241
 242         /*
 243          * Event reported for parent, before child might run.
 244          * The PF_STARTING flag prevents other engines from attaching
 245          * before this one has its chance.
 246          */
 247         u32 (*report_clone)(struct utrace_attached_engine *engine,
 248                             struct task_struct *parent,
 249                             unsigned long clone_flags,
 250                             struct task_struct *child);
 251
 252         /*
 253          * Event reported for parent using CLONE_VFORK or vfork system call.
 254          * The child has died or exec'd, so the vfork parent has unblocked
 255          * and is about to return child_pid.
 256          */
 257         u32 (*report_vfork_done)(struct utrace_attached_engine *engine,
 258                                  struct task_struct *parent, pid_t child_pid);
 259
 260         /*
 261          * Event reported after UTRACE_ACTION_QUIESCE is set, when the target
 262          * thread is quiescent.  Either it's the current thread, or it's in
 263          * TASK_TRACED or TASK_STOPPED and will not resume running until the
 264          * UTRACE_ACTION_QUIESCE flag is no longer asserted by any engine.
 265          */
 266         u32 (*report_quiesce)(struct utrace_attached_engine *engine,
 267                               struct task_struct *tsk);
 268
 269         /*
 270          * Thread dequeuing a signal to be delivered.
 271          * The action and *return_ka values say what UTRACE_ACTION_RESUME
 272          * will do (possibly already influenced by another tracing engine).
 273          * An UTRACE_SIGNAL_* return value overrides the signal disposition.
 274          * The *info data (including info->si_signo) can be changed at will.
 275          * Changing *return_ka affects the sigaction that be used.
 276          * The *orig_ka value is the one in force before other tracing
 277          * engines intervened.
 278          */
 279         u32 (*report_signal)(struct utrace_attached_engine *engine,
 280                              struct task_struct *tsk,
 281                              struct pt_regs *regs,
 282                              u32 action, siginfo_t *info,
 283                              const struct k_sigaction *orig_ka,
 284                              struct k_sigaction *return_ka);
 285
 286         /*
 287          * Job control event completing, about to send SIGCHLD to parent
 288          * with CLD_STOPPED or CLD_CONTINUED as given in type.
 289          * UTRACE_JOBSTOP_NOSIGCHLD in the return value inhibits that.
 290          */
 291         u32 (*report_jctl)(struct utrace_attached_engine *engine,
 292                            struct task_struct *tsk,
 293                            int type);
 294
 295         /*
 296          * Thread has just completed an exec.
 297          * The initial user register state is handy to be tweaked directly.
 298          */
 299         u32 (*report_exec)(struct utrace_attached_engine *engine,
 300                            struct task_struct *tsk,
 301                            const struct linux_binprm *bprm,
 302                            struct pt_regs *regs);
 303
 304         /*
 305          * Thread has entered the kernel to request a system call.
 306          * The user register state is handy to be tweaked directly.
 307          */
 308         u32 (*report_syscall_entry)(struct utrace_attached_engine *engine,
 309                                     struct task_struct *tsk,
 310                                     struct pt_regs *regs);
 311
 312         /*
 313          * Thread is about to leave the kernel after a system call request.
 314          * The user register state is handy to be tweaked directly.
 315          */
 316         u32 (*report_syscall_exit)(struct utrace_attached_engine *engine,
 317                                    struct task_struct *tsk,
 318                                    struct pt_regs *regs);
 319
 320         /*
 321          * Thread is exiting and cannot be prevented from doing so,
 322          * but all its state is still live.  The *code value will be
 323          * the wait result seen by the parent, and can be changed by
 324          * this engine or others.  The orig_code value is the real
 325          * status, not changed by any tracing engine.
 326          */
 327         u32 (*report_exit)(struct utrace_attached_engine *engine,
 328                            struct task_struct *tsk,
 329                            long orig_code, long *code);
 330
 331         /*
 332          * Thread is really dead now.  If UTRACE_ACTION_NOREAP is in force,
 333          * it remains an unreported zombie.  Otherwise, it might be reaped
 334          * by its parent, or self-reap immediately.  Though the actual
 335          * reaping may happen in parallel, a report_reap callback will
 336          * always be ordered after a report_death callback.
 337          */
 338         u32 (*report_death)(struct utrace_attached_engine *engine,
 339                             struct task_struct *tsk);
 340
 341         /*
 342          * Called when someone reaps the dead task (parent, init, or self).
 343          * No more callbacks are made after this one.
 344          * The engine is always detached.
 345          * There is nothing more a tracing engine can do about this thread.
 346          */
 347         void (*report_reap)(struct utrace_attached_engine *engine,
 348                             struct task_struct *tsk);
 349
 350         /*
 351          * Miscellaneous hooks.  These are not associated with event reports.
 352          * Any of these may be null if the engine has nothing to say.
 353          * These hooks are called in more constrained environments and should
 354          * not block or do very much.
 355          */
 356
 357         /*
 358          * Return nonzero iff the caller task should be allowed to access
 359          * the memory of the target task via /proc/PID/mem and so forth,
 360          * by dint of this engine's attachment to the target.
 361          */
 362         int (*allow_access_process_vm)(struct utrace_attached_engine *engine,
 363                                        struct task_struct *target,
 364                                        struct task_struct *caller);
 365
 366         /*
 367          * Return LSM_UNSAFE_* bits that apply to the exec in progress
 368          * due to tracing done by this engine.  These bits indicate that
 369          * someone is able to examine the process and so a set-UID or similar
 370          * privilege escalation may not be safe to permit.
 371          *
 372          * Called with task_lock held.
 373          */
 374         int (*unsafe_exec)(struct utrace_attached_engine *engine,
 375                            struct task_struct *target);
 376
 377         /*
 378          * Return the task_struct for the task using ptrace on this one, or
 379          * NULL.  Always called with rcu_read_lock held to keep the
 380          * returned struct alive.
 381          *
 382          * At exec time, this may be called with task_lock(target) still
 383          * held from when unsafe_exec was just called.  In that case it
 384          * must give results consistent with those unsafe_exec results,
 385          * i.e. non-NULL if any LSM_UNSAFE_PTRACE_* bits were set.
 386          *
 387          * The value is also used to display after "TracerPid:" in
 388          * /proc/PID/status, where it is called with only rcu_read_lock held.
 389          *
 390          * If this engine returns NULL, another engine may supply the result.
 391          */
 392         struct task_struct *(*tracer_task)(struct utrace_attached_engine *,
 393                                            struct task_struct *target);
 394 };
 395
 396
 397 /***
 398  *** These are the exported entry points for tracing engines to use.
 399  ***/
 400
 401 /*
 402  * Attach a new tracing engine to a thread, or look up attached engines.
 403  * See UTRACE_ATTACH_* flags, above.  The caller must ensure that the
 404  * target thread does not get freed, i.e. hold a ref or be its parent.
 405  */
 406 struct utrace_attached_engine *utrace_attach(struct task_struct *target,
 407                                              int flags,
 408                                              const struct utrace_engine_ops *,
 409                                              unsigned long data);
 410
 411 /*
 412  * Detach a tracing engine from a thread.  After this, the engine
 413  * data structure is no longer accessible, and the thread might be reaped.
 414  * The thread will start running again if it was being kept quiescent
 415  * and no longer has any attached engines asserting UTRACE_ACTION_QUIESCE.
 416  *
 417  * If the target thread is not already quiescent, then a callback to this
 418  * engine might be in progress or about to start on another CPU.  If it's
 419  * quiescent when utrace_detach is called, then after return it's guaranteed
 420  * that no more callbacks to the ops vector will be done.
 421  */
 422 void utrace_detach(struct task_struct *target,
 423                    struct utrace_attached_engine *engine);
 424
 425 /*
 426  * Change the flags for a tracing engine.
 427  * This resets the event flags and the action state flags.
 428  * If UTRACE_ACTION_QUIESCE and UTRACE_EVENT(QUIESCE) are set,
 429  * this will cause a report_quiesce callback soon, maybe immediately.
 430  * If UTRACE_ACTION_QUIESCE was set before and is no longer set by
 431  * any engine, this will wake the thread up.
 432  */
 433 void utrace_set_flags(struct task_struct *target,
 434                       struct utrace_attached_engine *engine,
 435                       unsigned long flags);
 436
 437 /*
 438  * Cause a specified signal delivery in the target thread, which must be
 439  * quiescent (or the current thread).  The action has UTRACE_SIGNAL_* bits
 440  * as returned from a report_signal callback.  If ka is non-null, it gives
 441  * the sigaction to follow for UTRACE_SIGNAL_DELIVER; otherwise, the
 442  * installed sigaction at the time of delivery is used.
 443  */
 444 int utrace_inject_signal(struct task_struct *target,
 445                          struct utrace_attached_engine *engine,
 446                          u32 action, siginfo_t *info,
 447                          const struct k_sigaction *ka);
 448
 449 /*
 450  * Prepare to access thread's machine state, see <linux/tracehook.h>.
 451  * The given thread must be quiescent (or the current thread).
 452  * When this returns, the struct utrace_regset calls may be used to
 453  * interrogate or change the thread's state.  Do not cache the returned
 454  * pointer when the thread can resume.  You must call utrace_regset to
 455  * ensure that context switching has completed and consistent state is
 456  * available.
 457  */
 458 const struct utrace_regset *utrace_regset(struct task_struct *target,
 459                                           struct utrace_attached_engine *,
 460                                           const struct utrace_regset_view *,
 461                                           int which);
 462
 463
 464 /*
 465  * Hooks in <linux/tracehook.h> call these entry points to the utrace dispatch.
 466  */
 467 int utrace_quiescent(struct task_struct *, struct utrace_signal *);
 468 void utrace_release_task(struct task_struct *);
 469 int utrace_get_signal(struct task_struct *, struct pt_regs *,
 470                       siginfo_t *, struct k_sigaction *);
 471 void utrace_report_clone(unsigned long clone_flags, struct task_struct *child);
 472 void utrace_report_vfork_done(pid_t child_pid);
 473 void utrace_report_exit(long *exit_code);
 474 void utrace_report_death(struct task_struct *, struct utrace *);
 475 int utrace_report_jctl(int type);
 476 void utrace_report_exec(struct linux_binprm *bprm, struct pt_regs *regs);
 477 void utrace_report_syscall(struct pt_regs *regs, int is_exit);
 478 struct task_struct *utrace_tracer_task(struct task_struct *);
 479 int utrace_allow_access_process_vm(struct task_struct *);
 480 int utrace_unsafe_exec(struct task_struct *);
 481 void utrace_signal_handler_singlestep(struct task_struct *, struct pt_regs *);
 482
 483
 484 #endif  /* linux/utrace.h */