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