3 files changed, 42 insertions, 22 deletions
diff --git a/include/linux/blk_types.h b/include/linux/blk_types.h
index d59553324a84..8808ee76e73c 100644
--- a/include/linux/blk_types.h
+++ b/include/linux/blk_types.h
@@ -273,7 +273,13 @@ struct bio {
 	 * Everything starting with bi_max_vecs will be preserved by bio_reset()
 	 */
 
-	unsigned short		bi_max_vecs;	/* max bvl_vecs we can hold */
+	/*
+	 * Number of elements in `bi_io_vec` that were allocated for this bio.
+	 * Only used by the bio submitter to make `bio_add_page` fail once full
+	 * and to free the `bi_io_vec` allocation. Must not be used in drivers
+	 * and does not hold a useful value for cloned bios.
+	 */
+	unsigned short		bi_max_vecs;
 
 	atomic_t		__bi_cnt;	/* pin count */
 
@@ -339,32 +345,33 @@ typedef __u32 __bitwise blk_mq_req_flags_t;
  * meaning.
  */
 enum req_op {
-	/* read sectors from the device */
+	/** @REQ_OP_READ: read sectors from the device */
 	REQ_OP_READ		= (__force blk_opf_t)0,
-	/* write sectors to the device */
+	/** @REQ_OP_WRITE: write sectors to the device */
 	REQ_OP_WRITE		= (__force blk_opf_t)1,
-	/* flush the volatile write cache */
+	/** @REQ_OP_FLUSH: flush the volatile write cache */
 	REQ_OP_FLUSH		= (__force blk_opf_t)2,
-	/* discard sectors */
+	/** @REQ_OP_DISCARD: discard sectors */
 	REQ_OP_DISCARD		= (__force blk_opf_t)3,
-	/* securely erase sectors */
+	/** @REQ_OP_SECURE_ERASE: securely erase sectors */
 	REQ_OP_SECURE_ERASE	= (__force blk_opf_t)5,
-	/* write data at the current zone write pointer */
+	/** @REQ_OP_ZONE_APPEND: write data at the current zone write pointer */
 	REQ_OP_ZONE_APPEND	= (__force blk_opf_t)7,
-	/* write the zero filled sector many times */
+	/** @REQ_OP_WRITE_ZEROES: write the zero filled sector many times */
 	REQ_OP_WRITE_ZEROES	= (__force blk_opf_t)9,
-	/* Open a zone */
+	/** @REQ_OP_ZONE_OPEN: Open a zone */
 	REQ_OP_ZONE_OPEN	= (__force blk_opf_t)11,
-	/* Close a zone */
+	/** @REQ_OP_ZONE_CLOSE: Close a zone */
 	REQ_OP_ZONE_CLOSE	= (__force blk_opf_t)13,
-	/* Transition a zone to full */
+	/** @REQ_OP_ZONE_FINISH: Transition a zone to full */
 	REQ_OP_ZONE_FINISH	= (__force blk_opf_t)15,
-	/* reset a zone write pointer */
+	/** @REQ_OP_ZONE_RESET: reset a zone write pointer */
 	REQ_OP_ZONE_RESET	= (__force blk_opf_t)17,
-	/* reset all the zone present on the device */
+	/** @REQ_OP_ZONE_RESET_ALL: reset all the zone present on the device */
 	REQ_OP_ZONE_RESET_ALL	= (__force blk_opf_t)19,
 
 	/* Driver private requests */
+	/* private: */
 	REQ_OP_DRV_IN		= (__force blk_opf_t)34,
 	REQ_OP_DRV_OUT		= (__force blk_opf_t)35,
 
diff --git a/include/linux/blkdev.h b/include/linux/blkdev.h
index 99ef8cd7673c..d463b9b5a0a5 100644
--- a/include/linux/blkdev.h
+++ b/include/linux/blkdev.h
@@ -1259,7 +1259,7 @@ extern void blk_io_schedule(void);
 
 int blkdev_issue_discard(struct block_device *bdev, sector_t sector,
 		sector_t nr_sects, gfp_t gfp_mask);
-int __blkdev_issue_discard(struct block_device *bdev, sector_t sector,
+void __blkdev_issue_discard(struct block_device *bdev, sector_t sector,
 		sector_t nr_sects, gfp_t gfp_mask, struct bio **biop);
 int blkdev_issue_secure_erase(struct block_device *bdev, sector_t sector,
 		sector_t nr_sects, gfp_t gfp);
diff --git a/include/linux/bvec.h b/include/linux/bvec.h
index 3fc0efa0825b..06fb60471aaf 100644
--- a/include/linux/bvec.h
+++ b/include/linux/bvec.h
@@ -75,14 +75,27 @@ static inline void bvec_set_virt(struct bio_vec *bv, void *vaddr,
 }
 
 struct bvec_iter {
-	sector_t		bi_sector;	/* device address in 512 byte
-						   sectors */
-	unsigned int		bi_size;	/* residual I/O count */
-
-	unsigned int		bi_idx;		/* current index into bvl_vec */
-
-	unsigned int            bi_bvec_done;	/* number of bytes completed in
-						   current bvec */
+	/*
+	 * Current device address in 512 byte sectors. Only updated by the bio
+	 * iter wrappers and not the bvec iterator helpers themselves.
+	 */
+	sector_t		bi_sector;
+
+	/*
+	 * Remaining size in bytes.
+	 */
+	unsigned int		bi_size;
+
+	/*
+	 * Current index into the bvec array. This indexes into `bi_io_vec` when
+	 * iterating a bvec array that is part of a `bio`.
+	 */
+	unsigned int		bi_idx;
+
+	/*
+	 * Current offset in the bvec entry pointed to by `bi_idx`.
+	 */
+	unsigned int		bi_bvec_done;
 } __packed __aligned(4);
 
 struct bvec_iter_all {