devtools: support FreeBSD
[dpdk.git] / lib / librte_meter / rte_meter.h
1
2 /* SPDX-License-Identifier: BSD-3-Clause
3  * Copyright(c) 2010-2014 Intel Corporation
4  */
5
6 #ifndef __INCLUDE_RTE_METER_H__
7 #define __INCLUDE_RTE_METER_H__
8
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12
13 /**
14  * @file
15  * RTE Traffic Metering
16  *
17  * Traffic metering algorithms:
18  *    1. Single Rate Three Color Marker (srTCM): defined by IETF RFC 2697
19  *    2. Two Rate Three Color Marker (trTCM): defined by IETF RFC 2698
20  *    3. Two Rate Three Color Marker (trTCM): defined by IETF RFC 4115
21  *
22  ***/
23
24 #include <stdint.h>
25
26 #include "rte_compat.h"
27
28 /*
29  * Application Programmer's Interface (API)
30  *
31  ***/
32
33 /**
34  * Color
35  */
36 enum rte_color {
37         RTE_COLOR_GREEN = 0, /**< Green */
38         RTE_COLOR_YELLOW, /**< Yellow */
39         RTE_COLOR_RED, /**< Red */
40         RTE_COLORS /**< Number of colors */
41 };
42
43 /** srTCM parameters per metered traffic flow. The CIR, CBS and EBS parameters only
44 count bytes of IP packets and do not include link specific headers. At least one of
45 the CBS or EBS parameters has to be greater than zero. */
46 struct rte_meter_srtcm_params {
47         uint64_t cir; /**< Committed Information Rate (CIR). Measured in bytes per second. */
48         uint64_t cbs; /**< Committed Burst Size (CBS).  Measured in bytes. */
49         uint64_t ebs; /**< Excess Burst Size (EBS).  Measured in bytes. */
50 };
51
52 /** trTCM parameters per metered traffic flow. The CIR, PIR, CBS and PBS parameters
53 only count bytes of IP packets and do not include link specific headers. PIR has to
54 be greater than or equal to CIR. Both CBS or EBS have to be greater than zero. */
55 struct rte_meter_trtcm_params {
56         uint64_t cir; /**< Committed Information Rate (CIR). Measured in bytes per second. */
57         uint64_t pir; /**< Peak Information Rate (PIR). Measured in bytes per second. */
58         uint64_t cbs; /**< Committed Burst Size (CBS). Measured in bytes. */
59         uint64_t pbs; /**< Peak Burst Size (PBS). Measured in bytes. */
60 };
61
62 /** trTCM parameters per metered traffic flow. The CIR, EIR, CBS and EBS
63 parameters only count bytes of IP packets and do not include link specific
64 headers. The CBS and EBS need to be greater than zero if CIR and EIR are
65 none-zero respectively.*/
66 struct rte_meter_trtcm_rfc4115_params {
67         uint64_t cir; /**< Committed Information Rate (CIR). Measured in bytes per second. */
68         uint64_t eir; /**< Excess Information Rate (EIR). Measured in bytes per second. */
69         uint64_t cbs; /**< Committed Burst Size (CBS). Measured in bytes. */
70         uint64_t ebs; /**< Excess Burst Size (EBS). Measured in bytes. */
71 };
72
73 /**
74  * Internal data structure storing the srTCM configuration profile. Typically
75  * shared by multiple srTCM objects.
76  */
77 struct rte_meter_srtcm_profile;
78
79 /**
80  * Internal data structure storing the trTCM configuration profile. Typically
81  * shared by multiple trTCM objects.
82  */
83 struct rte_meter_trtcm_profile;
84
85 /**
86  * Internal data structure storing the trTCM RFC4115 configuration profile.
87  * Typically shared by multiple trTCM objects.
88  */
89 struct rte_meter_trtcm_rfc4115_profile;
90
91 /** Internal data structure storing the srTCM run-time context per metered traffic flow. */
92 struct rte_meter_srtcm;
93
94 /** Internal data structure storing the trTCM run-time context per metered traffic flow. */
95 struct rte_meter_trtcm;
96
97 /**
98  * Internal data structure storing the trTCM RFC4115 run-time context per
99  * metered traffic flow.
100  */
101 struct rte_meter_trtcm_rfc4115;
102
103 /**
104  * srTCM profile configuration
105  *
106  * @param p
107  *    Pointer to pre-allocated srTCM profile data structure
108  * @param params
109  *    srTCM profile parameters
110  * @return
111  *    0 upon success, error code otherwise
112  */
113 int
114 rte_meter_srtcm_profile_config(struct rte_meter_srtcm_profile *p,
115         struct rte_meter_srtcm_params *params);
116
117 /**
118  * trTCM profile configuration
119  *
120  * @param p
121  *    Pointer to pre-allocated trTCM profile data structure
122  * @param params
123  *    trTCM profile parameters
124  * @return
125  *    0 upon success, error code otherwise
126  */
127 int
128 rte_meter_trtcm_profile_config(struct rte_meter_trtcm_profile *p,
129         struct rte_meter_trtcm_params *params);
130 /**
131  * @warning
132  * @b EXPERIMENTAL: this API may change without prior notice
133  *
134  * trTCM RFC 4115 profile configuration
135  *
136  * @param p
137  *    Pointer to pre-allocated trTCM profile data structure
138  * @param params
139  *    trTCM profile parameters
140  * @return
141  *    0 upon success, error code otherwise
142  */
143 __rte_experimental
144 int
145 rte_meter_trtcm_rfc4115_profile_config(
146         struct rte_meter_trtcm_rfc4115_profile *p,
147         struct rte_meter_trtcm_rfc4115_params *params);
148
149 /**
150  * srTCM configuration per metered traffic flow
151  *
152  * @param m
153  *    Pointer to pre-allocated srTCM data structure
154  * @param p
155  *    srTCM profile. Needs to be valid.
156  * @return
157  *    0 upon success, error code otherwise
158  */
159 int
160 rte_meter_srtcm_config(struct rte_meter_srtcm *m,
161         struct rte_meter_srtcm_profile *p);
162
163 /**
164  * trTCM configuration per metered traffic flow
165  *
166  * @param m
167  *    Pointer to pre-allocated trTCM data structure
168  * @param p
169  *    trTCM profile. Needs to be valid.
170  * @return
171  *    0 upon success, error code otherwise
172  */
173 int
174 rte_meter_trtcm_config(struct rte_meter_trtcm *m,
175         struct rte_meter_trtcm_profile *p);
176
177 /**
178  * @warning
179  * @b EXPERIMENTAL: this API may change without prior notice
180  *
181  * trTCM RFC 4115 configuration per metered traffic flow
182  *
183  * @param m
184  *    Pointer to pre-allocated trTCM data structure
185  * @param p
186  *    trTCM profile. Needs to be valid.
187  * @return
188  *    0 upon success, error code otherwise
189  */
190 __rte_experimental
191 int
192 rte_meter_trtcm_rfc4115_config(struct rte_meter_trtcm_rfc4115 *m,
193         struct rte_meter_trtcm_rfc4115_profile *p);
194
195 /**
196  * srTCM color blind traffic metering
197  *
198  * @param m
199  *    Handle to srTCM instance
200  * @param p
201  *    srTCM profile specified at srTCM object creation time
202  * @param time
203  *    Current CPU time stamp (measured in CPU cycles)
204  * @param pkt_len
205  *    Length of the current IP packet (measured in bytes)
206  * @return
207  *    Color assigned to the current IP packet
208  */
209 static inline enum rte_color
210 rte_meter_srtcm_color_blind_check(struct rte_meter_srtcm *m,
211         struct rte_meter_srtcm_profile *p,
212         uint64_t time,
213         uint32_t pkt_len);
214
215 /**
216  * srTCM color aware traffic metering
217  *
218  * @param m
219  *    Handle to srTCM instance
220  * @param p
221  *    srTCM profile specified at srTCM object creation time
222  * @param time
223  *    Current CPU time stamp (measured in CPU cycles)
224  * @param pkt_len
225  *    Length of the current IP packet (measured in bytes)
226  * @param pkt_color
227  *    Input color of the current IP packet
228  * @return
229  *    Color assigned to the current IP packet
230  */
231 static inline enum rte_color
232 rte_meter_srtcm_color_aware_check(struct rte_meter_srtcm *m,
233         struct rte_meter_srtcm_profile *p,
234         uint64_t time,
235         uint32_t pkt_len,
236         enum rte_color pkt_color);
237
238 /**
239  * trTCM color blind traffic metering
240  *
241  * @param m
242  *    Handle to trTCM instance
243  * @param p
244  *    trTCM profile specified at trTCM object creation time
245  * @param time
246  *    Current CPU time stamp (measured in CPU cycles)
247  * @param pkt_len
248  *    Length of the current IP packet (measured in bytes)
249  * @return
250  *    Color assigned to the current IP packet
251  */
252 static inline enum rte_color
253 rte_meter_trtcm_color_blind_check(struct rte_meter_trtcm *m,
254         struct rte_meter_trtcm_profile *p,
255         uint64_t time,
256         uint32_t pkt_len);
257
258 /**
259  * trTCM color aware traffic metering
260  *
261  * @param m
262  *    Handle to trTCM instance
263  * @param p
264  *    trTCM profile specified at trTCM object creation time
265  * @param time
266  *    Current CPU time stamp (measured in CPU cycles)
267  * @param pkt_len
268  *    Length of the current IP packet (measured in bytes)
269  * @param pkt_color
270  *    Input color of the current IP packet
271  * @return
272  *    Color assigned to the current IP packet
273  */
274 static inline enum rte_color
275 rte_meter_trtcm_color_aware_check(struct rte_meter_trtcm *m,
276         struct rte_meter_trtcm_profile *p,
277         uint64_t time,
278         uint32_t pkt_len,
279         enum rte_color pkt_color);
280
281 /**
282  * @warning
283  * @b EXPERIMENTAL: this API may change without prior notice
284  *
285  * trTCM RFC4115 color blind traffic metering
286  *
287  * @param m
288  *    Handle to trTCM instance
289  * @param p
290  *    trTCM profile specified at trTCM object creation time
291  * @param time
292  *    Current CPU time stamp (measured in CPU cycles)
293  * @param pkt_len
294  *    Length of the current IP packet (measured in bytes)
295  * @return
296  *    Color assigned to the current IP packet
297  */
298 __rte_experimental
299 static inline enum rte_color
300 rte_meter_trtcm_rfc4115_color_blind_check(
301         struct rte_meter_trtcm_rfc4115 *m,
302         struct rte_meter_trtcm_rfc4115_profile *p,
303         uint64_t time,
304         uint32_t pkt_len);
305
306 /**
307  * @warning
308  * @b EXPERIMENTAL: this API may change without prior notice
309  *
310  * trTCM RFC4115 color aware traffic metering
311  *
312  * @param m
313  *    Handle to trTCM instance
314  * @param p
315  *    trTCM profile specified at trTCM object creation time
316  * @param time
317  *    Current CPU time stamp (measured in CPU cycles)
318  * @param pkt_len
319  *    Length of the current IP packet (measured in bytes)
320  * @param pkt_color
321  *    Input color of the current IP packet
322  * @return
323  *    Color assigned to the current IP packet
324  */
325 __rte_experimental
326 static inline enum rte_color
327 rte_meter_trtcm_rfc4115_color_aware_check(
328         struct rte_meter_trtcm_rfc4115 *m,
329         struct rte_meter_trtcm_rfc4115_profile *p,
330         uint64_t time,
331         uint32_t pkt_len,
332         enum rte_color pkt_color);
333
334 /*
335  * Inline implementation of run-time methods
336  *
337  ***/
338
339 struct rte_meter_srtcm_profile {
340         uint64_t cbs;
341         /**< Upper limit for C token bucket */
342         uint64_t ebs;
343         /**< Upper limit for E token bucket */
344         uint64_t cir_period;
345         /**< Number of CPU cycles for each update of C and E token buckets */
346         uint64_t cir_bytes_per_period;
347         /**< Number of bytes to add to C and E token buckets on each update */
348 };
349
350 /* Internal data structure storing the srTCM run-time context per metered traffic flow. */
351 struct rte_meter_srtcm {
352         uint64_t time; /* Time of latest update of C and E token buckets */
353         uint64_t tc;   /* Number of bytes currently available in the committed (C) token bucket */
354         uint64_t te;   /* Number of bytes currently available in the excess (E) token bucket */
355 };
356
357 struct rte_meter_trtcm_profile {
358         uint64_t cbs;
359         /**< Upper limit for C token bucket */
360         uint64_t pbs;
361         /**< Upper limit for P token bucket */
362         uint64_t cir_period;
363         /**< Number of CPU cycles for one update of C token bucket */
364         uint64_t cir_bytes_per_period;
365         /**< Number of bytes to add to C token bucket on each update */
366         uint64_t pir_period;
367         /**< Number of CPU cycles for one update of P token bucket */
368         uint64_t pir_bytes_per_period;
369         /**< Number of bytes to add to P token bucket on each update */
370 };
371
372 /**
373  * Internal data structure storing the trTCM run-time context per metered
374  * traffic flow.
375  */
376 struct rte_meter_trtcm {
377         uint64_t time_tc;
378         /**< Time of latest update of C token bucket */
379         uint64_t time_tp;
380         /**< Time of latest update of P token bucket */
381         uint64_t tc;
382         /**< Number of bytes currently available in committed(C) token bucket */
383         uint64_t tp;
384         /**< Number of bytes currently available in the peak(P) token bucket */
385 };
386
387 struct rte_meter_trtcm_rfc4115_profile {
388         uint64_t cbs;
389         /**< Upper limit for C token bucket */
390         uint64_t ebs;
391         /**< Upper limit for E token bucket */
392         uint64_t cir_period;
393         /**< Number of CPU cycles for one update of C token bucket */
394         uint64_t cir_bytes_per_period;
395         /**< Number of bytes to add to C token bucket on each update */
396         uint64_t eir_period;
397         /**< Number of CPU cycles for one update of E token bucket */
398         uint64_t eir_bytes_per_period;
399         /**< Number of bytes to add to E token bucket on each update */
400 };
401
402 /**
403  * Internal data structure storing the trTCM RFC4115 run-time context per
404  * metered traffic flow.
405  */
406 struct rte_meter_trtcm_rfc4115 {
407         uint64_t time_tc;
408         /**< Time of latest update of C token bucket */
409         uint64_t time_te;
410         /**< Time of latest update of E token bucket */
411         uint64_t tc;
412         /**< Number of bytes currently available in committed(C) token bucket */
413         uint64_t te;
414         /**< Number of bytes currently available in the excess(E) token bucket */
415 };
416
417 static inline enum rte_color
418 rte_meter_srtcm_color_blind_check(struct rte_meter_srtcm *m,
419         struct rte_meter_srtcm_profile *p,
420         uint64_t time,
421         uint32_t pkt_len)
422 {
423         uint64_t time_diff, n_periods, tc, te;
424
425         /* Bucket update */
426         time_diff = time - m->time;
427         n_periods = time_diff / p->cir_period;
428         m->time += n_periods * p->cir_period;
429
430         /* Put the tokens overflowing from tc into te bucket */
431         tc = m->tc + n_periods * p->cir_bytes_per_period;
432         te = m->te;
433         if (tc > p->cbs) {
434                 te += (tc - p->cbs);
435                 if (te > p->ebs)
436                         te = p->ebs;
437                 tc = p->cbs;
438         }
439
440         /* Color logic */
441         if (tc >= pkt_len) {
442                 m->tc = tc - pkt_len;
443                 m->te = te;
444                 return RTE_COLOR_GREEN;
445         }
446
447         if (te >= pkt_len) {
448                 m->tc = tc;
449                 m->te = te - pkt_len;
450                 return RTE_COLOR_YELLOW;
451         }
452
453         m->tc = tc;
454         m->te = te;
455         return RTE_COLOR_RED;
456 }
457
458 static inline enum rte_color
459 rte_meter_srtcm_color_aware_check(struct rte_meter_srtcm *m,
460         struct rte_meter_srtcm_profile *p,
461         uint64_t time,
462         uint32_t pkt_len,
463         enum rte_color pkt_color)
464 {
465         uint64_t time_diff, n_periods, tc, te;
466
467         /* Bucket update */
468         time_diff = time - m->time;
469         n_periods = time_diff / p->cir_period;
470         m->time += n_periods * p->cir_period;
471
472         /* Put the tokens overflowing from tc into te bucket */
473         tc = m->tc + n_periods * p->cir_bytes_per_period;
474         te = m->te;
475         if (tc > p->cbs) {
476                 te += (tc - p->cbs);
477                 if (te > p->ebs)
478                         te = p->ebs;
479                 tc = p->cbs;
480         }
481
482         /* Color logic */
483         if ((pkt_color == RTE_COLOR_GREEN) && (tc >= pkt_len)) {
484                 m->tc = tc - pkt_len;
485                 m->te = te;
486                 return RTE_COLOR_GREEN;
487         }
488
489         if ((pkt_color != RTE_COLOR_RED) && (te >= pkt_len)) {
490                 m->tc = tc;
491                 m->te = te - pkt_len;
492                 return RTE_COLOR_YELLOW;
493         }
494
495         m->tc = tc;
496         m->te = te;
497         return RTE_COLOR_RED;
498 }
499
500 static inline enum rte_color
501 rte_meter_trtcm_color_blind_check(struct rte_meter_trtcm *m,
502         struct rte_meter_trtcm_profile *p,
503         uint64_t time,
504         uint32_t pkt_len)
505 {
506         uint64_t time_diff_tc, time_diff_tp, n_periods_tc, n_periods_tp, tc, tp;
507
508         /* Bucket update */
509         time_diff_tc = time - m->time_tc;
510         time_diff_tp = time - m->time_tp;
511         n_periods_tc = time_diff_tc / p->cir_period;
512         n_periods_tp = time_diff_tp / p->pir_period;
513         m->time_tc += n_periods_tc * p->cir_period;
514         m->time_tp += n_periods_tp * p->pir_period;
515
516         tc = m->tc + n_periods_tc * p->cir_bytes_per_period;
517         if (tc > p->cbs)
518                 tc = p->cbs;
519
520         tp = m->tp + n_periods_tp * p->pir_bytes_per_period;
521         if (tp > p->pbs)
522                 tp = p->pbs;
523
524         /* Color logic */
525         if (tp < pkt_len) {
526                 m->tc = tc;
527                 m->tp = tp;
528                 return RTE_COLOR_RED;
529         }
530
531         if (tc < pkt_len) {
532                 m->tc = tc;
533                 m->tp = tp - pkt_len;
534                 return RTE_COLOR_YELLOW;
535         }
536
537         m->tc = tc - pkt_len;
538         m->tp = tp - pkt_len;
539         return RTE_COLOR_GREEN;
540 }
541
542 static inline enum rte_color
543 rte_meter_trtcm_color_aware_check(struct rte_meter_trtcm *m,
544         struct rte_meter_trtcm_profile *p,
545         uint64_t time,
546         uint32_t pkt_len,
547         enum rte_color pkt_color)
548 {
549         uint64_t time_diff_tc, time_diff_tp, n_periods_tc, n_periods_tp, tc, tp;
550
551         /* Bucket update */
552         time_diff_tc = time - m->time_tc;
553         time_diff_tp = time - m->time_tp;
554         n_periods_tc = time_diff_tc / p->cir_period;
555         n_periods_tp = time_diff_tp / p->pir_period;
556         m->time_tc += n_periods_tc * p->cir_period;
557         m->time_tp += n_periods_tp * p->pir_period;
558
559         tc = m->tc + n_periods_tc * p->cir_bytes_per_period;
560         if (tc > p->cbs)
561                 tc = p->cbs;
562
563         tp = m->tp + n_periods_tp * p->pir_bytes_per_period;
564         if (tp > p->pbs)
565                 tp = p->pbs;
566
567         /* Color logic */
568         if ((pkt_color == RTE_COLOR_RED) || (tp < pkt_len)) {
569                 m->tc = tc;
570                 m->tp = tp;
571                 return RTE_COLOR_RED;
572         }
573
574         if ((pkt_color == RTE_COLOR_YELLOW) || (tc < pkt_len)) {
575                 m->tc = tc;
576                 m->tp = tp - pkt_len;
577                 return RTE_COLOR_YELLOW;
578         }
579
580         m->tc = tc - pkt_len;
581         m->tp = tp - pkt_len;
582         return RTE_COLOR_GREEN;
583 }
584
585 __rte_experimental
586 static inline enum rte_color
587 rte_meter_trtcm_rfc4115_color_blind_check(
588         struct rte_meter_trtcm_rfc4115 *m,
589         struct rte_meter_trtcm_rfc4115_profile *p,
590         uint64_t time,
591         uint32_t pkt_len)
592 {
593         uint64_t time_diff_tc, time_diff_te, n_periods_tc, n_periods_te, tc, te;
594
595         /* Bucket update */
596         time_diff_tc = time - m->time_tc;
597         time_diff_te = time - m->time_te;
598         n_periods_tc = time_diff_tc / p->cir_period;
599         n_periods_te = time_diff_te / p->eir_period;
600         m->time_tc += n_periods_tc * p->cir_period;
601         m->time_te += n_periods_te * p->eir_period;
602
603         tc = m->tc + n_periods_tc * p->cir_bytes_per_period;
604         if (tc > p->cbs)
605                 tc = p->cbs;
606
607         te = m->te + n_periods_te * p->eir_bytes_per_period;
608         if (te > p->ebs)
609                 te = p->ebs;
610
611         /* Color logic */
612         if (tc >= pkt_len) {
613                 m->tc = tc - pkt_len;
614                 m->te = te;
615                 return RTE_COLOR_GREEN;
616         }
617         if (te >= pkt_len) {
618                 m->tc = tc;
619                 m->te = te - pkt_len;
620                 return RTE_COLOR_YELLOW;
621         }
622
623         /* If we end up here the color is RED */
624         m->tc = tc;
625         m->te = te;
626         return RTE_COLOR_RED;
627 }
628
629 __rte_experimental
630 static inline enum rte_color
631 rte_meter_trtcm_rfc4115_color_aware_check(
632         struct rte_meter_trtcm_rfc4115 *m,
633         struct rte_meter_trtcm_rfc4115_profile *p,
634         uint64_t time,
635         uint32_t pkt_len,
636         enum rte_color pkt_color)
637 {
638         uint64_t time_diff_tc, time_diff_te, n_periods_tc, n_periods_te, tc, te;
639
640         /* Bucket update */
641         time_diff_tc = time - m->time_tc;
642         time_diff_te = time - m->time_te;
643         n_periods_tc = time_diff_tc / p->cir_period;
644         n_periods_te = time_diff_te / p->eir_period;
645         m->time_tc += n_periods_tc * p->cir_period;
646         m->time_te += n_periods_te * p->eir_period;
647
648         tc = m->tc + n_periods_tc * p->cir_bytes_per_period;
649         if (tc > p->cbs)
650                 tc = p->cbs;
651
652         te = m->te + n_periods_te * p->eir_bytes_per_period;
653         if (te > p->ebs)
654                 te = p->ebs;
655
656         /* Color logic */
657         if ((pkt_color == RTE_COLOR_GREEN) && (tc >= pkt_len)) {
658                 m->tc = tc - pkt_len;
659                 m->te = te;
660                 return RTE_COLOR_GREEN;
661         }
662
663         if ((pkt_color != RTE_COLOR_RED) && (te >= pkt_len)) {
664                 m->tc = tc;
665                 m->te = te - pkt_len;
666                 return RTE_COLOR_YELLOW;
667         }
668
669         /* If we end up here the color is RED */
670         m->tc = tc;
671         m->te = te;
672         return RTE_COLOR_RED;
673 }
674
675
676 #ifdef __cplusplus
677 }
678 #endif
679
680 #endif /* __INCLUDE_RTE_METER_H__ */