Commit c526fd8f9f4f21 ("net: inline dev_queue_xmit()") inlines
dev_queue_xmit() that contains comment quote from Ben Greear, which
originates from commit af191367a75262 ("[NET]: Document ->hard_start_xmit()
locking in comments."). It triggers htmldocs warning:
Documentation/networking/kapi:92: net/core/dev.c:4101: WARNING: Missing matching underline for section title overline.
-----------------------------------------------------------------------------------
I notice this method can also return errors from the queue disciplines,
including NET_XMIT_DROP, which is a positive value. So, errors can also
Fix the warning by rephrasing the function description. This is done by
incorporating notes from the quote as well as dropping the banner and
attribution signature.
Fixes: c526fd8f9f4f21 ("net: inline dev_queue_xmit()")
Link: https://lore.kernel.org/linux-next/[email protected]/
Reported-by: Stephen Rothwell <[email protected]>
Cc: Ben Greear <[email protected]>
Cc: Pavel Begunkov <[email protected]>
Cc: "David S. Miller" <[email protected]>
Cc: Jakub Kicinski <[email protected]>
Cc: Akira Yokosawa <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Signed-off-by: Bagas Sanjaya <[email protected]>
---
Changes since v2 [1]:
- Approach the problem by rephrasing (suggested by Jakub)
- Explain that inlining in the Fixes: commit triggers the warning
(suggested by Akira)
[1]: https://lore.kernel.org/linux-doc/[email protected]/
net/core/dev.c | 30 ++++++++++++++----------------
1 file changed, 14 insertions(+), 16 deletions(-)
diff --git a/net/core/dev.c b/net/core/dev.c
index f036ccb61da4da..75c00bb45f9b46 100644
--- a/net/core/dev.c
+++ b/net/core/dev.c
@@ -4139,22 +4139,20 @@ struct netdev_queue *netdev_core_pick_tx(struct net_device *dev,
* have set the device and priority and built the buffer before calling
* this function. The function can be called from an interrupt.
*
- * A negative errno code is returned on a failure. A success does not
- * guarantee the frame will be transmitted as it may be dropped due
- * to congestion or traffic shaping.
- *
- * -----------------------------------------------------------------------------------
- * I notice this method can also return errors from the queue disciplines,
- * including NET_XMIT_DROP, which is a positive value. So, errors can also
- * be positive.
- *
- * Regardless of the return value, the skb is consumed, so it is currently
- * difficult to retry a send to this method. (You can bump the ref count
- * before sending to hold a reference for retry if you are careful.)
- *
- * When calling this method, interrupts MUST be enabled. This is because
- * the BH enable code must have IRQs enabled so that it will not deadlock.
- * --BLG
+ * This function can returns a negative errno code in case of failure.
+ * Positive errno code can also be returned from the queue disciplines
+ * (including NET_XMIT_DROP). A success does not guarantee the frame
+ * will be transmitted as it may be dropped due to congestion or
+ * traffic shaping.
+ *
+ * The skb is consumed anyway regardless of return value, so it is
+ * currently difficult to retry sending to this method. If careful,
+ * you can bump the ref count before sending to hold a reference for
+ * retry.
+ *
+ * Interrupts must be enabled when calling this function, because
+ * BH-enabled code must have IRQs enabled so that it will not deadlock.
+ *
*/
int __dev_queue_xmit(struct sk_buff *skb, struct net_device *sb_dev)
{
base-commit: 8fc0b6992a06998404321f26a57ea54522659b64
--
An old man doll... just what I always wanted! - Clara
On 2022/05/07 17:46,
Bagas Sanjaya wrote:
> Commit c526fd8f9f4f21 ("net: inline dev_queue_xmit()") inlines
> dev_queue_xmit() that contains comment quote from Ben Greear, which
> originates from commit af191367a75262 ("[NET]: Document ->hard_start_xmit()
> locking in comments.").It triggers htmldocs warning:
What I asked was the explanation of *why* the inlining of the
function caused the new warning.
Your explanation above tries to tell *what* the offending commit
did, which is not what I asked. Furthermore, your explanation
is not accurate in that the comment block does not belong to
dev_queue_xmit() but to __dev_queue_xmit().
After seeking the answer myself, I reached a conclusion that
it is wrong to meddle with the comment block.
So, appended below is my version of the fix with the answer to
Stephen's question, "I am not sure why this has turned up just now."
Stephen, Jakub, what do you think?
Thanks, Akira
----8<--------------
From: Akira Yokosawa <[email protected]>
Subject: [PATCH -next] net/core: Hide __dev_queue_xmit()'s kernel-doc
Commit c526fd8f9f4f21 ("net: inline dev_queue_xmit()") added
export of __dev_queue_exit() to cope with inlining of its
wrapper functions dev_queue_xmit() and dev_queue_xmit_accel().
This made __dev_queue_exit()'s comment block visible to Sphinx
processing in "make htmldocs" because
Documentation/networking/kapi.rst has the directive of:
.. kernel-doc:: net/core/dev.c
:export:
Unfortunately, the kernel-doc style comment has a number of
issues when parsed as RestructuredText. Stephen reported a
new warning message from "make htmldocs" caused by one of
such issues.
The leading "__" in the function name indicates that it is an
internal API and should not be widely used.
Exposing documentation of such a function in HTML and PDF
documentations does not make sense.
For the time being, hide the kernel-doc style comment from Sphinx
processing by removing the kernel-doc marker of "/**".
Proper kernel-doc comments should be added to the inlined
wrapper functions, which is deferred to those who are familiar
with those netdev APIs.
Reported-by: Stephen Rothwell <[email protected]>
Fixes: c526fd8f9f4f21 ("net: inline dev_queue_xmit()")
Link: https://lore.kernel.org/linux-next/[email protected]/
Signed-off-by: Akira Yokosawa <[email protected]>
Cc: Jakub Kicinski <[email protected]>
Cc: "David S. Miller" <[email protected]>
Cc: Pavel Begunkov <[email protected]>
---
net/core/dev.c | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/net/core/dev.c b/net/core/dev.c
index c2d73595a7c3..a97fd413d705 100644
--- a/net/core/dev.c
+++ b/net/core/dev.c
@@ -4085,8 +4085,7 @@ struct netdev_queue *netdev_core_pick_tx(struct net_device *dev,
return netdev_get_tx_queue(dev, queue_index);
}
-/**
- * __dev_queue_xmit - transmit a buffer
+/* __dev_queue_xmit - transmit a buffer
* @skb: buffer to transmit
* @sb_dev: suboordinate device used for L2 forwarding offload
*
--
2.25.1
On Sun, May 08, 2022 at 08:48:10PM +0900, Akira Yokosawa wrote:
> So, appended below is my version of the fix with the answer to
> Stephen's question, "I am not sure why this has turned up just now."
>
> Stephen, Jakub, what do you think?
>
> Thanks, Akira
>
> ----8<--------------
> From: Akira Yokosawa <[email protected]>
> Subject: [PATCH -next] net/core: Hide __dev_queue_xmit()'s kernel-doc
>
> Commit c526fd8f9f4f21 ("net: inline dev_queue_xmit()") added
> export of __dev_queue_exit() to cope with inlining of its
> wrapper functions dev_queue_xmit() and dev_queue_xmit_accel().
> This made __dev_queue_exit()'s comment block visible to Sphinx
> processing in "make htmldocs" because
> Documentation/networking/kapi.rst has the directive of:
>
> .. kernel-doc:: net/core/dev.c
> :export:
>
> Unfortunately, the kernel-doc style comment has a number of
> issues when parsed as RestructuredText. Stephen reported a
> new warning message from "make htmldocs" caused by one of
> such issues.
>
> The leading "__" in the function name indicates that it is an
> internal API and should not be widely used.
> Exposing documentation of such a function in HTML and PDF
> documentations does not make sense.
>
Oops, I don't see that internal API marker. Maybe we can add "Only
public funtions should be added kernel-doc comments" note to
Documentation/doc-guide/kernel-doc.rst?
> For the time being, hide the kernel-doc style comment from Sphinx
> processing by removing the kernel-doc marker of "/**".
>
> Proper kernel-doc comments should be added to the inlined
> wrapper functions, which is deferred to those who are familiar
> with those netdev APIs.
>
Ah! Thanks for the explanation.
Did you mean proper kernel-doc comments should be added to the wrapper
functions that called this inlined method?
> Reported-by: Stephen Rothwell <[email protected]>
> Fixes: c526fd8f9f4f21 ("net: inline dev_queue_xmit()")
> Link: https://lore.kernel.org/linux-next/[email protected]/
> Signed-off-by: Akira Yokosawa <[email protected]>
> Cc: Jakub Kicinski <[email protected]>
> Cc: "David S. Miller" <[email protected]>
> Cc: Pavel Begunkov <[email protected]>
> ---
> net/core/dev.c | 3 +--
> 1 file changed, 1 insertion(+), 2 deletions(-)
>
> diff --git a/net/core/dev.c b/net/core/dev.c
> index c2d73595a7c3..a97fd413d705 100644
> --- a/net/core/dev.c
> +++ b/net/core/dev.c
> @@ -4085,8 +4085,7 @@ struct netdev_queue *netdev_core_pick_tx(struct net_device *dev,
> return netdev_get_tx_queue(dev, queue_index);
> }
>
> -/**
> - * __dev_queue_xmit - transmit a buffer
> +/* __dev_queue_xmit - transmit a buffer
> * @skb: buffer to transmit
> * @sb_dev: suboordinate device used for L2 forwarding offload
> *
> --
> 2.25.1
>
I'm in favor of this patch. Thanks.
--
An old man doll... just what I always wanted! - Clara
On 5/9/22 13:54, Bagas Sanjaya wrote:
> I'm in favor of this patch. Thanks.
>
Oops, I mean I'm in favor of your patch suggestion.
--
An old man doll... just what I always wanted! - Clara
On Mon, 9 May 2022 13:59:48 +0700 Bagas Sanjaya wrote:
> On 5/9/22 13:54, Bagas Sanjaya wrote:
> > I'm in favor of this patch. Thanks.
>
> Oops, I mean I'm in favor of your patch suggestion.
I think I already said what my preference was. This is a trivial
matter, let me just send a patch myself.