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_ethdev.h>
  45 #include <rte_ether.h>
  46 #include <rte_flow.h>
  47 #include <rte_acl.h>
  48 #include <rte_table_acl.h>
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 extern int librte_flow_classify_logtype;
  55
  56 #define RTE_FLOW_CLASSIFY_LOG(level, fmt, args...) \
  57 rte_log(RTE_LOG_ ## level, librte_flow_classify_logtype, "%s(): " fmt, \
  58         __func__, ## args)
  59
  60 /** Opaque data type for flow classifier */
  61 struct rte_flow_classifier;
  62
  63 /** Opaque data type for flow classify rule */
  64 struct rte_flow_classify_rule;
  65
  66 /** Flow classify rule type */
  67 enum rte_flow_classify_rule_type {
  68         /** no type */
  69         RTE_FLOW_CLASSIFY_RULE_TYPE_NONE,
  70         /** IPv4 5tuple type */
  71         RTE_FLOW_CLASSIFY_RULE_TYPE_IPV4_5TUPLE,
  72 };
  73
  74 /** Flow classify table type */
  75 enum rte_flow_classify_table_type {
  76         /** no type */
  77         RTE_FLOW_CLASSIFY_TABLE_TYPE_NONE,
  78         /** ACL type */
  79         RTE_FLOW_CLASSIFY_TABLE_TYPE_ACL,
  80 };
  81
  82 /**
  83  * Maximum number of tables allowed for any Flow Classifier instance.
  84  * The value of this parameter cannot be changed.
  85  */
  86 #define RTE_FLOW_CLASSIFY_TABLE_MAX  64
  87
  88 /** Parameters for flow classifier creation */
  89 struct rte_flow_classifier_params {
  90         /** flow classifier name */
  91         const char *name;
  92
  93         /** CPU socket ID where memory for the flow classifier and its */
  94         /** elements (tables) should be allocated */
  95         int socket_id;
  96
  97         /** Table type */
  98         enum rte_flow_classify_table_type type;
  99 };
 100
 101 /** Parameters for table creation */
 102 struct rte_flow_classify_table_params {
 103         /** Table operations (specific to each table type) */
 104         struct rte_table_ops *ops;
 105
 106         /** Opaque param to be passed to the table create operation */
 107         void *arg_create;
 108 };
 109
 110 /** IPv4 5-tuple data */
 111 struct rte_flow_classify_ipv4_5tuple {
 112         uint32_t dst_ip;         /**< Destination IP address in big endian. */
 113         uint32_t dst_ip_mask;    /**< Mask of destination IP address. */
 114         uint32_t src_ip;         /**< Source IP address in big endian. */
 115         uint32_t src_ip_mask;    /**< Mask of destination IP address. */
 116         uint16_t dst_port;       /**< Destination port in big endian. */
 117         uint16_t dst_port_mask;  /**< Mask of destination port. */
 118         uint16_t src_port;       /**< Source Port in big endian. */
 119         uint16_t src_port_mask;  /**< Mask of source port. */
 120         uint8_t proto;           /**< L4 protocol. */
 121         uint8_t proto_mask;      /**< Mask of L4 protocol. */
 122 };
 123
 124 /**
 125  * Flow stats
 126  *
 127  * For the count action, stats can be returned by the query API.
 128  *
 129  * Storage for stats is provided by application.
 130  */
 131 struct rte_flow_classify_stats {
 132         void *stats;
 133 };
 134
 135 struct rte_flow_classify_ipv4_5tuple_stats {
 136         /** count of packets that match IPv4 5tuple pattern */
 137         uint64_t counter1;
 138         /** IPv4 5tuple data */
 139         struct rte_flow_classify_ipv4_5tuple ipv4_5tuple;
 140 };
 141
 142 /**
 143  * Flow classifier create
 144  *
 145  * @param params
 146  *   Parameters for flow classifier creation
 147  * @return
 148  *   Handle to flow classifier instance on success or NULL otherwise
 149  */
 150 struct rte_flow_classifier *
 151 rte_flow_classifier_create(struct rte_flow_classifier_params *params);
 152
 153 /**
 154  * Flow classifier free
 155  *
 156  * @param cls
 157  *   Handle to flow classifier instance
 158  * @return
 159  *   0 on success, error code otherwise
 160  */
 161 int
 162 rte_flow_classifier_free(struct rte_flow_classifier *cls);
 163
 164 /**
 165  * Flow classify table create
 166  *
 167  * @param cls
 168  *   Handle to flow classifier instance
 169  * @param params
 170  *   Parameters for flow_classify table creation
 171  * @param table_id
 172  *   Table ID. Valid only within the scope of table IDs of the current
 173  *   classifier. Only returned after a successful invocation.
 174  * @return
 175  *   0 on success, error code otherwise
 176  */
 177 int
 178 rte_flow_classify_table_create(struct rte_flow_classifier *cls,
 179                 struct rte_flow_classify_table_params *params,
 180                 uint32_t *table_id);
 181
 182 /**
 183  * Add a flow classify rule to the flow_classifer table.
 184  *
 185  * @param[in] cls
 186  *   Flow classifier handle
 187  * @param[in] table_id
 188  *   id of table
 189  * @param[out] key_found
 190  *  returns 1 if key present already, 0 otherwise.
 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  *   A valid handle in case of success, NULL otherwise.
 202  */
 203 struct rte_flow_classify_rule *
 204 rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls,
 205                 uint32_t table_id,
 206                 int *key_found,
 207                 const struct rte_flow_attr *attr,
 208                 const struct rte_flow_item pattern[],
 209                 const struct rte_flow_action actions[],
 210                 struct rte_flow_error *error);
 211
 212 /**
 213  * Delete a flow classify rule from the flow_classifer table.
 214  *
 215  * @param[in] cls
 216  *   Flow classifier handle
 217  * @param[in] table_id
 218  *   id of table
 219  * @param[in] rule
 220  *   Flow classify rule
 221  * @return
 222  *   0 on success, error code otherwise.
 223  */
 224 int
 225 rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls,
 226                 uint32_t table_id,
 227                 struct rte_flow_classify_rule *rule);
 228
 229 /**
 230  * Query flow classifier for given rule.
 231  *
 232  * @param[in] cls
 233  *   Flow classifier handle
 234  * @param[in] table_id
 235  *   id of table
 236  * @param[in] pkts
 237  *   Pointer to packets to process
 238  * @param[in] nb_pkts
 239  *   Number of packets to process
 240  * @param[in] rule
 241  *   Flow classify rule
 242  * @param[in] stats
 243  *   Flow classify stats
 244  *
 245  * @return
 246  *   0 on success, error code otherwise.
 247  */
 248 int
 249 rte_flow_classifier_query(struct rte_flow_classifier *cls,
 250                 uint32_t table_id,
 251                 struct rte_mbuf **pkts,
 252                 const uint16_t nb_pkts,
 253                 struct rte_flow_classify_rule *rule,
 254                 struct rte_flow_classify_stats *stats);
 255
 256 #ifdef __cplusplus
 257 }
 258 #endif
 259
 260 #endif /* _RTE_FLOW_CLASSIFY_H_ */