net/virtio: fix incorrect cast of void *
[dpdk.git] / ethdev / rte_mtr.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright 2017 Intel Corporation
3  * Copyright 2017 NXP
4  * Copyright 2017 Cavium
5  */
6
7 #ifndef __INCLUDE_RTE_MTR_H__
8 #define __INCLUDE_RTE_MTR_H__
9
10 /**
11  * @file
12  * RTE Generic Traffic Metering and Policing API
13  *
14  * This interface provides the ability to configure the traffic metering and
15  * policing (MTR) in a generic way.
16  *
17  * The processing done for each input packet hitting a MTR object is:
18  *    A) Traffic metering: The packet is assigned a color (the meter output
19  *       color), based on the previous history of the flow reflected in the
20  *       current state of the MTR object, according to the specific traffic
21  *       metering algorithm. The traffic metering algorithm can typically work
22  *       in color aware mode, in which case the input packet already has an
23  *       initial color (the input color), or in color blind mode, which is
24  *       equivalent to considering all input packets initially colored as green.
25  *    B) Policing: There is a separate policer action configured for each meter
26  *       output color, which can:
27  *          a) Drop the packet.
28  *          b) Keep the same packet color: the policer output color matches the
29  *             meter output color (essentially a no-op action).
30  *          c) Recolor the packet: the policer output color is different than
31  *             the meter output color.
32  *       The policer output color is the output color of the packet, which is
33  *       set in the packet meta-data (i.e. struct rte_mbuf::sched::color).
34  *    C) Statistics: The set of counters maintained for each MTR object is
35  *       configurable and subject to the implementation support. This set
36  *       includes the number of packets and bytes dropped or passed for each
37  *       output color.
38  *
39  * Once successfully created, an MTR object is linked to one or several flows
40  * through the meter action of the flow API.
41  *    A) Whether an MTR object is private to a flow or potentially shared by
42  *       several flows has to be specified at creation time.
43  *    B) Several meter actions can be potentially registered for the same flow.
44  *
45  * @warning
46  * @b EXPERIMENTAL: this API may change without prior notice
47  */
48 #include <stdint.h>
49 #include <rte_compat.h>
50 #include <rte_common.h>
51 #include <rte_meter.h>
52 #include <rte_flow.h>
53
54 #ifdef __cplusplus
55 extern "C" {
56 #endif
57
58 /**
59  * Statistics counter type
60  */
61 enum rte_mtr_stats_type {
62         /** Number of packets passed as green by the policer. */
63         RTE_MTR_STATS_N_PKTS_GREEN = 1 << 0,
64
65         /** Number of packets passed as yellow by the policer. */
66         RTE_MTR_STATS_N_PKTS_YELLOW = 1 << 1,
67
68         /** Number of packets passed as red by the policer. */
69         RTE_MTR_STATS_N_PKTS_RED = 1 << 2,
70
71         /** Number of packets dropped by the policer. */
72         RTE_MTR_STATS_N_PKTS_DROPPED = 1 << 3,
73
74         /** Number of bytes passed as green by the policer. */
75         RTE_MTR_STATS_N_BYTES_GREEN = 1 << 4,
76
77         /** Number of bytes passed as yellow by the policer. */
78         RTE_MTR_STATS_N_BYTES_YELLOW = 1 << 5,
79
80         /** Number of bytes passed as red by the policer. */
81         RTE_MTR_STATS_N_BYTES_RED = 1 << 6,
82
83         /** Number of bytes dropped by the policer. */
84         RTE_MTR_STATS_N_BYTES_DROPPED = 1 << 7,
85 };
86
87 /**
88  * Statistics counters
89  */
90 struct rte_mtr_stats {
91         /** Number of packets passed by the policer (per color). */
92         uint64_t n_pkts[RTE_COLORS];
93
94         /** Number of bytes passed by the policer (per color). */
95         uint64_t n_bytes[RTE_COLORS];
96
97         /** Number of packets dropped by the policer. */
98         uint64_t n_pkts_dropped;
99
100         /** Number of bytes passed by the policer. */
101         uint64_t n_bytes_dropped;
102 };
103
104 /**
105  * Traffic metering algorithms
106  */
107 enum rte_mtr_algorithm {
108         /** No traffic metering performed, the output color is the same as the
109          * input color for every input packet. The meter of the MTR object is
110          * working in pass-through mode, having same effect as meter disable.
111          * @see rte_mtr_meter_disable()
112          */
113         RTE_MTR_NONE = 0,
114
115         /** Single Rate Three Color Marker (srTCM) - IETF RFC 2697. */
116         RTE_MTR_SRTCM_RFC2697,
117
118         /** Two Rate Three Color Marker (trTCM) - IETF RFC 2698. */
119         RTE_MTR_TRTCM_RFC2698,
120
121         /** Two Rate Three Color Marker (trTCM) - IETF RFC 4115. */
122         RTE_MTR_TRTCM_RFC4115,
123 };
124
125 /**
126  * Meter profile
127  */
128 struct rte_mtr_meter_profile {
129         /** Traffic metering algorithm. */
130         enum rte_mtr_algorithm alg;
131
132         RTE_STD_C11
133         union {
134                 /** Items only valid when *alg* is set to srTCM - RFC 2697. */
135                 struct {
136                         /**
137                          * Committed Information Rate (CIR)
138                          * (bytes per second or packets per second).
139                          */
140                         uint64_t cir;
141
142                         /** Committed Burst Size (CBS) (bytes or packets). */
143                         uint64_t cbs;
144
145                         /** Excess Burst Size (EBS) (bytes or packets). */
146                         uint64_t ebs;
147                 } srtcm_rfc2697;
148
149                 /** Items only valid when *alg* is set to trTCM - RFC 2698. */
150                 struct {
151                         /**
152                          * Committed Information Rate (CIR)
153                          * (bytes per second or packets per second).
154                          */
155                         uint64_t cir;
156
157                         /**
158                          * Peak Information Rate (PIR)
159                          * (bytes per second or packets per second).
160                          */
161                         uint64_t pir;
162
163                         /** Committed Burst Size (CBS) (bytes or packets). */
164                         uint64_t cbs;
165
166                         /** Peak Burst Size (PBS) (bytes or packets). */
167                         uint64_t pbs;
168                 } trtcm_rfc2698;
169
170                 /** Items only valid when *alg* is set to trTCM - RFC 4115. */
171                 struct {
172                         /**
173                          * Committed Information Rate (CIR)
174                          * (bytes per second or packets per second).
175                          */
176                         uint64_t cir;
177
178                         /**
179                          * Excess Information Rate (EIR)
180                          * (bytes per second or packets per second).
181                          */
182                         uint64_t eir;
183
184                         /** Committed Burst Size (CBS) (bytes or packets). */
185                         uint64_t cbs;
186
187                         /** Excess Burst Size (EBS) (bytes or packets). */
188                         uint64_t ebs;
189                 } trtcm_rfc4115;
190         };
191
192         /**
193          * When zero, the byte mode is enabled for the current profile, so the
194          * *rate* and *size* fields are specified in bytes per second
195          * and bytes, respectively.
196          * When non-zero, the packet mode is enabled for the current profile,
197          * so the *rate* and *size* fields are specified in packets per second
198          * and packets, respectively.
199          */
200         int packet_mode;
201 };
202
203 /**
204  * Meter policy
205  */
206 struct rte_mtr_meter_policy_params {
207         /**
208          * Policy action list per color.
209          * actions[i] potentially represents a chain of rte_flow actions
210          * terminated by the END action, exactly as specified by the rte_flow
211          * API for the flow definition, and not just a single action.
212          */
213         const struct rte_flow_action *actions[RTE_COLORS];
214 };
215
216 /**
217  * Parameters for each traffic metering & policing object
218  *
219  * @see enum rte_mtr_stats_type
220  */
221 struct rte_mtr_params {
222         /** Meter profile ID. */
223         uint32_t meter_profile_id;
224
225         /** Meter input color in case of MTR object chaining. When non-zero: if
226          * a previous MTR object is enabled in the same flow, then the color
227          * determined by the latest MTR object in the same flow is used as the
228          * input color by the current MTR object, otherwise the current MTR
229          * object uses the *dscp_table* to determine the input color. When zero:
230          * the color determined by any previous MTR object in same flow is
231          * ignored by the current MTR object, which uses the *dscp_table* to
232          * determine the input color.
233          */
234         int use_prev_mtr_color;
235
236         /** Meter input color. When non-NULL: it points to a pre-allocated and
237          * pre-populated table with exactly 64 elements providing the input
238          * color for each value of the IPv4/IPv6 Differentiated Services Code
239          * Point (DSCP) input packet field. When NULL: it is equivalent to
240          * setting this parameter to an all-green populated table (i.e. table
241          * with all the 64 elements set to green color). The color blind mode
242          * is configured by setting *use_prev_mtr_color* to 0 and *dscp_table*
243          * to either NULL or to an all-green populated table. When
244          * *use_prev_mtr_color* is non-zero value or when *dscp_table* contains
245          * at least one yellow or red color element, then the color aware mode
246          * is configured.
247          */
248         enum rte_color *dscp_table;
249
250         /** Non-zero to enable the meter, zero to disable the meter at the time
251          * of MTR object creation. Ignored when the meter profile indicated by
252          * *meter_profile_id* is set to NONE.
253          * @see rte_mtr_meter_disable()
254          */
255         int meter_enable;
256
257         /** Set of stats counters to be enabled.
258          * @see enum rte_mtr_stats_type
259          */
260         uint64_t stats_mask;
261
262         /** Meter policy ID. */
263         uint32_t meter_policy_id;
264 };
265
266 /**
267  * MTR capabilities
268  */
269 struct rte_mtr_capabilities {
270         /** Maximum number of MTR objects. */
271         uint32_t n_max;
272
273         /** Maximum number of MTR objects that can be shared by multiple flows.
274          * The value of zero indicates that shared MTR objects are not
275          * supported. The maximum value is *n_max*.
276          */
277         uint32_t n_shared_max;
278
279         /** When non-zero, this flag indicates that all the MTR objects that
280          * cannot be shared by multiple flows have identical capability set.
281          */
282         int identical;
283
284         /** When non-zero, this flag indicates that all the MTR objects that
285          * can be shared by multiple flows have identical capability set.
286          */
287         int shared_identical;
288
289         /** Maximum number of flows that can share the same MTR object. The
290          * value of zero is invalid. The value of 1 means that shared MTR
291          * objects not supported.
292          */
293         uint32_t shared_n_flows_per_mtr_max;
294
295         /** Maximum number of MTR objects that can be part of the same flow. The
296          * value of zero is invalid. The value of 1 indicates that MTR object
297          * chaining is not supported. The maximum value is *n_max*.
298          */
299         uint32_t chaining_n_mtrs_per_flow_max;
300
301         /**
302          * When non-zero, it indicates that the packet color identified by one
303          * MTR object can be used as the packet input color by any subsequent
304          * MTR object from the same flow. When zero, it indicates that the color
305          * determined by one MTR object is always ignored by any subsequent MTR
306          * object from the same flow. Only valid when MTR chaining is supported,
307          * i.e. *chaining_n_mtrs_per_flow_max* is greater than 1. When non-zero,
308          * it also means that the color aware mode is supported by at least one
309          * metering algorithm.
310          */
311         int chaining_use_prev_mtr_color_supported;
312
313         /**
314          * When non-zero, it indicates that the packet color identified by one
315          * MTR object is always used as the packet input color by any subsequent
316          * MTR object that is part of the same flow. When zero, it indicates
317          * that whether the color determined by one MTR object is either ignored
318          * or used as the packet input color by any subsequent MTR object from
319          * the same flow is individually configurable for each MTR object. Only
320          * valid when *chaining_use_prev_mtr_color_supported* is non-zero.
321          */
322         int chaining_use_prev_mtr_color_enforced;
323
324         /** Maximum number of MTR objects that can have their meter configured
325          * to run the srTCM RFC 2697 algorithm. The value of 0 indicates this
326          * metering algorithm is not supported. The maximum value is *n_max*.
327          */
328         uint32_t meter_srtcm_rfc2697_n_max;
329
330         /** Maximum number of MTR objects that can have their meter configured
331          * to run the trTCM RFC 2698 algorithm. The value of 0 indicates this
332          * metering algorithm is not supported. The maximum value is *n_max*.
333          */
334         uint32_t meter_trtcm_rfc2698_n_max;
335
336         /** Maximum number of MTR objects that can have their meter configured
337          * to run the trTCM RFC 4115 algorithm. The value of 0 indicates this
338          * metering algorithm is not supported. The maximum value is *n_max*.
339          */
340         uint32_t meter_trtcm_rfc4115_n_max;
341
342         /** Maximum traffic rate that can be metered by a single MTR object. For
343          * srTCM RFC 2697, this is the maximum CIR rate. For trTCM RFC 2698,
344          * this is the maximum PIR rate. For trTCM RFC 4115, this is the maximum
345          * value for the sum of PIR and EIR rates.
346          */
347         uint64_t meter_rate_max;
348
349         /**
350          * Maximum number of policy objects that can have.
351          * The value of 0 is invalid. Policy must be supported for meter.
352          * The maximum value is *n_max*.
353          */
354         uint64_t meter_policy_n_max;
355
356         /**
357          * When non-zero, it indicates that color aware mode is supported for
358          * the srTCM RFC 2697 metering algorithm.
359          */
360         int color_aware_srtcm_rfc2697_supported;
361
362         /**
363          * When non-zero, it indicates that color aware mode is supported for
364          * the trTCM RFC 2698 metering algorithm.
365          */
366         int color_aware_trtcm_rfc2698_supported;
367
368         /**
369          * When non-zero, it indicates that color aware mode is supported for
370          * the trTCM RFC 4115 metering algorithm.
371          */
372         int color_aware_trtcm_rfc4115_supported;
373
374         /**
375          * srTCM rfc2697 byte mode supported.
376          * When non-zero, it indicates that byte mode is supported for
377          * the srTCM RFC 2697 metering algorithm.
378          */
379         int srtcm_rfc2697_byte_mode_supported;
380
381         /**
382          * srTCM rfc2697 packet mode supported.
383          * When non-zero, it indicates that packet mode is supported for
384          * the srTCM RFC 2697 metering algorithm.
385          */
386         int srtcm_rfc2697_packet_mode_supported;
387
388         /**
389          * trTCM rfc2698 byte mode supported.
390          * When non-zero, it indicates that byte mode is supported for
391          * the trTCM RFC 2698 metering algorithm.
392          */
393         int trtcm_rfc2698_byte_mode_supported;
394
395         /**
396          * trTCM rfc2698 packet mode supported.
397          * When non-zero, it indicates that packet mode is supported for
398          * the trTCM RFC 2698 metering algorithm.
399          */
400         int trtcm_rfc2698_packet_mode_supported;
401
402         /**
403          * trTCM rfc4115 byte mode supported.
404          * When non-zero, it indicates that byte mode is supported for
405          * the trTCM RFC 4115 metering algorithm.
406          */
407         int trtcm_rfc4115_byte_mode_supported;
408
409         /**
410          * trTCM rfc4115 packet mode supported.
411          * When non-zero, it indicates that packet mode is supported for
412          * the trTCM RFC 4115 metering algorithm.
413          */
414         int trtcm_rfc4115_packet_mode_supported;
415
416         /** Set of supported statistics counter types.
417          * @see enum rte_mtr_stats_type
418          */
419         uint64_t stats_mask;
420 };
421
422 /**
423  * Verbose error types.
424  *
425  * Most of them provide the type of the object referenced by struct
426  * rte_mtr_error::cause.
427  */
428 enum rte_mtr_error_type {
429         RTE_MTR_ERROR_TYPE_NONE, /**< No error. */
430         RTE_MTR_ERROR_TYPE_UNSPECIFIED, /**< Cause unspecified. */
431         RTE_MTR_ERROR_TYPE_METER_PROFILE_ID,
432         RTE_MTR_ERROR_TYPE_METER_PROFILE,
433         RTE_MTR_ERROR_TYPE_METER_PROFILE_PACKET_MODE,
434         RTE_MTR_ERROR_TYPE_MTR_ID,
435         RTE_MTR_ERROR_TYPE_MTR_PARAMS,
436         RTE_MTR_ERROR_TYPE_POLICER_ACTION_GREEN,
437         RTE_MTR_ERROR_TYPE_POLICER_ACTION_YELLOW,
438         RTE_MTR_ERROR_TYPE_POLICER_ACTION_RED,
439         RTE_MTR_ERROR_TYPE_STATS_MASK,
440         RTE_MTR_ERROR_TYPE_STATS,
441         RTE_MTR_ERROR_TYPE_SHARED,
442         RTE_MTR_ERROR_TYPE_METER_POLICY_ID,
443         RTE_MTR_ERROR_TYPE_METER_POLICY,
444 };
445
446 /**
447  * Verbose error structure definition.
448  *
449  * This object is normally allocated by applications and set by PMDs, the
450  * message points to a constant string which does not need to be freed by
451  * the application, however its pointer can be considered valid only as long
452  * as its associated DPDK port remains configured. Closing the underlying
453  * device or unloading the PMD invalidates it.
454  *
455  * Both cause and message may be NULL regardless of the error type.
456  */
457 struct rte_mtr_error {
458         enum rte_mtr_error_type type; /**< Cause field and error type. */
459         const void *cause; /**< Object responsible for the error. */
460         const char *message; /**< Human-readable error message. */
461 };
462
463 /**
464  * MTR capabilities get
465  *
466  * @param[in] port_id
467  *   The port identifier of the Ethernet device.
468  * @param[out] cap
469  *   MTR capabilities. Needs to be pre-allocated and valid.
470  * @param[out] error
471  *   Error details. Filled in only on error, when not NULL.
472  * @return
473  *   0 on success, non-zero error code otherwise.
474  */
475 __rte_experimental
476 int
477 rte_mtr_capabilities_get(uint16_t port_id,
478         struct rte_mtr_capabilities *cap,
479         struct rte_mtr_error *error);
480
481 /**
482  * Meter profile add
483  *
484  * Create a new meter profile with ID set to *meter_profile_id*. The new profile
485  * is used to create one or several MTR objects.
486  *
487  * @param[in] port_id
488  *   The port identifier of the Ethernet device.
489  * @param[in] meter_profile_id
490  *   ID for the new meter profile. Needs to be unused by any of the existing
491  *   meter profiles added for the current port.
492  * @param[in] profile
493  *   Meter profile parameters. Needs to be pre-allocated and valid.
494  * @param[out] error
495  *   Error details. Filled in only on error, when not NULL.
496  * @return
497  *   0 on success, non-zero error code otherwise.
498  */
499 __rte_experimental
500 int
501 rte_mtr_meter_profile_add(uint16_t port_id,
502         uint32_t meter_profile_id,
503         struct rte_mtr_meter_profile *profile,
504         struct rte_mtr_error *error);
505
506 /**
507  * Meter profile delete
508  *
509  * Delete an existing meter profile. This operation fails when there is
510  * currently at least one user (i.e. MTR object) of this profile.
511  *
512  * @param[in] port_id
513  *   The port identifier of the Ethernet device.
514  * @param[in] meter_profile_id
515  *   Meter profile ID. Needs to be the valid.
516  * @param[out] error
517  *   Error details. Filled in only on error, when not NULL.
518  * @return
519  *   0 on success, non-zero error code otherwise.
520  */
521 __rte_experimental
522 int
523 rte_mtr_meter_profile_delete(uint16_t port_id,
524         uint32_t meter_profile_id,
525         struct rte_mtr_error *error);
526
527 /**
528  * Check whether a meter policy can be created on a given port.
529  *
530  * The meter policy is validated for correctness and
531  * whether it could be accepted by the device given sufficient resources.
532  * The policy is checked against the current capability information
533  * meter_policy_n_max configuration.
534  * The policy may also optionally be validated against existing
535  * device policy resources.
536  * This function has no effect on the target device.
537  *
538  * @param[in] port_id
539  *   The port identifier of the Ethernet device.
540  * @param[in] policy
541  *   Associated action list per color.
542  *   list NULL is legal and means no special action.
543  *   (list terminated by the END action).
544  * @param[out] error
545  *   Error details. Filled in only on error, when not NULL.
546  * @return
547  *   0 on success, non-zero error code otherwise.
548  */
549 __rte_experimental
550 int
551 rte_mtr_meter_policy_validate(uint16_t port_id,
552         struct rte_mtr_meter_policy_params *policy,
553         struct rte_mtr_error *error);
554
555 /**
556  * Meter policy add
557  *
558  * Create a new meter policy. The new policy
559  * is used to create single or multiple MTR objects.
560  * The same policy can be used to create multiple MTR objects.
561  *
562  * @param[in] port_id
563  *   The port identifier of the Ethernet device.
564  * @param[in] policy_id
565  *   Policy identifier for the new meter policy.
566  * @param[in] policy
567  *   Associated actions per color.
568  *   list NULL is legal and means no special action.
569  *   Non-NULL list must be terminated.
570  *   (list terminated by the END action).
571  * @param[out] error
572  *   Error details. Filled in only on error, when not NULL.
573  * @return
574  *   0 on success, non-zero error code otherwise.
575  */
576 __rte_experimental
577 int
578 rte_mtr_meter_policy_add(uint16_t port_id,
579         uint32_t policy_id,
580         struct rte_mtr_meter_policy_params *policy,
581         struct rte_mtr_error *error);
582
583 /**
584  * Define meter policy action list:
585  * GREEN - GREEN, YELLOW - YELLOW, RED - RED
586  */
587 #define rte_mtr_policy_pass_color(policy) \
588 struct rte_mtr_meter_policy_params policy = \
589 { \
590         .actions[RTE_COLOR_GREEN] = (struct rte_flow_action[]) { \
591                 { \
592                         .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
593                         .conf = &(struct rte_flow_action_meter_color) { \
594                                 .color = RTE_COLOR_GREEN, \
595                         }, \
596                 }, \
597                 { \
598                         .type = RTE_FLOW_ACTION_TYPE_END, \
599                 }, \
600         }, \
601         .actions[RTE_COLOR_YELLOW] = (struct rte_flow_action[]) { \
602                 { \
603                         .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
604                         .conf = &(struct rte_flow_action_meter_color) { \
605                                 .color = RTE_COLOR_YELLOW, \
606                         }, \
607                 }, \
608                 { \
609                 .type = RTE_FLOW_ACTION_TYPE_END, \
610                 }, \
611         }, \
612         .actions[RTE_COLOR_RED] = (struct rte_flow_action[]) { \
613                 { \
614                         .type = RTE_FLOW_ACTION_TYPE_METER_COLOR, \
615                         .conf = &(struct rte_flow_action_meter_color) { \
616                                 .color = RTE_COLOR_RED, \
617                         }, \
618                 }, \
619                 { \
620                         .type = RTE_FLOW_ACTION_TYPE_END, \
621                 }, \
622         }, \
623 }
624
625 /**
626  * Define meter policy action list:
627  * GREEN - Do nothing, YELLOW - Do nothing, RED - DROP
628  */
629 #define rte_mtr_policy_drop_red(policy) \
630 struct rte_mtr_meter_policy_params policy = \
631 { \
632         .actions[RTE_COLOR_GREEN] = NULL, \
633         .actions[RTE_COLOR_YELLOW] = NULL, \
634         .actions[RTE_COLOR_RED] = (struct rte_flow_action[]) { \
635                 { \
636                         .type = RTE_FLOW_ACTION_TYPE_DROP, \
637                 }, \
638                 { \
639                         .type = RTE_FLOW_ACTION_TYPE_END, \
640                 }, \
641         }, \
642 }
643
644 /**
645  * Meter policy delete
646  *
647  * Delete an existing meter policy. This operation fails when there is
648  * currently at least one user (i.e. MTR object) of this policy.
649  *
650  * @param[in] port_id
651  *   The port identifier of the Ethernet device.
652  * @param[in] policy_id
653  *   Policy identifier.
654  * @param[out] error
655  *   Error details. Filled in only on error, when not NULL.
656  * @return
657  *   0 on success, non-zero error code otherwise.
658  */
659 __rte_experimental
660 int
661 rte_mtr_meter_policy_delete(uint16_t port_id,
662         uint32_t policy_id,
663         struct rte_mtr_error *error);
664
665 /**
666  * MTR object create
667  *
668  * Create a new MTR object for the current port. This object is run as part of
669  * associated flow action for traffic metering and policing.
670  *
671  * @param[in] port_id
672  *   The port identifier of the Ethernet device.
673  * @param[in] mtr_id
674  *   MTR object ID. Needs to be unused by any of the existing MTR objects.
675  *   created for the current port.
676  * @param[in] params
677  *   MTR object params. Needs to be pre-allocated and valid.
678  * @param[in] shared
679  *   Non-zero when this MTR object can be shared by multiple flows, zero when
680  *   this MTR object can be used by a single flow.
681  * @param[out] error
682  *   Error details. Filled in only on error, when not NULL.
683  * @return
684  *   0 on success, non-zero error code otherwise.
685  *
686  * @see enum rte_flow_action_type::RTE_FLOW_ACTION_TYPE_METER
687  */
688 __rte_experimental
689 int
690 rte_mtr_create(uint16_t port_id,
691         uint32_t mtr_id,
692         struct rte_mtr_params *params,
693         int shared,
694         struct rte_mtr_error *error);
695
696 /**
697  * MTR object destroy
698  *
699  * Delete an existing MTR object. This operation fails when there is currently
700  * at least one user (i.e. flow) of this MTR object.
701  *
702  * @param[in] port_id
703  *   The port identifier of the Ethernet device.
704  * @param[in] mtr_id
705  *   MTR object ID. Needs to be valid.
706  *   created for the current port.
707  * @param[out] error
708  *   Error details. Filled in only on error, when not NULL.
709  * @return
710  *   0 on success, non-zero error code otherwise.
711  */
712 __rte_experimental
713 int
714 rte_mtr_destroy(uint16_t port_id,
715         uint32_t mtr_id,
716         struct rte_mtr_error *error);
717
718 /**
719  * MTR object meter disable
720  *
721  * Disable the meter of an existing MTR object. In disabled state, the meter of
722  * the current MTR object works in pass-through mode, meaning that for each
723  * input packet the meter output color is always the same as the input color. In
724  * particular, when the meter of the current MTR object is configured in color
725  * blind mode, the input color is always green, so the meter output color is
726  * also always green. Note that the policer and the statistics of the current
727  * MTR object are working as usual while the meter is disabled. No action is
728  * taken and this function returns successfully when the meter of the current
729  * MTR object is already disabled.
730  *
731  * @param[in] port_id
732  *   The port identifier of the Ethernet device.
733  * @param[in] mtr_id
734  *   MTR object ID.
735  * @param[out] error
736  *   Error details. Filled in only on error, when not NULL.
737  * @return
738  *   0 on success, non-zero error code otherwise.
739  */
740 __rte_experimental
741 int
742 rte_mtr_meter_disable(uint16_t port_id,
743         uint32_t mtr_id,
744         struct rte_mtr_error *error);
745
746 /**
747  * MTR object meter enable
748  *
749  * Enable the meter of an existing MTR object. If the MTR object has its meter
750  * already enabled, then no action is taken and this function returns
751  * successfully.
752  *
753  * @param[in] port_id
754  *   The port identifier of the Ethernet device.
755  * @param[in] mtr_id
756  *   MTR object ID.
757  * @param[out] error
758  *   Error details. Filled in only on error, when not NULL.
759  * @return
760  *   0 on success, non-zero error code otherwise.
761  */
762 __rte_experimental
763 int
764 rte_mtr_meter_enable(uint16_t port_id,
765         uint32_t mtr_id,
766         struct rte_mtr_error *error);
767
768 /**
769  * MTR object meter profile update
770  *
771  * @param[in] port_id
772  *   The port identifier of the Ethernet device.
773  * @param[in] mtr_id
774  *   MTR object ID. Needs to be valid.
775  * @param[in] meter_profile_id
776  *   Meter profile ID for the current MTR object. Needs to be valid.
777  * @param[out] error
778  *   Error details. Filled in only on error, when not NULL.
779  * @return
780  *   0 on success, non-zero error code otherwise.
781  */
782 __rte_experimental
783 int
784 rte_mtr_meter_profile_update(uint16_t port_id,
785         uint32_t mtr_id,
786         uint32_t meter_profile_id,
787         struct rte_mtr_error *error);
788
789 /**
790  * MTR object meter policy update
791  *
792  * @param[in] port_id
793  *   The port identifier of the Ethernet device.
794  * @param[in] mtr_id
795  *   MTR object ID. Needs to be valid.
796  * @param[in] meter_policy_id
797  *   Meter policy ID for the current MTR object. Needs to be valid.
798  * @param[out] error
799  *   Error details. Filled in only on error, when not NULL.
800  * @return
801  *   0 on success, non-zero error code otherwise.
802  */
803 __rte_experimental
804 int
805 rte_mtr_meter_policy_update(uint16_t port_id,
806         uint32_t mtr_id,
807         uint32_t meter_policy_id,
808         struct rte_mtr_error *error);
809
810 /**
811  * MTR object DSCP table update
812  *
813  * @param[in] port_id
814  *   The port identifier of the Ethernet device.
815  * @param[in] mtr_id
816  *   MTR object ID. Needs to be valid.
817  * @param[in] dscp_table
818  *   When non-NULL: it points to a pre-allocated and pre-populated table with
819  *   exactly 64 elements providing the input color for each value of the
820  *   IPv4/IPv6 Differentiated Services Code Point (DSCP) input packet field.
821  *   When NULL: it is equivalent to setting this parameter to an "all-green"
822  *   populated table (i.e. table with all the 64 elements set to green color).
823  * @param[out] error
824  *   Error details. Filled in only on error, when not NULL.
825  * @return
826  *   0 on success, non-zero error code otherwise.
827  */
828 __rte_experimental
829 int
830 rte_mtr_meter_dscp_table_update(uint16_t port_id,
831         uint32_t mtr_id,
832         enum rte_color *dscp_table,
833         struct rte_mtr_error *error);
834
835 /**
836  * MTR object enabled statistics counters update
837  *
838  * @param[in] port_id
839  *   The port identifier of the Ethernet device.
840  * @param[in] mtr_id
841  *   MTR object ID. Needs to be valid.
842  * @param[in] stats_mask
843  *   Mask of statistics counter types to be enabled for the current MTR object.
844  *   Any statistics counter type not included in this set is to be disabled for
845  *   the current MTR object.
846  * @param[out] error
847  *   Error details. Filled in only on error, when not NULL.
848  * @return
849  *   0 on success, non-zero error code otherwise.
850  *
851  * @see enum rte_mtr_stats_type
852  */
853 __rte_experimental
854 int
855 rte_mtr_stats_update(uint16_t port_id,
856         uint32_t mtr_id,
857         uint64_t stats_mask,
858         struct rte_mtr_error *error);
859
860 /**
861  * MTR object statistics counters read
862  *
863  * @param[in] port_id
864  *   The port identifier of the Ethernet device.
865  * @param[in] mtr_id
866  *   MTR object ID. Needs to be valid.
867  * @param[out] stats
868  *   When non-NULL, it contains the current value for the statistics counters
869  *   enabled for the current MTR object.
870  * @param[out] stats_mask
871  *   When non-NULL, it contains the mask of statistics counter types that are
872  *   currently enabled for this MTR object, indicating which of the counters
873  *   retrieved with the *stats* structure are valid.
874  * @param[in] clear
875  *   When this parameter has a non-zero value, the statistics counters are
876  *   cleared (i.e. set to zero) immediately after they have been read,
877  *   otherwise the statistics counters are left untouched.
878  * @param[out] error
879  *   Error details. Filled in only on error, when not NULL.
880  * @return
881  *   0 on success, non-zero error code otherwise.
882  *
883  * @see enum rte_mtr_stats_type
884  */
885 __rte_experimental
886 int
887 rte_mtr_stats_read(uint16_t port_id,
888         uint32_t mtr_id,
889         struct rte_mtr_stats *stats,
890         uint64_t *stats_mask,
891         int clear,
892         struct rte_mtr_error *error);
893
894 #ifdef __cplusplus
895 }
896 #endif
897
898 #endif /* __INCLUDE_RTE_MTR_H__ */