[patch mlxsw.wiki] ACLs: Add shared blocks

[Jiri Pirko]

From: Jiri Pirko <jiri at mellanox.com>

Signed-off-by: Jiri Pirko <jiri at mellanox.com>
---
 ACLs.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 63 insertions(+), 2 deletions(-)

diff --git a/ACLs.md b/ACLs.md
index 79a5c9aa3ee0..ffcf66b4ac4d 100644
--- a/ACLs.md
+++ b/ACLs.md
@@ -7,7 +7,8 @@
     5. [Trap Action Example Usage](#trap-action-example-usage)
     6. [Multi-table/Multi-chain Support](#multi-tablemulti-chain-support)
     7. [Mirred Action Example Usage](#mirred-action-example-usage)
-    8. [More Examples](#more-examples)
+    8. [Shared Blocks Support](#shared-blocks-support)
+    9. [More Examples](#more-examples)
 2. [Further Resources](#further-resources)
 
 TC Flower
@@ -162,6 +163,66 @@ address `fe01::1`. The selected action is `mirred`.
 This rule insertion instructs the hardware to redirect/mirror matched packet
 to the specified interface, enp3s0np2 in the example.
 
+#### Shared Blocks Support
+
+By default, each qdisc has its own group of chains (each contains filters).
+This group of chains is called `block`. For example for `ingress`
+qdisc the mapping between netdev:qdisc:block is 1:1:1.
+
+But consider a case when you have 2 netdevices, you create ingress qdisc
+on both. Now if you want to add identical set of filter rules to both,
+you need to add them twice. One for each netdev:qdisc:block. That is
+of course doable, but when the filters are offloaded to TCAM with limited
+number of entries, the duplications may become a scale issue. Sharing of
+blocks is aiming to resolve that.
+
+In order to ask kernel to share blocks, one has to indicate so during qdisc
+creation:
+
+```
+$ tc qdisc add dev enp3s0np1 ingress_block 22 ingress
+$ tc qdisc add dev enp3s0np2 ingress_block 22 ingress
+```
+
+These two commands added ingress qdiscs to both netdevices. Note the
+"ingress_block" option that indicates that both qdiscs should share the same
+block identified by index "22". It is up to the user to choose the
+block index.
+
+If you list the existing qdiscs, you see the block sharing info in the output:
+
+```
+$ tc qdisc
+qdisc ingress ffff: dev enp3s0np1 parent ffff:fff1 ingress_block 22
+qdisc ingress ffff: dev enp3s0np2 parent ffff:fff1 ingress_block 22
+```
+
+To make it more visual, the situation looks like this:
+
+```
+   enp3s0np1 ingress qdisc            enp3s0np2 ingress qdisc
+              |                                  |
+              |                                  |
+              +---------->  block 22  <----------+
+```
+
+There is no limitation in number of qdiscs that can share the same block.
+
+Once the qdisc block is shared, it is no longer possible to manipulate
+the filters using the qdisc handle. One has to rather use the block
+index as a handle:
+
+```
+$ tc filter add block 22 protocol ip pref 25 flower dst_ip 192.168.0.0/16 action drop
+```
+
+Aside of the `ingress` qdisc, the block sharing is also supported for `clsact`
+qdisc. For that, user can decide to share ingress and egress block:
+
+```
+$ tc qdisc add dev enp3s0np3 ingress_block 23 egress_block 24 clsact
+```
+
 #### More Examples
 
 ```
@@ -186,4 +247,4 @@ Further Resources
 3. [QoS in Linux with TC and Filters][1] by Phil Sutter (part of `iproute`
 documentation)
 
-[1]: https://github.com/Mellanox/mlxsw/wiki/tc-filters.pdf
\ No newline at end of file
+[1]: https://github.com/Mellanox/mlxsw/wiki/tc-filters.pdf
-- 
2.14.3