From c3e8270c609b268d6715cf68d841ace024bdd5c0 Mon Sep 17 00:00:00 2001 From: Alexander Aksenov Date: Wed, 9 Jul 2014 12:02:26 +0400 Subject: [PATCH] [STYLE] Buffer: doxygen comments Change-Id: I5db3a950b4f8bc9d5444159be5c7e8ba3beacd07 Signed-off-by: Alexander Aksenov --- buffer/buffer_description.h | 27 +++++-- buffer/buffer_queue.c | 139 +++++++++++++++++++++++++++++------ buffer/buffer_queue.h | 13 +++- buffer/data_types.h | 26 +++++-- buffer/kernel_operations.h | 93 ++++++++++++++++++----- buffer/swap_buffer_errors.h | 97 +++++++++++++++++------- buffer/swap_buffer_module.c | 88 ++++++++++++++++------ buffer/swap_buffer_module.h | 42 ++++++++--- buffer/swap_buffer_to_buffer_queue.h | 16 ++-- 9 files changed, 416 insertions(+), 125 deletions(-) diff --git a/buffer/buffer_description.h b/buffer/buffer_description.h index 2be9eaf..353e33a 100644 --- a/buffer/buffer_description.h +++ b/buffer/buffer_description.h @@ -1,6 +1,8 @@ -/* - * SWAP Buffer Module - * modules/buffer/buffer_description.h +/** + * @file buffer/buffer_description.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,19 +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 Alexander Aksenov : SWAP Buffer implement + * @section DESCRIPTION * + * swap_subbuffer structure represents one buffers subbufer */ -/* SWAP Buffer structure description */ - #ifndef __BUFFER_DESCRIPTION_H__ #define __BUFFER_DESCRIPTION_H__ #include "data_types.h" +/** + * @struct swap_subbuffer + * @brief This structures are combined in array which represents the SWAP buffer. + * @var swap_subbuffer::next_in_queue + * Pointer to the next swap_subbufer in queue + * @var swap_subbuffer::full_buffer_part + * Currently occupied subbuffers size + * @var swap_subbuffer::data_buffer + * Pointer to subbuffers data itself of type swap_subbuffer_ptr + * @var swap_subbuffer::buffer_sync + * Subbuffers sync primitive + */ struct swap_subbuffer { /* Pointer to the next subbuffer in queue */ struct swap_subbuffer *next_in_queue; diff --git a/buffer/buffer_queue.c b/buffer/buffer_queue.c index 2b2f6ec..1f048ba 100644 --- a/buffer/buffer_queue.c +++ b/buffer/buffer_queue.c @@ -1,6 +1,8 @@ -/* - * SWAP Buffer Module - * modules/buffer/buffer_queue.c +/** + * buffer/buffer_queue.c + * @author Alexander Aksenov : SWAP Buffer 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,14 +18,15 @@ * 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 Buffer implement + * @section DESCRIPTION * + * Implements buffers queues interface */ -/* SWAP buffer queues implementation */ - /* For all memory allocation/deallocation operations, except buffer memory * allocation/deallocation should be used * memory_allocation(size_t memory_size) @@ -47,8 +50,19 @@ #include "swap_buffer_errors.h" #include "kernel_operations.h" -/* Queue structure. Consist of pointers to the first and the last elements of - * queue. */ +/** + * @struct queue_t + * @brief Queue structure. Consist of pointers to the first and the last + * elements of queue. + * @var queue_t::start_ptr + * Pointer to the first subbuffer in queue + * @var queue_t::end_ptr + * Pointer to the last subbuffer in queue + * @var queue_t::subbuffers_count + * Subbuffers count in queue + * @var queue_t::queue_sync + * Queue access sync primitive + */ struct queue_t { struct swap_subbuffer *start_ptr; struct swap_subbuffer *end_ptr; @@ -56,7 +70,10 @@ struct queue_t { struct sync_t queue_sync; }; -/* Write queue */ +/** + * @var write_queue + * @brief Represents write queue. + */ struct queue_t write_queue = { .start_ptr = NULL, .end_ptr = NULL, @@ -66,7 +83,10 @@ struct queue_t write_queue = { } }; -/* Read queue */ +/** + * @var read_queue + * @brief Represents read queue. + */ struct queue_t read_queue = { .start_ptr = NULL, .end_ptr = NULL, @@ -96,7 +116,14 @@ static struct sync_t buffer_busy_sync = { /* Memory pages count in one subbuffer */ static int pages_order_in_subbuffer = 0; - +/** + * @brief Allocates memory for swap_subbuffer structures and subbuffers. + * Total allocated memory = subbuffer_size * subbuffers_count. + * + * @param subbuffer_size Size of each subbuffer. + * @param subbuffers_count Count of subbuffers. + * @return 0 on success, negative error code otherwise. + */ int buffer_queue_allocation(size_t subbuffer_size, unsigned int subbuffers_count) { @@ -220,6 +247,11 @@ buffer_allocation_error_ret: return result; } +/** + * @brief Resets all subbuffers for writing. + * + * @return 0 on success, negative error code otherwise. + */ int buffer_queue_reset(void) { struct swap_subbuffer *buffer = read_queue.start_ptr; @@ -261,6 +293,11 @@ int buffer_queue_reset(void) return E_SB_SUCCESS; } +/** + * @brief Free all allocated subbuffers. + * + * @return Void. + */ void buffer_queue_free(void) { struct swap_subbuffer *tmp = NULL; @@ -322,7 +359,11 @@ static void next_queue_element(struct queue_t *queue) --queue->subbuffers_count; } -/* Get first subbuffer from read list */ +/** + * @brief Get first subbuffer from read list. + * + * @return Pointer to swap_subbuffer + */ struct swap_subbuffer *get_from_read_list(void) { struct swap_subbuffer *result = NULL; @@ -346,7 +387,12 @@ get_from_read_list_unlock: return result; } -/* Add subbuffer to read list */ +/** + * @brief Add subbuffer to read list. + * + * @param subbuffer Pointer to the subbuffer to add. + * @return Void. + */ void add_to_read_list(struct swap_subbuffer *subbuffer) { /* Lock read sync primitive */ @@ -369,7 +415,12 @@ void add_to_read_list(struct swap_subbuffer *subbuffer) sync_unlock(&read_queue.queue_sync); } -/* Call add to read list and callback function from driver module */ +/** + * @brief Call add to read list and callback function from driver module. + * + * @param subbuffer Pointer to the subbuffer to add. + * @return swap_buffer_callback result. + */ int add_to_read_list_with_callback(struct swap_subbuffer *subbuffer) { int result = 0; @@ -381,14 +432,25 @@ int add_to_read_list_with_callback(struct swap_subbuffer *subbuffer) return result; } -/* Returns subbuffers to read count */ +/** + * @brief Returns subbuffers to read count. + * + * @return Count of subbuffers in read_queue. + */ unsigned int get_readable_buf_cnt(void) { return read_queue.subbuffers_count; } -/* Get first writable subbuffer from write list */ +/** + * @brief Get first writable subbuffer from write list. + * + * @param size Minimum amount of free space in subbuffer. + * @param[out] ptr_to_write Pointer to the variable where pointer to the beginning + * of memory for writing should be stored. + * @return Found swap_subbuffer. + */ struct swap_subbuffer *get_from_write_list(size_t size, void **ptr_to_write) { struct swap_subbuffer *result = NULL; @@ -461,7 +523,12 @@ struct swap_subbuffer *get_from_write_list(size_t size, void **ptr_to_write) return result; } -/* Add subbuffer to write list */ +/** + * @brief Add subbuffer to write list. + * + * @param subbuffer Pointer to the swap_subbuffer that should be stored. + * @return Void. + */ void add_to_write_list(struct swap_subbuffer *subbuffer) { sync_lock(&write_queue.queue_sync); @@ -484,14 +551,23 @@ void add_to_write_list(struct swap_subbuffer *subbuffer) sync_unlock(&write_queue.queue_sync); } -/* Returns subbuffers to write count */ +/** + * @brief Returns subbuffers to write count. + * + * @return Count of subbuffers in write queue. + */ unsigned int get_writable_buf_cnt(void) { return write_queue.subbuffers_count; } -/* Add subbuffer to busy list when it is read from out of the buffer */ +/** + * @brief Add subbuffer to busy list when it is read from out of the buffer. + * + * @param subbuffer Pointer to the swap_subbuffer that should be added. + * @return Void. + */ void add_to_busy_list(struct swap_subbuffer *subbuffer) { /* Lock busy sync primitive */ @@ -505,7 +581,12 @@ void add_to_busy_list(struct swap_subbuffer *subbuffer) sync_unlock(&buffer_busy_sync); } -/* Remove subbuffer from busy list when it is released */ +/** + * @brief Remove subbuffer from busy list when it is released. + * + * @param subbuffer Pointer to the swap_subbuffer that should be removed. + * @return 0 on success, negative error code otherwise. + */ int remove_from_busy_list(struct swap_subbuffer *subbuffer) { int result = -E_SB_NO_SUBBUFFER_IN_BUSY; // For sanitization @@ -531,7 +612,11 @@ int remove_from_busy_list(struct swap_subbuffer *subbuffer) return result; } -/* Set all subbuffers in write list to read list */ +/** + * @brief Set all subbuffers in write list to read list. + * + * @return Void. + */ void buffer_queue_flush(void) { struct swap_subbuffer *buffer = write_queue.start_ptr; @@ -558,7 +643,11 @@ void buffer_queue_flush(void) sync_unlock(&write_queue.queue_sync); } -/* Get subbuffers count in busy list */ +/** + * @brief Get subbuffers count in busy list. + * + * @return Count of swap_subbuffers in busy list. + */ int get_busy_buffers_count(void) { int result; @@ -570,7 +659,11 @@ int get_busy_buffers_count(void) return result; } -/* Get memory pages count in subbuffer */ +/** + * @brief Get memory pages count in subbuffer. + * + * @return Pages count in subbuffer. + */ int get_pages_count_in_subbuffer(void) { /* Return 1 if pages order 0, or 2 of power pages_order_in_subbuffer otherwise */ diff --git a/buffer/buffer_queue.h b/buffer/buffer_queue.h index a0833b5..9f627fb 100644 --- a/buffer/buffer_queue.h +++ b/buffer/buffer_queue.h @@ -1,6 +1,8 @@ -/* - * SWAP Buffer Module - * modules/buffer/buffer_queue.h +/** + * @file buffer/buffer_queue.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 Buffer implement + * @section DESCRIPTION * + * Represents buffers queues interface */ /* SWAP Buffer queues interface */ diff --git a/buffer/data_types.h b/buffer/data_types.h index 6da8b4c..47ef1d8 100644 --- a/buffer/data_types.h +++ b/buffer/data_types.h @@ -1,6 +1,8 @@ -/* - * SWAP Buffer Module - * modules/buffer/data_types.h +/** + * @file buffer/data_types.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 Buffer implement + * @section DESCRIPTION * + * Declares data types for SWAP buffer. */ #ifndef __DATA_TYPES_H__ @@ -31,13 +36,22 @@ struct page; -/* Using spinlocks as sync primitives */ +/** + * @struct sync_t + * @brief Using spinlocks as sync primitives. + * @var sync_t::spinlock + * Spinlock. + * @var sync_t::flags + * Flags for spinlock. + */ struct sync_t { spinlock_t spinlock; unsigned long flags; }; -/* swap_subbuffer_ptr points to the first memory page of the subbuffer */ +/** + * @brief swap_subbuffer_ptr points to the first memory page of the subbuffer. + */ typedef struct page *swap_subbuffer_ptr; #endif /* __DATA_TYPES_H__ */ diff --git a/buffer/kernel_operations.h b/buffer/kernel_operations.h index feb544b..62aefb2 100644 --- a/buffer/kernel_operations.h +++ b/buffer/kernel_operations.h @@ -1,6 +1,8 @@ -/* - * SWAP Buffer Module - * modules/buffer/kernel_operations.h +/** + * @file buffer/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,14 +18,15 @@ * 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 Buffer implement + * @section DESCRIPTION * + * Kernel functions wrap. */ -/* Kernel functions wrap */ - #ifndef __KERNEL_OPERATIONS_H__ #define __KERNEL_OPERATIONS_H__ @@ -40,60 +43,96 @@ /* MESSAGES */ +/** Prints debug message.*/ #define print_debug(msg, args...) \ printk(KERN_DEBUG "SWAP_BUFFER DEBUG : " msg, ##args) +/** Prints info message.*/ #define print_msg(msg, args...) \ printk(KERN_INFO "SWAP_BUFFER : " msg, ##args) +/** Prints warning message.*/ #define print_warn(msg, args...) \ printk(KERN_WARNING "SWAP_BUFFER WARNING : " msg, ##args) +/** Prints error message.*/ #define print_err(msg, args...) \ printk(KERN_ERR "SWAP_BUFFER ERROR : " msg, ##args) +/** Prints critical error message.*/ #define print_crit(msg, args...) \ printk(KERN_CRIT "SWAP_BUFFER CRITICAL : " msg, ##args) - - -/* LOCKS */ - -/* Spinlocks initialization */ +/** + * @brief struct sync_t initialization. + * + * @param buffer_sync Target sync primitive. + * @return Void. + */ static inline void sync_init(struct sync_t *buffer_sync) { spin_lock_init(&buffer_sync->spinlock); } -/* Lock spinlock with save flags */ +/** + * @brief Lock sync_t with saving flags. + * + * @param buffer_sync Target sync primitive. + * @return Void. + */ static inline void sync_lock(struct sync_t *buffer_sync) { spin_lock_irqsave(&buffer_sync->spinlock, buffer_sync->flags); } -/* Unlock spinlock with restore flags */ +/** + * @brief Unlock sync_t with restoring flags. + * + * @param buffer_sync Target sync primitive. + * @return Void. + */ static inline void sync_unlock(struct sync_t *buffer_sync) { spin_unlock_irqrestore(&buffer_sync->spinlock, buffer_sync->flags); } -/* Lock spinlock */ +/** + * @brief Lock sync_t without saving flags. + * + * @param buffer_sync Target sync primitive. + * @return Void. + */ static inline void sync_lock_no_flags(struct sync_t *buffer_sync) { spin_lock(&buffer_sync->spinlock); } -/* Unlock spinlock */ +/** + * @brief Unlock sync_t without restoring flags. + * + * @param buffer_sync Target sync primitive. + * @return Void. + */ static inline void sync_unlock_no_flags(struct sync_t *buffer_sync) { spin_unlock(&buffer_sync->spinlock); } -/* Disable preemption and irqs */ +/** + * @brief Disable preemption and irqs. + * + * @param flags Variable to save flags to. + * @return Void. + */ static inline void swap_irq_disable(unsigned long *flags) { preempt_disable(); local_irq_save(*flags); } -/* Enable preemption and irqs */ +/** + * @brief Enable preemption and irqs. + * + * @param flags Variable to restore flags from. + * @return Void. + */ static inline void swap_irq_enable(unsigned long *flags) { local_irq_restore(*flags); @@ -104,26 +143,36 @@ static inline void swap_irq_enable(unsigned long *flags) /* We alloc memory for swap_subbuffer structures with common kmalloc */ +/** Allocates memory for subbuffer structures.*/ #define memory_allocation(memory_size) kmalloc(memory_size, GFP_KERNEL) +/** Free subbuffer structures memory.*/ #define memory_free(ptr) kfree(ptr) -/* For subbuffers themselves, we allocate memory with alloc_pages, so, we have +/** For subbuffers themselves, we allocate memory with alloc_pages, so, we have * to evaluate required pages order */ #define buffer_allocation(memory_size) \ alloc_pages(GFP_KERNEL, (pages_order_in_subbuffer >= 0) ? \ pages_order_in_subbuffer : \ get_order_for_alloc_pages(memory_size)) +/** Free buffer's memory.*/ #define buffer_free(ptr, subbuf_size) \ __free_pages(ptr, (pages_order_in_subbuffer >= 0) ? \ pages_order_in_subbuffer : \ get_order_for_alloc_pages(subbuf_size)) +/** Returns buffer address.*/ #define buffer_address(buffer_ptr) page_address(buffer_ptr) +/** Sets page order in subbuffer.*/ #define set_pages_order_in_subbuffer(memory_size) \ pages_order_in_subbuffer = get_order_for_alloc_pages(memory_size) -/* Functions for pages allocation */ +/** + * @brief Functions for pages allocation. + * + * @param number Target number. + * @return Power of two. + */ static inline unsigned int nearest_power_of_two(unsigned int number) { unsigned int result = 0; @@ -141,6 +190,12 @@ static inline unsigned int nearest_power_of_two(unsigned int number) return result; } +/** + * @brief Order for alloc pages. + * + * @param memory_size Wishful memory size. + * @return Pages order. + */ static inline unsigned int get_order_for_alloc_pages(size_t memory_size) { /* First evaluate remainder of the division memory_size by PAGE_SIZE. diff --git a/buffer/swap_buffer_errors.h b/buffer/swap_buffer_errors.h index 81bdb5f..f153214 100644 --- a/buffer/swap_buffer_errors.h +++ b/buffer/swap_buffer_errors.h @@ -1,6 +1,8 @@ -/* - * SWAP Buffer Module - * modules/buffer/swap_buffer_errors.h +/** + * @file buffer/swap_buffer_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,38 +18,81 @@ * 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 Buffer implement + * @section DESCRIPTION * + * SWAP Buffer error codes enumeration. */ -/* SWAP Buffer error codes enumeration */ - #ifndef __SWAP_BUFFER_ERRORS_H__ #define __SWAP_BUFFER_ERRORS_H__ +/** + * @enum _swap_buffer_errors + * @brief SWAP buffer errors enumeration. + */ enum _swap_buffer_errors { - E_SB_SUCCESS = 0, /* Success */ - E_SB_UNRELEASED_BUFFERS = 1, /* There are some unreleased buffers. Mainly - returned by swap_buffer_uninit */ - E_SB_NO_WRITABLE_BUFFERS = 2, /* No buffers for writing */ - E_SB_WRONG_DATA_SIZE = 3, /* Wrong data size: size == 0 or - size > subbuffer size */ - E_SB_IS_STOPPED = 4, /* Trying to write data after SWAP buffer - has been stopped. */ - E_SB_OVERLAP = 5, /* Memory areas of data to be written and - subbuffer itself are overlap */ - E_SB_NO_READABLE_BUFFERS = 6, /* No buffers for reading */ - E_SB_NO_CALLBACK = 7, /* Callback function ptr == NULL */ - E_SB_NO_MEM_QUEUE_BUSY = 8, /* Memory for queue_busy wasn't allocated */ - E_SB_NO_MEM_BUFFER_STRUCT = 9, /* Memory for one of struct swap_buffer - wasn't allocated */ - E_SB_NO_MEM_DATA_BUFFER = 10, /* Memort for data buffer itself wasn't - allocated */ - E_SB_NO_SUBBUFFER_IN_BUSY = 11, /* No such subbuffer in busy_list */ - E_SB_NOT_ALLOC = 12, /* Subbuffers aren't allocated */ - E_SB_WRONG_THRESHOLD = 13 /* Thresholds > 100, top < lower */ + /** + * @brief Success. + */ + E_SB_SUCCESS = 0, + /** + * @brief There are some unreleased buffers. + * Mainly returned by swap_buffer_uninit. + */ + E_SB_UNRELEASED_BUFFERS = 1, + /** + * @brief No buffers for writing. + */ + E_SB_NO_WRITABLE_BUFFERS = 2, + /** + * @brief Wrong data size: size == 0 or size > subbuffer size. + */ + E_SB_WRONG_DATA_SIZE = 3, + /** + * @brief Trying to write data after SWAP buffer has been stopped. + */ + E_SB_IS_STOPPED = 4, + /** + * @brief Memory areas of data to be written and subbuffer itself + * are overlap. + */ + E_SB_OVERLAP = 5, + /** + * @brief No buffers for reading. + */ + E_SB_NO_READABLE_BUFFERS = 6, + /** + * @brief Callback function ptr == NULL. + */ + E_SB_NO_CALLBACK = 7, + /** + * @brief Memory for queue_busy wasn't allocated. + */ + E_SB_NO_MEM_QUEUE_BUSY = 8, + /** + * @brief Memory for one of struct swap_buffer wasn't allocated. + */ + E_SB_NO_MEM_BUFFER_STRUCT = 9, + /** + * @brief Memort for data buffer itself wasn't allocated. + */ + E_SB_NO_MEM_DATA_BUFFER = 10, + /** + * @brief No such subbuffer in busy_list. + */ + E_SB_NO_SUBBUFFER_IN_BUSY = 11, + /** + * @brief Subbuffers aren't allocated. + */ + E_SB_NOT_ALLOC = 12, + /** + * @brief Thresholds > 100, top < lower. + */ + E_SB_WRONG_THRESHOLD = 13 }; #endif /* __SWAP_BUFFER_ERRORS_H__ */ diff --git a/buffer/swap_buffer_module.c b/buffer/swap_buffer_module.c index 211601a..603ed58 100644 --- a/buffer/swap_buffer_module.c +++ b/buffer/swap_buffer_module.c @@ -1,6 +1,8 @@ -/* - * SWAP Buffer Module - * modules/buffer/swap_buffer_module.c +/** + * buffer/swap_buffer_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,37 +18,37 @@ * 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 Buffer implement + * @section DESCRIPTION * + * SWAP Buffer interface implementation. */ -/* SWAP Buffer interface implementation */ - #include "swap_buffer_module.h" #include "buffer_queue.h" #include "buffer_description.h" #include "swap_buffer_errors.h" #include "kernel_operations.h" -/* Bitwise mask for buffer status */ +/** + * @enum _swap_buffer_status_mask + * @brief Bitwise mask for buffer status. + */ enum _swap_buffer_status_mask { - BUFFER_FREE = 0, - BUFFER_ALLOC = 1, - BUFFER_PAUSE = 2, - BUFFER_WORK = 4 + BUFFER_FREE = 0, /**< 000 - memory free. */ + BUFFER_ALLOC = 1, /**< 001 - memory allocated. */ + BUFFER_PAUSE = 2, /**< 010 - buffer overflow. */ + BUFFER_WORK = 4 /**< @brief 100 - buffer work. */ }; -/* Buffer status masks: - * 0 - memory free - * 1 - memory allocated - * 10 - buffer overflow - * 100 - buffer work - * */ static unsigned char swap_buffer_status = BUFFER_FREE; -/* Callback type */ +/** + * @brief Subbuffer callback type. + */ typedef int(*subbuffer_callback_type)(void); /* Callback that is called when full subbuffer appears */ @@ -81,6 +83,14 @@ static inline unsigned int percent_to_count(unsigned char percent, return (percent * cnt) / 100; } +/** + * @brief Initializes SWAP buffer and allocates memory. + * + * @param buf_init Pointer to the buffer_init_t structure which contains + * information about subbuffers count, subbuffers size and subbuffer-full- + * callback. + * @return 0 on success, negative error code otherwise. + */ int swap_buffer_init(struct buffer_init_t *buf_init) { int result = -1; @@ -131,7 +141,11 @@ swap_buffer_init_work: } EXPORT_SYMBOL_GPL(swap_buffer_init); - +/** + * @brief Uninitializes SWAP buffer, releases allocated memory. + * + * @return 0 on success, negative error code otherwise. + */ int swap_buffer_uninit(void) { /* Check whether buffer is allocated */ @@ -164,7 +178,13 @@ int swap_buffer_uninit(void) } EXPORT_SYMBOL_GPL(swap_buffer_uninit); - +/** + * @brief Writes data to SWAP buffer. + * + * @param data Pointer to a data for writing. + * @param size Size of a data for writing. + * @return Size of written data on success, negative error code otherwise. + */ ssize_t swap_buffer_write(void *data, size_t size) { int result = E_SB_SUCCESS; @@ -219,7 +239,12 @@ buf_write_sem_post: } EXPORT_SYMBOL_GPL(swap_buffer_write); - +/** + * @brief Gets pointer to subbuffer for reading. + * + * @param[out] subbuffer Pointer to a variable which points on target subbuffer. + * @return 0 on success, negative error code otherwise. + */ int swap_buffer_get(struct swap_subbuffer **subbuffer) { int result = 0; @@ -246,7 +271,12 @@ int swap_buffer_get(struct swap_subbuffer **subbuffer) } EXPORT_SYMBOL_GPL(swap_buffer_get); - +/** + * @brief Releases subbuffer after reading. + * + * @param subbuffer Subbuffer that should be released. + * @return 0 on success, negative error code otherwise. + */ int swap_buffer_release(struct swap_subbuffer **subbuffer) { int result; @@ -270,7 +300,11 @@ int swap_buffer_release(struct swap_subbuffer **subbuffer) } EXPORT_SYMBOL_GPL(swap_buffer_release); - +/** + * @brief Sets all subbuffers for reading. + * + * @return Count of subbeffers for reading. + */ unsigned int swap_buffer_flush(void) { unsigned int result; @@ -285,7 +319,13 @@ unsigned int swap_buffer_flush(void) } EXPORT_SYMBOL_GPL(swap_buffer_flush); - +/** + * @brief Executes subbuffer-full-callback. + * + * @param buffer Pointer to the full subbuffer. + * @return -E_SB_NO_CALLBACK if no callback is registered or callbacks ret + * value otherwise. + */ int swap_buffer_callback(void *buffer) { int result; diff --git a/buffer/swap_buffer_module.h b/buffer/swap_buffer_module.h index cc70b02..1c047ad 100644 --- a/buffer/swap_buffer_module.h +++ b/buffer/swap_buffer_module.h @@ -1,6 +1,8 @@ -/* - * SWAP Buffer Module - * modules/buffer/swap_buffer_module.h +/** + * @file buffer/swap_buffer_module.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,14 +18,15 @@ * 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 Buffer implement + * @section DESCRIPTION * + * SWAP Buffer interface declaration. */ -/* SWAP Buffer interface description */ - #ifndef __SWAP_BUFFER_MODULE_H__ #define __SWAP_BUFFER_MODULE_H__ @@ -31,18 +34,37 @@ struct swap_subbuffer; +/** + * @struct buffer_init_t + * @brief Buffer init structure. Contains information necessary for SWAP buffer + * initialization. + * @var buffer_init_t::subbuffer_size + * Subbuffer size. + * @var buffer_init_t::nr_subbuffers + * Subbuffers count. + * @var buffer_init_t::subbuffer_full_cb + * Callback. Called when one of subbuffers is full. + * @var buffer_init_t::lower_threshold + * Lower threshold in percent. When buffers fall below this limit + * low_mem_cb is called and swap_buffer is suspended. + * @var buffer_init_t::low_mem_cb + * Callback that is called when count of free subbuffers falls below + * lower_threshold. + * @var buffer_init_t::top_threshold + * Top threshold in percent. When buffers exceed this limit + * enough_mem_cb is called. + * @var buffer_init_t::enough_mem_cb + * Callback that is called when count of free subbuffers exceeds top_threshold. + */ + struct buffer_init_t { size_t subbuffer_size; unsigned int nr_subbuffers; int (*subbuffer_full_cb)(void); - /* Lower threshold in percent. When buffers fall below this limit - * low_mem_cb is called and swap_buffer is suspended. */ unsigned char lower_threshold; int (*low_mem_cb)(void); - /* Top threshold in percent. When buffers exceed this limit - * enough_mem_cb is called */ unsigned char top_threshold; int (*enough_mem_cb)(void); }; diff --git a/buffer/swap_buffer_to_buffer_queue.h b/buffer/swap_buffer_to_buffer_queue.h index fec222f..4d1da3a 100644 --- a/buffer/swap_buffer_to_buffer_queue.h +++ b/buffer/swap_buffer_to_buffer_queue.h @@ -1,6 +1,8 @@ -/* - * SWAP Buffer Module - * modules/buffer/swap_buffer_to_buffer_queue.h +/** + * @file buffer/swap_buffer_to_buffer_queue.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,14 +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 Buffer implement + * Copyright (C) Samsung Electronics, 2013 * + * @section DESCRIPTION + * SWAP Buffer interface for buffer queue. */ -/* SWAP Buffer interface for buffer queue */ - #ifndef __SWAP_BUFFER_TO_BUFFER_QUEUE_H__ #define __SWAP_BUFFER_TO_BUFFER_QUEUE_H__ -- 2.7.4