[1/2] block: add initial kdoc over the request_queue
diff mbox series

Message ID 20200623220311.8033-2-mcgrof@kernel.org
State New
Headers show
Series
  • block: kdocify the request_queue
Related show

Commit Message

Luis Chamberlain June 23, 2020, 10:03 p.m. UTC
We start off with an initial description of the request_queue data
structure, followed by describing the purpose of the debugfs_mutex
debugfs_dir, and blk_trace.

Suggested-by: Bart Van Assche <bvanassche@acm.org>
Signed-off-by: Luis Chamberlain <mcgrof@kernel.org>
---
 include/linux/blkdev.h | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

Comments

Damien Le Moal June 24, 2020, 12:33 a.m. UTC | #1
On 2020/06/24 7:03, Luis Chamberlain wrote:
> We start off with an initial description of the request_queue data
> structure, followed by describing the purpose of the debugfs_mutex
> debugfs_dir, and blk_trace.
> 
> Suggested-by: Bart Van Assche <bvanassche@acm.org>
> Signed-off-by: Luis Chamberlain <mcgrof@kernel.org>
> ---
>  include/linux/blkdev.h | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
> 
> diff --git a/include/linux/blkdev.h b/include/linux/blkdev.h
> index 70461b347169..ea319c2b0593 100644
> --- a/include/linux/blkdev.h
> +++ b/include/linux/blkdev.h
> @@ -394,6 +394,26 @@ static inline int blkdev_zone_mgmt_ioctl(struct block_device *bdev,
>  
>  #endif /* CONFIG_BLK_DEV_ZONED */
>  
> +/**
> + * struct request_queue - block device driver request queue
> + * @debugfs_mutex: used to protect access to the @debugfs_dir
> + * @blk_trace: used by blktrace to keep track of setup / tracing
> + * @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,

s/requires for/requires/ (may be, not sure of my English grammar on this one :))

> + *	and so it will be created on demand if its block driver type does not
> + *	create it opon initialization.

s/opon/upon/

> + *
> + * The request_queue is used to manage incoming block layer device driver
> + * requests. We have three main type of block driver types which end up making

We have three main types of block drivers which...

> + * use of the request_queue:
> + *
> + *   o make_request block drivers (multiqueue)
> + *   o request-based block drivers

Isn't this second one BIO based drivers, like device-mapper BIO targets ?

> + *   o custom solutions such as scsi-generic

The SG driver does not create a request queue, it uses the one of the scsi
device created by the scsi stack. Is this what you mean here ? Saying
scsi-generic kind of implies sg driver.

> + *
> + * All partitions share the same request_queue data structure.
> + */
>  struct request_queue {
>  	struct request		*last_merge;
>  	struct elevator_queue	*elevator;
>
Johannes Thumshirn June 24, 2020, 7:22 a.m. UTC | #2
On 24/06/2020 00:04, Luis Chamberlain wrote:
> + *   o make_request block drivers (multiqueue)

I don't think the differentiation between singlequeue and 
multiqueue is usefull, given that the single queue block layer
is gone for quite some time now.
Bart Van Assche June 28, 2020, 8:53 p.m. UTC | #3
On 2020-06-23 15:03, Luis Chamberlain wrote:
> +/**
> + * struct request_queue - block device driver request queue

Since request queues are used as a communication channel between the
block layer core and block drivers and since the block layer core
creates request queues, I propose to leave out the word "driver".

> + * @debugfs_mutex: used to protect access to the @debugfs_dir
> + * @blk_trace: used by blktrace to keep track of setup / tracing
> + * @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,
> + *	and so it will be created on demand if its block driver type does not
> + *	create it opon initialization.
> + *
> + * The request_queue is used to manage incoming block layer device driver
> + * requests. We have three main type of block driver types which end up making
> + * use of the request_queue:

"incoming" is correct from the perspective of the block driver but not
from the perspective of the block layer core. How about describing
request queues as a communication channel between the block layer core
and block drivers?

Thanks,

Bart.

Patch
diff mbox series

diff --git a/include/linux/blkdev.h b/include/linux/blkdev.h
index 70461b347169..ea319c2b0593 100644
--- a/include/linux/blkdev.h
+++ b/include/linux/blkdev.h
@@ -394,6 +394,26 @@  static inline int blkdev_zone_mgmt_ioctl(struct block_device *bdev,
 
 #endif /* CONFIG_BLK_DEV_ZONED */
 
+/**
+ * struct request_queue - block device driver request queue
+ * @debugfs_mutex: used to protect access to the @debugfs_dir
+ * @blk_trace: used by blktrace to keep track of setup / tracing
+ * @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,
+ *	and so it will be created on demand if its block driver type does not
+ *	create it opon initialization.
+ *
+ * The request_queue is used to manage incoming block layer device driver
+ * requests. We have three main type of block driver types which end up making
+ * use of the request_queue:
+ *
+ *   o make_request block drivers (multiqueue)
+ *   o request-based block drivers
+ *   o custom solutions such as scsi-generic
+ *
+ * All partitions share the same request_queue data structure.
+ */
 struct request_queue {
 	struct request		*last_merge;
 	struct elevator_queue	*elevator;