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
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 <[email protected]>
---
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
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 <[email protected]>
Cc: Jonathan Corbet <[email protected]>
---
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
On Fri, 13 Sep 2019 19:03:00 -0300
André Almeida <[email protected]> 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
On 9/14/19 4:50 AM, Jonathan Corbet wrote:
> On Fri, 13 Sep 2019 19:03:00 -0300
> André Almeida <[email protected]> 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
>