engines/io_uring: add read_mode=prefetch for bsg cmd_type

Introduce a new engine option, read_mode, that selects which command
variant is issued for DDIR_READ, symmetric to the existing write_mode
option. Two values are supported: 'read', which preserves the current
behavior, and 'prefetch', which issues SCSI PRE-FETCH commands.

PRE-FETCH pulls the requested LBAs from the medium into the device
read cache without transferring the data to the host. This is useful
for warming the device read cache prior to a subsequent measurement,
and for measuring the overhead of the prefetch path itself.

The PRE-FETCH CDB length follows the cdb_len option:
PRE-FETCH(10)=0x34 and PRE-FETCH(16)=0x90. readfua is rejected in
this mode because the FUA bit is not defined for PRE-FETCH.

read_mode is currently only meaningful for the bsg cmd_type. Passing
a non-default value with cmd_type=nvme is rejected at engine init
rather than silently ignored, so that users notice a
misconfiguration.

Signed-off-by: Jungwon Lee <jjung1.lee@samsung.com>

Author: ljw8161

HOWTO.rst

@@ -3111,6 +3111,22 @@ with the caveat that when used on the command line, they must come after the
                         The device compares a single block against every block
                         in the range. Only one block is transferred.
 
+.. option:: read_mode=str : [io_uring_cmd]
+
+        Specifies the type of read operation. Only supported with
+        cmd_type=bsg. Defaults to 'read'.
+
+                **read**
+                        Use Read commands for read operations
+
+                **prefetch**
+                        Use SCSI Pre-Fetch commands, which pull the requested
+                        blocks from the medium into the device read cache
+                        without transferring data to the host. Useful for
+                        cache-warming and prefetch-overhead benchmarks. The
+                        Pre-Fetch(10)/(16) opcode is selected by :option:`cdb_len`.
+                        :option:`readfua` is not supported in this mode.
+
 .. option:: verify_mode=str : [io_uring_cmd]
 
         Specifies the type of command to be used in the verification phase.  Defaults to 'read'.

engines/bsg.c

