From patchwork Mon Dec 17 09:14:22 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Lam, Tiago" X-Patchwork-Id: 49000 X-Patchwork-Delegate: ferruh.yigit@amd.com Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 618581B714; Mon, 17 Dec 2018 10:14:28 +0100 (CET) Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by dpdk.org (Postfix) with ESMTP id 6D6521B70B for ; Mon, 17 Dec 2018 10:14:27 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by fmsmga104.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 17 Dec 2018 01:14:26 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.56,364,1539673200"; d="scan'208";a="304422021" Received: from silpixa00399125.ir.intel.com ([10.237.223.34]) by fmsmga005.fm.intel.com with ESMTP; 17 Dec 2018 01:14:25 -0800 From: Tiago Lam To: dev@dpdk.org Cc: ferruh.yigit@intel.com, linville@tuxdriver.com, Tiago Lam Date: Mon, 17 Dec 2018 09:14:22 +0000 Message-Id: <1545038062-35465-1-git-send-email-tiago.lam@intel.com> X-Mailer: git-send-email 2.7.4 Subject: [dpdk-dev] [PATCH] net/af_packet: add docs guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" As of commit 364e08f2bbc0, DPDK allows an aplication to send and receive raw packets using an AF_PACKET and PACKET_MMAP, when using a Linux Kernel. This complements it by adding a simple guide with the following information: - An introduction, where a brief explanation of this driver is given, pointing out the dependency on PACKET_MMAP; - Which options are supported at configuration time, while setting up an interface, and it's inherent limitations; - What the prerequisites are; - A command line example of how to set up a DPDK port using the af_packet driver. Since there's a dependency in PACKET_MMAP, the guide also points to the original Kernel documentation, so the reader can get more details. Signed-off-by: Tiago Lam Reviewed-by: Ferruh Yigit --- doc/guides/nics/af_packet.rst | 67 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 doc/guides/nics/af_packet.rst diff --git a/doc/guides/nics/af_packet.rst b/doc/guides/nics/af_packet.rst new file mode 100644 index 0000000..e6f77ad --- /dev/null +++ b/doc/guides/nics/af_packet.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Intel Corporation. + +AF_PACKET Poll Mode Driver +========================== + +The AF_PACKET socket in Linux allows an application to receive and send raw +packets. This Linux-specific PMD driver binds to an AF_PACKET socket and allows +a DPDK application to send and receive raw packets through the Kernel. + +In order to improve Rx and Tx performance this implementation makes use of +PACKET_MMAP, which provides a mmap'ed ring buffer, shared between user space +and kernel, that's used to send and receive packets. This helps reducing system +calls and the copies needed between user space and Kernel. + +The PACKET_FANOUT_HASH behaviour of AF_PACKET is used for frame reception. + +Options and inherent limitations +-------------------------------- + +The following options can be provided to set up an af_packet port in DPDK. +Some of these, in turn, will be used to configure the PAKET_MMAP settings. + +* "iface" - name of the Kernel interface to attach to (required); +* "qpairs" - number of Rx and Tx queues (optional, default 1); +* "qdisc_bypass" - set PACKET_QDISC_BYPASS option in AF_PACKET (optional, + disabled by default); +* "blocksz" - PACKET_MMAP block size (optional, default 4096); +* "framesz" - PACKET_MMAP frame size (optional, default 2048B; Note: multiple + of 16B); +* "framecnt" - PACKET_MMAP frame count (optional, default 512B). + +Because this implementation is based on PACKET_MMAP, and PACKET_MMAP has its +own pre-requisites, it should be noted that the inner workings of PACKET_MMAP +should be carefully considered before modifying some of these options (namely, +"blocksz, "framesz" and "framecnt" above). + +As an example, if one changes "framesz" to be 1024B, it is expected that +"blocksz" is set to at least 1024B as well (although 2048B in this case would +allow two "frames" per "block"). + +This restriction happens because PACKET_MMAP expects each single "frame" to fit +inside of a "block". And although multiple "frames" can fit inside of a single +"block", a "frame" may not span across two "blocks". + +For the full details behind PACKET_MMAP's structures and settings, consider +reading the `PACKET_MMAP documentation in the Kernel +`_. + +Prerequisites +------------- + +This is a Linux-specific PMD, thus the following prerequisites apply: + +* A Linux Kernel; +* A Kernel bound interface to attach to (e.g. a tap interface). + +Set up an af_packet interface +----------------------------- + +The following example will set up an af_packet interface in DPDK with the +default options described above (blocksz=4096B, framesz=2048B and +framecnt=512B): + +.. code-block:: console + + --vdev=eth_af_packet0,iface=tap0,blocksz=4096,framesz=2048,framecnt=512,qpairs=1,qdisc_bypass=0