linux-block.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH v2 0/4] null_blk: fixes around nr_devices and log improvements
@ 2019-09-13 22:02 André Almeida
  2019-09-13 22:02 ` [PATCH v2 1/4] null_blk: do not fail the module load with zero devices André Almeida
                   ` (3 more replies)
  0 siblings, 4 replies; 13+ messages in thread
From: André Almeida @ 2019-09-13 22:02 UTC (permalink / raw)
  To: linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman, André Almeida

Hello,

This patch series address feedback for a previous patch series sent by
me "docs: block: null_blk: enhance document style"[1].

First patch removes a restriction that prevents null_blk to load with
(nr_devices == 0). This restriction breaks applications, so it's a bug. I
have tested it running the kernel with `null_blk.nr_devices=0`.

In the previous series I have changed the type of var nr_devices, but I
forgot to change the type at module_param(). The second patch fix that.

The third patch uses a cleaver approach to make log messages consistent
using pr_fmt and the last one add a note on how to do that at the
coding style documentation.

Thanks,
	André

Changes since v1:
 - Add "Fixes" tag at [2/4]
 - No more headers reordering at [3/4]
 - Use #undef pr_fmt and KBUILD_MODNAME at [3/4] and [4/4]
 - Replace "printk.h" for "kernel.h" at [4/4]

 More details are provided at each patch changelog

[1] https://patchwork.kernel.org/project/linux-block/list/?series=172853

André Almeida (4):
  null_blk: do not fail the module load with zero devices
  null_blk: match the type of parameter nr_devices
  null_blk: format pr_* logs with pr_fmt
  coding-style: add explanation about pr_fmt macro

 Documentation/process/coding-style.rst | 10 +++++++++-
 drivers/block/null_blk.h               |  4 +++-
 drivers/block/null_blk_main.c          | 24 ++++++++++--------------
 drivers/block/null_blk_zoned.c         |  6 +++---
 4 files changed, 25 insertions(+), 19 deletions(-)

-- 
2.23.0


^ permalink raw reply	[flat|nested] 13+ messages in thread

* [PATCH v2 1/4] null_blk: do not fail the module load with zero devices
  2019-09-13 22:02 [PATCH v2 0/4] null_blk: fixes around nr_devices and log improvements André Almeida
@ 2019-09-13 22:02 ` André Almeida
  2019-09-13 22:15   ` Chaitanya Kulkarni
  2019-09-13 22:17   ` Bart Van Assche
  2019-09-13 22:02 ` [PATCH v2 2/4] null_blk: match the type of parameter nr_devices André Almeida
                   ` (2 subsequent siblings)
  3 siblings, 2 replies; 13+ messages in thread
From: André Almeida @ 2019-09-13 22:02 UTC (permalink / raw)
  To: linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman, André Almeida

The module load should fail only if there is something wrong with the
configuration or if an error prevents it to work properly. The module
should be able to be loaded with (nr_device == 0), since it will not
trigger errors or be in malfunction state. Preventing loading with zero
devices also breaks applications that configures this module using
configfs API. Remove the nr_device check to fix this.

Signed-off-by: André Almeida <andrealmeid@collabora.com>
Fixes: f7c4ce890dd2 ("null_blk: validate the number of devices")
---
Changes since v1:
- None
---
 drivers/block/null_blk_main.c | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/drivers/block/null_blk_main.c b/drivers/block/null_blk_main.c
index ab4b87677139..be32cb5ed339 100644
--- a/drivers/block/null_blk_main.c
+++ b/drivers/block/null_blk_main.c
@@ -1758,10 +1758,6 @@ static int __init null_init(void)
 		pr_err("null_blk: legacy IO path no longer available\n");
 		return -EINVAL;
 	}
-	if (!nr_devices) {
-		pr_err("null_blk: invalid number of devices\n");
-		return -EINVAL;
-	}
 	if (g_queue_mode == NULL_Q_MQ && g_use_per_node_hctx) {
 		if (g_submit_queues != nr_online_nodes) {
 			pr_warn("null_blk: submit_queues param is set to %u.\n",
-- 
2.23.0


^ permalink raw reply related	[flat|nested] 13+ messages in thread

* [PATCH v2 2/4] null_blk: match the type of parameter nr_devices
  2019-09-13 22:02 [PATCH v2 0/4] null_blk: fixes around nr_devices and log improvements André Almeida
  2019-09-13 22:02 ` [PATCH v2 1/4] null_blk: do not fail the module load with zero devices André Almeida
