From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by dpdk.org (Postfix) with ESMTP id 08D992C24 for ; Fri, 4 May 2018 14:46:13 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga008.fm.intel.com ([10.253.24.58]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 04 May 2018 05:46:13 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.49,362,1520924400"; d="scan'208";a="37428699" Received: from sivswdev02.ir.intel.com (HELO localhost.localdomain) ([10.237.217.46]) by fmsmga008.fm.intel.com with ESMTP; 04 May 2018 05:46:12 -0700 From: Konstantin Ananyev To: dev@dpdk.org Cc: Konstantin Ananyev Date: Fri, 4 May 2018 13:45:45 +0100 Message-Id: <1525437945-8207-9-git-send-email-konstantin.ananyev@intel.com> X-Mailer: git-send-email 1.7.0.7 In-Reply-To: <1523630598-24606-2-git-send-email-konstantin.ananyev@intel.com> References: <1523630598-24606-2-git-send-email-konstantin.ananyev@intel.com> Subject: [dpdk-dev] [PATCH v5 8/8] doc: add bpf library related info 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: , X-List-Received-Date: Fri, 04 May 2018 12:46:14 -0000 Signed-off-by: Konstantin Ananyev --- doc/api/doxy-api-index.md | 3 +- doc/api/doxy-api.conf | 1 + doc/guides/prog_guide/bpf_lib.rst | 38 ++++++++++++++++++++ doc/guides/prog_guide/index.rst | 1 + doc/guides/rel_notes/release_18_05.rst | 7 ++++ doc/guides/testpmd_app_ug/testpmd_funcs.rst | 56 +++++++++++++++++++++++++++++ 6 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 doc/guides/prog_guide/bpf_lib.rst diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index 26ce7b44b..927ec59b2 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -108,7 +108,8 @@ The public API headers are grouped by topics: [EFD] (@ref rte_efd.h), [ACL] (@ref rte_acl.h), [member] (@ref rte_member.h), - [flow classify] (@ref rte_flow_classify.h) + [flow classify] (@ref rte_flow_classify.h), + [BPF] (@ref rte_bpf.h) - **containers**: [mbuf] (@ref rte_mbuf.h), diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf index 5686cbb9d..037166e76 100644 --- a/doc/api/doxy-api.conf +++ b/doc/api/doxy-api.conf @@ -42,6 +42,7 @@ INPUT = doc/api/doxy-api-index.md \ lib/librte_acl \ lib/librte_bbdev \ lib/librte_bitratestats \ + lib/librte_bpf \ lib/librte_cfgfile \ lib/librte_cmdline \ lib/librte_compat \ diff --git a/doc/guides/prog_guide/bpf_lib.rst b/doc/guides/prog_guide/bpf_lib.rst new file mode 100644 index 000000000..7c08e6b2d --- /dev/null +++ b/doc/guides/prog_guide/bpf_lib.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Intel Corporation. + +Berkeley Packet Filter Library +============================== + +The DPDK provides an BPF library that gives the ability +to load and execute Enhanced Berkeley Packet Filter (eBPF) bytecode within +user-space dpdk application. + +It supports basic set of features from eBPF spec. +Please refer to the +`eBPF spec ` +for more information. +Also it introduces basic framework to load/unload BPF-based filters +on eth devices (right now only via SW RX/TX callbacks). + +The library API provides the following basic operations: + +* Create a new BPF execution context and load user provided eBPF code into it. + +* Destroy an BPF execution context and its runtime structures and free the associated memory. + +* Execute eBPF bytecode associated with provided input parameter. + +* Provide information about natively compiled code for given BPF context. + +* Load BPF program from the ELF file and install callback to execute it on given ethdev port/queue. + +Not currently supported eBPF features +------------------------------------- + + - JIT for non X86_64 platforms + - cBPF + - tail-pointer call + - eBPF MAP + - skb + - external function calls for 32-bit platforms diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 235ad0201..2c40fb4ec 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -51,6 +51,7 @@ Programmer's Guide vhost_lib metrics_lib port_hotplug_framework + bpf_lib source_org dev_kit_build_system dev_kit_root_make_help diff --git a/doc/guides/rel_notes/release_18_05.rst b/doc/guides/rel_notes/release_18_05.rst index 0ae61e87b..1ddb094c4 100644 --- a/doc/guides/rel_notes/release_18_05.rst +++ b/doc/guides/rel_notes/release_18_05.rst @@ -164,6 +164,13 @@ New Features stats/xstats on shared memory from secondary process, and also pdump packets on those virtual devices. +* **Added the BPF Library.** + + The BPF Library provides the ability to load and execute + Enhanced Berkeley Packet Filter (eBPF) within user-space dpdk application. + Also it introduces basic framework to load/unload BPF-based filters + on eth devices (right now only via SW RX/TX callbacks). + It also adds dependency on libelf. API Changes ----------- diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst index 013a40549..e4afb03dc 100644 --- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst +++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst @@ -3813,3 +3813,59 @@ Validate and create a QinQ rule on port 0 to steer traffic to a queue on the hos ID Group Prio Attr Rule 0 0 0 i- ETH VLAN VLAN=>VF QUEUE 1 0 0 i- ETH VLAN VLAN=>PF QUEUE + +BPF Functions +-------------- + +The following sections show functions to load/unload eBPF based filters. + +bpf-load +~~~~~~~~ + +Load an eBPF program as a callback for partciular RX/TX queue:: + + testpmd> bpf-load rx|tx (portid) (queueid) (load-flags) (bpf-prog-filename) + +The available load-flags are: + +* ``J``: use JIT generated native code, otherwise BPF interpreter will be used. + +* ``M``: assume input parameter is a pointer to rte_mbuf, otherwise assume it is a pointer to first segment's data. + +* ``-``: none. + +.. note:: + + You'll need clang v3.7 or above to build bpf program you'd like to load + +For example: + +.. code-block:: console + + cd test/bpf + clang -O2 -target bpf -c t1.c + +Then to load (and JIT compile) t1.o at RX queue 0, port 1:: + +.. code-block:: console + + testpmd> bpf-load rx 1 0 J ./dpdk.org/test/bpf/t1.o + +To load (not JITed) t1.o at TX queue 0, port 0:: + +.. code-block:: console + + testpmd> bpf-load tx 0 0 - ./dpdk.org/test/bpf/t1.o + +bpf-unload +~~~~~~~~~~ + +Unload previously loaded eBPF program for partciular RX/TX queue:: + + testpmd> bpf-unload rx|tx (portid) (queueid) + +For example to unload BPF filter from TX queue 0, port 0: + +.. code-block:: console + + testpmd> bpf-load tx 0 0 - ./dpdk.org/test/bpf/t1.o -- 2.13.6