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 BB28443E0E; Fri, 5 Apr 2024 23:18:14 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 105B140695; Fri, 5 Apr 2024 23:18:01 +0200 (CEST) Received: from mail-pg1-f169.google.com (mail-pg1-f169.google.com [209.85.215.169]) by mails.dpdk.org (Postfix) with ESMTP id 5CD59402F2 for ; Fri, 5 Apr 2024 23:17:59 +0200 (CEST) Received: by mail-pg1-f169.google.com with SMTP id 41be03b00d2f7-5d4d15ec7c5so2112240a12.1 for ; Fri, 05 Apr 2024 14:17:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20230601.gappssmtp.com; s=20230601; t=1712351878; x=1712956678; 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=ERPgEkQZ3csLaxHZkvZAw0nnZmaPM6GrLH22r4T2UUtF3WonGKc5VoIVIkiKy2GFZL KXsuNmphZybWneYuYF3CB5gwgAvATebm8/MFVCWDK2AMihhE4BDAi2eOeDbCP5ZwPzht 2KRHYlzl9WXtiOA99cRy1i2t4QWniPq5QpE+6lByOFa6XziSACAX8+l4DAi2QrnLURbw bMsVnbfarTSiS5zSupvkC3k/+p6X9qTMqg93inSkMlFuKvVBvo4hJLzC3M5S9p5Nu+3F l4+TZw5rVMGJgmmooU6p0irHVlIf5BXouVqm2XcZnBHkVoFB3KyNoYBiZd8fhIk4OrvY BJjA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1712351878; x=1712956678; 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=sGYknKrU+jEp04tl77XvPIaJp6SYjyaNfjSYF+wC94g3i59WYYgCVNpcPu6NQlKAdJ N9Wb4iby34vXqNF/HxZUj47HPF1+L71yLtA+wv8wlL+R+W6oUFM6GFHuVehfXC4keyaN NGkJPlPAEpYqfftORM0ehhP+ahYtkkG9wzwocVt9rti+Fhl5LmWGFK48O0dTb6Vfc7zS 6t4VqHT78JLAGGi+Ds165Qu3IXIZHaPbd10AjpqtsHya00zJFFu9h9vxhFCxVOpnyj8d kODLrtEC0ujEE4JraAQ2y/71QFtAnxuIdrK0LKJsrHRvasBtIa3jISa5aylCo1kKIq2+ VgVg== X-Gm-Message-State: AOJu0YzN75X8S40Hu2HgUILvVQkB1csdV2Ct+PrQbc8VyISCssBwL5c8 M8QX6pbCE9Ac9t7tWIZaY/rpMRo01+ZlYQtsmAhJCqyBfk4oghgU2Je7aPX0bbSfdiMeYFgA8Ra 4CBtYew== X-Google-Smtp-Source: AGHT+IFxIrdx40kl0T9BEYTvRcKTfYF9SceJOOSR4WnK98BmffkQtx+LvWsxnnl06prwzhJsDuBXwg== X-Received: by 2002:a17:90b:1191:b0:2a2:930c:9a8f with SMTP id gk17-20020a17090b119100b002a2930c9a8fmr2533150pjb.32.1712351878516; Fri, 05 Apr 2024 14:17:58 -0700 (PDT) Received: from hermes.local (204-195-96-226.wavecable.com. [204.195.96.226]) by smtp.gmail.com with ESMTPSA id r32-20020a17090a43a300b002a2f1e6f50bsm2137521pjg.1.2024.04.05.14.17.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 05 Apr 2024 14:17:57 -0700 (PDT) From: Stephen Hemminger To: dev@dpdk.org Cc: Stephen Hemminger Subject: [PATCH v6 2/8] doc: fix the requirements and building of TAP flow Date: Fri, 5 Apr 2024 14:14:54 -0700 Message-ID: <20240405211745.699697-3-stephen@networkplumber.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240405211745.699697-1-stephen@networkplumber.org> References: <20240130034925.44869-1-stephen@networkplumber.org> <20240405211745.699697-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