libblock: Block device transfer request API change

Add and use rtems_blkdev_request_done().  Block device transfer requests
must signal the completion status now with rtems_blkdev_request_done().
The return value of the block device IO control will be ignored for
transfer requests.

The first parameter of rtems_blkdev_request_cb is now the transfer
request structure.

Renamed rtems_blkdev_request::req_done to rtems_blkdev_request::done to
break third party drivers at compile time, otherwise this API change
would result in runtime errors.

5 files changed, 63 insertions, 48 deletions

diff --git a/cpukit/libblock/include/rtems/blkdev.h b/cpukit/libblock/include/rtems/blkdev.h
index ccc8981c35..7f83a26d04 100644
--- a/cpukit/libblock/include/rtems/blkdev.h
+++ b/cpukit/libblock/include/rtems/blkdev.h
@@ -53,18 +53,15 @@ typedef enum rtems_blkdev_request_op {
   RTEMS_BLKDEV_REQ_SYNC        /**< Sync any data with the media. */
 } rtems_blkdev_request_op;
 
+struct rtems_blkdev_request;
+
 /**
  * @brief Block device request done callback function type.
- *
- * The first parameter @a arg must be the argument provided by the block device
- * request structure @ref rtems_blkdev_request.
- *
- * The second parameter @a status should contain the status of the operation:
- *  - @c RTEMS_SUCCESSFUL Operation was successful.
- *  - @c RTEMS_IO_ERROR Some sort of input or output error.
- *  - @c RTEMS_UNSATISFIED Media no more present.
  */
-typedef void (*rtems_blkdev_request_cb)(void *arg, rtems_status_code status);
+typedef void (*rtems_blkdev_request_cb)(
+  struct rtems_blkdev_request *req,
+  rtems_status_code status
+);
 
 /**
  * Block device scatter or gather buffer structure.
@@ -92,15 +89,16 @@ typedef struct rtems_blkdev_sg_buffer {
 } rtems_blkdev_sg_buffer;
 
 /**
- * The block device request structure is used to read or write a number of
- * blocks from or to the device.
+ * @brief The block device transfer request is used to read or write a number
+ * of blocks from or to the device.
+ *
+ * Transfer requests are issued to the disk device driver with the
+ * @ref RTEMS_BLKIO_REQUEST IO control.  The transfer request completion status
+ * must be signalled with rtems_blkdev_request_done().  This function must be
+ * called exactly once per request.  The return value of the IO control will be
+ * ignored for transfer requests.
  *
- * TODO: The use of these req blocks is not a great design. The req is a
- *       struct with a single 'bufs' declared in the req struct and the
- *       others are added in the outer level struct. This relies on the
- *       structs joining as a single array and that assumes the compiler
- *       packs the structs. Why not just place on a list ? The BD has a
- *       node that can be used.
+ * @see rtems_blkdev_create().
  */
 typedef struct rtems_blkdev_request {
   /**
@@ -111,7 +109,7 @@ typedef struct rtems_blkdev_request {
   /**
    * Request done callback function.
    */
-  rtems_blkdev_request_cb req_done;
+  rtems_blkdev_request_cb done;
 
   /**
    * Argument to be passed to callback function.
@@ -133,6 +131,15 @@ typedef struct rtems_blkdev_request {
    */
   rtems_id io_task;
 
+  /*
+   * TODO: The use of these req blocks is not a great design. The req is a
+   *       struct with a single 'bufs' declared in the req struct and the
+   *       others are added in the outer level struct. This relies on the
+   *       structs joining as a single array and that assumes the compiler
+   *       packs the structs. Why not just place on a list ? The BD has a
+   *       node that can be used.
+   */
+
   /**
    * List of scatter or gather buffers.
    */
@@ -140,6 +147,25 @@ typedef struct rtems_blkdev_request {
 } rtems_blkdev_request;
 
 /**
+ * @brief Signals transfer request completion status.
+ *
+ * This function must be called exactly once per request.
+ *
+ * @param[in,out] req The transfer request.
+ * @param[in] status The status of the operation should be
+ *  - @c RTEMS_SUCCESSFUL, if the operation was successful,
+ *  - @c RTEMS_IO_ERROR, if some sort of input or output error occured, or
+ *  - @c RTEMS_UNSATISFIED, if media is no more present.
+ */
+static inline void rtems_blkdev_request_done(
+  rtems_blkdev_request *req,
+  rtems_status_code status
+)
+{
+  (*req->done)(req, status);
+}
+
+/**
  * The start block in a request.
  *
  * Only valid if the driver has returned the @ref RTEMS_BLKIO_CAPABILITIES of
@@ -341,6 +367,8 @@ extern const rtems_driver_address_table rtems_blkdev_generic_ops;
  * @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,
@@ -370,6 +398,8 @@ rtems_status_code rtems_blkdev_create(
  * @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,
diff --git a/cpukit/libblock/src/bdbuf.c b/cpukit/libblock/src/bdbuf.c
index 81f641ec33..8fb3848b16 100644
--- a/cpukit/libblock/src/bdbuf.c
+++ b/cpukit/libblock/src/bdbuf.c
@@ -1871,10 +1871,8 @@ rtems_bdbuf_get (rtems_disk_device   *dd,
  * @param status I/O completion status
  */
 static void
-rtems_bdbuf_transfer_done (void* arg, rtems_status_code status)
+rtems_bdbuf_transfer_done (rtems_blkdev_request* req, rtems_status_code status)
 {
-  rtems_blkdev_request* req = (rtems_blkdev_request*) arg;
-
   req->status = status;
 
   rtems_event_transient_send (req->io_task);
@@ -1886,7 +1884,6 @@ rtems_bdbuf_execute_transfer_request (rtems_disk_device    *dd,
                                       bool                  cache_locked)
 {
   rtems_status_code sc = RTEMS_SUCCESSFUL;
-  int result = 0;
   uint32_t transfer_index = 0;
   bool wake_transfer_waiters = false;
   bool wake_buffer_waiters = false;
@@ -1894,15 +1891,12 @@ rtems_bdbuf_execute_transfer_request (rtems_disk_device    *dd,
   if (cache_locked)
     rtems_bdbuf_unlock_cache ();
 
-  result = dd->ioctl (dd->phys_dev, RTEMS_BLKIO_REQUEST, req);
+  /* The return value will be ignored for transfer requests */
+  dd->ioctl (dd->phys_dev, RTEMS_BLKIO_REQUEST, req);
 
-  if (result == 0)
-  {
-    rtems_bdbuf_wait_for_transient_event ();
-    sc = req->status;
-  }
-  else
-    sc = RTEMS_IO_ERROR;
+  /* Wait for transfer request completion */
+  rtems_bdbuf_wait_for_transient_event ();
+  sc = req->status;
 
   rtems_bdbuf_lock_cache ();
 
@@ -1977,10 +1971,8 @@ rtems_bdbuf_execute_read_request (rtems_disk_device  *dd,
                      sizeof (rtems_blkdev_sg_buffer) * transfer_count);
 
   req->req = RTEMS_BLKDEV_REQ_READ;
-  req->req_done = rtems_bdbuf_transfer_done;
-  req->done_arg = req;
+  req->done = rtems_bdbuf_transfer_done;
   req->io_task = rtems_task_self ();
-  req->status = RTEMS_RESOURCE_IN_USE;
   req->bufnum = 0;
 
   rtems_bdbuf_set_state (bd, RTEMS_BDBUF_STATE_TRANSFER);
@@ -2655,8 +2647,7 @@ rtems_bdbuf_swapout_writereq_alloc (void)
     rtems_fatal_error_occurred (RTEMS_BLKDEV_FATAL_BDBUF_SO_NOMEM);
 
   write_req->req = RTEMS_BLKDEV_REQ_WRITE;
-  write_req->req_done = rtems_bdbuf_transfer_done;
-  write_req->done_arg = write_req;
+  write_req->done = rtems_bdbuf_transfer_done;
   write_req->io_task = rtems_task_self ();
 
   return write_req;
diff --git a/cpukit/libblock/src/flashdisk.c b/cpukit/libblock/src/flashdisk.c
index ec1ace2aee..a9e56c938f 100644
--- a/cpukit/libblock/src/flashdisk.c
+++ b/cpukit/libblock/src/flashdisk.c
@@ -2086,8 +2086,7 @@ rtems_fdisk_read (rtems_flashdisk* fd, rtems_blkdev_request* req)
     }
   }
 
-  req->status = ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL;
-  req->req_done (req->done_arg, req->status);
+  rtems_blkdev_request_done (req, ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL);
 
   return 0;
 }
@@ -2122,8 +2121,7 @@ rtems_fdisk_write (rtems_flashdisk* fd, rtems_blkdev_request* req)
     }
   }
 