@ 2019-09-13 22:02 ` André Almeida
  2019-09-13 22:15   ` Chaitanya Kulkarni
  2019-09-13 22:02 ` [PATCH v2 3/4] null_blk: format pr_* logs with pr_fmt André Almeida
  2019-09-13 22:03 ` [PATCH v2 4/4] coding-style: add explanation about pr_fmt macro André Almeida
  3 siblings, 1 reply; 13+ messages in thread
From: André Almeida @ 2019-09-13 22:02 UTC (permalink / raw)
  To: linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman, André Almeida

Since the variable nr_devices is an unsigned int, the module_param()
should also use this type. Change the type so they can match.

Signed-off-by: André Almeida <andrealmeid@collabora.com>
Fixes: f7c4ce890dd2 ("null_blk: validate the number of devices")
---
Changes since v1:
- Add "Fixes" tag
---
 drivers/block/null_blk_main.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/block/null_blk_main.c b/drivers/block/null_blk_main.c
index be32cb5ed339..5d20d65041bd 100644
--- a/drivers/block/null_blk_main.c
+++ b/drivers/block/null_blk_main.c
@@ -142,7 +142,7 @@ module_param_named(bs, g_bs, int, 0444);
 MODULE_PARM_DESC(bs, "Block size (in bytes)");
 
 static unsigned int nr_devices = 1;
-module_param(nr_devices, int, 0444);
+module_param(nr_devices, uint, 0444);
 MODULE_PARM_DESC(nr_devices, "Number of devices to register");
 
 static bool g_blocking;
-- 
2.23.0


^ permalink raw reply related	[flat|nested] 13+ messages in thread

* [PATCH v2 3/4] null_blk: format pr_* logs with pr_fmt
  2019-09-13 22:02 [PATCH v2 0/4] null_blk: fixes around nr_devices and log improvements André Almeida
  2019-09-13 22:02 ` [PATCH v2 1/4] null_blk: do not fail the module load with zero devices André Almeida
  2019-09-13 22:02 ` [PATCH v2 2/4] null_blk: match the type of parameter nr_devices André Almeida
