2009-04-29 Sebastian Huber <sebastian.huber@embedded-brains.de>

        * sapi/include/confdefs.h, libblock/include/rtems/bdbuf.h: Changed
        type of rtems_bdbuf_pool_configuration_size to size_t.

        * libblock/include/rtems/bdbuf.h, libblock/include/rtems/blkdev.h,
        libblock/include/rtems/diskdevs.h, libblock/src/bdbuf.c,
        libblock/src/blkdev.c, libblock/src/diskdevs.c: Buffer pool
        allocation is now cache aligned.  The cache functions are
        currently not available on all platforms so the cache line size is
        fixed to 32 bytes for now.  Changed various integer types which
        refer to block sizes, numbers and indexes.  Fixed logical block
        indexes in buffer get and read function.  It is now possible to
        delete logical disks.  Modified documentation

1 files changed, 149 insertions, 80 deletions

diff --git a/cpukit/libblock/include/rtems/blkdev.h b/cpukit/libblock/include/rtems/blkdev.h
index 57cbb6e47c..d5ec9f46cb 100644
--- a/cpukit/libblock/include/rtems/blkdev.h
+++ b/cpukit/libblock/include/rtems/blkdev.h
@@ -1,6 +1,7 @@
 /**
- * @file rtems/blkdev.h
- * block device driver interface definitions
+ * @file
+ *
+ * Block device management.
  */
  
 /*
@@ -20,109 +21,168 @@
 extern "C" {
 #endif
 
-/*
- *  Interface with device drivers Block device looks, initialized and behaves
- * like traditional RTEMS device driver. Heart of the block device driver is in
- * BIOREQUEST ioctl. This call puts I/O request to the block device queue, in
- * priority order, for asynchronous processing. When driver executes request,
- * req_done function invoked, so callee knows about it. Look for details below.
+/**
+ * @defgroup rtems_blkdev Block Device Management
+ *
+ * @ingroup rtems_libblock
+ *
+ * Interface between device drivers and the block device library.
+ *
+ * The heart of the block device driver is the @ref RTEMS_BLKIO_REQUEST IO
+ * control. This call puts IO @ref rtems_blkdev_request "requests" to the block
+ * device for asynchronous processing. When a driver executes a request, it
+ * invokes the request done callback function to finish the request.
+ *
+ * @{
  */
 
-/*
- * Block device block number datatype
+/**
+ * Block device block index type.
  */
 typedef uint32_t rtems_blkdev_bnum;
 
-/* Block device request type */
+/**
+ * Block device request type.
+ */
 typedef enum rtems_blkdev_request_op {
-    RTEMS_BLKDEV_REQ_READ,     /* Read operation */
-    RTEMS_BLKDEV_REQ_WRITE,    /* Write operation */
-    RTEMS_BLKDEV_CAPABILITIES  /* Capabilities request */
+  RTEMS_BLKDEV_REQ_READ,
+  RTEMS_BLKDEV_REQ_WRITE,
+  RTEMS_BLKDEV_CAPABILITIES
 } rtems_blkdev_request_op;
 
 /** 
- * ATA multi-sector buffer requests only supported. This option
- * means the cache will only supply multiple buffers that are
- * inorder so the ATA multi-sector command can be used. This is a
+ * 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
  * hack to work around the current ATA driver.
  */
 #define RTEMS_BLKDEV_CAP_MULTISECTOR_CONT (1 << 0)
 
-/*
- * @typedef rtems_blkdev_request_cb
- *
+/**
  * Type for block device request done callback function.
  *
- * @param arg Argument supplied in blkdev_request
- * @param status RTEMS status code for this operation
- * @param errno errno value to be passed to the user when
- *              status != RTEMS_SUCCESSFUL
+ * @param arg Argument supplied in @ref rtems_blkdev_request.
+ * @param status Status code for this operation.
+ * @param errno The @c errno value to be passed to the user when status is not
+ * equal to @c RTEMS_SUCCESSFUL.
  */
 typedef void (* rtems_blkdev_request_cb)(void *arg,
                                          rtems_status_code status,
                                          int error);
 
 /**
- * @struct rtems_blkdev_sg_buffer
- * Block device scatter/gather buffer structure
+ * Block device scatter or gather buffer structure.
  */
 typedef struct rtems_blkdev_sg_buffer {
-    uint32_t   block;   /* The block number */
-    uint32_t   length;  /* Buffer length */
-    void      *buffer;  /* Buffer pointer */
-    void      *user;    /* User pointer */
+  /**
+   * Block index.
+   */
+  rtems_blkdev_bnum block;
+
+  /**
+   * Buffer length.
+   */
+  uint32_t length;
+
+  /**
+   * Buffer pointer.
+   */
+  void *buffer;
+
+  /**
+   * User pointer.
+   */
+  void *user;
 } rtems_blkdev_sg_buffer;
 
