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.

c/src/lib/libbsp/arm/gp32/smc/smc.c

@@ -544,7 +544,7 @@ int sm_ECCEncode(const uint8_t * p_buf, uint8_t * p_ecc)
 */
 static int smc_write(rtems_blkdev_request *req)
 {
-	req->req_done(req->done_arg, RTEMS_SUCCESSFUL);
+	rtems_blkdev_request_done(req, RTEMS_SUCCESSFUL);
 	return 0;
 }
 
@@ -573,7 +573,7 @@ smc_read(rtems_blkdev_request *req)
 	smc_read_page(sg->block,sg->buffer);
         remains -= count;
     }
-    req->req_done(req->done_arg, RTEMS_SUCCESSFUL);
+    rtems_blkdev_request_done(req, RTEMS_SUCCESSFUL);
     return 0;
 }
 

c/src/lib/libbsp/lm32/shared/milkymist_memcard/memcard.c

@@ -197,14 +197,16 @@ static int memcard_disk_block_read(rtems_blkdev_request *r)
       return -RTEMS_IO_ERROR;
   }
 
-  r->req_done(r->done_arg, RTEMS_SUCCESSFUL);
+  rtems_blkdev_request_done(r, RTEMS_SUCCESSFUL);
 
   return 0;
 }
 
 static int memcard_disk_block_write(rtems_blkdev_request *r)
 {
-  return -RTEMS_IO_ERROR;
+  rtems_blkdev_request_done(r, RTEMS_IO_ERROR);
+
+  return 0;
 }
 
 static rtems_status_code memcard_init(void)

c/src/libchip/i2c/spi-sd-card.c

@@ -1117,7 +1117,7 @@ static int sd_card_disk_block_read( sd_card_driver_entry *e, rtems_blkdev_reques
 	RTEMS_CHECK_SC_RV( sc, "Stop");
 
 	/* Done */
-	r->req_done( r->done_arg, RTEMS_SUCCESSFUL);
+	rtems_blkdev_request_done( r, RTEMS_SUCCESSFUL);
 
 	return 0;
 
@@ -1132,9 +1132,9 @@ sd_card_disk_block_read_cleanup:
 	sd_card_stop( e);
 
 	/* Done */
-	r->req_done( r->done_arg, RTEMS_IO_ERROR);
+	rtems_blkdev_request_done( r, RTEMS_IO_ERROR);
 
-	return rv;
+	return 0;
 }
 
 static int sd_card_disk_block_write( sd_card_driver_entry *e, rtems_blkdev_request *r)
@@ -1206,7 +1206,7 @@ static int sd_card_disk_block_write( sd_card_driver_entry *e, rtems_blkdev_reque
 	RTEMS_CHECK_SC_RV( sc, "Stop");
 
 	/* Done */
-	r->req_done( r->done_arg, RTEMS_SUCCESSFUL);
+	rtems_blkdev_request_done( r, RTEMS_SUCCESSFUL);
 
 	return 0;
 
@@ -1225,9 +1225,9 @@ sd_card_disk_block_write_cleanup:
 	sd_card_stop( e);
 
 	/* Done */
-	r->req_done( r->done_arg, RTEMS_IO_ERROR);
+	rtems_blkdev_request_done( r, RTEMS_IO_ERROR);
 
-	return rv;
+	return 0;
 }
 
 static int sd_card_disk_ioctl( rtems_disk_device *dd, uint32_t req, void *arg)

c/src/libchip/ide/ata.c

@@ -185,7 +185,8 @@ ata_io_data_request(dev_t device, rtems_blkdev_request *req)
     areq = malloc(sizeof(ata_req_t));
     if (areq == NULL)
     {
-        return RTEMS_NO_MEMORY;
+        rtems_blkdev_request_done(req, RTEMS_NO_MEMORY);
+        return RTEMS_SUCCESSFUL;
     }
 
     areq->breq = req;

c/src/libchip/ide/ata_internal.h

@@ -218,8 +218,8 @@ typedef struct ata_req_s {
 /* call callback provided by block device request if it is defined */
 #define ATA_EXEC_CALLBACK(areq, status) \
     do {\
-        if (((areq)->breq != NULL) && ((areq)->breq->req_done != NULL)) \
+        if ((areq)->breq != NULL) \
-            (areq)->breq->req_done((areq)->breq->done_arg, status); \
+            rtems_blkdev_request_done((areq)->breq, status); \
     } while (0)
 
 /* ATA RTEMS driver events types */

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
+ * @brief The block device transfer request is used to read or write a number
- * blocks from or to the device.
+ * of blocks from or to the device.
  *
- * TODO: The use of these req blocks is not a great design. The req is a
+ * Transfer requests are issued to the disk device driver with the
- *       struct with a single 'bufs' declared in the req struct and the
+ * @ref RTEMS_BLKIO_REQUEST IO control.  The transfer request completion status
- *       others are added in the outer level struct. This relies on the
+ * must be signalled with rtems_blkdev_request_done().  This function must be
- *       structs joining as a single array and that assumes the compiler
+ * called exactly once per request.  The return value of the IO control will be
- *       packs the structs. Why not just place on a list ? The BD has a
+ * ignored for transfer requests.
- *       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,12 +131,40 @@ 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.
    */
   rtems_blkdev_sg_buffer bufs[0];
 } 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.
  *
