net/af_packet: add docs guide
Checks
Commit Message
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 <tiago.lam@intel.com>
---
doc/guides/nics/af_packet.rst | 67 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 67 insertions(+)
create mode 100644 doc/guides/nics/af_packet.rst
Comments
On 12/17/2018 9:14 AM, Tiago Lam wrote:
> 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 <tiago.lam@intel.com>
Thanks Tiago, appreciated.
> ---
> doc/guides/nics/af_packet.rst | 67 +++++++++++++++++++++++++++++++++++++++++++
index file (doc/guides/nics/index.rst) also needs to be updated to include new
doc, I can update this while merging.
<...>
> +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).
using `` instead of " highlights the text, I can update this while merging.
Reviewed-by: Ferruh Yigit <ferruh.yigit@intel.com>
On 12/18/2018 12:31 AM, Ferruh Yigit wrote:
> On 12/17/2018 9:14 AM, Tiago Lam wrote:
>> 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 <tiago.lam@intel.com>
<...>
>
> Reviewed-by: Ferruh Yigit <ferruh.yigit@intel.com>
Applied to dpdk-next-net/master, thanks.
(mentioned changes applied while merging, please confirm)
On 18/12/2018 00:39, Ferruh Yigit wrote:
> On 12/18/2018 12:31 AM, Ferruh Yigit wrote:
>> On 12/17/2018 9:14 AM, Tiago Lam wrote:
>>> 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 <tiago.lam@intel.com>
> <...>
>>
>> Reviewed-by: Ferruh Yigit <ferruh.yigit@intel.com>
>
> Applied to dpdk-next-net/master, thanks.
>
> (mentioned changes applied while merging, please confirm)
>
Thanks, Ferruh, for applying with the fixes.
I've re-build the docs and looks from here.
Tiago.
new file mode 100644
@@ -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
+<https://www.kernel.org/doc/Documentation/networking/packet_mmap.txt>`_.
+
+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