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