documentation fixes

Avoid designated initializers for C++ compatibility
Fixed invalid state transition from FRESH to CACHED
Free memory in case of an error.

4 files changed, 54 insertions, 22 deletions

diff --git a/cpukit/libblock/include/rtems/bdbuf.h b/cpukit/libblock/include/rtems/bdbuf.h
index 2b0d2aa7eb..49e3cc59c1 100644
--- a/cpukit/libblock/include/rtems/bdbuf.h
+++ b/cpukit/libblock/include/rtems/bdbuf.h
@@ -79,6 +79,7 @@ extern "C" {
  *
  * @dot
  * digraph state {
+ *   size="16,8";
  *   e [label="EMPTY",style="filled",fillcolor="aquamarine"];
  *   f [label="FRESH",style="filled",fillcolor="seagreen"];
  *   c [label="CACHED",style="filled",fillcolor="chartreuse"];
@@ -159,47 +160,73 @@ extern "C" {
  */
 
 /**
- * State of a buffer of the cache.
+ * @brief State of a buffer of the cache.
+ *
+ * The state has several implications.  Depending on the state a buffer can be
+ * in the AVL tree, in a list, in use by an entity and a group user or not.
  */
 typedef enum
 {
   /**
-   * Not in the cache.  Not in a list.  Not in use.
+   * @brief Empty.
+   *
+   * Not in the AVL tree.  Not in a list.  Not in use.  Not a user of its
+   * group.
    */
   RTEMS_BDBUF_STATE_EMPTY = 0,
 
   /**
-   * In the cache.  Not in a list.  In use by a get or read request.
+   * @brief Fresh.
+   *
+   * In the AVL tree.  Not in a list.  In use by a get or read request.  A user
+   * of its group.
    */
   RTEMS_BDBUF_STATE_FRESH,
 
   /**
-   * In the cache.  In the LRU list.  Not in use.
+   * @brief Cached.
+   *
+   * In the AVL tree.  In the LRU list.  Not in use.  Not a user of its group.
    */
-  RTEMS_BDBUF_STATE_CACHED,          /**< In the cache and available */
+  RTEMS_BDBUF_STATE_CACHED,
 
   /**
-   * In the cache.  Not in a list.  In use by an upper layer.
+   * @brief Accessed by upper layer.
+   *
+   * In the AVL tree.  Not in a list.  In use by an upper layer.  A user of its
+   * group.
    */
   RTEMS_BDBUF_STATE_ACCESS,
 
   /**
-   * In the cache.  Not in a list.  In use by an upper layer.
+   * @brief Accessed and modified by upper layer.
+   *
+   * In the AVL tree.  Not in a list.  In use by an upper layer.  A user of its
+   * group.
    */
   RTEMS_BDBUF_STATE_ACCESS_MODIFIED,
 
   /**
-   * In the cache.  In the modified list.  Not in use.
+   * @brief Modified by upper layer.
+   *
+   * In the AVL tree.  In the modified list.  In use by swapout mechanic.  A
+   * user of its group.
    */
   RTEMS_BDBUF_STATE_MODIFIED,
 
   /**
-   * In the cache.  In the sync list.  Not in use.
+   * @brief Scheduled for synchronization.
+   *
+   * In the AVL tree.  In the sync list.  In use by swapout mechanic.  A user
+   * of its group.
    */
   RTEMS_BDBUF_STATE_SYNC,
 
   /**
-   * In the cache.  Not in a list.  In use by the block device driver.
+   * @brief In transfer by block device driver.
+   *
+   * In the AVL tree.  Not in a list.  In use by the block device driver.  A
+   * user of its group.
    */
   RTEMS_BDBUF_STATE_TRANSFER
 } rtems_bdbuf_buf_state;
diff --git a/cpukit/libblock/include/rtems/blkdev.h b/cpukit/libblock/include/rtems/blkdev.h
index b9c4edcf3e..eb53700f40 100644
--- a/cpukit/libblock/include/rtems/blkdev.h
+++ b/cpukit/libblock/include/rtems/blkdev.h
@@ -182,11 +182,11 @@ typedef struct rtems_blkdev_request {
  * appropriate IO control handler.
  */
 #define RTEMS_GENERIC_BLOCK_DEVICE_DRIVER_ENTRIES \
-  .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
+  rtems_blkdev_generic_open, \
+  rtems_blkdev_generic_close, \
+  rtems_blkdev_generic_read, \
+  rtems_blkdev_generic_write, \
+  rtems_blkdev_generic_ioctl
 
 /**
  * Generic block device read primitive.
diff --git a/cpukit/libblock/src/bdbuf.c b/cpukit/libblock/src/bdbuf.c
index 60aca5df0d..db707ea71d 100644
--- a/cpukit/libblock/src/bdbuf.c
+++ b/cpukit/libblock/src/bdbuf.c
@@ -1831,21 +1831,25 @@ rtems_bdbuf_create_read_request (rtems_blkdev_request *req,
   if (media_block_end - media_block < transfer_count)
     transfer_count = media_block_end - media_block;
 
-  bd = rtems_bdbuf_get_buffer_for_access (dev, media_block, bds_per_group);
-
   req->bufnum = 0;
 
+  bd = rtems_bdbuf_get_buffer_for_access (dev, media_block, bds_per_group);
+
   req->bufs [0].user   = bd;
   req->bufs [0].block  = media_block;
   req->bufs [0].length = block_size;
   req->bufs [0].buffer = bd->buffer;
 
+  if (rtems_bdbuf_tracer)
+    rtems_bdbuf_show_users ("read", bd);
+
   switch (bd->state)
   {
     case RTEMS_BDBUF_STATE_CACHED:
     case RTEMS_BDBUF_STATE_MODIFIED:
       return;
     case RTEMS_BDBUF_STATE_FRESH:
+      rtems_bdbuf_set_state (bd, RTEMS_BDBUF_STATE_TRANSFER);
       break;
     default:
       rtems_bdbuf_fatal (bd->state, RTEMS_BLKDEV_FATAL_BDBUF_STATE_1);
@@ -1854,11 +1858,6 @@ rtems_bdbuf_create_read_request (rtems_blkdev_request *req,
 
   while (transfer_index < transfer_count)
   {
-    rtems_bdbuf_set_state (bd, RTEMS_BDBUF_STATE_TRANSFER);
-
-    if (rtems_bdbuf_tracer)
-      rtems_bdbuf_show_users ("reading", bd);
-
     media_block += media_block_count;
 
     bd = rtems_bdbuf_get_buffer_for_read_ahead (dev, media_block,
@@ -1867,11 +1866,16 @@ rtems_bdbuf_create_read_request (rtems_blkdev_request *req,
     if (bd == NULL)
       break;
 
+    rtems_bdbuf_set_state (bd, RTEMS_BDBUF_STATE_TRANSFER);
+
     req->bufs [transfer_index].user   = bd;
     req->bufs [transfer_index].block  = media_block;
     req->bufs [transfer_index].length = block_size;
     req->bufs [transfer_index].buffer = bd->buffer;
 
+    if (rtems_bdbuf_tracer)
+      rtems_bdbuf_show_users ("read-ahead", bd);
+
     ++transfer_index;
   }
 
diff --git a/cpukit/libblock/src/ide_part_table.c b/cpukit/libblock/src/ide_part_table.c
index 026b5d05dc..a93728b7f8 100644
--- a/cpukit/libblock/src/ide_part_table.c
+++ b/cpukit/libblock/src/ide_part_table.c
@@ -513,6 +513,7 @@ rtems_ide_part_table_initialize(char *dev_name)
     rc = rtems_ide_part_table_get(dev_name, disk_desc);
     if (rc != RTEMS_SUCCESSFUL)
     {
+        free(disk_desc);
         return rc;
     }