-  req->status = ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL;
-  req->req_done (req->done_arg, req->status);
+  rtems_blkdev_request_done (req, ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL);
 
   return 0;
 }
diff --git a/cpukit/libblock/src/nvdisk.c b/cpukit/libblock/src/nvdisk.c
index c90f319693..127291df71 100644
--- a/cpukit/libblock/src/nvdisk.c
+++ b/cpukit/libblock/src/nvdisk.c
@@ -597,10 +597,9 @@ rtems_nvdisk_read (rtems_nvdisk* nvd, rtems_blkdev_request* req)
     }
   }
 
-  req->status = ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL;
-  req->req_done (req->done_arg, req->status);
+  rtems_blkdev_request_done (req, ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL);
 
-  return ret;
+  return 0;
 }
 
 /**
@@ -637,8 +636,7 @@ rtems_nvdisk_write (rtems_nvdisk* nvd, rtems_blkdev_request* req)
     }
   }
 
-  req->status = ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL;
-  req->req_done (req->done_arg, req->status);
+  rtems_blkdev_request_done (req, ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL);
 
   return 0;
 }
diff --git a/cpukit/libblock/src/ramdisk-driver.c b/cpukit/libblock/src/ramdisk-driver.c
index fb4a80fe97..881b7df2a5 100644
--- a/cpukit/libblock/src/ramdisk-driver.c
+++ b/cpukit/libblock/src/ramdisk-driver.c
@@ -67,8 +67,7 @@ ramdisk_read(struct ramdisk *rd, rtems_blkdev_request *req)
 #endif
         memcpy(sg->buffer, from + (sg->block * rd->block_size), sg->length);
     }
-    req->status = RTEMS_SUCCESSFUL;
-    req->req_done(req->done_arg, RTEMS_SUCCESSFUL);
+    rtems_blkdev_request_done (req, RTEMS_SUCCESSFUL);
     return 0;
 }
 
@@ -92,8 +91,7 @@ ramdisk_write(struct ramdisk *rd, rtems_blkdev_request *req)
 #endif
         memcpy(to + (sg->block * rd->block_size), sg->buffer, sg->length);
     }
-    req->status = RTEMS_SUCCESSFUL;
-    req->req_done(req->done_arg, RTEMS_SUCCESSFUL);
+    rtems_blkdev_request_done (req, RTEMS_SUCCESSFUL);
     return 0;
 }