X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Ftestpmd_app_ug%2Ftestpmd_funcs.rst;h=2e6a23b12a6a408351b8f53f25ef9e9e0feb7691;hb=04cc665fab38e2a382f6886e57c97b78e92cea46;hp=cc319371d763759e408821d6c318644a335817d5;hpb=99a1b6895f078d5cd6b3033d213a76da5278552d;p=dpdk.git diff --git a/doc/guides/testpmd_app_ug/testpmd_funcs.rst b/doc/guides/testpmd_app_ug/testpmd_funcs.rst index cc319371d7..2e6a23b12a 100644 --- a/doc/guides/testpmd_app_ug/testpmd_funcs.rst +++ b/doc/guides/testpmd_app_ug/testpmd_funcs.rst @@ -24,10 +24,10 @@ If you type a partial command and hit ```` you get a list of the available testpmd> show port - info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap X - info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap all - stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap X - stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|stat_qmap|dcb_tc|cap all + info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|dcb_tc|cap X + info [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|dcb_tc|cap all + stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|dcb_tc|cap X + stats [Mul-choice STRING]: show|clear port info|stats|xstats|fdir|dcb_tc|cap all ... @@ -159,7 +159,7 @@ show port Display information for a given port or all ports:: - testpmd> show port (info|summary|stats|xstats|fdir|stat_qmap|dcb_tc|cap) (port_id|all) + testpmd> show port (info|summary|stats|xstats|fdir|dcb_tc|cap) (port_id|all) The available information categories are: @@ -173,12 +173,8 @@ The available information categories are: * ``fdir``: Flow Director information and statistics. -* ``stat_qmap``: Queue statistics mapping. - * ``dcb_tc``: DCB information such as TC mapping. -* ``cap``: Supported offload capabilities. - For example: .. code-block:: console @@ -246,7 +242,7 @@ clear port Clear the port statistics and forward engine statistics for a given port or for all ports:: - testpmd> clear port (info|stats|xstats|fdir|stat_qmap) (port_id|all) + testpmd> clear port (info|stats|xstats|fdir) (port_id|all) For example:: @@ -266,6 +262,13 @@ Display information for a given port's RX/TX descriptor status:: testpmd> show port (port_id) (rxq|txq) (queue_id) desc (desc_id) status +show rxq desc used count +~~~~~~~~~~~~~~~~~~~~~~~~ + +Display the number of receive packet descriptors currently filled by hardware +and ready to be processed by the driver on a given RX queue:: + + testpmd> show port (port_id) rxq (queue_id) desc used count show config ~~~~~~~~~~~ @@ -311,7 +314,7 @@ set fwd Set the packet forwarding mode:: testpmd> set fwd (io|mac|macswap|flowgen| \ - rxonly|txonly|csum|icmpecho|noisy|5tswap) (""|retry) + rxonly|txonly|csum|icmpecho|noisy|5tswap|shared-rxq) (""|retry) ``retry`` can be specified for forwarding engines except ``rx_only``. @@ -354,6 +357,9 @@ The available information categories are: L4 swaps the source port and destination port of transport layer (TCP and UDP). +* ``shared-rxq``: Receive only for shared Rx queue. + Resolve packet source port from mbuf and update stream statistics accordingly. + Example:: testpmd> set fwd rxonly @@ -521,6 +527,15 @@ Show multicast mac addresses added for a specific port:: testpmd> show port (port_id) mcast_macs +show flow transfer proxy port ID for the given port +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Show proxy port ID to use as the 1st argument in commands to +manage ``transfer`` flows and their indirect components. +:: + + testpmd> show port (port_id) flow transfer proxy + show device info ~~~~~~~~~~~~~~~~ @@ -1521,6 +1536,13 @@ Where: * ``autoneg``: Change the auto-negotiation parameter. +show flow control +~~~~~~~~~~~~~~~~~ + +show the link flow control parameter on a port:: + + testpmd> show port flow_ctrl + set pfc_ctrl rx ~~~~~~~~~~~~~~~ @@ -1539,6 +1561,29 @@ Where: * ``priority`` (0-7): VLAN User Priority. +set pfc_queue_ctrl +~~~~~~~~~~~~~~~~~~ + +Set the priority flow control parameter on a given Rx and Tx queue of a port:: + + testpmd> set pfc_queue_ctrl rx (on|off) \ + tx (on|off) + +Where: + +* ``tx_qid`` (integer): Tx qid for which ``tx_tc`` will be applied and traffic + will be paused when PFC frame is received with ``tx_tc`` enabled. + +* ``tx_tc`` (0-15): TC for which traffic is to be paused for xmit. + +* ``rx_qid`` (integer): Rx qid for which threshold will be applied and PFC + frame will be generated with ``tx_tc`` when exceeds the threshold. + +* ``rx_tc`` (0-15): TC filled in PFC frame for which remote Tx is to be paused. + +* ``pause_time`` (integer): Pause quanta filled in the PFC frame for which + interval, remote Tx will be paused. Valid only if Tx pause is on. + set stat_qmap ~~~~~~~~~~~~~ @@ -1600,31 +1645,6 @@ Set TX rate limitation for queues in VF on a port:: testpmd> set port (port_id) vf (vf_id) rate (rate_value) queue_mask (queue_mask) -set port - mirror rule -~~~~~~~~~~~~~~~~~~~~~~ - -Set pool or vlan type mirror rule for a port:: - - testpmd> set port (port_id) mirror-rule (rule_id) \ - (pool-mirror-up|pool-mirror-down|vlan-mirror) \ - (poolmask|vlanid[,vlanid]*) dst-pool (pool_id) (on|off) - -Set link mirror rule for a port:: - - testpmd> set port (port_id) mirror-rule (rule_id) \ - (uplink-mirror|downlink-mirror) dst-pool (pool_id) (on|off) - -For example to enable mirror traffic with vlan 0,1 to pool 0:: - - set port 0 mirror-rule 0 vlan-mirror 0,1 dst-pool 0 on - -reset port - mirror rule -~~~~~~~~~~~~~~~~~~~~~~~~ - -Reset a mirror rule for a port:: - - testpmd> reset port (port_id) mirror-rule (rule_id) - set flush_rx ~~~~~~~~~~~~ @@ -1732,7 +1752,7 @@ List all items from the ptype mapping table:: Where: -* ``valid_only``: A flag indicates if only list valid items(=1) or all itemss(=0). +* ``valid_only``: A flag indicates if only list valid items(=1) or all items(=0). Replace a specific or a group of software defined ptype with a new one:: @@ -1998,6 +2018,24 @@ Set fec mode for a specific port:: testpmd> set port (port_id) fec_mode auto|off|rs|baser +Config Sample actions list +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configure the sample actions list to be used when sampling a packet by +rte_flow_action_sample:: + + set sample_actions {index} {action} [/ {action} [...]] / end + +There are multiple global buffers for ``sample_actions``, this command will set +one internal buffer index by ``{index}``. + +In order to use different sample actions list, ``index`` must be specified +during the flow rule creation:: + + testpmd> flow create 0 ingress pattern eth / ipv4 / end actions + sample ratio 2 index 2 / end + +Otherwise the default index ``0`` is used. Port Functions -------------- @@ -2270,11 +2308,11 @@ port config - RSS Set the RSS (Receive Side Scaling) mode on or off:: - testpmd> port config all rss (all|default|eth|vlan|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|vxlan-gpe|l2tpv3|esp|ah|pfcp|none) + testpmd> port config all rss (all|default|eth|vlan|ip|tcp|udp|sctp|ether|port|vxlan|geneve|nvgre|vxlan-gpe|l2tpv3|esp|ah|pfcp|ecpri|mpls|l2tpv2|none) RSS is on by default. -The ``all`` option is equivalent to eth|vlan|ip|tcp|udp|sctp|ether|l2tpv3|esp|ah|pfcp. +The ``all`` option is equivalent to eth|vlan|ip|tcp|udp|sctp|ether|l2tpv3|esp|ah|pfcp|l2tpv2. The ``default`` option enables all supported RSS types reported by device info. @@ -2334,13 +2372,6 @@ Where the threshold type can be: These threshold options are also available from the command-line. -port config - E-tag -~~~~~~~~~~~~~~~~~~~ - -Enable/disable the E-tag support:: - - testpmd> port config (port_id|all) l2-tunnel E-tag (enable|disable) - port config pctype mapping ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2382,7 +2413,7 @@ port config udp_tunnel_port Add/remove UDP tunnel port for VXLAN/GENEVE tunneling protocols:: - testpmd> port config (port_id) udp_tunnel_port add|rm vxlan|geneve|vxlan-gpe (udp_port) + testpmd> port config (port_id) udp_tunnel_port add|rm vxlan|geneve|vxlan-gpe|ecpri (udp_port) port config tx_metadata ~~~~~~~~~~~~~~~~~~~~~~~ @@ -2422,6 +2453,15 @@ hash of input [IP] packets received on port:: ipv6-udp-ex ) +port cleanup txq mbufs +~~~~~~~~~~~~~~~~~~~~~~ + +To cleanup txq mbufs currently cached by driver:: + + testpmd> port cleanup (port_id) txq (queue_id) (free_cnt) + +If the value of ``free_cnt`` is 0, driver should free all cached mbufs. + Device Functions ---------------- @@ -2600,6 +2640,12 @@ in balance mode with a transmission policy of layer 2+3:: Active Slaves (3): [1 3 4] Primary: [3] +show bonding lacp info +~~~~~~~~~~~~~~~~~~~~~~ + +Show information about the Link Bonding device in mode 4 (link-aggregation-802.3ad):: + + testpmd> show bonding lacp info (port_id) Register Functions ------------------ @@ -2700,14 +2746,15 @@ add port meter profile (srTCM rfc2967) Add meter profile (srTCM rfc2697) to the ethernet device:: testpmd> add port meter profile srtcm_rfc2697 (port_id) (profile_id) \ - (cir) (cbs) (ebs) + (cir) (cbs) (ebs) (packet_mode) where: * ``profile_id``: ID for the meter profile. -* ``cir``: Committed Information Rate (CIR) (bytes/second). -* ``cbs``: Committed Burst Size (CBS) (bytes). -* ``ebs``: Excess Burst Size (EBS) (bytes). +* ``cir``: Committed Information Rate (CIR) (bytes per second or packets per second). +* ``cbs``: Committed Burst Size (CBS) (bytes or packets). +* ``ebs``: Excess Burst Size (EBS) (bytes or packets). +* ``packet_mode``: Packets mode for meter profile. add port meter profile (trTCM rfc2968) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2715,15 +2762,16 @@ add port meter profile (trTCM rfc2968) Add meter profile (srTCM rfc2698) to the ethernet device:: testpmd> add port meter profile trtcm_rfc2698 (port_id) (profile_id) \ - (cir) (pir) (cbs) (pbs) + (cir) (pir) (cbs) (pbs) (packet_mode) where: * ``profile_id``: ID for the meter profile. -* ``cir``: Committed information rate (bytes/second). -* ``pir``: Peak information rate (bytes/second). -* ``cbs``: Committed burst size (bytes). -* ``pbs``: Peak burst size (bytes). +* ``cir``: Committed information rate (bytes per second or packets per second). +* ``pir``: Peak information rate (bytes per second or packets per second). +* ``cbs``: Committed burst size (bytes or packets). +* ``pbs``: Peak burst size (bytes or packets). +* ``packet_mode``: Packets mode for meter profile. add port meter profile (trTCM rfc4115) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2731,15 +2779,16 @@ add port meter profile (trTCM rfc4115) Add meter profile (trTCM rfc4115) to the ethernet device:: testpmd> add port meter profile trtcm_rfc4115 (port_id) (profile_id) \ - (cir) (eir) (cbs) (ebs) + (cir) (eir) (cbs) (ebs) (packet_mode) where: * ``profile_id``: ID for the meter profile. -* ``cir``: Committed information rate (bytes/second). -* ``eir``: Excess information rate (bytes/second). -* ``cbs``: Committed burst size (bytes). -* ``ebs``: Excess burst size (bytes). +* ``cir``: Committed information rate (bytes per second or packets per second). +* ``eir``: Excess information rate (bytes per second or packets per second). +* ``cbs``: Committed burst size (bytes or packets). +* ``ebs``: Excess burst size (bytes or packets). +* ``packet_mode``: Packets mode for meter profile. delete port meter profile ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2748,13 +2797,37 @@ Delete meter profile from the ethernet device:: testpmd> del port meter profile (port_id) (profile_id) +create port policy +~~~~~~~~~~~~~~~~~~ + +Create new policy object for the ethernet device:: + + testpmd> add port meter policy (port_id) (policy_id) g_actions \ + {action} y_actions {action} r_actions {action} + +where: + +* ``policy_id``: policy ID. +* ``action``: action lists for green/yellow/red colors. + +delete port policy +~~~~~~~~~~~~~~~~~~ + +Delete policy object for the ethernet device:: + + testpmd> del port meter policy (port_id) (policy_id) + +where: + +* ``policy_id``: policy ID. + create port meter ~~~~~~~~~~~~~~~~~ Create new meter object for the ethernet device:: testpmd> create port meter (port_id) (mtr_id) (profile_id) \ - (meter_enable) (g_action) (y_action) (r_action) (stats_mask) (shared) \ + (policy_id) (meter_enable) (stats_mask) (shared) \ (use_pre_meter_color) [(dscp_tbl_entry0) (dscp_tbl_entry1)...\ (dscp_tbl_entry63)] @@ -2762,11 +2835,9 @@ where: * ``mtr_id``: meter object ID. * ``profile_id``: ID for the meter profile. +* ``policy_id``: ID for the policy. * ``meter_enable``: When this parameter has a non-zero value, the meter object gets enabled at the time of creation, otherwise remains disabled. -* ``g_action``: Policer action for the packet with green color. -* ``y_action``: Policer action for the packet with yellow color. -* ``r_action``: Policer action for the packet with red color. * ``stats_mask``: Mask of statistics counter types to be enabled for the meter object. * ``shared``: When this parameter has a non-zero value, the meter object is @@ -2814,24 +2885,6 @@ Set meter dscp table for the ethernet device:: testpmd> set port meter dscp table (port_id) (mtr_id) [(dscp_tbl_entry0) \ (dscp_tbl_entry1)...(dscp_tbl_entry63)] -set port meter policer action -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Set meter policer action for the ethernet device:: - - testpmd> set port meter policer action (port_id) (mtr_id) (action_mask) \ - (action0) [(action1) (action1)] - -where: - -* ``action_mask``: Bit mask indicating which policer actions need to be - updated. One or more policer actions can be updated in a single function - invocation. To update the policer action associated with color C, bit - (1 << C) needs to be set in *action_mask* and element at position C - in the *actions* array needs to be valid. -* ``actionx``: Policer action for the color x, - RTE_MTR_GREEN <= x < RTE_MTR_COLORS - set port meter stats mask ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3255,8 +3308,8 @@ Flow rules management --------------------- Control of the generic flow API (*rte_flow*) is fully exposed through the -``flow`` command (validation, creation, destruction, queries and operation -modes). +``flow`` command (configuration, validation, creation, destruction, queries +and operation modes). Considering *rte_flow* overlaps with all `Filter Functions`_, using both features simultaneously may cause undefined side-effects and is therefore @@ -3279,6 +3332,38 @@ The first parameter stands for the operation mode. Possible operations and their general syntax are described below. They are covered in detail in the following sections. +- Get info about flow engine:: + + flow info {port_id} + +- Configure flow engine:: + + flow configure {port_id} + [queues_number {number}] [queues_size {size}] + [counters_number {number}] + [aging_counters_number {number}] + [meters_number {number}] + +- Create a pattern template:: + flow pattern_template {port_id} create [pattern_template_id {id}] + [relaxed {boolean}] [ingress] [egress] [transfer] + template {item} [/ {item} [...]] / end + +- Destroy a pattern template:: + + flow pattern_template {port_id} destroy pattern_template {id} [...] + +- Create an actions template:: + + flow actions_template {port_id} create [actions_template_id {id}] + [ingress] [egress] [transfer] + template {action} [/ {action} [...]] / end + mask {action} [/ {action} [...]] / end + +- Destroy an actions template:: + + flow actions_template {port_id} destroy actions_template {id} [...] + - Check whether a flow rule can be created:: flow validate {port_id} @@ -3316,7 +3401,11 @@ following sections. - Dump internal representation information of all flows in hardware:: - flow dump {port_id} {output_file} + flow dump {port_id} all {output_file} + + for one flow:: + + flow dump {port_id} rule {rule_id} {output_file} - List and destroy aged flow rules:: @@ -3334,6 +3423,132 @@ following sections. flow tunnel list {port_id} +Retrieving info about flow management engine +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flow info`` retrieves info on pre-configurable resources in the underlying +device to give a hint of possible values for flow engine configuration. + +``rte_flow_info_get()``:: + + flow info {port_id} + +If successful, it will show:: + + Flow engine resources on port #[...]: + Number of queues: #[...] + Size of queues: #[...] + Number of counters: #[...] + Number of aging objects: #[...] + Number of meters: #[...] + +Otherwise it will show an error message of the form:: + + Caught error type [...] ([...]): [...] + +Configuring flow management engine +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flow configure`` pre-allocates all the needed resources in the underlying +device to be used later at the flow creation. Flow queues are allocated as well +for asynchronous flow creation/destruction operations. It is bound to +``rte_flow_configure()``:: + + flow configure {port_id} + [queues_number {number}] [queues_size {size}] + [counters_number {number}] + [aging_counters_number {number}] + [meters_number {number}] + +If successful, it will show:: + + Configure flows on port #[...]: number of queues #[...] with #[...] elements + +Otherwise it will show an error message of the form:: + + Caught error type [...] ([...]): [...] + +Creating pattern templates +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flow pattern_template create`` creates the specified pattern template. +It is bound to ``rte_flow_pattern_template_create()``:: + + flow pattern_template {port_id} create [pattern_template_id {id}] + [relaxed {boolean}] [ingress] [egress] [transfer] + template {item} [/ {item} [...]] / end + +If successful, it will show:: + + Pattern template #[...] created + +Otherwise it will show an error message of the form:: + + Caught error type [...] ([...]): [...] + +This command uses the same pattern items as ``flow create``, +their format is described in `Creating flow rules`_. + +Destroying pattern templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flow pattern_template destroy`` destroys one or more pattern templates +from their template ID (as returned by ``flow pattern_template create``), +this command calls ``rte_flow_pattern_template_destroy()`` as many +times as necessary:: + + flow pattern_template {port_id} destroy pattern_template {id} [...] + +If successful, it will show:: + + Pattern template #[...] destroyed + +It does not report anything for pattern template IDs that do not exist. +The usual error message is shown when a pattern template cannot be destroyed:: + + Caught error type [...] ([...]): [...] + +Creating actions templates +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flow actions_template create`` creates the specified actions template. +It is bound to ``rte_flow_actions_template_create()``:: + + flow actions_template {port_id} create [actions_template_id {id}] + [ingress] [egress] [transfer] + template {action} [/ {action} [...]] / end + mask {action} [/ {action} [...]] / end + +If successful, it will show:: + + Actions template #[...] created + +Otherwise it will show an error message of the form:: + + Caught error type [...] ([...]): [...] + +This command uses the same actions as ``flow create``, +their format is described in `Creating flow rules`_. + +Destroying actions templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flow actions_template destroy`` destroys one or more actions templates +from their template ID (as returned by ``flow actions_template create``), +this command calls ``rte_flow_actions_template_destroy()`` as many +times as necessary:: + + flow actions_template {port_id} destroy actions_template {id} [...] + +If successful, it will show:: + + Actions template #[...] destroyed + +It does not report anything for actions template IDs that do not exist. +The usual error message is shown when an actions template cannot be destroyed:: + + Caught error type [...] ([...]): [...] + Creating a tunnel stub for offload ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3452,6 +3667,10 @@ specified before the ``pattern`` token. - ``egress``: rule applies to egress traffic. - ``transfer``: apply rule directly to endpoints found in pattern. +Please note that use of ``transfer`` attribute requires that the flow and +its indirect components be managed via so-called ``transfer`` proxy port. +See `show flow transfer proxy port ID for the given port`_ for details. + Each instance of an attribute specified several times overrides the previous value as shown below (group 4 is used):: @@ -3472,7 +3691,7 @@ Tunnel offload Indicate tunnel offload rule type - ``tunnel_set {tunnel_id}``: mark rule as tunnel offload decap_set type. -- ``tunnel_match {tunnel_id}``: mark rule as tunel offload match type. +- ``tunnel_match {tunnel_id}``: mark rule as tunnel offload match type. Matching pattern ^^^^^^^^^^^^^^^^ @@ -3596,6 +3815,7 @@ This section lists supported pattern items and their attributes, if any. - ``offset {integer}``: absolute or relative offset for pattern. - ``limit {unsigned}``: search area limit for start of pattern. - ``pattern {string}``: byte string to look for. + - ``pattern_hex {string}``: byte string (provided in hexadecimal) to look for. - ``eth``: match Ethernet header. @@ -3613,6 +3833,7 @@ This section lists supported pattern items and their attributes, if any. - ``ipv4``: match IPv4 header. + - ``version_ihl {unsigned}``: IPv4 version and IP header length. - ``tos {unsigned}``: type of service. - ``ttl {unsigned}``: time to live. - ``proto {unsigned}``: next protocol ID. @@ -3653,6 +3874,7 @@ This section lists supported pattern items and their attributes, if any. - ``vxlan``: match VXLAN header. - ``vni {unsigned}``: VXLAN identifier. + - ``last_rsvd {unsigned}``: VXLAN last reserved 8-bits. - ``e_tag``: match IEEE 802.1BR E-Tag header. @@ -3674,6 +3896,12 @@ This section lists supported pattern items and their attributes, if any. - ``value {unsigned}``: key value. +- ``gre_option``: match GRE optional fields(checksum/key/sequence). + + - ``checksum {unsigned}``: checksum value. + - ``key {unsigned}``: key value. + - ``sequence {unsigned}``: sequence number value. + - ``fuzzy``: fuzzy pattern match, expect faster than default. - ``thresh {unsigned}``: accuracy threshold. @@ -3687,6 +3915,14 @@ This section lists supported pattern items and their attributes, if any. - ``vni {unsigned}``: virtual network identifier. - ``protocol {unsigned}``: protocol type. +- ``geneve-opt``: match GENEVE header option. + + - ``class {unsigned}``: GENEVE option class. + - ``type {unsigned}``: GENEVE option type. + - ``length {unsigned}``: GENEVE option length in 32-bit words. + - ``data {hex string}``: GENEVE option data, the length is defined by + ``length`` field. + - ``vxlan-gpe``: match VXLAN-GPE header. - ``vni {unsigned}``: VXLAN-GPE identifier. @@ -3736,6 +3972,7 @@ This section lists supported pattern items and their attributes, if any. - ``gtp_psc``: match GTP PDU extension header with type 0x85. - ``pdu_type {unsigned}``: PDU type. + - ``qfi {unsigned}``: QoS flow identifier. - ``pppoes``, ``pppoed``: match PPPoE header. @@ -3759,6 +3996,39 @@ This section lists supported pattern items and their attributes, if any. - ``s_field {unsigned}``: S field. - ``seid {unsigned}``: session endpoint identifier. +- ``integrity``: match packet integrity. + + - ``level {unsigned}``: Packet encapsulation level the item should + apply to. See rte_flow_action_rss for details. + - ``value {unsigned}``: A bitmask that specify what packet elements + must be matched for integrity. + +- ``conntrack``: match conntrack state. + +- ``port_representor``: match traffic entering the embedded switch from the given ethdev + + - ``port_id {unsigned}``: ethdev port ID + +- ``represented_port``: match traffic entering the embedded switch from + the entity represented by the given ethdev + + - ``ethdev_port_id {unsigned}``: ethdev port ID + +- ``l2tpv2``: match L2TPv2 header. + + - ``length {unsigned}``: L2TPv2 option length. + - ``tunnel_id {unsigned}``: L2TPv2 tunnel identifier. + - ``session_id {unsigned}``: L2TPv2 session identifier. + - ``ns {unsigned}``: L2TPv2 option ns. + - ``nr {unsigned}``: L2TPv2 option nr. + - ``offset_size {unsigned}``: L2TPv2 option offset. + +- ``ppp``: match PPP header. + + - ``addr {unsigned}``: PPP address. + - ``ctrl {unsigned}``: PPP control. + - ``proto_id {unsigned}``: PPP protocol identifier. + Actions list ^^^^^^^^^^^^ @@ -4025,10 +4295,24 @@ This section lists supported actions and their attributes, if any. - ``dscp_value {unsigned}``: The new DSCP value to be set -- ``shared``: Use shared action created via - ``flow shared_action {port_id} create`` +- ``indirect``: Use indirect action created via + ``flow indirect_action {port_id} create`` + + - ``indirect_action_id {unsigned}``: Indirect action ID to use + +- ``color``: Color the packet to reflect the meter color result + + - ``type {value}``: Set color type with specified value(green/yellow/red) - - ``shared_action_id {unsigned}``: Shared action ID to use +- ``port_representor``: at embedded switch level, send matching traffic to + the given ethdev + + - ``port_id {unsigned}``: ethdev port ID + +- ``represented_port``: at embedded switch level, send matching traffic to + the entity represented by the given ethdev + + - ``ethdev_port_id {unsigned}``: ethdev port ID Destroying flow rules ~~~~~~~~~~~~~~~~~~~~~ @@ -4319,113 +4603,117 @@ If attach ``destroy`` parameter, the command will destroy all the list aged flow testpmd> flow aged 0 Port 0 total aged flows: 0 -Creating shared actions -~~~~~~~~~~~~~~~~~~~~~~~ -``flow shared_action {port_id} create`` creates shared action with optional -shared action ID. It is bound to ``rte_flow_shared_action_create()``:: +Creating indirect actions +~~~~~~~~~~~~~~~~~~~~~~~~~ - flow shared_action {port_id} create [action_id {shared_action_id}] - [ingress] [egress] action {action} / end +``flow indirect_action {port_id} create`` creates indirect action with optional +indirect action ID. It is bound to ``rte_flow_action_handle_create()``:: + + flow indirect_action {port_id} create [action_id {indirect_action_id}] + [ingress] [egress] [transfer] action {action} / end If successful, it will show:: - Shared action #[...] created + Indirect action #[...] created -Otherwise, it will complain either that shared action already exists or that +Otherwise, it will complain either that indirect action already exists or that some error occurred:: - Shared action #[...] is already assigned, delete it first + Indirect action #[...] is already assigned, delete it first :: Caught error type [...] ([...]): [...] -Create shared rss action with id 100 to queues 1 and 2 on port 0:: +Create indirect rss action with id 100 to queues 1 and 2 on port 0:: - testpmd> flow shared_action 0 create action_id 100 \ + testpmd> flow indirect_action 0 create action_id 100 \ ingress action rss queues 1 2 end / end -Create shared rss action with id assigned by testpmd to queues 1 and 2 on +Create indirect rss action with id assigned by testpmd to queues 1 and 2 on port 0:: - testpmd> flow shared_action 0 create action_id \ + testpmd> flow indirect_action 0 create action_id \ ingress action rss queues 0 1 end / end -Updating shared actions -~~~~~~~~~~~~~~~~~~~~~~~ -``flow shared_action {port_id} update`` updates configuration of the shared -action from its shared action ID (as returned by -``flow shared_action {port_id} create``). It is bound to -``rte_flow_shared_action_update()``:: +Updating indirect actions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flow indirect_action {port_id} update`` updates configuration of the indirect +action from its indirect action ID (as returned by +``flow indirect_action {port_id} create``). It is bound to +``rte_flow_action_handle_update()``:: - flow shared_action {port_id} update {shared_action_id} + flow indirect_action {port_id} update {indirect_action_id} action {action} / end If successful, it will show:: - Shared action #[...] updated + Indirect action #[...] updated -Otherwise, it will complain either that shared action not found or that some +Otherwise, it will complain either that indirect action not found or that some error occurred:: - Failed to find shared action #[...] on port [...] + Failed to find indirect action #[...] on port [...] :: Caught error type [...] ([...]): [...] -Update shared rss action having id 100 on port 0 with rss to queues 0 and 3 +Update indirect rss action having id 100 on port 0 with rss to queues 0 and 3 (in create example above rss queues were 1 and 2):: - testpmd> flow shared_action 0 update 100 action rss queues 0 3 end / end + testpmd> flow indirect_action 0 update 100 action rss queues 0 3 end / end -Destroying shared actions -~~~~~~~~~~~~~~~~~~~~~~~~~ -``flow shared_action {port_id} update`` destroys one or more shared actions -from their shared action IDs (as returned by -``flow shared_action {port_id} create``). It is bound to -``rte_flow_shared_action_destroy()``:: +Destroying indirect actions +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``flow indirect_action {port_id} destroy`` destroys one or more indirect actions +from their indirect action IDs (as returned by +``flow indirect_action {port_id} create``). It is bound to +``rte_flow_action_handle_destroy()``:: - flow shared_action {port_id} destroy action_id {shared_action_id} [...] + flow indirect_action {port_id} destroy action_id {indirect_action_id} [...] If successful, it will show:: - Shared action #[...] destroyed + Indirect action #[...] destroyed -It does not report anything for shared action IDs that do not exist. -The usual error message is shown when a shared action cannot be destroyed:: +It does not report anything for indirect action IDs that do not exist. +The usual error message is shown when a indirect action cannot be destroyed:: Caught error type [...] ([...]): [...] -Destroy shared actions having id 100 & 101:: +Destroy indirect actions having id 100 & 101:: - testpmd> flow shared_action 0 destroy action_id 100 action_id 101 + testpmd> flow indirect_action 0 destroy action_id 100 action_id 101 -Query shared actions -~~~~~~~~~~~~~~~~~~~~ -``flow shared_action {port_id} query`` queries the shared action from its -shared action ID (as returned by ``flow shared_action {port_id} create``). -It is bound to ``rte_flow_shared_action_query()``:: +Query indirect actions +~~~~~~~~~~~~~~~~~~~~~~ - flow shared_action {port_id} query {shared_action_id} +``flow indirect_action {port_id} query`` queries the indirect action from its +indirect action ID (as returned by ``flow indirect_action {port_id} create``). +It is bound to ``rte_flow_action_handle_query()``:: -Currently only rss shared action supported. If successful, it will show:: + flow indirect_action {port_id} query {indirect_action_id} - Shared RSS action: +Currently only rss indirect action supported. If successful, it will show:: + + Indirect RSS action: refs:[...] -Otherwise, it will complain either that shared action not found or that some +Otherwise, it will complain either that indirect action not found or that some error occurred:: - Failed to find shared action #[...] on port [...] + Failed to find indirect action #[...] on port [...] :: Caught error type [...] ([...]): [...] -Query shared action having id 100:: +Query indirect action having id 100:: - testpmd> flow shared_action 0 query 100 + testpmd> flow indirect_action 0 query 100 Sample QinQ flow rules ~~~~~~~~~~~~~~~~~~~~~~ @@ -4433,14 +4721,14 @@ Sample QinQ flow rules Before creating QinQ rule(s) the following commands should be issued to enable QinQ:: testpmd> port stop 0 - testpmd> vlan set qinq_strip on 0 + testpmd> vlan set extend on 0 The above command sets the inner and outer TPID's to 0x8100. To change the TPID's the following commands should be used:: - testpmd> vlan set outer tpid 0xa100 0 - testpmd> vlan set inner tpid 0x9100 0 + testpmd> vlan set outer tpid 0x88A8 0 + testpmd> vlan set inner tpid 0x8100 0 testpmd> port start 0 Validate and create a QinQ rule on port 0 to steer traffic to a VF queue in a VM. @@ -4773,7 +5061,7 @@ Sample Raw encapsulation rule Raw encapsulation configuration can be set by the following commands -Eecapsulating VxLAN:: +Encapsulating VxLAN:: testpmd> set raw_encap 4 eth src is 10:11:22:33:44:55 / vlan tci is 1 inner_type is 0x0800 / ipv4 / udp dst is 4789 / vxlan vni @@ -4835,6 +5123,190 @@ if seid is set):: testpmd> flow create 0 ingress pattern eth / ipv6 / pfcp s_field is 1 seid is 1 / end actions queue index 3 / end +Sample Sampling/Mirroring rules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sample/Mirroring rules can be set by the following commands + +NIC-RX Sampling rule, the matched ingress packets and sent to the queue 1, +and 50% packets are duplicated and marked with 0x1234 and sent to queue 0. + +:: + + testpmd> set sample_actions 0 mark id 0x1234 / queue index 0 / end + testpmd> flow create 0 ingress group 1 pattern eth / end actions + sample ratio 2 index 0 / queue index 1 / end + +Mirroring rule with port representors (with "transfer" attribute), the matched +ingress packets with encapsulation header are sent to port id 0, and also +mirrored the packets and sent to port id 2. + +:: + + testpmd> set sample_actions 0 port_id id 2 / end + testpmd> flow create 1 ingress transfer pattern eth / end actions + sample ratio 1 index 0 / raw_encap / port_id id 0 / end + +Mirroring rule with port representors (with "transfer" attribute), the matched +ingress packets are sent to port id 2, and also mirrored the packets with +encapsulation header and sent to port id 0. + +:: + + testpmd> set sample_actions 0 raw_encap / port_id id 0 / end + testpmd> flow create 0 ingress transfer pattern eth / end actions + sample ratio 1 index 0 / port_id id 2 / end + +Mirroring rule with port representors (with "transfer" attribute), the matched +ingress packets are sent to port id 2, and also mirrored the packets with +VXLAN encapsulation header and sent to port id 0. + +:: + + testpmd> set vxlan ip-version ipv4 vni 4 udp-src 4 udp-dst 4 ip-src 127.0.0.1 + ip-dst 128.0.0.1 eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22 + testpmd> set sample_actions 0 vxlan_encap / port_id id 0 / end + testpmd> flow create 0 ingress transfer pattern eth / end actions + sample ratio 1 index 0 / port_id id 2 / end + +Mirroring rule with port representors (with "transfer" attribute), the matched +ingress packets are sent to port id 2, and also mirrored the packets with +NVGRE encapsulation header and sent to port id 0. + +:: + + testpmd> set nvgre ip-version ipv4 tni 4 ip-src 127.0.0.1 ip-dst 128.0.0.1 + eth-src 11:11:11:11:11:11 eth-dst 22:22:22:22:22:22 + testpmd> set sample_actions 0 nvgre_encap / port_id id 0 / end + testpmd> flow create 0 ingress transfer pattern eth / end actions + sample ratio 1 index 0 / port_id id 2 / end + +Sample integrity rules +~~~~~~~~~~~~~~~~~~~~~~ + +Integrity rules can be created by the following commands: + +Integrity rule that forwards valid TCP packets to group 1. +TCP packet integrity is matched with the ``l4_ok`` bit 3. + +:: + + testpmd> flow create 0 ingress + pattern eth / ipv4 / tcp / integrity value mask 8 value spec 8 / end + actions jump group 1 / end + +Integrity rule that forwards invalid packets to application. +General packet integrity is matched with the ``packet_ok`` bit 0. + +:: + + testpmd> flow create 0 ingress pattern integrity value mask 1 value spec 0 / end actions queue index 0 / end + +Sample conntrack rules +~~~~~~~~~~~~~~~~~~~~~~ + +Conntrack rules can be set by the following commands + +Need to construct the connection context with provided information. +In the first table, create a flow rule by using conntrack action and jump to +the next table. In the next table, create a rule to check the state. + +:: + + testpmd> set conntrack com peer 1 is_orig 1 enable 1 live 1 sack 1 cack 0 + last_dir 0 liberal 0 state 1 max_ack_win 7 r_lim 5 last_win 510 + last_seq 2632987379 last_ack 2532480967 last_end 2632987379 + last_index 0x8 + testpmd> set conntrack orig scale 7 fin 0 acked 1 unack_data 0 + sent_end 2632987379 reply_end 2633016339 max_win 28960 + max_ack 2632987379 + testpmd> set conntrack rply scale 7 fin 0 acked 1 unack_data 0 + sent_end 2532480967 reply_end 2532546247 max_win 65280 + max_ack 2532480967 + testpmd> flow indirect_action 0 create ingress action conntrack / end + testpmd> flow create 0 group 3 ingress pattern eth / ipv4 / tcp / end actions indirect 0 / jump group 5 / end + testpmd> flow create 0 group 5 ingress pattern eth / ipv4 / tcp / conntrack is 1 / end actions queue index 5 / end + +Construct the conntrack again with only "is_orig" set to 0 (other fields are +ignored), then use "update" interface to update the direction. Create flow +rules like above for the peer port. + +:: + + testpmd> flow indirect_action 0 update 0 action conntrack_update dir / end + +Sample meter with policy rules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Meter with policy rules can be created by the following commands: + +Need to create policy first and actions are set for green/yellow/red colors. +Create meter with policy id. Create flow with meter id. + +Example for policy with meter color action. The purpose is to color the packet +to reflect the meter color result. +The meter policy action list: ``green -> green, yellow -> yellow, red -> red``. + +:: + + testpmd> add port meter profile srtcm_rfc2697 0 13 21504 2688 0 0 + testpmd> add port meter policy 0 1 g_actions color type green / end y_actions color type yellow / end + r_actions color type red / end + testpmd> create port meter 0 1 13 1 yes 0xffff 0 0 + testpmd> flow create 0 priority 0 ingress group 1 pattern eth / end actions meter mtr_id 1 / end + +Sample L2TPv2 RSS rules +~~~~~~~~~~~~~~~~~~~~~~~ + +L2TPv2 RSS rules can be created by the following commands:: + + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 type control + / end actions rss types l2tpv2 end queues end / end + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / end + actions rss types eth l2-src-only end queues end / end + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / end + actions rss types l2tpv2 end queues end / end + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv4 + / end actions rss types ipv4 end queues end / end + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv6 + / udp / end actions rss types ipv6-udp end queues end / end + testpmd> flow create 0 ingress pattern eth / ipv6 / udp / l2tpv2 / ppp / ipv4 + / tcp / end actions rss types ipv4-tcp end queues end / end + testpmd> flow create 0 ingress pattern eth / ipv6 / udp / l2tpv2 / ppp / ipv6 + / end actions rss types ipv6 end queues end / end + +Sample L2TPv2 FDIR rules +~~~~~~~~~~~~~~~~~~~~~~~~ + +L2TPv2 FDIR rules can be created by the following commands:: + + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 type control + session_id is 0x1111 / end actions queue index 3 / end + testpmd> flow create 0 ingress pattern eth src is 00:00:00:00:00:01 / ipv4 + / udp / l2tpv2 type data / end actions queue index 3 / end + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 type data + session_id is 0x1111 / ppp / end actions queue index 3 / end + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv4 + src is 10.0.0.1 / end actions queue index 3 / end + testpmd> flow create 0 ingress pattern eth / ipv6 / udp / l2tpv2 / ppp / ipv6 + dst is ABAB:910B:6666:3457:8295:3333:1800:2929 / end actions queue index 3 / end + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv4 + / udp src is 22 / end actions queue index 3 / end + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / l2tpv2 / ppp / ipv4 + / tcp dst is 23 / end actions queue index 3 / end + +Sample RAW rule +~~~~~~~~~~~~~~~ + +A RAW rule can be created as following using ``pattern_hex`` key and mask. + +:: + + testpmd> flow create 0 group 0 priority 1 ingress pattern raw relative is 0 search is 0 offset + is 0 limit is 0 pattern_hex spec 00000000000000000000000000000000000000000000000000000a0a0a0a + pattern_hex mask 0000000000000000000000000000000000000000000000000000ffffffff / end actions + queue index 4 / end + BPF Functions -------------- @@ -4890,3 +5362,122 @@ For example to unload BPF filter from TX queue 0, port 0: .. code-block:: console testpmd> bpf-unload tx 0 0 + +Flex Item Functions +------------------- + +The following sections show functions that configure and create flex item object, +create flex pattern and use it in a flow rule. +The commands will use 20 bytes IPv4 header for examples: + +:: + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | ver | IHL | TOS | length | +0 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | identification | flg | frag. offset | +4 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | TTL | protocol | checksum | +8 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | source IP address | +12 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | destination IP address | +16 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + +Create flex item +~~~~~~~~~~~~~~~~ + +Flex item object is created by PMD according to a new header configuration. The +header configuration is compiled by the testpmd and stored in +``rte_flow_item_flex_conf`` type variable. + +:: + + # flow flex_item create + testpmd> flow flex_item init 0 3 ipv4_flex_config.json + port-0: created flex item #3 + +Flex item configuration is kept in external JSON file. +It describes the following header elements: + +**New header length.** + +Specify whether the new header has fixed or variable length and the basic/minimal +header length value. + +If header length is not fixed, header location with a value that completes header +length calculation and scale/offset function must be added. + +Scale function depends on port hardware. + +**Next protocol.** + +Describes location in the new header that specify following network header type. + +**Flow match samples.** + +Describes locations in the new header that will be used in flow rules. + +Number of flow samples and sample maximal length depend of port hardware. + +**Input trigger.** + +Describes preceding network header configuration. + +**Output trigger.** + +Describes conditions that trigger transfer to following network header + +.. code-block:: json + + { + "next_header": { "field_mode": "FIELD_MODE_FIXED", "field_size": 20}, + "next_protocol": {"field_size": 8, "field_base": 72}, + "sample_data": [ + { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 0}, + { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 32}, + { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 64}, + { "field_mode": "FIELD_MODE_FIXED", "field_size": 32, "field_base": 96} + ], + "input_link": [ + {"item": "eth type is 0x0800"}, + {"item": "vlan inner_type is 0x0800"} + ], + "output_link": [ + {"item": "udp", "next": 17}, + {"item": "tcp", "next": 6}, + {"item": "icmp", "next": 1} + ] + } + + +Flex pattern and flow rules +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Flex pattern describe parts of network header that will trigger flex flow item hit in a flow rule. +Flex pattern directly related to flex item samples configuration. +Flex pattern can be shared between ports. + +**Flex pattern and flow rule to match IPv4 version and 20 bytes length** + +:: + + # set flex_pattern is + testpmd> flow flex_item pattern 5 is 45FF + created pattern #5 + + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / flex item is 3 pattern is 5 / end actions mark id 1 / queue index 0 / end + Flow rule #0 created + +**Flex pattern and flow rule to match packets with source address 1.2.3.4** + +:: + + testpmd> flow flex_item pattern 2 spec 45000000000000000000000001020304 mask FF0000000000000000000000FFFFFFFF + created pattern #2 + + testpmd> flow create 0 ingress pattern eth / ipv4 / udp / flex item is 3 pattern is 2 / end actions mark id 1 / queue index 0 / end + Flow rule #0 created