Reviewed-by: Chaitanya Kulkarni <[email protected]>
Signed-off-by: Marcos Paulo de Souza <[email protected]>
---
No changes from v1.
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
Describing better what the function does, what the arguments are meant for, and
what SQ stands for.
Signed-off-by: Marcos Paulo de Souza <[email protected]>
---
Changes from v1:
* Change "SQ" to "only one hw_queue (SQ)" in the function signature
documentation (suggested by Chaitanya)
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..3f13cfb47cf0 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 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 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
Now documented functions of blk-mq.c will appear in the official kernel
documentation.
Signed-off-by: Marcos Paulo de Souza <[email protected]>
---
No changes from v1.
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
Looks good.
Reviewed-by: Chaitanya Kulkarni <[email protected]>
On 4/15/19, 8:28 PM, "[email protected] on behalf of Marcos Paulo de Souza" <[email protected] on behalf of [email protected]> wrote:
Describing better what the function does, what the arguments are meant for, and
what SQ stands for.
Signed-off-by: Marcos Paulo de Souza <[email protected]>
---
Changes from v1:
* Change "SQ" to "only one hw_queue (SQ)" in the function signature
documentation (suggested by Chaitanya)
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..3f13cfb47cf0 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 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 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
Looks good.
Reviewed-by: Chaitanya Kulkarni <[email protected]>
On 4/15/19, 8:28 PM, "Marcos Paulo de Souza" <[email protected]> wrote:
Now documented functions of blk-mq.c will appear in the official kernel
documentation.
Signed-off-by: Marcos Paulo de Souza <[email protected]>
---
No changes from v1.
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
On Tue, 2019-04-16 at 00:28 -0300, Marcos Paulo de Souza wrote:
+AD4 +ACo +AEA-set+AF8-flags: flags of +AEA-set
The above does not look very helpful to me ...
Bart.
On Tue, 2019-04-16 at 00:27 -0300, Marcos Paulo de Souza wrote:
+AD4 Reviewed-by: Chaitanya Kulkarni +ADw-chaitanya.kulkarni+AEA-wdc.com+AD4
+AD4 Signed-off-by: Marcos Paulo de Souza +ADw-marcos.souza.org+AEA-gmail.com+AD4
+AD4 ---
+AD4
+AD4 No changes from v1.
+AD4
+AD4 block/blk-mq.c +AHw 9 +++++++++
+AD4 1 file changed, 9 insertions()
Please always include a cover letter with a patch series that gives an
overview of the purpose of the patch series.
Thanks,
Bart.
gentle ping v2.
On Tue, Apr 16, 2019 at 12:27:59AM -0300, Marcos Paulo de Souza wrote:
> Reviewed-by: Chaitanya Kulkarni <[email protected]>
> Signed-off-by: Marcos Paulo de Souza <[email protected]>
> ---
>
> No changes from v1.
>
> 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
>
--
Thanks,
Marcos
On 5/1/19 8:04 PM, Marcos Paulo de Souza wrote:
> gentle ping v2.
It's not that I hate the series, I just don't see it adding any real
value. It should already be quite clear what the functions do, by name,
and the comments don't really add to that.
--
Jens Axboe
On Thu, May 02, 2019 at 02:37:56PM -0600, Jens Axboe wrote:
> On 5/1/19 8:04 PM, Marcos Paulo de Souza wrote:
> > gentle ping v2.
>
> It's not that I hate the series, I just don't see it adding any real
> value. It should already be quite clear what the functions do, by name,
> and the comments don't really add to that.
My first goal was to make someone to first read the function comment without
going into the details of the code, and at the same time, by adding these
documentations, having these functions being listed at
https://www.kernel.org/doc/html/latest/.
So, in IMHO, they add a fast way, for someone who is trying to understand how
things work, to understand exactly what the function does in some seconds, than
reading the functions code.
In you're now happy with these comments, can you point how can I improve them?
Thanks in advance,
Marcos
>
> --
> Jens Axboe
>
--
Thanks,
Marcos