From 9b460c47abe36554b5d024f2000aaaf9a4613941 Mon Sep 17 00:00:00 2001 From: Alexander Aksenov Date: Wed, 9 Jul 2014 12:23:10 +0400 Subject: [PATCH] [STYLE] Driver: doxygen comments Change-Id: I447d86174a2b6a94aa45f20232d688f7e5dd375b Signed-off-by: Alexander Aksenov --- driver/app_manage.h | 24 +++++-- driver/device_driver.c | 61 +++++++++++++--- driver/device_driver.h | 13 ++-- driver/device_driver_to_driver_to_buffer.h | 15 ++-- driver/driver_defs.h | 19 +++-- driver/driver_to_buffer.c | 69 ++++++++++++++---- driver/driver_to_buffer.h | 13 ++-- driver/driver_to_msg.h | 15 ++-- driver/swap_debugfs.c | 29 ++++++-- driver/swap_debugfs.h | 19 +++-- driver/swap_driver_errors.h | 111 ++++++++++++++++++++++------- driver/swap_driver_module.c | 13 ++-- driver/swap_ioctl.h | 28 ++++++-- driver/us_interaction.c | 32 +++++++-- driver/us_interaction.h | 14 ++-- driver/us_interaction_msg.h | 34 ++++++--- 16 files changed, 390 insertions(+), 119 deletions(-) diff --git a/driver/app_manage.h b/driver/app_manage.h index cae9950..6c31de6 100644 --- a/driver/app_manage.h +++ b/driver/app_manage.h @@ -1,6 +1,8 @@ -/* - * SWAP device driver - * modules/driver/app_manage.h +/** + * @file driver/app_manage.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,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, 2014 * - * 2014 Alexander Aksenov : Driver user<-> kernel - * connect implement + * @section DESCRIPTION * + * Driver user <-> kernel connect implement. */ #ifndef __APP_MANAGE_H__ @@ -29,6 +33,11 @@ #include "us_interaction.h" #include "us_interaction_msg.h" +/** + * @brief Sends pause message to kernel. + * + * @return us_interaction_send_msg result. + */ static inline int app_manage_pause_apps(void) { enum us_interaction_k2u_msg_t us_int_msg = US_INT_PAUSE_APPS; @@ -36,6 +45,11 @@ static inline int app_manage_pause_apps(void) return us_interaction_send_msg(&us_int_msg, sizeof(us_int_msg)); } +/** + * @brief Sends continue message to kernel. + * + * @return us_interaction_send_msg result. + */ static inline int app_manage_cont_apps(void) { enum us_interaction_k2u_msg_t us_int_msg = US_INT_CONT_APPS; diff --git a/driver/device_driver.c b/driver/device_driver.c index 9a567d9..bd01519 100644 --- a/driver/device_driver.c +++ b/driver/device_driver.c @@ -1,6 +1,8 @@ -/* - * SWAP device driver - * modules/driver/device_driver.c +/** + * driver/device_driver.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,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 device driver implement + * @section DESCRIPTION * + * Provides SWAP device. */ #include @@ -48,8 +53,10 @@ #include "driver_to_buffer.h" #include "driver_to_msg.h" +/** SWAP device name as it is in /dev/. */ #define SWAP_DEVICE_NAME "swap_device" +/** Maximum subbuffer size. Used for sanitization checks. */ #define MAXIMUM_SUBBUFFER_SIZE (64 * 1024) /* swap_device driver routines */ @@ -63,7 +70,10 @@ static ssize_t swap_device_splice_read(struct file *filp, loff_t *ppos, struct pipe_inode_info *pipe, size_t len, unsigned int flags); -/* File operations structure */ +/** + * @var swap_device_fops + * @brief SWAP device file operations. + */ const struct file_operations swap_device_fops = { .owner = THIS_MODULE, .read = swap_device_read, @@ -74,8 +84,10 @@ const struct file_operations swap_device_fops = { }; /* Typedefs for splice_* funcs. Prototypes are for linux-3.8.6 */ +/** Splice to pipe pointer type. */ typedef ssize_t(*splice_to_pipe_p_t)(struct pipe_inode_info *pipe, struct splice_pipe_desc *spd); +/** Splice grow spd pointer type. */ typedef int(*splice_grow_spd_p_t)(const struct pipe_inode_info *pipe, struct splice_pipe_desc *spd); @@ -125,8 +137,14 @@ static void exit_w_wake_up(void) } -/* We need this realization of splice_shrink_spd() because of the its desing - * frequent changes that I have encountered in custom kernels */ +/** + * @brief We need this realization of splice_shrink_spd() because its desing + * frequently changes in custom kernels. + * + * @param pipe Pointer to the pipe whereto splice data. + * @param spd Pointer to the splice_pipe_desc structure. + * @return Void. + */ void swap_device_splice_shrink_spd(struct pipe_inode_info *pipe, struct splice_pipe_desc *spd) { @@ -138,8 +156,14 @@ void swap_device_splice_shrink_spd(struct pipe_inode_info *pipe, } -/* Register device TODO Think of permanent major */ -int swap_device_init(void) +/* TODO Think of permanent major */ + +/** + * @brief Register device. + * + * @return 0 on success, negative error code otherwise. + */ + int swap_device_init(void) { int result; @@ -218,7 +242,13 @@ init_fail: return result; } -/* Unregister device TODO Check wether driver is registered */ +/* TODO Check wether driver is registered */ + +/** + * @brief Unregister device. + * + * @return Void. + */ void swap_device_exit(void) { exit_w_wake_up(); @@ -471,6 +501,11 @@ swap_device_splice_read_error: return result; } +/** + * @brief Wakes up daemon that splicing data from driver. + * + * @return Void. + */ void swap_device_wake_up_process(void) { if (atomic_read(&flag_wake_up) == 0) { @@ -479,6 +514,12 @@ void swap_device_wake_up_process(void) } } +/** + * @brief Registers received message handler. + * + * @param mh Pointer to message handler. + * @return Void. + */ void set_msg_handler(msg_handler_t mh) { msg_handler = mh; diff --git a/driver/device_driver.h b/driver/device_driver.h index e1b16bf..b8f821b 100644 --- a/driver/device_driver.h +++ b/driver/device_driver.h @@ -1,6 +1,8 @@ -/* - * SWAP driver - * modules/driver/device_driver.h +/** + * @file driver/device_driver.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 device driver implement + * @section DESCRIPTION * + * SWAP device driver interface declaration. */ #ifndef __SWAP_DRIVER_DEVICE_DRIVER_H__ diff --git a/driver/device_driver_to_driver_to_buffer.h b/driver/device_driver_to_driver_to_buffer.h index bce2b62..1e062e2 100644 --- a/driver/device_driver_to_driver_to_buffer.h +++ b/driver/device_driver_to_driver_to_buffer.h @@ -1,6 +1,8 @@ -/* - * SWAP driver - * modules/driver_new/device_driver_to_driver_to_buffer.h +/** + * @file device_driver_to_driver_to_buffer.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,13 +18,14 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * - * Copyright (C) Samsung Electronics, 2013 + * @section COPYRIGHT * - * 2013 Alexander Aksenov : SWAP device driver implement + * Copyright (C) Samsung Electronics, 2013 * + * @section DESCRIPTION + * SWAP device interface for driver_to_buffer. */ -/* SWAP device interface for driver_to_buffer */ #ifndef __DEVICE_DRIVER_TO_DRIVER_TO_BUFFER_H__ #define __DEVICE_DRIVER_TO_DRIVER_TO_BUFFER_H__ diff --git a/driver/driver_defs.h b/driver/driver_defs.h index 35b23d7..635f319 100644 --- a/driver/driver_defs.h +++ b/driver/driver_defs.h @@ -1,6 +1,8 @@ -/* - * SWAP device driver - * modules/driver/driver_defs.h +/** + * @file driver/driver_defs.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,12 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * - * Copyright (C) Samsung Electronics, 2013 + * @section COPYRIGHT * - * 2013 Alexander Aksenov : SWAP device driver implement + * Copyright (C) Samsung Electronics, 2013 * + * @section DESCRIPTION + * Device driver defs. */ #ifndef __SWAP_DRIVER_DEVICE_DEFS_H__ @@ -27,14 +31,19 @@ #include +/** Prints debug message.*/ #define print_debug(msg, args...) \ printk(KERN_DEBUG "SWAP_DRIVER DEBUG : " msg, ##args) +/** Prints info message.*/ #define print_msg(msg, args...) \ printk(KERN_INFO "SWAP_DRIVER : " msg, ##args) +/** Prints warning message.*/ #define print_warn(msg, args...) \ printk(KERN_WARNING "SWAP_DRIVER WARNING : " msg, ##args) +/** Prints error message.*/ #define print_err(msg, args...) \ printk(KERN_ERR "SWAP_DRIVER ERROR : " msg, ##args) +/** Prints critical error message.*/ #define print_crit(msg, args...) \ printk(KERN_CRIT "SWAP_DRIVER CRITICAL : " msg, ##args) diff --git a/driver/driver_to_buffer.c b/driver/driver_to_buffer.c index fc8751b..cc9dba0 100644 --- a/driver/driver_to_buffer.c +++ b/driver/driver_to_buffer.c @@ -1,6 +1,8 @@ -/* - * SWAP driver - * modules/driver/driver_to_buffer.c +/** + * driver/driver_to_buffer.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,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 device driver implement + * @section DESCRIPTION * + * Driver and buffer interaction interface implementation. */ #include @@ -136,7 +141,11 @@ static int driver_to_buffer_release(void) return E_SD_SUCCESS; } -/* Buffers callback function */ +/** + * @brief Buffers callback function + * + * @return 0 + */ int driver_to_buffer_callback(void) { /* Increment buffers_to_read counter */ @@ -146,7 +155,14 @@ int driver_to_buffer_callback(void) return E_SD_SUCCESS; } -/* Read buffers */ +/** + * @brief Copies data from subbuffer to userspace. + * + * @param[out] buf Pointer to userspace memory area whereto copy data from + * subbuffer. + * @param count Size of data to be read. + * @return Read data size on success, negative error code on error. + */ ssize_t driver_to_buffer_read(char __user *buf, size_t count) { size_t bytes_to_copy; @@ -186,7 +202,11 @@ ssize_t driver_to_buffer_read(char __user *buf, size_t count) return bytes_to_read; } -/* Flush swap_buffer */ +/** + * @brief Flushes SWAP buffer. + * + * @return 0. + */ int driver_to_buffer_flush(void) { unsigned int flushed; @@ -198,7 +218,12 @@ int driver_to_buffer_flush(void) return E_SD_SUCCESS; } -/* Fills spd structure */ +/** + * @brief Fills spd structure. + * + * @param[out] spd Pointer to the splice_pipe_desc struct that should be filled. + * @return 0 on success, negative error code on error. + */ int driver_to_buffer_fill_spd(struct splice_pipe_desc *spd) { size_t data_to_splice = busy_buffer->full_buffer_part; @@ -237,13 +262,23 @@ int driver_to_buffer_fill_spd(struct splice_pipe_desc *spd) return 0; } -/* Check for subbuffers ready to be read */ +/** + * @brief Check for subbuffer ready to be read. + * + * @return 1 if there is subbuffer to be read, 0 - if there isn't. + */ int driver_to_buffer_buffer_to_read(void) { return busy_buffer ? 1 : 0; } -/* Set buffers size and count */ +/** + * @brief Initializes SWAP buffer. + * + * @param size Size of one subbuffer. + * @param count Count of subbuffers. + * @return 0 on success, negative error code on error. + */ int driver_to_buffer_initialize(size_t size, unsigned int count) { int result; @@ -277,7 +312,11 @@ int driver_to_buffer_initialize(size_t size, unsigned int count) return E_SD_SUCCESS; } -/* Uninitialize buffer */ +/** + * @brief Uninitializes buffer. + * + * @return 0 on success, negative error code on error. + */ int driver_to_buffer_uninitialize(void) { int result; @@ -310,7 +349,12 @@ int driver_to_buffer_uninitialize(void) return result; } -/* Get next buffer to read */ +/** + * @brief Get next buffer to read. + * + * @return 0 on success, negative error code on error, E_SD_NO_DATA_TO_READ if + * there is nothing to be read. + */ int driver_to_buffer_next_buffer_to_read(void) { int result; @@ -340,4 +384,3 @@ int driver_to_buffer_next_buffer_to_read(void) return E_SD_SUCCESS; } - diff --git a/driver/driver_to_buffer.h b/driver/driver_to_buffer.h index d7a9646..200c6bb 100644 --- a/driver/driver_to_buffer.h +++ b/driver/driver_to_buffer.h @@ -1,6 +1,8 @@ -/* - * SWAP driver - * modules/driver/driver_to_buffer.h +/** + * @file driver/driver_to_buffer.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 device driver implement + * @section DESCRIPTION * + * Driver and buffer interaction interface declaration. */ #ifndef __SWAP_DRIVER_DRIVER_TO_BUFFER__ diff --git a/driver/driver_to_msg.h b/driver/driver_to_msg.h index 07aa949..73fc434 100644 --- a/driver/driver_to_msg.h +++ b/driver/driver_to_msg.h @@ -1,6 +1,8 @@ -/* - * SWAP device driver - * modules/driver/driver_to_msg.h +/** + * @file driver/driver_to_msg.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 @@ -16,16 +18,19 @@ * 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 driver to parser implement + * @section DESCRIPTION * + * Driver and parser interaction interface declaration. */ #ifndef __SWAP_DRIVER_DRIVER_TO_MSG__ #define __SWAP_DRIVER_DRIVER_TO_MSG__ - +/** Defines type for message handler's pointer. */ typedef int (*msg_handler_t)(void __user *data); /* Set the message handler */ diff --git a/driver/swap_debugfs.c b/driver/swap_debugfs.c index bc13e1d..976ed79 100644 --- a/driver/swap_debugfs.c +++ b/driver/swap_debugfs.c @@ -1,6 +1,8 @@ -/* - * SWAP kernel features - * driver/swap_debugfs.c +/** + * driver/swap_debugfs.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 * + * Initializes root debugfs for all SWAP modules */ @@ -29,13 +34,22 @@ static struct dentry *swap_dir = NULL; - +/** + * @brief Get debugfs dir. + * + * @return Pointer to dentry stuct. + */ struct dentry *get_swap_debugfs_dir(void) { return swap_dir; } EXPORT_SYMBOL_GPL(get_swap_debugfs_dir); +/** + * @brief Initializes SWAP debugfs. + * + * @return 0 on success, negative error code on error. + */ int swap_debugfs_init(void) { swap_dir = debugfs_create_dir("swap", NULL); @@ -45,6 +59,11 @@ int swap_debugfs_init(void) return 0; } +/** + * @brief Deinitializes SWAP debugfs and recursively removes all its files. + * + * @return Void. + */ void swap_debugfs_exit(void) { struct dentry *dir = swap_dir; diff --git a/driver/swap_debugfs.h b/driver/swap_debugfs.h index 305030f..a1912a2 100644 --- a/driver/swap_debugfs.h +++ b/driver/swap_debugfs.h @@ -1,9 +1,8 @@ -#ifndef _SWAP_DEBUG_FS_H -#define _SWAP_DEBUG_FS_H - -/* - * SWAP kernel features - * driver/swap_debugfs.h +/** + * @file driver/swap_debugfs.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,13 +18,19 @@ * 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 debugfs interface definition. */ +#ifndef _SWAP_DEBUG_FS_H +#define _SWAP_DEBUG_FS_H + struct dentry; diff --git a/driver/swap_driver_errors.h b/driver/swap_driver_errors.h index e7cade7..75294a6 100644 --- a/driver/swap_driver_errors.h +++ b/driver/swap_driver_errors.h @@ -1,6 +1,8 @@ -/* - * SWAP Driver Module - * modules/buffer/swap_driver_errors.h +/** + * @file driver/swap_driver_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,39 +18,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, 2013 * - * 2013 Alexander Aksenov : SWAP Driver implement + * @section DESCRIPTION * + * SWAP driver error codes. */ #ifndef __SWAP_DRIVER_ERRORS_H__ #define __SWAP_DRIVER_ERRORS_H__ -/* SWAP Driver error codes enumeration */ +/** + * @enum _swap_driver_errors + * @brief SWAP driver errors enumeration. + */ enum _swap_driver_errors { - E_SD_SUCCESS = 0, /* Success */ - E_SD_ALLOC_CHRDEV_FAIL = 1, /* alloc_chrdev_region failed */ - E_SD_CDEV_ALLOC_FAIL = 2, /* cdev_alloc failed */ - E_SD_CDEV_ADD_FAIL = 3, /* cdev_add failed */ - E_SD_CLASS_CREATE_FAIL = 4, /* class_create failed */ - E_SD_DEVICE_CREATE_FAIL = 5, /* device_create failed */ - E_SD_NO_SPLICE_FUNCS = 6, /* splice_* funcs not found */ - E_SD_NO_DATA_TO_READ = 7, /* swap_buffer_get tells us that there is no - readable subbuffers */ - E_SD_NO_BUSY_SUBBUFFER = 8, /* No busy subbuffer */ - E_SD_WRONG_SUBBUFFER_PTR = 9, /* Wrong subbuffer pointer passed to - swap_buffer module */ - E_SD_BUFFER_ERROR = 10, /* Unhandled swap_buffer error */ - E_SD_WRITE_ERROR = 11, /* Write to subbuffer error */ - E_SD_WRONG_ARGS = 12, /* Arguments, passed to the func, doesn't - pass sanity check */ - E_SD_NO_MEMORY = 13, /* No memory to allocate */ - E_SD_UNINIT_ERROR = 14, /* swap_buffer uninitialization error */ - E_SD_NL_INIT_ERR = 15, /* Netlink init error */ - E_SD_NL_MSG_ERR = 16, /* Netlink message send error */ - E_SD_NO_DAEMON_PID = 17 /* No daemon pid in us_interaction */ + /** + * @brief Success. + */ + E_SD_SUCCESS = 0, + /** + * @brief Alloc_chrdev_region failed. + */ + E_SD_ALLOC_CHRDEV_FAIL = 1, + /** + * @brief cdev_alloc failed. + */ + E_SD_CDEV_ALLOC_FAIL = 2, + /** + * @brief cdev_add failed. + */ + E_SD_CDEV_ADD_FAIL = 3, + /** + * @brief class_create failed. + */ + E_SD_CLASS_CREATE_FAIL = 4, + /** + * @brief device_create failed. + */ + E_SD_DEVICE_CREATE_FAIL = 5, + /** + * @brief splice_* funcs not found. + */ + E_SD_NO_SPLICE_FUNCS = 6, + /** + * @brief swap_buffer_get tells us that there is no readable subbuffers. + */ + E_SD_NO_DATA_TO_READ = 7, + /** + * @brief No busy subbuffer. + */ + E_SD_NO_BUSY_SUBBUFFER = 8, + /** + * @brief Wrong subbuffer pointer passed to swap_buffer module. + */ + E_SD_WRONG_SUBBUFFER_PTR = 9, + /** + * @brief Unhandled swap_buffer error. + */ + E_SD_BUFFER_ERROR = 10, + /** + * @brief Write to subbuffer error. + */ + E_SD_WRITE_ERROR = 11, + /** + * @brief Arguments, been passed to the func, doesn't pass sanity check. + */ + E_SD_WRONG_ARGS = 12, + /** + * @brief No memory to allocate. + */ + E_SD_NO_MEMORY = 13, + /** + * @brief swap_buffer uninitialization error. + */ + E_SD_UNINIT_ERROR = 14, + /** + * @brief Netlink init error. + */ + E_SD_NL_INIT_ERR = 15, + /** + * @brief Netlink message send error. + */ + E_SD_NL_MSG_ERR = 16, + /** + * @brief No daemon pid in us_interaction. + */ + E_SD_NO_DAEMON_PID = 17 }; #endif /* __SWAP_DRIVER_ERRORS_H__ */ diff --git a/driver/swap_driver_module.c b/driver/swap_driver_module.c index 4c702ab..08fb151 100644 --- a/driver/swap_driver_module.c +++ b/driver/swap_driver_module.c @@ -1,6 +1,8 @@ -/* - * SWAP Driver - * modules/driver/swap_driver_module.c +/** + * driver/swap_driver_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,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 device driver implement + * @section DESCRIPTION * + * SWAP drive module interface implementation. */ #include diff --git a/driver/swap_ioctl.h b/driver/swap_ioctl.h index 38d7a01..2b00084 100644 --- a/driver/swap_ioctl.h +++ b/driver/swap_ioctl.h @@ -1,6 +1,8 @@ -/* - * SWAP driver - * modules/driver/swap_ioctl.h +/** + * @file driver/swap_ioctl.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 device driver implement + * @section DESCRIPTION * + * Provides ioctl commands and recources for SWAP driver. */ #ifndef __SWAP_IOCTL_H__ @@ -27,8 +32,17 @@ #include +/** SWAP device magic number. */ #define SWAP_DRIVER_IOC_MAGIC 0xAF +/** + * @struct buffer_initialize + * @brief SWAP buffer initialization struct. + * @var buffer_initialize::size + * Size of one subbuffer. + * @var buffer_initialize::count + * Count of subbuffers in the buffer. + */ struct buffer_initialize { size_t size; unsigned int count; @@ -36,13 +50,19 @@ struct buffer_initialize { /* SWAP Device ioctl commands */ +/** Initialize buffer message. */ #define SWAP_DRIVER_BUFFER_INITIALIZE _IOW(SWAP_DRIVER_IOC_MAGIC, 1, \ struct buffer_initialize *) +/** Uninitialize buffer message. */ #define SWAP_DRIVER_BUFFER_UNINITIALIZE _IO(SWAP_DRIVER_IOC_MAGIC, 2) +/** Set next buffer to read. */ #define SWAP_DRIVER_NEXT_BUFFER_TO_READ _IO(SWAP_DRIVER_IOC_MAGIC, 3) +/** Flush buffers. */ #define SWAP_DRIVER_FLUSH_BUFFER _IO(SWAP_DRIVER_IOC_MAGIC, 4) +/** Custom message. */ #define SWAP_DRIVER_MSG _IOW(SWAP_DRIVER_IOC_MAGIC, 5, \ void *) +/** Force wake up daemon. */ #define SWAP_DRIVER_WAKE_UP _IO(SWAP_DRIVER_IOC_MAGIC, 6) #endif /* __SWAP_IOCTL_H__ */ diff --git a/driver/us_interaction.c b/driver/us_interaction.c index 2b2d6c8..0f64f3d 100644 --- a/driver/us_interaction.c +++ b/driver/us_interaction.c @@ -1,6 +1,8 @@ -/* - * SWAP device driver - * modules/driver/us_interaction.c +/** + * driver/us_interaction.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, 2014 * - * 2014 Alexander Aksenov : Driver user<-> kernel - * connect implement + * @section DESCRIPTION * + * Kernel-to-user interface implementation. */ @@ -45,7 +49,13 @@ static const char cn_swap_name[] = "cn_swap"; /* Send messages counter */ static u32 msg_counter = 0; - +/** + * @brief Sends message to userspace via netlink. + * + * @param data Pointer to the data to be send. + * @param size Size of the data to be send. + * @return 0 on success, error code on error. + */ int us_interaction_send_msg(const void *data, size_t size) { struct cn_msg *msg; @@ -80,6 +90,11 @@ static void us_interaction_recv_msg(struct cn_msg *msg, { } +/** + * @brief Creates netlink connection. + * + * @return 0 on success, error code on error. + */ int us_interaction_create(void) { int res; @@ -91,6 +106,11 @@ int us_interaction_create(void) return E_SD_SUCCESS; } +/** + * @brief Destroy netlink connection. + * + * @return Void. + */ void us_interaction_destroy(void) { cn_del_callback(&cn_swap_id); diff --git a/driver/us_interaction.h b/driver/us_interaction.h index d6fb591..9e9ec79 100644 --- a/driver/us_interaction.h +++ b/driver/us_interaction.h @@ -1,6 +1,8 @@ -/* - * SWAP device driver - * modules/driver/us_interaction.h +/** + * @file driver/us_interaction.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,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, 2014 * - * 2014 Alexander Aksenov : Driver user<-> kernel - * connect implement + * @section DESCRIPTION * + * Kernel-to-user interface definition. */ #ifndef __US_INTERACTION_H__ diff --git a/driver/us_interaction_msg.h b/driver/us_interaction_msg.h index c87a2c4..47de39e 100644 --- a/driver/us_interaction_msg.h +++ b/driver/us_interaction_msg.h @@ -1,6 +1,8 @@ -/* - * SWAP device driver - * modules/driver/us_interaction_msg.h +/** + * @file driver/us_interaction_msg.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,24 +18,36 @@ * 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 : Driver user<-> kernel - * connect implement + * @section DESCRIPTION * + * Netlink messages declaration. */ #ifndef __US_INTERACTION_MSG_H__ #define __US_INTERACTION_MSG_H__ -#define CN_SWAP_IDX 0x22 /* Should be unique throughout the system */ -#define CN_SWAP_VAL 0x1 /* Just the same in kernel and user */ -#define CN_DAEMON_GROUP 0x1 /* Listener group. Connector works a bit faster +#define CN_SWAP_IDX 0x22 /**< Should be unique throughout the system */ +#define CN_SWAP_VAL 0x1 /**< Just the same in kernel and user */ +#define CN_DAEMON_GROUP 0x1 /**< Listener group. Connector works a bit faster * when using one */ +/** + * @enum us_interaction_k2u_msg_t + * @brief Kernel-to-user netlink messages headers. + */ enum us_interaction_k2u_msg_t { - US_INT_PAUSE_APPS = 1, /* Make daemon pause apps */ - US_INT_CONT_APPS = 2 /* Make daemon continue apps */ + /** + * @brief Make daemon pause apps. + */ + US_INT_PAUSE_APPS = 1, + /** + * @brief Make daemon continue apps. + */ + US_INT_CONT_APPS = 2 }; #endif /* __US_INTERACTION_MSG_H__ */ -- 2.7.4