include/linux/uprobes.h

Source file repositories/reference/linux-study-clean/include/linux/uprobes.h

File Facts

System
Linux kernel
Corpus path
include/linux/uprobes.h
Extension
.h
Size
10615 bytes
Lines
309
Domain
Core OS
Bucket
Core Kernel Interface
Inferred role
Core OS: implementation source
Status
source implementation candidate

Why This File Exists

Core operating-system implementation surface: boot, tasks, memory, VFS, syscall-facing interfaces, synchronization, credentials, and isolation.

Dependency Surface

Detected Declarations

Annotated Snippet

struct uprobe_consumer {
	/*
	 * handler() can return UPROBE_HANDLER_REMOVE to signal the need to
	 * unregister uprobe for current process. If UPROBE_HANDLER_REMOVE is
	 * returned, filter() callback has to be implemented as well and it
	 * should return false to "confirm" the decision to uninstall uprobe
	 * for the current process. If filter() is omitted or returns true,
	 * UPROBE_HANDLER_REMOVE is effectively ignored.
	 */
	int (*handler)(struct uprobe_consumer *self, struct pt_regs *regs, __u64 *data);
	int (*ret_handler)(struct uprobe_consumer *self,
				unsigned long func,
				struct pt_regs *regs, __u64 *data);
	bool (*filter)(struct uprobe_consumer *self, struct mm_struct *mm);

	struct list_head cons_node;

	__u64 id;	/* set when uprobe_consumer is registered */
};

#ifdef CONFIG_UPROBES
#include <asm/uprobes.h>

enum uprobe_task_state {
	UTASK_RUNNING,
	UTASK_SSTEP,
	UTASK_SSTEP_ACK,
	UTASK_SSTEP_TRAPPED,
};

/* The state of hybrid-lifetime uprobe inside struct return_instance */
enum hprobe_state {
	HPROBE_LEASED,		/* uretprobes_srcu-protected uprobe */
	HPROBE_STABLE,		/* refcounted uprobe */
	HPROBE_GONE,		/* NULL uprobe, SRCU expired, refcount failed */
	HPROBE_CONSUMED,	/* uprobe "consumed" by uretprobe handler */
};

/*
 * Hybrid lifetime uprobe. Represents a uprobe instance that could be either
 * SRCU protected (with SRCU protection eventually potentially timing out),
 * refcounted using uprobe->ref, or there could be no valid uprobe (NULL).
 *
 * hprobe's internal state is setup such that background timer thread can
 * atomically "downgrade" temporarily RCU-protected uprobe into refcounted one
 * (or no uprobe, if refcounting failed).
 *
 * *stable* pointer always point to the uprobe (or could be NULL if there is
 * was no valid underlying uprobe to begin with).
 *
 * *leased* pointer is the key to achieving race-free atomic lifetime state
 * transition and can have three possible states:
 *   - either the same non-NULL value as *stable*, in which case uprobe is
 *     SRCU-protected;
 *   - NULL, in which case uprobe (if there is any) is refcounted;
 *   - special __UPROBE_DEAD value, which represents an uprobe that was SRCU
 *     protected initially, but SRCU period timed out and we attempted to
 *     convert it to refcounted, but refcount_inc_not_zero() failed, because
 *     uprobe effectively went away (the last consumer unsubscribed). In this
 *     case it's important to know that *stable* pointer (which still has
 *     non-NULL uprobe pointer) shouldn't be used, because lifetime of
 *     underlying uprobe is not guaranteed anymore. __UPROBE_DEAD is just an
 *     internal marker and is handled transparently by hprobe_fetch() helper.
 *
 * When uprobe is SRCU-protected, we also record srcu_idx value, necessary for
 * SRCU unlocking.
 *
 * See hprobe_expire() and hprobe_fetch() for details of race-free uprobe
 * state transitioning details. It all hinges on atomic xchg() over *leaded*
 * pointer. *stable* pointer, once initially set, is not modified concurrently.
 */
struct hprobe {
	enum hprobe_state state;
	int srcu_idx;
	struct uprobe *uprobe;
};

/*
 * uprobe_task: Metadata of a task while it singlesteps.
 */
struct uprobe_task {
	enum uprobe_task_state		state;

	unsigned int			depth;
	struct return_instance		*return_instances;

	struct return_instance		*ri_pool;
	struct timer_list		ri_timer;
	seqcount_t			ri_seqcount;

Annotation

Implementation Notes