net: add documentation for BQL helpers
Subsystems (2)
PATCH 1/1 net: add documentation for BQL helpers
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.
--- include/linux/netdevice.h | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)
include/linux/netdevice.h +27 -0
@@ -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 ));
Signature · 1 line
1.8.1.2
Quoted 21 lines · Florian Fainelli
Provide a kernel-doc comment documentation for the BQL helpers:
-netdev_sent_queue
-netdev_completed_queue
-netdev_reset_queueSimilarly to how it is done for the other functions, the documentation only covers the function operating on struct
net_deviceand not structnetdev_queue.Signed-off-by Florian Fainelli <[email protected]>--- include/linux/netdevice.h | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)include/linux/netdevice.h +0
-0@@ -2101,6 +2101,16 @@ static inline void netdev_tx_sent_queue(struct netdev_queue *dev_queue,#endif }
include/linux/netdevice.h static inline void netdev_tx_sent_queue(struct netdev_queue *dev_queue, · line 2112
Quoted 10 lines
include/linux/netdevice.h +9
-0+/** +* 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 )
Quoted 18 lines
include/linux/netdevice.h +11
-0+*/ 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...) +*/
2013/9/6 Eric Dumazet <[email protected]>:
Quoted 35 lines · Florian Fainelli
Quoted 21 lines
Provide a kernel-doc comment documentation for the BQL helpers:
-netdev_sent_queue
-netdev_completed_queue
-netdev_reset_queueSimilarly to how it is done for the other functions, the documentation only covers the function operating on struct
net_deviceand not structnetdev_queue.Signed-off-by Florian Fainelli <[email protected]>--- include/linux/netdevice.h | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)include/linux/netdevice.h +0
-0@@ -2101,6 +2101,16 @@ static inline void netdev_tx_sent_queue(struct netdev_queue *dev_queue,#endif }include/linux/netdevice.h static inline void netdev_tx_sent_queue(struct netdev_queue *dev_queue, · line 2112
Quoted 10 lines
include/linux/netdevice.h +9
-0+/** +* 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.
Quoted 7 lines
@bytes should be a good approximation, and should match
netdev_completed_queue()@bytesIf you think of TSO, we know that
skb->lendoes not exactly matches number of bytes on physical medium ( checkqdisc_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?
Signature · 1 line
Florian
Quoted 10 lines · Florian Fainelli
+/**
+ *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 v2 1/1 net: add documentation for BQL helpers
In reply to Florian FainelliProvide 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.
---
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(+)
include/linux/netdevice.h +26 -0
@@ -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 ));
Signature · 1 line
1.8.1.2
Quoted 9 lines · Florian Fainelli
Provide a kernel-doc comment documentation for the BQL helpers:
-netdev_sent_queue
-netdev_completed_queue
-netdev_reset_queueSimilarly to how it is done for the other functions, the documentation only covers the function operating on struct
net_deviceand not structnetdev_queue.
Quoted 5 lines
Signed-off-by Florian Fainelli <[email protected]>---
Change since v1:
- incorporate suggestsions from Eric Dumazet and just specify the exact match for netdev_sent_queue/netdev_completed_queue
Thanks
From: "Florian Fainelli" <[email protected]>
Date: Fri, 6 Sep 2013 16:58:00 +0100
Quoted 10 lines
Provide a kernel-doc comment documentation for the BQL helpers:
-netdev_sent_queue
-netdev_completed_queue
-netdev_reset_queueSimilarly to how it is done for the other functions, the documentation only covers the function operating on struct
net_deviceand not structnetdev_queue.Signed-off-by Florian Fainelli <[email protected]>
Applied.