From: Luis Chamberlain <mcgrof@kernel.org>
To: axboe@kernel.dk, damien.lemoal@wdc.com, bvanassche@acm.org,
ming.lei@redhat.com, martin.petersen@oracle.com,
satyat@google.com
Cc: linux-block@vger.kernel.org, linux-kernel@vger.kernel.org,
Luis Chamberlain <mcgrof@kernel.org>
Subject: [PATCH 2/2] block: move request_queue member docs to kdoc
Date: Tue, 23 Jun 2020 22:03:11 +0000 [thread overview]
Message-ID: <20200623220311.8033-3-mcgrof@kernel.org> (raw)
In-Reply-To: <20200623220311.8033-1-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
next prev parent reply other threads:[~2020-06-23 22:03 UTC|newest]
Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-06-23 22:03 [PATCH 0/2] block: kdocify the request_queue Luis Chamberlain
2020-06-23 22:03 ` [PATCH 1/2] block: add initial kdoc over " Luis Chamberlain
2020-06-24 0:33 ` Damien Le Moal
2020-06-24 7:22 ` Johannes Thumshirn
2020-06-28 20:53 ` Bart Van Assche
2020-06-23 22:03 ` Luis Chamberlain [this message]
2020-06-24 0:46 ` [PATCH 2/2] block: move request_queue member docs to kdoc Damien Le Moal
2020-06-24 7:23 ` Johannes Thumshirn
2020-06-28 21:23 ` Bart Van Assche
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200623220311.8033-3-mcgrof@kernel.org \
--to=mcgrof@kernel.org \
--cc=axboe@kernel.dk \
--cc=bvanassche@acm.org \
--cc=damien.lemoal@wdc.com \
--cc=linux-block@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=martin.petersen@oracle.com \
--cc=ming.lei@redhat.com \
--cc=satyat@google.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.