include/net/netdev_queues.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _LINUX_NET_QUEUES_H
   3 #define _LINUX_NET_QUEUES_H
   4
   5 #include <linux/netdevice.h>
   6
   7 /* See the netdev.yaml spec for definition of each statistic */
   8 struct netdev_queue_stats_rx {
   9         u64 bytes;
  10         u64 packets;
  11         u64 alloc_fail;
  12
  13         u64 hw_drops;
  14         u64 hw_drop_overruns;
  15
  16         u64 csum_unnecessary;
  17         u64 csum_none;
  18         u64 csum_bad;
  19
  20         u64 hw_gro_packets;
  21         u64 hw_gro_bytes;
  22         u64 hw_gro_wire_packets;
  23         u64 hw_gro_wire_bytes;
  24
  25         u64 hw_drop_ratelimits;
  26 };
  27
  28 struct netdev_queue_stats_tx {
  29         u64 bytes;
  30         u64 packets;
  31
  32         u64 hw_drops;
  33         u64 hw_drop_errors;
  34
  35         u64 csum_none;
  36         u64 needs_csum;
  37
  38         u64 hw_gso_packets;
  39         u64 hw_gso_bytes;
  40         u64 hw_gso_wire_packets;
  41         u64 hw_gso_wire_bytes;
  42
  43         u64 hw_drop_ratelimits;
  44
  45         u64 stop;
  46         u64 wake;
  47 };
  48
  49 /**
  50  * struct netdev_stat_ops - netdev ops for fine grained stats
  51  * @get_queue_stats_rx: get stats for a given Rx queue
  52  * @get_queue_stats_tx: get stats for a given Tx queue
  53  * @get_base_stats:     get base stats (not belonging to any live instance)
  54  *
  55  * Query stats for a given object. The values of the statistics are undefined
  56  * on entry (specifically they are *not* zero-initialized). Drivers should
  57  * assign values only to the statistics they collect. Statistics which are not
  58  * collected must be left undefined.
  59  *
  60  * Queue objects are not necessarily persistent, and only currently active
  61  * queues are queried by the per-queue callbacks. This means that per-queue
  62  * statistics will not generally add up to the total number of events for
  63  * the device. The @get_base_stats callback allows filling in the delta
  64  * between events for currently live queues and overall device history.
  65  * When the statistics for the entire device are queried, first @get_base_stats
  66  * is issued to collect the delta, and then a series of per-queue callbacks.
  67  * Only statistics which are set in @get_base_stats will be reported
  68  * at the device level, meaning that unlike in queue callbacks, setting
  69  * a statistic to zero in @get_base_stats is a legitimate thing to do.
  70  * This is because @get_base_stats has a second function of designating which
  71  * statistics are in fact correct for the entire device (e.g. when history
  72  * for some of the events is not maintained, and reliable "total" cannot
  73  * be provided).
  74  *
  75  * Device drivers can assume that when collecting total device stats,
  76  * the @get_base_stats and subsequent per-queue calls are performed
  77  * "atomically" (without releasing the rtnl_lock).
  78  *
  79  * Device drivers are encouraged to reset the per-queue statistics when
  80  * number of queues change. This is because the primary use case for
  81  * per-queue statistics is currently to detect traffic imbalance.
  82  */
  83 struct netdev_stat_ops {
  84         void (*get_queue_stats_rx)(struct net_device *dev, int idx,
  85                                    struct netdev_queue_stats_rx *stats);
  86         void (*get_queue_stats_tx)(struct net_device *dev, int idx,
  87                                    struct netdev_queue_stats_tx *stats);
  88         void (*get_base_stats)(struct net_device *dev,
  89                                struct netdev_queue_stats_rx *rx,
  90                                struct netdev_queue_stats_tx *tx);
  91 };
  92
  93 /**
  94  * struct netdev_queue_mgmt_ops - netdev ops for queue management
  95  *
  96  * @ndo_queue_mem_size: Size of the struct that describes a queue's memory.
  97  *
  98  * @ndo_queue_mem_alloc: Allocate memory for an RX queue at the specified index.
  99  *                       The new memory is written at the specified address.
 100  *
 101  * @ndo_queue_mem_free: Free memory from an RX queue.
 102  *
 103  * @ndo_queue_start:    Start an RX queue with the specified memory and at the
 104  *                      specified index.
 105  *
 106  * @ndo_queue_stop:     Stop the RX queue at the specified index. The stopped
 107  *                      queue's memory is written at the specified address.
 108  */
 109 struct netdev_queue_mgmt_ops {
 110         size_t                  ndo_queue_mem_size;
 111         int                     (*ndo_queue_mem_alloc)(struct net_device *dev,
 112                                                        void *per_queue_mem,
 113                                                        int idx);
 114         void                    (*ndo_queue_mem_free)(struct net_device *dev,
 115                                                       void *per_queue_mem);
 116         int                     (*ndo_queue_start)(struct net_device *dev,
 117                                                    void *per_queue_mem,
 118                                                    int idx);
 119         int                     (*ndo_queue_stop)(struct net_device *dev,
 120                                                   void *per_queue_mem,
 121                                                   int idx);
 122 };
 123
 124 /**
 125  * DOC: Lockless queue stopping / waking helpers.
 126  *
 127  * The netif_txq_maybe_stop() and __netif_txq_completed_wake()
 128  * macros are designed to safely implement stopping
 129  * and waking netdev queues without full lock protection.
 130  *
 131  * We assume that there can be no concurrent stop attempts and no concurrent
 132  * wake attempts. The try-stop should happen from the xmit handler,
 133  * while wake up should be triggered from NAPI poll context.
 134  * The two may run concurrently (single producer, single consumer).
 135  *
 136  * The try-stop side is expected to run from the xmit handler and therefore
 137  * it does not reschedule Tx (netif_tx_start_queue() instead of
 138  * netif_tx_wake_queue()). Uses of the ``stop`` macros outside of the xmit
 139  * handler may lead to xmit queue being enabled but not run.
 140  * The waking side does not have similar context restrictions.
 141  *
 142  * The macros guarantee that rings will not remain stopped if there's
 143  * space available, but they do *not* prevent false wake ups when
 144  * the ring is full! Drivers should check for ring full at the start
 145  * for the xmit handler.
 146  *
 147  * All descriptor ring indexes (and other relevant shared state) must
 148  * be updated before invoking the macros.
 149  */
 150
 151 #define netif_txq_try_stop(txq, get_desc, start_thrs)                   \
 152         ({                                                              \
 153                 int _res;                                               \
 154                                                                         \
 155                 netif_tx_stop_queue(txq);                               \
 156                 /* Producer index and stop bit must be visible          \
 157                  * to consumer before we recheck.                       \
 158                  * Pairs with a barrier in __netif_txq_completed_wake(). \
 159                  */                                                     \
 160                 smp_mb__after_atomic();                                 \
 161                                                                         \
 162                 /* We need to check again in a case another             \
 163                  * CPU has just made room available.                    \
 164                  */                                                     \
 165                 _res = 0;                                               \
 166                 if (unlikely(get_desc >= start_thrs)) {                 \
 167                         netif_tx_start_queue(txq);                      \
 168                         _res = -1;                                      \
 169                 }                                                       \
 170                 _res;                                                   \
 171         })                                                              \
 172
 173 /**
 174  * netif_txq_maybe_stop() - locklessly stop a Tx queue, if needed
 175  * @txq:        struct netdev_queue to stop/start
 176  * @get_desc:   get current number of free descriptors (see requirements below!)
 177  * @stop_thrs:  minimal number of available descriptors for queue to be left
 178  *              enabled
 179  * @start_thrs: minimal number of descriptors to re-enable the queue, can be
 180  *              equal to @stop_thrs or higher to avoid frequent waking
 181  *
 182  * All arguments may be evaluated multiple times, beware of side effects.
 183  * @get_desc must be a formula or a function call, it must always
 184  * return up-to-date information when evaluated!
 185  * Expected to be used from ndo_start_xmit, see the comment on top of the file.
 186  *
 187  * Returns:
 188  *       0 if the queue was stopped
 189  *       1 if the queue was left enabled
 190  *      -1 if the queue was re-enabled (raced with waking)
 191  */
 192 #define netif_txq_maybe_stop(txq, get_desc, stop_thrs, start_thrs)      \
 193         ({                                                              \
 194                 int _res;                                               \
 195                                                                         \
 196                 _res = 1;                                               \
 197                 if (unlikely(get_desc < stop_thrs))                     \
 198                         _res = netif_txq_try_stop(txq, get_desc, start_thrs); \
 199                 _res;                                                   \
 200         })                                                              \
 201
 202 /* Variant of netdev_tx_completed_queue() which guarantees smp_mb() if
 203  * @bytes != 0, regardless of kernel config.
 204  */
 205 static inline void
 206 netdev_txq_completed_mb(struct netdev_queue *dev_queue,
 207                         unsigned int pkts, unsigned int bytes)
 208 {
 209         if (IS_ENABLED(CONFIG_BQL))
 210                 netdev_tx_completed_queue(dev_queue, pkts, bytes);
 211         else if (bytes)
 212                 smp_mb();
 213 }
 214
 215 /**
 216  * __netif_txq_completed_wake() - locklessly wake a Tx queue, if needed
 217  * @txq:        struct netdev_queue to stop/start
 218  * @pkts:       number of packets completed
 219  * @bytes:      number of bytes completed
 220  * @get_desc:   get current number of free descriptors (see requirements below!)
 221  * @start_thrs: minimal number of descriptors to re-enable the queue
 222  * @down_cond:  down condition, predicate indicating that the queue should
 223  *              not be woken up even if descriptors are available
 224  *
 225  * All arguments may be evaluated multiple times.
 226  * @get_desc must be a formula or a function call, it must always
 227  * return up-to-date information when evaluated!
 228  * Reports completed pkts/bytes to BQL.
 229  *
 230  * Returns:
 231  *       0 if the queue was woken up
 232  *       1 if the queue was already enabled (or disabled but @down_cond is true)
 233  *      -1 if the queue was left unchanged (@start_thrs not reached)
 234  */
 235 #define __netif_txq_completed_wake(txq, pkts, bytes,                    \
 236                                    get_desc, start_thrs, down_cond)     \
 237         ({                                                              \
 238                 int _res;                                               \
 239                                                                         \
 240                 /* Report to BQL and piggy back on its barrier.         \
 241                  * Barrier makes sure that anybody stopping the queue   \
 242                  * after this point sees the new consumer index.        \
 243                  * Pairs with barrier in netif_txq_try_stop().          \
 244                  */                                                     \
 245                 netdev_txq_completed_mb(txq, pkts, bytes);              \
 246                                                                         \
 247                 _res = -1;                                              \
 248                 if (pkts && likely(get_desc >= start_thrs)) {           \
 249                         _res = 1;                                       \
 250                         if (unlikely(netif_tx_queue_stopped(txq)) &&    \
 251                             !(down_cond)) {                             \
 252                                 netif_tx_wake_queue(txq);               \
 253                                 _res = 0;                               \
 254                         }                                               \
 255                 }                                                       \
 256                 _res;                                                   \
 257         })
 258
 259 #define netif_txq_completed_wake(txq, pkts, bytes, get_desc, start_thrs) \
 260         __netif_txq_completed_wake(txq, pkts, bytes, get_desc, start_thrs, false)
 261
 262 /* subqueue variants follow */
 263
 264 #define netif_subqueue_try_stop(dev, idx, get_desc, start_thrs)         \
 265         ({                                                              \
 266                 struct netdev_queue *txq;                               \
 267                                                                         \
 268                 txq = netdev_get_tx_queue(dev, idx);                    \
 269                 netif_txq_try_stop(txq, get_desc, start_thrs);          \
 270         })
 271
 272 #define netif_subqueue_maybe_stop(dev, idx, get_desc, stop_thrs, start_thrs) \
 273         ({                                                              \
 274                 struct netdev_queue *txq;                               \
 275                                                                         \
 276                 txq = netdev_get_tx_queue(dev, idx);                    \
 277                 netif_txq_maybe_stop(txq, get_desc, stop_thrs, start_thrs); \
 278         })
 279
 280 #define netif_subqueue_completed_wake(dev, idx, pkts, bytes,            \
 281                                       get_desc, start_thrs)             \
 282         ({                                                              \
 283                 struct netdev_queue *txq;                               \
 284                                                                         \
 285                 txq = netdev_get_tx_queue(dev, idx);                    \
 286                 netif_txq_completed_wake(txq, pkts, bytes,              \
 287                                          get_desc, start_thrs);         \
 288         })
 289
 290 #endif