net/mlx5: support flow director

[dpdk.git] / doc / guides / prog_guide / packet_classif_access_ctrl.rst

diff --git a/doc/guides/prog_guide/packet_classif_access_ctrl.rst b/doc/guides/prog_guide/packet_classif_access_ctrl.rst
index 210b020..a6bee9b 100644 (file)
--- a/doc/guides/prog_guide/packet_classif_access_ctrl.rst
+++ b/doc/guides/prog_guide/packet_classif_access_ctrl.rst
@@ -246,6 +246,74 @@ A typical example of such an IPv6 2-tuple rule is a follows:
 Any IPv6 packets with protocol ID 6 (TCP), and source address inside the range
 [2001:db8:1234:0000:0000:0000:0000:0000 - 2001:db8:1234:ffff:ffff:ffff:ffff:ffff] matches the above rule.
 
+In the following example the last element of the search key is 8-bit long.
+So it is a case where the 4 consecutive bytes of an input field are not fully occupied.
+The structure for the classification is:
+
+.. code-block:: c
+
+    struct acl_key {
+        uint8_t ip_proto;
+        uint32_t ip_src;
+        uint32_t ip_dst;
+        uint8_t tos;      /*< This is partially using a 32-bit input element */
+    };
+
+The following array of field definitions can be used:
+
+.. code-block:: c
+
+    struct rte_acl_field_def ipv4_defs[4] = {
+        /* first input field - always one byte long. */
+        {
+            .type = RTE_ACL_FIELD_TYPE_BITMASK,
+            .size = sizeof (uint8_t),
+            .field_index = 0,
+            .input_index = 0,
+            .offset = offsetof (struct acl_key, ip_proto),
+        },
+
+        /* next input field (IPv4 source address) - 4 consecutive bytes. */
+        {
+            .type = RTE_ACL_FIELD_TYPE_MASK,
+            .size = sizeof (uint32_t),
+            .field_index = 1,
+            .input_index = 1,
+           .offset = offsetof (struct acl_key, ip_src),
+        },
+
+        /* next input field (IPv4 destination address) - 4 consecutive bytes. */
+        {
+            .type = RTE_ACL_FIELD_TYPE_MASK,
+            .size = sizeof (uint32_t),
+            .field_index = 2,
+            .input_index = 2,
+           .offset = offsetof (struct acl_key, ip_dst),
+        },
+
+        /*
+         * Next element of search key (Type of Service) is indeed 1 byte long.
+         * Anyway we need to allocate all the 4 consecutive bytes for it.
+         */
+        {
+            .type = RTE_ACL_FIELD_TYPE_BITMASK,
+            .size = sizeof (uint32_t), /* All the 4 consecutive bytes are allocated */
+            .field_index = 3,
+            .input_index = 3,
+            .offset = offsetof (struct acl_key, tos),
+        },
+    };
+
+A typical example of such an IPv4 4-tuple rule is as follows:
+
+::
+
+    source addr/mask  destination addr/mask  tos/mask protocol/mask
+    192.168.1.0/24    192.168.2.31/32        1/0xff   6/0xff
+
+Any IPv4 packets with protocol ID 6 (TCP), source address 192.168.1.[0-255], destination address 192.168.2.31,
+ToS 1 matches the above rule.
+
 When creating a set of rules, for each rule, additional information must be supplied also:
 
 *   **priority**: A weight to measure the priority of the rules (higher is better).
@@ -261,8 +329,9 @@ When creating a set of rules, for each rule, additional information must be supp
     Each set could be assigned its own category and by combining them into a single database,
     one lookup returns a result for each of the four sets.
 
-*   **userdata**: A user-defined field that could be any value except zero.
+*   **userdata**: A user-defined value.
     For each category, a successful match returns the userdata field of the highest priority matched rule.
+    When no rules match, returned value is zero.
 
 .. note::
 
@@ -281,14 +350,14 @@ for each of them.
 Depending on the rule-set, it might reduce RT memory requirements but might
 increase classification time.
 There is a possibility at build-time to specify maximum memory limit for internal RT structures for given AC context.
-It could be done via **max_size** field of the **rte_acl_config** strucure.
+It could be done via **max_size** field of the **rte_acl_config** structure.
 Setting it to the value greater than zero, instructs rte_acl_build() to:
 
-*   attempt to minimise number of tries in the RT table, but
+*   attempt to minimize number of tries in the RT table, but
 *   make sure that size of RT table wouldn't exceed given value.
 
-Setting it to zero makes rte_acl_build() to use the default behaviour:
-try to minimise size of the RT structures, but doesn't expose any hard limit on it.
+Setting it to zero makes rte_acl_build() to use the default behavior:
+try to minimize size of the RT structures, but doesn't expose any hard limit on it.
 
 That gives the user the ability to decisions about performance/space trade-off.
 For example:
@@ -304,12 +373,12 @@ For example:
      * populated with rules AC context and cfg filled properly.
      */
 
-     /* try to build AC context, with RT strcutures less then 8MB. */
+     /* try to build AC context, with RT structures less then 8MB. */
      cfg.max_size = 0x800000;
      ret = rte_acl_build(acx, &cfg);
 
      /*
-      * RT strcutures can't fit into 8MB for given context.
+      * RT structures can't fit into 8MB for given context.
       * Try to build without exposing any hard limit.
       */
      if (ret == -ERANGE) {