include/linux/uprobes.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 #ifndef _LINUX_UPROBES_H
   3 #define _LINUX_UPROBES_H
   4 /*
   5  * User-space Probes (UProbes)
   6  *
   7  * Copyright (C) IBM Corporation, 2008-2012
   8  * Authors:
   9  *      Srikar Dronamraju
  10  *      Jim Keniston
  11  * Copyright (C) 2011-2012 Red Hat, Inc., Peter Zijlstra
  12  */
  13
  14 #include <linux/errno.h>
  15 #include <linux/rbtree.h>
  16 #include <linux/types.h>
  17 #include <linux/wait.h>
  18 #include <linux/timer.h>
  19 #include <linux/seqlock.h>
  20
  21 struct uprobe;
  22 struct vm_area_struct;
  23 struct mm_struct;
  24 struct inode;
  25 struct notifier_block;
  26 struct page;
  27
  28 /*
  29  * Allowed return values from uprobe consumer's handler callback
  30  * with following meaning:
  31  *
  32  * UPROBE_HANDLER_REMOVE
  33  * - Remove the uprobe breakpoint from current->mm.
  34  * UPROBE_HANDLER_IGNORE
  35  * - Ignore ret_handler callback for this consumer.
  36  */
  37 #define UPROBE_HANDLER_REMOVE           1
  38 #define UPROBE_HANDLER_IGNORE           2
  39
  40 #define MAX_URETPROBE_DEPTH             64
  41
  42 struct uprobe_consumer {
  43         /*
  44          * handler() can return UPROBE_HANDLER_REMOVE to signal the need to
  45          * unregister uprobe for current process. If UPROBE_HANDLER_REMOVE is
  46          * returned, filter() callback has to be implemented as well and it
  47          * should return false to "confirm" the decision to uninstall uprobe
  48          * for the current process. If filter() is omitted or returns true,
  49          * UPROBE_HANDLER_REMOVE is effectively ignored.
  50          */
  51         int (*handler)(struct uprobe_consumer *self, struct pt_regs *regs, __u64 *data);
  52         int (*ret_handler)(struct uprobe_consumer *self,
  53                                 unsigned long func,
  54                                 struct pt_regs *regs, __u64 *data);
  55         bool (*filter)(struct uprobe_consumer *self, struct mm_struct *mm);
  56
  57         struct list_head cons_node;
  58
  59         __u64 id;       /* set when uprobe_consumer is registered */
  60 };
  61
  62 #ifdef CONFIG_UPROBES
  63 #include <asm/uprobes.h>
  64
  65 enum uprobe_task_state {
  66         UTASK_RUNNING,
  67         UTASK_SSTEP,
  68         UTASK_SSTEP_ACK,
  69         UTASK_SSTEP_TRAPPED,
  70 };
  71
  72 /* The state of hybrid-lifetime uprobe inside struct return_instance */
  73 enum hprobe_state {
  74         HPROBE_LEASED,          /* uretprobes_srcu-protected uprobe */
  75         HPROBE_STABLE,          /* refcounted uprobe */
  76         HPROBE_GONE,            /* NULL uprobe, SRCU expired, refcount failed */
  77         HPROBE_CONSUMED,        /* uprobe "consumed" by uretprobe handler */
  78 };
  79
  80 /*
  81  * Hybrid lifetime uprobe. Represents a uprobe instance that could be either
  82  * SRCU protected (with SRCU protection eventually potentially timing out),
  83  * refcounted using uprobe->ref, or there could be no valid uprobe (NULL).
  84  *
  85  * hprobe's internal state is setup such that background timer thread can
  86  * atomically "downgrade" temporarily RCU-protected uprobe into refcounted one
  87  * (or no uprobe, if refcounting failed).
  88  *
  89  * *stable* pointer always point to the uprobe (or could be NULL if there is
  90  * was no valid underlying uprobe to begin with).
  91  *
  92  * *leased* pointer is the key to achieving race-free atomic lifetime state
  93  * transition and can have three possible states:
  94  *   - either the same non-NULL value as *stable*, in which case uprobe is
  95  *     SRCU-protected;
  96  *   - NULL, in which case uprobe (if there is any) is refcounted;
  97  *   - special __UPROBE_DEAD value, which represents an uprobe that was SRCU
  98  *     protected initially, but SRCU period timed out and we attempted to
  99  *     convert it to refcounted, but refcount_inc_not_zero() failed, because
 100  *     uprobe effectively went away (the last consumer unsubscribed). In this
 101  *     case it's important to know that *stable* pointer (which still has
 102  *     non-NULL uprobe pointer) shouldn't be used, because lifetime of
 103  *     underlying uprobe is not guaranteed anymore. __UPROBE_DEAD is just an
 104  *     internal marker and is handled transparently by hprobe_fetch() helper.
 105  *
 106  * When uprobe is SRCU-protected, we also record srcu_idx value, necessary for
 107  * SRCU unlocking.
 108  *
 109  * See hprobe_expire() and hprobe_fetch() for details of race-free uprobe
 110  * state transitioning details. It all hinges on atomic xchg() over *leaded*
 111  * pointer. *stable* pointer, once initially set, is not modified concurrently.
 112  */
 113 struct hprobe {
 114         enum hprobe_state state;
 115         int srcu_idx;
 116         struct uprobe *uprobe;
 117 };
 118
 119 /*
 120  * uprobe_task: Metadata of a task while it singlesteps.
 121  */
 122 struct uprobe_task {
 123         enum uprobe_task_state          state;
 124
 125         unsigned int                    depth;
 126         struct return_instance          *return_instances;
 127
 128         struct return_instance          *ri_pool;
 129         struct timer_list               ri_timer;
 130         seqcount_t                      ri_seqcount;
 131
 132         union {
 133                 struct {
 134                         struct arch_uprobe_task autask;
 135                         unsigned long           vaddr;
 136                 };
 137
 138                 struct {
 139                         struct callback_head    dup_xol_work;
 140                         unsigned long           dup_xol_addr;
 141                 };
 142         };
 143
 144         struct uprobe                   *active_uprobe;
 145         unsigned long                   xol_vaddr;
 146
 147         struct arch_uprobe              *auprobe;
 148 };
 149
 150 struct return_consumer {
 151         __u64   cookie;
 152         __u64   id;
 153 };
 154
 155 struct return_instance {
 156         struct hprobe           hprobe;
 157         unsigned long           func;
 158         unsigned long           stack;          /* stack pointer */
 159         unsigned long           orig_ret_vaddr; /* original return address */
 160         bool                    chained;        /* true, if instance is nested */
 161         int                     cons_cnt;       /* total number of session consumers */
 162
 163         struct return_instance  *next;          /* keep as stack */
 164         struct rcu_head         rcu;
 165
 166         /* singular pre-allocated return_consumer instance for common case */
 167         struct return_consumer  consumer;
 168         /*
 169          * extra return_consumer instances for rare cases of multiple session consumers,
 170          * contains (cons_cnt - 1) elements
 171          */
 172         struct return_consumer  *extra_consumers;
 173 } ____cacheline_aligned;
 174
 175 enum rp_check {
 176         RP_CHECK_CALL,
 177         RP_CHECK_CHAIN_CALL,
 178         RP_CHECK_RET,
 179 };
 180
 181 struct xol_area;
 182
 183 struct uprobes_state {
 184         struct xol_area         *xol_area;
 185 };
 186
 187 extern void __init uprobes_init(void);
 188 extern int set_swbp(struct arch_uprobe *aup, struct mm_struct *mm, unsigned long vaddr);
 189 extern int set_orig_insn(struct arch_uprobe *aup, struct mm_struct *mm, unsigned long vaddr);
 190 extern bool is_swbp_insn(uprobe_opcode_t *insn);
 191 extern bool is_trap_insn(uprobe_opcode_t *insn);
 192 extern unsigned long uprobe_get_swbp_addr(struct pt_regs *regs);
 193 extern unsigned long uprobe_get_trap_addr(struct pt_regs *regs);
 194 extern int uprobe_write_opcode(struct arch_uprobe *auprobe, struct mm_struct *mm, unsigned long vaddr, uprobe_opcode_t);
 195 extern struct uprobe *uprobe_register(struct inode *inode, loff_t offset, loff_t ref_ctr_offset, struct uprobe_consumer *uc);
 196 extern int uprobe_apply(struct uprobe *uprobe, struct uprobe_consumer *uc, bool);
 197 extern void uprobe_unregister_nosync(struct uprobe *uprobe, struct uprobe_consumer *uc);
 198 extern void uprobe_unregister_sync(void);
 199 extern int uprobe_mmap(struct vm_area_struct *vma);
 200 extern void uprobe_munmap(struct vm_area_struct *vma, unsigned long start, unsigned long end);
 201 extern void uprobe_start_dup_mmap(void);
 202 extern void uprobe_end_dup_mmap(void);
 203 extern void uprobe_dup_mmap(struct mm_struct *oldmm, struct mm_struct *newmm);
 204 extern void uprobe_free_utask(struct task_struct *t);
 205 extern void uprobe_copy_process(struct task_struct *t, unsigned long flags);
 206 extern int uprobe_post_sstep_notifier(struct pt_regs *regs);
 207 extern int uprobe_pre_sstep_notifier(struct pt_regs *regs);
 208 extern void uprobe_notify_resume(struct pt_regs *regs);
 209 extern bool uprobe_deny_signal(void);
 210 extern bool arch_uprobe_skip_sstep(struct arch_uprobe *aup, struct pt_regs *regs);
 211 extern void uprobe_clear_state(struct mm_struct *mm);
 212 extern int  arch_uprobe_analyze_insn(struct arch_uprobe *aup, struct mm_struct *mm, unsigned long addr);
 213 extern int  arch_uprobe_pre_xol(struct arch_uprobe *aup, struct pt_regs *regs);
 214 extern int  arch_uprobe_post_xol(struct arch_uprobe *aup, struct pt_regs *regs);
 215 extern bool arch_uprobe_xol_was_trapped(struct task_struct *tsk);
 216 extern int  arch_uprobe_exception_notify(struct notifier_block *self, unsigned long val, void *data);
 217 extern void arch_uprobe_abort_xol(struct arch_uprobe *aup, struct pt_regs *regs);
 218 extern unsigned long arch_uretprobe_hijack_return_addr(unsigned long trampoline_vaddr, struct pt_regs *regs);
 219 extern bool arch_uretprobe_is_alive(struct return_instance *ret, enum rp_check ctx, struct pt_regs *regs);
 220 extern bool arch_uprobe_ignore(struct arch_uprobe *aup, struct pt_regs *regs);
 221 extern void arch_uprobe_copy_ixol(struct page *page, unsigned long vaddr,
 222                                          void *src, unsigned long len);
 223 extern void uprobe_handle_trampoline(struct pt_regs *regs);
 224 extern void *arch_uprobe_trampoline(unsigned long *psize);
 225 extern unsigned long uprobe_get_trampoline_vaddr(void);
 226 #else /* !CONFIG_UPROBES */
 227 struct uprobes_state {
 228 };
 229
 230 static inline void uprobes_init(void)
 231 {
 232 }
 233
 234 #define uprobe_get_trap_addr(regs)      instruction_pointer(regs)
 235
 236 static inline struct uprobe *
 237 uprobe_register(struct inode *inode, loff_t offset, loff_t ref_ctr_offset, struct uprobe_consumer *uc)
 238 {
 239         return ERR_PTR(-ENOSYS);
 240 }
 241 static inline int
 242 uprobe_apply(struct uprobe* uprobe, struct uprobe_consumer *uc, bool add)
 243 {
 244         return -ENOSYS;
 245 }
 246 static inline void
 247 uprobe_unregister_nosync(struct uprobe *uprobe, struct uprobe_consumer *uc)
 248 {
 249 }
 250 static inline void uprobe_unregister_sync(void)
 251 {
 252 }
 253 static inline int uprobe_mmap(struct vm_area_struct *vma)
 254 {
 255         return 0;
 256 }
 257 static inline void
 258 uprobe_munmap(struct vm_area_struct *vma, unsigned long start, unsigned long end)
 259 {
 260 }
 261 static inline void uprobe_start_dup_mmap(void)
 262 {
 263 }
 264 static inline void uprobe_end_dup_mmap(void)
 265 {
 266 }
 267 static inline void
 268 uprobe_dup_mmap(struct mm_struct *oldmm, struct mm_struct *newmm)
 269 {
 270 }
 271 static inline void uprobe_notify_resume(struct pt_regs *regs)
 272 {
 273 }
 274 static inline bool uprobe_deny_signal(void)
 275 {
 276         return false;
 277 }
 278 static inline void uprobe_free_utask(struct task_struct *t)
 279 {
 280 }
 281 static inline void uprobe_copy_process(struct task_struct *t, unsigned long flags)
 282 {
 283 }
 284 static inline void uprobe_clear_state(struct mm_struct *mm)
 285 {
 286 }
 287 #endif /* !CONFIG_UPROBES */
 288 #endif  /* _LINUX_UPROBES_H */