asus-laptop: set the right paths in the documentation
[linux-2.6.git] / Documentation / networking / multiqueue.txt
index 00b60cc..4caa0e3 100644 (file)
@@ -3,19 +3,11 @@
                ===========================================
 
 Section 1: Base driver requirements for implementing multiqueue support
-Section 2: Qdisc support for multiqueue devices
-Section 3: Brief howto using PRIO or RR for multiqueue devices
-
 
 Intro: Kernel support for multiqueue devices
 ---------------------------------------------------------
 
-Kernel support for multiqueue devices is only an API that is presented to the
-netdevice layer for base drivers to implement.  This feature is part of the
-core networking stack, and all network devices will be running on the
-multiqueue-aware stack.  If a base driver only has one queue, then these
-changes are transparent to that driver.
-
+Kernel support for multiqueue devices is always present.
 
 Section 1: Base driver requirements for implementing multiqueue support
 -----------------------------------------------------------------------
@@ -32,80 +24,56 @@ netif_{start|stop|wake}_subqueue() functions to manage each queue while the
 device is still operational.  netdev->queue_lock is still used when the device
 comes online or when it's completely shut down (unregister_netdev(), etc.).
 
-Finally, the base driver should indicate that it is a multiqueue device.  The
-feature flag NETIF_F_MULTI_QUEUE should be added to the netdev->features
-bitmap on device initialization.  Below is an example from e1000:
-
-#ifdef CONFIG_E1000_MQ
-       if ( (adapter->hw.mac.type == e1000_82571) ||
-            (adapter->hw.mac.type == e1000_82572) ||
-            (adapter->hw.mac.type == e1000_80003es2lan))
-               netdev->features |= NETIF_F_MULTI_QUEUE;
-#endif
-
 
 Section 2: Qdisc support for multiqueue devices
+
 -----------------------------------------------
 
-Currently two qdiscs support multiqueue devices.  A new round-robin qdisc,
-sch_rr, and sch_prio. The qdisc is responsible for classifying the skb's to
-bands and queues, and will store the queue mapping into skb->queue_mapping.
-Use this field in the base driver to determine which queue to send the skb
-to.
+Currently two qdiscs are optimized for multiqueue devices.  The first is the
+default pfifo_fast qdisc.  This qdisc supports one qdisc per hardware queue.
+A new round-robin qdisc, sch_multiq also supports multiple hardware queues. The
+qdisc is responsible for classifying the skb's and then directing the skb's to
+bands and queues based on the value in skb->queue_mapping.  Use this field in
+the base driver to determine which queue to send the skb to.
 
-sch_rr has been added for hardware that doesn't want scheduling policies from
-software, so it's a straight round-robin qdisc.  It uses the same syntax and
-classification priomap that sch_prio uses, so it should be intuitive to
-configure for people who've used sch_prio.
+sch_multiq has been added for hardware that wishes to avoid head-of-line
+blocking.  It will cycle though the bands and verify that the hardware queue
+associated with the band is not stopped prior to dequeuing a packet.
 
-The PRIO qdisc naturally plugs into a multiqueue device.  If PRIO has been
-built with NET_SCH_PRIO_MQ, then upon load, it will make sure the number of
-bands requested is equal to the number of queues on the hardware.  If they
-are equal, it sets a one-to-one mapping up between the queues and bands.  If
-they're not equal, it will not load the qdisc.  This is the same behavior
-for RR.  Once the association is made, any skb that is classified will have
-skb->queue_mapping set, which will allow the driver to properly queue skb's
-to multiple queues.
+On qdisc load, the number of bands is based on the number of queues on the
+hardware.  Once the association is made, any skb with skb->queue_mapping set,
+will be queued to the band associated with the hardware queue.
 
 
-Section 3: Brief howto using PRIO and RR for multiqueue devices
+Section 3: Brief howto using MULTIQ for multiqueue devices
 ---------------------------------------------------------------
 
 The userspace command 'tc,' part of the iproute2 package, is used to configure
-qdiscs.  To add the PRIO qdisc to your network device, assuming the device is
-called eth0, run the following command:
+qdiscs.  To add the MULTIQ qdisc to your network device, assuming the device
+is called eth0, run the following command:
 
-# tc qdisc add dev eth0 root handle 1: prio bands 4 multiqueue
+# tc qdisc add dev eth0 root handle 1: multiq
 
-This will create 4 bands, 0 being highest priority, and associate those bands
-to the queues on your NIC.  Assuming eth0 has 4 Tx queues, the band mapping
-would look like:
+The qdisc will allocate the number of bands to equal the number of queues that
+the device reports, and bring the qdisc online.  Assuming eth0 has 4 Tx
+queues, the band mapping would look like:
 
 band 0 => queue 0
 band 1 => queue 1
 band 2 => queue 2
 band 3 => queue 3
 
-Traffic will begin flowing through each queue if your TOS values are assigning
-traffic across the various bands.  For example, ssh traffic will always try to
-go out band 0 based on TOS -> Linux priority conversion (realtime traffic),
-so it will be sent out queue 0.  ICMP traffic (pings) fall into the "normal"
-traffic classification, which is band 1.  Therefore pings will be send out
-queue 1 on the NIC.
-
-Note the use of the multiqueue keyword.  This is only in versions of iproute2
-that support multiqueue networking devices; if this is omitted when loading
-a qdisc onto a multiqueue device, the qdisc will load and operate the same
-if it were loaded onto a single-queue device (i.e. - sends all traffic to
-queue 0).
-
-Another alternative to multiqueue band allocation can be done by using the
-multiqueue option and specify 0 bands.  If this is the case, the qdisc will
-allocate the number of bands to equal the number of queues that the device
-reports, and bring the qdisc online.
+Traffic will begin flowing through each queue based on either the simple_tx_hash
+function or based on netdev->select_queue() if you have it defined.
 
-The behavior of tc filters remains the same, where it will override TOS priority
-classification.
+The behavior of tc filters remains the same.  However a new tc action,
+skbedit, has been added.  Assuming you wanted to route all traffic to a
+specific host, for example 192.168.0.3, through a specific queue you could use
+this action and establish a filter such as:
 
+tc filter add dev eth0 parent 1: protocol ip prio 1 u32 \
+       match ip dst 192.168.0.3 \
+       action skbedit queue_mapping 3
 
-Author: Peter P. Waskiewicz Jr. <peter.p.waskiewicz.jr@intel.com>
+Author: Alexander Duyck <alexander.h.duyck@intel.com>
+Original Author: Peter P. Waskiewicz Jr. <peter.p.waskiewicz.jr@intel.com>