@@ -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,

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)
+  /* Wait for transfer request completion */
-  {
   rtems_bdbuf_wait_for_transient_event ();
   sc = req->status;
-  }
-  else
-    sc = RTEMS_IO_ERROR;
 
   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 = rtems_bdbuf_transfer_done;
-  req->done_arg = req;
   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 = rtems_bdbuf_transfer_done;
-  write_req->done_arg = write_req;
   write_req->io_task = rtems_task_self ();
 
   return write_req;

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;
+  rtems_blkdev_request_done (req, ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL);
-  req->req_done (req->done_arg, req->status);
 
   return 0;
 }
@@ -2122,8 +2121,7 @@ rtems_fdisk_write (rtems_flashdisk* fd, rtems_blkdev_request* req)
     }
   }
 
-  req->status = ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL;
+  rtems_blkdev_request_done (req, ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL);
-  req->req_done (req->done_arg, req->status);
 
   return 0;
 }

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;
+  rtems_blkdev_request_done (req, ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL);
-  req->req_done (req->done_arg, req->status);
 
-  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;
+  rtems_blkdev_request_done (req, ret ? RTEMS_IO_ERROR : RTEMS_SUCCESSFUL);
-  req->req_done (req->done_arg, req->status);
 
   return 0;
 }

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;
+    rtems_blkdev_request_done (req, RTEMS_SUCCESSFUL);
-    req->req_done(req->done_arg, 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;
+    rtems_blkdev_request_done (req, RTEMS_SUCCESSFUL);
-    req->req_done(req->done_arg, RTEMS_SUCCESSFUL);
     return 0;
 }
 

testsuites/libtests/block05/init.c

@@ -379,7 +379,7 @@ static int disk_ioctl(rtems_disk_device *dd, uint32_t req, void *argp)
     switch (r->req) {
       case RTEMS_BLKDEV_REQ_READ:
       case RTEMS_BLKDEV_REQ_WRITE:
-        r->req_done(r->done_arg, RTEMS_SUCCESSFUL);
+        rtems_blkdev_request_done(r, RTEMS_SUCCESSFUL);
         return 0;
       default:
         errno = EINVAL;

testsuites/libtests/block06/init.c

@@ -488,7 +488,7 @@ bdbuf_disk_ioctl (rtems_disk_device *dd, uint32_t req, void* argp)
         {
           case RTEMS_BLKDEV_REQ_READ:
             if (!bdbuf_disk_ioctl_process (bdd, r))
-              errno = EIO;
+              rtems_blkdev_request_done(r, RTEMS_IO_ERROR);
             else
             {
               rtems_blkdev_sg_buffer* sg = r->bufs;
@@ -511,15 +511,16 @@ bdbuf_disk_ioctl (rtems_disk_device *dd, uint32_t req, void* argp)
                 remains -= length;
               }
 
-              r->req_done (r->done_arg, RTEMS_SUCCESSFUL);
+              rtems_blkdev_request_done (r, RTEMS_SUCCESSFUL);
             }
             bdbuf_disk_ioctl_leave (bdd, r->bufnum);
             break;
 
           case RTEMS_BLKDEV_REQ_WRITE:
             if (!bdbuf_disk_ioctl_process (bdd, r))
-              errno = EIO;
+              rtems_blkdev_request_done(r, RTEMS_IO_ERROR);
-            r->req_done (r->done_arg, RTEMS_SUCCESSFUL);
+            else
+              rtems_blkdev_request_done(r, RTEMS_SUCCESSFUL);
             bdbuf_disk_ioctl_leave (bdd, r->bufnum);
             break;
 

testsuites/libtests/block08/test_disk.c

@@ -35,15 +35,17 @@ test_disk_ioctl(rtems_disk_device *dd, uint32_t req, void *argp)
     rtems_status_code     rc;
     bdbuf_test_msg        msg;
     size_t                msg_size;
+    rtems_blkdev_request *r;
 
     switch (req)
     {
         case RTEMS_BLKIO_REQUEST:
         {
-            rtems_blkdev_request   *r = argp;
             rtems_blkdev_sg_buffer *sg;
             unsigned int            i;
 
+            r = argp;
+
             printk("DISK_DRV: %s ",
                    r->req == RTEMS_BLKDEV_REQ_READ ? "R" :
                    r->req == RTEMS_BLKDEV_REQ_WRITE ? "W" : "?");
@@ -71,7 +73,8 @@ test_disk_ioctl(rtems_disk_device *dd, uint32_t req, void *argp)
     if (rc != RTEMS_SUCCESSFUL)
     {
         printf("Error while sending a message to Test task: %u\n", rc);
-        return -1;
+        rtems_blkdev_request_done(r, RTEMS_IO_ERROR);
+        return 0;
     }
 
     /* Wait for a reply from the test task */
@@ -81,27 +84,27 @@ test_disk_ioctl(rtems_disk_device *dd, uint32_t req, void *argp)
     if (rc != RTEMS_SUCCESSFUL)
     {
         printf("Error while reading a message from Test task: %u\n", rc);
-        return rc;
+        rtems_blkdev_request_done(r, RTEMS_IO_ERROR);
+        return 0;
     }
     if (msg.type != BDBUF_TEST_MSG_TYPE_DRIVER_REPLY)
     {
         printf("Unexpected message comes to test disk driver: %d\n",
                msg.type);
-        return -1;
+        rtems_blkdev_request_done(r, RTEMS_IO_ERROR);
+        return 0;
     }
 
     if (msg.val.driver_reply.ret_val != 0)
     {
-        errno = msg.val.driver_reply.ret_errno;
+        rtems_blkdev_request_done(r, RTEMS_IO_ERROR);
     }
     else
     {
-        rtems_blkdev_request *r = (rtems_blkdev_request *)argp;
+        rtems_blkdev_request_done(r, msg.val.driver_reply.res_status);
-
-        r->req_done(r->done_arg, msg.val.driver_reply.res_status);
     }
 
-    return msg.val.driver_reply.ret_val;
+    return 0;
 }
 
 rtems_device_driver

testsuites/libtests/block09/init.c

@@ -64,10 +64,7 @@ static int disk_ioctl(rtems_disk_device *dd, uint32_t req, void *arg)
       rtems_blkdev_sg_buffer *sg = &r->bufs [i];
       char *buf = sg->buffer;
 
-      if (sg->length != 1) {
+      if (sg->length == 1) {
-        return -1;
-      }
-
         switch (r->req) {
           case RTEMS_BLKDEV_REQ_READ:
             switch (sg->block) {
@@ -82,7 +79,8 @@ static int disk_ioctl(rtems_disk_device *dd, uint32_t req, void *arg)
                 *buf = disk_data [sg->block];
                 break;
               default:
-              return -1;
+                sc = RTEMS_IO_ERROR;
+                break;
             }
             break;
           case RTEMS_BLKDEV_REQ_WRITE:
@@ -96,15 +94,20 @@ static int disk_ioctl(rtems_disk_device *dd, uint32_t req, void *arg)
                 sc = RTEMS_IO_ERROR;
                 break;
               default:
-              return -1;
+                sc = RTEMS_IO_ERROR;
+                break;
             }
             break;
           default:
-          return -1;
+            sc = RTEMS_IO_ERROR;
+            break;
+        }
+      } else {
+        sc = RTEMS_IO_ERROR;
       }
     }
 
