libblock: Documentation

2 files changed, 125 insertions, 98 deletions

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
@@ -342,90 +449,10 @@ rtems_blkdev_generic_ioctl(
 );
 
 /**
- * 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) {