1 /*- 2 * BSD LICENSE 3 * 4 * Copyright(c) 2017 Intel Corporation. All rights reserved. 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * * Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * * Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * * Neither the name of Intel Corporation nor the names of its 18 * contributors may be used to endorse or promote products derived 19 * from this software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 */ 33 34 #ifndef _RTE_FLOW_CLASSIFY_H_ 35 #define _RTE_FLOW_CLASSIFY_H_ 36 37 /** 38 * @file 39 * 40 * RTE Flow Classify Library 41 * 42 * @b EXPERIMENTAL: this API may change without prior notice 43 * 44 * This library provides flow record information with some measured properties. 45 * 46 * Application should define the flow and measurement criteria (action) for it. 47 * 48 * The Library doesn't maintain any flow records itself, instead flow 49 * information is returned to upper layer only for given packets. 50 * 51 * It is application's responsibility to call rte_flow_classifier_query() 52 * for a burst of packets, just after receiving them or before transmitting 53 * them. 54 * Application should provide the flow type interested in, measurement to apply 55 * to that flow in rte_flow_classify_table_entry_add() API, and should provide 56 * the rte_flow_classifier object and storage to put results in for the 57 * rte_flow_classifier_query() API. 58 * 59 * Usage: 60 * - application calls rte_flow_classifier_create() to create an 61 * rte_flow_classifier object. 62 * - application calls rte_flow_classify_table_create() to create a table 63 * in the rte_flow_classifier object. 64 * - application calls rte_flow_classify_table_entry_add() to add a rule to 65 * the table in the rte_flow_classifier object. 66 * - application calls rte_flow_classifier_query() in a polling manner, 67 * preferably after rte_eth_rx_burst(). This will cause the library to 68 * match packet information to flow information with some measurements. 69 * - rte_flow_classifier object can be destroyed when it is no longer needed 70 * with rte_flow_classifier_free() 71 */ 72 73 #include <rte_common.h> 74 #include <rte_ethdev.h> 75 #include <rte_ether.h> 76 #include <rte_flow.h> 77 #include <rte_acl.h> 78 #include <rte_table_acl.h> 79 80 #ifdef __cplusplus 81 extern "C" { 82 #endif 83 84 extern int librte_flow_classify_logtype; 85 86 #define RTE_FLOW_CLASSIFY_LOG(level, ...) \ 87 rte_log(RTE_LOG_ ## level, \ 88 librte_flow_classify_logtype, \ 89 RTE_FMT("%s(): " RTE_FMT_HEAD(__VA_ARGS__,), \ 90 __func__, \ 91 RTE_FMT_TAIL(__VA_ARGS__,))) 92 93 /** Opaque data type for flow classifier */ 94 struct rte_flow_classifier; 95 96 /** Opaque data type for flow classify rule */ 97 struct rte_flow_classify_rule; 98 99 /** Flow classify rule type */ 100 enum rte_flow_classify_rule_type { 101 /** no type */ 102 RTE_FLOW_CLASSIFY_RULE_TYPE_NONE, 103 /** IPv4 5tuple type */ 104 RTE_FLOW_CLASSIFY_RULE_TYPE_IPV4_5TUPLE, 105 }; 106 107 /** Flow classify table type */ 108 enum rte_flow_classify_table_type { 109 /** no type */ 110 RTE_FLOW_CLASSIFY_TABLE_TYPE_NONE, 111 /** ACL type */ 112 RTE_FLOW_CLASSIFY_TABLE_TYPE_ACL, 113 }; 114 115 /** 116 * Maximum number of tables allowed for any Flow Classifier instance. 117 * The value of this parameter cannot be changed. 118 */ 119 #define RTE_FLOW_CLASSIFY_TABLE_MAX 64 120 121 /** Parameters for flow classifier creation */ 122 struct rte_flow_classifier_params { 123 /** flow classifier name */ 124 const char *name; 125 126 /** CPU socket ID where memory for the flow classifier and its */ 127 /** elements (tables) should be allocated */ 128 int socket_id; 129 130 /** Table type */ 131 enum rte_flow_classify_table_type type; 132 }; 133 134 /** Parameters for table creation */ 135 struct rte_flow_classify_table_params { 136 /** Table operations (specific to each table type) */ 137 struct rte_table_ops *ops; 138 139 /** Opaque param to be passed to the table create operation */ 140 void *arg_create; 141 }; 142 143 /** IPv4 5-tuple data */ 144 struct rte_flow_classify_ipv4_5tuple { 145 uint32_t dst_ip; /**< Destination IP address in big endian. */ 146 uint32_t dst_ip_mask; /**< Mask of destination IP address. */ 147 uint32_t src_ip; /**< Source IP address in big endian. */ 148 uint32_t src_ip_mask; /**< Mask of destination IP address. */ 149 uint16_t dst_port; /**< Destination port in big endian. */ 150 uint16_t dst_port_mask; /**< Mask of destination port. */ 151 uint16_t src_port; /**< Source Port in big endian. */ 152 uint16_t src_port_mask; /**< Mask of source port. */ 153 uint8_t proto; /**< L4 protocol. */ 154 uint8_t proto_mask; /**< Mask of L4 protocol. */ 155 }; 156 157 /** 158 * Flow stats 159 * 160 * For the count action, stats can be returned by the query API. 161 * 162 * Storage for stats is provided by application. 163 */ 164 struct rte_flow_classify_stats { 165 void *stats; 166 }; 167 168 struct rte_flow_classify_ipv4_5tuple_stats { 169 /** count of packets that match IPv4 5tuple pattern */ 170 uint64_t counter1; 171 /** IPv4 5tuple data */ 172 struct rte_flow_classify_ipv4_5tuple ipv4_5tuple; 173 }; 174 175 /** 176 * Flow classifier create 177 * 178 * @param params 179 * Parameters for flow classifier creation 180 * @return 181 * Handle to flow classifier instance on success or NULL otherwise 182 */ 183 struct rte_flow_classifier * 184 rte_flow_classifier_create(struct rte_flow_classifier_params *params); 185 186 /** 187 * Flow classifier free 188 * 189 * @param cls 190 * Handle to flow classifier instance 191 * @return 192 * 0 on success, error code otherwise 193 */ 194 int 195 rte_flow_classifier_free(struct rte_flow_classifier *cls); 196 197 /** 198 * Flow classify table create 199 * 200 * @param cls 201 * Handle to flow classifier instance 202 * @param params 203 * Parameters for flow_classify table creation 204 * @param table_id 205 * Table ID. Valid only within the scope of table IDs of the current 206 * classifier. Only returned after a successful invocation. 207 * @return 208 * 0 on success, error code otherwise 209 */ 210 int 211 rte_flow_classify_table_create(struct rte_flow_classifier *cls, 212 struct rte_flow_classify_table_params *params, 213 uint32_t *table_id); 214 215 /** 216 * Add a flow classify rule to the flow_classifer table. 217 * 218 * @param[in] cls 219 * Flow classifier handle 220 * @param[in] table_id 221 * id of table 222 * @param[out] key_found 223 * returns 1 if key present already, 0 otherwise. 224 * @param[in] attr 225 * Flow rule attributes 226 * @param[in] pattern 227 * Pattern specification (list terminated by the END pattern item). 228 * @param[in] actions 229 * Associated actions (list terminated by the END pattern item). 230 * @param[out] error 231 * Perform verbose error reporting if not NULL. Structure 232 * initialised in case of error only. 233 * @return 234 * A valid handle in case of success, NULL otherwise. 235 */ 236 struct rte_flow_classify_rule * 237 rte_flow_classify_table_entry_add(struct rte_flow_classifier *cls, 238 uint32_t table_id, 239 int *key_found, 240 const struct rte_flow_attr *attr, 241 const struct rte_flow_item pattern[], 242 const struct rte_flow_action actions[], 243 struct rte_flow_error *error); 244 245 /** 246 * Delete a flow classify rule from the flow_classifer table. 247 * 248 * @param[in] cls 249 * Flow classifier handle 250 * @param[in] table_id 251 * id of table 252 * @param[in] rule 253 * Flow classify rule 254 * @return 255 * 0 on success, error code otherwise. 256 */ 257 int 258 rte_flow_classify_table_entry_delete(struct rte_flow_classifier *cls, 259 uint32_t table_id, 260 struct rte_flow_classify_rule *rule); 261 262 /** 263 * Query flow classifier for given rule. 264 * 265 * @param[in] cls 266 * Flow classifier handle 267 * @param[in] table_id 268 * id of table 269 * @param[in] pkts 270 * Pointer to packets to process 271 * @param[in] nb_pkts 272 * Number of packets to process 273 * @param[in] rule 274 * Flow classify rule 275 * @param[in] stats 276 * Flow classify stats 277 * 278 * @return 279 * 0 on success, error code otherwise. 280 */ 281 int 282 rte_flow_classifier_query(struct rte_flow_classifier *cls, 283 uint32_t table_id, 284 struct rte_mbuf **pkts, 285 const uint16_t nb_pkts, 286 struct rte_flow_classify_rule *rule, 287 struct rte_flow_classify_stats *stats); 288 289 #ifdef __cplusplus 290 } 291 #endif 292 293 #endif /* _RTE_FLOW_CLASSIFY_H_ */ 294