-    r->req_done(r->done_arg, sc);
+    rtems_blkdev_request_done(r, sc);
 
     return 0;
   } else {

testsuites/libtests/block10/init.c

@@ -105,7 +105,7 @@ static int disk_ioctl(rtems_disk_device *dd, uint32_t req, void *arg)
       set_task_prio(RTEMS_SELF, PRIORITY_SWAPOUT);
     }
 
-    r->req_done(r->done_arg, sc);
+    rtems_blkdev_request_done(r, sc);
 
     return 0;
   } else {

testsuites/libtests/block12/init.c

@@ -55,7 +55,7 @@ static int test_disk_ioctl(rtems_disk_device *dd, uint32_t req, void *arg)
       ++block_access_counts [block];
     }
 
-    breq->req_done(breq->done_arg, RTEMS_SUCCESSFUL);
+    rtems_blkdev_request_done(breq, RTEMS_SUCCESSFUL);
   } else {
     errno = EINVAL;
     rv = -1;

testsuites/libtests/block13/init.c

@@ -126,7 +126,7 @@ static int test_disk_ioctl(rtems_disk_device *dd, uint32_t req, void *arg)
       ++block_access_counts [block];
     }
 
-    (*breq->req_done)(breq->done_arg, RTEMS_SUCCESSFUL);
+    rtems_blkdev_request_done(breq, RTEMS_SUCCESSFUL);
   } else {
     errno = EINVAL;
     rv = -1;

testsuites/libtests/block14/init.c

@@ -105,7 +105,7 @@ static int test_disk_ioctl(rtems_disk_device *dd, uint32_t req, void *arg)
       }
     }
 
-    (*breq->req_done)(breq->done_arg, sc);
+    rtems_blkdev_request_done(breq, sc);
   } else {
     errno = EINVAL;
     rv = -1;

testsuites/libtests/block15/init.c

@@ -84,7 +84,7 @@ static int test_disk_ioctl(rtems_disk_device *dd, uint32_t req, void *arg)
       }
     }
 
-    (*breq->req_done)(breq->done_arg, RTEMS_SUCCESSFUL);
+    rtems_blkdev_request_done(breq, RTEMS_SUCCESSFUL);
   } else if (req == RTEMS_BLKIO_CAPABILITIES) {
     *(uint32_t *) arg = RTEMS_BLKDEV_CAP_MULTISECTOR_CONT;
   } else {