From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 66CBD43DC3; Tue, 2 Apr 2024 19:18:10 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 2C4814064C; Tue, 2 Apr 2024 19:17:58 +0200 (CEST) Received: from mail-pl1-f180.google.com (mail-pl1-f180.google.com [209.85.214.180]) by mails.dpdk.org (Postfix) with ESMTP id 5F437402D8 for ; Tue, 2 Apr 2024 19:17:55 +0200 (CEST) Received: by mail-pl1-f180.google.com with SMTP id d9443c01a7336-1e244c7cbf8so22859885ad.0 for ; Tue, 02 Apr 2024 10:17:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20230601.gappssmtp.com; s=20230601; t=1712078274; x=1712683074; darn=dpdk.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=zxIUf5LqWFYk0J3FN48Qroz1rnjdL/+cKWhdS8rBBwc=; b=HqGxdJjX1uS1Va7nMdT9tWeUoZDXz2SaRWyEy8kaPrN+3RDzIjDsz56mUm22rA2zcf P3ZsNgMmk0pYQjGladSWZlyLMW4mm12rgo1otLwa55Btw9UkL6OGUXripjVlMvk3p1ap xGuyCk0V5NRK/welkzivlJtMaAZnhtizgfX/hDjpwAyYyjXJvLG+WlG+gPf8BjIxKjII 4/PiPUWdYENnnIPOKm8eW4DGcsRE4jpuu2DdqCmai3QkqHA086NGzJuUg855ck9ZBN2Y Y91cnky3VofJ+drEC9DW+qQGxkQnwxrCJ1ytleUPm56Urqeo3Vkh5qMPq/YiZc4IWJqc TaQg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1712078274; x=1712683074; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=zxIUf5LqWFYk0J3FN48Qroz1rnjdL/+cKWhdS8rBBwc=; b=Vy3O78q0eejZc8AETkBsdh0BFByXSqNgSLbLApsnC+tWFiF3xi0zhjqdz4Idpo+9Gd 9i56KaXhSQJJRrxpHdQCDMjet9FRZ0QmZa0+WXeCuc3CSj/4WWaKZshItE/At1GPaT1D 6ZQDyjnbIQ9MhVLcE/q9aOVrO71O0LoTtjTgw57tiVA7PbjeKnzCKupk3xtWgcNBR901 Eu39wXF3plfTBs+XPHPFYc5Zp0RzHrB9zYeQYjsJ0LH0/pF8EOCBtfg8fqrkUwm7Zcby rGyvUnAcEKJX7WS1Zq7wpfoOS9HZhXf4jZwzxT1Rjn8eG8ui1kzRjcjal0zVpnhmOvI+ R6Dg== X-Gm-Message-State: AOJu0YwLbMMCwhfYYPNiHmujjKR6S9AkaAAlzdQ+VZ6Oy4/23a7itZbZ 30cdKpS1giZuoiBURRG/aEV7xkRydqKiimAKwYqkZJybfDQv86ZqrpiDnYNO+49yvFzQhe4V9ah V X-Google-Smtp-Source: AGHT+IEZlEdPdcc/rSAQv0cBc2FAZ74Fa2EwHAGx5Hq821kL6XosTPkYQ15JGW5C8JkUzxAOlVW6fA== X-Received: by 2002:a17:902:654d:b0:1dd:e15e:4a5a with SMTP id d13-20020a170902654d00b001dde15e4a5amr385595pln.59.1712078274462; Tue, 02 Apr 2024 10:17:54 -0700 (PDT) Received: from hermes.lan (204-195-96-226.wavecable.com. [204.195.96.226]) by smtp.gmail.com with ESMTPSA id q15-20020a170902a3cf00b001e264b50964sm2219815plb.205.2024.04.02.10.17.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Apr 2024 10:17:54 -0700 (PDT) From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger Subject: [PATCH v5 2/8] doc: fix the requirements and building of TAP flow Date: Tue, 2 Apr 2024 10:12:34 -0700 Message-ID: <20240402171751.138324-3-stephen@networkplumber.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240402171751.138324-1-stephen@networkplumber.org> References: <20240130034925.44869-1-stephen@networkplumber.org> <20240402171751.138324-1-stephen@networkplumber.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org The build process for TAP eBPF RSS is now changed, so documentation needs to be updated. Since kernel 4.19 is the oldest current LTS supported kernel, the TAP documentation can be simplified. Any complaints about flow not working means the kernel is out of scope of current DPDK. Signed-off-by: Stephen Hemminger --- doc/guides/linux_gsg/sys_reqs.rst | 3 + doc/guides/nics/tap.rst | 95 ++++++++----------------------- 2 files changed, 28 insertions(+), 70 deletions(-) diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys_reqs.rst index 13be715933..0254568517 100644 --- a/doc/guides/linux_gsg/sys_reqs.rst +++ b/doc/guides/linux_gsg/sys_reqs.rst @@ -101,6 +101,9 @@ Running DPDK Applications To run a DPDK application, some customization may be required on the target machine. +.. _linux_gsg_kernel_version: + + System Software ~~~~~~~~~~~~~~~ diff --git a/doc/guides/nics/tap.rst b/doc/guides/nics/tap.rst index d4f45c02a1..dcfefba567 100644 --- a/doc/guides/nics/tap.rst +++ b/doc/guides/nics/tap.rst @@ -103,13 +103,8 @@ options. Default interface name is ``dtunX``, where X stands for unique id. Flow API support ---------------- -The tap PMD supports major flow API pattern items and actions, when running on -linux kernels above 4.2 ("Flower" classifier required). -The kernel support can be checked with this command:: - zcat /proc/config.gz | ( grep 'CLS_FLOWER=' || echo 'not supported' ) | - tee -a /dev/stderr | grep -q '=m' && - lsmod | ( grep cls_flower || echo 'try modprobe cls_flower' ) +The tap PMD supports major flow API pattern items and actions, when running on a supported Linux version. See :ref:`linux_gsg_kernel_version`. Supported items: @@ -123,7 +118,7 @@ Supported actions: - DROP - QUEUE - PASSTHRU -- RSS (requires kernel 4.9) +- RSS (requires clang, libbpf, and bpftool) It is generally not possible to provide a "last" item. However, if the "last" item, once masked, is identical to the masked spec, then it is supported. @@ -229,80 +224,40 @@ load commands at startup in command line or Lua script in pktgen. RSS specifics ------------- -Packet distribution in TAP is done by the kernel which has a default -distribution. This feature is adding RSS distribution based on eBPF code. -The default eBPF code calculates RSS hash based on Toeplitz algorithm for -a fixed RSS key. It is calculated on fixed packet offsets. For IPv4 and IPv6 it -is calculated over src/dst addresses (8 or 32 bytes for IPv4 or IPv6 -respectively) and src/dst TCP/UDP ports (4 bytes). +The default packet distribution in TAP without flow rules is done by the +kernel which has a default flow based distribution. +When flow rules are used to distribute packets across a set of queues +an eBPF program is used to calculate the RSS based on Toeplitz algorithm for +with the given key. -The RSS algorithm is written in file ``tap_bpf_program.c`` which -does not take part in TAP PMD compilation. Instead this file is compiled -in advance to eBPF object file. The eBPF object file is then parsed and -translated into eBPF byte code in the format of C arrays of eBPF -instructions. The C array of eBPF instructions is part of TAP PMD tree and -is taking part in TAP PMD compilation. At run time the C arrays are uploaded to -the kernel via BPF system calls and the RSS hash is calculated by the -kernel. +The hash is calculated for IPv4 and IPv6, over src/dst addresses +(8 or 32 bytes for IPv4 or IPv6 respectively) and +optionally the src/dst TCP/UDP ports (4 bytes). -It is possible to support different RSS hash algorithms by updating file -``tap_bpf_program.c`` In order to add a new RSS hash algorithm follow these -steps: - -#. Write the new RSS implementation in file ``tap_bpf_program.c`` - - BPF programs which are uploaded to the kernel correspond to - C functions under different ELF sections. - -#. Install ``LLVM`` library and ``clang`` compiler versions 3.7 and above - -#. Use make to compile `tap_bpf_program.c`` via ``LLVM`` into an object file - and extract the resulting instructions into ``tap_bpf_insn.h``:: - - cd bpf; make - -#. Recompile the TAP PMD. - -The C arrays are uploaded to the kernel using BPF system calls. - -``tc`` (traffic control) is a well known user space utility program used to -configure the Linux kernel packet scheduler. It is usually packaged as -part of the ``iproute2`` package. -Since commit 11c39b5e9 ("tc: add eBPF support to f_bpf") ``tc`` can be used -to uploads eBPF code to the kernel and can be patched in order to print the -C arrays of eBPF instructions just before calling the BPF system call. -Please refer to ``iproute2`` package file ``lib/bpf.c`` function -``bpf_prog_load()``. - -An example utility for eBPF instruction generation in the format of C arrays will -be added in next releases +The RSS algorithm is written in file ``tap_rss.c`` which is compiled with +clang and then turned into a skeleton header file with bpftool. +The skeleton header file is then compiled into the tap driver. TAP reports on supported RSS functions as part of dev_infos_get callback: ``RTE_ETH_RSS_IP``, ``RTE_ETH_RSS_UDP`` and ``RTE_ETH_RSS_TCP``. -**Known limitation:** TAP supports all of the above hash functions together -and not in partial combinations. + +**Known limitation:** TAP supports only these functions, it is not possible +to be more fine grained. For example, selecting only IPv4 and not IPV6 +to be hashed is not possible. Systems supporting flow API --------------------------- -- "tc flower" classifier requires linux kernel above 4.2 -- eBPF/RSS requires linux kernel above 4.9 - -+--------------------+-----------------------+ -| RH7.3 | No flow rule support | -+--------------------+-----------------------+ -| RH7.4 | No RSS action support | -+--------------------+-----------------------+ -| RH7.5 | No RSS action support | -+--------------------+-----------------------+ -| SLES 15, | No limitation | -| kernel 4.12 | | -+--------------------+-----------------------+ -| Azure Ubuntu 16.04,| No limitation | -| kernel 4.13 | | -+--------------------+-----------------------+ +- Any system which meets the current DPDK kernel requirements should + be able to support the flow API. + +- Supporting eBPF/RSS requires ``bpftool`` and ``libbpf``. Limitations ----------- * Rx/Tx must have the same number of queues. + +* The kernel will distribute packets across all queues. + If using flow API then add a default match and action to force a different + behavior. -- 2.43.0