lib/librte_ethdev/rte_flow_driver.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright 2016 6WIND S.A.
   3  * Copyright 2016 Mellanox Technologies, Ltd
   4  */
   5
   6 #ifndef RTE_FLOW_DRIVER_H_
   7 #define RTE_FLOW_DRIVER_H_
   8
   9 /**
  10  * @file
  11  * RTE generic flow API (driver side)
  12  *
  13  * This file provides implementation helpers for internal use by PMDs, they
  14  * are not intended to be exposed to applications and are not subject to ABI
  15  * versioning.
  16  */
  17
  18 #include <stdint.h>
  19
  20 #include "rte_ethdev.h"
  21 #include "rte_flow.h"
  22
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26
  27 /**
  28  * Generic flow operations structure implemented and returned by PMDs.
  29  *
  30  * To implement this API, PMDs must handle the RTE_ETH_FILTER_GENERIC filter
  31  * type in their .filter_ctrl callback function (struct eth_dev_ops) as well
  32  * as the RTE_ETH_FILTER_GET filter operation.
  33  *
  34  * If successful, this operation must result in a pointer to a PMD-specific
  35  * struct rte_flow_ops written to the argument address as described below:
  36  *
  37  * \code
  38  *
  39  * // PMD filter_ctrl callback
  40  *
  41  * static const struct rte_flow_ops pmd_flow_ops = { ... };
  42  *
  43  * switch (filter_type) {
  44  * case RTE_ETH_FILTER_GENERIC:
  45  *     if (filter_op != RTE_ETH_FILTER_GET)
  46  *         return -EINVAL;
  47  *     *(const void **)arg = &pmd_flow_ops;
  48  *     return 0;
  49  * }
  50  *
  51  * \endcode
  52  *
  53  * See also rte_flow_ops_get().
  54  *
  55  * These callback functions are not supposed to be used by applications
  56  * directly, which must rely on the API defined in rte_flow.h.
  57  *
  58  * Public-facing wrapper functions perform a few consistency checks so that
  59  * unimplemented (i.e. NULL) callbacks simply return -ENOTSUP. These
  60  * callbacks otherwise only differ by their first argument (with port ID
  61  * already resolved to a pointer to struct rte_eth_dev).
  62  */
  63 struct rte_flow_ops {
  64         /** See rte_flow_validate(). */
  65         int (*validate)
  66                 (struct rte_eth_dev *,
  67                  const struct rte_flow_attr *,
  68                  const struct rte_flow_item [],
  69                  const struct rte_flow_action [],
  70                  struct rte_flow_error *);
  71         /** See rte_flow_create(). */
  72         struct rte_flow *(*create)
  73                 (struct rte_eth_dev *,
  74                  const struct rte_flow_attr *,
  75                  const struct rte_flow_item [],
  76                  const struct rte_flow_action [],
  77                  struct rte_flow_error *);
  78         /** See rte_flow_destroy(). */
  79         int (*destroy)
  80                 (struct rte_eth_dev *,
  81                  struct rte_flow *,
  82                  struct rte_flow_error *);
  83         /** See rte_flow_flush(). */
  84         int (*flush)
  85                 (struct rte_eth_dev *,
  86                  struct rte_flow_error *);
  87         /** See rte_flow_query(). */
  88         int (*query)
  89                 (struct rte_eth_dev *,
  90                  struct rte_flow *,
  91                  const struct rte_flow_action *,
  92                  void *,
  93                  struct rte_flow_error *);
  94         /** See rte_flow_isolate(). */
  95         int (*isolate)
  96                 (struct rte_eth_dev *,
  97                  int,
  98                  struct rte_flow_error *);
  99         /** See rte_flow_dev_dump(). */
 100         int (*dev_dump)
 101                 (struct rte_eth_dev *dev,
 102                  FILE *file,
 103                  struct rte_flow_error *error);
 104         /** See rte_flow_get_aged_flows() */
 105         int (*get_aged_flows)
 106                 (struct rte_eth_dev *dev,
 107                  void **context,
 108                  uint32_t nb_contexts,
 109                  struct rte_flow_error *err);
 110 };
 111
 112 /**
 113  * Get generic flow operations structure from a port.
 114  *
 115  * @param port_id
 116  *   Port identifier to query.
 117  * @param[out] error
 118  *   Pointer to flow error structure.
 119  *
 120  * @return
 121  *   The flow operations structure associated with port_id, NULL in case of
 122  *   error, in which case rte_errno is set and the error structure contains
 123  *   additional details.
 124  */
 125 const struct rte_flow_ops *
 126 rte_flow_ops_get(uint16_t port_id, struct rte_flow_error *error);
 127
 128 /** Helper macro to build input graph for rte_flow_expand_rss(). */
 129 #define RTE_FLOW_EXPAND_RSS_NEXT(...) \
 130         (const int []){ \
 131                 __VA_ARGS__, 0, \
 132         }
 133
 134 /** Node object of input graph for rte_flow_expand_rss(). */
 135 struct rte_flow_expand_node {
 136         const int *const next;
 137         /**<
 138          * List of next node indexes. Index 0 is interpreted as a terminator.
 139          */
 140         const enum rte_flow_item_type type;
 141         /**< Pattern item type of current node. */
 142         uint64_t rss_types;
 143         /**<
 144          * RSS types bit-field associated with this node
 145          * (see ETH_RSS_* definitions).
 146          */
 147 };
 148
 149 /** Object returned by rte_flow_expand_rss(). */
 150 struct rte_flow_expand_rss {
 151         uint32_t entries;
 152         /**< Number of entries @p patterns and @p priorities. */
 153         struct {
 154                 struct rte_flow_item *pattern; /**< Expanded pattern array. */
 155                 uint32_t priority; /**< Priority offset for each expansion. */
 156         } entry[];
 157 };
 158
 159 /**
 160  * Expand RSS flows into several possible flows according to the RSS hash
 161  * fields requested and the driver capabilities.
 162  *
 163  * @b EXPERIMENTAL: this API may change without prior notice
 164  *
 165  * @param[out] buf
 166  *   Buffer to store the result expansion.
 167  * @param[in] size
 168  *   Buffer size in bytes. If 0, @p buf can be NULL.
 169  * @param[in] pattern
 170  *   User flow pattern.
 171  * @param[in] types
 172  *   RSS types to expand (see ETH_RSS_* definitions).
 173  * @param[in] graph
 174  *   Input graph to expand @p pattern according to @p types.
 175  * @param[in] graph_root_index
 176  *   Index of root node in @p graph, typically 0.
 177  *
 178  * @return
 179  *   A positive value representing the size of @p buf in bytes regardless of
 180  *   @p size on success, a negative errno value otherwise and rte_errno is
 181  *   set, the following errors are defined:
 182  *
 183  *   -E2BIG: graph-depth @p graph is too deep.
 184  */
 185 __rte_experimental
 186 int
 187 rte_flow_expand_rss(struct rte_flow_expand_rss *buf, size_t size,
 188                     const struct rte_flow_item *pattern, uint64_t types,
 189                     const struct rte_flow_expand_node graph[],
 190                     int graph_root_index);
 191
 192 #ifdef __cplusplus
 193 }
 194 #endif
 195
 196 #endif /* RTE_FLOW_DRIVER_H_ */