From d266460adce31eb21e878eee5c4f777dcb828a30 Mon Sep 17 00:00:00 2001 From: Alexander Aksenov Date: Tue, 8 Jul 2014 15:17:40 +0400 Subject: [PATCH] [STYLE] Uprobe: doxygen comments Change-Id: I1499884899563a9ba916e3681c5406632dd9eb97 Signed-off-by: Alexander Aksenov --- uprobe/arch/asm-arm/swap_uprobes.c | 95 +++++++++++++++++++-- uprobe/arch/asm-arm/swap_uprobes.h | 29 ++++--- uprobe/arch/asm-arm/trampoline_thumb.h | 18 ++-- uprobe/arch/asm-x86/swap_uprobes.c | 85 +++++++++++++++++-- uprobe/arch/asm-x86/swap_uprobes.h | 25 ++++-- uprobe/swap_uprobes.c | 151 +++++++++++++++++++++++++++++++-- uprobe/swap_uprobes.h | 105 ++++++++++++++--------- 7 files changed, 421 insertions(+), 87 deletions(-) diff --git a/uprobe/arch/asm-arm/swap_uprobes.c b/uprobe/arch/asm-arm/swap_uprobes.c index ebbd797..5413272 100644 --- a/uprobe/arch/asm-arm/swap_uprobes.c +++ b/uprobe/arch/asm-arm/swap_uprobes.c @@ -1,6 +1,11 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/uprobe/arch/asm-arm/swap_uprobes.h +/** + * uprobe/arch/asm-arm/swap_uprobes.c + * @author Alexey Gerenkov User-Space Probes initial + * implementation; Support x86/ARM/MIPS for both user and kernel spaces. + * @author Ekaterina Gorelkina : redesign module for + * separating core and arch parts + * + * @section LICENSE * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -16,12 +21,13 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * + * @section COPYRIGHT + * * Copyright (C) Samsung Electronics, 2006-2010 * - * 2008-2009 Alexey Gerenkov User-Space - * Probes initial implementation; Support x86/ARM/MIPS for both user and kernel spaces. - * 2010 Ekaterina Gorelkina : redesign module for separating core and arch parts + * @section DESCRIPTION * + * Arch-dependent uprobe interface implementation for ARM. */ #include @@ -37,7 +43,10 @@ // FIXME: #include - +/** + * @def flush_insns + * @brief Flushes instructions. + */ #define flush_insns(addr, size) \ flush_icache_range((unsigned long)(addr), \ (unsigned long)(addr) + (size)) @@ -530,6 +539,13 @@ static int arch_copy_trampoline_thumb_uprobe(struct uprobe *up) return 0; } +/** + * @brief Prepares uprobe for ARM. + * + * @param up Pointer to the uprobe. + * @return 0 on success,\n + * negative error code on error. + */ int arch_prepare_uprobe(struct uprobe *up) { struct kprobe *p = up2kp(up); @@ -568,6 +584,12 @@ int arch_prepare_uprobe(struct uprobe *up) return 0; } +/** + * @brief Analysis opcodes. + * + * @param rp Pointer to the uretprobe. + * @return Void. + */ void arch_opcode_analysis_uretprobe(struct uretprobe *rp) { /* Remove retprobe if first insn overwrites lr */ @@ -580,6 +602,13 @@ void arch_opcode_analysis_uretprobe(struct uretprobe *rp) ARM_INSN_MATCH(BLX2, rp->up.kp.opcode)); } +/** + * @brief Prepates uretprobe for ARM. + * + * @param ri Pointer to the uretprobe instance. + * @param regs Pointer to CPU register data. + * @return Void. + */ void arch_prepare_uretprobe(struct uretprobe_instance *ri, struct pt_regs *regs) { @@ -596,6 +625,14 @@ void arch_prepare_uretprobe(struct uretprobe_instance *ri, } } +/** + * @brief Disarms uretprobe instance. + * + * @param ri Pointer to the uretprobe instance + * @param task Pointer to the task for which the uretprobe instance + * @return 0 on success,\n + * negative error code on error. + */ int arch_disarm_urp_inst(struct uretprobe_instance *ri, struct task_struct *task) { @@ -675,6 +712,13 @@ check_lr: /* check lr anyway */ return retval; } +/** + * @brief Jump pre-handler. + * + * @param p Pointer to the kprobe. + * @param regs Pointer to CPU register data. + * @return 0. + */ int setjmp_upre_handler(struct kprobe *p, struct pt_regs *regs) { struct uprobe *up = container_of(p, struct uprobe, kp); @@ -698,6 +742,13 @@ int setjmp_upre_handler(struct kprobe *p, struct pt_regs *regs) return 0; } +/** + * @brief Gets trampoline address. + * + * @param p Pointer to the kprobe. + * @param regs Pointer to CPU register data. + * @return Trampoline address. + */ unsigned long arch_get_trampoline_addr(struct kprobe *p, struct pt_regs *regs) { return thumb_mode(regs) ? @@ -705,6 +756,13 @@ unsigned long arch_get_trampoline_addr(struct kprobe *p, struct pt_regs *regs) (unsigned long)(p->ainsn.insn + UPROBES_TRAMP_RET_BREAK_IDX); } +/** + * @brief Restores return address. + * + * @param orig_ret_addr Original return address. + * @param regs Pointer to CPU register data. + * @return Void. + */ void arch_set_orig_ret_addr(unsigned long orig_ret_addr, struct pt_regs *regs) { regs->ARM_lr = orig_ret_addr; @@ -716,6 +774,12 @@ void arch_set_orig_ret_addr(unsigned long orig_ret_addr, struct pt_regs *regs) regs->ARM_cpsr &= ~PSR_T_BIT; } +/** + * @brief Removes uprobe. + * + * @param up Pointer to the uprobe. + * @return Void. + */ void arch_remove_uprobe(struct uprobe *up) { swap_slot_free(up->sm, up->atramp.utramp); @@ -824,6 +888,13 @@ static int uprobe_handler(struct pt_regs *regs) return 0; } +/** + * @brief Breakpoint instruction handler. + * + * @param regs Pointer to CPU register data. + * @param instr Instruction. + * @return uprobe_handler results. + */ int uprobe_trap_handler(struct pt_regs *regs, unsigned int instr) { int ret; @@ -856,6 +927,11 @@ static struct undef_hook undef_hook_for_us_thumb = { .fn = uprobe_trap_handler }; +/** + * @brief Installs breakpoint hooks. + * + * @return 0. + */ int swap_arch_init_uprobes(void) { swap_register_undef_hook(&undef_hook_for_us_arm); @@ -864,6 +940,11 @@ int swap_arch_init_uprobes(void) return 0; } +/** + * @brief Uninstalls breakpoint hooks. + * + * @return Void. + */ void swap_arch_exit_uprobes(void) { swap_unregister_undef_hook(&undef_hook_for_us_thumb); diff --git a/uprobe/arch/asm-arm/swap_uprobes.h b/uprobe/arch/asm-arm/swap_uprobes.h index a89af74..4f87e84 100644 --- a/uprobe/arch/asm-arm/swap_uprobes.h +++ b/uprobe/arch/asm-arm/swap_uprobes.h @@ -1,6 +1,11 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/uprobe/arch/asm-arm/swap_uprobes.h +/** + * @file uprobe/arch/asm-arm/swap_uprobes.h + * @author Alexey Gerenkov User-Space Probes initial + * implementation; Support x86/ARM/MIPS for both user and kernel spaces. + * @author Ekaterina Gorelkina : redesign module for + * separating core and arch parts + * + * @section LICENSE * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -16,12 +21,13 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * + * @section COPYRIGHT + * * Copyright (C) Samsung Electronics, 2006-2010 * - * 2008-2009 Alexey Gerenkov User-Space - * Probes initial implementation; Support x86/ARM/MIPS for both user and kernel spaces. - * 2010 Ekaterina Gorelkina : redesign module for separating core and arch parts + * @section DESCRIPTION * + * Arch-dependent uprobe interface declaration. */ @@ -35,11 +41,14 @@ struct uprobe; struct uretprobe; struct uretprobe_instance; - +/** + * @struct arch_specific_tramp + * @brief Stores arch-dependent trampolines. + */ struct arch_specific_tramp { - unsigned long tramp_arm[UPROBES_TRAMP_LEN]; - unsigned long tramp_thumb[UPROBES_TRAMP_LEN]; - void *utramp; + unsigned long tramp_arm[UPROBES_TRAMP_LEN]; /**< ARM trampoline */ + unsigned long tramp_thumb[UPROBES_TRAMP_LEN]; /**< Thumb trampoline */ + void *utramp; /**< Pointer to trampoline */ }; diff --git a/uprobe/arch/asm-arm/trampoline_thumb.h b/uprobe/arch/asm-arm/trampoline_thumb.h index 9716f50..e406b80 100644 --- a/uprobe/arch/asm-arm/trampoline_thumb.h +++ b/uprobe/arch/asm-arm/trampoline_thumb.h @@ -1,6 +1,11 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/uprobe/arch/asm-arm/trampoline_thumb.h +/** + * @file uprobe/arch/asm-arm/trampoline_thumb.h + * @author Alexey Gerenkov User-Space Probes initial + * implementation; Support x86/ARM/MIPS for both user and kernel spaces. + * @author Ekaterina Gorelkina : redesign module for + * separating core and arch parts + * + * @section LICENSE * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -16,12 +21,13 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * + * @section COPYRIGHT + * * Copyright (C) Samsung Electronics, 2006-2010 * - * 2008-2009 Alexey Gerenkov User-Space - * Probes initial implementation; Support x86/ARM/MIPS for both user and kernel spaces. - * 2010 Ekaterina Gorelkina : redesign module for separating core and arch parts + * @section DESCRIPTION * + * Thumb trampolines. */ diff --git a/uprobe/arch/asm-x86/swap_uprobes.c b/uprobe/arch/asm-x86/swap_uprobes.c index 85a12aa..7e40594 100644 --- a/uprobe/arch/asm-x86/swap_uprobes.c +++ b/uprobe/arch/asm-x86/swap_uprobes.c @@ -1,6 +1,11 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/uprobe/arch/asm-x86/swap_uprobes.c +/** + * uprobe/arch/asm-x86/swap_uprobes.c + * @author Alexey Gerenkov User-Space Probes initial + * implementation; Support x86/ARM/MIPS for both user and kernel spaces. + * @author Ekaterina Gorelkina : redesign module for + * separating core and arch parts + * + * @section LICENSE * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -16,12 +21,13 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * + * @section COPYRIGHT + * * Copyright (C) Samsung Electronics, 2006-2010 * - * 2008-2009 Alexey Gerenkov User-Space - * Probes initial implementation; Support x86/ARM/MIPS for both user and kernel spaces. - * 2010 Ekaterina Gorelkina : redesign module for separating core and arch parts + * @section DESCRIPTION * + * Arch-dependent uprobe interface implementation for x86. */ #include @@ -29,9 +35,13 @@ #include #include +/** + * @struct uprobe_ctlblk + * @brief Uprobe control block + */ struct uprobe_ctlblk { - unsigned long flags; - struct kprobe *p; + unsigned long flags; /**< Flags */ + struct kprobe *p; /**< Pointer to the uprobe's kprobe */ }; static unsigned long trampoline_addr(struct uprobe *up) @@ -68,6 +78,13 @@ static void restore_current_flags(struct pt_regs *regs) regs->EREG(flags) |= __get_cpu_var(ucb).flags & IF_MASK; } +/** + * @brief Prepares uprobe for x86. + * + * @param up Pointer to the uprobe. + * @return 0 on success,\n + * -1 on error. + */ int arch_prepare_uprobe(struct uprobe *up) { int ret = 0; @@ -95,6 +112,13 @@ int arch_prepare_uprobe(struct uprobe *up) return ret; } +/** + * @brief Jump pre-handler. + * + * @param p Pointer to the uprobe's kprobe. + * @param regs Pointer to CPU register data. + * @return 0. + */ int setjmp_upre_handler(struct kprobe *p, struct pt_regs *regs) { struct uprobe *up = container_of(p, struct uprobe, kp); @@ -125,6 +149,13 @@ int setjmp_upre_handler(struct kprobe *p, struct pt_regs *regs) return 0; } +/** + * @brief Prepares uretprobe for x86. + * + * @param ri Pointer to the uretprobe instance. + * @param regs Pointer to CPU register data. + * @return Void. + */ void arch_prepare_uretprobe(struct uretprobe_instance *ri, struct pt_regs *regs) { /* Replace the return addr with trampoline addr */ @@ -138,6 +169,14 @@ void arch_prepare_uretprobe(struct uretprobe_instance *ri, struct pt_regs *regs) panic("failed to write user space func ra %lx!\n", regs->EREG(sp)); } +/** + * @brief Disarms uretprobe on x86 arch. + * + * @param ri Pointer to the uretprobe instance. + * @param task Pointer to the task for which the probe. + * @return 0 on success,\n + * negative error code on error. + */ int arch_disarm_urp_inst(struct uretprobe_instance *ri, struct task_struct *task) { @@ -170,16 +209,36 @@ int arch_disarm_urp_inst(struct uretprobe_instance *ri, return 0; } +/** + * @brief Gets trampoline address. + * + * @param p Pointer to the uprobe's kprobe. + * @param regs Pointer to CPU register data. + * @return Trampoline address. + */ unsigned long arch_get_trampoline_addr(struct kprobe *p, struct pt_regs *regs) { return trampoline_addr(kp2up(p)); } +/** + * @brief Restores return address. + * + * @param orig_ret_addr Original return address. + * @param regs Pointer to CPU register data. + * @return Void. + */ void arch_set_orig_ret_addr(unsigned long orig_ret_addr, struct pt_regs *regs) { regs->EREG(ip) = orig_ret_addr; } +/** + * @brief Removes uprobe. + * + * @param up Pointer to the target uprobe. + * @return Void. + */ void arch_remove_uprobe(struct uprobe *up) { struct kprobe *p = up2kp(up); @@ -415,11 +474,21 @@ static struct notifier_block uprobe_exceptions_nb = { .priority = INT_MAX }; +/** + * @brief Registers notify. + * + * @return register_die_notifier result. + */ int swap_arch_init_uprobes(void) { return register_die_notifier(&uprobe_exceptions_nb); } +/** + * @brief Unregisters notify. + * + * @return Void. + */ void swap_arch_exit_uprobes(void) { unregister_die_notifier(&uprobe_exceptions_nb); diff --git a/uprobe/arch/asm-x86/swap_uprobes.h b/uprobe/arch/asm-x86/swap_uprobes.h index a0ae4d4..9e1a586 100644 --- a/uprobe/arch/asm-x86/swap_uprobes.h +++ b/uprobe/arch/asm-x86/swap_uprobes.h @@ -1,6 +1,11 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/uprobe/arch/asm-x86/swap_uprobes.h +/** + * @file uprobe/arch/asm-x86/swap_uprobes.h + * @author Alexey Gerenkov User-Space Probes initial + * implementation; Support x86/ARM/MIPS for both user and kernel spaces. + * @author Ekaterina Gorelkina : redesign module for + * separating core and arch parts + * + * @section LICENSE * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -16,12 +21,13 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * + * @section COPYRIGHT + * * Copyright (C) Samsung Electronics, 2006-2010 * - * 2008-2009 Alexey Gerenkov User-Space - * Probes initial implementation; Support x86/ARM/MIPS for both user and kernel spaces. - * 2010 Ekaterina Gorelkina : redesign module for separating core and arch parts + * @section DESCRIPTION * + * Arch-dependent uprobe interface declaration. */ #ifndef _X86_SWAP_UPROBES_H @@ -32,9 +38,12 @@ struct uprobe; struct uretprobe; struct uretprobe_instance; - +/** + * @struct arch_specific_tramp + * @brief Stores x86 trampoline + */ struct arch_specific_tramp { - u8 tramp[UPROBES_TRAMP_LEN + BP_INSN_SIZE]; /* BP for uretprobe */ + u8 tramp[UPROBES_TRAMP_LEN + BP_INSN_SIZE]; /**< BP for uretprobe */ }; diff --git a/uprobe/swap_uprobes.c b/uprobe/swap_uprobes.c index 7a5e277..aba404b 100644 --- a/uprobe/swap_uprobes.c +++ b/uprobe/swap_uprobes.c @@ -1,6 +1,11 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/uprobe/swap_uprobes.h +/** + * uprobe/swap_uprobes.c + * @author Alexey Gerenkov User-Space Probes initial + * implementation; Support x86/ARM/MIPS for both user and kernel spaces. + * @author Ekaterina Gorelkina : redesign module for + * separating core and arch parts + * + * @section LICENSE * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -16,12 +21,13 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * + * @section COPYRIGHT + * * Copyright (C) Samsung Electronics, 2006-2010 * - * 2008-2009 Alexey Gerenkov User-Space - * Probes initial implementation; Support x86/ARM/MIPS for both user and kernel spaces. - * 2010 Ekaterina Gorelkina : redesign module for separating core and arch parts + * @section DESCRIPTION * + * Uprobes implementation. */ @@ -246,6 +252,13 @@ static void arm_uprobe(struct uprobe *p) } } +/** + * @brief Disarms uprobe. + * + * @param p Pointer to the uprobe's kprobe. + * @param task Pointer to the target task. + * @return Void. + */ void disarm_uprobe(struct kprobe *p, struct task_struct *task) { int ret = write_proc_vm_atomic(task, (unsigned long)p->addr, @@ -281,6 +294,14 @@ static void init_uretprobe_inst_table(void) } } +/** + * @brief Gets uprobe's kprobe. + * + * @param addr Probe's address. + * @param tgid Probes's thread group ID. + * @return Pointer to the kprobe on success,\n + * NULL otherwise. + */ struct kprobe *get_ukprobe(void *addr, pid_t tgid) { struct hlist_head *head; @@ -297,12 +318,27 @@ struct kprobe *get_ukprobe(void *addr, pid_t tgid) return NULL; } +/** + * @brief Adds uprobe to hlist when trampoline have been made. + * + * @param p Pointer to the uprobe's kprobe. + * @return Void. + */ void add_uprobe_table(struct kprobe *p) { INIT_HLIST_NODE(&p->is_hlist); hlist_add_head_rcu(&p->is_hlist, &uprobe_insn_slot_table[hash_ptr(p->ainsn.insn, UPROBE_HASH_BITS)]); } +/** + * @brief Gets kprobe by insn slot. + * + * @param addr Probe's address. + * @param tgit Probe's thread group ID. + * @param regs Pointer to CPU registers data. + * @return Pointer to the kprobe on success,\n + * NULL otherwise. + */ struct kprobe *get_ukprobe_by_insn_slot(void *addr, pid_t tgid, struct pt_regs *regs) { struct hlist_head *head; @@ -375,7 +411,14 @@ static struct uretprobe_instance *get_used_urp_inst(struct uretprobe *rp) return NULL; } -/* Called with uretprobe_lock held */ +/** + * @brief Gets free uretprobe instanse for the specified uretprobe without + * allocation. Called with uretprobe_lock held. + * + * @param rp Pointer to the uretprobe. + * @return Pointer to the uretprobe_instance on success,\n + * NULL otherwise. + */ struct uretprobe_instance *get_free_urp_inst_no_alloc(struct uretprobe *rp) { struct uretprobe_instance *ri; @@ -446,6 +489,13 @@ static struct uretprobe_instance *get_free_urp_inst(struct uretprobe *rp) } // =================================================================== +/** + * @brief Registers uprobe. + * + * @param up Pointer to the uprobe to register. + * @return 0 on success,\n + * negative error code on error. + */ int swap_register_uprobe(struct uprobe *up) { int ret = 0; @@ -506,6 +556,13 @@ out: return ret; } +/** + * @brief Unregisters uprobe. + * + * @param up Pointer to the uprobe. + * @param disarm Disarm flag. When true uprobe is disarmed. + * @return Void. + */ void __swap_unregister_uprobe(struct uprobe *up, int disarm) { struct kprobe *p, *old_p, *list_p; @@ -574,11 +631,25 @@ valid_p: } EXPORT_SYMBOL_GPL(__swap_unregister_uprobe); +/** + * @brief Unregisters uprobe. Main interface function, wrapper for + * __swap_unregister_uprobe. + * + * @param up Pointer to the uprobe. + * @return Void. + */ void swap_unregister_uprobe(struct uprobe *up) { __swap_unregister_uprobe(up, 1); } +/** + * @brief Registers ujprobe. + * + * @param uj Pointer to the ujprobe function. + * @return 0 on success,\n + * error code on error. + */ int swap_register_ujprobe(struct ujprobe *jp) { int ret = 0; @@ -593,6 +664,13 @@ int swap_register_ujprobe(struct ujprobe *jp) } EXPORT_SYMBOL_GPL(swap_register_ujprobe); +/** + * @brief Unregisters ujprobe. + * + * @param jp Pointer to the ujprobe. + * @param disarm Disarm flag, passed to __swap_unregister_uprobe. + * @return Void. + */ void __swap_unregister_ujprobe(struct ujprobe *jp, int disarm) { __swap_unregister_uprobe(&jp->up, disarm); @@ -609,12 +687,26 @@ void __swap_unregister_ujprobe(struct ujprobe *jp, int disarm) } EXPORT_SYMBOL_GPL(__swap_unregister_ujprobe); +/** + * @brief Unregisters ujprobe. Main interface function, wrapper for + * __swap_unregister_ujprobe. + * + * @param jp Pointer to the jprobe. + * @return Void. + */ void swap_unregister_ujprobe(struct ujprobe *jp) { __swap_unregister_ujprobe(jp, 1); } EXPORT_SYMBOL_GPL(swap_unregister_ujprobe); +/** + * @brief Trampoline uprobe handler. + * + * @param p Pointer to the uprobe's kprobe. + * @param regs Pointer to CPU register data. + * @return 1 + */ int trampoline_uprobe_handler(struct kprobe *p, struct pt_regs *regs) { struct uretprobe_instance *ri = NULL; @@ -713,6 +805,13 @@ static int pre_handler_uretprobe(struct kprobe *p, struct pt_regs *regs) return 0; } +/** + * @brief Registers uretprobe. + * + * @param rp Pointer to the uretprobe. + * @return 0 on success,\n + * negative error code on error. + */ int swap_register_uretprobe(struct uretprobe *rp) { int i, ret = 0; @@ -761,6 +860,13 @@ int swap_register_uretprobe(struct uretprobe *rp) } EXPORT_SYMBOL_GPL(swap_register_uretprobe); +/** + * @brief Disarms uretprobe instances for the specified child task. + * + * @param parent Pointer to the parent task struct. + * @param task Pointer to the child task struct. + * @return 0 + */ int swap_disarm_urp_inst_for_task(struct task_struct *parent, struct task_struct *task) { unsigned long flags; @@ -784,6 +890,12 @@ int swap_disarm_urp_inst_for_task(struct task_struct *parent, struct task_struct } EXPORT_SYMBOL_GPL(swap_disarm_urp_inst_for_task); +/** + * @brief Disarms uretprobes for specified task. + * + * @param task Pointer to the task_struct. + * @return Void. + */ void swap_discard_pending_uretprobes(struct task_struct *task) { unsigned long flags; @@ -809,6 +921,13 @@ void swap_discard_pending_uretprobes(struct task_struct *task) } EXPORT_SYMBOL_GPL(swap_discard_pending_uretprobes); +/** + * @brief Unregisters uretprobe. + * + * @param rp Pointer to the ureprobe. + * @param disarm Disarm flag, passed to __swap_unregister_uprobe + * @return Void. + */ void __swap_unregister_uretprobe(struct uretprobe *rp, int disarm) { unsigned long flags; @@ -843,12 +962,25 @@ void __swap_unregister_uretprobe(struct uretprobe *rp, int disarm) } EXPORT_SYMBOL_GPL(__swap_unregister_uretprobe); +/** + * @brief Unregistets uretprobe. Main interface function, wrapper for + * __swap_unregister_uretprobe. + * + * @param rp Pointer to the uretprobe. + * @return Void. + */ void swap_unregister_uretprobe(struct uretprobe *rp) { __swap_unregister_uretprobe(rp, 1); } EXPORT_SYMBOL_GPL(swap_unregister_uretprobe); +/** + * @brief Unregisters all uprobes for task's thread group ID. + * + * @param task Pointer to the task_struct + * @return Void. + */ void swap_unregister_all_uprobes(struct task_struct *task) { struct hlist_head *head; @@ -873,6 +1005,11 @@ void swap_unregister_all_uprobes(struct task_struct *task) } EXPORT_SYMBOL_GPL(swap_unregister_all_uprobes); +/** + * @brief Arch-independent wrapper for arch_ujprobe_return. + * + * @return Void. + */ void swap_ujprobe_return(void) { arch_ujprobe_return(); diff --git a/uprobe/swap_uprobes.h b/uprobe/swap_uprobes.h index bd83064..8d91b14 100644 --- a/uprobe/swap_uprobes.h +++ b/uprobe/swap_uprobes.h @@ -1,9 +1,11 @@ -#ifndef _SWAP_UPROBES_H -#define _SWAP_UPROBES_H - -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/uprobe/swap_uprobes.h +/** + * @file uprobe/swap_uprobes.h + * @author Alexey Gerenkov User-Space Probes initial + * implementation; Support x86/ARM/MIPS for both user and kernel spaces. + * @author Ekaterina Gorelkina : redesign module for + * separating core and arch parts + * + * @section LICENSE * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -19,75 +21,96 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * + * @section COPYRIGHT + * * Copyright (C) Samsung Electronics, 2006-2010 * - * 2008-2009 Alexey Gerenkov User-Space - * Probes initial implementation; Support x86/ARM/MIPS for both user and kernel spaces. - * 2010 Ekaterina Gorelkina : redesign module for separating core and arch parts + * @section DESCRIPTION * + * Uprobes interface declaration. */ +#ifndef _SWAP_UPROBES_H +#define _SWAP_UPROBES_H + + #include #include - +/** + * @struct uprobe + * @brief Stores uprobe data, based on kprobe. + */ struct uprobe { - struct kprobe kp; - struct task_struct *task; - struct slot_manager *sm; - struct arch_specific_tramp atramp; + struct kprobe kp; /**< Kprobe for this uprobe */ + struct task_struct *task; /**< Pointer to the task struct */ + struct slot_manager *sm; /**< Pointer to slot manager */ + struct arch_specific_tramp atramp; /**< Stores trampoline */ }; +/** + * @brief Uprobe pre-entry handler. + */ typedef unsigned long (*uprobe_pre_entry_handler_t)(void *priv_arg, struct pt_regs * regs); +/** + * @struct ujprobe + * @brief Stores ujprobe data, based on uprobe. + */ struct ujprobe { - struct uprobe up; - /* probe handling code to jump to */ - void *entry; - // handler whichw willb bec called before 'entry' + struct uprobe up; /**< Uprobe for this ujprobe */ + void *entry; /**< Probe handling code to jump to */ + /** Handler which will be called before 'entry' */ uprobe_pre_entry_handler_t pre_entry; - void *priv_arg; - char *args; + void *priv_arg; /**< Private args for handler */ + char *args; /**< Function args format string */ }; struct uretprobe_instance; +/** + * @brief Uretprobe handler. + */ typedef int (*uretprobe_handler_t)(struct uretprobe_instance *, struct pt_regs *); -/* - * Function-return probe - +/** + * @strict uretprobe + * @brief Function-return probe. + * * Note: * User needs to provide a handler function, and initialize maxactive. - * maxactive - The maximum number of instances of the probed function that - * can be active concurrently. - * nmissed - tracks the number of times the probed function's return was - * ignored, due to maxactive being too low. - * */ struct uretprobe { - struct uprobe up; - uretprobe_handler_t handler; - uretprobe_handler_t entry_handler; + struct uprobe up; /**< Uprobe for this uretprobe */ + uretprobe_handler_t handler; /**< Uretprobe handler */ + uretprobe_handler_t entry_handler; /**< Uretprobe entry handler */ + /** Maximum number of instances of the probed function that can be + * active concurrently. */ int maxactive; + /** Tracks the number of times the probed function's return was + * ignored, due to maxactive being too low. */ int nmissed; - struct hlist_head free_instances; - struct hlist_head used_instances; + struct hlist_head free_instances; /**< Free instances list */ + struct hlist_head used_instances; /**< Used instances list */ #ifdef CONFIG_ARM - /* probe with noreturn (bl,blx) */ - unsigned arm_noret:1; - unsigned thumb_noret:1; + unsigned arm_noret:1; /**< No-return flag for ARM */ + unsigned thumb_noret:1; /**< No-return flag for Thumb */ #endif }; +/** + * @struct uretprobe_instance + * @brief Structure for each uretprobe instance. + */ struct uretprobe_instance { /* either on free list or used list */ - struct hlist_node uflist; - struct hlist_node hlist; - struct uretprobe *rp; - kprobe_opcode_t *ret_addr; - kprobe_opcode_t *sp; - struct task_struct *task; + struct hlist_node uflist; /**< Free list */ + struct hlist_node hlist; /**< Used list */ + struct uretprobe *rp; /**< Pointer to the parent uretprobe */ + kprobe_opcode_t *ret_addr; /**< Return address */ + kprobe_opcode_t *sp; /**< Pointer to stack */ + struct task_struct *task; /**< Pointer to the task struct */ }; int swap_register_uprobe(struct uprobe *p); -- 2.7.4