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_ */ 289