@ 2019-09-13 22:02 ` André Almeida
  2019-09-13 22:16   ` Chaitanya Kulkarni
  2019-09-13 22:03 ` [PATCH v2 4/4] coding-style: add explanation about pr_fmt macro André Almeida
  3 siblings, 1 reply; 13+ messages in thread
From: André Almeida @ 2019-09-13 22:02 UTC (permalink / raw)
  To: linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman, André Almeida

Instead of writing "null_blk: " at the beginning of each
pr_err/info/warn log message, format messages using pr_fmt() macro.

Signed-off-by: André Almeida <andrealmeid@collabora.com>
---
Changes from v1:
- Use #undef instead of reorder #includes
- Use KBUILD_MODNAME instead of using the hardcoded module name
---
 drivers/block/null_blk.h       |  5 ++++-
 drivers/block/null_blk_main.c  | 16 ++++++++--------
 drivers/block/null_blk_zoned.c |  4 ++--
 3 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/drivers/block/null_blk.h b/drivers/block/null_blk.h
index a1b9929bd911..8a65cb549dd5 100644
--- a/drivers/block/null_blk.h
+++ b/drivers/block/null_blk.h
@@ -2,6 +2,9 @@
 #ifndef __BLK_NULL_BLK_H
 #define __BLK_NULL_BLK_H
 
+#undef pr_fmt
+#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
+
 #include <linux/blkdev.h>
 #include <linux/slab.h>
 #include <linux/blk-mq.h>
@@ -96,7 +99,7 @@ void null_zone_reset(struct nullb_cmd *cmd, sector_t sector);
 #else
 static inline int null_zone_init(struct nullb_device *dev)
 {
-	pr_err("null_blk: CONFIG_BLK_DEV_ZONED not enabled\n");
+	pr_err("CONFIG_BLK_DEV_ZONED not enabled\n");
 	return -EINVAL;
 }
 static inline void null_zone_exit(struct nullb_device *dev) {}
diff --git a/drivers/block/null_blk_main.c b/drivers/block/null_blk_main.c
index 5d20d65041bd..3821fdb85c94 100644
--- a/drivers/block/null_blk_main.c
+++ b/drivers/block/null_blk_main.c
@@ -1311,7 +1311,7 @@ static bool should_requeue_request(struct request *rq)
 
 static enum blk_eh_timer_return null_timeout_rq(struct request *rq, bool res)
 {
-	pr_info("null_blk: rq %p timed out\n", rq);
+	pr_info("rq %p timed out\n", rq);
 	blk_mq_complete_request(rq);
 	return BLK_EH_DONE;
 }
@@ -1739,28 +1739,28 @@ static int __init null_init(void)
 	struct nullb_device *dev;
 
 	if (g_bs > PAGE_SIZE) {
-		pr_warn("null_blk: invalid block size\n");
-		pr_warn("null_blk: defaults block size to %lu\n", PAGE_SIZE);
+		pr_warn("invalid block size\n");
+		pr_warn("defaults block size to %lu\n", PAGE_SIZE);
 		g_bs = PAGE_SIZE;
 	}
 
 	if (!is_power_of_2(g_zone_size)) {
-		pr_err("null_blk: zone_size must be power-of-two\n");
+		pr_err("zone_size must be power-of-two\n");
 		return -EINVAL;
 	}
 
 	if (g_home_node != NUMA_NO_NODE && g_home_node >= nr_online_nodes) {
-		pr_err("null_blk: invalid home_node value\n");
+		pr_err("invalid home_node value\n");
 		g_home_node = NUMA_NO_NODE;
 	}
 
 	if (g_queue_mode == NULL_Q_RQ) {
-		pr_err("null_blk: legacy IO path no longer available\n");
+		pr_err("legacy IO path no longer available\n");
 		return -EINVAL;
 	}
 	if (g_queue_mode == NULL_Q_MQ && g_use_per_node_hctx) {
 		if (g_submit_queues != nr_online_nodes) {
-			pr_warn("null_blk: submit_queues param is set to %u.\n",
+			pr_warn("submit_queues param is set to %u.\n",
 							nr_online_nodes);
 			g_submit_queues = nr_online_nodes;
 		}
@@ -1803,7 +1803,7 @@ static int __init null_init(void)
 		}
 	}
 
-	pr_info("null_blk: module loaded\n");
+	pr_info("module loaded\n");
 	return 0;
 
 err_dev:
diff --git a/drivers/block/null_blk_zoned.c b/drivers/block/null_blk_zoned.c
index cb28d93f2bd1..b2b977be5ddd 100644
--- a/drivers/block/null_blk_zoned.c
+++ b/drivers/block/null_blk_zoned.c
@@ -17,7 +17,7 @@ int null_zone_init(struct nullb_device *dev)
 	unsigned int i;
 
 	if (!is_power_of_2(dev->zone_size)) {
-		pr_err("null_blk: zone_size must be power-of-two\n");
+		pr_err("zone_size must be power-of-two\n");
 		return -EINVAL;
 	}
 
@@ -31,7 +31,7 @@ int null_zone_init(struct nullb_device *dev)
 
 	if (dev->zone_nr_conv >= dev->nr_zones) {
 		dev->zone_nr_conv = dev->nr_zones - 1;
-		pr_info("null_blk: changed the number of conventional zones to %u",
+		pr_info("changed the number of conventional zones to %u",
 			dev->zone_nr_conv);
 	}
 
-- 
2.23.0


^ permalink raw reply related	[flat|nested] 13+ messages in thread

* [PATCH v2 4/4] coding-style: add explanation about pr_fmt macro
  2019-09-13 22:02 [PATCH v2 0/4] null_blk: fixes around nr_devices and log improvements André Almeida
                   ` (2 preceding siblings ...)
  2019-09-13 22:02 ` [PATCH v2 3/4] null_blk: format pr_* logs with pr_fmt André Almeida
@ 2019-09-13 22:03 ` André Almeida
  2019-09-13 22:18   ` Chaitanya Kulkarni
  2019-09-14  7:50   ` Jonathan Corbet
  3 siblings, 2 replies; 13+ messages in thread