@@ -166,7 +166,8 @@ static void fio_bsg_set_verify_bytchk(struct bsg_cmd *bc, unsigned int cdb_len,
 int fio_bsg_uring_cmd_prep(struct bsg_uring_cmd *cmd, struct io_u *io_u,
 			   struct bsg_cmd *bc, bool fua, unsigned int cdb_len,
 			   enum bsg_write_variant wvariant,
-			   unsigned int verify_bytchk)
+			   unsigned int verify_bytchk,
+			   enum bsg_read_variant rvariant)
 {
 	struct bsg_data *data = FILE_ENG_DATA(io_u->file);
 	unsigned long long offset, nlb;
@@ -197,6 +198,23 @@ int fio_bsg_uring_cmd_prep(struct bsg_uring_cmd *cmd, struct io_u *io_u,
 
 	switch (io_u->ddir) {
 	case DDIR_READ:
+		if (rvariant == BSG_READ_VARIANT_PREFETCH) {
+			/*
+			 * PREFETCH pulls the requested blocks from the medium
+			 * into the device read cache. No host data transfer.
+			 */
+			fio_bsg_uring_cmd_init(cmd, bc, io_u, SG_DXFER_NONE,
+					       cdb_len);
+			switch (cdb_len) {
+			case 10:
+				bc->cdb[0] = bsg_cmd_prefetch_10;
+				break;
+			case 16:
+				bc->cdb[0] = bsg_cmd_prefetch_16;
+				break;
+			}
+			break;
+		}
 		fio_bsg_uring_cmd_init(cmd, bc, io_u, SG_DXFER_FROM_DEV, cdb_len);
 		switch (cdb_len) {
 		case 10:

engines/bsg.h

@@ -62,6 +62,8 @@ enum bsg_io_opcode {
 	bsg_cmd_write_16		= 0x8A,
 	bsg_cmd_verify_10		= 0x2F,
 	bsg_cmd_verify_16		= 0x8F,
+	bsg_cmd_prefetch_10		= 0x34,
+	bsg_cmd_prefetch_16		= 0x90,
 	bsg_cmd_varlen			= BSG_VARLEN_CDB_OPCODE,
 };
 
@@ -71,6 +73,12 @@ enum bsg_write_variant {
 	BSG_WRITE_VARIANT_VERIFY,
 };
 
+/* Which command variant to issue for DDIR_READ ddir. */
+enum bsg_read_variant {
+	BSG_READ_VARIANT_READ = 0,
+	BSG_READ_VARIANT_PREFETCH,
+};
+
 struct bsg_cmd {
 	unsigned char cdb[MAX_CDB_LEN];
 	unsigned char sb[MAX_SB];
@@ -89,6 +97,7 @@ int fio_bsg_uring_cmd_get_file_size(struct thread_data *td, struct fio_file *f);
 int fio_bsg_uring_cmd_prep(struct bsg_uring_cmd *cmd, struct io_u *io_u,
 			   struct bsg_cmd *bc, bool fua, unsigned int cdb_len,
 			   enum bsg_write_variant wvariant,
-			   unsigned int verify_bytchk);
+			   unsigned int verify_bytchk,
+			   enum bsg_read_variant rvariant);
 
 #endif /* FIO_BSG_H */

engines/io_uring.c

@@ -121,6 +121,11 @@ enum uring_cmd_verify_mode {
 	FIO_URING_CMD_VMODE_COMPARE,
 };
 
+enum uring_cmd_read_mode {
+	FIO_URING_CMD_RMODE_READ = 0,
+	FIO_URING_CMD_RMODE_PREFETCH,
+};
+
 struct io_sq_ring {
 	unsigned *head;
 	unsigned *tail;
@@ -216,6 +221,7 @@ struct ioring_options {
 	enum uring_cmd_type cmd_type;
 	unsigned int cdb_len;
 	unsigned int verify_bytchk;
+	unsigned int read_mode;
 };
 
 static unsigned int enter_flags = IORING_ENTER_GETEVENTS;
@@ -566,6 +572,26 @@ static struct fio_option options[] = {
 		.category = FIO_OPT_C_ENGINE,
 		.group	= FIO_OPT_G_IOURING,
 	},
+	{
+		.name	= "read_mode",
+		.lname	= "Read command type",
+		.type	= FIO_OPT_STR,
+		.off1	= offsetof(struct ioring_options, read_mode),
+		.help	= "Specify the read operation type (bsg cmd_type only)",
+		.def	= "read",
+		.posval = {
+			  { .ival = "read",
+			    .oval = FIO_URING_CMD_RMODE_READ,
+			    .help = "Use Read commands for read operations",
+			  },
+			  { .ival = "prefetch",
+			    .oval = FIO_URING_CMD_RMODE_PREFETCH,
+			    .help = "Use Pre-Fetch commands for read operations",
+			  },
+		},
+		.category = FIO_OPT_C_ENGINE,
+		.group	= FIO_OPT_G_IOURING,
+	},
 	CMDPRIO_OPTIONS(struct ioring_options, FIO_OPT_G_IOURING),
 	{
 		.name	= "md_per_io_size",
@@ -880,18 +906,24 @@ static int fio_ioring_cmd_prep(struct thread_data *td, struct io_u *io_u)
 	} else {
 		struct bsg_uring_cmd *cmd;
 		enum bsg_write_variant wvariant;
+		enum bsg_read_variant rvariant;
 
 		if (o->write_mode == FIO_URING_CMD_WMODE_VERIFY)
 			wvariant = BSG_WRITE_VARIANT_VERIFY;
 		else
 			wvariant = BSG_WRITE_VARIANT_WRITE;
+		if (o->read_mode == FIO_URING_CMD_RMODE_PREFETCH)
+			rvariant = BSG_READ_VARIANT_PREFETCH;
+		else
+			rvariant = BSG_READ_VARIANT_READ;
 
 		sqe->len = io_u->xfer_buflen;
 		cmd = (struct bsg_uring_cmd *)sqe->cmd;
 
 		return fio_bsg_uring_cmd_prep(cmd, io_u, &ld->bc[io_u->index],
 					      ld->fua[io_u->ddir], o->cdb_len,
-					      wvariant, o->verify_bytchk);
+					      wvariant, o->verify_bytchk,
+					      rvariant);
 	}
 }
 
@@ -1613,6 +1645,11 @@ static int fio_ioring_cmd_init(struct thread_data *td, struct ioring_data *ld)
 	}
 
 	if (o->cmd_type == FIO_URING_CMD_NVME) {
+		if (o->read_mode != FIO_URING_CMD_RMODE_READ) {
+			log_err("fio: read_mode is only supported with "
+				"cmd_type=bsg\n");
+			return 1;
+		}
 		if (td_write(td)) {
 			if (o->wmode_split_nr > 1) {
 				int i;
@@ -1675,6 +1712,22 @@ static int fio_ioring_cmd_init(struct thread_data *td, struct ioring_data *ld)
 			return 1;
 		}
 
+		if (o->read_mode == FIO_URING_CMD_RMODE_PREFETCH &&
+		    o->readfua) {
+			log_err("readfua is not supported "
+				"with read_mode=prefetch for bsg\n");
+			td_verror(td, EINVAL, "fio_ioring_cmd_init");
+			return 1;
+		}
+
+		if (o->read_mode == FIO_URING_CMD_RMODE_PREFETCH &&
+		    o->cdb_len == 32) {
+			log_err("cdb_len=32 is not supported "
+				"with read_mode=prefetch for bsg\n");
+			td_verror(td, EINVAL, "fio_ioring_cmd_init");
+			return 1;
+		}
+
 		if (td_write(td)) {
 			if (o->write_mode != FIO_URING_CMD_WMODE_WRITE &&
 			    o->write_mode != FIO_URING_CMD_WMODE_VERIFY) {

fio.1

@@ -2901,6 +2901,23 @@ block is transferred.
 .RE
 .RE
 .TP
+.BI (io_uring_cmd)read_mode \fR=\fPstr
+Specifies the type of read operation. Only supported with cmd_type=bsg.
+Defaults to 'read'.
+.RS
+.RS
+.TP
+.B read
+Use Read commands for read operations
+.TP
+.B prefetch
+Use SCSI Pre-Fetch commands, which pull the requested blocks from the medium
+into the device read cache without transferring data to the host. Useful for
+cache-warming and prefetch-overhead benchmarks. The Pre-Fetch(10)/(16) opcode
+is selected by \fBcdb_len\fR. \fBreadfua\fR is not supported in this mode.
+.RE
+.RE
+.TP
 .BI (io_uring_cmd)verify_mode \fR=\fPstr
 Specifies the type of command to be used in the verification phase. Defaults to 'read'.
 .RS