lib/librte_flow_classify/rte_flow_classify.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2017 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_FLOW_CLASSIFY_H_
   6 #define _RTE_FLOW_CLASSIFY_H_
   7
   8 /**
   9  * @file
  10  *
  11  * RTE Flow Classify Library
  12  *
  13  * @b EXPERIMENTAL: this API may change without prior notice
  14  *
  15  * This library provides flow record information with some measured properties.
  16  *
  17  * Application should define the flow and measurement criteria (action) for it.
  18  *
  19  * The Library doesn't maintain any flow records itself, instead flow
  20  * information is returned to upper layer only for given packets.
  21  *
  22  * It is application's responsibility to call rte_flow_classifier_query()
  23  * for a burst of packets, just after receiving them or before transmitting
  24  * them.
  25  * Application should provide the flow type interested in, measurement to apply
  26  * to that flow in rte_flow_classify_table_entry_add() API, and should provide
  27  * the rte_flow_classifier object and storage to put results in for the
  28  * rte_flow_classifier_query() API.
  29  *
  30  *  Usage:
  31  *  - application calls rte_flow_classifier_create() to create an
  32  *    rte_flow_classifier object.
  33  *  - application calls rte_flow_classify_table_create() to create a table
  34  *    in the rte_flow_classifier object.
  35  *  - application calls rte_flow_classify_table_entry_add() to add a rule to
  36  *    the table in the rte_flow_classifier object.
  37  *  - application calls rte_flow_classifier_query() in a polling manner,
  38  *    preferably after rte_eth_rx_burst(). This will cause the library to
  39  *    match packet information to flow information with some measurements.
  40  *  - rte_flow_classifier object can be destroyed when it is no longer needed
  41  *    with rte_flow_classifier_free()
  42  */
  43
  44 #include <rte_compat.h>
  45 #include <rte_common.h>
  46 #include <rte_ethdev.h>
  47 #include <rte_ether.h>
  48 #include <rte_flow.h>
  49 #include <rte_acl.h>
  50 #include <rte_table_acl.h>
  51
  52 #ifdef __cplusplus
  53 extern "C" {
  54 #endif
  55
  56 extern int librte_flow_classify_logtype;
  57
  58 #define RTE_FLOW_CLASSIFY_LOG(level, ...) \
  59         rte_log(RTE_LOG_ ## level, \
  60                 librte_flow_classify_logtype, \
  61                 RTE_FMT("%s(): " RTE_FMT_HEAD(__VA_ARGS__,), \
  62                         __func__, \
  63                         RTE_FMT_TAIL(__VA_ARGS__,)))
  64
  65 #ifndef RTE_FLOW_CLASSIFY_TABLE_MAX
  66 #define RTE_FLOW_CLASSIFY_TABLE_MAX             32
  67 #endif
  68
  69 /** Opaque data type for flow classifier */
  70 struct rte_flow_classifier;
  71
  72 /** Opaque data type for flow classify rule */
  73 struct rte_flow_classify_rule;
  74
  75 /** Flow classify rule type */
  76 enum rte_flow_classify_rule_type {
  77         /** no type */
  78         RTE_FLOW_CLASSIFY_RULE_TYPE_NONE,
  79         /** IPv4 5tuple type */
  80         RTE_FLOW_CLASSIFY_RULE_TYPE_IPV4_5TUPLE,
  81 };
  82
  83 /** Flow classify table type */
  84 enum rte_flow_classify_table_type {
  85         /** No type */
  86         RTE_FLOW_CLASSIFY_TABLE_TYPE_NONE = 1 << 0,
  87         /** ACL IP4 5TUPLE */
  88         RTE_FLOW_CLASSIFY_TABLE_ACL_IP4_5TUPLE = 1 << 1,
  89         /** ACL VLAN IP4 5TUPLE */
  90         RTE_FLOW_CLASSIFY_TABLE_ACL_VLAN_IP4_5TUPLE = 1 << 2,
  91         /** ACL QinQ IP4 5TUPLE */
  92         RTE_FLOW_CLASSIFY_TABLE_ACL_QINQ_IP4_5TUPLE = 1 << 3,
  93
  94 };
  95
  96 /** Parameters for flow classifier creation */
  97 struct rte_flow_classifier_params {
  98         /** flow classifier name */
  99         const char *name;
 100
 101         /** CPU socket ID where memory for the flow classifier and its */
 102         /** elements (tables) should be allocated */
 103         int socket_id;
 104 };
 105
 106 /** Parameters for table creation */
 107 struct rte_flow_classify_table_params {
 108         /** Table operations (specific to each table type) */
 109         struct rte_table_ops *ops;
 110
 111         /** Opaque param to be passed to the table create operation */
 112         void *arg_create;
 113
 114         /** Classifier table type */
 115         enum rte_flow_classify_table_type type;
 116 };
 117
 118 /** IPv4 5-tuple data */
 119 struct rte_flow_classify_ipv4_5tuple {
 120         uint32_t dst_ip;         /**< Destination IP address in big endian. */
 121         uint32_t dst_ip_mask;    /**< Mask of destination IP address. */
 122         uint32_t src_ip;         /**< Source IP address in big endian. */
 123         uint32_t src_ip_mask;    /**< Mask of destination IP address. */
 124         uint16_t dst_port;       /**< Destination port in big endian. */
 125         uint16_t dst_port_mask;  /**< Mask of destination port. */
 126         uint16_t src_port;       /**< Source Port in big endian. */
 127         uint16_t src_port_mask;  /**< Mask of source port. */
 128         uint8_t proto;           /**< L4 protocol. */
 129         uint8_t proto_mask;      /**< Mask of L4 protocol. */
 130 };
 131
 132 /**
 133  * Flow stats
 134  *
 135  * For the count action, stats can be returned by the query API.
 136  *
 137  * Storage for stats is provided by application.
 138  */
 139 struct rte_flow_classify_stats {
 140         void *stats;
 141 };
 142
 143 struct rte_flow_classify_ipv4_5tuple_stats {
 144         /** count of packets that match IPv4 5tuple pattern */
 145         uint64_t counter1;
 146         /** IPv4 5tuple data */
 147         struct rte_flow_classify_ipv4_5tuple ipv4_5tuple;
 148 };
 149
 150 /**
 151  * Flow classifier create
 152  *
 153  * @param params
 154  *   Parameters for flow classifier creation
 155  * @return
 156  *   Handle to flow classifier instance on success or NULL otherwise
 157  */
 158 struct rte_flow_classifier * __rte_experimental
 159 rte_flow_classifier_create(struct rte_flow_classifier_params *params);
 160
 161 /**
 162  * Flow classifier free
 163  *
 164  * @param cls
 165  *   Handle to flow classifier instance
 166  * @return
 167  *   0 on success, error code otherwise
 168  */
 169 int __rte_experimental
 170 rte_flow_classifier_free(struct rte_flow_classifier *cls);
 171
 172 /**
 173  * Flow classify table create
 174  *
 175  * @param cls
 176  *   Handle to flow classifier instance
 177  * @param params
 178  *   Parameters for flow_classify table creation
 179  * @return
 180  *   0 on success, error code otherwise
 181  */
 182 int __rte_experimental
 183 rte_flow_classify_table_create(struct rte_flow_classifier *cls,
 184                 struct rte_flow_classify_table_params *params);
 185
 186 /**
 187  * Flow classify validate
 188  *
 189  * @param cls
 190  *   Handle to flow classifier instance
 191  * @param[in] attr
 192  *   Flow rule attributes
 193  * @param[in] pattern
 194  *   Pattern specification (list terminated by the END pattern item).
 195  * @param[in] actions
 196  *   Associated actions (list terminated by the END pattern item).
 197  * @param[out] error
 198  *   Perform verbose error reporting if not NULL. Structure
 199  *   initialised in case of error only.
 200  * @return
 201  *   0 on success, error code otherwise
 202  */
 203 int __rte_experimental
 204 rte_flow_classify_validate(struct rte_flow_classifier *cls,
 205                 const struct rte_flow_attr *attr,
 206                 const struct rte_flow_item pattern[],
 207                 const struct rte_flow_action actions[],
 208                 struct rte_flow_error *error);
 209
 210 /**
 211  * Add a flow classify rule to the flow_classifer table.
 212  *
 213  * @param[in] cls
 214  *   Flow classifier handle
 215  * @param[in] attr
 216  *   Flow rule attributes
 217  * @param[in] pattern
 218  *   Pattern specification (list terminated by the END pattern item).
 219  * @param[in] actions
 220  *   Associated actions (list terminated by the END pattern item).
 221  * @param[out] key_found
 222  *  returns 1 if rule present already, 0 otherwise.
 223  * @param[out] error
 224  *   Perform verbose error reporting if not NULL. Structure
 225  *   initialised in case of error only.
 226  * @return
 227  *   A valid handle in case of success, NULL otherwise.
 228  */
 229 struct rte_flow_classify_rule * __rte_experimental
 230 rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
 231                 const struct rte_flow_attr *attr,
 232                 const struct rte_flow_item pattern[],
 233                 const struct rte_flow_action actions[],
 234                 int *key_found,
 235                 struct rte_flow_error *error);
 236
 237 /**
 238  * Delete a flow classify rule from the flow_classifer table.
 239  *
 240  * @param[in] cls
 241  *   Flow classifier handle
 242  * @param[in] rule
 243  *   Flow classify rule
 244  * @return
 245  *   0 on success, error code otherwise.
 246  */
 247 int __rte_experimental
 248 rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
 249                 struct rte_flow_classify_rule *rule);
 250
 251 /**
 252  * Query flow classifier for given rule.
 253  *
 254  * @param[in] cls
 255  *   Flow classifier handle
 256  * @param[in] pkts
 257  *   Pointer to packets to process
 258  * @param[in] nb_pkts
 259  *   Number of packets to process
 260  * @param[in] rule
 261  *   Flow classify rule
 262  * @param[in] stats
 263  *   Flow classify stats
 264  *
 265  * @return
 266  *   0 on success, error code otherwise.
 267  */
 268 int __rte_experimental
 269 rte_flow_classifier_query(struct rte_flow_classifier *cls,
 270                 struct rte_mbuf **pkts,
 271                 const uint16_t nb_pkts,
 272                 struct rte_flow_classify_rule *rule,
 273                 struct rte_flow_classify_stats *stats);
 274
 275 #ifdef __cplusplus
 276 }
 277 #endif
 278
 279 #endif /* _RTE_FLOW_CLASSIFY_H_ */