From: André Almeida @ 2019-09-13 22:03 UTC (permalink / raw)
  To: linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman, André Almeida

The pr_fmt macro is useful to format log messages printed by pr_XXXX()
functions. Add text to explain the purpose of it, how to use and an
example.

Signed-off-by: André Almeida <andrealmeid@collabora.com>
Cc: Jonathan Corbet <corbet@lwn.net>
---
Changes from v1:
- Add Jonathan as explict Cc
- Replace "include/printk.h" by "#include <linux/kernel.h>
- Add note about #undef
- Replace hardcore string by KBUILD_MODNAME at the example
---
 Documentation/process/coding-style.rst | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index f4a2198187f9..1a33a933fbd3 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -819,7 +819,15 @@ which you should use to make sure messages are matched to the right device
 and driver, and are tagged with the right level:  dev_err(), dev_warn(),
 dev_info(), and so forth.  For messages that aren't associated with a
 particular device, <linux/printk.h> defines pr_notice(), pr_info(),
-pr_warn(), pr_err(), etc.
+pr_warn(), pr_err(), etc. It's possible to format pr_XXX() messages using the
+macro pr_fmt() to prevent rewriting the style of messages. It should be
+defined before ``#include <linux/kernel.h>``, to avoid compiler warning about
+redefinitions, or just use ``#undef pr_fmt``. This is particularly useful for
+adding the name of the module at the beginning of the message, for instance:
+
+.. code-block:: c
+
+        #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
 
 Coming up with good debugging messages can be quite a challenge; and once
 you have them, they can be a huge help for remote troubleshooting.  However
-- 
2.23.0


^ permalink raw reply related	[flat|nested] 13+ messages in thread

* Re: [PATCH v2 1/4] null_blk: do not fail the module load with zero devices
  2019-09-13 22:02 ` [PATCH v2 1/4] null_blk: do not fail the module load with zero devices André Almeida
@ 2019-09-13 22:15   ` Chaitanya Kulkarni
  2019-09-13 22:17   ` Bart Van Assche
  1 sibling, 0 replies; 13+ messages in thread
From: Chaitanya Kulkarni @ 2019-09-13 22:15 UTC (permalink / raw)
  To: André Almeida, linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman

Looks good.

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

On 09/13/2019 03:04 PM, André Almeida wrote:
> The module load should fail only if there is something wrong with the
> configuration or if an error prevents it to work properly. The module
> should be able to be loaded with (nr_device == 0), since it will not
> trigger errors or be in malfunction state. Preventing loading with zero
> devices also breaks applications that configures this module using
> configfs API. Remove the nr_device check to fix this.
>
> Signed-off-by: André Almeida <andrealmeid@collabora.com>
> Fixes: f7c4ce890dd2 ("null_blk: validate the number of devices")
> ---
> Changes since v1:
> - None
> ---
>   drivers/block/null_blk_main.c | 4 ----
>   1 file changed, 4 deletions(-)
>
> diff --git a/drivers/block/null_blk_main.c b/drivers/block/null_blk_main.c
> index ab4b87677139..be32cb5ed339 100644
> --- a/drivers/block/null_blk_main.c
> +++ b/drivers/block/null_blk_main.c
> @@ -1758,10 +1758,6 @@ static int __init null_init(void)
>   		pr_err("null_blk: legacy IO path no longer available\n");
>   		return -EINVAL;
>   	}
> -	if (!nr_devices) {
> -		pr_err("null_blk: invalid number of devices\n");
> -		return -EINVAL;
> -	}
>   	if (g_queue_mode == NULL_Q_MQ && g_use_per_node_hctx) {
>   		if (g_submit_queues != nr_online_nodes) {
>   			pr_warn("null_blk: submit_queues param is set to %u.\n",
>


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH v2 2/4] null_blk: match the type of parameter nr_devices
  2019-09-13 22:02 ` [PATCH v2 2/4] null_blk: match the type of parameter nr_devices André Almeida
