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 __rte_experimental 159 struct rte_flow_classifier * 160 rte_flow_classifier_create(struct rte_flow_classifier_params *params); 161 162 /** 163 * Flow classifier free 164 * 165 * @param cls 166 * Handle to flow classifier instance 167 * @return 168 * 0 on success, error code otherwise 169 */ 170 __rte_experimental 171 int 172 rte_flow_classifier_free(struct rte_flow_classifier *cls); 173 174 /** 175 * Flow classify table create 176 * 177 * @param cls 178 * Handle to flow classifier instance 179 * @param params 180 * Parameters for flow_classify table creation 181 * @return 182 * 0 on success, error code otherwise 183 */ 184 __rte_experimental 185 int 186 rte_flow_classify_table_create(struct rte_flow_classifier *cls, 187 struct rte_flow_classify_table_params *params); 188 189 /** 190 * Flow classify validate 191 * 192 * @param cls 193 * Handle to flow classifier instance 194 * @param[in] attr 195 * Flow rule attributes 196 * @param[in] pattern 197 * Pattern specification (list terminated by the END pattern item). 198 * @param[in] actions 199 * Associated actions (list terminated by the END pattern item). 200 * @param[out] error 201 * Perform verbose error reporting if not NULL. Structure 202 * initialised in case of error only. 203 * @return 204 * 0 on success, error code otherwise 205 */ 206 __rte_experimental 207 int 208 rte_flow_classify_validate(struct rte_flow_classifier *cls, 209 const struct rte_flow_attr *attr, 210 const struct rte_flow_item pattern[], 211 const struct rte_flow_action actions[], 212 struct rte_flow_error *error); 213 214 /** 215 * Add a flow classify rule to the flow_classifier table. 216 * 217 * @param[in] cls 218 * Flow classifier handle 219 * @param[in] attr 220 * Flow rule attributes 221 * @param[in] pattern 222 * Pattern specification (list terminated by the END pattern item). 223 * @param[in] actions 224 * Associated actions (list terminated by the END pattern item). 225 * @param[out] key_found 226 * returns 1 if rule present already, 0 otherwise. 227 * @param[out] error 228 * Perform verbose error reporting if not NULL. Structure 229 * initialised in case of error only. 230 * @return 231 * A valid handle in case of success, NULL otherwise. 232 */ 233 __rte_experimental 234 struct rte_flow_classify_rule * 235 rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls, 236 const struct rte_flow_attr *attr, 237 const struct rte_flow_item pattern[], 238 const struct rte_flow_action actions[], 239 int *key_found, 240 struct rte_flow_error *error); 241 242 /** 243 * Delete a flow classify rule from the flow_classifier table. 244 * 245 * @param[in] cls 246 * Flow classifier handle 247 * @param[in] rule 248 * Flow classify rule 249 * @return 250 * 0 on success, error code otherwise. 251 */ 252 __rte_experimental 253 int 254 rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls, 255 struct rte_flow_classify_rule *rule); 256 257 /** 258 * Query flow classifier for given rule. 259 * 260 * @param[in] cls 261 * Flow classifier handle 262 * @param[in] pkts 263 * Pointer to packets to process 264 * @param[in] nb_pkts 265 * Number of packets to process 266 * @param[in] rule 267 * Flow classify rule 268 * @param[in] stats 269 * Flow classify stats 270 * 271 * @return 272 * 0 on success, error code otherwise. 273 */ 274 __rte_experimental 275 int 276 rte_flow_classifier_query(struct rte_flow_classifier *cls, 277 struct rte_mbuf **pkts, 278 const uint16_t nb_pkts, 279 struct rte_flow_classify_rule *rule, 280 struct rte_flow_classify_stats *stats); 281 282 #ifdef __cplusplus 283 } 284 #endif 285 286 #endif /* _RTE_FLOW_CLASSIFY_H_ */ 287