[PATCH 2/2] block: move request_queue member docs to kdoc

[Luis Chamberlain <mcgrof@kernel.org>]

Now that we have a template, expand on the kdoc form for
the request_queue data structure with documentation from
the rest of the members, *only* for information we already
had.

This does not add any new documentation. This just shifts
documentation to kdoc form.

Signed-off-by: Luis Chamberlain <mcgrof@kernel.org>
---
 include/linux/blkdev.h | 139 ++++++++++++-----------------------------
 1 file changed, 40 insertions(+), 99 deletions(-)

diff --git a/include/linux/blkdev.h b/include/linux/blkdev.h
index ea319c2b0593..d30bfef893b9 100644
--- a/include/linux/blkdev.h
+++ b/include/linux/blkdev.h
@@ -396,8 +396,38 @@ static inline int blkdev_zone_mgmt_ioctl(struct block_device *bdev,
 
 /**
  * struct request_queue - block device driver request queue
+ * @queue_ctx: software queue context
+ * @queue_hw_ctx: hw dispatch queues
+ * @queuedata: the queue owner gets to use this for whatever they like.
+ *	ll_rw_blk doesn't touch it.
+ * @queue_flags: various queue flags, see %QUEUE_* below
+ * @pm_only: Number of contexts that have called blk_set_pm_only(). If this
+ *	counter is above zero then only %RQF_PM and %RQF_PREEMPT requests are
+ *	processed.
+ * @id: ida allocated id for this queue.  Used to index queues from ioctx.
+ * @bounce_gfp: queue needs bounce pages for pages above this limit
+ * @kobj: queue kobject
+ * @mq_kobj: mq queue kobject
+ * @nr_requests: maximum number of of requests
+ * @ksm: Inline crypto capabilities
+ * @nr_zones:
+ * @nr_zones: total number of zones of the device. This is always 0 for regular
+ *	block devices.
+ * @conv_zones_bitmap: bitmap of nr_zones bits which indicates if a zone
+ *	is conventional (bit set) or sequential (bit clear).
+ * @seq_zones_wlock: bitmap of nr_zones bits which indicates if a zone
+ *	is write locked, that is, if a write request targeting the zone was
+ *	dispatched.
+ * @debugfs_mutex: used to protect access to the @ebugfs_dir
  * @debugfs_mutex: used to protect access to the @debugfs_dir
  * @blk_trace: used by blktrace to keep track of setup / tracing
+ * @fq: for flush operations
+ * @td: throttle data
+ * @unused_hctx_list: list used for reusing dead hctx instance in case of
+ *	updating nr_hw_queues.
+ * @unused_hctx_lock: used to protect the @unused_hctx_list
+ * @mq_freeze_lock: protects concurrent access to q_usage_counter by
+ *	percpu_ref_kill() and percpu_ref_reinit().
  * @debugfs_dir: directory created to place debugfs information. This is always
  *	created for make_request and request-based block drivers upon
  *	initialization. blktrace requires for this directory to be created,
@@ -413,67 +443,35 @@ static inline int blkdev_zone_mgmt_ioctl(struct block_device *bdev,
  *   o custom solutions such as scsi-generic
  *
  * All partitions share the same request_queue data structure.
+ *
+ * Zoned block device dispatch control is managed by the fields @nr_zones,
+ * @conv_zones_bitmap and @seq_zones_wlock. These fields are fields are
+ * initialized by the low level device driver (e.g. scsi/sd.c).  Stacking
+ * drivers (device mappers) may or may not initialize these fields.
+ * Reads of this information must be protected with blk_queue_enter() /
+ * blk_queue_exit(). Modifying this information is only allowed while
+ * no requests are being processed. See also blk_mq_freeze_queue() and
+ * blk_mq_unfreeze_queue().
  */
 struct request_queue {
 	struct request		*last_merge;
 	struct elevator_queue	*elevator;
-
 	struct blk_queue_stats	*stats;
 	struct rq_qos		*rq_qos;
-
 	make_request_fn		*make_request_fn;
-
 	const struct blk_mq_ops	*mq_ops;
-
-	/* sw queues */
 	struct blk_mq_ctx __percpu	*queue_ctx;
-
 	unsigned int		queue_depth;
-
-	/* hw dispatch queues */
 	struct blk_mq_hw_ctx	**queue_hw_ctx;
 	unsigned int		nr_hw_queues;
-
 	struct backing_dev_info	*backing_dev_info;
-
-	/*
-	 * The queue owner gets to use this for whatever they like.
-	 * ll_rw_blk doesn't touch it.
-	 */
 	void			*queuedata;
-
-	/*
-	 * various queue flags, see QUEUE_* below
-	 */
 	unsigned long		queue_flags;
-	/*
-	 * Number of contexts that have called blk_set_pm_only(). If this
-	 * counter is above zero then only RQF_PM and RQF_PREEMPT requests are
-	 * processed.
-	 */
 	atomic_t		pm_only;
-
-	/*
-	 * ida allocated id for this queue.  Used to index queues from
-	 * ioctx.
-	 */
 	int			id;
-
-	/*
-	 * queue needs bounce pages for pages above this limit
-	 */
 	gfp_t			bounce_gfp;
-
 	spinlock_t		queue_lock;
-
-	/*
-	 * queue kobject
-	 */
 	struct kobject kobj;
-
-	/*
-	 * mq queue kobject
-	 */
 	struct kobject *mq_kobj;
 
 #ifdef  CONFIG_BLK_DEV_INTEGRITY
@@ -485,66 +483,32 @@ struct request_queue {
 	int			rpm_status;
 	unsigned int		nr_pending;
 #endif
-
-	/*
-	 * queue settings
-	 */
-	unsigned long		nr_requests;	/* Max # of requests */
-
+	unsigned long		nr_requests;
 	unsigned int		dma_pad_mask;
 	unsigned int		dma_alignment;
-
 #ifdef CONFIG_BLK_INLINE_ENCRYPTION
-	/* Inline crypto capabilities */
 	struct blk_keyslot_manager *ksm;
 #endif
-
 	unsigned int		rq_timeout;
 	int			poll_nsec;
-
 	struct blk_stat_callback	*poll_cb;
 	struct blk_rq_stat	poll_stat[BLK_MQ_POLL_STATS_BKTS];
-
 	struct timer_list	timeout;
 	struct work_struct	timeout_work;
-
 	struct list_head	icq_list;
 #ifdef CONFIG_BLK_CGROUP
 	DECLARE_BITMAP		(blkcg_pols, BLKCG_MAX_POLS);
 	struct blkcg_gq		*root_blkg;
 	struct list_head	blkg_list;
 #endif
-
 	struct queue_limits	limits;
-
 	unsigned int		required_elevator_features;
-
 #ifdef CONFIG_BLK_DEV_ZONED
-	/*
-	 * Zoned block device information for request dispatch control.
-	 * nr_zones is the total number of zones of the device. This is always
-	 * 0 for regular block devices. conv_zones_bitmap is a bitmap of nr_zones
-	 * bits which indicates if a zone is conventional (bit set) or
-	 * sequential (bit clear). seq_zones_wlock is a bitmap of nr_zones
-	 * bits which indicates if a zone is write locked, that is, if a write
-	 * request targeting the zone was dispatched. All three fields are
-	 * initialized by the low level device driver (e.g. scsi/sd.c).
-	 * Stacking drivers (device mappers) may or may not initialize
-	 * these fields.
-	 *
-	 * Reads of this information must be protected with blk_queue_enter() /
-	 * blk_queue_exit(). Modifying this information is only allowed while
-	 * no requests are being processed. See also blk_mq_freeze_queue() and
-	 * blk_mq_unfreeze_queue().
-	 */
 	unsigned int		nr_zones;
 	unsigned long		*conv_zones_bitmap;
 	unsigned long		*seq_zones_wlock;
 #endif /* CONFIG_BLK_DEV_ZONED */
 
-	/*
-	 * sg stuff
-	 */
 	unsigned int		sg_timeout;
 	unsigned int		sg_reserved_size;
 	int			node;
@@ -552,59 +516,36 @@ struct request_queue {
 #ifdef CONFIG_BLK_DEV_IO_TRACE
 	struct blk_trace __rcu	*blk_trace;
 #endif
-	/*
-	 * for flush operations
-	 */
 	struct blk_flush_queue	*fq;
-
 	struct list_head	requeue_list;
 	spinlock_t		requeue_lock;
 	struct delayed_work	requeue_work;
-
 	struct mutex		sysfs_lock;
 	struct mutex		sysfs_dir_lock;
-
-	/*
-	 * for reusing dead hctx instance in case of updating
-	 * nr_hw_queues
-	 */
 	struct list_head	unused_hctx_list;
 	spinlock_t		unused_hctx_lock;
-
 	int			mq_freeze_depth;
-
 #if defined(CONFIG_BLK_DEV_BSG)
 	struct bsg_class_device bsg_dev;
 #endif
 
 #ifdef CONFIG_BLK_DEV_THROTTLING
-	/* Throttle data */
 	struct throtl_data *td;
 #endif
 	struct rcu_head		rcu_head;
 	wait_queue_head_t	mq_freeze_wq;
-	/*
-	 * Protect concurrent access to q_usage_counter by
-	 * percpu_ref_kill() and percpu_ref_reinit().
-	 */
 	struct mutex		mq_freeze_lock;
 	struct percpu_ref	q_usage_counter;
-
 	struct blk_mq_tag_set	*tag_set;
 	struct list_head	tag_set_list;
 	struct bio_set		bio_split;
-
 	struct dentry		*debugfs_dir;
-
 #ifdef CONFIG_BLK_DEBUG_FS
 	struct dentry		*sched_debugfs_dir;
 	struct dentry		*rqos_debugfs_dir;
 #endif
-
 	bool			mq_sysfs_init_done;
-
 	size_t			cmd_size;
-
 #define BLK_MAX_WRITE_HINTS	5
 	u64			write_hints[BLK_MAX_WRITE_HINTS];
 };
-- 
2.26.2