@ 2019-09-13 22:15   ` Chaitanya Kulkarni
  0 siblings, 0 replies; 13+ messages in thread
From: Chaitanya Kulkarni @ 2019-09-13 22:15 UTC (permalink / raw)
  To: André Almeida, linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman

Looks good.

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

On 09/13/2019 03:04 PM, André Almeida wrote:
> Since the variable nr_devices is an unsigned int, the module_param()
> should also use this type. Change the type so they can match.
>
> Signed-off-by: André Almeida <andrealmeid@collabora.com>
> Fixes: f7c4ce890dd2 ("null_blk: validate the number of devices")
> ---
> Changes since v1:
> - Add "Fixes" tag
> ---
>   drivers/block/null_blk_main.c | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/drivers/block/null_blk_main.c b/drivers/block/null_blk_main.c
> index be32cb5ed339..5d20d65041bd 100644
> --- a/drivers/block/null_blk_main.c
> +++ b/drivers/block/null_blk_main.c
> @@ -142,7 +142,7 @@ module_param_named(bs, g_bs, int, 0444);
>   MODULE_PARM_DESC(bs, "Block size (in bytes)");
>
>   static unsigned int nr_devices = 1;
> -module_param(nr_devices, int, 0444);
> +module_param(nr_devices, uint, 0444);
>   MODULE_PARM_DESC(nr_devices, "Number of devices to register");
>
>   static bool g_blocking;
>


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH v2 3/4] null_blk: format pr_* logs with pr_fmt
  2019-09-13 22:02 ` [PATCH v2 3/4] null_blk: format pr_* logs with pr_fmt André Almeida
@ 2019-09-13 22:16   ` Chaitanya Kulkarni
  0 siblings, 0 replies; 13+ messages in thread
From: Chaitanya Kulkarni @ 2019-09-13 22:16 UTC (permalink / raw)
  To: André Almeida, linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman

Looks good.

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

On 09/13/2019 03:04 PM, André Almeida wrote:
> Instead of writing "null_blk: " at the beginning of each
> pr_err/info/warn log message, format messages using pr_fmt() macro.
>
> Signed-off-by: André Almeida<andrealmeid@collabora.com>
> ---
> Changes from v1:


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH v2 1/4] null_blk: do not fail the module load with zero devices
  2019-09-13 22:02 ` [PATCH v2 1/4] null_blk: do not fail the module load with zero devices André Almeida
  2019-09-13 22:15   ` Chaitanya Kulkarni
@ 2019-09-13 22:17   ` Bart Van Assche
  2019-09-13 22:37     ` Chaitanya Kulkarni
  1 sibling, 1 reply; 13+ messages in thread
From: Bart Van Assche @ 2019-09-13 22:17 UTC (permalink / raw)
  To: André Almeida, linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman

On 9/13/19 3:02 PM, André Almeida wrote:
> The module load should fail only if there is something wrong with the
> configuration or if an error prevents it to work properly. The module
> should be able to be loaded with (nr_device == 0), since it will not
> trigger errors or be in malfunction state. Preventing loading with zero
> devices also breaks applications that configures this module using
> configfs API. Remove the nr_device check to fix this.

I just noticed that this patch is necessary to unbreak blktests. The srp 
tests fail as follows with Jens' for-next branch:

modprobe: ERROR: could not insert 'null_blk': Invalid argument

I think that error is triggered by the following statement in 
common/multipath-over-rdma:

     modprobe null_blk nr_devices=0 || return $?

Bart.

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH v2 4/4] coding-style: add explanation about pr_fmt macro
  2019-09-13 22:03 ` [PATCH v2 4/4] coding-style: add explanation about pr_fmt macro André Almeida
@ 2019-09-13 22:18   ` Chaitanya Kulkarni
  2019-09-14  7:50   ` Jonathan Corbet
  1 sibling, 0 replies; 13+ messages in thread
