From e354eb4f4fbd602adede59138c819eb94e7c1488 Mon Sep 17 00:00:00 2001 From: Alex Ivanov Date: Tue, 8 Jan 2013 09:02:58 -0500 Subject: libfs: Doxygen Clean Up Task #1 http://www.google-melange.com/gci/task/view/google/gci2012/8120204 Patch committed with fixes for whitespace issues. --- cpukit/libfs/src/imfs/imfs.h | 97 +++++----- cpukit/libfs/src/pipe/pipe.h | 20 +- cpukit/libfs/src/rfs/rtems-rfs-bitmaps.h | 89 +++++---- cpukit/libfs/src/rfs/rtems-rfs-block-pos.h | 44 ++--- cpukit/libfs/src/rfs/rtems-rfs-block.h | 106 ++++++----- cpukit/libfs/src/rfs/rtems-rfs-buffer.h | 74 +++++--- cpukit/libfs/src/rfs/rtems-rfs-dir-hash.h | 7 +- cpukit/libfs/src/rfs/rtems-rfs-dir.h | 101 ++++++---- cpukit/libfs/src/rfs/rtems-rfs-file-system-fwd.h | 2 +- cpukit/libfs/src/rfs/rtems-rfs-file-system.h | 56 +++--- cpukit/libfs/src/rfs/rtems-rfs-file.h | 100 ++++++---- cpukit/libfs/src/rfs/rtems-rfs-format.h | 5 +- cpukit/libfs/src/rfs/rtems-rfs-inode.h | 225 +++++++++++++---------- cpukit/libfs/src/rfs/rtems-rfs-link.h | 68 ++++--- cpukit/libfs/src/rfs/rtems-rfs-mutex.h | 35 ++-- cpukit/libfs/src/rfs/rtems-rfs-rtems.h | 70 +++---- cpukit/libfs/src/rfs/rtems-rfs-shell.h | 17 +- cpukit/libfs/src/rfs/rtems-rfs-trace.h | 16 +- cpukit/libfs/src/rfs/rtems-rfs.h | 16 +- 19 files changed, 666 insertions(+), 482 deletions(-) (limited to 'cpukit/libfs') diff --git a/cpukit/libfs/src/imfs/imfs.h b/cpukit/libfs/src/imfs/imfs.h index 46fee024c3..9b2d6a6b74 100644 --- a/cpukit/libfs/src/imfs/imfs.h +++ b/cpukit/libfs/src/imfs/imfs.h @@ -1,7 +1,7 @@ /** - * @file rtems/imfs.h + * @file * - * @brief Header file for the In-Memory File System + * @brief Header File for the In-Memory File System */ /* @@ -25,6 +25,8 @@ * @defgroup IMFS POSIX In-Memory File System Support * * @brief In-Memory File System Support + * + * @{ */ #ifdef __cplusplus @@ -168,8 +170,8 @@ typedef union { /** * @brief Initializes an IMFS node. * - * @param[in,out] node The IMFS node. - * @param[in] info The IMFS type information. + * @param[in,out] node is the IMFS node. + * @param[in] info is the IMFS type information. * * @retval node Successful operation. * @retval NULL An error occurred. The @c errno indicates the error. This @@ -186,8 +188,8 @@ typedef IMFS_jnode_t *(*IMFS_node_control_initialize)( /** * @brief Returns the node and does nothing else. * - * @param[in,out] node The IMFS node. - * @param[in] info The IMFS type information. + * @param[in,out] node is the IMFS node. + * @param[in] info is the IMFS type information. * * @retval node Returns always the node passed as parameter. * @@ -201,8 +203,8 @@ IMFS_jnode_t *IMFS_node_initialize_default( /** * @brief Returns the node and sets the generic node context. * - * @param[in,out] node The IMFS node. - * @param[in] info The IMFS type information. + * @param[in,out] node is the IMFS node. + * @param[in] info is the IMFS type information. * * @retval node Returns always the node passed as parameter. * @@ -216,7 +218,7 @@ IMFS_jnode_t *IMFS_node_initialize_generic( /** * @brief Prepares the removal of an IMFS node from its parent directory. * - * @param[in,out] node The IMFS node. + * @param[in,out] node is the IMFS node. * * @retval node Successful operation. * @retval NULL An error occurred. The @c errno indicates the error. This @@ -231,7 +233,7 @@ typedef IMFS_jnode_t *(*IMFS_node_control_remove)( /** * @brief Returns the node and does nothing else. * - * @param[in,out] node The IMFS node. + * @param[in,out] node is the IMFS node. * * @retval node Returns always the node passed as parameter. * @@ -244,7 +246,7 @@ IMFS_jnode_t *IMFS_node_remove_default( /** * @brief Destroys an IMFS node. * - * @param[in,out] node The IMFS node. + * @param[in,out] node is the IMFS node. * * @retval node Returns always the node passed as parameter. * @@ -255,7 +257,7 @@ typedef IMFS_jnode_t *(*IMFS_node_control_destroy)( IMFS_jnode_t *node ); /** * @brief Returns the node and does nothing else. * - * @param[in,out] node The IMFS node. + * @param[in,out] node is the IMFS node. * * @retval node Returns always the node passed as parameter. * @@ -392,7 +394,7 @@ extern int miniIMFS_initialize( ); /** - * @brief IMFS Initialization Support + * @brief IMFS initialization support. */ extern int IMFS_initialize_support( rtems_filesystem_mount_table_entry_t *mt_entry, @@ -400,14 +402,14 @@ extern int IMFS_initialize_support( const IMFS_node_control *const node_controls [IMFS_TYPE_COUNT] ); /** - * @brief Unmount this Instance of IMFS + * @brief Unmount this instance of IMFS. */ extern void IMFS_fsunmount( rtems_filesystem_mount_table_entry_t *mt_entry ); /** - * @brief RTEMS Load Tarfs + * @brief RTEMS load tarfs. * * This file implements the "mount" procedure for tar-based IMFS * extensions. The TAR is not actually mounted under the IMFS. @@ -459,7 +461,7 @@ extern int rtems_tarfs_load( ); /** - * @brief IMFS Dump + * @brief Dump the entire IMFS. * * This routine dumps the entire IMFS that is mounted at the root * directory. @@ -470,7 +472,8 @@ extern int rtems_tarfs_load( extern void IMFS_dump( void ); /** - * @brief IMFS Memory File Maximum Size + * @brief Get the size of the largest file which can be created + * using the IMFS memory file type. * * Return the size of the largest file which can be created * using the IMFS memory file type. @@ -478,22 +481,22 @@ extern void IMFS_dump( void ); extern int IMFS_memfile_maximum_size( void ); /** - * @brief Destroy IMFS Node + * @brief Destroy an IMFS node. */ extern void IMFS_node_destroy( IMFS_jnode_t *node ); /** - * @brief Clone IMFS Node + * @brief Clone an IMFS node. */ extern int IMFS_node_clone( rtems_filesystem_location_info_t *loc ); /** - * @brief Free IMFS Node + * @brief Free an IMFS node. */ extern void IMFS_node_free( const rtems_filesystem_location_info_t *loc ); /** - * @brief IMFS Node Type + * @brief IMFS Node Type Get the type of an IMFS node. * * The following verifies that returns the type of node that the * loc refers to. @@ -503,7 +506,7 @@ extern rtems_filesystem_node_types_t IMFS_node_type( ); /** - * @brief IMFS Stat + * @brief Perform a status processing for the IMFS. * * This routine provides a stat for the IMFS file system. */ @@ -513,14 +516,14 @@ extern int IMFS_stat( ); /** - * @brief Evaluation IMFS Node Support + * @brief IMFS evaluation node support. */ extern void IMFS_eval_path( rtems_filesystem_eval_path_context_t *ctx ); /** - * @brief IMFS Create a New Link Node + * @brief Create a new IMFS link node. * * The following rouine creates a new link node under parent with the * name given in name. The link node is set to point to the node at @@ -534,7 +537,7 @@ extern int IMFS_link( ); /** - * @brief IMFS Change Owner + * @brief Change the owner of IMFS. * * This routine is the implementation of the chown() system * call for the IMFS. @@ -546,7 +549,7 @@ extern int IMFS_chown( ); /** - * @brief Create a IMFS Node + * @brief Create an IMFS node. * * Routine to create a node in the IMFS file system. */ @@ -559,7 +562,7 @@ extern int IMFS_mknod( ); /** - * @brief Create a New IMFS Node + * @brief Create a new IMFS node. * * Routine to create a new in memory file system node. */ @@ -573,7 +576,7 @@ extern IMFS_jnode_t *IMFS_allocate_node( ); /** - * @brief Create an IMFS Node + * @brief Create an IMFS node. * * Create an IMFS filesystem node of an arbitrary type that is NOT * the root directory node. @@ -611,10 +614,10 @@ extern bool IMFS_is_imfs_instance( /** * @brief Makes a generic IMFS node. * - * @param[in] path The path to the new generic IMFS node. - * @param[in] mode The node mode. - * @param[in] node_control The node control. - * @param[in] context The node control handler context. + * @param[in] path is a pointer to the new generic IMFS node. + * @param[in] mode is the node mode. + * @param[in] node_control is the node control. + * @param[in] context is the node control handler context. * * @retval 0 Successful operation. * @retval -1 An error occurred. The @c errno indicates the error. @@ -658,14 +661,14 @@ extern int IMFS_make_generic_node( /** @} */ /** - * @brief Mount an IMFS + * @brief Mount an IMFS. */ extern int IMFS_mount( rtems_filesystem_mount_table_entry_t *mt_entry /* IN */ ); /** - * @brief Unmount an IMFS + * @brief Unmount an IMFS. */ extern int IMFS_unmount( rtems_filesystem_mount_table_entry_t *mt_entry /* IN */ @@ -676,7 +679,7 @@ extern IMFS_jnode_t *IMFS_memfile_remove( ); /** - * @brief Truncate a Memory File + * @brief Truncate a memory file. * * This routine processes the ftruncate() system call. */ @@ -686,7 +689,7 @@ extern int memfile_ftruncate( ); /** - * @brief IMFS Read Next Directory + * @brief Read the next directory of the IMFS. * * This routine will read the next directory entry based on the directory * offset. The offset should be equal to -n- time the size of an individual @@ -718,7 +721,7 @@ extern ssize_t imfs_dir_read( */ /** - * @brief Open a Memory File + * @brief Open a memory file. * * This routine processes the open() system call. Note that there is * nothing special to be done at open() time. @@ -731,7 +734,7 @@ extern int memfile_open( ); /** - * @brief Read a Memory File + * @brief Read a memory file. * * This routine processes the read() system call. */ @@ -742,7 +745,7 @@ extern ssize_t memfile_read( ); /** - * @brief Write a Memory File + * @brief Write a memory file. * * This routine processes the write() system call. */ @@ -802,7 +805,7 @@ extern int device_ftruncate( /** @} */ /** - * @brief Set IMFS File Access and Modification Times + * @brief Set IMFS file access and modification times. * * * This routine is the implementation of the utime() system @@ -815,7 +818,7 @@ extern int IMFS_utime( ); /** - * @brief Change IMFS File Mode + * @brief Change the IMFS file mode. */ extern int IMFS_fchmod( const rtems_filesystem_location_info_t *loc, @@ -823,7 +826,7 @@ extern int IMFS_fchmod( ); /** - * @brief IMFS Create a New Symbolic Link Node + * @brief Create a new IMFS symbolic link node. * * The following rouine creates a new symbolic link node under parent * with the name given in name. The node is set to point to the node at @@ -837,9 +840,9 @@ extern int IMFS_symlink( ); /** - * @brief IMFS Put Symbolic Link into Buffer + * @brief Put IMFS symbolic link into buffer. * - * The following rouine puts the symblic links destination name into + * The following rouine puts the symbolic links destination name into * buff. * */ @@ -850,7 +853,7 @@ extern ssize_t IMFS_readlink( ); /** - * @brief IMFS Rename + * @brief Rename the IMFS. * * The following rouine creates a new link node under parent with the * name given in name and removes the old. @@ -863,7 +866,7 @@ extern int IMFS_rename( size_t namelen ); /** - * @brief IMFS Node Removal Handler + * @brief IMFS node removal handler. * * This file contains the handler used to remove a node when a file type * does not require special actions. @@ -980,6 +983,8 @@ static inline dev_t IMFS_generic_get_device_identifier_by_node( /** @} */ +/** @} */ + #ifdef __cplusplus } #endif diff --git a/cpukit/libfs/src/pipe/pipe.h b/cpukit/libfs/src/pipe/pipe.h index 158cde5e35..f51855c173 100644 --- a/cpukit/libfs/src/pipe/pipe.h +++ b/cpukit/libfs/src/pipe/pipe.h @@ -1,7 +1,7 @@ /** - * @file rtems/pipe.h + * @file * - * @brief Defines the Interface to the POSIX FIFO/pipe File System Support + * @brief POSIX FIFO/pipe File System Support * * This include file defines the interface to the POSIX FIFO/pipe file system * support. @@ -28,6 +28,8 @@ extern "C" { * @defgroup FIFO_PIPE FIFO/pipe File System Support * * @brief Interface to the POSIX FIFO/pipe File System + * + * @{ */ /* Control block to manage each pipe */ @@ -51,7 +53,7 @@ typedef struct pipe_control { } pipe_control_t; /** - * @brief Create an Anonymous Pipe + * @brief Create an anonymous pipe. * * Called by pipe() to create an anonymous pipe. */ @@ -60,7 +62,7 @@ extern int pipe_create( ); /** - * @brief Release a Pipe + * @brief Release a pipe. * * Interface to file system close. * @@ -73,7 +75,7 @@ extern void pipe_release( ); /** - * @brief FIFO Open + * @brief File system open. * Interface to file system open. * * *pipep points to pipe control structure. If called with *pipep = NULL, @@ -86,7 +88,7 @@ extern int fifo_open( ); /** - * @brief Pipe Read + * @brief File system read. * * Interface to file system read. */ @@ -98,7 +100,7 @@ extern ssize_t pipe_read( ); /** - * @brief Pipe Write + * @brief File system write. * * Interface to file system write. */ @@ -110,7 +112,7 @@ extern ssize_t pipe_write( ); /** - * @brief Pipe IO Control + * @brief File system Input/Output control. * * Interface to file system ioctl. */ @@ -121,6 +123,8 @@ extern int pipe_ioctl( rtems_libio_t *iop ); +/** @} */ + #ifdef __cplusplus } #endif diff --git a/cpukit/libfs/src/rfs/rtems-rfs-bitmaps.h b/cpukit/libfs/src/rfs/rtems-rfs-bitmaps.h index 01d4f0f28c..c2497764e2 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-bitmaps.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-bitmaps.h @@ -186,7 +186,8 @@ typedef struct rtems_rfs_bitmap_control_s * Create a bit mask with the specified number of bits up to an element's * size. The mask is aligned to bit 0 of the element. * - * @param size The number of bits in the mask. + * @param[in] size is the number of bits in the mask. + * * @return The mask of the argument size number of bits. */ rtems_rfs_bitmap_element rtems_rfs_bitmap_mask (unsigned int size); @@ -195,8 +196,9 @@ rtems_rfs_bitmap_element rtems_rfs_bitmap_mask (unsigned int size); * Create a bit mask section. A mask section is a mask that is not aligned to * an end of the element. * - * @param start The first bit of the mask numbered from 0. - * @param end The end bit of the mask numbered from 0. + * @param[in] start is the first bit of the mask numbered from 0. + * @param[in] end is the end bit of the mask numbered from 0. + * * @return Mask section as defined by the start and end arguments. */ rtems_rfs_bitmap_element rtems_rfs_bitmap_mask_section (unsigned int start, @@ -206,9 +208,11 @@ rtems_rfs_bitmap_element rtems_rfs_bitmap_mask_section (unsigned int start, * Set a bit in a map and if all the bits are set, set the search map bit as * well. * - * @param control The control for the map. - * @param bit The bit in the map to set. - * @return int The error number (errno). No error if 0. + * @param[in] control is the control for the map. + * @param[in] bit is the bit in the map to set. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_bitmap_map_set (rtems_rfs_bitmap_control* control, rtems_rfs_bitmap_bit bit); @@ -217,9 +221,11 @@ int rtems_rfs_bitmap_map_set (rtems_rfs_bitmap_control* control, * Clear a bit in a map and make sure the search map bit is clear so a search * will find this bit available. * - * @param control The control for the map. - * @param bit The bit in the map to clear. - * @return int The error number (errno). No error if 0. + * @param[in] control is the control for the map. + * @param[in] bit is the bit in the map to clear. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_bitmap_map_clear (rtems_rfs_bitmap_control* control, rtems_rfs_bitmap_bit bit); @@ -227,10 +233,12 @@ int rtems_rfs_bitmap_map_clear (rtems_rfs_bitmap_control* control, /** * Test a bit in the map. * - * @param control The bitmap control. - * @param bit The bit to test. - * @param state The state of the bit if no error is returned. - * @return int The error number (errno). No error if 0. + * @param[in] control is the bitmap control. + * @param[in] bit is the bit to test. + * @param[in] state is the state of the bit if no error is returned. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_bitmap_map_test (rtems_rfs_bitmap_control* control, @@ -240,31 +248,37 @@ rtems_rfs_bitmap_map_test (rtems_rfs_bitmap_control* control, /** * Set all bits in the bitmap and set the dirty bit. * - * @param control The bitmap control. - * @return int The error number (errno). No error if 0. + * @param[in] control is the bitmap control. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_bitmap_map_set_all (rtems_rfs_bitmap_control* control); /** * Clear all bits in the bitmap and set the dirty bit. * - * @param control The bitmap control. - * @return int The error number (errno). No error if 0. + * @param[in] control is the bitmap control. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_bitmap_map_clear_all (rtems_rfs_bitmap_control* control); /** * Find a free bit searching from the seed up and down until found. The search * is performing by moving up from the seed for the window distance then to - * search down from the seed for the window distance. This is repeated out from - * the seed for each window until a free bit is found. The search is performed - * by checking the search map to see if the map has a free bit. + * search down from the seed for the window distance. This is repeated out + * from the seed for each window until a free bit is found. The search is + * performed by checking the search map to see if the map has a free bit. + * + * @param[in] control is the map control. + * @param[in] seed is the bit to search out from. + * @param[out] allocate A bit was allocated. + * @param[out] bit will contain the bit found free if true is returned. * - * @param control The map control. - * @param seed The bit to search out from. - * @param allocate A bit was allocated. - * @param bit Returns the bit found free if true is returned. - * @return int The error number (errno). No error if 0. + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_bitmap_map_alloc (rtems_rfs_bitmap_control* control, rtems_rfs_bitmap_bit seed, @@ -274,19 +288,24 @@ int rtems_rfs_bitmap_map_alloc (rtems_rfs_bitmap_control* control, /** * Create a search bit map from the actual bit map. * - * @param control The map control. - * @return int The error number (errno). No error if 0. + * @param[in] control is the map control. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_bitmap_create_search (rtems_rfs_bitmap_control* control); /** * Open a bitmap control with a map and search map. * - * @param control The map control. - * @param fs The file system data. - * @param buffer The buffer handle the map is stored in. - * @param size The number of bits in the map. - * @return int The error number (errno). No error if 0. + * @param[in] control is the map control. + * @param[in] fs is the file system data. + * @param[in] buffer is a pointer to the buffer handle the map is + * stored in. + * @param[in] size is the number of bits in the map. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_bitmap_open (rtems_rfs_bitmap_control* control, rtems_rfs_file_system* fs, @@ -297,8 +316,10 @@ int rtems_rfs_bitmap_open (rtems_rfs_bitmap_control* control, /** * Close a bitmap. * - * @param control The bit map control. - * @return int The error number (errno). No error if 0. + * @param[in] control is the bit map control. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_bitmap_close (rtems_rfs_bitmap_control* control); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-block-pos.h b/cpukit/libfs/src/rfs/rtems-rfs-block-pos.h index b0de7c1846..1aab489027 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-block-pos.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-block-pos.h @@ -72,8 +72,8 @@ typedef struct rtems_rfs_block_pos_s /** * Copy a block position. * - * @param _lhs The left hand side. - * @param _rhs The right hand side. + * @param[in] _lhs is the left hand side. + * @param[in] _rhs is the right hand side. */ #define rtems_rfs_block_copy_bpos(_lhs, _rhs) \ do { (_lhs)->bno = (_rhs)->bno; \ @@ -83,7 +83,7 @@ typedef struct rtems_rfs_block_pos_s /** * Zero a block position. * - * @param bpos A pointer to the block position. + * @param[in] bpos is a pointer to the block position. */ static inline void rtems_rfs_block_set_bpos_zero (rtems_rfs_block_pos* bpos) @@ -96,9 +96,9 @@ rtems_rfs_block_set_bpos_zero (rtems_rfs_block_pos* bpos) /** * Given a position compute the block number and block offset. * - * @param fs The file system data. - * @param pos The position as an absolute offset from the start. - * @param bpos Pointer to the block position to fill in. + * @param[in] fs is the file system data. + * @param[in] pos is the position as an absolute offset from the start. + * @param[out] bpos is a pointer to the block position to fill in. */ void rtems_rfs_block_get_bpos (rtems_rfs_file_system* fs, rtems_rfs_pos pos, @@ -107,9 +107,10 @@ void rtems_rfs_block_get_bpos (rtems_rfs_file_system* fs, /** * Given a block position compute the absolute offset. * - * @param fs The file system data. - * @param bpos Pointer to the block position to fill in. - * @return rtems_rfs_pos The absolute offset. + * @param[in] fs is the file system data. + * @param[out] bpos is a pointer to the block position to fill in. + * + * @retval offset The absolute offset. */ rtems_rfs_pos rtems_rfs_block_get_pos (rtems_rfs_file_system* fs, rtems_rfs_block_pos* bpos); @@ -118,9 +119,9 @@ rtems_rfs_pos rtems_rfs_block_get_pos (rtems_rfs_file_system* fs, * Add the relative position to the block position. The relative position is * signed. * - * @param fs The file system data. - * @param offset The relative offset add to the block position. - * @param bpos Pointer to the block position to fill in. + * @param[in] fs is the file system data. + * @param[in] offset is the relative offset add to the block position. + * @param[out] bpos is a pointer to the block position to fill in. */ static inline void rtems_rfs_block_add_pos (rtems_rfs_file_system* fs, @@ -156,8 +157,8 @@ typedef struct rtems_rfs_block_size_s /** * Copy a block size. * - * @param _lhs The left hand side. - * @param _rhs The right hand side. + * @param[in] _lhs is the left hand side. + * @param[in] _rhs is the right hand side. */ #define rtems_rfs_block_copy_size(_lhs, _rhs) \ do { (_lhs)->count = (_rhs)->count; \ @@ -202,7 +203,7 @@ typedef struct rtems_rfs_block_size_s /** * Zero a block size. * - * @param size A pointer to the block size. + * @param[in] size is a pointer to the block size. */ static inline void rtems_rfs_block_set_size_zero (rtems_rfs_block_size* size) @@ -214,9 +215,9 @@ rtems_rfs_block_set_size_zero (rtems_rfs_block_size* size) /** * Set the size given a position. * - * @param fs The file system data. - * @param pos The position as an absolute offset from the start. - * @param size Pointer to the block size to fill in. + * @param[in] fs is the file system data. + * @param[in] pos is the position as an absolute offset from the start. + * @param[out] size is a pointer to the block size to fill in. */ void rtems_rfs_block_get_block_size (rtems_rfs_file_system* fs, rtems_rfs_pos pos, @@ -230,9 +231,10 @@ void rtems_rfs_block_get_block_size (rtems_rfs_file_system* fs, * blocks is 1 and offset is 0 the size is the block size. If the block count * is 1 and size is 100 the size is 100. * - * @param fs The file system data. - * @param size The size in blocks and offset. - * @return rtems_rfs_pos The size in bytes. + * @param[in] fs is the file system data. + * @param[in] size The size in blocks and offset. + * + * @retval size The size in bytes. */ rtems_rfs_pos rtems_rfs_block_get_size (rtems_rfs_file_system* fs, rtems_rfs_block_size* size); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-block.h b/cpukit/libfs/src/rfs/rtems-rfs-block.h index c93cb20b24..928186f52b 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-block.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-block.h @@ -30,9 +30,10 @@ /** * Get a block number in the media format and return it in the host format. * - * @param _h The buffer handle of the block. - * @param _b The block number index. - * @return uint32_t The block number. + * @param[in] _h is the buffer handle of the block. + * @param[in] _b is the block number index. + * + * @retval block The block number. */ #define rtems_rfs_block_get_number(_h, _b) \ ((rtems_rfs_block_no) \ @@ -42,10 +43,10 @@ /** * Set a block number in the media format given a number in the host format. * - * @param _h The buffer handle of the block. - * @param _b The block number index, ie the number of block number not the + * @param[in] _h is the buffer handle of the block. + * @param[in] _b is the block number index, ie the number of block number not the * buffer offset. - * @param _n The block number. + * @param[in] _n is the block number. */ #define rtems_rfs_block_set_number(_h, _b, _n) \ do { \ @@ -195,8 +196,8 @@ typedef struct rtems_rfs_block_map_s /** * Set the size offset for the map. The map is tagged as dirty. * - * @param map Pointer to the open map to set the offset in. - * @param offset The offset to set in the map's size. + * @param[in] map is a pointer to the open map to set the offset in. + * @param[in] offset is the offset to set in the map's size. */ static inline void rtems_rfs_block_map_set_size_offset (rtems_rfs_block_map* map, @@ -209,8 +210,8 @@ rtems_rfs_block_map_set_size_offset (rtems_rfs_block_map* map, /** * Set the map's size. The map is tagged as dirty. * - * @param map Pointer to the open map to set the offset in. - * @param size The size to set in the map's size. + * @param[in] map is a pointer to the open map to set the offset in. + * @param[in] size is the size to set in the map's size. */ static inline void rtems_rfs_block_map_set_size (rtems_rfs_block_map* map, @@ -224,10 +225,12 @@ rtems_rfs_block_map_set_size (rtems_rfs_block_map* map, * map. The buffer handles are opened. The block position is set to the start * so a seek of offset 0 will return the first block. * - * @param fs The file system data. - * @param inode The inode the map belongs to. - * @param map The map that is opened. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] inode is a pointer to the inode the map belongs to. + * @param[in] map is a pointer to the map that is opened. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_block_map_open (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* inode, @@ -237,9 +240,11 @@ int rtems_rfs_block_map_open (rtems_rfs_file_system* fs, * Close the map. The buffer handles are closed and any help buffers are * released. * - * @param fs The file system data. - * @param map The map that is opened. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] map is a pointer to the map that is opened. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_block_map_close (rtems_rfs_file_system* fs, rtems_rfs_block_map* map); @@ -247,11 +252,13 @@ int rtems_rfs_block_map_close (rtems_rfs_file_system* fs, /** * Find a block number in the map from the position provided. * - * @param fs The file system data. - * @param map The map to search. - * @param bpos The block position to find. - * @param block Pointer to place the block in when found. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] map is a pointer to the map to search. + * @param[in] bpos is a pointer to the block position to find. + * @param[out] block will contain the block in when found. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_block_map_find (rtems_rfs_file_system* fs, rtems_rfs_block_map* map, @@ -261,12 +268,14 @@ int rtems_rfs_block_map_find (rtems_rfs_file_system* fs, /** * Seek around the map. * - * @param fs The file system data. - * @param map The map to search. - * @param offset The distance to seek. It is signed. - * @param block Pointer to place the block in when found. + * @param[in] fs is the file system data. + * @param[in] map is a pointer to the map to search. + * @param[in] offset is the distance to seek. It is signed. + * @param[out] block will contain the block in when found. + * + * @retval 0 Successful operation. * @retval ENXIO Failed to seek because it is outside the block map. - * @return int The error number (errno). No error if 0. + * @retval error_code An error occurred. */ int rtems_rfs_block_map_seek (rtems_rfs_file_system* fs, rtems_rfs_block_map* map, @@ -276,11 +285,13 @@ int rtems_rfs_block_map_seek (rtems_rfs_file_system* fs, /** * Seek to the next block. * - * @param fs The file system data. - * @param map The map to search. - * @param block Pointer to place the block in when found. + * @param[in] fs is the file system data. + * @param[in] map is a pointer to the map to search. + * @param[out] block will contain the block in when found. + * + * @retval 0 Successful operation. * @retval ENXIO Failed to seek because it is outside the block map. - * @return int The error number (errno). No error if 0. + * @retval error_code An error occurred. */ int rtems_rfs_block_map_next_block (rtems_rfs_file_system* fs, rtems_rfs_block_map* map, @@ -289,11 +300,14 @@ int rtems_rfs_block_map_next_block (rtems_rfs_file_system* fs, /** * Grow the block map by the specified number of blocks. * - * @param fs The file system data. - * @param map Pointer to the open map to grow. - * @param blocks The number of blocks to grow the map by. - * @param new_block The first of the blocks allocated to the map. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] map is a pointer to the open map to grow. + * @param[in] blocks is the number of blocks to grow the map by. + * @param[out] new_block will contain first of the blocks allocated + * to the map. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_block_map_grow (rtems_rfs_file_system* fs, rtems_rfs_block_map* map, @@ -303,11 +317,13 @@ int rtems_rfs_block_map_grow (rtems_rfs_file_system* fs, /** * Grow the block map by the specified number of blocks. * - * @param fs The file system data. - * @param map Pointer to the open map to shrink. - * @param blocks The number of blocks to shrink the map by. If more than the - * number of blocks the map is emptied. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] map is a pointer to the open map to shrink. + * @param[in] blocks is the number of blocks to shrink the map by. If more + * than the number of blocks the map is emptied. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_block_map_shrink (rtems_rfs_file_system* fs, rtems_rfs_block_map* map, @@ -316,9 +332,11 @@ int rtems_rfs_block_map_shrink (rtems_rfs_file_system* fs, /** * Free all blocks in the map. * - * @param fs The file system data. - * @param map Pointer to the open map to free all blocks from. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] map is a pointer to the open map to free all blocks from. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_block_map_free_all (rtems_rfs_file_system* fs, rtems_rfs_block_map* map); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-buffer.h b/cpukit/libfs/src/rfs/rtems-rfs-buffer.h index c6b1f05c53..ec35e648d7 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-buffer.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-buffer.h @@ -159,14 +159,16 @@ typedef struct rtems_rfs_buffer_handle_t #define rtems_rfs_buffer_refs_down(_h) ((_h)->buffer->references -= 1) /** - * Request a buffer. The buffer can be filled with data from the media (read == - * true) or you can request a buffer to fill with data. + * Request a buffer. The buffer can be filled with data from the media + * (read == true) or you can request a buffer to fill with data. * - * @param fs The file system data. - * @param handle The handle the requested buffer is attached to. - * @param block The block number. - * @param read Read the data from the disk. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] handle is the handle the requested buffer is attached to. + * @param[in] block is the block number. + * @param[in] read Read the data from the disk. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_buffer_handle_request (rtems_rfs_file_system* fs, rtems_rfs_buffer_handle* handle, @@ -178,9 +180,11 @@ int rtems_rfs_buffer_handle_request (rtems_rfs_file_system* fs, * result does not indicate if the data was successfully written to the disk as * this operation may be performed in asynchronously to this release. * - * @param fs The file system data. - * @param handle The handle the requested buffer is attached to. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] handle is the handle the requested buffer is attached to. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_buffer_handle_release (rtems_rfs_file_system* fs, rtems_rfs_buffer_handle* handle); @@ -188,9 +192,11 @@ int rtems_rfs_buffer_handle_release (rtems_rfs_file_system* fs, /** * Open a handle. * - * @param fs The file system data. - * @param handle The buffer handle to open. - * @return int The error number (errno). No error if 0. + * @param[in] fs i the file system data. + * @param[in] handle i the buffer handle to open. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ static inline int rtems_rfs_buffer_handle_open (rtems_rfs_file_system* fs, @@ -205,9 +211,11 @@ rtems_rfs_buffer_handle_open (rtems_rfs_file_system* fs, /** * Close a handle. * - * @param fs The file system data. - * @param handle The buffer handle to close. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] handle is the buffer handle to close. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ static inline int rtems_rfs_buffer_handle_close (rtems_rfs_file_system* fs, @@ -223,42 +231,52 @@ rtems_rfs_buffer_handle_close (rtems_rfs_file_system* fs, /** * Open the buffer interface. * - * @param name The device name to the media. - * @param fs Pointer to the file system data. - * @return int The error number (errno). No error if 0. + * @param[in] name is a pointer to the device name to the media. + * @param[in] fs is the file system data. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_buffer_open (const char* name, rtems_rfs_file_system* fs); /** * Close the buffer interface. * - * @param fs Pointer to the file system data. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_buffer_close (rtems_rfs_file_system* fs); /** * Sync all buffers to the media. * - * @param fs Pointer to the file system data. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_buffer_sync (rtems_rfs_file_system* fs); /** * Set the block size of the device. * - * @param fs Pointer to the file system data. - * @param size The new block size. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] size is the new block size. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_buffer_setblksize (rtems_rfs_file_system* fs, size_t size); /** * Release any chained buffers. * - * @param fs The file system data. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_buffers_release (rtems_rfs_file_system* fs); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-dir-hash.h b/cpukit/libfs/src/rfs/rtems-rfs-dir-hash.h index f7908d8716..46b2719a7e 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-dir-hash.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-dir-hash.h @@ -26,9 +26,10 @@ /** * Compute a hash of the key over the length of string. * - * @param key The key to calculate the hash of. - * @param length The length of the key in bytes. - * @return uint32_t The hash. + * @param[in] key is a pointer to the key to calculate the hash of. + * @param[in] length is the length of the key in bytes. + * + * @retval hash The computed uint32_t hash. */ uint32_t rtems_rfs_dir_hash (const void *key, size_t length); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-dir.h b/cpukit/libfs/src/rfs/rtems-rfs-dir.h index 50c89eccc5..ddfcb5418e 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-dir.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-dir.h @@ -55,8 +55,9 @@ /** * Return the hash of the entry. * - * @param _e Pointer to the directory entry. - * @return uint32_t The hash. + * @param[in] _e is a pointer to the directory entry. + * + * @retval hash The uint32_t hash of the entry. */ #define rtems_rfs_dir_entry_hash(_e) \ rtems_rfs_read_u32 (_e + RTEMS_RFS_DIR_ENTRY_HASH) @@ -64,8 +65,9 @@ /** * Set the hash of the entry. * - * @param _e Pointer to the directory entry. - * @param _h The hash. + * @param[in] _e is a pointer to the directory entry. + * + * @param[in] _h is the hash of the entry. */ #define rtems_rfs_dir_set_entry_hash(_e, _h) \ rtems_rfs_write_u32 (_e + RTEMS_RFS_DIR_ENTRY_HASH, _h) @@ -73,8 +75,9 @@ /** * Return the ino of the entry. * - * @param _e Pointer to the directory entry. - * @return uint32_t The ino. + * @param[in] _e is a pointer to the directory entry. + * + * @retval ino The ino of the entry. */ #define rtems_rfs_dir_entry_ino(_e) \ rtems_rfs_read_u32 (_e + RTEMS_RFS_DIR_ENTRY_INO) @@ -82,8 +85,9 @@ /** * Set the ino of the entry. * - * @param _e Pointer to the directory entry. - * @param _i The ino. + * @param[in] _e is a pointer to the directory entry. + * + * @param[in] _i is the ino of the entry. */ #define rtems_rfs_dir_set_entry_ino(_e, _i) \ rtems_rfs_write_u32 (_e + RTEMS_RFS_DIR_ENTRY_INO, _i) @@ -91,8 +95,9 @@ /** * Return the length of the entry. * - * @param _e Pointer to the directory entry. - * @return uint16_t The length. + * @param[in] _e Pointer to the directory entry. + * + * @retval length The length of the entry. */ #define rtems_rfs_dir_entry_length(_e) \ rtems_rfs_read_u16 (_e + RTEMS_RFS_DIR_ENTRY_LEN) @@ -100,8 +105,8 @@ /** * Set the length of the entry. * - * @param _e Pointer to the directory entry. - * @param _l The length. + * @param[in] _e is a pointer to the directory entry. + * @param[in] _l is the length. */ #define rtems_rfs_dir_set_entry_length(_e, _l) \ rtems_rfs_write_u16 (_e + RTEMS_RFS_DIR_ENTRY_LEN, _l) @@ -110,13 +115,17 @@ * Look up a directory entry in the directory pointed to by the inode. The look * up is local to this directory. No need to decend. * - * @param fs The file system. - * @param inode The inode of the directory to search. - * @param name The name to look up. The name may not be nul terminated. - * @param length The length of the name. - * @param ino The return inode number if there is no error. - * @param offset The offset in the directory for the entry. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system. + * @param[in] inode is a pointer to the inode of the directory to search. + * @param[in] name is a pointer to the name to look up. The name may not be + * nul terminated. + * @param[in] length is the length of the name. + * @param[out] ino will be filled in with the inode number + * if there is no error. + * @param[in] offset is the offset in the directory for the entry. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_dir_lookup_ino (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* inode, @@ -129,12 +138,15 @@ int rtems_rfs_dir_lookup_ino (rtems_rfs_file_system* fs, * Add an entry to the directory returing the inode number allocated to the * entry. * - * @param fs The file system data. - * @param dir Pointer to the directory inode the entry is to be added too. - * @param name The name of the entry to be added. - * @param length The length of the name excluding a terminating 0. - * @param ino The ino of the entry. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] dir is a pointer to the directory inode the + * entry is to be added too. + * @param[in] name is a pointer to the name of the entry to be added. + * @param[in] length is the length of the name excluding a terminating 0. + * @param[in] ino is the ino of the entry. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_dir_add_entry (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* dir, @@ -145,12 +157,15 @@ int rtems_rfs_dir_add_entry (rtems_rfs_file_system* fs, /** * Del an entry from the directory using an inode number as a key. * - * @param fs The file system data. - * @param dir Pointer to the directory inode the entry is to be deleted from. - * @param ino The ino of the entry. - * @param offset The offset in the directory of the entry to delete. If 0 - * search from the start for the ino. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] dir is a pointer to the directory inode the + * entry is to be deleted from. + * @param[in] ino is the ino of the entry. + * @param[in] offset is the offset in the directory of the entry + * to delete. If 0 search from the start for the ino. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_dir_del_entry (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* dir, @@ -161,12 +176,16 @@ int rtems_rfs_dir_del_entry (rtems_rfs_file_system* fs, * Read the directory entry from offset into the directory entry buffer and * return the length of space this entry uses in the directory table. * - * @param fs The file system data. - * @param dir The direct inode handler. - * @param offset The offset in the directory to read from. - * @param dirent Pointer to the dirent structure the entry is written into. - * @param length Set the length this entry takes in the directory. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] dir is a pointer to the direct inode handler. + * @param[in] offset is the offset in the directory to read from. + * @param[in] dirent is a ointer to the dirent structure the entry + * is written into. + * @param[out] length will contain the length this entry + * takes in the directory. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_dir_read (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* dir, @@ -178,9 +197,11 @@ int rtems_rfs_dir_read (rtems_rfs_file_system* fs, * Check if the directory is empty. The current and parent directory entries * are ignored. * - * @param fs The file system data - * @param dir The directory inode to check. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data + * @param[in] dir is a pointer to the directory inode to check. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_dir_empty (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* dir); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-file-system-fwd.h b/cpukit/libfs/src/rfs/rtems-rfs-file-system-fwd.h index ae45acf55e..19b03587e1 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-file-system-fwd.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-file-system-fwd.h @@ -1,7 +1,7 @@ /** * @file * - * @brief RTEMS File Systems Data forward decl + * @brief RTEMS File Systems Data Forward Declaration * * @ingroup rtems-rfs * diff --git a/cpukit/libfs/src/rfs/rtems-rfs-file-system.h b/cpukit/libfs/src/rfs/rtems-rfs-file-system.h index c1f3dd7465..1d059ae92c 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-file-system.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-file-system.h @@ -50,8 +50,8 @@ #define RTEMS_RFS_VERSION_MASK INT32_C(0x00000000) /** - * The root inode number. Do not use 0 as this has special meaning in some Unix - * operating systems. + * The root inode number. Do not use 0 as this has special meaning in some + * Unix operating systems. */ #define RTEMS_RFS_ROOT_INO (1) @@ -61,8 +61,8 @@ #define RTEMS_RFS_EMPTY_INO (0) /** - * The number of blocks in the inode. This number effects the size of the inode - * and that effects the overhead of the inode tables in a group. + * The number of blocks in the inode. This number effects the size of the + * inode and that effects the overhead of the inode tables in a group. */ #define RTEMS_RFS_INODE_BLOCKS (5) @@ -262,27 +262,27 @@ struct _rtems_rfs_file_system /** * Return the flags. * - * @param _fs Pointer to the file system. + * @param[in] _fs is a pointer to the file system. */ #define rtems_rfs_fs_flags(_f) ((_f)->flags) /** * Should bitmap buffers be released when finished ? * - * @param _fs Pointer to the file system. + * @param[in] _fs is a pointer to the file system. */ #define rtems_rfs_fs_release_bitmaps(_f) (!((_f)->flags & RTEMS_RFS_FS_BITMAPS_HOLD)) /** * Are the buffers locally cache or released back to the buffering layer ? * - * @param _fs Pointer to the file system. + * @param[in] _fs is a pointer to the file system. */ #define rtems_rfs_fs_no_local_cache(_f) ((_f)->flags & RTEMS_RFS_FS_NO_LOCAL_CACHE) /** * The disk device number. * - * @param _fs Pointer to the file system. + * @param[in] _fs is a pointer to the file system. */ #if RTEMS_RFS_USE_LIBBLOCK #define rtems_rfs_fs_device(_fs) ((_fs)->disk) @@ -293,21 +293,21 @@ struct _rtems_rfs_file_system /** * The size of the disk in blocks. * - * @param _fs Pointer to the file system. + * @param[in] _fs is a pointer to the file system. */ #define rtems_rfs_fs_blocks(_fs) ((_fs)->blocks) /** * The block size. * - * @param _fs Pointer to the file system. + * @param[in] _fs is a pointer to the file system. */ #define rtems_rfs_fs_block_size(_fs) ((_fs)->block_size) /** * The number of inodes. * - * @param _fs Pointer to the file system. + * @param[in] _fs is a pointer to the file system. */ #define rtems_rfs_fs_inodes(_fs) ((_fs)->inodes) @@ -315,9 +315,9 @@ struct _rtems_rfs_file_system * Calculate a block in the file system given the group and the block within * the group. * - * @param _fs Pointer to the file system. - * @param _grp The group. - * @param _blk The block within the group. + * @param[in] _fs is a pointer to the file system. + * @param[in] _grp is the group. + * @param[in] _blk is the block within the group. * @return The absolute block number. */ #define rtems_rfs_fs_block(_fs, _grp, _blk) \ @@ -326,7 +326,7 @@ struct _rtems_rfs_file_system /** * The media size of the disk in media size blocks. * - * @param _fs Pointer to the file system. + * @param[in] _fs is a pointer to the file system. */ #if RTEMS_RFS_USE_LIBBLOCK #define rtems_rfs_fs_media_blocks(_fs) ((_fs)->disk->size) @@ -338,7 +338,7 @@ struct _rtems_rfs_file_system * The media block size. This is the size of a block on disk. For a device I/O * this value is 1. * - * @param _fs Pointer to the file system. + * @param[in] _fs is a pointer to the file system. */ #if RTEMS_RFS_USE_LIBBLOCK #define rtems_rfs_fs_media_block_size(_fs) ((_fs)->disk->media_block_size) @@ -366,7 +366,7 @@ struct _rtems_rfs_file_system /** * Return the size of the disk in bytes. * - * @param fs Pointer to the file system. + * @param[in] fs is a pointer to the file system. * @return uint64_t The size of the disk in bytes. */ uint64_t rtems_rfs_fs_size(rtems_rfs_file_system* fs); @@ -374,7 +374,7 @@ uint64_t rtems_rfs_fs_size(rtems_rfs_file_system* fs); /** * The size of the disk in bytes calculated from the media parameters.. * - * @param fs Pointer to the file system. + * @param[in] fs is a pointer to the file system. * @return uint64_t The size of the disk in bytes. */ uint64_t rtems_rfs_fs_media_size (rtems_rfs_file_system* fs); @@ -382,12 +382,14 @@ uint64_t rtems_rfs_fs_media_size (rtems_rfs_file_system* fs); /** * Open the file system given a file path. * - * @param name The device to open. - * @param fs The file system data filled in by this call. - * @param user A pointer to user data. - * @param flags The initial set of user flags for the file system. - * @param max_held_buffers The maximum number of buffers the RFS holds. - * @return int The error number (errno). No error if 0. + * @param[in] name is a pointer to the device to open. + * @param[in] fs is the file system data filled in by this call. + * @param[in] user is a pointer to the user data. + * @param[in] flags is a initial set of user flags for the file system. + * @param[in] max_held_buffers is the maximum number of buffers the RFS holds. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_fs_open (const char* name, void* user, @@ -398,8 +400,10 @@ int rtems_rfs_fs_open (const char* name, /** * Close the file system. * - * @param fs The file system data. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_fs_close (rtems_rfs_file_system* fs); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-file.h b/cpukit/libfs/src/rfs/rtems-rfs-file.h index f39f02a985..9665c60ea5 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-file.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-file.h @@ -89,8 +89,9 @@ typedef struct _rtems_rfs_file_shared /** * Get the atime. * - * @param shared The shared file data. - * @return rtems_rfs_time The atime. + * @param[in] shared is a pointer to the shared file data. + * + * @retval atime The atime. */ static inline rtems_rfs_time rtems_rfs_file_shared_get_atime (rtems_rfs_file_shared* shared) @@ -101,8 +102,9 @@ rtems_rfs_file_shared_get_atime (rtems_rfs_file_shared* shared) /** * Get the mtime. * - * @param shared The shared file data. - * @return rtems_rfs_time The mtime. + * @param[in] shared is a pointer to the shared file data. + * + * @retval mtime The mtime. */ static inline rtems_rfs_time rtems_rfs_file_shared_get_mtime (rtems_rfs_file_shared* shared) @@ -113,8 +115,9 @@ rtems_rfs_file_shared_get_mtime (rtems_rfs_file_shared* shared) /** * Get the ctime. * - * @param shared The shared file data. - * @return rtems_rfs_time The ctime. + * @param[in] shared is a pointer to the shared file data. + * + * @retval ctime The ctime. */ static inline rtems_rfs_time rtems_rfs_file_shared_get_ctime (rtems_rfs_file_shared* shared) @@ -125,8 +128,9 @@ rtems_rfs_file_shared_get_ctime (rtems_rfs_file_shared* shared) /** * Get the block count. * - * @param shared The shared file data. - * @return uint32_t The block count. + * @param[in] shared is a pointer to the shared file data. + * + * @retval count The block count. */ static inline uint32_t rtems_rfs_file_shared_get_block_count (rtems_rfs_file_shared* shared) @@ -137,8 +141,9 @@ rtems_rfs_file_shared_get_block_count (rtems_rfs_file_shared* shared) /** * Get the block offset. * - * @param shared The shared file data. - * @return uint16_t The block offset. + * @param shared is a pointer to the shared file data. + * + * @retval offset The block offset. */ static inline uint16_t rtems_rfs_file_shared_get_block_offset (rtems_rfs_file_shared* shared) @@ -149,9 +154,10 @@ rtems_rfs_file_shared_get_block_offset (rtems_rfs_file_shared* shared) /** * Calculate the size of data. * - * @param fs The file system data. - * @oaram shared The shared file data. - * @return rtems_rfs_pos The data size in bytes. + * @param[in] fs is the file system data. + * @param[in] shared is a pointer to the shared file data. + * + * @retval data The data size in bytes. */ static inline rtems_rfs_pos rtems_rfs_file_shared_get_size (rtems_rfs_file_system* fs, @@ -292,10 +298,12 @@ typedef struct _rtems_rfs_file_handle /** * Open a file handle. * - * @param fs The file system. - * @param ino The inode number of the file to be opened. - * @param handle Return the handle pointer in this handle. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system. + * @param[in] ino is the inode number of the file to be opened. + * @param[out] handle will be filled in with the handle pointer. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_file_open (rtems_rfs_file_system* fs, rtems_rfs_ino ino, @@ -305,9 +313,11 @@ int rtems_rfs_file_open (rtems_rfs_file_system* fs, /** * Close an open file handle. * - * @param fs The file system. - * @param handle The open file handle. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system. + * @param[in] handle is the open file handle. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_file_close (rtems_rfs_file_system* fs, rtems_rfs_file_handle* handle); @@ -321,10 +331,12 @@ int rtems_rfs_file_close (rtems_rfs_file_system* fs, * I/O past the end of a block so the call returns the amount of data * available. * - * @param handle The file handle. - * @param available The amount of data available for I/O. - * @param read The I/O operation is a read so the block is read from the media. - * @return int The error number (errno). No error if 0. + * @param[in] handle is the file handle. + * @param[in] available is the amount of data available for I/O. + * @param[in] read is the I/O operation is a read so the block is read from the media. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_file_io_start (rtems_rfs_file_handle* handle, size_t* available, @@ -337,10 +349,12 @@ int rtems_rfs_file_io_start (rtems_rfs_file_handle* handle, * * If the file's position is updated by the size amount. * - * @param handle The file handle. - * @param size The amount of data read or written. - * @param read The I/O was a read if true else it was a write. - * @return int The error number (errno). No error if 0. + * @param[in] handle is the file handle. + * @param[in] size is the amount of data read or written. + * @param[in] read is the I/O was a read if true else it was a write. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_file_io_end (rtems_rfs_file_handle* handle, size_t size, @@ -351,8 +365,10 @@ int rtems_rfs_file_io_end (rtems_rfs_file_handle* handle, * buffer and the buffer was not already released as modified the data will be * lost. * - * @param handle The file handle. - * @return int The error number (errno). No error if 0. + * @param[in] handle is the file handle. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_file_io_release (rtems_rfs_file_handle* handle); @@ -360,10 +376,12 @@ int rtems_rfs_file_io_release (rtems_rfs_file_handle* handle); * The file to the position returning the old position. The position is * abolute. * - * @param handle The file handle. - * @param pos The position to seek to. - * @param new_pos The actual position. - * @return int The error number (errno). No error if 0. + * @param[in] handle The file handle. + * @param[in] pos is the position to seek to. + * @param[out] new_pos will contain the actual position. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_file_seek (rtems_rfs_file_handle* handle, rtems_rfs_pos pos, @@ -373,9 +391,10 @@ int rtems_rfs_file_seek (rtems_rfs_file_handle* handle, * Set the size of the file to the new size. This can extend the file to a new * size. * - * @param handle The file handle. - * @param size The new size of the file. - * @return int The error number (errno). No error if 0. + * @param[in] handle is the file handle. + * @param[in] size is the new size of the file. + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_file_set_size (rtems_rfs_file_handle* handle, rtems_rfs_pos size); @@ -383,9 +402,12 @@ int rtems_rfs_file_set_size (rtems_rfs_file_handle* handle, /** * Return the shared file data for an ino. * - * @param fs The file system data. - * @param ino The inode number to locate the data for. + * @param[in] fs is the file system data. + * @param[in] ino is the inode number to locate the data for. * @return rtems_rfs_file_shared* The shared data or NULL is not located. + * + * @retval shared The shared data. + * @retval NULL No shared file data is located. */ rtems_rfs_file_shared* rtems_rfs_file_get_shared (rtems_rfs_file_system* fs, rtems_rfs_ino ino); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-format.h b/cpukit/libfs/src/rfs/rtems-rfs-format.h index 56b1aa9d82..f0d9f0c2b1 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-format.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-format.h @@ -75,8 +75,9 @@ typedef struct _rtems_rfs_format_config /** * RFS Format command. * - * @param name The device name to format. - * @param config Pointer to a configuration table. + * @param[in] name is the device name to format. + * @param[in] config is a pointer to the configuration table. + * * @retval -1 Error. See errno. * @retval 0 No error. Format successful. */ diff --git a/cpukit/libfs/src/rfs/rtems-rfs-inode.h b/cpukit/libfs/src/rfs/rtems-rfs-inode.h index a26232fdc3..a8be80f6ff 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-inode.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-inode.h @@ -230,8 +230,9 @@ typedef struct _rtems_rfs_inode_handle /** * Get the link count. * - * @param handle The inode handle. - * @return uint16_t The link count. + * @param[in] handle is the inode handle. + * + * @retval links The link count. */ static inline uint16_t rtems_rfs_inode_get_links (rtems_rfs_inode_handle* handle) @@ -246,8 +247,8 @@ rtems_rfs_inode_get_links (rtems_rfs_inode_handle* handle) /** * Set the link count. * - * @param handle The inode handle. - * @prarm links The links. + * @param[in] handle is the inode handle. + * @param[in] links are the links. */ static inline void rtems_rfs_inode_set_links (rtems_rfs_inode_handle* handle, uint16_t links) @@ -259,8 +260,9 @@ rtems_rfs_inode_set_links (rtems_rfs_inode_handle* handle, uint16_t links) /** * Get the flags. * - * @param handle The inode handle. - * @return uint16_t The flags. + * @param[in] handle is the inode handle. + * + * @retval flags The flags. */ static inline uint16_t rtems_rfs_inode_get_flags (rtems_rfs_inode_handle* handle) @@ -271,8 +273,8 @@ rtems_rfs_inode_get_flags (rtems_rfs_inode_handle* handle) /** * Set the flags. * - * @param handle The inode handle. - * @prarm flags The flags. + * @param[in] handle is the inode handle. + * @param[in] flags are the flags. */ static inline void rtems_rfs_inode_set_flags (rtems_rfs_inode_handle* handle, uint16_t flags) @@ -284,8 +286,9 @@ rtems_rfs_inode_set_flags (rtems_rfs_inode_handle* handle, uint16_t flags) /** * Get the mode. * - * @param handle The inode handle. - * @return uint16_t The mode. + * @param[in] handle is the inode handle. + * + * @retval mode The mode. */ static inline uint16_t rtems_rfs_inode_get_mode (rtems_rfs_inode_handle* handle) @@ -296,8 +299,8 @@ rtems_rfs_inode_get_mode (rtems_rfs_inode_handle* handle) /** * Set the mode. * - * @param handle The inode handle. - * @prarm mode The mode. + * @param[in] handle is the inode handle. + * @param[in] mode is the mode. */ static inline void rtems_rfs_inode_set_mode (rtems_rfs_inode_handle* handle, uint16_t mode) @@ -309,8 +312,9 @@ rtems_rfs_inode_set_mode (rtems_rfs_inode_handle* handle, uint16_t mode) /** * Get the user id. * - * @param handle The inode handle. - * @return uint16_t The user id (uid). + * @param[in] handle is the inode handle. + * + * @retval uid The used id. */ static inline uint16_t rtems_rfs_inode_get_uid (rtems_rfs_inode_handle* handle) @@ -321,8 +325,9 @@ rtems_rfs_inode_get_uid (rtems_rfs_inode_handle* handle) /** * Get the group id. * - * @param handle The inode handle. - * @return uint16_t The group id (gid). + * @param[in] handle is the inode handle. + * + * @retval gid The grpup id. */ static inline uint16_t rtems_rfs_inode_get_gid (rtems_rfs_inode_handle* handle) @@ -333,9 +338,9 @@ rtems_rfs_inode_get_gid (rtems_rfs_inode_handle* handle) /** * Set the user id and group id. * - * @param handle The inode handle. - * @param uid The user id (uid). - * @param gid The group id (gid). + * @param[in] handle is the inode handle. + * @param[in] uid is the user id (uid). + * @param[in] gid is the group id (gid). */ static inline void rtems_rfs_inode_set_uid_gid (rtems_rfs_inode_handle* handle, @@ -348,8 +353,9 @@ rtems_rfs_inode_set_uid_gid (rtems_rfs_inode_handle* handle, /** * Get the block offset. * - * @param handle The inode handle. - * @return uint32_t The block offset. + * @param[in] handle is the inode handle. + * + * @retval offset The block offset. */ static inline uint16_t rtems_rfs_inode_get_block_offset (rtems_rfs_inode_handle* handle) @@ -360,8 +366,8 @@ rtems_rfs_inode_get_block_offset (rtems_rfs_inode_handle* handle) /** * Set the block offset. * - * @param handle The inode handle. - * @param block_count The block offset. + * @param[in] handle is the inode handle. + * @param[in] block_count is the block offset. */ static inline void rtems_rfs_inode_set_block_offset (rtems_rfs_inode_handle* handle, @@ -374,8 +380,9 @@ rtems_rfs_inode_set_block_offset (rtems_rfs_inode_handle* handle, /** * Get the block count. * - * @param handle The inode handle. - * @return uint32_t The block count. + * @param[in] handle is the inode handle. + * + * @retval count The block count. */ static inline uint32_t rtems_rfs_inode_get_block_count (rtems_rfs_inode_handle* handle) @@ -386,8 +393,8 @@ rtems_rfs_inode_get_block_count (rtems_rfs_inode_handle* handle) /** * Set the block count. * - * @param handle The inode handle. - * @param block_count The block count. + * @param[in] handle is the inode handle. + * @param[in] block_count is the block count. */ static inline void rtems_rfs_inode_set_block_count (rtems_rfs_inode_handle* handle, uint32_t block_count) @@ -399,8 +406,9 @@ rtems_rfs_inode_set_block_count (rtems_rfs_inode_handle* handle, uint32_t block_ /** * Get the atime. * - * @param handle The inode handle. - * @return rtems_rfs_time The atime. + * @param[in] handle is the inode handle. + * + * @retval atime The atime. */ static inline rtems_rfs_time rtems_rfs_inode_get_atime (rtems_rfs_inode_handle* handle) @@ -411,8 +419,8 @@ rtems_rfs_inode_get_atime (rtems_rfs_inode_handle* handle) /** * Set the atime. * - * @param handle The inode handle. - * @prarm atime The atime. + * @param[in] handle is the inode handle. + * @param[in] atime The atime. */ static inline void rtems_rfs_inode_set_atime (rtems_rfs_inode_handle* handle, @@ -425,8 +433,9 @@ rtems_rfs_inode_set_atime (rtems_rfs_inode_handle* handle, /** * Get the mtime. * - * @param handle The inode handle. - * @return rtems_rfs_time The mtime. + * @param[in] handle is the inode handle. + * + * @retval mtime The mtime. */ static inline rtems_rfs_time rtems_rfs_inode_get_mtime (rtems_rfs_inode_handle* handle) @@ -437,8 +446,8 @@ rtems_rfs_inode_get_mtime (rtems_rfs_inode_handle* handle) /** * Set the mtime. * - * @param handle The inode handle. - * @prarm atime The mtime. + * @param[in] handle is the inode handle. + * @param[in] mtime The mtime. */ static inline void rtems_rfs_inode_set_mtime (rtems_rfs_inode_handle* handle, @@ -451,8 +460,9 @@ rtems_rfs_inode_set_mtime (rtems_rfs_inode_handle* handle, /** * Get the ctime. * - * @param handle The inode handle. - * @return rtems_rfs_time The ctime. + * @param[in] handle is the inode handle. + * + * @retval ctime The ctime. */ static inline rtems_rfs_time rtems_rfs_inode_get_ctime (rtems_rfs_inode_handle* handle) @@ -463,8 +473,8 @@ rtems_rfs_inode_get_ctime (rtems_rfs_inode_handle* handle) /** * Set the ctime. * - * @param handle The inode handle. - * @prarm atime The ctime. + * @param[in] handle is the inode handle. + * @param[in] ctime The ctime. */ static inline void rtems_rfs_inode_set_ctime (rtems_rfs_inode_handle* handle, @@ -477,9 +487,10 @@ rtems_rfs_inode_set_ctime (rtems_rfs_inode_handle* handle, /** * Get the block number. * - * @param handle The inode handle. - * @param block The block number to return. - * @return uint32_t The block number. + * @param[in] handle is the inode handle. + * @param[in] block is the block number to return. + * + * @retval block The block number. */ static inline uint32_t rtems_rfs_inode_get_block (rtems_rfs_inode_handle* handle, int block) @@ -490,9 +501,9 @@ rtems_rfs_inode_get_block (rtems_rfs_inode_handle* handle, int block) /** * Set the block number for a given block index. * - * @param handle The inode handle. - * @param block The block index. - * @param bno The block number. + * @param[in] handle is the inode handle. + * @param[in] block is the block index. + * @param[in] bno is the block number. */ static inline void rtems_rfs_inode_set_block (rtems_rfs_inode_handle* handle, int block, uint32_t bno) @@ -504,8 +515,9 @@ rtems_rfs_inode_set_block (rtems_rfs_inode_handle* handle, int block, uint32_t b /** * Get the last map block from the inode. * - * @param handle The inode handle. - * @return uint32_t The last map block number. + * @param[in] handle is the inode handle. + * + * @retval block The last map block number. */ static inline uint32_t rtems_rfs_inode_get_last_map_block (rtems_rfs_inode_handle* handle) @@ -516,8 +528,8 @@ rtems_rfs_inode_get_last_map_block (rtems_rfs_inode_handle* handle) /** * Set the last map block. * - * @param handle The inode handle. - * @param block_count The last map block number. + * @param[in] handle is the inode handle. + * @param[in] block_count is last map block number. */ static inline void rtems_rfs_inode_set_last_map_block (rtems_rfs_inode_handle* handle, uint32_t last_map_block) @@ -529,8 +541,10 @@ rtems_rfs_inode_set_last_map_block (rtems_rfs_inode_handle* handle, uint32_t las /** * Get the last data block from the inode. * - * @param handle The inode handle. - * @return uint32_t The last data block number. + * @param[in] handle is the inode handle. + * + * @retval block The last data block number. + * */ static inline uint32_t rtems_rfs_inode_get_last_data_block (rtems_rfs_inode_handle* handle) @@ -541,8 +555,8 @@ rtems_rfs_inode_get_last_data_block (rtems_rfs_inode_handle* handle) /** * Set the last data block. * - * @param handle The inode handle. - * @param block_count The last data block number. + * @param[in] handle is the inode handle. + * @param[in] block_count is the last data block number. */ static inline void rtems_rfs_inode_set_last_data_block (rtems_rfs_inode_handle* handle, uint32_t last_data_block) @@ -554,20 +568,24 @@ rtems_rfs_inode_set_last_data_block (rtems_rfs_inode_handle* handle, uint32_t la /** * Allocate an inode number and return it. * - * @param fs The file system data. - * @param ino Return the ino. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[out] ino will contain the ino. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_inode_alloc (rtems_rfs_file_system* fs, rtems_rfs_bitmap_bit goal, rtems_rfs_ino* ino); /** - * Allocate an inode number and return it. + * Free an inode. * - * @param fs The file system data. - * @param ino The ino too free. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] ino is the ino too free. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_inode_free (rtems_rfs_file_system* fs, rtems_rfs_ino ino); @@ -577,11 +595,13 @@ int rtems_rfs_inode_free (rtems_rfs_file_system* fs, * data pointer. All data is in media byte order and needs to be accessed via * the supporting calls. * - * @param fs The file system. - * @param ino The inode number. - * @param handle The handle to the inode we are opening. - * @param load If true load the inode into memory from the media. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system. + * @param[in] ino is the inode number. + * @param[in] handle is the handle to the inode we are opening. + * @param[in] load If true load the inode into memory from the media. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_inode_open (rtems_rfs_file_system* fs, rtems_rfs_ino ino, @@ -591,9 +611,11 @@ int rtems_rfs_inode_open (rtems_rfs_file_system* fs, /** * The close inode handle. All opened inodes need to be closed. * - * @param fs The file system. - * @param handle The handle to close. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system. + * @param[in] handle is the handle to close. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_inode_close (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* handle); @@ -601,9 +623,11 @@ int rtems_rfs_inode_close (rtems_rfs_file_system* fs, /** * Load the inode into memory. * - * @param fs The file system. - * @param handle The inode handle to load. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system. + * @param[in] handle is the inode handle to load. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_inode_load (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* handle); @@ -611,10 +635,12 @@ int rtems_rfs_inode_load (rtems_rfs_file_system* fs, /** * Unload the inode from memory. * - * @param fs The file system. - * @param handle The inode handle to unload. - * @param update_ctime Update the ctime field of the inode. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system. + * @param[in] handle is the inode handle to unload. + * @param[in] update_ctime Update the ctime field of the inode. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_inode_unload (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* handle, @@ -624,9 +650,10 @@ int rtems_rfs_inode_unload (rtems_rfs_file_system* fs, * Create an inode allocating, initialising and adding an entry to the parent * directory. * - * @param fs The file system data. - * @param parent The parent inode number to add the directory entry to. - * @param name The name of the directory entryinode to create. + * @param[in] fs is the file system data. + * @param[in] parent is the parent inode number to add the directory entry to. + * @param[in] name is a pointer to the name of the directory entryinode + * to create. * */ int rtems_rfs_inode_create (rtems_rfs_file_system* fs, @@ -643,9 +670,11 @@ int rtems_rfs_inode_create (rtems_rfs_file_system* fs, * Delete the inode eraseing it and release the buffer to commit the write. You * need to load the inode again if you wish to use it again. * - * @param fs The file system. - * @param handle The inode handle to erase. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system. + * @param[in] handle is the inode handle to erase. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_inode_delete (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* handle); @@ -653,12 +682,14 @@ int rtems_rfs_inode_delete (rtems_rfs_file_system* fs, /** * Initialise a new inode. * - * @param handle The inode handle to initialise. - * @param links The number of links to the inode. - * @param mode The inode mode. - * @param uid The user id. - * @param gid The group id. - * @return int The error number (errno). No error if 0. + * @param[in] handle is the inode handle to initialise. + * @param[in] links are the number of links to the inode. + * @param[in] mode is the inode mode. + * @param[in] uid is the user id. + * @param[in] gid is the group id. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_inode_initialise (rtems_rfs_inode_handle* handle, uint16_t links, @@ -670,11 +701,13 @@ int rtems_rfs_inode_initialise (rtems_rfs_inode_handle* handle, * Time stamp the inode with the current time. The ctime field is hanlded * automatically. * - * @param handle The inode handle. - * @param atime Update the atime field. - * @param mtime UPdate the mtime field. - * @return int The error number (errno). No error if 0 and ENXIO if no inode - * loaded. + * @param[in] handle is the inode handle. + * @param[in] atime Update the atime field. + * @param[in] mtime UPdate the mtime field. + * + * @retval 0 Successful operation. + * @retval ENXIO No inode is loaded. + * @retval error_code An error occurred. */ int rtems_rfs_inode_time_stamp_now (rtems_rfs_inode_handle* handle, bool atime, @@ -683,10 +716,10 @@ int rtems_rfs_inode_time_stamp_now (rtems_rfs_inode_handle* handle, /** * Calculate the size of data attached to the inode. * - * @param fs The file system data. - * @param handle The inode handle. - * @return rtems_rfs_pos The data size in bytes in the block map attched to the - * inode. + * @param[in] fs is the file system data. + * @param[in] handle is the inode handle. + * + * @retval size The data size in bytes in the block map attched to the inode. */ rtems_rfs_pos rtems_rfs_inode_get_size (rtems_rfs_file_system* fs, rtems_rfs_inode_handle* handle); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-link.h b/cpukit/libfs/src/rfs/rtems-rfs-link.h index 0f473f2200..6a1cf18f6d 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-link.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-link.h @@ -41,13 +41,16 @@ typedef enum rtems_rfs_unlink_dir_e * Create a link. Do not link directories unless renaming or you will create * loops in the file system. * - * @param fs The file system. - * @param name The name of the link. - * @param length The length of the name. - * @param parent The inode number of the parent directory. - * @param target The inode of the target. - * @param link_dir If true directories can be linked. Useful when renaming. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system. + * @param[in] name is a pointer to the name of the link. + * @param[in] length is the length of the name. + * @param[in] parent is the inode number of the parent directory. + * @param[in] target is the inode of the target. + * @param[in] link_dir If true directories can be linked. Useful when + * renaming. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_link (rtems_rfs_file_system* fs, const char* name, @@ -57,16 +60,18 @@ int rtems_rfs_link (rtems_rfs_file_system* fs, bool link_dir); /** - * Unlink the node from the parent directory. A directory offset for the target - * entry is required because links cause a number of inode numbers to appear in - * a single directory so scanning does not work. + * Unlink the node from the parent directory. A directory offset for the + * target entry is required because links cause a number of inode numbers to + * appear in a single directory so scanning does not work. + * + * @param[in] fs is the file system. + * @param[in] parent is the inode number of the parent directory. + * @param[in] target is the inode of the target. + * @param[in] doff is the parent directory entry offset for the target entry. + * @param[in] dir_mode is the directory unlink mode. * - * @param fs The file system. - * @param parent The inode number of the parent directory. - * @param target The inode of the target. - * @param doff Parent directory entry offset for the target entry. - * @param dir_mode Directory unlink mode. - * @return int The error number (errno). No error if 0. + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_unlink (rtems_rfs_file_system* fs, rtems_rfs_ino parent, @@ -77,13 +82,16 @@ int rtems_rfs_unlink (rtems_rfs_file_system* fs, /** * Symbolic link is an inode that has a path attached. * - * @param fs The file system data. - * @param name The name of the node. - * @param length The length of the name of the node. - * @param link The link path attached to the symlink inode. - * @param link_length The length of the link path. - * @param parent The parent inode number. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] name is a pointer to the name of the node. + * @param[in] length is the length of the name of the node. + * @param[in] link is a pointer to the link path attached to the + * symlink inode. + * @param[in] link_length is the length of the link path. + * @param[in] parent is the parent inode number. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_symlink (rtems_rfs_file_system* fs, const char* name, @@ -98,12 +106,14 @@ int rtems_rfs_symlink (rtems_rfs_file_system* fs, * Read a symbolic link into the provided buffer returning the link of link * name. * - * @param fs The file system data. - * @param link The link inode number to read. - * @param path The buffer to write the link path into. - * @param size The size of the buffer. - * @param length Set to the length of the link path. - * @return int The error number (errno). No error if 0. + * @param[in] fs is the file system data. + * @param[in] link is the link inode number to read. + * @param[in] path is a pointer to the buffer to write the link path into. + * @param[in] size is the size of the buffer. + * @param[out] length will contain the length of the link path. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_rfs_symlink_read (rtems_rfs_file_system* fs, rtems_rfs_ino link, diff --git a/cpukit/libfs/src/rfs/rtems-rfs-mutex.h b/cpukit/libfs/src/rfs/rtems-rfs-mutex.h index ac04aeea1a..edf67f4f7b 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-mutex.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-mutex.h @@ -41,27 +41,33 @@ typedef uint32_t rtems_rfs_mutex; /* place holder */ #endif /** - * Create the mutex. + * @brief Create the mutex. + * + * @param [in] mutex is pointer to the mutex handle returned to the caller. + * + * @retval 0 Successful operation. + * @retval EIO An error occurred. * - * @param mutex Reference to the mutex handle returned to the caller. - * @return int The error number (errno). No error if 0. */ int rtems_rfs_mutex_create (rtems_rfs_mutex* mutex); /** - * Create the mutex. + * @brief Destroy the mutex. + * + * @param[in] mutex Reference to the mutex handle returned to the caller. * - * @param mutex Reference to the mutex handle returned to the caller. - * @return int The error number (errno). No error if 0. + * @retval 0 Successful operation. + * @retval EIO An error occurred. */ int rtems_rfs_mutex_destroy (rtems_rfs_mutex* mutex); /** - * Lock the mutex. + * @brief Lock the mutex. * - * @param mutex The mutex to lock. - * @retval true The mutex is locked. - * @retval false The mutex could not be locked. + * @param[in] mutex is a pointer to the mutex to lock. + * + * @retval 0 Successful operation. + * @retval EIO An error occurred. */ static inline int rtems_rfs_mutex_lock (rtems_rfs_mutex* mutex) @@ -82,11 +88,12 @@ rtems_rfs_mutex_lock (rtems_rfs_mutex* mutex) } /** - * Unlock the mutex. + * @brief Unlock the mutex. + * + * @param[in] mutex is a pointer to the mutex to unlock. * - * @param mutex The mutex to unlock. - * @retval true The mutex is unlocked. - * @retval false The mutex could not be unlocked. + * @retval 0 Successful operation. + * @retval EIO An error occurred. */ static inline int rtems_rfs_mutex_unlock (rtems_rfs_mutex* mutex) diff --git a/cpukit/libfs/src/rfs/rtems-rfs-rtems.h b/cpukit/libfs/src/rfs/rtems-rfs-rtems.h index 00fcb27143..bbff3aeaf3 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-rtems.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-rtems.h @@ -1,10 +1,3 @@ -/* - * COPYRIGHT (c) 2010 Chris Johns - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.com/license/LICENSE. - */ /** * @file * @@ -15,6 +8,14 @@ * This file is not to be installed. It binds the RFS file system to RTEMS. */ +/* + * COPYRIGHT (c) 2010 Chris Johns + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.com/license/LICENSE. + */ + #if !defined(RTEMS_RFS_RTEMS_DEFINED) #define RTEMS_RFS_RTEMS_DEFINED @@ -44,10 +45,12 @@ * Take the result code and set errno with it and if non-zero return -1 else * return 0. * - * @param what The message to print is the error is not zero. - * @param error The error code. - * @retval -1 An error has occurred. - * @retval 0 No error. + * @param[in] what is a pointer to the message to print if the error + * is not zero. + * @param[in] error is the error code. + * + * @retval 0 Successful operation. + * @retval -1 An error occurred. */ int rtems_rfs_rtems_error (const char* mesg, int error); #endif @@ -84,7 +87,8 @@ int rtems_rfs_rtems_error (const char* mesg, int error); * defined to 0 the code is dead code elminiated when built with -Os, -O2, or * higher. * - * @param mask The part of the API to trace. + * @param[in] mask is the part of the API to trace. + * * @retval true Tracing is active for the mask. * @retval false Do not trace. */ @@ -97,8 +101,9 @@ bool rtems_rfs_rtems_trace (uint32_t mask); /** * Set the mask. * - * @param mask The mask bits to set. - * @return The previous mask. + * @param[in] mask is the mask bits to set. + * + * @retval mask The previous mask. */ #if RTEMS_RFS_RTEMS_TRACE void rtems_rfs_rtems_trace_set_mask (uint32_t mask); @@ -109,8 +114,9 @@ void rtems_rfs_rtems_trace_set_mask (uint32_t mask); /** * Clear the mask. * - * @param mask The mask bits to clear. - * @return The previous mask. + * @param[in] mask is the mask bits to clear. + * + * @retval mask The previous mask. */ #if RTEMS_RFS_RTEMS_TRACE void rtems_rfs_rtems_trace_clear_mask (uint32_t mask); @@ -144,7 +150,7 @@ typedef struct rtems_rfs_rtems_private /** * Return the file system structure given a path location. * - * @param _loc Pointer to the path location. + * @param[in] _loc is a pointer to the path location. * @return rtems_rfs_file_system* */ #define rtems_rfs_rtems_pathloc_dev(_loc) \ @@ -153,8 +159,8 @@ typedef struct rtems_rfs_rtems_private /** * Set the inode number (ino) into the path location. * - * @param _loc Pointer to the path location. - * @param _ino The ino to set in the path location. + * @param[in] _loc is a pointer to the path location. + * @param[in] _ino is the ino to set in the path location. */ #define rtems_rfs_rtems_set_pathloc_ino(_loc, _ino) \ (_loc)->node_access = (void*)((intptr_t)(_ino)) @@ -162,7 +168,7 @@ typedef struct rtems_rfs_rtems_private /** * Get the inode number (ino) given a path location. * - * @param _loc Pointer to the path location. + * @param[in] _loc is a pointer to the path location. * @return rtems_rfs_ino The inode number in the path location. */ #define rtems_rfs_rtems_get_pathloc_ino(_loc) \ @@ -171,8 +177,8 @@ typedef struct rtems_rfs_rtems_private /** * Set the directory offset (doff) into the path location. * - * @param _loc Pointer to the path location. - * @param _doff The doff to set in the path location. + * @param[in] _loc is a pointer to the path location. + * @param[in] _doff is the doff to set in the path location. */ #define rtems_rfs_rtems_set_pathloc_doff(_loc, _doff) \ (_loc)->node_access_2 = (void*)((intptr_t)(_doff)) @@ -180,7 +186,7 @@ typedef struct rtems_rfs_rtems_private /** * Get the directory offset (doff) given a path location. * - * @param _loc Pointer to the path location. + * @param[in] _loc is a pointer to the path location. * @return uin32_t The doff in the path location. */ #define rtems_rfs_rtems_get_pathloc_doff(_loc) \ @@ -189,7 +195,7 @@ typedef struct rtems_rfs_rtems_private /** * Get the ino from the I/O pointer. * - * @param _iop The I/O pointer. + * @param[in] _iop is the I/O pointer. * @return ino */ #define rtems_rfs_rtems_get_iop_ino(_iop) \ @@ -207,8 +213,8 @@ typedef struct rtems_rfs_rtems_private /** * Set the file handle in the I/O pointer. * - * @param _iop The I/O pointer. - * @param _fh The file handle. + * @param[in] _iop is the I/O pointer. + * @param[in] _fh is the file handle. */ #define rtems_rfs_rtems_set_iop_file_handle(_iop, _fh) \ (_iop)->pathinfo.node_access_2 = (_fh) @@ -216,7 +222,7 @@ typedef struct rtems_rfs_rtems_private /** * Create the name of the handler's table given the type of handlers. * - * @param _h The name of the handlers. + * @param[in] _h is the name of the handlers. * @return label The name of the handler's table. */ #define rtems_rfs_rtems_handlers(_h) \ @@ -225,8 +231,10 @@ typedef struct rtems_rfs_rtems_private /** * Set the handlers in the path location based on the mode of the inode. * - * @param loc Pointer to the path location to set the handlers in. - * @param inode The inode handle to check the mode of for the type of handlers. + * @param[in] loc is a pointer to the path location to set the handlers in. + * @param[in] inode is the inode handle to check the mode of for the + * type of handlers. + * * @retval true The handlers have been set. * @retval false There are no handlers for the mode. */ @@ -236,7 +244,7 @@ bool rtems_rfs_rtems_set_handlers (rtems_filesystem_location_info_t* pathloc, /** * Convert the system mode flags to inode mode flags. * - * @param mode The system mode flags. + * @param[in] mode is the system mode flags. * @return uint16_t The inode mode flags. */ uint16_t rtems_rfs_rtems_imode (mode_t mode); @@ -244,7 +252,7 @@ uint16_t rtems_rfs_rtems_imode (mode_t mode); /** * Convert the inode mode flags to system mode flags. * - * @param imode The inode mode flags + * @param[in] imode is the inode mode flags * @return mode_t The system mode flags. */ mode_t rtems_rfs_rtems_mode (int imode); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-shell.h b/cpukit/libfs/src/rfs/rtems-rfs-shell.h index 135290d3e9..a917b8556c 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-shell.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-shell.h @@ -1,6 +1,5 @@ /** * @file - * * * @ingroup rtems-rfs * @brief RTEMS File Systems Shell Commands @@ -27,18 +26,22 @@ /** * The shell command for the RFS debugger. * - * @param argc The argument count. - * @param argv The argument variables. - * @return int The exit code for the command. A 0 is no error. + * @param[in] argc is the argument count. + * @param[in] argv is a pointer to the argument variables. + * + * @retval 0 Successful operation. + * @retval error_code An error occurred. */ int rtems_shell_debugrfs (int argc, char *argv[]); /** * The shell command for formatting an RFS file system. * - * @param argc The argument count. - * @param argv The argument variables. - * @return int The exit code for the command. A 0 is no error. + * @param[in] argc is the argument count. + * @param[in] argv is a pointer to the argument variables. + * + * @retval 0 Successful operation. + * @retval 1 An error occurred. */ int rtems_shell_rfs_format (int argc, char* argv[]); diff --git a/cpukit/libfs/src/rfs/rtems-rfs-trace.h b/cpukit/libfs/src/rfs/rtems-rfs-trace.h index 09273a5939..030e6c2058 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs-trace.h +++ b/cpukit/libfs/src/rfs/rtems-rfs-trace.h @@ -1,7 +1,8 @@ /** * @file * - * @brief Manages the Trace and Debugging Features of the RTEMS RFS File System + * @brief Manages the Trace and Debugging Features of the + * RTEMS RFS File System * * @ingroup rtems-rfs * @@ -87,7 +88,8 @@ typedef uint64_t rtems_rfs_trace_mask; * Call to check if this part is bring traced. If RTEMS_RFS_TRACE is defined to * 0 the code is dead code elminiated when built with -Os, -O2, or higher. * - * @param mask The part of the API to trace. + * @param[in] mask is the part of the API to trace. + * * @retval true Tracing is active for the mask. * @retval false Do not trace. */ @@ -100,8 +102,9 @@ bool rtems_rfs_trace (rtems_rfs_trace_mask mask); /** * Set the mask. * - * @param mask The mask bits to set. - * @return The previous mask. + * @param[in] mask are the mask bits to set. + * + * @retval mask The previous mask. */ #if RTEMS_RFS_TRACE rtems_rfs_trace_mask rtems_rfs_trace_set_mask (rtems_rfs_trace_mask mask); @@ -112,8 +115,9 @@ rtems_rfs_trace_mask rtems_rfs_trace_set_mask (rtems_rfs_trace_mask mask); /** * Clear the mask. * - * @param mask The mask bits to clear. - * @return The previous mask. + * @param[in] mask are the mask bits to clear. + * + * @retval mask The previous mask. */ #if RTEMS_RFS_TRACE rtems_rfs_trace_mask rtems_rfs_trace_clear_mask (rtems_rfs_trace_mask mask); diff --git a/cpukit/libfs/src/rfs/rtems-rfs.h b/cpukit/libfs/src/rfs/rtems-rfs.h index 251a61805f..b1684e0ebd 100644 --- a/cpukit/libfs/src/rfs/rtems-rfs.h +++ b/cpukit/libfs/src/rfs/rtems-rfs.h @@ -1,19 +1,21 @@ -/* - * COPYRIGHT (c) 2010 Chris Johns - * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.com/license/LICENSE. - */ /** * @file * + * @brief RFS File system Initialization * @ingroup rtems-rfs * * RTEMS File System * */ +/* + * COPYRIGHT (c) 2010 Chris Johns + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.com/license/LICENSE. + */ + #if !defined(RTEMS_RFS_DEFINED) #define RTEMS_RFS_DEFINED -- cgit v1.2.3