Skip to contentSkip to conversation

net: add documentation for BQL helpers

PATCH Superseded Florian Fainelli 3 participants 7 messages Sep 6, 2013

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

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
index 8ed4ae9..ac36629 100644
@@ -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
#1 lore raw
Quoted 21 lines · 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.

---
 include/linux/netdevice.h | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
include/linux/netdevice.h +0 -0
index 8ed4ae9..ac36629 100644
@@ -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...)
+ */
#2 lore raw

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_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 +0 -0
index 8ed4ae9..ac36629 100644
@@ -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() @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?

Signature · 1 line
Florian
#3 lore raw
In reply to Florian Fainelli
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)

#4 lore raw

PATCH v2 1/1 net: add documentation for BQL helpers

In reply to 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.

---
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
index 8ed4ae9..041b42a 100644
@@ -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
Acked-by on v2 1/1
#5 lore raw
Quoted 9 lines · 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.

Quoted 5 lines

---
Change since v1:
- incorporate suggestsions from Eric Dumazet and just specify the exact match for netdev_sent_queue/netdev_completed_queue

Thanks

maintainer Applied
#6 lore raw
In reply to Florian Fainelli

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_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.

Applied.