From 1024561f197d2716bc8764556b43da7d424291f9 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Tue, 28 Feb 2012 16:29:27 +0100 Subject: libblock: Documentation --- cpukit/libblock/include/rtems/bdbuf.h | 66 ++++++++++++++++++++++------------- 1 file changed, 41 insertions(+), 25 deletions(-) (limited to 'cpukit/libblock/include/rtems/bdbuf.h') diff --git a/cpukit/libblock/include/rtems/bdbuf.h b/cpukit/libblock/include/rtems/bdbuf.h index 11b413223b..37e06aa9e9 100644 --- a/cpukit/libblock/include/rtems/bdbuf.h +++ b/cpukit/libblock/include/rtems/bdbuf.h @@ -15,7 +15,7 @@ * issues. * Change to support demand driven variable buffer sizes. * - * Copyright (c) 2009 embedded brains GmbH. + * Copyright (c) 2009-2012 embedded brains GmbH. * * @(#) bdbuf.h,v 1.9 2005/02/02 00:06:18 joel Exp */ @@ -443,8 +443,12 @@ extern const rtems_bdbuf_config rtems_bdbuf_configuration; * neccessary) buffers. After initialization all blocks is placed into the * ready state. * - * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed - * successfully or error code if error is occured) + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_CALLED_FROM_ISR Called from an interrupt context. + * @retval RTEMS_INVALID_NUMBER The buffer maximum is not an integral multiple + * of the buffer minimum. + * @retval RTEMS_RESOURCE_IN_USE Already initialized. + * @retval RTEMS_UNSATISFIED Not enough resources. */ rtems_status_code rtems_bdbuf_init (void); @@ -466,12 +470,15 @@ rtems_bdbuf_init (void); * The block number is the linear block number. This is relative to the start * of the partition on the media. * - * @param device Device number (constructed of major and minor device number) - * @param block Linear media block number - * @param bd Reference to the buffer descriptor pointer. + * @param device [in] Device number (constructed of major and minor device + * number). + * @param block [in] Linear media block number. + * @param bd [out] Reference to the buffer descriptor pointer. * - * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed - * successfully or error code if error is occured) + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_NOT_CONFIGURED Not initialized. + * @retval RTEMS_INVALID_ID No such device. + * @retval RTEMS_INVALID_NUMBER Invalid block size. */ rtems_status_code rtems_bdbuf_get (dev_t device, rtems_blkdev_bnum block, rtems_bdbuf_buffer** bd); @@ -491,12 +498,16 @@ rtems_bdbuf_get (dev_t device, rtems_blkdev_bnum block, rtems_bdbuf_buffer** bd) * buffer is returned. The highest priority waiter will obtain the buffer * first. * - * @param device Device number (constructed of major and minor device number) - * @param block Linear media block number - * @param bd Reference to the buffer descriptor pointer. + * @param device [in] Device number (constructed of major and minor device + * number). + * @param block [in] Linear media block number. + * @param bd [out] Reference to the buffer descriptor pointer. * - * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed - * successfully or error code if error is occured) + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_NOT_CONFIGURED Not initialized. + * @retval RTEMS_INVALID_ID No such device. + * @retval RTEMS_INVALID_NUMBER Invalid block size. + * @retval RTEMS_IO_ERROR IO error. */ rtems_status_code rtems_bdbuf_read (dev_t device, rtems_blkdev_bnum block, rtems_bdbuf_buffer** bd); @@ -509,10 +520,11 @@ rtems_bdbuf_read (dev_t device, rtems_blkdev_bnum block, rtems_bdbuf_buffer** bd * the cache and modified before this call it will be returned to the modified * queue. The buffers is returned to the end of the LRU list. * - * @param bd Reference to the buffer descriptor. + * @param bd [in] Reference to the buffer descriptor. * - * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed - * successfully or error code if error is occured) + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_NOT_CONFIGURED Not initialized. + * @retval RTEMS_INVALID_ADDRESS The reference is NULL. */ rtems_status_code rtems_bdbuf_release (rtems_bdbuf_buffer* bd); @@ -527,10 +539,11 @@ rtems_bdbuf_release (rtems_bdbuf_buffer* bd); * or a sync call has been made. If the buffer is obtained with a get or read * before the hold timer has expired the buffer will be returned to the user. * - * @param bd Reference to the buffer descriptor. + * @param bd [in] Reference to the buffer descriptor. * - * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed - * successfully or error code if error is occured) + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_NOT_CONFIGURED Not initialized. + * @retval RTEMS_INVALID_ADDRESS The reference is NULL. */ rtems_status_code rtems_bdbuf_release_modified (rtems_bdbuf_buffer* bd); @@ -544,10 +557,11 @@ rtems_bdbuf_release_modified (rtems_bdbuf_buffer* bd); * @note This code does not lock the sync mutex and stop additions to the * modified queue. - * @param bd Reference to the buffer descriptor. + * @param bd [in] Reference to the buffer descriptor. * - * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed - * successfully or error code if error is occured) + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_NOT_CONFIGURED Not initialized. + * @retval RTEMS_INVALID_ADDRESS The reference is NULL. */ rtems_status_code rtems_bdbuf_sync (rtems_bdbuf_buffer* bd); @@ -561,10 +575,12 @@ rtems_bdbuf_sync (rtems_bdbuf_buffer* bd); * @note Nesting calls to sync multiple devices will be handled sequentially. A * nested call will be blocked until the first sync request has complete. * - * @param dev Block device number + * @param dev [in] Device number (constructed of major and minor device + * number). * - * @return RTEMS status code (RTEMS_SUCCESSFUL if operation completed - * successfully or error code if error is occured) + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_NOT_CONFIGURED Not initialized. + * @retval RTEMS_INVALID_ID No such device. */ rtems_status_code rtems_bdbuf_syncdev (dev_t dev); -- cgit v1.2.3