14 files changed, 236 insertions, 4 deletions
diff --git a/docs/_images/policer-1r2c-aware.png b/docs/_images/policer-1r2c-aware.png
new file mode 100644
index 00000000000..8eb4f8d341f
--- /dev/null
+++ b/docs/_images/policer-1r2c-aware.png
diff --git a/docs/_images/policer-1r2c-blind.png b/docs/_images/policer-1r2c-blind.png
new file mode 100644
index 00000000000..ec8a1dd62f4
--- /dev/null
+++ b/docs/_images/policer-1r2c-blind.png
diff --git a/docs/_images/policer-1r2c-bucket.png b/docs/_images/policer-1r2c-bucket.png
new file mode 100644
index 00000000000..dc4587074d7
--- /dev/null
+++ b/docs/_images/policer-1r2c-bucket.png
diff --git a/docs/_images/policer-1r3c-aware.png b/docs/_images/policer-1r3c-aware.png
new file mode 100644
index 00000000000..6a904b5abc7
--- /dev/null
+++ b/docs/_images/policer-1r3c-aware.png
diff --git a/docs/_images/policer-1r3c-blind.png b/docs/_images/policer-1r3c-blind.png
new file mode 100644
index 00000000000..1bcef6adf6d
--- /dev/null
+++ b/docs/_images/policer-1r3c-blind.png
diff --git a/docs/_images/policer-1r3c-bucket.png b/docs/_images/policer-1r3c-bucket.png
new file mode 100644
index 00000000000..24094ee79f8
--- /dev/null
+++ b/docs/_images/policer-1r3c-bucket.png
diff --git a/docs/_images/policer-2r3c-aware.png b/docs/_images/policer-2r3c-aware.png
new file mode 100644
index 00000000000..214dc62c6aa
--- /dev/null
+++ b/docs/_images/policer-2r3c-aware.png
diff --git a/docs/_images/policer-2r3c-blind.png b/docs/_images/policer-2r3c-blind.png
new file mode 100644
index 00000000000..a2faa1fb9f4
--- /dev/null
+++ b/docs/_images/policer-2r3c-blind.png
diff --git a/docs/_images/policer-2r3c-bucket.png b/docs/_images/policer-2r3c-bucket.png
new file mode 100644
index 00000000000..a0c427281be
--- /dev/null
+++ b/docs/_images/policer-2r3c-bucket.png
diff --git a/docs/developer/corefeatures/index.rst b/docs/developer/corefeatures/index.rst
index 1012387a17a..8daadaabc27 100644
--- a/docs/developer/corefeatures/index.rst
+++ b/docs/developer/corefeatures/index.rst
@@ -20,3 +20,4 @@ Core Features
     eventviewer
     stats
     selinux_doc
+    policer
diff --git a/docs/developer/corefeatures/policer.rst b/docs/developer/corefeatures/policer.rst
new file mode 120000
index 00000000000..cc75a1a6ec0
--- /dev/null
+++ b/docs/developer/corefeatures/policer.rst
@@ -0,0 +1 @@
+../../../src/vnet/policer/policer.rst
+\ No newline at end of file
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 97bd0b573e1..8ab46744793 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -113,6 +113,7 @@ buildingrst
 builtin
 builtinurl
 Builtinurl
+burstiness
 busybox
 BV
 bvi
@@ -843,6 +844,8 @@ Pnat
 PoC
 podSubnet
 policer
+Policer
+policers
 Policers
 Pollable
 portranges
diff --git a/src/vnet/policer/policer.c b/src/vnet/policer/policer.c
index 9dd50b83d24..8389a5ead48 100644
--- a/src/vnet/policer/policer.c
+++ b/src/vnet/policer/policer.c
@@ -694,13 +694,23 @@ done:
 
 VLIB_CLI_COMMAND (configure_policer_command, static) = {
   .path = "configure policer",
-  .short_help = "configure policer name <name> <params> ",
+  .short_help = "configure policer name <name> [type 1r2c | 1r3c | 2r3c-2698 "
+		"| 2r3c-4115] [color-aware] [cir <cir>] [cb <cb>] [eir <eir>] "
+		"[eb <eb>] [rate kbps | pps] [round closest | up | down] "
+		"[conform-action drop | transmit | mark-and-transmit <dscp>] "
+		"[exceed-action drop | transmit | mark-and-transmit <dscp>] "
+		"[violate-action drop | transmit | mark-and-transmit <dscp>]",
   .function = policer_add_command_fn,
 };
 
 VLIB_CLI_COMMAND (policer_add_command, static) = {
   .path = "policer add",
-  .short_help = "policer name <name> <params> ",
+  .short_help = "policer name <name> [type 1r2c | 1r3c | 2r3c-2698 | "
+		"2r3c-4115] [color-aware] [cir <cir>] [cb <cb>] [eir <eir>] "
+		"[eb <eb>] [rate kbps | pps] [round closest | up | down] "
+		"[conform-action drop | transmit | mark-and-transmit <dscp>] "
+		"[exceed-action drop | transmit | mark-and-transmit <dscp>] "
+		"[violate-action drop | transmit | mark-and-transmit <dscp>]",
   .function = policer_add_command_fn,
 };
 
