[PATCH net-next] net: add documentation for BQL helpers

[PATCH net-next] net: add documentation for BQL helpers

[Florian Fainelli]

Provide a kernel-doc comment documentation for the BQL helpers:
- netdev_sent_queue
- netdev_completed_queue
- netdev_reset_queue

Similarly to how it is done for the other functions, the documentation
only covers the function operating on struct net_device and not struct
netdev_queue.

Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>
---
 include/linux/netdevice.h | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 8ed4ae9..ac36629 100644
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -2101,6 +2101,16 @@ static inline void netdev_tx_sent_queue(struct netdev_queue *dev_queue,
 #endif
 }
 
+/**
+ * 	netdev_sent_queue - report the number of bytes queued to hardware
+ * 	@dev: network device
+ * 	@bytes: number of bytes queued to the hardware device queue
+ *
+ * 	Report the number of bytes queued for sending/completion to the network
+ * 	device hardware queue. @bytes should specify the number of bytes which
+ * 	will be sent over the physical medium (without prepended/appended
+ * 	control blocks, FCS...)
+ */
 static inline void netdev_sent_queue(struct net_device *dev, unsigned int bytes)
 {
 	netdev_tx_sent_queue(netdev_get_tx_queue(dev, 0), bytes);
@@ -2130,6 +2140,16 @@ static inline void netdev_tx_completed_queue(struct netdev_queue *dev_queue,
 #endif
 }
 
+/**
+ * 	netdev_completed_queue - report bytes and packets completed by device
+ * 	@dev: network device
+ * 	@pkts: actual number of packets sent over the medium
+ * 	@bytes: actual number of bytes sent over the medium
+ *
+ * 	Report the number of bytes and packets transmitted by the network device
+ * 	hardware queue over the physical medium (without prepended/appended
+ * 	control blocks, FCS...)
+ */
 static inline void netdev_completed_queue(struct net_device *dev,
 					  unsigned int pkts, unsigned int bytes)
 {
@@ -2144,6 +2164,13 @@ static inline void netdev_tx_reset_queue(struct netdev_queue *q)
 #endif
 }
 
+/**
+ * 	netdev_reset_queue - reset the packets and bytes count of a network device
+ * 	@dev_queue: network device
+ *
+ * 	Reset the bytes and packet count of a network device and clear the
+ * 	software flow control OFF bit for this network device
+ */
 static inline void netdev_reset_queue(struct net_device *dev_queue)
 {
 	netdev_tx_reset_queue(netdev_get_tx_queue(dev_queue, 0));
-- 
1.8.1.2

Re: [PATCH net-next] net: add documentation for BQL helpers

[Eric Dumazet]

On Fri, 2013-09-06 at 11:58 +0100, Florian Fainelli wrote:
> Provide a kernel-doc comment documentation for the BQL helpers:
> - netdev_sent_queue
> - netdev_completed_queue
> - netdev_reset_queue
> 
> Similarly to how it is done for the other functions, the documentation
> only covers the function operating on struct net_device and not struct
> netdev_queue.
> 
> Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>
> ---
>  include/linux/netdevice.h | 27 +++++++++++++++++++++++++++
>  1 file changed, 27 insertions(+)
> 
> diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
> index 8ed4ae9..ac36629 100644
> --- a/include/linux/netdevice.h
> +++ b/include/linux/netdevice.h
> @@ -2101,6 +2101,16 @@ static inline void netdev_tx_sent_queue(struct netdev_queue *dev_queue,
>  #endif
>  }
>  
> +/**
> + * 	netdev_sent_queue - report the number of bytes queued to hardware
> + * 	@dev: network device
> + * 	@bytes: number of bytes queued to the hardware device queue
> + *
> + * 	Report the number of bytes queued for sending/completion to the network
> + * 	device hardware queue. @bytes should specify the number of bytes which
> + * 	will be sent over the physical medium (without prepended/appended
> + * 	control blocks, FCS...)

There is no such requirement.

@bytes should be a good approximation, and should match
netdev_completed_queue() @bytes


If you think of TSO, we know that skb->len does not exactly matches
number of bytes on physical medium ( check qdisc_pkt_len_init() to see
how Qdisc layer tries to get better estimation )


> + */
>  static inline void netdev_sent_queue(struct net_device *dev, unsigned int bytes)
>  {
>  	netdev_tx_sent_queue(netdev_get_tx_queue(dev, 0), bytes);
> @@ -2130,6 +2140,16 @@ static inline void netdev_tx_completed_queue(struct netdev_queue *dev_queue,
>  #endif
>  }
>  
> +/**
> + * 	netdev_completed_queue - report bytes and packets completed by device
> + * 	@dev: network device
> + * 	@pkts: actual number of packets sent over the medium
> + * 	@bytes: actual number of bytes sent over the medium
> + *
> + * 	Report the number of bytes and packets transmitted by the network device
> + * 	hardware queue over the physical medium (without prepended/appended
> + * 	control blocks, FCS...)
> + */

Re: [PATCH net-next] net: add documentation for BQL helpers

[Florian Fainelli]

2013/9/6 Eric Dumazet <eric.dumazet@gmail.com>:
> On Fri, 2013-09-06 at 11:58 +0100, Florian Fainelli wrote:
>> Provide a kernel-doc comment documentation for the BQL helpers:
>> - netdev_sent_queue
>> - netdev_completed_queue
>> - netdev_reset_queue
>>
>> Similarly to how it is done for the other functions, the documentation
>> only covers the function operating on struct net_device and not struct
>> netdev_queue.
>>
>> Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>
>> ---
>>  include/linux/netdevice.h | 27 +++++++++++++++++++++++++++
>>  1 file changed, 27 insertions(+)
>>
>> diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
>> index 8ed4ae9..ac36629 100644
>> --- a/include/linux/netdevice.h
>> +++ b/include/linux/netdevice.h
>> @@ -2101,6 +2101,16 @@ static inline void netdev_tx_sent_queue(struct netdev_queue *dev_queue,
>>  #endif
>>  }
>>
>> +/**
>> + *   netdev_sent_queue - report the number of bytes queued to hardware
>> + *   @dev: network device
>> + *   @bytes: number of bytes queued to the hardware device queue
>> + *
>> + *   Report the number of bytes queued for sending/completion to the network
>> + *   device hardware queue. @bytes should specify the number of bytes which
>> + *   will be sent over the physical medium (without prepended/appended
>> + *   control blocks, FCS...)
>
> There is no such requirement.
>
> @bytes should be a good approximation, and should match
> netdev_completed_queue() @bytes
>
>
> If you think of TSO, we know that skb->len does not exactly matches
> number of bytes on physical medium ( check qdisc_pkt_len_init() to see
> how Qdisc layer tries to get better estimation )

Thanks Eric, do you also want me to update the comment above
netdev_completed_queue() or are you happy with it?
-- 
Florian

Re: [PATCH net-next] net: add documentation for BQL helpers

[Eric Dumazet]

On Fri, 2013-09-06 at 11:58 +0100, Florian Fainelli wrote:

>  
> +/**
> + * 	netdev_completed_queue - report bytes and packets completed by device
> + * 	@dev: network device
> + * 	@pkts: actual number of packets sent over the medium
> + * 	@bytes: actual number of bytes sent over the medium
> + *
> + * 	Report the number of bytes and packets transmitted by the network device
> + * 	hardware queue over the physical medium (without prepended/appended
> + * 	control blocks, FCS...)

Here, you should instead document that the @bytes must exactly match the
amount given in netdev_sent_queue(), or else BQL can panic.

(each queued skb accounts for X bytes on BQL, so at TX completion, same
X must be unaccounted)

[PATCH net-next v2] net: add documentation for BQL helpers

[Florian Fainelli]

Provide a kernel-doc comment documentation for the BQL helpers:
- netdev_sent_queue
- netdev_completed_queue
- netdev_reset_queue

Similarly to how it is done for the other functions, the documentation
only covers the function operating on struct net_device and not struct
netdev_queue.

Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>
---
Change since v1:
- incorporate suggestsions from Eric Dumazet and just specify the exact
  match for netdev_sent_queue/netdev_completed_queue

 include/linux/netdevice.h | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/include/linux/netdevice.h b/include/linux/netdevice.h
index 8ed4ae9..041b42a 100644
--- a/include/linux/netdevice.h
+++ b/include/linux/netdevice.h
@@ -2101,6 +2101,15 @@ static inline void netdev_tx_sent_queue(struct netdev_queue *dev_queue,
 #endif
 }
 
+/**
+ * 	netdev_sent_queue - report the number of bytes queued to hardware
+ * 	@dev: network device
+ * 	@bytes: number of bytes queued to the hardware device queue
+ *
+ * 	Report the number of bytes queued for sending/completion to the network
+ * 	device hardware queue. @bytes should be a good approximation and should
+ * 	exactly match netdev_completed_queue() @bytes
+ */
 static inline void netdev_sent_queue(struct net_device *dev, unsigned int bytes)
 {
 	netdev_tx_sent_queue(netdev_get_tx_queue(dev, 0), bytes);
@@ -2130,6 +2139,16 @@ static inline void netdev_tx_completed_queue(struct netdev_queue *dev_queue,
 #endif
 }
 
+/**
+ * 	netdev_completed_queue - report bytes and packets completed by device
+ * 	@dev: network device
+ * 	@pkts: actual number of packets sent over the medium
+ * 	@bytes: actual number of bytes sent over the medium
+ *
+ * 	Report the number of bytes and packets transmitted by the network device
+ * 	hardware queue over the physical medium, @bytes must exactly match the
+ * 	@bytes amount passed to netdev_sent_queue()
+ */
 static inline void netdev_completed_queue(struct net_device *dev,
 					  unsigned int pkts, unsigned int bytes)
 {
@@ -2144,6 +2163,13 @@ static inline void netdev_tx_reset_queue(struct netdev_queue *q)
 #endif
 }
 
+/**
+ * 	netdev_reset_queue - reset the packets and bytes count of a network device
+ * 	@dev_queue: network device
+ *
+ * 	Reset the bytes and packet count of a network device and clear the
+ * 	software flow control OFF bit for this network device
+ */
 static inline void netdev_reset_queue(struct net_device *dev_queue)
 {
 	netdev_tx_reset_queue(netdev_get_tx_queue(dev_queue, 0));
-- 
1.8.1.2

Re: [PATCH net-next v2] net: add documentation for BQL helpers

[Eric Dumazet]

On Fri, 2013-09-06 at 16:58 +0100, Florian Fainelli wrote:
> Provide a kernel-doc comment documentation for the BQL helpers:
> - netdev_sent_queue
> - netdev_completed_queue
> - netdev_reset_queue
> 
> Similarly to how it is done for the other functions, the documentation
> only covers the function operating on struct net_device and not struct
> netdev_queue.
> 
> Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>
> ---
> Change since v1:
> - incorporate suggestsions from Eric Dumazet and just specify the exact
>   match for netdev_sent_queue/netdev_completed_queue

Acked-by: Eric Dumazet <edumazet@google.com>

Thanks

Re: [PATCH net-next v2] net: add documentation for BQL helpers

[David Miller]

From: "Florian Fainelli" <f.fainelli@gmail.com>
Date: Fri, 6 Sep 2013 16:58:00 +0100

> Provide a kernel-doc comment documentation for the BQL helpers:
> - netdev_sent_queue
> - netdev_completed_queue
> - netdev_reset_queue
> 
> Similarly to how it is done for the other functions, the documentation
> only covers the function operating on struct net_device and not struct
> netdev_queue.
> 
> Signed-off-by: Florian Fainelli <f.fainelli@gmail.com>

Applied.