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_flow.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, ...) \ 57 rte_log(RTE_LOG_ ## level, \ 58 librte_flow_classify_logtype, \ 59 RTE_FMT("%s(): " RTE_FMT_HEAD(__VA_ARGS__,), \ 60 __func__, \ 61 RTE_FMT_TAIL(__VA_ARGS__,))) 62 63 #ifndef RTE_FLOW_CLASSIFY_TABLE_MAX 64 #define RTE_FLOW_CLASSIFY_TABLE_MAX 32 65 #endif 66 67 /** Opaque data type for flow classifier */ 68 struct rte_flow_classifier; 69 70 /** Opaque data type for flow classify rule */ 71 struct rte_flow_classify_rule; 72 73 /** Flow classify rule type */ 74 enum rte_flow_classify_rule_type { 75 /** no type */ 76 RTE_FLOW_CLASSIFY_RULE_TYPE_NONE, 77 /** IPv4 5tuple type */ 78 RTE_FLOW_CLASSIFY_RULE_TYPE_IPV4_5TUPLE, 79 }; 80 81 /** Flow classify table type */ 82 enum rte_flow_classify_table_type { 83 /** No type */ 84 RTE_FLOW_CLASSIFY_TABLE_TYPE_NONE = 1 << 0, 85 /** ACL IP4 5TUPLE */ 86 RTE_FLOW_CLASSIFY_TABLE_ACL_IP4_5TUPLE = 1 << 1, 87 /** ACL VLAN IP4 5TUPLE */ 88 RTE_FLOW_CLASSIFY_TABLE_ACL_VLAN_IP4_5TUPLE = 1 << 2, 89 /** ACL QinQ IP4 5TUPLE */ 90 RTE_FLOW_CLASSIFY_TABLE_ACL_QINQ_IP4_5TUPLE = 1 << 3, 91 92 }; 93 94 /** Parameters for flow classifier creation */ 95 struct rte_flow_classifier_params { 96 /** flow classifier name */ 97 const char *name; 98 99 /** CPU socket ID where memory for the flow classifier and its */ 100 /** elements (tables) should be allocated */ 101 int socket_id; 102 }; 103 104 /** Parameters for table creation */ 105 struct rte_flow_classify_table_params { 106 /** Table operations (specific to each table type) */ 107 struct rte_table_ops *ops; 108 109 /** Opaque param to be passed to the table create operation */ 110 void *arg_create; 111 112 /** Classifier table type */ 113 enum rte_flow_classify_table_type type; 114 }; 115 116 /** IPv4 5-tuple data */ 117 struct rte_flow_classify_ipv4_5tuple { 118 uint32_t dst_ip; /**< Destination IP address in big endian. */ 119 uint32_t dst_ip_mask; /**< Mask of destination IP address. */ 120 uint32_t src_ip; /**< Source IP address in big endian. */ 121 uint32_t src_ip_mask; /**< Mask of destination IP address. */ 122 uint16_t dst_port; /**< Destination port in big endian. */ 123 uint16_t dst_port_mask; /**< Mask of destination port. */ 124 uint16_t src_port; /**< Source Port in big endian. */ 125 uint16_t src_port_mask; /**< Mask of source port. */ 126 uint8_t proto; /**< L4 protocol. */ 127 uint8_t proto_mask; /**< Mask of L4 protocol. */ 128 }; 129 130 /** 131 * Flow stats 132 * 133 * For the count action, stats can be returned by the query API. 134 * 135 * Storage for stats is provided by application. 136 */ 137 struct rte_flow_classify_stats { 138 void *stats; 139 }; 140 141 struct rte_flow_classify_ipv4_5tuple_stats { 142 /** count of packets that match IPv4 5tuple pattern */ 143 uint64_t counter1; 144 /** IPv4 5tuple data */ 145 struct rte_flow_classify_ipv4_5tuple ipv4_5tuple; 146 }; 147 148 /** 149 * Flow classifier create 150 * 151 * @param params 152 * Parameters for flow classifier creation 153 * @return 154 * Handle to flow classifier instance on success or NULL otherwise 155 */ 156 __rte_experimental 157 struct rte_flow_classifier * 158 rte_flow_classifier_create(struct rte_flow_classifier_params *params); 159 160 /** 161 * Flow classifier free 162 * 163 * @param cls 164 * Handle to flow classifier instance 165 * @return 166 * 0 on success, error code otherwise 167 */ 168 __rte_experimental 169 int 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 __rte_experimental 183 int 184 rte_flow_classify_table_create(struct rte_flow_classifier *cls, 185 struct rte_flow_classify_table_params *params); 186 187 /** 188 * Flow classify validate 189 * 190 * @param cls 191 * Handle to flow classifier instance 192 * @param[in] attr 193 * Flow rule attributes 194 * @param[in] pattern 195 * Pattern specification (list terminated by the END pattern item). 196 * @param[in] actions 197 * Associated actions (list terminated by the END pattern item). 198 * @param[out] error 199 * Perform verbose error reporting if not NULL. Structure 200 * initialised in case of error only. 201 * @return 202 * 0 on success, error code otherwise 203 */ 204 __rte_experimental 205 int 206 rte_flow_classify_validate(struct rte_flow_classifier *cls, 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 * Add a flow classify rule to the flow_classifier table. 214 * 215 * @param[in] cls 216 * Flow classifier handle 217 * @param[in] attr 218 * Flow rule attributes 219 * @param[in] pattern 220 * Pattern specification (list terminated by the END pattern item). 221 * @param[in] actions 222 * Associated actions (list terminated by the END pattern item). 223 * @param[out] key_found 224 * returns 1 if rule present already, 0 otherwise. 225 * @param[out] error 226 * Perform verbose error reporting if not NULL. Structure 227 * initialised in case of error only. 228 * @return 229 * A valid handle in case of success, NULL otherwise. 230 */ 231 __rte_experimental 232 struct rte_flow_classify_rule * 233 rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls, 234 const struct rte_flow_attr *attr, 235 const struct rte_flow_item pattern[], 236 const struct rte_flow_action actions[], 237 int *key_found, 238 struct rte_flow_error *error); 239 240 /** 241 * Delete a flow classify rule from the flow_classifier table. 242 * 243 * @param[in] cls 244 * Flow classifier handle 245 * @param[in] rule 246 * Flow classify rule 247 * @return 248 * 0 on success, error code otherwise. 249 */ 250 __rte_experimental 251 int 252 rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls, 253 struct rte_flow_classify_rule *rule); 254 255 /** 256 * Query flow classifier for given rule. 257 * 258 * @param[in] cls 259 * Flow classifier handle 260 * @param[in] pkts 261 * Pointer to packets to process 262 * @param[in] nb_pkts 263 * Number of packets to process 264 * @param[in] rule 265 * Flow classify rule 266 * @param[in] stats 267 * Flow classify stats 268 * 269 * @return 270 * 0 on success, error code otherwise. 271 */ 272 __rte_experimental 273 int 274 rte_flow_classifier_query(struct rte_flow_classifier *cls, 275 struct rte_mbuf **pkts, 276 const uint16_t nb_pkts, 277 struct rte_flow_classify_rule *rule, 278 struct rte_flow_classify_stats *stats); 279 280 #ifdef __cplusplus 281 } 282 #endif 283 284 #endif /* _RTE_FLOW_CLASSIFY_H_ */ 285