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

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

[Marcos Paulo de Souza]

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 2/3] blk-mq.c: Rework documention of blk_mq_init_sq_queue function

[Marcos Paulo de Souza]

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

Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
---
 block/blk-mq.c | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/block/blk-mq.c b/block/blk-mq.c
index 4a8277a54c03..fd0bf89b8a73 100644
--- a/block/blk-mq.c
+++ b/block/blk-mq.c
@@ -2675,9 +2675,20 @@ 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 a SQ queue and tag set
+ * @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 of @set
+ *
+ * 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 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.

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 1/3] blk-mq.c: Add documention of function blk_mq_init_queue

[Chaitanya Kulkarni]

Looks good.

Reviewed-by: Chaitanya Kulkarni <chaitanya.kulkarni@wdc.com>

On 4/13/19 8:11 PM, Marcos Paulo de Souza wrote:
> 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;
> 

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

[Chaitanya Kulkarni]

On 4/13/19 8:11 PM, Marcos Paulo de Souza wrote:
> Describing better what the function does, and what the arguments are
> meant for.
> 
> Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
> ---
>   block/blk-mq.c | 17 ++++++++++++++---
>   1 file changed, 14 insertions(+), 3 deletions(-)
> 
> diff --git a/block/blk-mq.c b/block/blk-mq.c
> index 4a8277a54c03..fd0bf89b8a73 100644
> --- a/block/blk-mq.c
> +++ b/block/blk-mq.c
> @@ -2675,9 +2675,20 @@ 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.
> +/**
Is following line beyond 80 columns ?
> + * blk_mq_init_sq_queue - Create a new request queue with a SQ queue and tag set
It will be great if we describe what SQ in the above line, otherwise we 
stating just obvious here.
> + * @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 of @set
> + *
> + * 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,
> 

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

[Marcos Paulo de Souza]

On Sun, Apr 14, 2019 at 09:02:13PM +0000, Chaitanya Kulkarni wrote:
> On 4/13/19 8:11 PM, Marcos Paulo de Souza wrote:
> > Describing better what the function does, and what the arguments are
> > meant for.
> > 
> > Signed-off-by: Marcos Paulo de Souza <marcos.souza.org@gmail.com>
> > ---
> >   block/blk-mq.c | 17 ++++++++++++++---
> >   1 file changed, 14 insertions(+), 3 deletions(-)
> > 
> > diff --git a/block/blk-mq.c b/block/blk-mq.c
> > index 4a8277a54c03..fd0bf89b8a73 100644
> > --- a/block/blk-mq.c
> > +++ b/block/blk-mq.c
> > @@ -2675,9 +2675,20 @@ 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.
> > +/**
> Is following line beyond 80 columns ?

Actually it hit the limit of 80 columns.

> > + * blk_mq_init_sq_queue - Create a new request queue with a SQ queue and tag set
> It will be great if we describe what SQ in the above line, otherwise we 
> stating just obvious here.

You're right, I will change the "SQ" for "only one hw_queue (SQ)", to describe
what is the 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 of @set
> > + *
> > + * 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,
> > 
> 

-- 
Thanks,
Marcos