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