| Message ID | 20220507084643.18278-1-bagasdotme@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | Netdev Maintainers |
| Headers | show |
| Series | [net-next,v3] net/core: Rephrase function description of __dev_queue_xmit() | expand |
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 <akiyks@gmail.com> 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 <sfr@canb.auug.org.au> Fixes: c526fd8f9f4f21 ("net: inline dev_queue_xmit()") Link: https://lore.kernel.org/linux-next/20220503073420.6d3f135d@canb.auug.org.au/ Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Jakub Kicinski <kuba@kernel.org> Cc: "David S. Miller" <davem@davemloft.net> Cc: Pavel Begunkov <asml.silence@gmail.com> --- 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 *
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 <akiyks@gmail.com> > 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 <sfr@canb.auug.org.au> > Fixes: c526fd8f9f4f21 ("net: inline dev_queue_xmit()") > Link: https://lore.kernel.org/linux-next/20220503073420.6d3f135d@canb.auug.org.au/ > Signed-off-by: Akira Yokosawa <akiyks@gmail.com> > Cc: Jakub Kicinski <kuba@kernel.org> > Cc: "David S. Miller" <davem@davemloft.net> > Cc: Pavel Begunkov <asml.silence@gmail.com> > --- > 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.
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.
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.
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) {
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/20220503073420.6d3f135d@canb.auug.org.au/ Reported-by: Stephen Rothwell <sfr@canb.auug.org.au> Cc: Ben Greear <greearb@candelatech.com> Cc: Pavel Begunkov <asml.silence@gmail.com> Cc: "David S. Miller" <davem@davemloft.net> Cc: Jakub Kicinski <kuba@kernel.org> Cc: Akira Yokosawa <akiyks@gmail.com> Cc: netdev@vger.kernel.org Cc: linux-next@vger.kernel.org Cc: linux-kernel@vger.kernel.org Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> --- 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/20220505082907.42393-1-bagasdotme@gmail.com/ net/core/dev.c | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) base-commit: 8fc0b6992a06998404321f26a57ea54522659b64