-/* blkdev_request (Block Device Request) structure is
- * used to read/write a number of blocks from/to device.
+/**
+ * The block device dequest structure is used to read or write a number of
+ * blocks from or to the device.
  */
 typedef struct rtems_blkdev_request {
-    /* Block device operation (read or write) */
-    rtems_blkdev_request_op req;
-    /* Callback function */
-    rtems_blkdev_request_cb req_done;
-    /* Argument to be passed to callback function*/
-    void *done_arg;
-    /* Last I/O operation completion status */
-    rtems_status_code status; 
-    /* If status != RTEMS_SUCCESSFUL, this field contains error code */
-    int error;
-    /* Number of blocks for this request. */
-    uint32_t bufnum;
-
-    /* The task requesting the IO operation. */
-    rtems_id io_task;
-
-    /* List of scatter/gather buffers */
-    rtems_blkdev_sg_buffer bufs[0];
+  /**
+   * Block device operation (read or write).
+   */
+  rtems_blkdev_request_op req;
+
+  /**
+   * Request done callback function.
+   */
+  rtems_blkdev_request_cb req_done;
+
+  /**
+   * Argument to be passed to callback function.
+   */
+  void *done_arg;
+
+  /**
+   * Last IO operation completion status.
+   */
+  rtems_status_code status; 
+
+  /**
+   * If @c status is not equal to @c RTEMS_SUCCESSFUL, this field contains the
+   * error number.
+   */
+  int error;
+
+  /**
+   * Number of blocks for this request.
+   */
+  uint32_t bufnum;
+
+  /**
+   * The task requesting the IO operation.
+   */
+  rtems_id io_task;
+
+  /**
+   * List of scatter or gather buffers.
+   */
+  rtems_blkdev_sg_buffer bufs[0];
 } rtems_blkdev_request;
 
-/* The start block in a request. Only valid if the driver has returned the
- * RTEMS_BLKDEV_CAPABILITIES of RTEMS_BLKDEV_CAP_MULTISECTOR_CONT */
-#define RTEMS_BLKDEV_START_BLOCK(_r) (_r->bufs[0].block)
-
-/* Block device IOCTL request codes */
-#define RTEMS_BLKIO_REQUEST      _IOWR('B', 1, rtems_blkdev_request)
-#define RTEMS_BLKIO_GETBLKSIZE   _IO('B', 2)
-#define RTEMS_BLKIO_GETSIZE      _IO('B', 3)
-#define RTEMS_BLKIO_SYNCDEV      _IO('B', 4)
+/**
+ * The start block in a request.
+ *
+ * Only valid if the driver has returned the @ref RTEMS_BLKDEV_CAPABILITIES of
+ * @ref RTEMS_BLKDEV_CAP_MULTISECTOR_CONT.
+ */
+#define RTEMS_BLKDEV_START_BLOCK(req) (req->bufs[0].block)
 
-/* Device driver interface conventions suppose that driver may
- * contain initialize/open/close/read/write/ioctl entry points. These
- * primitives (except initialize) can be implemented in generic fashion,
- * based upon supplied block device driver ioctl handler. Every block
- * device driver should provide initialize entry point, which is register
- * all block devices and appropriate ioctl handlers.
+/**
+ * @name IO Control Request Codes
+ *
+ * @{
  */
 
+#define RTEMS_BLKIO_REQUEST _IOWR('B', 1, rtems_blkdev_request)
+#define RTEMS_BLKIO_GETBLKSIZE _IO('B', 2)
+#define RTEMS_BLKIO_GETSIZE _IO('B', 3)
+#define RTEMS_BLKIO_SYNCDEV _IO('B', 4)
+
+/** @} */
+
+/**
+ * The device driver interface conventions suppose that a driver may contain an
+ * initialize, open, close, read, write and IO control entry points. These
+ * primitives (except initialize) can be implemented in a generic fashion based
+ * upon the supplied block device driver IO control handler. Every block device
+ * driver should provide an initialize entry point, which registers the
+ * appropriate IO control handler.
+ */
 #define RTEMS_GENERIC_BLOCK_DEVICE_DRIVER_ENTRIES \
-      rtems_blkdev_generic_open, rtems_blkdev_generic_close, \
-      rtems_blkdev_generic_read, rtems_blkdev_generic_write, \
-      rtems_blkdev_generic_ioctl
+  .open_entry = rtems_blkdev_generic_open, \
+  .close_entry = rtems_blkdev_generic_close, \
+  .read_entry = rtems_blkdev_generic_read, \
+  .write_entry = rtems_blkdev_generic_write, \
+  .control_entry = rtems_blkdev_generic_ioctl
 
-/* blkdev_generic_read --
- *     Generic block device read primitive. Implemented using block device
- *     buffer management primitives.
+/**
+ * Generic block device read primitive.
+ *
+ * Implemented using block device buffer management primitives.
  */
 rtems_device_driver
 rtems_blkdev_generic_read(
@@ -131,9 +191,10 @@ rtems_blkdev_generic_read(
     void                    * arg
 );
 
-/* blkdev_generic_write --
- *     Generic block device driver write primitive. Implemented using block
- *     device buffer management primitives.
+/**
+ * Generic block device write primitive.
+ *
+ * Implemented using block device buffer management primitives.
  */
 rtems_device_driver
 rtems_blkdev_generic_write(
@@ -142,8 +203,10 @@ rtems_blkdev_generic_write(
     void                    * arg
 );
 
-/* blkdev_generic_open --
- *     Generic block device open primitive.
+/**
+ * Generic block device open primitive.
+ *
+ * Implemented using block device buffer management primitives.
  */
 rtems_device_driver
 rtems_blkdev_generic_open(
@@ -152,8 +215,10 @@ rtems_blkdev_generic_open(
     void                    * arg
 );
 
-/* blkdev_generic_close --
- *     Generic block device close primitive.
+/**
+ * Generic block device close primitive.
+ *
+ * Implemented using block device buffer management primitives.
  */
 rtems_device_driver
 rtems_blkdev_generic_close(
@@ -162,8 +227,10 @@ rtems_blkdev_generic_close(
     void                    * arg
 );
 
-/* blkdev_generic_ioctl --
- *     Generic block device ioctl primitive.
+/**
+ * Generic block device IO control primitive.
+ *
+ * Implemented using block device buffer management primitives.
  */
 rtems_device_driver
 rtems_blkdev_generic_ioctl(
@@ -172,6 +239,8 @@ rtems_blkdev_generic_ioctl(
     void                    * arg
 );
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif