From 1d5614b7990ddb03e256ded9dc616c26b9b446f3 Mon Sep 17 00:00:00 2001 From: Alexander Aksenov Date: Fri, 4 Jul 2014 15:33:32 +0400 Subject: [PATCH] [STYLE] Ks_features: doxygen comments Change-Id: Ib3a0a402efbed0bda691a6f0f43fe842e7892bad Signed-off-by: Alexander Aksenov --- ks_features/features_data.c | 41 +++++++++++++++++++++++--- ks_features/ks_features.c | 65 ++++++++++++++++++++++++++++++++++++++--- ks_features/ks_features.h | 31 +++++++++++++------- ks_features/syscall_list.h | 13 ++++++--- ksyms/ksyms.c | 30 ++++++++++++++++--- ksyms/ksyms.h | 19 +++++++----- ksyms/ksyms_init.h | 13 ++++++--- ksyms/ksyms_module.c | 23 ++++++++++++--- ksyms/no_ksyms.c | 70 +++++++++++++++++++++++++++++++++++++++++---- 9 files changed, 257 insertions(+), 48 deletions(-) diff --git a/ks_features/features_data.c b/ks_features/features_data.c index ec47f66..dbb4c3c 100644 --- a/ks_features/features_data.c +++ b/ks_features/features_data.c @@ -1,6 +1,8 @@ -/* - * SWAP kernel features - * modules/ks_features/features_data.c +/** + * ks_features/features_data.c + * @author Vyacheslav Cherkashin: SWAP ks_features implement + * + * @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,16 +18,31 @@ * 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: SWAP ks_features implement + * @section DESCRIPTION * + * SWAP kernel features */ #include "syscall_list.h" #include +/** + * @struct feature + * Feature description. + * @var feature::cnt + * Syscalls count. + * @var feature::feature_list + * Pointer to feature's syscall list. + * @var feature::sub_type + * Featue subtype. + * @var feature::enable + * Is feature enable. + */ struct feature { size_t cnt; enum syscall_id *feature_list; @@ -34,7 +51,15 @@ struct feature { unsigned enable:1; }; +/** + * @def X + * X-macros for syscall list. + */ #define X(name, args) id_##name +/** + * @enum syscall_id + * Syscall list + */ enum syscall_id { SYSCALL_LIST }; @@ -256,6 +281,10 @@ static enum syscall_id id_desc[] = { id_sys_setns }; +/** + * @def CREATE_FEATURE + * Feature initialization. + */ #define CREATE_FEATURE(x, subtype) \ { \ .cnt = sizeof(x) / sizeof(enum syscall_id), \ @@ -274,6 +303,10 @@ static struct feature features[] = { CREATE_FEATURE(id_desc, PST_KS_DESC) }; +/** + * @enum + * Defines feature_cnt. + */ enum { feature_cnt = sizeof(features) / sizeof(struct feature) }; diff --git a/ks_features/ks_features.c b/ks_features/ks_features.c index 05fd8f5..04e0f12 100644 --- a/ks_features/ks_features.c +++ b/ks_features/ks_features.c @@ -1,6 +1,8 @@ -/* - * SWAP kernel features - * modules/ks_features/ks_features.c +/** + * ks_features/ks_features.c + * @author Vyacheslav Cherkashin: SWAP ks_features implement + * + * @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: SWAP ks_features implement + * @section DESCRIPTION * + * SWAP kernel features */ @@ -34,6 +39,18 @@ #include "syscall_list.h" #include "features_data.c" +/** + * @struct ks_probe + * @brief Kernel-space probe. Struct used as a container of syscall probes. + * @var ks_probe::rp + * Pointer to kretprobe. + * @var ks_probe::counter + * Installed probes counter. + * @var ks_probe::args + * Pointer to args format string. + * @var ks_probe::sub_type + * Probe sub type. + */ struct ks_probe { struct kretprobe rp; int counter; @@ -53,6 +70,10 @@ static const char *const syscall_name[] = { }; #undef X +/** + * @enum + * Syscall name count defenition + */ enum { syscall_name_cnt = sizeof(syscall_name) / sizeof(char *) }; @@ -141,6 +162,10 @@ static int switch_ret_handler(struct kretprobe_instance *ri, struct pt_regs *reg return 0; } +/** + * @var switch_rp + * Kretprobe for scheduler. + */ struct kretprobe switch_rp = { .entry_handler = switch_entry_handler, .handler = switch_ret_handler @@ -149,6 +174,11 @@ struct kretprobe switch_rp = { static DEFINE_MUTEX(mutex_sc_enable); static int sc_enable = 0; +/** + * @brief Get scheduler address. + * + * @return 0 on success, negative error code on error. + */ int init_switch_context(void) { unsigned long addr; @@ -164,6 +194,11 @@ int init_switch_context(void) return 0; } +/** + * @brief Unregisters probe on context switching. + * + * @return Void. + */ void exit_switch_context(void) { if (sc_enable) @@ -407,6 +442,12 @@ static struct feature *get_feature(enum feature_id id) return &features[id]; } +/** + * @brief Sets probes related to specified feature. + * + * @param id Feature id. + * @return 0 on success, negative error code on error. + */ int set_feature(enum feature_id id) { struct feature *f; @@ -423,6 +464,12 @@ int set_feature(enum feature_id id) } EXPORT_SYMBOL_GPL(set_feature); +/** + * @brief Unsets probes related to specified feature. + * + * @param id Feature id. + * @return 0 on success, negative error code on error. + */ int unset_feature(enum feature_id id) { struct feature *f; @@ -509,6 +556,11 @@ static void print_feature(struct feature *f) } } +/** + * @brief Prints features. + * + * @return Void. + */ void print_features(void) { int i; @@ -520,6 +572,11 @@ void print_features(void) } } +/** + * @brief Prints all syscalls. + * + * @return Void. + */ void print_all_syscall(void) { int i; diff --git a/ks_features/ks_features.h b/ks_features/ks_features.h index 629e0f0..a98c3f6 100644 --- a/ks_features/ks_features.h +++ b/ks_features/ks_features.h @@ -1,6 +1,8 @@ -/* - * SWAP kernel features - * modules/ks_features/ks_features.h +/** + * @file ks_features/ks_features.h + * @author Vyacheslav Cherkashin: SWAP ks_features implement + * + * @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,24 +18,31 @@ * 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: SWAP ks_features implement + * @section DESCRIPTION * + * SWAP kernel features interface declaration. */ #ifndef _KS_FEATURES_H #define _KS_FEATURES_H +/** + * @enum feature_id + * Features ids + */ enum feature_id { - FID_FILE = 1, - FID_IPC = 2, - FID_PROCESS = 3, - FID_SIGNAL = 4, - FID_NET = 5, - FID_DESC = 6, - FID_SWITCH = 7 + FID_FILE = 1, /**< File probes */ + FID_IPC = 2, /**< Hz probes */ + FID_PROCESS = 3, /**< Process probes */ + FID_SIGNAL = 4, /**< Signal probes */ + FID_NET = 5, /**< Network probes */ + FID_DESC = 6, /**< Description probes */ + FID_SWITCH = 7 /**< Switch context probes */ }; int set_feature(enum feature_id id); diff --git a/ks_features/syscall_list.h b/ks_features/syscall_list.h index 66be2cb..c3d807d 100644 --- a/ks_features/syscall_list.h +++ b/ks_features/syscall_list.h @@ -1,6 +1,8 @@ -/* - * SWAP kernel features - * modules/ks_features/syscall_list.h +/** + * @file ks_features/syscall_list.h + * @author Vyacheslav Cherkashin: SWAP ks_features implement + * + * @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: SWAP ks_features implement + * @section DESCRIPTION * + * Syscalls list. */ diff --git a/ksyms/ksyms.c b/ksyms/ksyms.c index 4545d91..02a450a 100644 --- a/ksyms/ksyms.c +++ b/ksyms/ksyms.c @@ -1,6 +1,9 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/ksyms/ksyms.c +/** + * @file ksyms/ksyms.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,10 +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, 2014 * - * 2014 Alexander Aksenov + * @section DESCRIPTION * + * SWAP ksyms module. */ @@ -29,6 +35,16 @@ #include #include +/** + * @struct symbol_data + * @brief Stores symbols data. + * @var symbol_data::name + * Pointer to symbol name string. + * @var symbol_data::len + * Symbol name length. + * @var symbol_data::addr + * Symbol address. + */ struct symbol_data { const char *name; size_t len; @@ -51,6 +67,12 @@ static int symbol_cb(void *data, const char *sym, struct module *mod, return 0; } +/** + * @brief Search of symbol address based on substring. + * + * @param name Pointer to the substring. + * @return Symbol address. + */ unsigned long swap_ksyms_substr(const char *name) { struct symbol_data sym_data = { diff --git a/ksyms/ksyms.h b/ksyms/ksyms.h index 723bb08..3348b7f 100644 --- a/ksyms/ksyms.h +++ b/ksyms/ksyms.h @@ -1,9 +1,8 @@ -#ifndef __KSYMS_H__ -#define __KSYMS_H__ - -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/ksyms/ksyms.h +/** + * @file ksyms/ksyms.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 + * @sectoin DESCRIPTION * + * SWAP symbols searching module. */ +#ifndef __KSYMS_H__ +#define __KSYMS_H__ + #include #if LINUX_VERSION_CODE < KERNEL_VERSION(2, 6, 33) #include diff --git a/ksyms/ksyms_init.h b/ksyms/ksyms_init.h index 99d44b6..6235a59 100644 --- a/ksyms/ksyms_init.h +++ b/ksyms/ksyms_init.h @@ -1,6 +1,8 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/ksyms/ksyms_init.h +/** + * @file ksyms/ksyms_init.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 LICENSE + * * Copyright (C) Samsung Electronics, 2014 * - * 2014 Alexander Aksenov + * @section DESCRIPTION * + * SWAP symbols searching module initialization interface. */ #ifndef __KSYMS_INIT_H__ diff --git a/ksyms/ksyms_module.c b/ksyms/ksyms_module.c index cd4b852..d113951 100644 --- a/ksyms/ksyms_module.c +++ b/ksyms/ksyms_module.c @@ -1,6 +1,8 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/ksyms/ksyms_module.c +/** + * @file ksyms/ksyms_module.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,16 +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, 2014 * - * 2014 Alexander Aksenov + * @section DESCRIPTION * + * SWAP symbols searching module initialization implementation. */ #include "ksyms_init.h" #include +/** + * @brief Init ksyms module. + * + * @return 0 on success. + */ int __init swap_ksyms_init(void) { int ret = ksyms_init(); @@ -35,6 +45,11 @@ int __init swap_ksyms_init(void) return ret; } +/** + * @brief Exit ksyms module. + * + * @return Void. + */ void __exit swap_ksyms_exit(void) { ksyms_exit(); diff --git a/ksyms/no_ksyms.c b/ksyms/no_ksyms.c index 59c74e3..2e87038 100644 --- a/ksyms/no_ksyms.c +++ b/ksyms/no_ksyms.c @@ -1,6 +1,8 @@ -/* - * Dynamic Binary Instrumentation Module based on KProbes - * modules/ksyms/no_ksyms.c +/** + * @file ksyms/no_ksyms.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 * + * SWAP symbols searching implementation. */ #include "ksyms.h" @@ -31,7 +36,10 @@ #include #include - +/** + * @def KSYMS_ERR + * Error message define. + */ #define KSYMS_ERR(format, args...) \ do { \ char *f = __FILE__; \ @@ -39,7 +47,16 @@ printk("%s:%u \'%s\' ERROR: " format "\n" , (n) ? n+1 : f, __LINE__, __FUNCTION__, ##args); \ } while(0) - +/** + * @struct sys_map_item + * @brief System map list item info. + * @var sys_map_item::list + * List pointer. + * @var sys_map_item::addr + * Symbol address. + * @var sys_map_item::name + * Symbol name. + */ struct sys_map_item { struct list_head list; @@ -50,10 +67,19 @@ struct sys_map_item { static char* sm_path = NULL; module_param(sm_path, charp, 0); +/** + * @var smi_list + * List of sys_map_item. + */ LIST_HEAD(smi_list); static struct file *file = NULL; static int cnt_init_sm = 0; + +/** + * @var cnt_init_sm_lock + * System map items list lock. + */ DEFINE_SEMAPHORE(cnt_init_sm_lock); static int file_open(void) @@ -258,6 +284,11 @@ static void free_sys_map(void) } } +/** + * @brief Generates symbols list. + * + * @return 0 on success. + */ int swap_get_ksyms(void) { int ret = 0; @@ -274,6 +305,11 @@ int swap_get_ksyms(void) } EXPORT_SYMBOL_GPL(swap_get_ksyms); +/** + * @brief Frees symbols list. + * + * @return Void. + */ void swap_put_ksyms(void) { down(&cnt_init_sm_lock); @@ -291,6 +327,12 @@ void swap_put_ksyms(void) } EXPORT_SYMBOL_GPL(swap_put_ksyms); +/** + * @brief Searches for symbol by its exact name. + * + * @param name Pointer the name string. + * @return Symbol's address. + */ unsigned long swap_ksyms(const char *name) { struct sys_map_item *smi; @@ -305,6 +347,12 @@ unsigned long swap_ksyms(const char *name) } EXPORT_SYMBOL_GPL(swap_ksyms); +/** + * @brief Searches for symbol by substring of its name. + * + * @param name Pointer to the name substring. + * @return Symbol's address. + */ unsigned long swap_ksyms_substr(const char *name) { struct sys_map_item *smi; @@ -319,6 +367,11 @@ unsigned long swap_ksyms_substr(const char *name) } EXPORT_SYMBOL_GPL(swap_ksyms_substr); +/** + * @brief SWAP ksyms module initialization. + * + * @return 0 on success, negative error code on error. + */ int ksyms_init(void) { int ret = 0; @@ -339,6 +392,11 @@ int ksyms_init(void) return 0; } +/** + * @brief SWAP ksyms module deinitialization. + * + * @return Void. + */ void ksyms_exit(void) { down(&cnt_init_sm_lock); -- 2.7.4