0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===========================================
0004 HOWTO for multiqueue network device support
0005 ===========================================
0006
0007 Section 1: Base driver requirements for implementing multiqueue support
0008 =======================================================================
0009
0010 Intro: Kernel support for multiqueue devices
0011 ---------------------------------------------------------
0012
0013 Kernel support for multiqueue devices is always present.
0014
0015 Base drivers are required to use the new alloc_etherdev_mq() or
0016 alloc_netdev_mq() functions to allocate the subqueues for the device. The
0017 underlying kernel API will take care of the allocation and deallocation of
0018 the subqueue memory, as well as netdev configuration of where the queues
0019 exist in memory.
0020
0021 The base driver will also need to manage the queues as it does the global
0022 netdev->queue_lock today. Therefore base drivers should use the
0023 netif_{start|stop|wake}_subqueue() functions to manage each queue while the
0024 device is still operational. netdev->queue_lock is still used when the device
0025 comes online or when it's completely shut down (unregister_netdev(), etc.).
0026
0027
0028 Section 2: Qdisc support for multiqueue devices
0029 ===============================================
0030
0031 Currently two qdiscs are optimized for multiqueue devices. The first is the
0032 default pfifo_fast qdisc. This qdisc supports one qdisc per hardware queue.
0033 A new round-robin qdisc, sch_multiq also supports multiple hardware queues. The
0034 qdisc is responsible for classifying the skb's and then directing the skb's to
0035 bands and queues based on the value in skb->queue_mapping. Use this field in
0036 the base driver to determine which queue to send the skb to.
0037
0038 sch_multiq has been added for hardware that wishes to avoid head-of-line
0039 blocking. It will cycle though the bands and verify that the hardware queue
0040 associated with the band is not stopped prior to dequeuing a packet.
0041
0042 On qdisc load, the number of bands is based on the number of queues on the
0043 hardware. Once the association is made, any skb with skb->queue_mapping set,
0044 will be queued to the band associated with the hardware queue.
0045
0046
0047 Section 3: Brief howto using MULTIQ for multiqueue devices
0048 ==========================================================
0049
0050 The userspace command 'tc,' part of the iproute2 package, is used to configure
0051 qdiscs. To add the MULTIQ qdisc to your network device, assuming the device
0052 is called eth0, run the following command::
0053
0054 # tc qdisc add dev eth0 root handle 1: multiq
0055
0056 The qdisc will allocate the number of bands to equal the number of queues that
0057 the device reports, and bring the qdisc online. Assuming eth0 has 4 Tx
0058 queues, the band mapping would look like::
0059
0060 band 0 => queue 0
0061 band 1 => queue 1
0062 band 2 => queue 2
0063 band 3 => queue 3
0064
0065 Traffic will begin flowing through each queue based on either the simple_tx_hash
0066 function or based on netdev->select_queue() if you have it defined.
0067
0068 The behavior of tc filters remains the same. However a new tc action,
0069 skbedit, has been added. Assuming you wanted to route all traffic to a
0070 specific host, for example 192.168.0.3, through a specific queue you could use
0071 this action and establish a filter such as::
0072
0073 tc filter add dev eth0 parent 1: protocol ip prio 1 u32 \
0074 match ip dst 192.168.0.3 \
0075 action skbedit queue_mapping 3
0076
0077 :Author: Alexander Duyck <alexander.h.duyck@intel.com>
0078 :Original Author: Peter P. Waskiewicz Jr. <peter.p.waskiewicz.jr@intel.com>