From: Chaitanya Kulkarni @ 2019-09-13 22:18 UTC (permalink / raw)
  To: André Almeida, linux-block, linux-doc, linux-kernel
  Cc: corbet, axboe, kernel, krisman

I'm not super familier with the format, will let someone do the
final review.

In general looks good.

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

On 09/13/2019 03:04 PM, André Almeida wrote:
> The pr_fmt macro is useful to format log messages printed by pr_XXXX()
> functions. Add text to explain the purpose of it, how to use and an
> example.
>
> Signed-off-by: André Almeida<andrealmeid@collabora.com>
> Cc: Jonathan Corbet<corbet@lwn.net>
> ---
> Changes from v1:
> - Add Jonathan as explict Cc
> - Replace "include/printk.h" by "#include <linux/kernel.h>
> - Add note about #undef
> - Replace hardcore string by KBUILD_MODNAME at the example
> ---


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH v2 1/4] null_blk: do not fail the module load with zero devices
  2019-09-13 22:17   ` Bart Van Assche
@ 2019-09-13 22:37     ` Chaitanya Kulkarni
  0 siblings, 0 replies; 13+ messages in thread
From: Chaitanya Kulkarni @ 2019-09-13 22:37 UTC (permalink / raw)
  To: Bart Van Assche, André Almeida, linux-block, linux-doc,
	linux-kernel
  Cc: corbet, axboe, kernel, krisman

On 09/13/2019 03:18 PM, Bart Van Assche wrote:
> I just noticed that this patch is necessary to unbreak blktests. The srp
> tests fail as follows with Jens' for-next branch:
>
> modprobe: ERROR: could not insert 'null_blk': Invalid argument
>
> I think that error is triggered by the following statement in
> common/multipath-over-rdma:
>
>       modprobe null_blk nr_devices=0 || return $?
>
> Bart.
>

Not only that I'm sure my membacked null_blk testcases will also start
failing without this patch, which I've not posted on mailing list yet.


^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH v2 4/4] coding-style: add explanation about pr_fmt macro
  2019-09-13 22:03 ` [PATCH v2 4/4] coding-style: add explanation about pr_fmt macro André Almeida
  2019-09-13 22:18   ` Chaitanya Kulkarni
@ 2019-09-14  7:50   ` Jonathan Corbet
  2019-09-16 13:38     ` André Almeida
  1 sibling, 1 reply; 13+ messages in thread
From: Jonathan Corbet @ 2019-09-14  7:50 UTC (permalink / raw)
  To: André Almeida
  Cc: linux-block, linux-doc, linux-kernel, axboe, kernel, krisman

On Fri, 13 Sep 2019 19:03:00 -0300
André Almeida <andrealmeid@collabora.com> wrote:

> The pr_fmt macro is useful to format log messages printed by pr_XXXX()
> functions. Add text to explain the purpose of it, how to use and an
> example.

So I've finally had a chance to take a real look at this...

> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index f4a2198187f9..1a33a933fbd3 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -819,7 +819,15 @@ which you should use to make sure messages are matched to the right device
>  and driver, and are tagged with the right level:  dev_err(), dev_warn(),
>  dev_info(), and so forth.  For messages that aren't associated with a
>  particular device, <linux/printk.h> defines pr_notice(), pr_info(),
> -pr_warn(), pr_err(), etc.
> +pr_warn(), pr_err(), etc. It's possible to format pr_XXX() messages using the
> +macro pr_fmt() to prevent rewriting the style of messages. It should be
> +defined before ``#include <linux/kernel.h>``, to avoid compiler warning about
> +redefinitions, or just use ``#undef pr_fmt``. This is particularly useful for
> +adding the name of the module at the beginning of the message, for instance:
> +
> +.. code-block:: c
> +
> +        #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt

Honestly, I think that this is out of scope for a document on coding
style.  That document is already far too long for most people to read, I
don't think we should load it down with more stuff that isn't directly
style related.

That said, the information can be useful.  I wanted to say that it should
go with the documentation of the pr_* macros but ... well ... um ... we
don't seem to have a whole lot of that.  Figures.

I suspect this is more than you wanted to sign up for, but...IMO, the right
thing to do is to fill printk.h with a nice set of kerneldoc comments
describing how this stuff should be used, then to pull that information
into the core-api manual, somewhere near our extensive discussion of printk
formats.  It's amazing that we lack docs for something so basic.

