From eb93595b4ce63eea6e144d77a6bcbfb82225e73d Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Wed, 31 Oct 2012 13:56:15 +0100 Subject: libblock: Documentation --- cpukit/libblock/include/rtems/blkdev.h | 203 +++++++++++++++++++-------------- cpukit/libblock/src/blkdev-imfs.c | 20 ++-- 2 files changed, 125 insertions(+), 98 deletions(-) (limited to 'cpukit/libblock') diff --git a/cpukit/libblock/include/rtems/blkdev.h b/cpukit/libblock/include/rtems/blkdev.h index 7f83a26d04..0ea955d435 100644 --- a/cpukit/libblock/include/rtems/blkdev.h +++ b/cpukit/libblock/include/rtems/blkdev.h @@ -41,7 +41,7 @@ extern "C" { */ /** - * Block device request type. + * @brief Block device request type. * * @warning The sync request is an IO one and only used from the cache. Use the * Block IO when operating at the device level. We need a sync request @@ -64,7 +64,7 @@ typedef void (*rtems_blkdev_request_cb)( ); /** - * Block device scatter or gather buffer structure. + * @brief Block device scatter or gather buffer structure. */ typedef struct rtems_blkdev_sg_buffer { /** @@ -166,10 +166,10 @@ static inline void rtems_blkdev_request_done( } /** - * The start block in a request. + * @brief The start block in a request. * - * Only valid if the driver has returned the @ref RTEMS_BLKIO_CAPABILITIES of - * @ref RTEMS_BLKDEV_CAP_MULTISECTOR_CONT. + * Only valid if the driver has returned the + * @ref RTEMS_BLKDEV_CAP_MULTISECTOR_CONT capability. */ #define RTEMS_BLKDEV_START_BLOCK(req) (req->bufs[0].block) @@ -252,7 +252,13 @@ static inline int rtems_disk_fd_reset_device_stats(int fd) } /** - * Only consecutive multi-sector buffer requests are supported. + * @name Block Device Driver Capabilities + * + * @{ + */ + +/** + * @brief Only consecutive multi-sector buffer requests are supported. * * This option means the cache will only supply multiple buffers that are * inorder so the ATA multi-sector command for example can be used. This is a @@ -261,11 +267,112 @@ static inline int rtems_disk_fd_reset_device_stats(int fd) #define RTEMS_BLKDEV_CAP_MULTISECTOR_CONT (1 << 0) /** - * The driver will accept a sync call. A sync call is made to a driver - * after a bdbuf cache sync has finished. + * @brief The driver will accept a sync call. + * + * A sync call is made to a driver after a bdbuf cache sync has finished. */ #define RTEMS_BLKDEV_CAP_SYNC (1 << 1) +/** @} */ + +/** + * @brief Common IO control primitive. + * + * Use this in all block devices to handle the common set of IO control + * requests. + */ +int +rtems_blkdev_ioctl(rtems_disk_device *dd, uint32_t req, void *argp); + +/** + * @brief Creates a block device. + * + * The block size is set to the media block size. + * + * @param[in] device The path for the new block device. + * @param[in] media_block_size The media block size in bytes. Must be positive. + * @param[in] media_block_count The media block count. Must be positive. + * @param[in] handler The block device IO control handler. Must not be @c NULL. + * @param[in] driver_data The block device driver data. + * + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_INVALID_NUMBER Media block size or count is not positive. + * @retval RTEMS_NO_MEMORY Not enough memory. + * @retval RTEMS_UNSATISFIED Cannot create generic device node. + * + * @see rtems_blkdev_create_partition(), rtems_bdbuf_set_block_size(), and + * rtems_blkdev_request. + */ +rtems_status_code rtems_blkdev_create( + const char *device, + uint32_t media_block_size, + rtems_blkdev_bnum media_block_count, + rtems_block_device_ioctl handler, + void *driver_data +); + +/** + * @brief Creates a partition within a parent block device. + * + * A partition manages a subset of consecutive blocks contained in a parent block + * device. The blocks must be within the range of blocks managed by the + * associated parent block device. The media block size and IO control + * handler are inherited by the parent block device. The block size is set to + * the media block size. + * + * @param[in] partition The path for the new partition device. + * @param[in] parent_block_device The parent block device path. + * @param[in] media_block_begin The media block begin of the partition within + * the parent block device. + * @param[in] media_block_count The media block count of the partition. + * + * @retval RTEMS_SUCCESSFUL Successful operation. + * @retval RTEMS_INVALID_ID Block device node does not exist. + * @retval RTEMS_INVALID_NODE File system node is not a block device. + * @retval RTEMS_NOT_IMPLEMENTED Block device implementation is incomplete. + * @retval RTEMS_INVALID_NUMBER Block begin or block count is invalid. + * @retval RTEMS_NO_MEMORY Not enough memory. + * @retval RTEMS_UNSATISFIED Cannot create generic device node. + * + * @see rtems_blkdev_create() and rtems_bdbuf_set_block_size(). + */ +rtems_status_code rtems_blkdev_create_partition( + const char *partition, + const char *parent_block_device, + rtems_blkdev_bnum media_block_begin, + rtems_blkdev_bnum media_block_count +); + +/** + * @brief Prints the block device statistics. + */ +void rtems_blkdev_print_stats( + const rtems_blkdev_stats *stats, + rtems_printk_plugin_t print, + void *print_arg +); + +/** + * @brief Block device statistics command. + */ +void rtems_blkstats( + FILE *output, + const char *device, + bool reset +); + +/** @} */ + +/** + * @defgroup rtems_blkdev_generic Generic Disk Device + * + * @ingroup rtems_blkdev + * + * Generic disk device operations for standard RTEMS IO drivers. + * + * @{ + */ + /** * The device driver interface conventions suppose that a driver may contain an * initialize, open, close, read, write and IO control entry points. These @@ -341,91 +448,11 @@ rtems_blkdev_generic_ioctl( void * arg ); -/** - * Common IO control primitive. - * - * Use this in all block devices to handle the common set of ioctl requests. - */ -int -rtems_blkdev_ioctl(rtems_disk_device *dd, uint32_t req, void *argp); - /** * @brief Generic block operations driver address table. */ extern const rtems_driver_address_table rtems_blkdev_generic_ops; -/** - * @brief Creates a block device. - * - * @param[in] device The path for the new block device. - * @param[in] block_size The block size. Must be positive. - * @param[in] block_count The block count. Must be positive. - * @param[in] handler The block device IO control handler. Must not be @c NULL. - * @param[in] driver_data The block device driver data. - * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_NUMBER Block size or block count is not positive. - * @retval RTEMS_NO_MEMORY Not enough memory. - * @retval RTEMS_UNSATISFIED Cannot create generic device node. - * - * @see rtems_blkdev_create_partition() and rtems_blkdev_request. - */ -rtems_status_code rtems_blkdev_create( - const char *device, - uint32_t block_size, - rtems_blkdev_bnum block_count, - rtems_block_device_ioctl handler, - void *driver_data -); - -/** - * @brief Creates a partition within a block device. - * - * A partition manages a subset of consecutive blocks contained in a block - * device. The blocks must be within the range of blocks managed by the - * associated block device. The media block size, block size, and IO control - * handler are inherited by the block device. - * - * @param[in] partition The path for the new partition device. - * @param[in] device The block device path. - * @param[in] block_begin The block begin of the partition. - * @param[in] block_count The block count of the partition. - * - * @retval RTEMS_SUCCESSFUL Successful operation. - * @retval RTEMS_INVALID_ID Block device node does not exist. - * @retval RTEMS_INVALID_NODE File system node is not a block device. - * @retval RTEMS_NOT_IMPLEMENTED Block device implementation is incomplete. - * @retval RTEMS_INVALID_NUMBER Block begin or block count is invalid. - * @retval RTEMS_NO_MEMORY Not enough memory. - * @retval RTEMS_UNSATISFIED Cannot create generic device node. - * - * @see rtems_blkdev_create(). - */ -rtems_status_code rtems_blkdev_create_partition( - const char *partition, - const char *device, - rtems_blkdev_bnum block_begin, - rtems_blkdev_bnum block_count -); - -/** - * @brief Prints the block device statistics. - */ -void rtems_blkdev_print_stats( - const rtems_blkdev_stats *stats, - rtems_printk_plugin_t print, - void *print_arg -); - -/** - * @brief Block device statistics command. - */ -void rtems_blkstats( - FILE *output, - const char *device, - bool reset -); - /** @} */ #ifdef __cplusplus diff --git a/cpukit/libblock/src/blkdev-imfs.c b/cpukit/libblock/src/blkdev-imfs.c index e3c76a1d2f..290ae781ef 100644 --- a/cpukit/libblock/src/blkdev-imfs.c +++ b/cpukit/libblock/src/blkdev-imfs.c @@ -262,8 +262,8 @@ static const IMFS_node_control rtems_blkdev_imfs_control = { rtems_status_code rtems_blkdev_create( const char *device, - uint32_t block_size, - rtems_blkdev_bnum block_count, + uint32_t media_block_size, + rtems_blkdev_bnum media_block_count, rtems_block_device_ioctl handler, void *driver_data ) @@ -274,8 +274,8 @@ rtems_status_code rtems_blkdev_create( if (ctx != NULL) { sc = rtems_disk_init_phys( &ctx->dd, - block_size, - block_count, + media_block_size, + media_block_count, handler, driver_data ); @@ -306,13 +306,13 @@ rtems_status_code rtems_blkdev_create( rtems_status_code rtems_blkdev_create_partition( const char *partition, - const char *device, - rtems_blkdev_bnum block_begin, - rtems_blkdev_bnum block_count + const char *parent_block_device, + rtems_blkdev_bnum media_block_begin, + rtems_blkdev_bnum media_block_count ) { rtems_status_code sc = RTEMS_SUCCESSFUL; - int fd = open(device, O_RDWR); + int fd = open(parent_block_device, O_RDWR); if (fd >= 0) { int rv; @@ -330,8 +330,8 @@ rtems_status_code rtems_blkdev_create_partition( sc = rtems_disk_init_log( &ctx->dd, phys_dd, - block_begin, - block_count + media_block_begin, + media_block_count ); if (sc == RTEMS_SUCCESSFUL) { -- cgit v1.2.3