@@ -718,14 +728,14 @@ VLIB_CLI_COMMAND (policer_bind_command, static) = {
 
 VLIB_CLI_COMMAND (policer_input_command, static) = {
   .path = "policer input",
-  .short_help = "policer input [unapply] name <name> <interfac>",
+  .short_help = "policer input [unapply] name <name> <interface>",
   .function = policer_input_command_fn,
   .function_arg = VLIB_RX,
 };
 
 VLIB_CLI_COMMAND (policer_output_command, static) = {
   .path = "policer output",
-  .short_help = "policer output [unapply] name <name> <interfac>",
+  .short_help = "policer output [unapply] name <name> <interface>",
   .function = policer_input_command_fn,
   .function_arg = VLIB_TX,
 };
diff --git a/src/vnet/policer/policer.rst b/src/vnet/policer/policer.rst
new file mode 100644
index 00000000000..0e7369e373b
--- /dev/null
+++ b/src/vnet/policer/policer.rst
@@ -0,0 +1,217 @@
+.. _policer:
+
+Policing
+========
+
+VPP implements several policer types, that don't always conform
+to the related RFCs [#rfc2697]_ [#rfc2698]_ [#rfc4115]_.
+Only policers implemented in VPP will be presented, along with
+the differences they have compared to RFCs.
+
+.. contents:: :local:
+   :depth: 1
+
+
+1 rate 2 color (1r2c)
+---------------------
+
+This is the most straightforward policer. There is no RFC describing it,
+however we can found its description in many documentation [#juniper]_ [#cisco]_ .
+
+A 1r2c policer is great to classify incoming packets into two categories:
+conforming packets (said green), and violating ones (said red).
+
+Parameters
+~~~~~~~~~~
+
+To set-up such a policer, only two parameters are needed:
+
+Committed Information Rate (CIR)
+  Given in bytes per second, this parameter is the average
+  throughput allowed by the policer.
+
+  It sets the limit between conforming arriving packets (those making the
+  traffic fall below the CIR), and violating arriving packets
+  (those making the traffic exceed the CIR).
+
+Committed Burst Size (CBS)
+  It represents the size (in bytes) of a token bucket used to allow
+  some burstiness from the incoming traffic.
+
+.. figure:: /_images/policer-1r2c-bucket.png
+   :align: center
+   :scale: 25%
+
+   Figure 1: 1r2c bucket filling logic
+
+The committed token bucket (C) is filling up at CIR tokens (bytes)
+per second, up to CBS tokens. All overflowing tokens are lost.
+
+Color-Blind algorithm
+~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /_images/policer-1r2c-blind.png
+   :align: center
+   :scale: 75%
+
+|
+
+Color-Aware algorithm
+~~~~~~~~~~~~~~~~~~~~~
+
+In online documentation, there is no trace of a color-aware 1r2c policer.
+However, VPP implementation allows such a thing.
+
+.. image:: /_images/policer-1r2c-aware.png
+   :align: center
+   :scale: 75%
+
+|
+
+
+1 rate 3 color (1r3c) RFC 2697 [#rfc2697]_
+------------------------------------------
+
+As for the `1 rate 2 color (1r2c)`_ policer, only one rate parameters is required
+to setup a 1r3c policer. However, such a policer adds another kind of packet category:
+exceeding ones (said yellow).
+
+Parameters
+~~~~~~~~~~
+
+To set-up such a policer, three parameters are needed:
+
+Committed Information Rate (CIR)
+  As in the `1 rate 2 color (1r2c)`_ policer.
+
+Committed Burst Size (CBS)
+  As in the `1 rate 2 color (1r2c)`_ policer.
+
+Excess Burst Size (EBS)
+  It represents the size (in bytes) of a second token bucket used
+  to allow an additional burstiness from the incoming traffic, when
+  traffic as been below the CIR for some time.
+
+.. figure:: /_images/policer-1r3c-bucket.png
+   :align: center
+   :scale: 25%
+
+   Figure 2: 1r3c buckets filling logic
+
+The committed token bucket (C) is filling up at CIR tokens (bytes)
+per second, up to CBS tokens. When C is full, tokens are overflowing
+into the excess token bucket (E), up to EBS tokens. Only overflowing
+tokens from E are lost.
+
+Color-Blind algorithm
+~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /_images/policer-1r3c-blind.png
+   :align: center
+   :scale: 75%
+
+|
+
+Color-Aware algorithm
+~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /_images/policer-1r3c-aware.png
+   :align: center
+   :scale: 75%
+
+|
+
+Notes
+~~~~~
+
+In the RFC 2697 [#rfc2697]_ describing the 1r3c policer, conforming (green) packets
+only consume tokens from the token bucket C. Whereas, in VPP, they also consume tokens from E.
+
+One way to stick to the RFC is then to set the EBS parameter to be superior to CBS, so that
+EBS - CBS corresponds to the EBS from the RFC.
+
+However, VPP does not enforce setting EBS > CBS, which could result in undesired behavior.
+
+2 rate 3 color (2r3c) RFC 2698 [#rfc2698]_
+------------------------------------------
+
+Instead of setting the limit between yellow and red packets in terms of bursts,
+as it is done by `1 rate 3 color (1r3c) RFC 2697`_ policers, two rate policers introduce
+another rate parameter to discriminate between those two kinds of packets.
+
+Parameters
+~~~~~~~~~~
+
+To set-up such a policer, four parameters are needed:
+
+Committed Information Rate (CIR)
+  As in the `1 rate 2 color (1r2c)`_ policer.
+
+Committed Burst Size (CBS)
+  As in the `1 rate 2 color (1r2c)`_ policer.
+
+Peak Information Rate (PIR)
+  Given in bytes per second, this parameter is the average
+  throughput allowed by the policer when there is a peak in
+  traffic.
+
+  It sets a second limit between exceeding arriving packets
+  (those making the traffic fall below the PIR, but above CIR),
+  and violating arriving packets (those making the traffic exceed the PIR).
+
+Peak Burst Size (PBS)
+  It represents the size (in bytes) of a second token bucket used
+  to allow an additional peak traffic.
+
+.. figure:: /_images/policer-2r3c-bucket.png
+   :align: center
+   :scale: 25%
+
+   Figure 2: 2r3c-rfc2698 buckets filling logic
+
+The committed token bucket (C) is filling up at CIR tokens (bytes)
+per second, up to CBS tokens. In the meantime, the peak token bucket (P)
+is filling up at PIR tokens per second, up to PBS. All overflowing tokens
+from C and P are lost.
+
+Color-Blind algorithm
+~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /_images/policer-2r3c-blind.png
+   :align: center
+   :scale: 75%
+
+|
+
+Color-Aware algorithm
+~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: /_images/policer-2r3c-aware.png
+   :align: center
+   :scale: 50%
+
+|
+
+Notes
+~~~~~
+
+To have a working policer, the condition PIR >= CIR needs to hold.
+Indeed, since we assume that peak traffic should have a greater
+rate than committed ones.
+
+
+2 rate 3 color (2r3c) RFC 4115 [#rfc4115]_
+------------------------------------------
+
+The 2r3c-RFC4115 is an allowed choice by VPP. However, there is currently
+no implementation of such a policer. Hence, the only two rate policer VPP
+implements is the `2 rate 3 color (2r3c) RFC 2698`_ policer.
+
+
+.. rubric:: References:
+
+.. [#juniper] https://www.juniper.net/documentation/us/en/software/junos/traffic-mgmt-nfx/routing-policy/topics/concept/tcm-overview-cos-qfx-series-understanding.html
+.. [#cisco] https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/qos_mqc/configuration/xe-16-8/qos-mqc-xe-16-8-book/qos-pkt-policing.html
+.. [#rfc2697] https://www.rfc-editor.org/rfc/rfc2697.html
+.. [#rfc2698] https://www.rfc-editor.org/rfc/rfc2698.html
+.. [#rfc4115] https://www.rfc-editor.org/rfc/rfc4115.html