Pattern items fall in two categories:
- Matching protocol headers and packet data (ANY, RAW, ETH, VLAN, IPV4,
- IPV6, ICMP, UDP, TCP, SCTP, VXLAN and so on), usually associated with a
- specification structure.
+ IPV6, ICMP, UDP, TCP, SCTP, VXLAN, MPLS, GRE and so on), usually
+ associated with a specification structure.
- Matching meta-data or affecting pattern processing (END, VOID, INVERT, PF,
VF, PORT and so on), often without a specification structure.
values lower than those in ``spec`` are not supported.
- Setting ``spec`` and optionally ``last`` without ``mask`` causes the PMD
- to only take the fields it can recognize into account. There is no error
- checking for unsupported fields.
+ to use the default mask defined for that item (defined as
+ ``rte_flow_item_{name}_mask`` constants).
-- Not setting any of them (assuming item type allows it) uses default
- parameters that depend on the item type. Most of the time, particularly
- for protocol header items, it is equivalent to providing an empty (zeroed)
- ``mask``.
+- Not setting any of them (assuming item type allows it) is equivalent to
+ providing an empty (zeroed) ``mask`` for broad (nonspecific) matching.
- ``mask`` is a simple bit-mask applied before interpreting the contents of
``spec`` and ``last``, which may yield unexpected results if not used
- Can be specified multiple times to match traffic addressed to several VF
IDs.
- Can be combined with a PF item to match both PF and VF traffic.
+- Default ``mask`` matches any VF ID.
.. _table_rte_flow_item_vf:
As a device property, the list of allowed values as well as the value
associated with a port_id should be retrieved by other means.
+- Default ``mask`` matches any port index.
+
.. _table_rte_flow_item_port:
.. table:: PORT
This is usually specified as the first pattern item when looking for a
protocol anywhere in a packet.
+- Default ``mask`` stands for any number of layers.
+
.. _table_rte_flow_item_any:
.. table:: ANY
offset for subsequent items.
- This type does not support ranges (``last`` field).
+- Default ``mask`` matches all fields exactly.
.. _table_rte_flow_item_raw:
- ``dst``: destination MAC.
- ``src``: source MAC.
- ``type``: EtherType.
+- Default ``mask`` matches destination and source addresses only.
Item: ``VLAN``
^^^^^^^^^^^^^^
- ``tpid``: tag protocol identifier.
- ``tci``: tag control information.
+- Default ``mask`` matches TCI only.
Item: ``IPV4``
^^^^^^^^^^^^^^
Note: IPv4 options are handled by dedicated pattern items.
- ``hdr``: IPv4 header definition (``rte_ip.h``).
+- Default ``mask`` matches source and destination addresses only.
Item: ``IPV6``
^^^^^^^^^^^^^^
Note: IPv6 options are handled by dedicated pattern items.
- ``hdr``: IPv6 header definition (``rte_ip.h``).
+- Default ``mask`` matches source and destination addresses only.
Item: ``ICMP``
^^^^^^^^^^^^^^
Matches an ICMP header.
- ``hdr``: ICMP header definition (``rte_icmp.h``).
+- Default ``mask`` matches ICMP type and code only.
Item: ``UDP``
^^^^^^^^^^^^^
Matches a UDP header.
- ``hdr``: UDP header definition (``rte_udp.h``).
+- Default ``mask`` matches source and destination ports only.
Item: ``TCP``
^^^^^^^^^^^^^
Matches a TCP header.
- ``hdr``: TCP header definition (``rte_tcp.h``).
+- Default ``mask`` matches source and destination ports only.
Item: ``SCTP``
^^^^^^^^^^^^^^
Matches a SCTP header.
- ``hdr``: SCTP header definition (``rte_sctp.h``).
+- Default ``mask`` matches source and destination ports only.
Item: ``VXLAN``
^^^^^^^^^^^^^^^
- ``rsvd0``: reserved, normally 0x000000.
- ``vni``: VXLAN network identifier.
- ``rsvd1``: reserved, normally 0x00.
+- Default ``mask`` matches VNI only.
+
+Item: ``E_TAG``
+^^^^^^^^^^^^^^^
+
+Matches an IEEE 802.1BR E-Tag header.
+
+- ``tpid``: tag protocol identifier (0x893F)
+- ``epcp_edei_in_ecid_b``: E-Tag control information (E-TCI), E-PCP (3b),
+ E-DEI (1b), ingress E-CID base (12b).
+- ``rsvd_grp_ecid_b``: reserved (2b), GRP (2b), E-CID base (12b).
+- ``in_ecid_e``: ingress E-CID ext.
+- ``ecid_e``: E-CID ext.
+- Default ``mask`` simultaneously matches GRP and E-CID base.
+
+Item: ``NVGRE``
+^^^^^^^^^^^^^^^
+
+Matches a NVGRE header (RFC 7637).
+
+- ``c_k_s_rsvd0_ver``: checksum (1b), undefined (1b), key bit (1b),
+ sequence number (1b), reserved 0 (9b), version (3b). This field must have
+ value 0x2000 according to RFC 7637.
+- ``protocol``: protocol type (0x6558).
+- ``tni``: virtual subnet ID.
+- ``flow_id``: flow ID.
+- Default ``mask`` matches TNI only.
+
+Item: ``MPLS``
+^^^^^^^^^^^^^^
+
+Matches a MPLS header.
+
+- ``label_tc_s_ttl``: label, TC, Bottom of Stack and TTL.
+- Default ``mask`` matches label only.
+
+Item: ``GRE``
+^^^^^^^^^^^^^^
+
+Matches a GRE header.
+
+- ``c_rsvd0_ver``: checksum, reserved 0 and version.
+- ``protocol``: protocol type.
+- Default ``mask`` matches protocol only.
+
+Item: ``FUZZY``
+^^^^^^^^^^^^^^^^^
+
+Fuzzy pattern match, expect faster than default.
+
+This is for device that support fuzzy match option. Usually a fuzzy match is
+fast but the cost is accuracy. i.e. Signature Match only match pattern's hash
+value, but it is possible two different patterns have the same hash value.
+
+Matching accuracy level can be configured by threshold. Driver can divide the
+range of threshold and map to different accuracy levels that device support.
+
+.. _table_rte_flow_item_fuzzy:
+
+.. table:: FUZZY
+
+ +----------+---------------+--------------------------------------------------+
+ | Field | Subfield | Value |
+ +==========+===========+======================================================+
+ | ``spec`` | ``threshold`` | 0 as perfect match, 0xffffffff as fuzziest match |
+ +----------+---------------+--------------------------------------------------+
+ | ``last`` | ``threshold`` | upper range value |
+ +----------+-----------+------------------------------------------------------+
+ | ``mask`` | ``threshold`` | bit-mask apply to "spec" and "last" |
+ +----------+-----------+------------------------------------------------------+
+
+Usage example, fuzzy match a TCPv4 packets:
+
+.. _table_rte_flow_item_fuzzy_example:
+
+.. table:: Fuzzy matching
+
+ +-------+----------+
+ | Index | Item |
+ +=======+==========+
+ | 0 | FUZZY |
+ +-------+----------+
+ | 1 | Ethernet |
+ +-------+----------+
+ | 2 | IPv4 |
+ +-------+----------+
+ | 3 | TCP |
+ +-------+----------+
+ | 4 | END |
+ +-------+----------+
Actions
~~~~~~~
const struct rte_flow_action actions[],
struct rte_flow_error *error);
-While this function has no effect on the target device, the flow rule is
-validated against its current configuration state and the returned value
-should be considered valid by the caller for that state only.
+The flow rule is validated for correctness and whether it could be accepted
+by the device given sufficient resources. The rule is checked against the
+current device mode and queue configuration. The flow rule may also
+optionally be validated against existing flow rules and device resources.
+This function has no effect on the target device.
The returned value is guaranteed to remain valid only as long as no
successful calls to ``rte_flow_create()`` or ``rte_flow_destroy()`` are made
- ``-EINVAL``: unknown or invalid rule specification.
- ``-ENOTSUP``: valid but unsupported rule specification (e.g. partial
bit-masks are unsupported).
-- ``-EEXIST``: collision with an existing rule.
-- ``-ENOMEM``: not enough resources.
+- ``EEXIST``: collision with an existing rule. Only returned if device
+ supports flow rule collision checking and there was a flow rule
+ collision. Not receiving this return code is no guarantee that creating
+ the rule will not fail due to a collision.
+- ``ENOMEM``: not enough memory to execute the function, or if the device
+ supports resource validation, resource limitation on the device.
- ``-EBUSY``: action cannot be performed due to busy device resources, may
succeed if the affected queues or even the entire port are in a stopped
state (see ``rte_eth_dev_rx_queue_stop()`` and ``rte_eth_dev_stop()``).
- 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
+Isolated mode
+-------------
+
+The general expectation for ingress traffic is that flow rules process it
+first; the remaining unmatched or pass-through traffic usually ends up in a
+queue (with or without RSS, locally or in some sub-device instance)
+depending on the global configuration settings of a port.
+
+While fine from a compatibility standpoint, this approach makes drivers more
+complex as they have to check for possible side effects outside of this API
+when creating or destroying flow rules. It results in a more limited set of
+available rule types due to the way device resources are assigned (e.g. no
+support for the RSS action even on capable hardware).
+
+Given that nonspecific traffic can be handled by flow rules as well,
+isolated mode is a means for applications to tell a driver that ingress on
+the underlying port must be injected from the defined flow rules only; that
+no default traffic is expected outside those rules.
+
+This has the following benefits:
+
+- Applications get finer-grained control over the kind of traffic they want
+ to receive (no traffic by default).
+
+- More importantly they control at what point nonspecific traffic is handled
+ relative to other flow rules, by adjusting priority levels.
+
+- Drivers can assign more hardware resources to flow rules and expand the
+ set of supported rule types.
+
+Because toggling isolated mode may cause profound changes to the ingress
+processing path of a driver, it may not be possible to leave it once
+entered. Likewise, existing flow rules or global configuration settings may
+prevent a driver from entering isolated mode.
+
+Applications relying on this mode are therefore encouraged to toggle it as
+soon as possible after device initialization, ideally before the first call
+to ``rte_eth_dev_configure()`` to avoid possible failures due to conflicting
+settings.
+
+Once effective, the following functionality has no effect on the underlying
+port and may return errors such as ``ENOTSUP`` ("not supported"):
+
+- Toggling promiscuous mode.
+- Toggling allmulticast mode.
+- Configuring MAC addresses.
+- Configuring multicast addresses.
+- Configuring VLAN filters.
+- Configuring Rx filters through the legacy API (e.g. FDIR).
+- Configuring global RSS settings.
+
+.. code-block:: c
+
+ int
+ rte_flow_isolate(uint8_t port_id, int set, struct rte_flow_error *error);
+
+Arguments:
+
+- ``port_id``: port identifier of Ethernet device.
+- ``set``: nonzero to enter isolated mode, attempt to leave it otherwise.
+- ``error``: perform verbose error reporting if not NULL. PMDs initialize
+ this structure in case of error only.
+
+Return values:
+
+- 0 on success, a negative errno value otherwise and ``rte_errno`` is set.
+
Verbose error reporting
-----------------------
- "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 a
- specific item type if needed.
+- Signature mode of operation is not defined but could be handled through
+ "FUZZY" item.
.. _table_rte_flow_migration_fdir:
| | +----------+-----+ |
| | | ``mask`` | any | |
+---+-------------------+----------+-----+ |
- | 3 | VF, PF (optional) | ``spec`` | any | |
- | | +----------+-----+ |
+ | 3 | VF, PF, FUZZY | ``spec`` | any | |
+ | | (optional) +----------+-----+ |
| | | ``last`` | N/A | |
| | +----------+-----+ |
| | | ``mask`` | any | |
git.droids-corp.org / dpdk.git / blobdiff