[net-next PATCH v1 3/3] net: packet: Document PACKET_DEV_QPAIR_SPLIT and friends

[John Fastabend <john.fastabend@gmail.com>]

This adds a section to the packet interface kernel documentation
describing the set of socket options to get direct queue
assignment working.

Signed-off-by: John Fastabend <john.r.fastabend@intel.com>
---
 Documentation/networking/packet_mmap.txt |   44 ++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/Documentation/networking/packet_mmap.txt b/Documentation/networking/packet_mmap.txt
index a6d7cb9..ad26194 100644
--- a/Documentation/networking/packet_mmap.txt
+++ b/Documentation/networking/packet_mmap.txt
@@ -1047,6 +1047,50 @@ See include/linux/net_tstamp.h and Documentation/networking/timestamping
 for more information on hardware timestamps.
 
 -------------------------------------------------------------------------------
++ PACKET_RXTX_QPAIRS_SPLIT and friends
+-------------------------------------------------------------------------------
+
+The PACKET_RXTX_QPAIRS_SLIT setting allows direct access to the hardware
+packet rings. If your NIC is capable of supporting hardware packet steering
+and the driver has this feature enabled you can use the hardware to steer
+packets directly to user mapped memory and use user space descriptor rings.
+
+The user space flow should be,
+
+	bind(fd, &sockaddr, sizeof(sockaddr));
+
+	/* Get the device type and info */
+	getsockopt(fd, SOL_PACKET, PACKET_DEV_DESC_INFO, &def_info,
+		   &optlen);
+
+	/* With device info we can look up descriptor format */
+
+	/* Get the layout of ring space offset, page_sz, cnt */
+	getsockopt(fd, SOL_PACKET, PACKET_DEV_QPAIR_MAP_REGION_INFO,
+                   &info, &optlen);
+
+        /* request some queues from the driver */
+	setsockopt(fd, SOL_PACKET, PACKET_RXTX_QPAIRS_SPLIT,
+		   &qpairs_info, sizeof(qpairs_info));
+
+	/* if we let the driver pick us queues learn which queues
+	 * we were given
+	 */
+	getsockopt(fd, SOL_PACKET, PACKET_RXTX_QPAIRS_SPLIT,
+		   &qpairs_info, sizeof(qpairs_info));
+
+	/* And mmap queue pairs to user space */
+	mmap(NULL, info.tp_dev_bar_sz, PROT_READ | PROT_WRITE,
+	     MAP_SHARED, fd, 0);
+
+	/* Now we have some user space queues to read/write to*/
+
+After this user space can directly manipulate the drivers descriptor rings.
+The descriptor rings use the native descriptor format of the hardware device.
+The device specifics are returned from the PACKET_DEV_DESC_INFO call which
+allows user space to determine the correct descriptor format to use.
+
+-------------------------------------------------------------------------------
 + Miscellaneous bits
 -------------------------------------------------------------------------------