From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr0-f182.google.com (mail-wr0-f182.google.com [209.85.128.182]) by dpdk.org (Postfix) with ESMTP id 818E37EE3 for ; Thu, 19 Apr 2018 12:16:46 +0200 (CEST) Received: by mail-wr0-f182.google.com with SMTP id w3-v6so12503310wrg.2 for ; Thu, 19 Apr 2018 03:16:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=6wind-com.20150623.gappssmtp.com; s=20150623; h=date:from:to:subject:message-id:references:mime-version :content-disposition:content-transfer-encoding:in-reply-to; bh=LFHH8XYBpG68dlAVWdFqojXiLRTunOoeHf7mrFXJhzY=; b=tdNs1Ex0dExMRhqKK6y3VwkUqw+IEk8fA9ChqaNnzIQl930t9ZOPIiPFmI4GskGlTf TKrVxBjhs3d0XhEf6dBtQuPccoevsHRPZi9L1clfFGg4lI7aDq27A3icpuQtqa4TASBV 6kTBnesO542KJozAXaS2j5ff8nlyipAnzOJvjfp98dLExzg9Mif4L/dljiVo2txYsUc5 F/mFy+UKaiGSnVwr3wPtB+Mi6r7BUSAosFSZthpsYMZ8AtzCTGAjzWkCEaFEsdIC3Mo2 VhA4gVahYi5GEKqeG2vblFmgQNnIMO19qUOqrfuH8KIX4FAsPEyMMjUm6JftJXlLHRZj tM9g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:subject:message-id:references :mime-version:content-disposition:content-transfer-encoding :in-reply-to; bh=LFHH8XYBpG68dlAVWdFqojXiLRTunOoeHf7mrFXJhzY=; b=U0Shvu3MypvHfZmJ2AbQeQIFpt6PfV6KESSFPKmZfjakGoi7WqZ5fFbXXcCo/AKoCC 3OVzWNNCM3mRs+oBVLau4fzGc52wGWjRBA359T59q37w9SMvpRw53dMWrk5ouSpDYpvK 9NgYU/5nj0h7Mbjs3K0quZcNdDd/CGgNRtAFt2Lb4WoUD8ZKiwnI0/WwrHvgjqKH2J9i QnUkVWM1CVxn9fs6JZ1qiumZPW6YEgWCPk32mXTtgsWUPRVejTtdOzhf5wKEhCuek4dJ wcRCytPL8u5jAFOD0NXd+zN007uH2zgM5H6BZMt+GPVCbu47LvdgFa1arnTeT/vX7X4Y eAOw== X-Gm-Message-State: ALQs6tCJlvBEA/hcgkU+3J8er/1DO18Q+hA7vqeeGpM8OrTYWrheK+SS Z/iaPd6NxD0orapcjMQ8wvyg4g== X-Google-Smtp-Source: AIpwx4+/EGMRn4n98rYz1FgNTHgM44jxVIBs/NUSKjX9YpuqNh8xG5rKPpILPqoxHm6pgcHYE1P/Cg== X-Received: by 2002:adf:c682:: with SMTP id j2-v6mr4083258wrg.135.1524133005987; Thu, 19 Apr 2018 03:16:45 -0700 (PDT) Received: from 6wind.com (host.78.145.23.62.rev.coltfrance.com. [62.23.145.78]) by smtp.gmail.com with ESMTPSA id v66sm5216383wmd.41.2018.04.19.03.16.45 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 19 Apr 2018 03:16:45 -0700 (PDT) Date: Thu, 19 Apr 2018 12:16:31 +0200 From: Adrien Mazarguil To: Thomas Monjalon , Ferruh Yigit , dev@dpdk.org Message-ID: <20180419100848.6178-4-adrien.mazarguil@6wind.com> References: <20180416150525.2817-1-adrien.mazarguil@6wind.com> <20180419100848.6178-1-adrien.mazarguil@6wind.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20180419100848.6178-1-adrien.mazarguil@6wind.com> X-Mailer: git-send-email 2.11.0 Subject: [dpdk-dev] [PATCH v5 03/16] doc: remove flow API migration section 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: Thu, 19 Apr 2018 10:16:46 -0000 This section has become less relevant since the flow API (rte_flow) is now a mature DPDK API with applications developed directly on top of it instead of an afterthought. This patch removes it for the following reasons: - It has never been updated to track the latest changes in the legacy filter types and never will. - Many provided examples are theoretical and misleading since PMDs do not implement them. Others are obvious. - Upcoming work on the flow API will alter the behavior of several pattern items, actions and in some cases, flow rules, which will in turn cause existing examples to be wrong. Signed-off-by: Adrien Mazarguil Acked-by: Andrew Rybchenko --- doc/guides/prog_guide/rte_flow.rst | 298 -------------------------------- 1 file changed, 298 deletions(-) diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst index a11ebd617..51826d04c 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/rte_flow.rst @@ -55,9 +55,6 @@ encompasses and supersedes (including all functions and filter types) in order to expose a single interface with an unambiguous behavior that is common to all poll-mode drivers (PMDs). -Several methods to migrate existing applications are described in `API -migration`_. - Flow rule --------- @@ -2068,298 +2065,3 @@ Future evolutions - Optional software fallback when PMDs are unable to handle requested flow rules so applications do not have to implement their own. - -API migration -------------- - -Exhaustive list of deprecated filter types (normally prefixed with -*RTE_ETH_FILTER_*) found in ``rte_eth_ctrl.h`` and methods to convert them -to *rte_flow* rules. - -``MACVLAN`` to ``ETH`` → ``VF``, ``PF`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*MACVLAN* can be translated to a basic `Item: ETH`_ flow rule with a -terminating `Action: VF`_ or `Action: PF`_. - -.. _table_rte_flow_migration_macvlan: - -.. table:: MACVLAN conversion - - +--------------------------+---------+ - | Pattern | Actions | - +===+=====+==========+=====+=========+ - | 0 | ETH | ``spec`` | any | VF, | - | | +----------+-----+ PF | - | | | ``last`` | N/A | | - | | +----------+-----+ | - | | | ``mask`` | any | | - +---+-----+----------+-----+---------+ - | 1 | END | END | - +---+----------------------+---------+ - -``ETHERTYPE`` to ``ETH`` → ``QUEUE``, ``DROP`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*ETHERTYPE* is basically an `Item: ETH`_ flow rule with a terminating -`Action: QUEUE`_ or `Action: DROP`_. - -.. _table_rte_flow_migration_ethertype: - -.. table:: ETHERTYPE conversion - - +--------------------------+---------+ - | Pattern | Actions | - +===+=====+==========+=====+=========+ - | 0 | ETH | ``spec`` | any | QUEUE, | - | | +----------+-----+ DROP | - | | | ``last`` | N/A | | - | | +----------+-----+ | - | | | ``mask`` | any | | - +---+-----+----------+-----+---------+ - | 1 | END | END | - +---+----------------------+---------+ - -``FLEXIBLE`` to ``RAW`` → ``QUEUE`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*FLEXIBLE* can be translated to one `Item: RAW`_ pattern with a terminating -`Action: QUEUE`_ and a defined priority level. - -.. _table_rte_flow_migration_flexible: - -.. table:: FLEXIBLE conversion - - +--------------------------+---------+ - | Pattern | Actions | - +===+=====+==========+=====+=========+ - | 0 | RAW | ``spec`` | any | QUEUE | - | | +----------+-----+ | - | | | ``last`` | N/A | | - | | +----------+-----+ | - | | | ``mask`` | any | | - +---+-----+----------+-----+---------+ - | 1 | END | END | - +---+----------------------+---------+ - -``SYN`` to ``TCP`` → ``QUEUE`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*SYN* is a `Item: TCP`_ rule with only the ``syn`` bit enabled and masked, -and a terminating `Action: QUEUE`_. - -Priority level can be set to simulate the high priority bit. - -.. _table_rte_flow_migration_syn: - -.. table:: SYN conversion - - +-----------------------------------+---------+ - | Pattern | Actions | - +===+======+==========+=============+=========+ - | 0 | ETH | ``spec`` | unset | QUEUE | - | | +----------+-------------+ | - | | | ``last`` | unset | | - | | +----------+-------------+ | - | | | ``mask`` | unset | | - +---+------+----------+-------------+---------+ - | 1 | IPV4 | ``spec`` | unset | END | - | | +----------+-------------+ | - | | | ``mask`` | unset | | - | | +----------+-------------+ | - | | | ``mask`` | unset | | - +---+------+----------+---------+---+ | - | 2 | TCP | ``spec`` | ``syn`` | 1 | | - | | +----------+---------+---+ | - | | | ``mask`` | ``syn`` | 1 | | - +---+------+----------+---------+---+ | - | 3 | END | | - +---+-------------------------------+---------+ - -``NTUPLE`` to ``IPV4``, ``TCP``, ``UDP`` → ``QUEUE`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*NTUPLE* is similar to specifying an empty L2, `Item: IPV4`_ as L3 with -`Item: TCP`_ or `Item: UDP`_ as L4 and a terminating `Action: QUEUE`_. - -A priority level can be specified as well. - -.. _table_rte_flow_migration_ntuple: - -.. table:: NTUPLE conversion - - +-----------------------------+---------+ - | Pattern | Actions | - +===+======+==========+=======+=========+ - | 0 | ETH | ``spec`` | unset | QUEUE | - | | +----------+-------+ | - | | | ``last`` | unset | | - | | +----------+-------+ | - | | | ``mask`` | unset | | - +---+------+----------+-------+---------+ - | 1 | IPV4 | ``spec`` | any | END | - | | +----------+-------+ | - | | | ``last`` | unset | | - | | +----------+-------+ | - | | | ``mask`` | any | | - +---+------+----------+-------+ | - | 2 | TCP, | ``spec`` | any | | - | | UDP +----------+-------+ | - | | | ``last`` | unset | | - | | +----------+-------+ | - | | | ``mask`` | any | | - +---+------+----------+-------+ | - | 3 | END | | - +---+-------------------------+---------+ - -``TUNNEL`` to ``ETH``, ``IPV4``, ``IPV6``, ``VXLAN`` (or other) → ``QUEUE`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*TUNNEL* matches common IPv4 and IPv6 L3/L4-based tunnel types. - -In the following table, `Item: ANY`_ is used to cover the optional L4. - -.. _table_rte_flow_migration_tunnel: - -.. table:: TUNNEL conversion - - +-------------------------------------------------------+---------+ - | Pattern | Actions | - +===+==========================+==========+=============+=========+ - | 0 | ETH | ``spec`` | any | QUEUE | - | | +----------+-------------+ | - | | | ``last`` | unset | | - | | +----------+-------------+ | - | | | ``mask`` | any | | - +---+--------------------------+----------+-------------+---------+ - | 1 | IPV4, IPV6 | ``spec`` | any | END | - | | +----------+-------------+ | - | | | ``last`` | unset | | - | | +----------+-------------+ | - | | | ``mask`` | any | | - +---+--------------------------+----------+-------------+ | - | 2 | ANY | ``spec`` | any | | - | | +----------+-------------+ | - | | | ``last`` | unset | | - | | +----------+---------+---+ | - | | | ``mask`` | ``num`` | 0 | | - +---+--------------------------+----------+---------+---+ | - | 3 | VXLAN, GENEVE, TEREDO, | ``spec`` | any | | - | | NVGRE, GRE, ... +----------+-------------+ | - | | | ``last`` | unset | | - | | +----------+-------------+ | - | | | ``mask`` | any | | - +---+--------------------------+----------+-------------+ | - | 4 | END | | - +---+---------------------------------------------------+---------+ - -``FDIR`` to most item types → ``QUEUE``, ``DROP``, ``PASSTHRU`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -*FDIR* is more complex than any other type, there are several methods to -emulate its functionality. It is summarized for the most part in the table -below. - -A few features are intentionally not supported: - -- The ability to configure the matching input set and masks for the entire - device, PMDs should take care of it automatically according to the - requested flow rules. - - For example if a device supports only one bit-mask per protocol type, - source/address IPv4 bit-masks can be made immutable by the first created - rule. Subsequent IPv4 or TCPv4 rules can only be created if they are - compatible. - - Note that only protocol bit-masks affected by existing flow rules are - immutable, others can be changed later. They become mutable again after - the related flow rules are destroyed. - -- Returning four or eight bytes of matched data when using flex bytes - filtering. Although a specific action could implement it, it conflicts - with the much more useful 32 bits tagging on devices that support it. - -- Side effects on RSS processing of the entire device. Flow rules that - conflict with the current device configuration should not be - allowed. Similarly, device configuration should not be allowed when it - affects existing flow rules. - -- Device modes of operation. "none" is unsupported since filtering cannot be - disabled as long as a flow rule is present. - -- "MAC VLAN" or "tunnel" perfect matching modes should be automatically set - according to the created flow rules. - -- Signature mode of operation is not defined but could be handled through - "FUZZY" item. - -.. _table_rte_flow_migration_fdir: - -.. table:: FDIR conversion - - +----------------------------------------+-----------------------+ - | Pattern | Actions | - +===+===================+==========+=====+=======================+ - | 0 | ETH, RAW | ``spec`` | any | QUEUE, DROP, PASSTHRU | - | | +----------+-----+ | - | | | ``last`` | N/A | | - | | +----------+-----+ | - | | | ``mask`` | any | | - +---+-------------------+----------+-----+-----------------------+ - | 1 | IPV4, IPv6 | ``spec`` | any | MARK | - | | +----------+-----+ | - | | | ``last`` | N/A | | - | | +----------+-----+ | - | | | ``mask`` | any | | - +---+-------------------+----------+-----+-----------------------+ - | 2 | TCP, UDP, SCTP | ``spec`` | any | END | - | | +----------+-----+ | - | | | ``last`` | N/A | | - | | +----------+-----+ | - | | | ``mask`` | any | | - +---+-------------------+----------+-----+ | - | 3 | VF, PF, FUZZY | ``spec`` | any | | - | | (optional) +----------+-----+ | - | | | ``last`` | N/A | | - | | +----------+-----+ | - | | | ``mask`` | any | | - +---+-------------------+----------+-----+ | - | 4 | END | | - +---+------------------------------------+-----------------------+ - -``HASH`` -~~~~~~~~ - -There is no counterpart to this filter type because it translates to a -global device setting instead of a pattern item. Device settings are -automatically set according to the created flow rules. - -``L2_TUNNEL`` to ``VOID`` → ``VXLAN`` (or others) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -All packets are matched. This type alters incoming packets to encapsulate -them in a chosen tunnel type, optionally redirect them to a VF as well. - -The destination pool for tag based forwarding can be emulated with other -flow rules using `Action: DUP`_. - -.. _table_rte_flow_migration_l2tunnel: - -.. table:: L2_TUNNEL conversion - - +---------------------------+--------------------+ - | Pattern | Actions | - +===+======+==========+=====+====================+ - | 0 | VOID | ``spec`` | N/A | VXLAN, GENEVE, ... | - | | | | | | - | | | | | | - | | +----------+-----+ | - | | | ``last`` | N/A | | - | | +----------+-----+ | - | | | ``mask`` | N/A | | - | | | | | | - +---+------+----------+-----+--------------------+ - | 1 | END | VF (optional) | - +---+ +--------------------+ - | 2 | | END | - +---+-----------------------+--------------------+ -- 2.11.0