[PATCH v3 0/3] Add documentation of some blk-mq functions

[PATCH v3 0/3] Add documentation of some blk-mq functions

[Marcos Paulo de Souza]

blk_mq_init_sq_queue and blk_mq_init_queue are being documented, more will be
added in further patches.

I would like to thank Chaitanya and Bart for their reviews.

Changes from v2:
* Changed the description of argument @set of blk_mq_init_sq_queue, making it
  less obvious and more informative. Now this argument has two example of
  possible flags for tag_set (suggested by Bart)
* Cover letter added (suggested by Bart)

Changes from v1:
* Change "SQ" to "only one hw_queue (SQ)" in the function signature
  documentation (suggested by Chaitanya)

Marcos Paulo de Souza (3):
  blk-mq.c: Add documention of function blk_mq_init_queue
  blk-mq.c: Rework documention of blk_mq_init_sq_queue function
  Documentation: kernel-api.rst: Add block/blk-mq.c

 Documentation/core-api/kernel-api.rst |  6 ++++++
 block/blk-mq.c                        | 27 ++++++++++++++++++++++++---
 2 files changed, 30 insertions(+), 3 deletions(-)

-- 
2.16.4

[PATCH v3 1/3] blk-mq.c: Add documention of function blk_mq_init_queue

[Marcos Paulo de Souza]

Reviewed-by: Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com>
Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
---
 block/blk-mq.c | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/block/blk-mq.c b/block/blk-mq.c
index 9516304a38ee..4a8277a54c03 100644
--- a/block/blk-mq.c
+++ b/block/blk-mq.c
@@ -2650,6 +2650,15 @@ void blk_mq_release(struct request_queue *q)
 	blk_mq_sysfs_deinit(q);
 }
 
+/**
+ * blk_mq_init_queue - Create a new request queue associating a blk_mq_tag_set
+ * @set: tag_set to be associated with the request queue
+ *
+ * Description:
+ * This function creates a new request queue, associating @set with it.
+ *
+ * Returns a new request queue on success, or ERR_PTR() on failure.
+ */
 struct request_queue *blk_mq_init_queue(struct blk_mq_tag_set *set)
 {
 	struct request_queue *uninit_q, *q;
-- 
2.16.4

[PATCH v3 2/3] blk-mq.c: Rework documention of blk_mq_init_sq_queue function

[Marcos Paulo de Souza]

Describing better what the function does, what the arguments are meant for, and
what SQ stands for.

Reviewed-by: Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com>
Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
---
 block/blk-mq.c | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/block/blk-mq.c b/block/blk-mq.c
index 4a8277a54c03..03f45d0cd795 100644
--- a/block/blk-mq.c
+++ b/block/blk-mq.c
@@ -2675,9 +2675,21 @@ struct request_queue *blk_mq_init_queue(struct blk_mq_tag_set *set)
 }
 EXPORT_SYMBOL(blk_mq_init_queue);
 
-/*
- * Helper for setting up a queue with mq ops, given queue depth, and
- * the passed in mq ops flags.
+/**
+ * blk_mq_init_sq_queue - Create a new request queue with only one hw_queue (SQ)
+ * @set: tag set to be associated by the newly created request queue
+ * @ops: operations to be associated with @set
+ * @queue_depth: number of tags of @set
+ * @set_flags: flags that will be associated with @set, like BLK_MQ_F_TAG_SHARED
+ * or BLK_MQ_F_BLOCKING for example.
+ *
+ * Description:
+ * @set is initialized using @ops, @queue_depth, @set_flags, and using only one
+ * hw_queue (SQ). Later on blk_mq_alloc_tag_set() is called to validate and/or
+ * adjust values of the tag set. blk_mq_init_queue() is called passing @set as
+ * argument, returning a new request queue with @set associated.
+ *
+ * Returns the newly created request queue on success, or ERR_PTR() on failure.
  */
 struct request_queue *blk_mq_init_sq_queue(struct blk_mq_tag_set *set,
 					   const struct blk_mq_ops *ops,
-- 
2.16.4

[PATCH v3 3/3] Documentation: kernel-api.rst: Add block/blk-mq.c

[Marcos Paulo de Souza]

Now documented functions of blk-mq.c will appear in the official kernel
documentation.

Reviewed-by: Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com>
Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
---
 Documentation/core-api/kernel-api.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 71f5d2fe39b7..cc323480ce0e 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -276,6 +276,12 @@ Block Devices
 .. kernel-doc:: block/blk-map.c
    :export:
 
+.. kernel-doc:: block/blk-mq.c
+   :export:
+
+.. kernel-doc:: block/blk-mq.c
+   :internal:
+
 .. kernel-doc:: block/blk-sysfs.c
    :internal:
 
-- 
2.16.4

Re: [PATCH v3 0/3] Add documentation of some blk-mq functions

[Marcos Paulo de Souza]

gentle ping.

On Tue, Apr 16, 2019 at 11:10:27PM -0300, Marcos Paulo de Souza wrote:
> blk_mq_init_sq_queue and blk_mq_init_queue are being documented, more will be
> added in further patches.
> 
> I would like to thank Chaitanya and Bart for their reviews.
> 
> Changes from v2:
> * Changed the description of argument @set of blk_mq_init_sq_queue, making it
>   less obvious and more informative. Now this argument has two example of
>   possible flags for tag_set (suggested by Bart)
> * Cover letter added (suggested by Bart)
> 
> Changes from v1:
> * Change "SQ" to "only one hw_queue (SQ)" in the function signature
>   documentation (suggested by Chaitanya)
> 
> Marcos Paulo de Souza (3):
>   blk-mq.c: Add documention of function blk_mq_init_queue
>   blk-mq.c: Rework documention of blk_mq_init_sq_queue function
>   Documentation: kernel-api.rst: Add block/blk-mq.c
> 
>  Documentation/core-api/kernel-api.rst |  6 ++++++
>  block/blk-mq.c                        | 27 ++++++++++++++++++++++++---
>  2 files changed, 30 insertions(+), 3 deletions(-)
> 
> -- 
> 2.16.4
> 

-- 
Thanks,
Marcos