From: Alexander Aksenov Date: Mon, 7 Jul 2014 14:04:14 +0000 (+0400) Subject: [STYLE] Writer: doxygen comments X-Git-Tag: Tizen_SDK_2.3~32 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F50%2F24250%2F3;p=kernel%2Fswap-modules.git [STYLE] Writer: doxygen comments Change-Id: Iac94937fdddb44b62df99bdd81553a025426edc4 Signed-off-by: Alexander Aksenov --- diff --git a/writer/debugfs_writer.c b/writer/debugfs_writer.c index 7be639b..a09cd37 100644 --- a/writer/debugfs_writer.c +++ b/writer/debugfs_writer.c @@ -1,6 +1,8 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * writer/debugfs_writer.c +/** + * writer/debugfs_writer.c + * @author Vyacheslav Cherkashin + * + * @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,10 +18,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, 2013 * - * 2013 Vyacheslav Cherkashin + * @section DESCRIPTION * + * Writer debugfs implementation. */ @@ -225,6 +230,11 @@ static const struct file_operations fops_filter = { */ static struct dentry *writer_dir = NULL; +/** + * @brief Removes writer debugfs. + * + * @return Void. + */ void exit_debugfs_writer(void) { if (writer_dir) @@ -235,6 +245,11 @@ void exit_debugfs_writer(void) exit_buffer(); } +/** + * @brief Initializes writer debugfs. + * + * @return 0 on success, error code on error. + */ int init_debugfs_writer(void) { int ret; diff --git a/writer/debugfs_writer.h b/writer/debugfs_writer.h index 60a8205..d5e1fc3 100644 --- a/writer/debugfs_writer.h +++ b/writer/debugfs_writer.h @@ -1,9 +1,8 @@ -#ifndef _DEBUGFS_WRITER_H -#define _DEBUGFS_WRITER_H - -/* - * Dynamic Binary Instrumentation Module based on KProbes - * writer/debugfs_writer.h +/** + * @file writer/debugfs_writer.h + * @author Vyacheslav Cherkashin + * + * @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,12 +18,18 @@ * 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, 2013 * - * 2013 Vyacheslav Cherkashin + * @section DESCRIPTION * + * Writer debugfs interface declaration. */ +#ifndef _DEBUGFS_WRITER_H +#define _DEBUGFS_WRITER_H + int init_debugfs_writer(void); void exit_debugfs_writer(void); diff --git a/writer/event_filter.c b/writer/event_filter.c index fdddd51..669fc61 100644 --- a/writer/event_filter.c +++ b/writer/event_filter.c @@ -1,6 +1,8 @@ -/* - * SWAP kernel features - * writer/event_filter.c +/** + * writer/event_filter.c + * @author Vyacheslav Cherkashin + * + * @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,10 +18,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, 2013 * - * 2013 Vyacheslav Cherkashin + * @section DESCRIPTION * + * Events filter. */ @@ -59,6 +64,12 @@ static struct ev_filter *event_filter_find(const char *name) return NULL; } +/** + * @brief Registers event filter. + * + * @param f Pointer to the event filter. + * @return 0 on success, error code on error. + */ int event_filter_register(struct ev_filter *f) { if (event_filter_find(f->name)) @@ -71,6 +82,12 @@ int event_filter_register(struct ev_filter *f) } EXPORT_SYMBOL_GPL(event_filter_register); +/** + * @brief Unregisters event filter. + * + * @param f Pointer to the event filter. + * @return Void. + */ void event_filter_unregister(struct ev_filter *f) { struct ev_filter *filter, *tmp; @@ -87,6 +104,12 @@ void event_filter_unregister(struct ev_filter *f) } EXPORT_SYMBOL_GPL(event_filter_unregister); +/** + * @brief Sets event filter by its name. + * + * @param name Filter name. + * @return 0 on success, error code on error. + */ int event_filter_set(const char *name) { struct ev_filter *f; @@ -101,11 +124,23 @@ int event_filter_set(const char *name) } EXPORT_SYMBOL_GPL(event_filter_set); +/** + * @brief Gets filter name. + * + * @return Pointer to the filter name string. + */ const char *event_filter_get(void) { return filter_current->name; } +/** + * @brief Runs specified callback for each filter in list. + * + * @param func Specified callback. + * @param data Pointer to the data passed to the callback. + * @return Void. + */ void event_filter_on_each(void (*func)(struct ev_filter *, void *), void *data) { @@ -115,11 +150,21 @@ void event_filter_on_each(void (*func)(struct ev_filter *, void *), func(f, data); } +/** + * @brief Initializes event filter. + * + * @return Initialization result. + */ int event_filter_init(void) { return event_filter_register(&filter_none); } +/** + * @brief Uninitializes event filter. + * + * @return Void. + */ void event_filter_exit(void) { event_filter_unregister(&filter_none);; diff --git a/writer/event_filter.h b/writer/event_filter.h index 3adcaae..1b420eb 100644 --- a/writer/event_filter.h +++ b/writer/event_filter.h @@ -1,9 +1,8 @@ -#ifndef _EVENT_FILTER_H -#define _EVENT_FILTER_H - -/* - * SWAP kernel features - * writer/event_filter.h +/** + * @file writer/event_filter.h + * @author Vyacheslav Cherkashin + * + * @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,21 +18,32 @@ * 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, 2013 * - * 2013 Vyacheslav Cherkashin + * @section DESCRIPTION * + * Event filter interface declaration. */ +#ifndef _EVENT_FILTER_H +#define _EVENT_FILTER_H + + #include struct task_struct; +/** + * @struct ev_filter + * @bref Event filter structure. + */ struct ev_filter { - struct list_head list; - char *name; - int (*filter)(struct task_struct *); + struct list_head list; /**< Filter list head. */ + char *name; /**< Filter name. */ + int (*filter)(struct task_struct *); /**< Filter function. */ }; diff --git a/writer/kernel_operations.h b/writer/kernel_operations.h index 8d6b718..2610507 100644 --- a/writer/kernel_operations.h +++ b/writer/kernel_operations.h @@ -1,6 +1,8 @@ -/* - * SWAP Writer Module - * modules/writer/kernel_operations.h +/** + * @file writer/kernel_operations.h + * @author Alexander Aksenov + * + * @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,10 +18,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, 2013 * - * 2013 Alexander Aksenov : SWAP Writer implementation + * @section DESCRIPTION * + * Writer kernel operations. */ /* Kernel functions wrap */ @@ -32,14 +37,19 @@ /* MESSAGES */ +/** Prints debug message.*/ #define print_debug(msg, args...) \ printk(KERN_DEBUG "SWAP_WRITER DEBUG : " msg, ##args) +/** Prints info message.*/ #define print_msg(msg, args...) \ printk(KERN_INFO "SWAP_WRITER : " msg, ##args) +/** Prints warning message.*/ #define print_warn(msg, args...) \ printk(KERN_WARNING "SWAP_WRITER WARNING : " msg, ##args) +/** Prints error message.*/ #define print_err(msg, args...) \ printk(KERN_ERR "SWAP_WRITER ERROR : " msg, ##args) +/** Prints critical error message.*/ #define print_crit(msg, args...) \ printk(KERN_CRIT "SWAP_WRITER CRITICAL : " msg, ##args) @@ -49,16 +59,16 @@ /* Regs manipulations */ #if defined(CONFIG_ARM) -#define get_regs_ip(regs) regs->ARM_pc -#define get_regs_ret_func(regs) regs->ARM_lr -#define get_regs_ret_val(regs) regs->ARM_r0 -#define get_regs_stack_ptr(regs) regs->ARM_sp +#define get_regs_ip(regs) regs->ARM_pc /**< Get pc reg. */ +#define get_regs_ret_func(regs) regs->ARM_lr /**< Get lr reg. */ +#define get_regs_ret_val(regs) regs->ARM_r0 /**< Get ret val. */ +#define get_regs_stack_ptr(regs) regs->ARM_sp /**< Get stack pointer. */ #elif defined(CONFIG_X86_32) -#define get_regs_ip(regs) regs->ip - 1 -#define get_regs_ret_val(regs) regs->ax -#define get_regs_stack_ptr(regs) regs->sp +#define get_regs_ip(regs) regs->ip - 1 /**< Get ip. */ +#define get_regs_ret_val(regs) regs->ax /**< Get ret val. */ +#define get_regs_stack_ptr(regs) regs->sp /**< Get stack pointer. */ static inline u32 get_regs_ret_func(struct pt_regs *regs) { diff --git a/writer/kernel_operations_arm.c b/writer/kernel_operations_arm.c index 460a563..dfdc5dd 100644 --- a/writer/kernel_operations_arm.c +++ b/writer/kernel_operations_arm.c @@ -1,6 +1,8 @@ -/* - * SWAP Writer - * modules/writer/kernel_operations_arm.c +/** + * writer/kernel_operations_arm.c + * @author Alexander Aksenov + * + * @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,11 +18,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, 2013 * - * 2013 Alexander Aksenov : SWAP Writer module kernel - * operaions implement + * @section DESCRIPTION * + * ARM arch-dependent operations. */ #include @@ -35,6 +39,14 @@ /* ======================= ARGS ========================== */ +/** + * @brief Returns arg values. + * + * @param[out] args Pointer to array where argument values should be stored/ + * @param cnt Arguments count. + * @param regs Pointer to register data. + * @return 0. + */ int get_args(unsigned long args[], int cnt, struct pt_regs *regs) { /* All args, except first 4, are passed on the stack */ @@ -76,6 +88,16 @@ int get_args(unsigned long args[], int cnt, struct pt_regs *regs) * end = start + PAGE_SIZE * */ +/** + * @brief Gets shared kernel memory addresses. + * + * @param mm Pointer to process mm_struct. + * @param[out] start Pointer to the variable where the first shared mem + * address should be put. + * @param[out] end Pointer to the variable where the last shared mem + * address should be put. + * @return Pointer to the string with shared mem area name. + */ const char *get_shared_kmem(struct mm_struct *mm, unsigned long *start, unsigned long *end) { diff --git a/writer/kernel_operations_x86.c b/writer/kernel_operations_x86.c index c830af0..78ac1ae 100644 --- a/writer/kernel_operations_x86.c +++ b/writer/kernel_operations_x86.c @@ -1,6 +1,8 @@ -/* - * SWAP Writer - * modules/writer/kernel_operations_x86.c +/** + * writer/kernel_operations_x86.c + * @author Alexander Aksenov + * + * @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,11 +18,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, 2013 * - * 2013 Alexander Aksenov : SWAP Writer module kernel - * operaions implement + * @section DESCRIPTION * + * X86 arch-dependent operations. */ #include @@ -35,6 +39,14 @@ /* ======================= ARGS ========================== */ +/** + * @brief Returns arg values. + * + * @param[out] args Pointer to array where argument values should be stored/ + * @param cnt Arguments count. + * @param regs Pointer to register data. + * @return 0. + */ int get_args(unsigned long args[], int cnt, struct pt_regs *regs) { int i, stack_args = 0; @@ -78,6 +90,16 @@ int get_args(unsigned long args[], int cnt, struct pt_regs *regs) /* ================== KERNEL SHARED MEM ===================== */ +/** + * @brief Gets shared kernel memory addresses. + * + * @param mm Pointer to process mm_struct. + * @param[out] start Pointer to the variable where the first shared mem + * address should be put. + * @param[out] end Pointer to the variable where the last shared mem + * address should be put. + * @return Pointer to the string with shared mem area name. + */ const char *get_shared_kmem(struct mm_struct *mm, unsigned long *start, unsigned long *end) { diff --git a/writer/swap_writer_errors.h b/writer/swap_writer_errors.h index 6cb946a..def1f47 100644 --- a/writer/swap_writer_errors.h +++ b/writer/swap_writer_errors.h @@ -1,6 +1,8 @@ -/* - * SWAP Writer - * modules/writer/swap_writer_errors.h +/** + * @file writer/swap_writer_errors.h + * @author Alexander Aksenov + * + * @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,18 +18,24 @@ * 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, 2013 * - * 2013 Alexander Aksenov : SWAP Writer module kernel - * operaions implement + * @section DESCRIPTION * + * Writer module error codes. */ #ifndef __SWAP_WRITER_ERRORS_H__ #define __SWAP_WRITER_ERRORS_H__ +/** + * @enum _swap_writer_errors + * Error codes. + */ enum _swap_writer_errors { - E_SW_SUCCESS = 0 /* Success */ + E_SW_SUCCESS = 0 /**< Success. */ }; #endif /* __SWAP_WRITER_ERRORS_H__ */ diff --git a/writer/swap_writer_module.c b/writer/swap_writer_module.c index 03f8bfc..cca749c 100644 --- a/writer/swap_writer_module.c +++ b/writer/swap_writer_module.c @@ -1,6 +1,9 @@ -/* - * SWAP Writer - * modules/writer/swap_writer_module.c +/** + * writer/swap_writer_module.c + * @author Alexander Aksenov + * @author Vyacheslav Cherkashin + * + * @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,11 +19,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, 2013 * - * 2013 Alexander Aksenov , Vyacheslav Cherkashin: - * SWAP Writer module implement + * @section DESCRIPTION * + * Packing and writing data. */ #include @@ -48,24 +53,34 @@ #include "event_filter.h" +/** + * @enum MSG_ID + * @brief Supported message IDs. + */ enum MSG_ID { - MSG_PROC_INFO = 0x0001, - MSG_TERMINATE = 0x0002, - MSG_ERROR = 0x0003, - MSG_SAMPLE = 0x0004, - MSG_FUNCTION_ENTRY = 0x0008, - MSG_FUNCTION_EXIT = 0x0009, - MSG_CONTEXT_SWITCH_ENTRY = 0x0010, - MSG_CONTEXT_SWITCH_EXIT = 0x0011, - MSG_PROC_MAP = 0x0012, - MSG_PROC_UNMAP = 0x0013, - MSG_PROC_COMM = 0x0014 + MSG_PROC_INFO = 0x0001, /**< Process info */ + MSG_TERMINATE = 0x0002, /**< Terminate */ + MSG_ERROR = 0x0003, /**< Error */ + MSG_SAMPLE = 0x0004, /**< Sampler event */ + MSG_FUNCTION_ENTRY = 0x0008, /**< Function entry */ + MSG_FUNCTION_EXIT = 0x0009, /**< Function return */ + MSG_CONTEXT_SWITCH_ENTRY = 0x0010, /**< Context switch entry */ + MSG_CONTEXT_SWITCH_EXIT = 0x0011, /**< Context switch exit */ + MSG_PROC_MAP = 0x0012, /**< Process map */ + MSG_PROC_UNMAP = 0x0013, /**< Process unmap */ + MSG_PROC_COMM = 0x0014 /**< Process comm */ }; static char *cpu_buf[NR_CPUS]; static u32 seq_num = 0; static unsigned int discarded = 0; +/** + * @brief Initializes new message. + * + * @param buf_size Message buffer size. + * @return Success. + */ int init_msg(size_t buf_size) { int i; @@ -77,6 +92,11 @@ int init_msg(size_t buf_size) } EXPORT_SYMBOL_GPL(init_msg); +/** + * @brief Uninitializes message. + * + * @return Void. + */ void uninit_msg(void) { int i; @@ -86,18 +106,33 @@ void uninit_msg(void) } EXPORT_SYMBOL_GPL(uninit_msg); +/** + * @brief Sets discarded events count to 0. + * + * @return Void. + */ void reset_discarded(void) { discarded = 0; } EXPORT_SYMBOL_GPL(reset_discarded); +/** + * @brief Sets events sequence number to 0. + * + * @return Void. + */ void reset_seq_num(void) { seq_num = 0; } EXPORT_SYMBOL_GPL(reset_seq_num); +/** + * @brief Gets discarded events count. + * + * @return Discarded events count. + */ unsigned int get_discarded_count(void) { return discarded; @@ -124,12 +159,16 @@ static inline u64 timespec2time(struct timespec *ts) * ============================================================================ */ +/** + * @struct basic_msg_fmt + * @brief Basic message. + */ struct basic_msg_fmt { - u32 msg_id; - u32 seq_number; - u64 time; - u32 len; - char payload[0]; + u32 msg_id; /**< Message ID */ + u32 seq_number; /**< Sequence number */ + u64 time; /**< Message time */ + u32 len; /**< Message length */ + char payload[0]; /**< Message itself */ } __attribute__((packed)); #if 0 /* debug */ @@ -197,29 +236,45 @@ static char* pack_basic_msg_fmt(char *buf, enum MSG_ID id) * ============================================================================ */ +/** + * @struct proc_info_top + * @brief Top proc info part. + */ struct proc_info_top { - u32 pid; - char comm[0]; + u32 pid; /**< Process PID */ + char comm[0]; /**< Message */ } __attribute__((packed)); +/** + * @struct proc_info_bottom + * @brief Bottom proc info part. + */ struct proc_info_bottom { - u32 ppid; - u32 start_sec; - u32 start_nsec; - u64 low_addr; - u64 high_addr; - char bin_path[0]; + u32 ppid; /**< Parent PID */ + u32 start_sec; /**< Start time sec */ + u32 start_nsec; /**< Start time nsec */ + u64 low_addr; /**< Low address */ + u64 high_addr; /**< High address */ + char bin_path[0]; /**< Binary path */ } __attribute__((packed)); +/** + * @struct proc_info_part + * @brief Process info part. + */ struct proc_info_part { - u32 lib_cnt; - char libs[0]; + u32 lib_cnt; /**< Library count */ + char libs[0]; /**< Libraries */ } __attribute__((packed)); +/** + * @struct lib_obj + * @brief Library object. + */ struct lib_obj { - u64 low_addr; - u64 high_addr; - char lib_path[0]; + u64 low_addr; /**< Low library address */ + u64 high_addr; /**< High library address */ + char lib_path[0]; /**< Library path */ } __attribute__((packed)); static char *pack_path(char *buf, struct file *file) @@ -383,7 +438,14 @@ static char *pack_proc_info(char *payload, struct task_struct *task, return pack_proc_info_bottom(payload, task, dentry); } -/* called with down\up\_read(&task->mm->mmap_sem) */ +/** + * @brief Packs and writes process info message. Called with + * down\up\_read(&task->mm->mmap_sem). + * + * @param task Pointer to the target task_struct. + * @param dentry Pointer to the task dentry. + * @return Written data size on success, negative error code on error. + */ int proc_info_msg(struct task_struct *task, struct dentry *dentry) { char *buf, *payload, *buf_end; @@ -411,8 +473,12 @@ EXPORT_SYMBOL_GPL(proc_info_msg); * ============================================================================ */ +/** + * @struct proc_terminate + * @brief Terminate message struct. + */ struct proc_terminate { - u32 pid; + u32 pid; /**< Process ID */ } __attribute__((packed)); static char *pack_proc_terminate(char *payload, struct task_struct *task) @@ -423,6 +489,12 @@ static char *pack_proc_terminate(char *payload, struct task_struct *task) return payload + sizeof(*pt); } +/** + * @brief Packs and writes terminate message. + * + * @param task Target task_struct. + * @return Void. + */ void terminate_msg(struct task_struct *task) { char *buf, *payload, *buf_end; @@ -446,11 +518,16 @@ EXPORT_SYMBOL_GPL(terminate_msg); * = PROCESS MAP = * ============================================================================ */ + +/** + * @struct proc_map + * @brief Process mapping info. + */ struct proc_map { - u32 pid; - u64 low_addr; - u64 high_addr; - char bin_path[0]; + u32 pid; /**< Process ID */ + u64 low_addr; /**< Low address */ + u64 high_addr; /**< High address */ + char bin_path[0]; /**< Binary path */ } __attribute__((packed)); static char *pack_proc_map(char *payload, struct vm_area_struct *vma) @@ -464,6 +541,12 @@ static char *pack_proc_map(char *payload, struct vm_area_struct *vma) return pack_path(pm->bin_path, vma->vm_file); } +/** + * @brief Packs and writes process map message. + * + * @param vma Target memory area. + * @return Void. + */ void pcoc_map_msg(struct vm_area_struct *vma) { char *buf, *payload, *buf_end; @@ -487,10 +570,15 @@ EXPORT_SYMBOL_GPL(pcoc_map_msg); * = PROCESS UNMAP = * ============================================================================ */ + +/** + * @struct proc_unmap + * @brief Process mapping info. + */ struct proc_unmap { - u32 pid; - u64 low_addr; - u64 high_addr; + u32 pid; /**< Process ID */ + u64 low_addr; /**< Low address */ + u64 high_addr; /**< High address */ } __attribute__((packed)); static char *pack_proc_unmap(char *payload, unsigned long start, @@ -505,6 +593,13 @@ static char *pack_proc_unmap(char *payload, unsigned long start, return payload + sizeof(*pum); } +/** + * @brief Packs and writes process unmap message. + * + * @param start Unmapping area low address. + * @param end Unmapping area high address. + * @return Void. + */ void proc_unmap_msg(unsigned long start, unsigned long end) { char *buf, *payload, *buf_end; @@ -528,9 +623,14 @@ EXPORT_SYMBOL_GPL(proc_unmap_msg); * = PROCESS COMM = * ============================================================================ */ + +/** + * @struct proc_comm + * @brief Comm message info. + */ struct proc_comm { - u32 pid; - char comm[0]; + u32 pid; /**< Process ID */ + char comm[0]; /**< Comm */ } __attribute__((packed)); static char *pack_proc_comm(char *data, struct task_struct *task) @@ -542,6 +642,12 @@ static char *pack_proc_comm(char *data, struct task_struct *task) return pack_comm(pcomm->comm, task); } +/** + * @brief Packs and writes process comm message. + * + * @param task Target task_struct. + * @return Void. + */ void proc_comm_msg(struct task_struct *task) { char *buf, *payload, *buf_end; @@ -566,11 +672,15 @@ EXPORT_SYMBOL_GPL(proc_comm_msg); * ============================================================================ */ +/** + * @struct sample + * @brief Sampler event info. + */ struct sample { - u32 pid; - u64 pc_addr; - u32 tid; - u32 cpu_num; + u32 pid; /**< Process ID */ + u64 pc_addr; /**< Instruction pointer address */ + u32 tid; /**< Thread ID */ + u32 cpu_num; /**< CPU number */ } __attribute__((packed)); static char *pack_sample(char *payload, struct pt_regs *regs) @@ -586,6 +696,12 @@ static char *pack_sample(char *payload, struct pt_regs *regs) return payload + sizeof(*s); } +/** + * @brief Packs and writes sample message. + * + * @param regs Pointer to CPU register data. + * @return Written data size on success, negative error code on error. + */ int sample_msg(struct pt_regs *regs) { char *buf, *payload, *buf_end; @@ -615,16 +731,20 @@ EXPORT_SYMBOL_GPL(sample_msg); * ============================================================================ */ +/** + * @struct msg_func_entry + * @brief Entry event info. + */ struct msg_func_entry { - u64 pc_addr; - u64 caller_pc_addr; - u16 probe_type; - u16 probe_sub_type; - u32 pid; - u32 tid; - u32 cpu_num; - u32 cnt_args; - char args[0]; + u64 pc_addr; /**< Instruction pointer address. */ + u64 caller_pc_addr; /**< Return address */ + u16 probe_type; /**< Probe type */ + u16 probe_sub_type; /**< Probe subtype */ + u32 pid; /**< Process ID */ + u32 tid; /**< Thread ID */ + u32 cpu_num; /**< CPU number */ + u32 cnt_args; /**< Count of args */ + char args[0]; /**< Args format string */ } __attribute__((packed)); static char *pack_msg_func_entry(char *payload, const char *fmt, @@ -740,6 +860,16 @@ static int pack_args(char *buf, int len, const char *fmt, struct pt_regs *regs) return buf - buf_old; } +/** + * @brief Packs and writes entry event message. + * + * @param fmt Arguments format string. + * @param func_addr Function address. + * @param regs CPU register data. + * @param pt Probe type. + * @param sub_type Probe sub type. + * @return Written data size on success, negative error code on error. + */ int entry_event(const char *fmt, unsigned long func_addr, struct pt_regs *regs, enum PROBE_TYPE pt, int sub_type) { @@ -783,13 +913,17 @@ EXPORT_SYMBOL_GPL(entry_event); * ============================================================================ */ +/** + * @struct msg_func_exit + * @brief Exit event message info. + */ struct msg_func_exit { - u32 pid; - u32 tid; - u64 pc_addr; - u64 caller_pc_addr; - u32 cpu_num; - char ret_val[0]; + u32 pid; /**< PID */ + u32 tid; /**< TID */ + u64 pc_addr; /**< Instruction pointer */ + u64 caller_pc_addr; /**< Return address */ + u32 cpu_num; /**< CPU number */ + char ret_val[0]; /**< Return value */ } __attribute__((packed)); static int pack_msg_ret_val(char *buf, int len, char ret_type, @@ -897,6 +1031,15 @@ static int pack_msg_func_exit(char *buf, int len, char ret_type, return sizeof(*mfe) + ret; } +/** + * @brief Packs and writes exit event. + * + * @param ret_type Return value type. + * @param regs CPU register data. + * @param func_addr Function address. + * @param ret_addr Return address. + * @return Written data size on success, negative error code on error. + */ int exit_event(char ret_type, struct pt_regs *regs, unsigned long func_addr, unsigned long ret_addr) { @@ -935,11 +1078,15 @@ EXPORT_SYMBOL_GPL(exit_event); * ============================================================================ */ +/* + * @struct msg_context_switch + * @brief Context switch message info. + */ struct msg_context_switch { - u64 pc_addr; - u32 pid; - u32 tid; - u32 cpu_num; + u64 pc_addr; /**< Instruction pointer */ + u32 pid; /**< PID */ + u32 tid; /**< TID */ + u32 cpu_num; /**< CPU number */ } __attribute__((packed)); static char *pack_msg_context_switch(char *payload, struct pt_regs *regs) @@ -971,6 +1118,12 @@ static int context_switch(struct pt_regs *regs, enum MSG_ID id) return ret; } +/** + * @brief Packs and writes context switch entry message. + * + * @param regs CPU register data. + * @return Written data size on success, negative error code on error. + */ int switch_entry(struct pt_regs *regs) { if (!check_event(current)) @@ -980,6 +1133,12 @@ int switch_entry(struct pt_regs *regs) } EXPORT_SYMBOL_GPL(switch_entry); +/** + * @brief Packs and writes context switch exit message. + * + * @param regs CPU register data. + * @return Written data size on success, negative error code on error. + */ int switch_exit(struct pt_regs *regs) { if (!check_event(current)) @@ -997,8 +1156,12 @@ EXPORT_SYMBOL_GPL(switch_exit); * ============================================================================ */ +/** + * @struct msg_err + * @brief Error message info. + */ struct msg_err { - char msg[0]; + char msg[0]; /**< Error message string */ } __attribute__((packed)); static char *pack_msg_err(char *payload, const char *fmt, va_list args) @@ -1013,6 +1176,12 @@ static char *pack_msg_err(char *payload, const char *fmt, va_list args) return payload + sizeof(*me) + ret + 1; } +/** + * @brief Packs and writes error message. + * + * @param fmt Error string format + * @return Written data size on success, negative error code on error. + */ int error_msg(const char *fmt, ...) { char *buf, *payload, *buf_end; @@ -1044,6 +1213,13 @@ EXPORT_SYMBOL_GPL(error_msg); * ============================================================================ */ +/** + * @brief Interface for writing messages from user space directly. + * + * @param buf Pointer to message. + * @param len Message len. + * @return len + */ int raw_msg(char *buf, size_t len) { struct basic_msg_fmt *bmf = (struct basic_msg_fmt *)buf; @@ -1208,6 +1384,16 @@ static int pack_custom_event(char *buf, int len, const char *fmt, va_list args) enum { max_custom_event_size = 2048 }; +/** + * @brief Packs and writes custom entry event. + * + * @param func_addr Function address. + * @param regs CPU register data. + * @param type Probe type. + * @param sub_type Probe sub type. + * @param fmt Format string. + * @return Written data size on success, negative error code on error. + */ int custom_entry_event(unsigned long func_addr, struct pt_regs *regs, int type, int sub_type, const char *fmt, ...) { @@ -1240,6 +1426,16 @@ EXPORT_SYMBOL_GPL(custom_entry_event); /* TODO currently this function is a simple wrapper. it will be refactored when * protocol changes are applied */ + +/** + * @brief Packs and writes custom exit event. + * + * @param func_addr Function address. + * @param ret_addr Return address. + * @param regs CPU register data. + * @param fmt Format string. + * @return Written data size on success, negative error code on error. + */ int custom_exit_event(unsigned long func_addr, unsigned long ret_addr, struct pt_regs *regs, const char *fmt, ...) { diff --git a/writer/swap_writer_module.h b/writer/swap_writer_module.h index 2327c6c..74a34c0 100644 --- a/writer/swap_writer_module.h +++ b/writer/swap_writer_module.h @@ -1,6 +1,9 @@ -/* - * SWAP Writer - * modules/writer/swap_writer_module.h +/** + * @file writer/swap_writer_module.h + * @author Alexander Aksenov + * @author Vyacheslav Cherkashin + * + * @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,11 +19,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, 2013 * - * 2013 Alexander Aksenov , Vyacheslav Cherkashin: - * SWAP Writer module implement + * @section DESCRIPTION * + * Write module interface defenition. */ #ifndef _SWAP_MSG_H @@ -28,19 +33,27 @@ #include +/** + * @enum PROBE_TYPE + * @brief Probe types. + */ enum PROBE_TYPE { - PT_US = 1, - PT_KS = 3 + PT_US = 1, /**< User probe */ + PT_KS = 3 /**< Kernel probe */ }; +/** + * @enum PROBE_SUB_TYPE + * @brief Probe sub types. + */ enum PROBE_SUB_TYPE { - PST_NONE = 0x00, - PST_KS_FILE = 0x01, - PST_KS_IPC = 0x02, - PST_KS_PROCESS = 0x04, - PST_KS_SIGNAL = 0x08, - PST_KS_NETWORK = 0x10, - PST_KS_DESC = 0x20 + PST_NONE = 0x00, /**< Common */ + PST_KS_FILE = 0x01, /**< File feature */ + PST_KS_IPC = 0x02, /**< Ipc feature */ + PST_KS_PROCESS = 0x04, /**< Process feature */ + PST_KS_SIGNAL = 0x08, /**< Signal feature */ + PST_KS_NETWORK = 0x10, /**< Network feature */ + PST_KS_DESC = 0x20 /**< Desc feature */ }; struct pt_regs;