Thanks,

jon

^ permalink raw reply	[flat|nested] 13+ messages in thread

* Re: [PATCH v2 4/4] coding-style: add explanation about pr_fmt macro
  2019-09-14  7:50   ` Jonathan Corbet
@ 2019-09-16 13:38     ` André Almeida
  0 siblings, 0 replies; 13+ messages in thread
From: André Almeida @ 2019-09-16 13:38 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-block, linux-doc, linux-kernel, axboe, kernel, krisman

On 9/14/19 4:50 AM, Jonathan Corbet wrote:
> On Fri, 13 Sep 2019 19:03:00 -0300
> André Almeida <andrealmeid@collabora.com> wrote:
> 
>> The pr_fmt macro is useful to format log messages printed by pr_XXXX()
>> functions. Add text to explain the purpose of it, how to use and an
>> example.
> 
> So I've finally had a chance to take a real look at this...
> 
>> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
>> index f4a2198187f9..1a33a933fbd3 100644
>> --- a/Documentation/process/coding-style.rst
>> +++ b/Documentation/process/coding-style.rst
>> @@ -819,7 +819,15 @@ which you should use to make sure messages are matched to the right device
>>  and driver, and are tagged with the right level:  dev_err(), dev_warn(),
>>  dev_info(), and so forth.  For messages that aren't associated with a
>>  particular device, <linux/printk.h> defines pr_notice(), pr_info(),
>> -pr_warn(), pr_err(), etc.
>> +pr_warn(), pr_err(), etc. It's possible to format pr_XXX() messages using the
>> +macro pr_fmt() to prevent rewriting the style of messages. It should be
>> +defined before ``#include <linux/kernel.h>``, to avoid compiler warning about
>> +redefinitions, or just use ``#undef pr_fmt``. This is particularly useful for
>> +adding the name of the module at the beginning of the message, for instance:
>> +
>> +.. code-block:: c
>> +
>> +        #define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
> 
> Honestly, I think that this is out of scope for a document on coding
> style.  That document is already far too long for most people to read, I
> don't think we should load it down with more stuff that isn't directly
> style related.
> 
> That said, the information can be useful.  I wanted to say that it should
> go with the documentation of the pr_* macros but ... well ... um ... we
> don't seem to have a whole lot of that.  Figures.
> 
> I suspect this is more than you wanted to sign up for, but...IMO, the right
> thing to do is to fill printk.h with a nice set of kerneldoc comments
> describing how this stuff should be used, then to pull that information
> into the core-api manual, somewhere near our extensive discussion of printk
> formats.  It's amazing that we lack docs for something so basic.
> 

Thanks for the feedback jon. For now, I'll drop this patch for this
series. In a future patch I'll move this text for
Documentation/core-api/printk-formats.rst and will also add kernel-doc
comments to pr_XXXX() functions.

> Thanks,
> 
> jon
> 


^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2019-09-16 13:40 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-09-13 22:02 [PATCH v2 0/4] null_blk: fixes around nr_devices and log improvements André Almeida
2019-09-13 22:02 ` [PATCH v2 1/4] null_blk: do not fail the module load with zero devices André Almeida
2019-09-13 22:15   ` Chaitanya Kulkarni
2019-09-13 22:17   ` Bart Van Assche
2019-09-13 22:37     ` Chaitanya Kulkarni
2019-09-13 22:02 ` [PATCH v2 2/4] null_blk: match the type of parameter nr_devices André Almeida
2019-09-13 22:15   ` Chaitanya Kulkarni
2019-09-13 22:02 ` [PATCH v2 3/4] null_blk: format pr_* logs with pr_fmt André Almeida
2019-09-13 22:16   ` Chaitanya Kulkarni
2019-09-13 22:03 ` [PATCH v2 4/4] coding-style: add explanation about pr_fmt macro André Almeida
2019-09-13 22:18   ` Chaitanya Kulkarni
2019-09-14  7:50   ` Jonathan Corbet
2019-09-16 13:38     ` André Almeida

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).