DPDK patches and discussions
 help / color / mirror / Atom feed
* [dpdk-dev] [PATCH v1] doc: Merge l3fwd and l3fwd-acl documentation files
@ 2017-04-25 18:39 Ravi Kerur
  2017-05-05 16:15 ` Mcnamara, John
                   ` (2 more replies)
  0 siblings, 3 replies; 10+ messages in thread
From: Ravi Kerur @ 2017-04-25 18:39 UTC (permalink / raw)
  To: dev, konstantin.ananyev; +Cc: Ravi Kerur

Merge relevant contents of l3fwd and l3fwd-acl documentation.
Modify l3fwd document with ACL specific information.
Remove l3fwd-acl documentation file.

Signed-off-by: Ravi Kerur <rkerur@gmail.com>
---
 doc/guides/sample_app_ug/img/ipv4_hash_rule.svg    | 158 +++++++++
 doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg     | 139 ++++++++
 doc/guides/sample_app_ug/index.rst                 |   1 -
 doc/guides/sample_app_ug/l3_forward.rst            | 326 ++++++++++++++++-
 .../sample_app_ug/l3_forward_access_ctrl.rst       | 385 ---------------------
 5 files changed, 614 insertions(+), 395 deletions(-)
 create mode 100644 doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
 create mode 100644 doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
 delete mode 100644 doc/guides/sample_app_ug/l3_forward_access_ctrl.rst

diff --git a/doc/guides/sample_app_ug/img/ipv4_hash_rule.svg b/doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
new file mode 100644
index 0000000..89d563f
--- /dev/null
+++ b/doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.91 r13725"
+   width="819"
+   height="460"
+   viewBox="0 0 819 460"
+   sodipodi:docname="ipv4_hash_rule.svg">
+  <metadata
+     id="metadata8">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs6" />
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="640"
+     inkscape:window-height="480"
+     id="namedview4"
+     showgrid="false"
+     inkscape:zoom="0.47252747"
+     inkscape:cx="409.5"
+     inkscape:cy="230"
+     inkscape:window-x="65"
+     inkscape:window-y="24"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="svg2" />
+  <image
+     width="819"
+     height="460"
+     preserveAspectRatio="none"
+     xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAzMAAAHMCAIAAABukmEEAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
+jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAABTgSURBVHhe7drrgaM2GAXQ1LUFbT1bzTaTYhLE
+yxIGj2f8mCvmnF8gQHwCLN2d5J//AADIIJkBAKSQzAAAUkhmAAApJDMAgBSSGQBACskMACCFZAYA
+kEIyAwBIIZkBAKSQzAAAUkhmAAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBIIZkBAKSQzAAAUkhm
+AAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBIIZkBAKSQzAAAUkhmAAApJDMAgBSSGQBACskMACCF
+ZAYAkEIyAwBIIZkBAKSQzAAAUkhmAAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBIIZkBAKSQzAAA
+UkhmAAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBIIZkBAKSQzAAAUkhmAAApJDMAgBSSGQBACskM
+ACCFZAYAkEIyAwBIIZkBAKSQzAAAUkhmAAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBIIZkBAKSQ
+zAAAUkhmAAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBIIZkBAKSQzAAAUkhmAAApJDMAgBSSGQBA
+CskMACCFZAYAkEIyAwBIIZkBAKSQzAAAUkhmAAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBIIZkB
+AKSQzAAAUkhmAAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBIIZkBAKSQzAAAUkhmAAApJDMAgBSS
+GQBACskMACCFZAYAkEIyAwBIIZkBAKSQzAAAUkhmAAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBI
+IZkBAKSQzAAAUkhmAAApJDMAgBSSGQBACskMACCFZAYAkEIyAwBIIZkBAKSQzAAAUkhmAAApJDMA
+gBSSGQBACskMACCFZAYAkKKDZPYPAHxkXjOgc30ks3kLAPZYKTgNyQyA7lkpOA3JDIDuWSk4DckM
+gO5ZKTgNyQyA7lkpOA3JDIDuWSk4DckMgO5ZKTgNyQyA7lkpOA3JDIDuWSk4DckMgO5ZKTgNyQyA
+7lkpOA3JDIDuWSk4DckMgO5ZKTgNyQyA7lkpOA3JDIDuWSk4DckMgO5ZKTgNyQyA7lkpOA3JDIDu
+WSk4DckMgO5ZKTgNyQyA7lkpOA3JDIDuWSk4DckMgO5ZKTgNyQyA7lkpOA3JDIDuWSk4DckMgO5Z
+KTgNyQyA7lkpOA3JDIDuWSk4DckMgO5ZKTgNyQyA7lkpOA3JDIDuWSk4DckMgO5ZKTgNyQyA7lkp
+OA3JDIDuWSk4DckMgO5ZKTgNyQyA7lkpOA3JDIDuWSk4DckMgO5ZKTgNyQzghf7+/uef33/nHV7G
+SsFpSGbwc/z759fwe7q4HRjK2S+IFC/qdlWS0MWn7/T08vpPZstn8+vPv3NLoqHAeQs6J5nxAsNa
+tDuJH7WHqJb096+kr84ro3KTyxsYx3vjhbyopFePtP7KxkzxuZs9vbzymF/+ZkfjaFf3/NSOBltq
+Xq9/3wAeMgx53oLOSWZ3qGf62lF7onbO/miivb04lYn6dg89PrHxCS2D+vv77XXefuZPUm7SjKy8
+y/mu1ScynFLtbdf44dDQMH0Fm4P1Vetgxrf+Zzr916/Dbp+m/crWEdZlTLVdV7s76t1BNc1L6/6Z
+awWvVW5T3Wes5cMnXM76sLb2gcYahj9vQec6T2bjZDT58tQ39XHr8qOJqZMJa1Rm4Eux45hv1H5z
+vi7D/v375oTe4xNrn9BirLhezscFb9I+gOHAcPn4ZIu6q+qay0V1z+/IK6PrQZaCS03lyPaN7rUN
+puHM3Yw700nVZrMzPZNLRwfdPs34ZJcxlptNe5syjqrdlHd0WultucuU4w87XB7xS5UbXkY9udy4
+HL2UMD+gscbF5tr10uakl4/iIUOB8xZ0rudkVk9+8+T4BWWWOmHO2LqauNept5l8h1NuzdfFNOpy
+VvvILteNgWO9cr997OWDP2AUVet85XXLk0wdb/osj6mqp+wuZ2w+uebycaca19JBtbPpeTx02XuR
+cpN2hKWMctumzNlBSZvm8VUOXW7PXtrXWywOun2a9cbT9rLTlnFYbXvk6LS2s+K4w+tzn6/cfR30
+aq2hLe5S2lXVi6bm6vxkw89p3oLO9Z7MDiaju/7IMZomnev56XJVpzljo9ynvcEy95Yj2wez1zZb
+ZulNh/Vu6XnZOWoft6t7LNUUl2uu67hueaqprOpd1HVt91qbyoZTx062BS/tV329eGSTcpN1bKOq
+jHKwGfxBSZvmpYfDAb17pOV+q8to2zKOi2rKOzptaG+f440Ot0deYf+ZrnduD1fF71+3qbk6P9nw
+tuct6FzPyWycVeqpd1SmlHZSWc/Y+bvaMueUrqqD9e7Y4bxz1L656bi/7F2uKVvtLHjd8ip15ZOl
+xnJkW8RhXVU3TY+bC4a+d4e8tjdPaNPXYDmvtLeFXLe8wHiTqZ62zkv9166HOu62HVSnHR54pXKT
+ZgTbKgaXpoOSrke6vqz67KX97SNdb9xqyzistj1ydNp2TLc6vD73+crdrwe91tAWdyntqupFU3N1
+frJhCp63oHNdJ7OizCDFOnM0U8pmb6uazpqZbTNdrRPTUfvmNk1fg+W80t5Wc93yKtuamprHMuqH
+WBr2ymp6qXfaB3B5MkftmwNLAZWl56vadlqer9xjLK+tczOcxnrJZBnqpvnyCLZ9bU98iXKTzZO8
+eoyXQtqzV+Nly4HqnLF9GULVvjfSnW6fZn3ErU0ZR9Vuyjs6rfS2nHXw/5ldDrfjf4m9m1zaSjmX
+o0P7Ult74KLprjo/2fBRzlvQue6T2WScFKfJo52hbs4p9ex5aypdOzlq3xwYq2ktPS+H1tvutLxE
+M9ZiM5bi0lTO3hwsjge2uWB9MkftO09s536V63KvWx4ylHB5PqXvaW9zl8uBsn25YDA9nLmp7FSb
+axdV+7b+6tDrTEWuqvuVchZrWcvpbV2l9fff9YJ6EFUvl2u2Iz3o9mmG++31fFXGfrXX5X1wWtW6
+f+b1jV9hLKe6a7t/qWEqezlQ9qqLVk3Nw87eOWmGYc1b0LmTJLNphhlnknYavDUpTlNUY55/1s4m
+68R01L65zea0Hddl3Sr0GUpNl9l1HPrVZHupuz17UWpsWsdupiuqY2PrsnOrvRrv/g0r5YT2+Vy3
+PGiqb7LWcvVeLmdt6p3qKeeP6ovWxvqiw55vPocET3/yPEn1oV19R9WXOWyuBw++uubrrM8PNoxi
+3oLOdZzMhinlMl2UiWTaa6aU+kDZrueX+shonKOmS6tj08w179xqr25ajjVdb5UT2rXtuuW5pnJX
+VXWl9sVawXJ6PYrNIEdV2+UOv/8O2+uV++3XnV3OK6bTrmvbrTZCqT+rolf5OSOlJ8OUMG9B5zpO
+Zu1avgaBqyX/clYdM3aiQdN2uepn5gw+q7zxn/EOf85I6ckwic5b0LmukxnkkFfgO1kpOA3JDPiJ
+homlNrfSLS+R05DM+JxxFfvAfCrkmb/Rq690bvX1dsu74zQ6+JT93hKMa1Yx7980n+rFdW5+i5X5
+QJ/uHMKdp3VkGtGR+aT+nWks/HAdfMpv+72N09S++YyfZx7/V5/AI9fyjY5eXL9v87OVjw+g7093
+GsJg3j8wn9T5YAcnGAJMOviUX/p7G2ek2dy0Zz6jMh84rycO84ld8Qa3X1Z3b/ORgvsa6eprQ/7a
+VTm6Lh5qHXzKr/i9jVNQMe9/3nz9GeeCF43rRd2+0zSE1dx6LneOq5fhP15nedP9vOvHq328h+/S
+adlwrYNP+Ym/t3HOKeb9Z5h7PMWk8IaB9Pugrisfn9YZ3vvqU8MJH/v4cp5WYfhgB08f7xN7e4/u
+CoYjHXzKT/m9jfPMawc73WIw73flnZW/815PcbvgvsZywxcGMj6YxOG/oqrkwb6osNf1/AodlQq3
+dfApP/J7GyeWYt5/i/mWnUwT31VqR89n3jrWy1hueGQIacN/aT1Rgx2KeUM977nL47ooEu5x2t/b
+OJl88+imGgbzfphvr+3bC/jQ/eWFD+S2x4vPGf4bKgkZ7JvLGG4XMvAj4eXB/Tr4lD/7exsnkKxx
+pZUUVU/Uk6l9trDYgdz2rLK/ffhDAW+r4Z334k7eCKfRwad8/+9tnC1zRzSVN5j3v8O3F7ArsKov
+1JM2hHs8t+ZvfALfcuse3/iJeR2cRgef8j2/t+Gcjn6W31Ltt9z0U3LK+3Il4U944xXVfssT+MbH
+3tcbPzfvgtPo4FO+/Xsbjnb6g5wqH8z7L/OeuzxFSKmP1JBQ/z1eV2cvT4CT8eFxGh18yke/t6H9
+HD/Flw6kx0f0vTU/fvcenzn0zu+O0+jgU979vZ3vRziM6HyD6s6zXoFXCW/mR8dpdPAp+73xHr40
+6JffL6chmQHQPSsFpyGZAZzCv39+DdPl6Pffue3nGEY9b0HnJDPgLD4TTapzf/35d27s2d/f60iq
+zZ9jeJHzFnROMgPO4RPRpMSyk0WXMuQ1jpbx/bQ/m1kpOA3JDDiF3WhSR7DL9nDqyXLZJmu2ez+D
+lYLTkMzOr0zSV39A2GmcmkZH/9r+ylWPn/BGOwP82qh5u/JOLi/psrdsVcfHzV/neoXt8M+YPT8y
+vMl5CzrXdTIrc1FtnYmmA83EVJ1bz8M7Z7bu76r2Qbd39PAk03/U+TvcryrmRuO4W21WHrnqkRPe
+Zrr9U54V36D8qtqXtOyNL2kIYuvR+q2NP8YTZLN2+JuH8SMM0+m8BZ3rPpldTanTpHvPUrp7Zu3+
+rmp3dnujh6fbnabbxlLJ+ix3H+zkk1c9fsK7tQOcfXLU/SjVX32C9zdGaV9Su1deWfWart5g8rju
+daLP8muOVwrozPmS2eR6Xj6asz6cl+/vqnbc7TdMoLvFNI3tGcfFf/Kqx094u90amsa8mr+mfIgH
+//C4pzHP4S9rOPDrz5/q6I332bFq/M2j+CkkM07jRySzdurdTMQfzsv3d1U7PHR3D0+0e5emcXPG
+uJTtVvW5qx4/4e02FU0+N+qufDzexW5jlOFV7ESTZbPUv7RVYymHe36BtXGIo7OM6DOGYc9b0Lnu
+k1mlDmnNKtLsbJfSzcFr93dVO+z27h6eaLeYG+M6LP6zVz1+wtvt1tA05tX8iI/Hu+hhpKXGyVLp
+ksuKegSXM5uJg34Nr3Legs51n8wOZtVmFWl2Nnvb3Wv3d1U7PHR3D0+0e5e2sV7AxkP3PNiPr3r8
+hHdrBzj75Kh7csd4Z7uNkEIy4zR+RDK7uZR+uN7c31XtuNtvWNd3i9k0VmVdNss5bX2fveprJ3yj
+zQAn94y6U/eMd7LbCCkkM07jZySzW0vp5syy23Z6T1cfXlWfcKOYpys3qI0l7TbONdYN12XX7rvq
+ayd8iwefVafKSK7GcH8jpBh+jfMWdK77ZFYbl437l9LdM8fzHsoiH3a72wN8i/ItXn2F9zdCimE+
+nbegc10nM+DLdv8JcX8jZBm+zHkLOieZAdA9KwWnIZkB0D0rBachmQHQPSsFpyGZAdA9KwWnIZkB
+0D0rBachmQHQPSsFpyGZAdA9KwWnIZkB0D0rBachmQHQPSsFpyGZAdA9KwWnIZkB0D0rBafRRzID
+gNvmNQM651MGAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDM
+AABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAK
+yQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEA
+pJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZ
+AEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEgh
+mQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCA
+FJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjID
+AEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkk
+MwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQ
+QjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYA
+ACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVk
+BgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABS
+SGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwA
+IIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDM
+AABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAK
+yQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEA
+pJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZ
+AEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEgh
+mQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCA
+FJIZAEAKyQwAIIVkBgCQQjIDAEghmQEApJDMAABSSGYAACkkMwCAFJIZAEAKyQwAIIVkBgCQQjID
+AEghmQEApJDMAAAy/Pff/3eU/2CcVgwUAAAAAElFTkSuQmCC
+"
+     id="image10"
+     x="0"
+     y="0" />
+</svg>
diff --git a/doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg b/doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
new file mode 100644
index 0000000..dcb63b6
--- /dev/null
+++ b/doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.91 r13725"
+   width="819"
+   height="460"
+   viewBox="0 0 819 460"
+   sodipodi:docname="ipv4_lpm_rule.svg">
+  <metadata
+     id="metadata8">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs6" />
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="640"
+     inkscape:window-height="480"
+     id="namedview4"
+     showgrid="false"
+     inkscape:zoom="0.47252747"
+     inkscape:cx="409.5"
+     inkscape:cy="230"
+     inkscape:window-x="65"
+     inkscape:window-y="24"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="svg2" />
+  <image
+     width="819"
+     height="460"
+     preserveAspectRatio="none"
+     xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAzMAAAHMCAIAAABukmEEAAAAAXNSR0IArs4c6QAAAARnQU1BAACx
+jwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAABCISURBVHhe7dthkqJKGobRWlcvqNbTq6nN9GLu
+BURMFC2zSslX85wfM2oBgvSXPDER8/EfAAAZlBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+AQCkUGYAACmUGQBACmUGAJBCmQEApFBmAAAplBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+AQCkUGYAACmUGQBACmUGAJBCmQEApFBmAAAplBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+AQCkUGYAACmUGQBACmUGAJBCmQEApFBmAAAplBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+AQCkUGYAACmUGQBACmUGAJBCmQEApFBmAAAplBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+AQCkUGYAACmUGQBACmUGAJBCmQEApFBmAAAplBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+AQCkUGYAACmUGQBACmUGAJBCmQEApFBmAAAplBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+AQCkUGYAACmUGQBACmUGAJBCmQEApFBmAAAplBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+AQCkUGYAACmUGQBACmUGAJBCmQEApFBmAAAplBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+AQCkUGYAACmUGQBACmUGAJBCmQEApFBmAAAplBkAQAplBgCQQpkBAKRQZgAAKZQZAEAKZQYAkEKZ
+Ue0D6MM888CODB7VrNfQA5MOTRg8qlmvoQcmHZoweFSzXkMPTDo0YfCoZr2GHph0aMLgUc16DT0w
+6dCEwaOa9Rp6YNKhCYNHNes19MCkQxMGj2rWa+iBSYcmDB7VrNfQA5MOTRg8qlmvoQcmHZoweFSz
+XkMPTDo0YfCoZr2GHph0aMLgUc16DT0w6dCEwaOa9Rp6YNKhCYNHNes19MCkQxMGj2rWa+iBSYcm
+DB7VrNfQA5MOTRg8qlmvuenf3z/Dv5GPjz9//82f8JJMOjRh8Khmvb709fnx8fk1v3kVx4I6uKej
+xj22LnO8/GX/l/wt2DD8q5hfATsyeFSLXq+HLNhMjGufP8YzYuRaBT3IeMrF8adK+/YXuuucnvtT
+sx9lBk0YPKrdXK/X/zvMT3vl51XSpMyecvCnltl48PNTHlvt8IXrr56vbnVnz/Zddl1t9LSzZx/D
+PZxfATsyeFS7uV6vH/njE/sn0bJOgxrXIuna54/wnGP//Df43vouHS3Xsf7q4vKundOwyenzZ/7U
+7EmZQRMGj2oVZTZYPbTHvx6dnvDFp8Ou5TYXj/jij1v7//n7t8iC7c+ncBjejg7HKL/x2lltfzIp
+S2TYZHg9XvNkONqyU7FLcaDl+y4OPn4w/3U8XvmNv1Ycu7DcqvWfi+vb3q/Yc37z0JOlleHf4vwK
+2JHBo9rN9Xp8dq+fy6endvn8Pm239bS/UgBfn2UizK/Lbxy/4bvPp9fF0e89q8tPDob9j19z2Oh4
+uMPr4s1yAsftTx9uHPz40Xh+py94jOJsCsuVrM+muMCN05yUv2G5PS9t+Nc7vwJ2ZPCodnO9vnzm
+H5/a5385PsDHz88f99cK4GTZ4mzTJQuufb6cz8G42X1ndfnJ6Gz/1beu3qy/drZssXHw6W9/h/8o
+T+9Rts7m9NnqxJefZLD+w8nqcMX2vDRlBk0YPKr9oszOlA/88v3VAlgfY9piFQVFFlz7/OwPNWd1
+5ZPTu8P75eCrN8XXHg9zcNzi/ODLVuXxH2Y6enHk9fvTyR7OojynrdNZ/aann5rXNtz5+RWwI4NH
+tZvr9cWze3loj39Znt6b1j1wuW35/F+2ONt0yYJrn6+OUndWR6dPLvZefbB6s+xUHm/j25c/z38b
+/+tJoTN+1eLsO5a/fX4NL5c/jmcz2th6uY5ye17ZcKPnV8CODB7Vbq7X65CYHuTHt982xrjB4fm+
+vWnx/J/C4fB6fDlvO33d8c2tz5eKqDqro+WTG3+6eLN8bfH948uzA2wcfHxxvhU8381JB57F4FHt
+5no9ZcTJWfOs/3r445Qns6U/jhue7b9sO/2/K49bn476+TW8XvbZ/rwoo9lpu9G1s7r8ZNxvfaT1
+R6s3xdduXMXlwVd7j38++yng2YZ/jPMrYEcGj2rW64ONMIM3YtKhCYNHNev1RJjx5kw6NGHwqGa9
+hh6YdGjC4FHNeg09MOnQhMGjmvUaemDSoQmDRzXrNfTApEMTBo9q1mvogUmHJgwe1azX0AOTDk0Y
+PKpZr6EHJh2aMHhUs15DD0w6NGHwqJa8Xg/nVmXeDbhgQKAJg0e1wPV6qqzR/P5u826T+SNgYiig
+CYNHtZz1egqq0fz+d+ZjeRqtzT9KYf4D7869hiYMHtWar9dTHozm9482H737x9K1H+Ha57wZdxma
+MHhUa7heT0mw37fv/HVRvr3wbn+ZfrjF0ITBo1qT9Xr40lbPiYZf3cqd19vbz9Ib9xeaMHhU23m9
+Hr4u4QkRcho7qLrMTn6TPrm50ITBo9pu6/XwRWnPhsBTeqwfXN17/yA9c2ehCYNHtR3W6+Erkp8K
+4af3Yz++qLf8NXBboQmDR7WnrtfDwV/lefBCp3qPX17LO/0UHLin0ITBo9rz1utXfBIM5/yKp33p
+l1fxHj8CJfcUmjB4VHvGej0c86UfA29w/vOrX3jpX4BLbig0YfCo9tj1ejja2zwAXvRaHnjOr3j5
+XONuQhMGj2oe5LcNF/VC1/XwU32ha+c2txKaMHhUe8h6PRzkvdf9V7nAZ5zkS1w433IfoQmDR7Vf
+rtfD7v2s+OEX+6RzS75k7uc+QhMGj2q/Wa/7XOuHqw688KeeUuD1UstNhCYMHtV+tl4Pe3W+0Kdd
+/rPPp/Pb/QbcQWjC4FGtdr0etrfEH+T8FPucRsjF8jNuHzRh8KhWtV5b3C8Nv0nbn2W3b297mfyS
+2wdNGDyq3bleD5tZ2W9o+Pvs+b2trpHfc++gCYNHtW/X62EDa/qd9v+t9r81+38jD+HGQRMGj2q3
+12ur+Q/s9qO1ujv+Vbwidw2aMHhUs16/LmXG/dw1aMLgUc16/aLa3jj/bF6OWwZNGDyqWa+hByYd
+mjB4VLNeQw9MOjRh8KhmvYYemHRowuBRzXoNPTDp0ITBo5r1Gnpg0qEJg0c16zX0wKRDEwaPatbr
+G74+Pz4+v+Y38MpMOjRh8Khmvb7uvcLs398/w82eqM0ODfd9fgXsyOBR7bv1enyeXz7ID0/5P3//
+ze8Hmw/+O2rg3kOt7bHXEGbHTYutzjcb8+3smInG05xPsnhJP4Z/pfMrYEcGj2rfrddjk6xb5PBg
+/xo+Lx7vmw/+b2vg/kOVdtpr+GB+P/wGx79MiVb8HuNGn5+rY0Yar2457ct7yvtTZtCEwaNafZkd
+jJ+fcmTzwX9vDdxxqA3P3mv421ZurQ5w2GV9zEjrU3yBE+bhlBk0YfCo9pAy23zwb344v1v5/lDz
+u5Un73UlzMqYG3cYX974uhRnp3jt4nhjygyaMHhUe0KZzQ/+u2vg+0PNb1aeutfZXxbF5+PLww9z
+beMg61N8gRPm4ZQZNGHwqOZ/M9vY68oBhnQrtzj+LFe2jjKe+nIby5OnF8oMmjB4VHtImW0/+O+t
+gTsOteGJe23uP2673vPc6a+BiktdXTW9GP6Fzq+AHRk8qn23Xl+rnHXibD/4Nz8cd1wf8Z5D7b3X
+aqfDca6G19kxU00XMXmBk+Xhhhs/vwJ2ZPCo9t16fXqeT4aH+pgwpfk5v/ng3/hw+qioodL1Q+24
+1/jJOszOd12OeTDusHwlZBr+2c6vgB0ZPKpZr89chhm8AZMOTRg8qlmv14QZ78mkQxMGj2rWa+iB
+SYcmDB7VrNfQA5MOTRg8qlmvoQcmHZoweFSzXkMPTDo0YfCoZr2GHph0aMLgUc16DT0w6dCEwaOa
+9Rp6YNKhCYNHNes19MCkQxMGj2rWa+iBSYcmDB7VrNfQA5MOTRg8qg3rNdCDeeaBHRk8AIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAghTIDAEihzAAAUigzAIAUygwA
+IIUyAwBIocwAAFIoMwCAFMoMACCFMgMASKHMAABSKDMAgBTKDAAgw3///Q/eEdTxO2yxrQAAAABJ
+RU5ErkJggg==
+"
+     id="image10"
+     x="0"
+     y="0" />
+</svg>
diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
index 02611ef..62cafb0 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -53,7 +53,6 @@ Sample Applications User Guides
     l2_forward_cat
     l3_forward
     l3_forward_power_man
-    l3_forward_access_ctrl
     l3_forward_virtual
     link_status_intr
     load_balancer
diff --git a/doc/guides/sample_app_ug/l3_forward.rst b/doc/guides/sample_app_ug/l3_forward.rst
index 6a6b8fb..69063bd 100644
--- a/doc/guides/sample_app_ug/l3_forward.rst
+++ b/doc/guides/sample_app_ug/l3_forward.rst
@@ -1,5 +1,5 @@
 ..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+    Copyright(c) 2010-2017 Intel Corporation. All rights reserved.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -31,12 +31,18 @@
 L3 Forwarding Sample Application
 ================================
 
-The L3 Forwarding application is a simple example of packet processing using the DPDK.
-The application performs L3 forwarding.
+The L3 Forwarding with Hash, LPM or Access Control application is a simple example of packet processing using the DPDK.
+The application performs L3 forwarding when Hash or LPM is used.
+The application performs a security check on received packets when Access Control is used.
+Packets that are in the Access Control List (ACL), which is loaded during initialization, are dropped.
+Others are forwarded to the correct port.
 
 Overview
 --------
 
+Hash and LPM
+~~~~~~~~~~~~
+
 The application demonstrates the use of the hash and LPM libraries in the DPDK to implement packet forwarding.
 The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
 The main difference from the L2 Forwarding sample application is that the forwarding decision
@@ -49,15 +55,263 @@ The hash object is used in correlation with a flow table to map each input packe
 The hash lookup key is represented by a DiffServ 5-tuple composed of the following fields read from the input packet:
 Source IP Address, Destination IP Address, Protocol, Source Port and Destination Port.
 The ID of the output interface for the input packet is read from the identified flow table entry.
-The set of flows used by the application is statically configured and loaded into the hash at initialization time.
 When the selected lookup method is LPM based, an LPM object is used to emulate the forwarding stage for IPv4 packets.
 The LPM object is used as the routing table to identify the next hop for each input packet at runtime.
 
 The LPM lookup key is represented by the Destination IP Address field read from the input packet.
 The ID of the output interface for the input packet is the next hop returned by the LPM lookup.
-The set of LPM rules used by the application is statically configured and loaded into the LPM object at initialization time.
 
-In the sample application, hash-based forwarding supports IPv4 and IPv6. LPM-based forwarding supports IPv4 only.
+In the sample application, both hash-based and LPM forwarding supports IPv4 and IPv6.
+
+The application loads rules at initialization which are used for L3 forwarding.
+The application needs to acquire route rules before it runs.
+
+To read data from the specified file successfully, the application assumes the following:
+
+*   Each rule occupies a single line.
+
+*   Only the following four rule line types are valid in this application:
+
+*   Route rule line starts with a leading character 'L' for LPM
+
+*   Route rule line starts with a leading character 'E' for hash-based
+
+*   Comment line, which starts with a leading character '#'
+
+*   Empty line, which consists of a space, form-feed ('\f'), newline ('\n'),
+    carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
+
+Other lines types are considered invalid.
+
+*   A typical IPv4 LPM rule line should have a format as shown below:
+
+
+.. _figure_ipv4_lpm_rule:
+
+.. figure:: img/ipv4_lpm_rule.*
+
+   A typical IPv4 LPM rule
+
+*   A typical IPv4 hash rule line should have a format as shown below:
+
+
+.. _figure_ipv4_hash_rule:
+
+.. figure:: img/ipv4_hash_rule.*
+
+   A typical IPv4 hash rule
+
+Access Control
+~~~~~~~~~~~~~~
+The application demonstrates the use of the ACL library in the DPDK to implement access control
+and packet L3 forwarding.
+The application loads two types of rules at initialization:
+
+*   Route information rules, which are used for L3 forwarding
+
+*   Access Control List (ACL) rules that blacklist (or block) packets with a specific characteristic
+
+When packets are received from a port,
+the application extracts the necessary information from the TCP/IP header of the received packet and
+performs a lookup in the rule database to figure out whether the packets should be dropped (in the ACL range)
+or forwarded to desired ports.
+The initialization and run-time paths are similar to those of the :doc:`l3_forward`.
+However, there are significant differences in the two applications.
+For example, the original L3 forwarding application uses either LPM or
+an exact match algorithm to perform forwarding port lookup,
+while this application uses the ACL library to perform both ACL and route entry lookup.
+The following sections provide more detail.
+
+Classification for both IPv4 and IPv6 packets is supported in this application.
+The application also assumes that all the packets it processes are TCP/UDP packets and
+always extracts source/destination port information from the packets.
+
+Tuple Packet Syntax
+^^^^^^^^^^^^^^^^^^^
+
+The application implements packet classification for the IPv4/IPv6 5-tuple syntax specifically.
+The 5-tuple syntax consist of a source IP address, a destination IP address,
+a source port, a destination port and a protocol identifier.
+The fields in the 5-tuple syntax have the following formats:
+
+*   **Source IP address and destination IP address**
+    : Each is either a 32-bit field (for IPv4), or a set of 4 32-bit fields (for IPv6) represented by a value and a mask length.
+    For example, an IPv4 range of 192.168.1.0 to 192.168.1.255 could be represented by a value = [192, 168, 1, 0] and a mask length = 24.
+
+*   **Source port and destination port**
+    : Each is a 16-bit field, represented by a lower start and a higher end.
+    For example, a range of ports 0 to 8192 could be represented by lower = 0 and higher = 8192.
+
+*   **Protocol identifier**
+    : An 8-bit field, represented by a value and a mask, that covers a range of values.
+    To verify that a value is in the range, use the following expression: "(VAL & mask) == value"
+
+The trick in how to represent a range with a mask and value is as follows.
+A range can be enumerated in binary numbers with some bits that are never changed and some bits that are dynamically changed.
+Set those bits that dynamically changed in mask and value with 0.
+Set those bits that never changed in the mask with 1, in value with number expected.
+For example, a range of 6 to 7 is enumerated as 0b110 and 0b111.
+Bit 1-7 are bits never changed and bit 0 is the bit dynamically changed.
+Therefore, set bit 0 in mask and value with 0, set bits 1-7 in mask with 1, and bits 1-7 in value with number 0b11.
+So, mask is 0xfe, value is 0x6.
+
+.. note::
+
+    The library assumes that each field in the rule is in LSB or Little Endian order when creating the database.
+    It internally converts them to MSB or Big Endian order.
+    When performing a lookup, the library assumes the input is in MSB or Big Endian order.
+
+Access Rule Syntax
+^^^^^^^^^^^^^^^^^^
+
+In this sample application, each rule is a combination of the following:
+
+*   5-tuple field: This field has a format described in Section.
+
+*   priority field: A weight to measure the priority of the rules.
+    The rule with the higher priority will ALWAYS be returned if the specific input has multiple matches in the rule database.
+    Rules with lower priority will NEVER be returned in any cases.
+
+*   userdata field: A user-defined field that could be any value.
+    It can be the forwarding port number if the rule is a route table entry or it can be a pointer to a mapping address
+    if the rule is used for address mapping in the NAT application.
+    The key point is that it is a useful reserved field for user convenience.
+
+ACL and Route Rules
+^^^^^^^^^^^^^^^^^^^
+
+The application needs to acquire ACL and route rules before it runs.
+Route rules are mandatory, while ACL rules are optional.
+To simplify the complexity of the priority field for each rule, all ACL and route entries are assumed to be in the same file.
+To read data from the specified file successfully, the application assumes the following:
+
+*   Each rule occupies a single line.
+
+*   Only the following four rule line types are valid in this application:
+
+*   ACL rule line, which starts with a leading character '@'
+
+*   Route rule line, which starts with a leading character 'R'
+
+*   Comment line, which starts with a leading character '#'
+
+*   Empty line, which consists of a space, form-feed ('\f'), newline ('\n'),
+    carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
+
+Other lines types are considered invalid.
+
+*   Rules are organized in descending order of priority,
+    which means rules at the head of the file always have a higher priority than those further down in the file.
+
+*   A typical IPv4 ACL rule line should have a format as shown below:
+
+
+.. _figure_ipv4_acl_rule:
+
+.. figure:: img/ipv4_acl_rule.*
+
+   A typical IPv4 ACL rule
+
+
+IPv4 addresses are specified in CIDR format as specified in RFC 4632.
+They consist of the dot notation for the address and a prefix length separated by '/'.
+For example, 192.168.0.34/32, where the address is 192.168.0.34 and the prefix length is 32.
+
+Ports are specified as a range of 16-bit numbers in the format MIN:MAX,
+where MIN and MAX are the inclusive minimum and maximum values of the range.
+The range 0:65535 represents all possible ports in a range.
+When MIN and MAX are the same value, a single port is represented, for example, 20:20.
+
+The protocol identifier is an 8-bit value and a mask separated by '/'.
+For example: 6/0xfe matches protocol values 6 and 7.
+
+*   Route rules start with a leading character 'R' and have the same format as ACL rules except an extra field at the tail
+    that indicates the forwarding port number.
+
+Rules File Example
+^^^^^^^^^^^^^^^^^^
+
+.. _figure_example_rules:
+
+.. figure:: img/example_rules.*
+
+   Rules example
+
+
+Each rule is explained as follows:
+
+*   Rule 1 (the first line) tells the application to drop those packets with source IP address = [1.2.3.*],
+    destination IP address = [192.168.0.36], protocol = [6]/[7]
+
+*   Rule 2 (the second line) is similar to Rule 1, except the source IP address is ignored.
+    It tells the application to forward packets with destination IP address = [192.168.0.36],
+    protocol = [6]/[7], destined to port 1.
+
+*   Rule 3 (the third line) tells the application to forward all packets to port 0.
+    This is something like a default route entry.
+
+As described earlier, the application assume rules are listed in descending order of priority,
+therefore Rule 1 has the highest priority, then Rule 2, and finally,
+Rule 3 has the lowest priority.
+
+Consider the arrival of the following three packets:
+
+*   Packet 1 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [6]
+
+*   Packet 2 has source IP address = [1.2.4.4], destination IP address = [192.168.0.36], and protocol = [6]
+
+*   Packet 3 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [8]
+
+Observe that:
+
+*   Packet 1 matches all of the rules
+
+*   Packet 2 matches Rule 2 and Rule 3
+
+*   Packet 3 only matches Rule 3
+
+For priority reasons, Packet 1 matches Rule 1 and is dropped.
+Packet 2 matches Rule 2 and is forwarded to port 1.
+Packet 3 matches Rule 3 and is forwarded to port 0.
+
+For more details on the rule file format,
+please refer to rule_ipv4.db and rule_ipv6.db files (inside <RTE_SDK>/examples/l3fwd-acl/).
+
+Application Phases
+^^^^^^^^^^^^^^^^^^
+
+Once the application starts, it transitions through three phases:
+
+*   **Initialization Phase**
+    - Perform the following tasks:
+
+*   Parse command parameters. Check the validity of rule file(s) name(s), number of logical cores, receive and transmit queues.
+    Bind ports, queues and logical cores. Check ACL search options, and so on.
+
+*   Call Environmental Abstraction Layer (EAL) and Poll Mode Driver (PMD) functions to initialize the environment and detect possible NICs.
+    The EAL creates several threads and sets affinity to a specific hardware thread CPU based on the configuration specified
+    by the command line arguments.
+
+*   Read the rule files and format the rules into the representation that the ACL library can recognize.
+    Call the ACL library function to add the rules into the database and compile them as a trie of pattern sets.
+    Note that application maintains a separate AC contexts for IPv4 and IPv6 rules.
+
+*   **Runtime Phase**
+    - Process the incoming packets from a port. Packets are processed in three steps:
+
+    *   Retrieval: Gets a packet from the receive queue. Each logical core may process several queues for different ports.
+        This depends on the configuration specified by command line arguments.
+
+    *   Lookup: Checks that the packet type is supported (IPv4/IPv6) and performs a 5-tuple lookup over corresponding AC context.
+        If an ACL rule is matched, the packets will be dropped and return back to step 1.
+        If a route rule is matched, it indicates the packet is not in the ACL list and should be forwarded.
+        If there is no matches for the packet, then the packet is dropped.
+
+    *   Forwarding: Forwards the packet to the corresponding port.
+
+*   **Final Phase** - Perform the following tasks:
+
+    Calls the EAL, PMD driver and ACL library to free resource, then quits.
 
 Compiling the Application
 -------------------------
@@ -93,14 +347,18 @@ The application has a number of command line options::
     ./l3fwd [EAL options] -- -p PORTMASK
                              [-P]
                              [-E]
+                             [-A]
                              [-L]
                              --config(port,queue,lcore)[,(port,queue,lcore)]
+                             --rule_ipv4 FILENAME
+                             --rule_ipv6 FILENAME
                              [--eth-dest=X,MM:MM:MM:MM:MM:MM]
                              [--enable-jumbo [--max-pkt-len PKTLEN]]
                              [--no-numa]
                              [--hash-entry-num]
                              [--ipv6]
                              [--parse-ptype]
+                             --scalar
 
 Where,
 
@@ -111,10 +369,18 @@ Where,
 
 * ``-E:`` Optional, enable exact match.
 
+* ``-A:`` Optional, enable access control list match.
+
 * ``-L:`` Optional, enable longest prefix match.
 
 * ``--config (port,queue,lcore)[,(port,queue,lcore)]:`` Determines which queues from which ports are mapped to which cores.
 
+* ``--rule_ipv4 FILENAME:`` Specifies the IPv4 hash-based, LPM, ACL and route rules file
+
+* ``--rule_ipv6 FILENAME:`` Specifies the IPv6 hash-based, LPM, ACL and route rules file
+
+* ``--scalar:`` Use a scalar function to perform ACL rule lookup
+
 * ``--eth-dest=X,MM:MM:MM:MM:MM:MM:`` Optional, ethernet destination for port X.
 
 * ``--enable-jumbo:`` Optional, enables jumbo frames.
@@ -137,7 +403,7 @@ To enable L3 forwarding between two ports, assuming that both ports are in the s
 
 .. code-block:: console
 
-    ./build/l3fwd -l 1,2 -n 4 -- -p 0x3 --config="(0,0,1),(1,0,2)"
+    ./build/l3fwd -l 1,2 -n 4 -- -p 0x3 --config="(0,0,1),(1,0,2) --rule_ipv4="./rule_ipv4.db" -- rule_ipv6="./rule_ipv6.db""
 
 In this command:
 
@@ -159,6 +425,12 @@ In this command:
 |          |           |           |                                     |
 +----------+-----------+-----------+-------------------------------------+
 
+*   The --rule_ipv4 option specifies the reading of IPv4 rules sets from the ./ rule_ipv4.db file.
+
+*   The --rule_ipv6 option specifies the reading of IPv6 rules sets from the ./ rule_ipv6.db file.
+
+*   The --scalar option specifies the performing of ACL rule lookup with a scalar function.
+
 Refer to the *DPDK Getting Started Guide* for general information on running applications and
 the Environment Abstraction Layer (EAL) options.
 
@@ -171,6 +443,22 @@ The following sections provide some explanation of the sample application code.
 the initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
 The following sections describe aspects that are specific to the L3 Forwarding sample application.
 
+Parse Rules from File
+~~~~~~~~~~~~~~~~~~~~~
+
+As described earlier, Hash, LPM and ACL route rules are assumed to be saved in a file.
+For ACL both ACL and route rules are assumed to be saved in the same file.
+The application parses the rules from the file and adds them to the database by calling the respective library function.
+It ignores empty and comment lines, and parses and validates the rules it reads.
+If errors are detected, the application exits with messages to identify the errors encountered.
+
+The application needs to consider the userdata and priority fields for ACL.
+The ACL rules save the index to the specific rules in the userdata field,
+while route rules save the forwarding port number.
+In order to differentiate the two types of rules, ACL rules add a signature in the userdata field.
+As for the priority field, the application assumes rules are organized in descending order of priority.
+Therefore, the code only decreases the priority number with each rule it parses.
+
 Hash Initialization
 ~~~~~~~~~~~~~~~~~~~
 
@@ -194,7 +482,7 @@ for the convenience to execute hash performance test on 4M/8M/16M flows.
 
 .. code-block:: c
 
-    #if (APP_LOOKUP_METHOD == APP_LOOKUP_EXACT_MATCH)
+    #if (-E option used)
 
         static void
         setup_hash(int socketid)
@@ -228,7 +516,7 @@ The LPM object is created and loaded with the pre-configured entries read from a
 
 .. code-block:: c
 
-    #if (APP_LOOKUP_METHOD == APP_LOOKUP_LPM)
+    #if (-L option used)
 
     static void
     setup_lpm(int socketid)
@@ -358,3 +646,23 @@ for LPM-based lookups is done by the get_ipv4_dst_port() function below:
 
         return (uint8_t) ((rte_lpm_lookup(ipv4_l3fwd_lookup_struct, rte_be_to_cpu_32(ipv4_hdr->dst_addr), &next_hop) == 0)? next_hop : portid);
     }
+
+Setting Up the ACL Context
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For each supported AC rule format (IPv4 5-tuple, IPv6 6-tuple) application creates a separate context handler
+from the ACL library for each CPU socket on the board and adds parsed rules into that context.
+
+Note, that for each supported rule type,
+application needs to calculate the expected offset of the fields from the start of the packet.
+That's why only packets with fixed IPv4/ IPv6 header are supported.
+That allows to perform ACL classify straight over incoming packet buffer -
+no extra protocol field retrieval need to be performed.
+
+Subsequently, the application checks whether NUMA is enabled.
+If it is, the application records the socket IDs of the CPU cores involved in the task.
+
+Finally, the application creates contexts handler from the ACL library,
+adds rules parsed from the file into the database and build an ACL trie.
+It is important to note that the application creates an independent copy of each database for each socket CPU
+involved in the task to reduce the time for remote memory access.
diff --git a/doc/guides/sample_app_ug/l3_forward_access_ctrl.rst b/doc/guides/sample_app_ug/l3_forward_access_ctrl.rst
deleted file mode 100644
index a6aa4fb..0000000
--- a/doc/guides/sample_app_ug/l3_forward_access_ctrl.rst
+++ /dev/null
@@ -1,385 +0,0 @@
-..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
-    All rights reserved.
-
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions
-    are met:
-
-    * Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in
-    the documentation and/or other materials provided with the
-    distribution.
-    * Neither the name of Intel Corporation nor the names of its
-    contributors may be used to endorse or promote products derived
-    from this software without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-L3 Forwarding with Access Control Sample Application
-====================================================
-
-The L3 Forwarding with Access Control application is a simple example of packet processing using the DPDK.
-The application performs a security check on received packets.
-Packets that are in the Access Control List (ACL), which is loaded during initialization, are dropped.
-Others are forwarded to the correct port.
-
-Overview
---------
-
-The application demonstrates the use of the ACL library in the DPDK to implement access control
-and packet L3 forwarding.
-The application loads two types of rules at initialization:
-
-*   Route information rules, which are used for L3 forwarding
-
-*   Access Control List (ACL) rules that blacklist (or block) packets with a specific characteristic
-
-When packets are received from a port,
-the application extracts the necessary information from the TCP/IP header of the received packet and
-performs a lookup in the rule database to figure out whether the packets should be dropped (in the ACL range)
-or forwarded to desired ports.
-The initialization and run-time paths are similar to those of the :doc:`l3_forward`.
-However, there are significant differences in the two applications.
-For example, the original L3 forwarding application uses either LPM or
-an exact match algorithm to perform forwarding port lookup,
-while this application uses the ACL library to perform both ACL and route entry lookup.
-The following sections provide more detail.
-
-Classification for both IPv4 and IPv6 packets is supported in this application.
-The application also assumes that all the packets it processes are TCP/UDP packets and
-always extracts source/destination port information from the packets.
-
-Tuple Packet Syntax
-~~~~~~~~~~~~~~~~~~~
-
-The application implements packet classification for the IPv4/IPv6 5-tuple syntax specifically.
-The 5-tuple syntax consist of a source IP address, a destination IP address,
-a source port, a destination port and a protocol identifier.
-The fields in the 5-tuple syntax have the following formats:
-
-*   **Source IP address and destination IP address**
-    : Each is either a 32-bit field (for IPv4), or a set of 4 32-bit fields (for IPv6) represented by a value and a mask length.
-    For example, an IPv4 range of 192.168.1.0 to 192.168.1.255 could be represented by a value = [192, 168, 1, 0] and a mask length = 24.
-
-*   **Source port and destination port**
-    : Each is a 16-bit field, represented by a lower start and a higher end.
-    For example, a range of ports 0 to 8192 could be represented by lower = 0 and higher = 8192.
-
-*   **Protocol identifier**
-    : An 8-bit field, represented by a value and a mask, that covers a range of values.
-    To verify that a value is in the range, use the following expression: "(VAL & mask) == value"
-
-The trick in how to represent a range with a mask and value is as follows.
-A range can be enumerated in binary numbers with some bits that are never changed and some bits that are dynamically changed.
-Set those bits that dynamically changed in mask and value with 0.
-Set those bits that never changed in the mask with 1, in value with number expected.
-For example, a range of 6 to 7 is enumerated as 0b110 and 0b111.
-Bit 1-7 are bits never changed and bit 0 is the bit dynamically changed.
-Therefore, set bit 0 in mask and value with 0, set bits 1-7 in mask with 1, and bits 1-7 in value with number 0b11.
-So, mask is 0xfe, value is 0x6.
-
-.. note::
-
-    The library assumes that each field in the rule is in LSB or Little Endian order when creating the database.
-    It internally converts them to MSB or Big Endian order.
-    When performing a lookup, the library assumes the input is in MSB or Big Endian order.
-
-Access Rule Syntax
-~~~~~~~~~~~~~~~~~~
-
-In this sample application, each rule is a combination of the following:
-
-*   5-tuple field: This field has a format described in Section.
-
-*   priority field: A weight to measure the priority of the rules.
-    The rule with the higher priority will ALWAYS be returned if the specific input has multiple matches in the rule database.
-    Rules with lower priority will NEVER be returned in any cases.
-
-*   userdata field: A user-defined field that could be any value.
-    It can be the forwarding port number if the rule is a route table entry or it can be a pointer to a mapping address
-    if the rule is used for address mapping in the NAT application.
-    The key point is that it is a useful reserved field for user convenience.
-
-ACL and Route Rules
-~~~~~~~~~~~~~~~~~~~
-
-The application needs to acquire ACL and route rules before it runs.
-Route rules are mandatory, while ACL rules are optional.
-To simplify the complexity of the priority field for each rule, all ACL and route entries are assumed to be in the same file.
-To read data from the specified file successfully, the application assumes the following:
-
-*   Each rule occupies a single line.
-
-*   Only the following four rule line types are valid in this application:
-
-*   ACL rule line, which starts with a leading character '@'
-
-*   Route rule line, which starts with a leading character 'R'
-
-*   Comment line, which starts with a leading character '#'
-
-*   Empty line, which consists of a space, form-feed ('\f'), newline ('\n'),
-    carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
-
-Other lines types are considered invalid.
-
-*   Rules are organized in descending order of priority,
-    which means rules at the head of the file always have a higher priority than those further down in the file.
-
-*   A typical IPv4 ACL rule line should have a format as shown below:
-
-
-.. _figure_ipv4_acl_rule:
-
-.. figure:: img/ipv4_acl_rule.*
-
-   A typical IPv4 ACL rule
-
-
-IPv4 addresses are specified in CIDR format as specified in RFC 4632.
-They consist of the dot notation for the address and a prefix length separated by '/'.
-For example, 192.168.0.34/32, where the address is 192.168.0.34 and the prefix length is 32.
-
-Ports are specified as a range of 16-bit numbers in the format MIN:MAX,
-where MIN and MAX are the inclusive minimum and maximum values of the range.
-The range 0:65535 represents all possible ports in a range.
-When MIN and MAX are the same value, a single port is represented, for example, 20:20.
-
-The protocol identifier is an 8-bit value and a mask separated by '/'.
-For example: 6/0xfe matches protocol values 6 and 7.
-
-*   Route rules start with a leading character 'R' and have the same format as ACL rules except an extra field at the tail
-    that indicates the forwarding port number.
-
-Rules File Example
-~~~~~~~~~~~~~~~~~~
-
-.. _figure_example_rules:
-
-.. figure:: img/example_rules.*
-
-   Rules example
-
-
-Each rule is explained as follows:
-
-*   Rule 1 (the first line) tells the application to drop those packets with source IP address = [1.2.3.*],
-    destination IP address = [192.168.0.36], protocol = [6]/[7]
-
-*   Rule 2 (the second line) is similar to Rule 1, except the source IP address is ignored.
-    It tells the application to forward packets with destination IP address = [192.168.0.36],
-    protocol = [6]/[7], destined to port 1.
-
-*   Rule 3 (the third line) tells the application to forward all packets to port 0.
-    This is something like a default route entry.
-
-As described earlier, the application assume rules are listed in descending order of priority,
-therefore Rule 1 has the highest priority, then Rule 2, and finally,
-Rule 3 has the lowest priority.
-
-Consider the arrival of the following three packets:
-
-*   Packet 1 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [6]
-
-*   Packet 2 has source IP address = [1.2.4.4], destination IP address = [192.168.0.36], and protocol = [6]
-
-*   Packet 3 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [8]
-
-Observe that:
-
-*   Packet 1 matches all of the rules
-
-*   Packet 2 matches Rule 2 and Rule 3
-
-*   Packet 3 only matches Rule 3
-
-For priority reasons, Packet 1 matches Rule 1 and is dropped.
-Packet 2 matches Rule 2 and is forwarded to port 1.
-Packet 3 matches Rule 3 and is forwarded to port 0.
-
-For more details on the rule file format,
-please refer to rule_ipv4.db and rule_ipv6.db files (inside <RTE_SDK>/examples/l3fwd-acl/).
-
-Application Phases
-~~~~~~~~~~~~~~~~~~
-
-Once the application starts, it transitions through three phases:
-
-*   **Initialization Phase**
-    - Perform the following tasks:
-
-*   Parse command parameters. Check the validity of rule file(s) name(s), number of logical cores, receive and transmit queues.
-    Bind ports, queues and logical cores. Check ACL search options, and so on.
-
-*   Call Environmental Abstraction Layer (EAL) and Poll Mode Driver (PMD) functions to initialize the environment and detect possible NICs.
-    The EAL creates several threads and sets affinity to a specific hardware thread CPU based on the configuration specified
-    by the command line arguments.
-
-*   Read the rule files and format the rules into the representation that the ACL library can recognize.
-    Call the ACL library function to add the rules into the database and compile them as a trie of pattern sets.
-    Note that application maintains a separate AC contexts for IPv4 and IPv6 rules.
-
-*   **Runtime Phase**
-    - Process the incoming packets from a port. Packets are processed in three steps:
-
-    *   Retrieval: Gets a packet from the receive queue. Each logical core may process several queues for different ports.
-        This depends on the configuration specified by command line arguments.
-
-    *   Lookup: Checks that the packet type is supported (IPv4/IPv6) and performs a 5-tuple lookup over corresponding AC context.
-        If an ACL rule is matched, the packets will be dropped and return back to step 1.
-        If a route rule is matched, it indicates the packet is not in the ACL list and should be forwarded.
-        If there is no matches for the packet, then the packet is dropped.
-
-    *   Forwarding: Forwards the packet to the corresponding port.
-
-*   **Final Phase** - Perform the following tasks:
-
-    Calls the EAL, PMD driver and ACL library to free resource, then quits.
-
-Compiling the Application
--------------------------
-
-To compile the application:
-
-#.  Go to the sample application directory:
-
-    ..  code-block:: console
-
-        export RTE_SDK=/path/to/rte_sdk
-        cd ${RTE_SDK}/examples/l3fwd-acl
-
-#.  Set the target (a default target is used if not specified). For example:
-
-    ..  code-block:: console
-
-        export RTE_TARGET=x86_64-native-linuxapp-gcc
-
-    See the *DPDK IPL Getting Started Guide* for possible RTE_TARGET values.
-
-#.  Build the application:
-
-    ..  code-block:: console
-
-        make
-
-Running the Application
------------------------
-
-The application has a number of command line options:
-
-..  code-block:: console
-
-    ./build/l3fwd-acl [EAL options] -- -p PORTMASK [-P] --config(port,queue,lcore)[,(port,queue,lcore)] --rule_ipv4 FILENAME rule_ipv6 FILENAME [--scalar] [--enable-jumbo [--max-pkt-len PKTLEN]] [--no-numa]
-
-
-where,
-
-*   -p PORTMASK: Hexadecimal bitmask of ports to configure
-
-*   -P: Sets all ports to promiscuous mode so that packets are accepted regardless of the packet's Ethernet MAC destination address.
-    Without this option, only packets with the Ethernet MAC destination address set to the Ethernet address of the port are accepted.
-
-*   --config (port,queue,lcore)[,(port,queue,lcore)]: determines which queues from which ports are mapped to which cores
-
-*   --rule_ipv4 FILENAME: Specifies the IPv4 ACL and route rules file
-
-*   --rule_ipv6 FILENAME: Specifies the IPv6 ACL and route rules file
-
-*   --scalar: Use a scalar function to perform rule lookup
-
-*   --enable-jumbo: optional, enables jumbo frames
-
-*   --max-pkt-len: optional, maximum packet length in decimal (64-9600)
-
-*   --no-numa: optional, disables numa awareness
-
-For example, consider a dual processor socket platform with 8 physical cores, where cores 0-7 and 16-23 appear on socket 0,
-while cores 8-15 and 24-31 appear on socket 1.
-
-To enable L3 forwarding between two ports, assuming that both ports are in the same socket, using two cores, cores 1 and 2,
-(which are in the same socket too), use the following command:
-
-..  code-block:: console
-
-    ./build/l3fwd-acl -l 1,2 -n 4 -- -p 0x3 --config="(0,0,1),(1,0,2)" --rule_ipv4="./rule_ipv4.db" -- rule_ipv6="./rule_ipv6.db" --scalar
-
-In this command:
-
-*   The -l option enables cores 1, 2
-
-*   The -p option enables ports 0 and 1
-
-*   The --config option enables one queue on each port and maps each (port,queue) pair to a specific core.
-    The following table shows the mapping in this example:
-
-    +----------+------------+-----------+-------------------------------------+
-    | **Port** | **Queue**  | **lcore** |            **Description**          |
-    |          |            |           |                                     |
-    +==========+============+===========+=====================================+
-    | 0        | 0          | 1         | Map queue 0 from port 0 to lcore 1. |
-    |          |            |           |                                     |
-    +----------+------------+-----------+-------------------------------------+
-    | 1        | 0          | 2         | Map queue 0 from port 1 to lcore 2. |
-    |          |            |           |                                     |
-    +----------+------------+-----------+-------------------------------------+
-
-*   The --rule_ipv4 option specifies the reading of IPv4 rules sets from the ./ rule_ipv4.db file.
-
-*   The --rule_ipv6 option specifies the reading of IPv6 rules sets from the ./ rule_ipv6.db file.
-
-*   The --scalar option specifies the performing of rule lookup with a scalar function.
-
-Explanation
------------
-
-The following sections provide some explanation of the sample application code.
-The aspects of port, device and CPU configuration are similar to those of the :doc:`l3_forward`.
-The following sections describe aspects that are specific to L3 forwarding with access control.
-
-Parse Rules from File
-~~~~~~~~~~~~~~~~~~~~~
-
-As described earlier, both ACL and route rules are assumed to be saved in the same file.
-The application parses the rules from the file and adds them to the database by calling the ACL library function.
-It ignores empty and comment lines, and parses and validates the rules it reads.
-If errors are detected, the application exits with messages to identify the errors encountered.
-
-The application needs to consider the userdata and priority fields.
-The ACL rules save the index to the specific rules in the userdata field,
-while route rules save the forwarding port number.
-In order to differentiate the two types of rules, ACL rules add a signature in the userdata field.
-As for the priority field, the application assumes rules are organized in descending order of priority.
-Therefore, the code only decreases the priority number with each rule it parses.
-
-Setting Up the ACL Context
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For each supported AC rule format (IPv4 5-tuple, IPv6 6-tuple) application creates a separate context handler
-from the ACL library for each CPU socket on the board and adds parsed rules into that context.
-
-Note, that for each supported rule type,
-application needs to calculate the expected offset of the fields from the start of the packet.
-That's why only packets with fixed IPv4/ IPv6 header are supported.
-That allows to perform ACL classify straight over incoming packet buffer -
-no extra protocol field retrieval need to be performed.
-
-Subsequently, the application checks whether NUMA is enabled.
-If it is, the application records the socket IDs of the CPU cores involved in the task.
-
-Finally, the application creates contexts handler from the ACL library,
-adds rules parsed from the file into the database and build an ACL trie.
-It is important to note that the application creates an independent copy of each database for each socket CPU
-involved in the task to reduce the time for remote memory access.
-- 
2.7.4

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [dpdk-dev] [PATCH v1] doc: Merge l3fwd and l3fwd-acl documentation files
  2017-04-25 18:39 [dpdk-dev] [PATCH v1] doc: Merge l3fwd and l3fwd-acl documentation files Ravi Kerur
@ 2017-05-05 16:15 ` Mcnamara, John
  2017-05-07 20:50 ` Thomas Monjalon
  2017-05-08 21:00 ` [dpdk-dev] [PATCH v2] " Ravi Kerur
  2 siblings, 0 replies; 10+ messages in thread
From: Mcnamara, John @ 2017-05-05 16:15 UTC (permalink / raw)
  To: Ravi Kerur, dev, Ananyev, Konstantin



> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Ravi Kerur
> Sent: Tuesday, April 25, 2017 7:39 PM
> To: dev@dpdk.org; Ananyev, Konstantin <konstantin.ananyev@intel.com>
> Cc: Ravi Kerur <rkerur@gmail.com>
> Subject: [dpdk-dev] [PATCH v1] doc: Merge l3fwd and l3fwd-acl
> documentation files
> 
> Merge relevant contents of l3fwd and l3fwd-acl documentation.
> Modify l3fwd document with ACL specific information.
> Remove l3fwd-acl documentation file.

Acked-by: John McNamara <john.mcnamara@intel.com>

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [dpdk-dev] [PATCH v1] doc: Merge l3fwd and l3fwd-acl documentation files
  2017-04-25 18:39 [dpdk-dev] [PATCH v1] doc: Merge l3fwd and l3fwd-acl documentation files Ravi Kerur
  2017-05-05 16:15 ` Mcnamara, John
@ 2017-05-07 20:50 ` Thomas Monjalon
  2017-05-08 21:04   ` Ravi Kerur
  2017-05-08 21:00 ` [dpdk-dev] [PATCH v2] " Ravi Kerur
  2 siblings, 1 reply; 10+ messages in thread
From: Thomas Monjalon @ 2017-05-07 20:50 UTC (permalink / raw)
  To: Ravi Kerur; +Cc: dev, konstantin.ananyev

Hi,

25/04/2017 20:39, Ravi Kerur:
> Merge relevant contents of l3fwd and l3fwd-acl documentation.
> Modify l3fwd document with ACL specific information.
> Remove l3fwd-acl documentation file.
> 
> Signed-off-by: Ravi Kerur <rkerur@gmail.com>
> ---
>  doc/guides/sample_app_ug/img/ipv4_hash_rule.svg    | 158 +++++++++
>  doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg     | 139 ++++++++
>  doc/guides/sample_app_ug/index.rst                 |   1 -
>  doc/guides/sample_app_ug/l3_forward.rst            | 326 ++++++++++++++++-
>  .../sample_app_ug/l3_forward_access_ctrl.rst       | 385 ---------------------
>  5 files changed, 614 insertions(+), 395 deletions(-)
>  create mode 100644 doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
>  create mode 100644 doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
>  delete mode 100644 doc/guides/sample_app_ug/l3_forward_access_ctrl.rst

I've not looked at the content.
I just do not understand why a patch for merging content is adding
some new files.
Moreover, these SVG files contains some binary PNG.
Please send only some source files.

^ permalink raw reply	[flat|nested] 10+ messages in thread

* [dpdk-dev] [PATCH v2] doc: Merge l3fwd and l3fwd-acl documentation files
  2017-04-25 18:39 [dpdk-dev] [PATCH v1] doc: Merge l3fwd and l3fwd-acl documentation files Ravi Kerur
  2017-05-05 16:15 ` Mcnamara, John
  2017-05-07 20:50 ` Thomas Monjalon
@ 2017-05-08 21:00 ` Ravi Kerur
  2017-05-10 10:14   ` Mcnamara, John
  2017-05-11  1:49   ` [dpdk-dev] [PATCH v3] " Ravi Kerur
  2 siblings, 2 replies; 10+ messages in thread
From: Ravi Kerur @ 2017-05-08 21:00 UTC (permalink / raw)
  To: dev; +Cc: john.mcnamara, thomas, Ravi Kerur

Merge l3fwd and l3fwd-acl documentation to reflect the code.
Add examples of LPM and Exact Match rules in .svg files.

Signed-off-by: Ravi Kerur <rkerur@gmail.com>
---
v2:
	Remove binary PNG from .svg files.

v1:
	Merge relevant contents of l3fwd and l3fwd-acl documentation.
	Modify l3fwd document with ACL specific information.
	Remove l3fwd-acl documentation file.
---
 doc/guides/sample_app_ug/img/ipv4_hash_rule.svg    | 108 ++++++
 doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg     |  96 +++++
 doc/guides/sample_app_ug/index.rst                 |   1 -
 doc/guides/sample_app_ug/l3_forward.rst            | 326 ++++++++++++++++-
 .../sample_app_ug/l3_forward_access_ctrl.rst       | 385 ---------------------
 5 files changed, 521 insertions(+), 395 deletions(-)
 create mode 100644 doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
 create mode 100644 doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
 delete mode 100644 doc/guides/sample_app_ug/l3_forward_access_ctrl.rst

diff --git a/doc/guides/sample_app_ug/img/ipv4_hash_rule.svg b/doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
new file mode 100644
index 0000000..76edfda
--- /dev/null
+++ b/doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
@@ -0,0 +1,108 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="744.09448819"
+   height="1052.3622047"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.4 r9939"
+   sodipodi:docname="New document 1">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.35"
+     inkscape:cx="375"
+     inkscape:cy="520"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1117"
+     inkscape:window-height="679"
+     inkscape:window-x="548"
+     inkscape:window-y="204"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot2985"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"><flowRegion
+         id="flowRegion2987"><rect
+           id="rect2989"
+           width="1402.8573"
+           height="174.28569"
+           x="-48.57143"
+           y="218.07646" /></flowRegion><flowPara
+         id="flowPara2991"> </flowPara><flowPara
+         id="flowPara2997">E101.0.0.0       100.10.0.0         101          11           0x06          0</flowPara><flowPara
+         id="flowPara2993" /><flowPara
+         id="flowPara2995" /></flowRoot>    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M -37.142857,258.07647 C 31.428571,123.79075 148.57143,252.36218 148.57143,252.36218"
+       id="path3001"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 245.71429,260.93361 c 105.71428,-131.42857 222.85714,-2.85714 222.85714,-2.85714"
+       id="path3003"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 577.14286,263.79075 c 54.28571,-125.71428 108.57143,-2.85714 108.57143,-2.85714"
+       id="path3007"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 762.85714,269.50504 c 51.42857,-125.71429 100,-2.85714 100,-2.85714"
+       id="path3011"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 962.85714,269.50504 C 1025.7143,160.93361 1100,263.79075 1100,263.79075"
+       id="path3037"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 1180,269.50504 c 65.7143,-91.42857 117.1429,-8.57143 117.1429,-8.57143"
+       id="path3039"
+       inkscape:connector-curvature="0" />
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot3041"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"><flowRegion
+         id="flowRegion3043"><rect
+           id="rect3045"
+           width="1351.4286"
+           height="77.14286"
+           x="-71.428574"
+           y="106.6479" /></flowRegion><flowPara
+         id="flowPara3047">  Src Addr           Dest Addr         Src port  Dest port   Protocol    Fwd</flowPara></flowRoot>  </g>
+</svg>
diff --git a/doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg b/doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
new file mode 100644
index 0000000..1b7f02c
--- /dev/null
+++ b/doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="744.09448819"
+   height="1052.3622047"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.4 r9939"
+   sodipodi:docname="New document 1">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.35"
+     inkscape:cx="375"
+     inkscape:cy="520"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     inkscape:window-width="1137"
+     inkscape:window-height="740"
+     inkscape:window-x="898"
+     inkscape:window-y="214"
+     inkscape:window-maximized="0" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot2985"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"><flowRegion
+         id="flowRegion2987"><rect
+           id="rect2989"
+           width="1111.4286"
+           height="131.42857"
+           x="-14.285714"
+           y="326.64789" /></flowRegion><flowPara
+         id="flowPara2991"></flowPara><flowPara
+         id="flowPara2993">  L101.10.1.0/24                              0</flowPara></flowRoot>    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M -5.7142857,363.79075 C 208.57143,226.6479 311.42857,360.93361 311.42857,360.93361"
+       id="path2995"
+       inkscape:connector-curvature="0" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 642.85714,378.07647 c 82.85715,-108.57143 148.57143,2.85714 148.57143,2.85714"
+       id="path2997"
+       inkscape:connector-curvature="0" />
+    <flowRoot
+       xml:space="preserve"
+       id="flowRoot2999"
+       style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Sans;font-style:normal;font-weight:normal;font-size:40px;line-height:125%;letter-spacing:0px;word-spacing:0px"><flowRegion
+         id="flowRegion3001"><rect
+           id="rect3003"
+           width="851.42859"
+           height="60"
+           x="-11.428572"
+           y="232.36218" /></flowRegion><flowPara
+         id="flowPara3005"></flowPara></flowRoot>    <flowRoot
+       xml:space="preserve"
+       id="flowRoot3015"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"><flowRegion
+         id="flowRegion3017"><rect
+           id="rect3019"
+           width="805.71429"
+           height="74.285713"
+           x="-20"
+           y="206.6479" /></flowRegion><flowPara
+         id="flowPara3021">   Dest Addr/Prefix                           Fwd</flowPara></flowRoot>  </g>
+</svg>
diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
index 02611ef..62cafb0 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -53,7 +53,6 @@ Sample Applications User Guides
     l2_forward_cat
     l3_forward
     l3_forward_power_man
-    l3_forward_access_ctrl
     l3_forward_virtual
     link_status_intr
     load_balancer
diff --git a/doc/guides/sample_app_ug/l3_forward.rst b/doc/guides/sample_app_ug/l3_forward.rst
index 6a6b8fb..69063bd 100644
--- a/doc/guides/sample_app_ug/l3_forward.rst
+++ b/doc/guides/sample_app_ug/l3_forward.rst
@@ -1,5 +1,5 @@
 ..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+    Copyright(c) 2010-2017 Intel Corporation. All rights reserved.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -31,12 +31,18 @@
 L3 Forwarding Sample Application
 ================================
 
-The L3 Forwarding application is a simple example of packet processing using the DPDK.
-The application performs L3 forwarding.
+The L3 Forwarding with Hash, LPM or Access Control application is a simple example of packet processing using the DPDK.
+The application performs L3 forwarding when Hash or LPM is used.
+The application performs a security check on received packets when Access Control is used.
+Packets that are in the Access Control List (ACL), which is loaded during initialization, are dropped.
+Others are forwarded to the correct port.
 
 Overview
 --------
 
+Hash and LPM
+~~~~~~~~~~~~
+
 The application demonstrates the use of the hash and LPM libraries in the DPDK to implement packet forwarding.
 The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
 The main difference from the L2 Forwarding sample application is that the forwarding decision
@@ -49,15 +55,263 @@ The hash object is used in correlation with a flow table to map each input packe
 The hash lookup key is represented by a DiffServ 5-tuple composed of the following fields read from the input packet:
 Source IP Address, Destination IP Address, Protocol, Source Port and Destination Port.
 The ID of the output interface for the input packet is read from the identified flow table entry.
-The set of flows used by the application is statically configured and loaded into the hash at initialization time.
 When the selected lookup method is LPM based, an LPM object is used to emulate the forwarding stage for IPv4 packets.
 The LPM object is used as the routing table to identify the next hop for each input packet at runtime.
 
 The LPM lookup key is represented by the Destination IP Address field read from the input packet.
 The ID of the output interface for the input packet is the next hop returned by the LPM lookup.
-The set of LPM rules used by the application is statically configured and loaded into the LPM object at initialization time.
 
-In the sample application, hash-based forwarding supports IPv4 and IPv6. LPM-based forwarding supports IPv4 only.
+In the sample application, both hash-based and LPM forwarding supports IPv4 and IPv6.
+
+The application loads rules at initialization which are used for L3 forwarding.
+The application needs to acquire route rules before it runs.
+
+To read data from the specified file successfully, the application assumes the following:
+
+*   Each rule occupies a single line.
+
+*   Only the following four rule line types are valid in this application:
+
+*   Route rule line starts with a leading character 'L' for LPM
+
+*   Route rule line starts with a leading character 'E' for hash-based
+
+*   Comment line, which starts with a leading character '#'
+
+*   Empty line, which consists of a space, form-feed ('\f'), newline ('\n'),
+    carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
+
+Other lines types are considered invalid.
+
+*   A typical IPv4 LPM rule line should have a format as shown below:
+
+
+.. _figure_ipv4_lpm_rule:
+
+.. figure:: img/ipv4_lpm_rule.*
+
+   A typical IPv4 LPM rule
+
+*   A typical IPv4 hash rule line should have a format as shown below:
+
+
+.. _figure_ipv4_hash_rule:
+
+.. figure:: img/ipv4_hash_rule.*
+
+   A typical IPv4 hash rule
+
+Access Control
+~~~~~~~~~~~~~~
+The application demonstrates the use of the ACL library in the DPDK to implement access control
+and packet L3 forwarding.
+The application loads two types of rules at initialization:
+
+*   Route information rules, which are used for L3 forwarding
+
+*   Access Control List (ACL) rules that blacklist (or block) packets with a specific characteristic
+
+When packets are received from a port,
+the application extracts the necessary information from the TCP/IP header of the received packet and
+performs a lookup in the rule database to figure out whether the packets should be dropped (in the ACL range)
+or forwarded to desired ports.
+The initialization and run-time paths are similar to those of the :doc:`l3_forward`.
+However, there are significant differences in the two applications.
+For example, the original L3 forwarding application uses either LPM or
+an exact match algorithm to perform forwarding port lookup,
+while this application uses the ACL library to perform both ACL and route entry lookup.
+The following sections provide more detail.
+
+Classification for both IPv4 and IPv6 packets is supported in this application.
+The application also assumes that all the packets it processes are TCP/UDP packets and
+always extracts source/destination port information from the packets.
+
+Tuple Packet Syntax
+^^^^^^^^^^^^^^^^^^^
+
+The application implements packet classification for the IPv4/IPv6 5-tuple syntax specifically.
+The 5-tuple syntax consist of a source IP address, a destination IP address,
+a source port, a destination port and a protocol identifier.
+The fields in the 5-tuple syntax have the following formats:
+
+*   **Source IP address and destination IP address**
+    : Each is either a 32-bit field (for IPv4), or a set of 4 32-bit fields (for IPv6) represented by a value and a mask length.
+    For example, an IPv4 range of 192.168.1.0 to 192.168.1.255 could be represented by a value = [192, 168, 1, 0] and a mask length = 24.
+
+*   **Source port and destination port**
+    : Each is a 16-bit field, represented by a lower start and a higher end.
+    For example, a range of ports 0 to 8192 could be represented by lower = 0 and higher = 8192.
+
+*   **Protocol identifier**
+    : An 8-bit field, represented by a value and a mask, that covers a range of values.
+    To verify that a value is in the range, use the following expression: "(VAL & mask) == value"
+
+The trick in how to represent a range with a mask and value is as follows.
+A range can be enumerated in binary numbers with some bits that are never changed and some bits that are dynamically changed.
+Set those bits that dynamically changed in mask and value with 0.
+Set those bits that never changed in the mask with 1, in value with number expected.
+For example, a range of 6 to 7 is enumerated as 0b110 and 0b111.
+Bit 1-7 are bits never changed and bit 0 is the bit dynamically changed.
+Therefore, set bit 0 in mask and value with 0, set bits 1-7 in mask with 1, and bits 1-7 in value with number 0b11.
+So, mask is 0xfe, value is 0x6.
+
+.. note::
+
+    The library assumes that each field in the rule is in LSB or Little Endian order when creating the database.
+    It internally converts them to MSB or Big Endian order.
+    When performing a lookup, the library assumes the input is in MSB or Big Endian order.
+
+Access Rule Syntax
+^^^^^^^^^^^^^^^^^^
+
+In this sample application, each rule is a combination of the following:
+
+*   5-tuple field: This field has a format described in Section.
+
+*   priority field: A weight to measure the priority of the rules.
+    The rule with the higher priority will ALWAYS be returned if the specific input has multiple matches in the rule database.
+    Rules with lower priority will NEVER be returned in any cases.
+
+*   userdata field: A user-defined field that could be any value.
+    It can be the forwarding port number if the rule is a route table entry or it can be a pointer to a mapping address
+    if the rule is used for address mapping in the NAT application.
+    The key point is that it is a useful reserved field for user convenience.
+
+ACL and Route Rules
+^^^^^^^^^^^^^^^^^^^
+
+The application needs to acquire ACL and route rules before it runs.
+Route rules are mandatory, while ACL rules are optional.
+To simplify the complexity of the priority field for each rule, all ACL and route entries are assumed to be in the same file.
+To read data from the specified file successfully, the application assumes the following:
+
+*   Each rule occupies a single line.
+
+*   Only the following four rule line types are valid in this application:
+
+*   ACL rule line, which starts with a leading character '@'
+
+*   Route rule line, which starts with a leading character 'R'
+
+*   Comment line, which starts with a leading character '#'
+
+*   Empty line, which consists of a space, form-feed ('\f'), newline ('\n'),
+    carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
+
+Other lines types are considered invalid.
+
+*   Rules are organized in descending order of priority,
+    which means rules at the head of the file always have a higher priority than those further down in the file.
+
+*   A typical IPv4 ACL rule line should have a format as shown below:
+
+
+.. _figure_ipv4_acl_rule:
+
+.. figure:: img/ipv4_acl_rule.*
+
+   A typical IPv4 ACL rule
+
+
+IPv4 addresses are specified in CIDR format as specified in RFC 4632.
+They consist of the dot notation for the address and a prefix length separated by '/'.
+For example, 192.168.0.34/32, where the address is 192.168.0.34 and the prefix length is 32.
+
+Ports are specified as a range of 16-bit numbers in the format MIN:MAX,
+where MIN and MAX are the inclusive minimum and maximum values of the range.
+The range 0:65535 represents all possible ports in a range.
+When MIN and MAX are the same value, a single port is represented, for example, 20:20.
+
+The protocol identifier is an 8-bit value and a mask separated by '/'.
+For example: 6/0xfe matches protocol values 6 and 7.
+
+*   Route rules start with a leading character 'R' and have the same format as ACL rules except an extra field at the tail
+    that indicates the forwarding port number.
+
+Rules File Example
+^^^^^^^^^^^^^^^^^^
+
+.. _figure_example_rules:
+
+.. figure:: img/example_rules.*
+
+   Rules example
+
+
+Each rule is explained as follows:
+
+*   Rule 1 (the first line) tells the application to drop those packets with source IP address = [1.2.3.*],
+    destination IP address = [192.168.0.36], protocol = [6]/[7]
+
+*   Rule 2 (the second line) is similar to Rule 1, except the source IP address is ignored.
+    It tells the application to forward packets with destination IP address = [192.168.0.36],
+    protocol = [6]/[7], destined to port 1.
+
+*   Rule 3 (the third line) tells the application to forward all packets to port 0.
+    This is something like a default route entry.
+
+As described earlier, the application assume rules are listed in descending order of priority,
+therefore Rule 1 has the highest priority, then Rule 2, and finally,
+Rule 3 has the lowest priority.
+
+Consider the arrival of the following three packets:
+
+*   Packet 1 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [6]
+
+*   Packet 2 has source IP address = [1.2.4.4], destination IP address = [192.168.0.36], and protocol = [6]
+
+*   Packet 3 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [8]
+
+Observe that:
+
+*   Packet 1 matches all of the rules
+
+*   Packet 2 matches Rule 2 and Rule 3
+
+*   Packet 3 only matches Rule 3
+
+For priority reasons, Packet 1 matches Rule 1 and is dropped.
+Packet 2 matches Rule 2 and is forwarded to port 1.
+Packet 3 matches Rule 3 and is forwarded to port 0.
+
+For more details on the rule file format,
+please refer to rule_ipv4.db and rule_ipv6.db files (inside <RTE_SDK>/examples/l3fwd-acl/).
+
+Application Phases
+^^^^^^^^^^^^^^^^^^
+
+Once the application starts, it transitions through three phases:
+
+*   **Initialization Phase**
+    - Perform the following tasks:
+
+*   Parse command parameters. Check the validity of rule file(s) name(s), number of logical cores, receive and transmit queues.
+    Bind ports, queues and logical cores. Check ACL search options, and so on.
+
+*   Call Environmental Abstraction Layer (EAL) and Poll Mode Driver (PMD) functions to initialize the environment and detect possible NICs.
+    The EAL creates several threads and sets affinity to a specific hardware thread CPU based on the configuration specified
+    by the command line arguments.
+
+*   Read the rule files and format the rules into the representation that the ACL library can recognize.
+    Call the ACL library function to add the rules into the database and compile them as a trie of pattern sets.
+    Note that application maintains a separate AC contexts for IPv4 and IPv6 rules.
+
+*   **Runtime Phase**
+    - Process the incoming packets from a port. Packets are processed in three steps:
+
+    *   Retrieval: Gets a packet from the receive queue. Each logical core may process several queues for different ports.
+        This depends on the configuration specified by command line arguments.
+
+    *   Lookup: Checks that the packet type is supported (IPv4/IPv6) and performs a 5-tuple lookup over corresponding AC context.
+        If an ACL rule is matched, the packets will be dropped and return back to step 1.
+        If a route rule is matched, it indicates the packet is not in the ACL list and should be forwarded.
+        If there is no matches for the packet, then the packet is dropped.
+
+    *   Forwarding: Forwards the packet to the corresponding port.
+
+*   **Final Phase** - Perform the following tasks:
+
+    Calls the EAL, PMD driver and ACL library to free resource, then quits.
 
 Compiling the Application
 -------------------------
@@ -93,14 +347,18 @@ The application has a number of command line options::
     ./l3fwd [EAL options] -- -p PORTMASK
                              [-P]
                              [-E]
+                             [-A]
                              [-L]
                              --config(port,queue,lcore)[,(port,queue,lcore)]
+                             --rule_ipv4 FILENAME
+                             --rule_ipv6 FILENAME
                              [--eth-dest=X,MM:MM:MM:MM:MM:MM]
                              [--enable-jumbo [--max-pkt-len PKTLEN]]
                              [--no-numa]
                              [--hash-entry-num]
                              [--ipv6]
                              [--parse-ptype]
+                             --scalar
 
 Where,
 
@@ -111,10 +369,18 @@ Where,
 
 * ``-E:`` Optional, enable exact match.
 
+* ``-A:`` Optional, enable access control list match.
+
 * ``-L:`` Optional, enable longest prefix match.
 
 * ``--config (port,queue,lcore)[,(port,queue,lcore)]:`` Determines which queues from which ports are mapped to which cores.
 
+* ``--rule_ipv4 FILENAME:`` Specifies the IPv4 hash-based, LPM, ACL and route rules file
+
+* ``--rule_ipv6 FILENAME:`` Specifies the IPv6 hash-based, LPM, ACL and route rules file
+
+* ``--scalar:`` Use a scalar function to perform ACL rule lookup
+
 * ``--eth-dest=X,MM:MM:MM:MM:MM:MM:`` Optional, ethernet destination for port X.
 
 * ``--enable-jumbo:`` Optional, enables jumbo frames.
@@ -137,7 +403,7 @@ To enable L3 forwarding between two ports, assuming that both ports are in the s
 
 .. code-block:: console
 
-    ./build/l3fwd -l 1,2 -n 4 -- -p 0x3 --config="(0,0,1),(1,0,2)"
+    ./build/l3fwd -l 1,2 -n 4 -- -p 0x3 --config="(0,0,1),(1,0,2) --rule_ipv4="./rule_ipv4.db" -- rule_ipv6="./rule_ipv6.db""
 
 In this command:
 
@@ -159,6 +425,12 @@ In this command:
 |          |           |           |                                     |
 +----------+-----------+-----------+-------------------------------------+
 
+*   The --rule_ipv4 option specifies the reading of IPv4 rules sets from the ./ rule_ipv4.db file.
+
+*   The --rule_ipv6 option specifies the reading of IPv6 rules sets from the ./ rule_ipv6.db file.
+
+*   The --scalar option specifies the performing of ACL rule lookup with a scalar function.
+
 Refer to the *DPDK Getting Started Guide* for general information on running applications and
 the Environment Abstraction Layer (EAL) options.
 
@@ -171,6 +443,22 @@ The following sections provide some explanation of the sample application code.
 the initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
 The following sections describe aspects that are specific to the L3 Forwarding sample application.
 
+Parse Rules from File
+~~~~~~~~~~~~~~~~~~~~~
+
+As described earlier, Hash, LPM and ACL route rules are assumed to be saved in a file.
+For ACL both ACL and route rules are assumed to be saved in the same file.
+The application parses the rules from the file and adds them to the database by calling the respective library function.
+It ignores empty and comment lines, and parses and validates the rules it reads.
+If errors are detected, the application exits with messages to identify the errors encountered.
+
+The application needs to consider the userdata and priority fields for ACL.
+The ACL rules save the index to the specific rules in the userdata field,
+while route rules save the forwarding port number.
+In order to differentiate the two types of rules, ACL rules add a signature in the userdata field.
+As for the priority field, the application assumes rules are organized in descending order of priority.
+Therefore, the code only decreases the priority number with each rule it parses.
+
 Hash Initialization
 ~~~~~~~~~~~~~~~~~~~
 
@@ -194,7 +482,7 @@ for the convenience to execute hash performance test on 4M/8M/16M flows.
 
 .. code-block:: c
 
-    #if (APP_LOOKUP_METHOD == APP_LOOKUP_EXACT_MATCH)
+    #if (-E option used)
 
         static void
         setup_hash(int socketid)
@@ -228,7 +516,7 @@ The LPM object is created and loaded with the pre-configured entries read from a
 
 .. code-block:: c
 
-    #if (APP_LOOKUP_METHOD == APP_LOOKUP_LPM)
+    #if (-L option used)
 
     static void
     setup_lpm(int socketid)
@@ -358,3 +646,23 @@ for LPM-based lookups is done by the get_ipv4_dst_port() function below:
 
         return (uint8_t) ((rte_lpm_lookup(ipv4_l3fwd_lookup_struct, rte_be_to_cpu_32(ipv4_hdr->dst_addr), &next_hop) == 0)? next_hop : portid);
     }
+
+Setting Up the ACL Context
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For each supported AC rule format (IPv4 5-tuple, IPv6 6-tuple) application creates a separate context handler
+from the ACL library for each CPU socket on the board and adds parsed rules into that context.
+
+Note, that for each supported rule type,
+application needs to calculate the expected offset of the fields from the start of the packet.
+That's why only packets with fixed IPv4/ IPv6 header are supported.
+That allows to perform ACL classify straight over incoming packet buffer -
+no extra protocol field retrieval need to be performed.
+
+Subsequently, the application checks whether NUMA is enabled.
+If it is, the application records the socket IDs of the CPU cores involved in the task.
+
+Finally, the application creates contexts handler from the ACL library,
+adds rules parsed from the file into the database and build an ACL trie.
+It is important to note that the application creates an independent copy of each database for each socket CPU
+involved in the task to reduce the time for remote memory access.
diff --git a/doc/guides/sample_app_ug/l3_forward_access_ctrl.rst b/doc/guides/sample_app_ug/l3_forward_access_ctrl.rst
deleted file mode 100644
index a6aa4fb..0000000
--- a/doc/guides/sample_app_ug/l3_forward_access_ctrl.rst
+++ /dev/null
@@ -1,385 +0,0 @@
-..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
-    All rights reserved.
-
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions
-    are met:
-
-    * Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in
-    the documentation and/or other materials provided with the
-    distribution.
-    * Neither the name of Intel Corporation nor the names of its
-    contributors may be used to endorse or promote products derived
-    from this software without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-L3 Forwarding with Access Control Sample Application
-====================================================
-
-The L3 Forwarding with Access Control application is a simple example of packet processing using the DPDK.
-The application performs a security check on received packets.
-Packets that are in the Access Control List (ACL), which is loaded during initialization, are dropped.
-Others are forwarded to the correct port.
-
-Overview
---------
-
-The application demonstrates the use of the ACL library in the DPDK to implement access control
-and packet L3 forwarding.
-The application loads two types of rules at initialization:
-
-*   Route information rules, which are used for L3 forwarding
-
-*   Access Control List (ACL) rules that blacklist (or block) packets with a specific characteristic
-
-When packets are received from a port,
-the application extracts the necessary information from the TCP/IP header of the received packet and
-performs a lookup in the rule database to figure out whether the packets should be dropped (in the ACL range)
-or forwarded to desired ports.
-The initialization and run-time paths are similar to those of the :doc:`l3_forward`.
-However, there are significant differences in the two applications.
-For example, the original L3 forwarding application uses either LPM or
-an exact match algorithm to perform forwarding port lookup,
-while this application uses the ACL library to perform both ACL and route entry lookup.
-The following sections provide more detail.
-
-Classification for both IPv4 and IPv6 packets is supported in this application.
-The application also assumes that all the packets it processes are TCP/UDP packets and
-always extracts source/destination port information from the packets.
-
-Tuple Packet Syntax
-~~~~~~~~~~~~~~~~~~~
-
-The application implements packet classification for the IPv4/IPv6 5-tuple syntax specifically.
-The 5-tuple syntax consist of a source IP address, a destination IP address,
-a source port, a destination port and a protocol identifier.
-The fields in the 5-tuple syntax have the following formats:
-
-*   **Source IP address and destination IP address**
-    : Each is either a 32-bit field (for IPv4), or a set of 4 32-bit fields (for IPv6) represented by a value and a mask length.
-    For example, an IPv4 range of 192.168.1.0 to 192.168.1.255 could be represented by a value = [192, 168, 1, 0] and a mask length = 24.
-
-*   **Source port and destination port**
-    : Each is a 16-bit field, represented by a lower start and a higher end.
-    For example, a range of ports 0 to 8192 could be represented by lower = 0 and higher = 8192.
-
-*   **Protocol identifier**
-    : An 8-bit field, represented by a value and a mask, that covers a range of values.
-    To verify that a value is in the range, use the following expression: "(VAL & mask) == value"
-
-The trick in how to represent a range with a mask and value is as follows.
-A range can be enumerated in binary numbers with some bits that are never changed and some bits that are dynamically changed.
-Set those bits that dynamically changed in mask and value with 0.
-Set those bits that never changed in the mask with 1, in value with number expected.
-For example, a range of 6 to 7 is enumerated as 0b110 and 0b111.
-Bit 1-7 are bits never changed and bit 0 is the bit dynamically changed.
-Therefore, set bit 0 in mask and value with 0, set bits 1-7 in mask with 1, and bits 1-7 in value with number 0b11.
-So, mask is 0xfe, value is 0x6.
-
-.. note::
-
-    The library assumes that each field in the rule is in LSB or Little Endian order when creating the database.
-    It internally converts them to MSB or Big Endian order.
-    When performing a lookup, the library assumes the input is in MSB or Big Endian order.
-
-Access Rule Syntax
-~~~~~~~~~~~~~~~~~~
-
-In this sample application, each rule is a combination of the following:
-
-*   5-tuple field: This field has a format described in Section.
-
-*   priority field: A weight to measure the priority of the rules.
-    The rule with the higher priority will ALWAYS be returned if the specific input has multiple matches in the rule database.
-    Rules with lower priority will NEVER be returned in any cases.
-
-*   userdata field: A user-defined field that could be any value.
-    It can be the forwarding port number if the rule is a route table entry or it can be a pointer to a mapping address
-    if the rule is used for address mapping in the NAT application.
-    The key point is that it is a useful reserved field for user convenience.
-
-ACL and Route Rules
-~~~~~~~~~~~~~~~~~~~
-
-The application needs to acquire ACL and route rules before it runs.
-Route rules are mandatory, while ACL rules are optional.
-To simplify the complexity of the priority field for each rule, all ACL and route entries are assumed to be in the same file.
-To read data from the specified file successfully, the application assumes the following:
-
-*   Each rule occupies a single line.
-
-*   Only the following four rule line types are valid in this application:
-
-*   ACL rule line, which starts with a leading character '@'
-
-*   Route rule line, which starts with a leading character 'R'
-
-*   Comment line, which starts with a leading character '#'
-
-*   Empty line, which consists of a space, form-feed ('\f'), newline ('\n'),
-    carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
-
-Other lines types are considered invalid.
-
-*   Rules are organized in descending order of priority,
-    which means rules at the head of the file always have a higher priority than those further down in the file.
-
-*   A typical IPv4 ACL rule line should have a format as shown below:
-
-
-.. _figure_ipv4_acl_rule:
-
-.. figure:: img/ipv4_acl_rule.*
-
-   A typical IPv4 ACL rule
-
-
-IPv4 addresses are specified in CIDR format as specified in RFC 4632.
-They consist of the dot notation for the address and a prefix length separated by '/'.
-For example, 192.168.0.34/32, where the address is 192.168.0.34 and the prefix length is 32.
-
-Ports are specified as a range of 16-bit numbers in the format MIN:MAX,
-where MIN and MAX are the inclusive minimum and maximum values of the range.
-The range 0:65535 represents all possible ports in a range.
-When MIN and MAX are the same value, a single port is represented, for example, 20:20.
-
-The protocol identifier is an 8-bit value and a mask separated by '/'.
-For example: 6/0xfe matches protocol values 6 and 7.
-
-*   Route rules start with a leading character 'R' and have the same format as ACL rules except an extra field at the tail
-    that indicates the forwarding port number.
-
-Rules File Example
-~~~~~~~~~~~~~~~~~~
-
-.. _figure_example_rules:
-
-.. figure:: img/example_rules.*
-
-   Rules example
-
-
-Each rule is explained as follows:
-
-*   Rule 1 (the first line) tells the application to drop those packets with source IP address = [1.2.3.*],
-    destination IP address = [192.168.0.36], protocol = [6]/[7]
-
-*   Rule 2 (the second line) is similar to Rule 1, except the source IP address is ignored.
-    It tells the application to forward packets with destination IP address = [192.168.0.36],
-    protocol = [6]/[7], destined to port 1.
-
-*   Rule 3 (the third line) tells the application to forward all packets to port 0.
-    This is something like a default route entry.
-
-As described earlier, the application assume rules are listed in descending order of priority,
-therefore Rule 1 has the highest priority, then Rule 2, and finally,
-Rule 3 has the lowest priority.
-
-Consider the arrival of the following three packets:
-
-*   Packet 1 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [6]
-
-*   Packet 2 has source IP address = [1.2.4.4], destination IP address = [192.168.0.36], and protocol = [6]
-
-*   Packet 3 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [8]
-
-Observe that:
-
-*   Packet 1 matches all of the rules
-
-*   Packet 2 matches Rule 2 and Rule 3
-
-*   Packet 3 only matches Rule 3
-
-For priority reasons, Packet 1 matches Rule 1 and is dropped.
-Packet 2 matches Rule 2 and is forwarded to port 1.
-Packet 3 matches Rule 3 and is forwarded to port 0.
-
-For more details on the rule file format,
-please refer to rule_ipv4.db and rule_ipv6.db files (inside <RTE_SDK>/examples/l3fwd-acl/).
-
-Application Phases
-~~~~~~~~~~~~~~~~~~
-
-Once the application starts, it transitions through three phases:
-
-*   **Initialization Phase**
-    - Perform the following tasks:
-
-*   Parse command parameters. Check the validity of rule file(s) name(s), number of logical cores, receive and transmit queues.
-    Bind ports, queues and logical cores. Check ACL search options, and so on.
-
-*   Call Environmental Abstraction Layer (EAL) and Poll Mode Driver (PMD) functions to initialize the environment and detect possible NICs.
-    The EAL creates several threads and sets affinity to a specific hardware thread CPU based on the configuration specified
-    by the command line arguments.
-
-*   Read the rule files and format the rules into the representation that the ACL library can recognize.
-    Call the ACL library function to add the rules into the database and compile them as a trie of pattern sets.
-    Note that application maintains a separate AC contexts for IPv4 and IPv6 rules.
-
-*   **Runtime Phase**
-    - Process the incoming packets from a port. Packets are processed in three steps:
-
-    *   Retrieval: Gets a packet from the receive queue. Each logical core may process several queues for different ports.
-        This depends on the configuration specified by command line arguments.
-
-    *   Lookup: Checks that the packet type is supported (IPv4/IPv6) and performs a 5-tuple lookup over corresponding AC context.
-        If an ACL rule is matched, the packets will be dropped and return back to step 1.
-        If a route rule is matched, it indicates the packet is not in the ACL list and should be forwarded.
-        If there is no matches for the packet, then the packet is dropped.
-
-    *   Forwarding: Forwards the packet to the corresponding port.
-
-*   **Final Phase** - Perform the following tasks:
-
-    Calls the EAL, PMD driver and ACL library to free resource, then quits.
-
-Compiling the Application
--------------------------
-
-To compile the application:
-
-#.  Go to the sample application directory:
-
-    ..  code-block:: console
-
-        export RTE_SDK=/path/to/rte_sdk
-        cd ${RTE_SDK}/examples/l3fwd-acl
-
-#.  Set the target (a default target is used if not specified). For example:
-
-    ..  code-block:: console
-
-        export RTE_TARGET=x86_64-native-linuxapp-gcc
-
-    See the *DPDK IPL Getting Started Guide* for possible RTE_TARGET values.
-
-#.  Build the application:
-
-    ..  code-block:: console
-
-        make
-
-Running the Application
------------------------
-
-The application has a number of command line options:
-
-..  code-block:: console
-
-    ./build/l3fwd-acl [EAL options] -- -p PORTMASK [-P] --config(port,queue,lcore)[,(port,queue,lcore)] --rule_ipv4 FILENAME rule_ipv6 FILENAME [--scalar] [--enable-jumbo [--max-pkt-len PKTLEN]] [--no-numa]
-
-
-where,
-
-*   -p PORTMASK: Hexadecimal bitmask of ports to configure
-
-*   -P: Sets all ports to promiscuous mode so that packets are accepted regardless of the packet's Ethernet MAC destination address.
-    Without this option, only packets with the Ethernet MAC destination address set to the Ethernet address of the port are accepted.
-
-*   --config (port,queue,lcore)[,(port,queue,lcore)]: determines which queues from which ports are mapped to which cores
-
-*   --rule_ipv4 FILENAME: Specifies the IPv4 ACL and route rules file
-
-*   --rule_ipv6 FILENAME: Specifies the IPv6 ACL and route rules file
-
-*   --scalar: Use a scalar function to perform rule lookup
-
-*   --enable-jumbo: optional, enables jumbo frames
-
-*   --max-pkt-len: optional, maximum packet length in decimal (64-9600)
-
-*   --no-numa: optional, disables numa awareness
-
-For example, consider a dual processor socket platform with 8 physical cores, where cores 0-7 and 16-23 appear on socket 0,
-while cores 8-15 and 24-31 appear on socket 1.
-
-To enable L3 forwarding between two ports, assuming that both ports are in the same socket, using two cores, cores 1 and 2,
-(which are in the same socket too), use the following command:
-
-..  code-block:: console
-
-    ./build/l3fwd-acl -l 1,2 -n 4 -- -p 0x3 --config="(0,0,1),(1,0,2)" --rule_ipv4="./rule_ipv4.db" -- rule_ipv6="./rule_ipv6.db" --scalar
-
-In this command:
-
-*   The -l option enables cores 1, 2
-
-*   The -p option enables ports 0 and 1
-
-*   The --config option enables one queue on each port and maps each (port,queue) pair to a specific core.
-    The following table shows the mapping in this example:
-
-    +----------+------------+-----------+-------------------------------------+
-    | **Port** | **Queue**  | **lcore** |            **Description**          |
-    |          |            |           |                                     |
-    +==========+============+===========+=====================================+
-    | 0        | 0          | 1         | Map queue 0 from port 0 to lcore 1. |
-    |          |            |           |                                     |
-    +----------+------------+-----------+-------------------------------------+
-    | 1        | 0          | 2         | Map queue 0 from port 1 to lcore 2. |
-    |          |            |           |                                     |
-    +----------+------------+-----------+-------------------------------------+
-
-*   The --rule_ipv4 option specifies the reading of IPv4 rules sets from the ./ rule_ipv4.db file.
-
-*   The --rule_ipv6 option specifies the reading of IPv6 rules sets from the ./ rule_ipv6.db file.
-
-*   The --scalar option specifies the performing of rule lookup with a scalar function.
-
-Explanation
------------
-
-The following sections provide some explanation of the sample application code.
-The aspects of port, device and CPU configuration are similar to those of the :doc:`l3_forward`.
-The following sections describe aspects that are specific to L3 forwarding with access control.
-
-Parse Rules from File
-~~~~~~~~~~~~~~~~~~~~~
-
-As described earlier, both ACL and route rules are assumed to be saved in the same file.
-The application parses the rules from the file and adds them to the database by calling the ACL library function.
-It ignores empty and comment lines, and parses and validates the rules it reads.
-If errors are detected, the application exits with messages to identify the errors encountered.
-
-The application needs to consider the userdata and priority fields.
-The ACL rules save the index to the specific rules in the userdata field,
-while route rules save the forwarding port number.
-In order to differentiate the two types of rules, ACL rules add a signature in the userdata field.
-As for the priority field, the application assumes rules are organized in descending order of priority.
-Therefore, the code only decreases the priority number with each rule it parses.
-
-Setting Up the ACL Context
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For each supported AC rule format (IPv4 5-tuple, IPv6 6-tuple) application creates a separate context handler
-from the ACL library for each CPU socket on the board and adds parsed rules into that context.
-
-Note, that for each supported rule type,
-application needs to calculate the expected offset of the fields from the start of the packet.
-That's why only packets with fixed IPv4/ IPv6 header are supported.
-That allows to perform ACL classify straight over incoming packet buffer -
-no extra protocol field retrieval need to be performed.
-
-Subsequently, the application checks whether NUMA is enabled.
-If it is, the application records the socket IDs of the CPU cores involved in the task.
-
-Finally, the application creates contexts handler from the ACL library,
-adds rules parsed from the file into the database and build an ACL trie.
-It is important to note that the application creates an independent copy of each database for each socket CPU
-involved in the task to reduce the time for remote memory access.
-- 
2.7.4

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [dpdk-dev] [PATCH v1] doc: Merge l3fwd and l3fwd-acl documentation files
  2017-05-07 20:50 ` Thomas Monjalon
@ 2017-05-08 21:04   ` Ravi Kerur
  0 siblings, 0 replies; 10+ messages in thread
From: Ravi Kerur @ 2017-05-08 21:04 UTC (permalink / raw)
  To: Thomas Monjalon; +Cc: dev, Ananyev, Konstantin

On Sun, May 7, 2017 at 1:50 PM, Thomas Monjalon <thomas@monjalon.net> wrote:

> Hi,
>
> 25/04/2017 20:39, Ravi Kerur:
> > Merge relevant contents of l3fwd and l3fwd-acl documentation.
> > Modify l3fwd document with ACL specific information.
> > Remove l3fwd-acl documentation file.
> >
> > Signed-off-by: Ravi Kerur <rkerur@gmail.com>
> > ---
> >  doc/guides/sample_app_ug/img/ipv4_hash_rule.svg    | 158 +++++++++
> >  doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg     | 139 ++++++++
> >  doc/guides/sample_app_ug/index.rst                 |   1 -
> >  doc/guides/sample_app_ug/l3_forward.rst            | 326
> ++++++++++++++++-
> >  .../sample_app_ug/l3_forward_access_ctrl.rst       | 385
> ---------------------
> >  5 files changed, 614 insertions(+), 395 deletions(-)
> >  create mode 100644 doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
> >  create mode 100644 doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
> >  delete mode 100644 doc/guides/sample_app_ug/l3_forward_access_ctrl.rst
>
> I've not looked at the content.
> I just do not understand why a patch for merging content is adding
> some new files.
> Moreover, these SVG files contains some binary PNG.
> Please send only some source files.
>

Thanks John and Thomas for review.

We have created two new ".svg" files illustrating an example for LPM and
Exact Match rules and hence they are reflected in the patch.
I have created .svg files directly from inkscape and they now contain only
html.

I have sent 'v2', please review it and let me know if additional changes
are required.

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [dpdk-dev] [PATCH v2] doc: Merge l3fwd and l3fwd-acl documentation files
  2017-05-08 21:00 ` [dpdk-dev] [PATCH v2] " Ravi Kerur
@ 2017-05-10 10:14   ` Mcnamara, John
  2017-05-11  1:51     ` Ravi Kerur
  2017-05-11  1:49   ` [dpdk-dev] [PATCH v3] " Ravi Kerur
  1 sibling, 1 reply; 10+ messages in thread
From: Mcnamara, John @ 2017-05-10 10:14 UTC (permalink / raw)
  To: Ravi Kerur, dev; +Cc: thomas



> -----Original Message-----
> From: Ravi Kerur [mailto:rkerur@gmail.com]
> Sent: Monday, May 8, 2017 10:00 PM
> To: dev@dpdk.org
> Cc: Mcnamara, John <john.mcnamara@intel.com>; thomas@monjalon.net; Ravi
> Kerur <rkerur@gmail.com>
> Subject: [PATCH v2] doc: Merge l3fwd and l3fwd-acl documentation files
> 
> Merge l3fwd and l3fwd-acl documentation to reflect the code.
> Add examples of LPM and Exact Match rules in .svg files.
> 
> Signed-off-by: Ravi Kerur <rkerur@gmail.com>
> ---
> v2:
> 	Remove binary PNG from .svg files.
> 
> v1:
> 	Merge relevant contents of l3fwd and l3fwd-acl documentation.
> 	Modify l3fwd document with ACL specific information.
> 	Remove l3fwd-acl documentation file.
> ---
>  doc/guides/sample_app_ug/img/ipv4_hash_rule.svg    | 108 ++++++
>  doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg     |  96 +++++
>  doc/guides/sample_app_ug/index.rst                 |   1 -
>  doc/guides/sample_app_ug/l3_forward.rst            | 326
> ++++++++++++++++-
>  .../sample_app_ug/l3_forward_access_ctrl.rst       | 385 ----------------
> -----
>  5 files changed, 521 insertions(+), 395 deletions(-)  create mode 100644
> doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
>  create mode 100644 doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
> 


Thanks once more for the doc. Some comments below.


> ...
>      Redistribution and use in source and binary forms, with or without @@
> -31,12 +31,18 @@
>  L3 Forwarding Sample Application
>  ================================
> 
> -The L3 Forwarding application is a simple example of packet processing
> using the DPDK.
> -The application performs L3 forwarding.
> +The L3 Forwarding with Hash, LPM or Access Control application is a
> simple example of packet processing using the DPDK.
> +The application performs L3 forwarding when Hash or LPM is used.
> +The application performs a security check on received packets when Access
> Control is used.
> +Packets that are in the Access Control List (ACL), which is loaded during
> initialization, are dropped.
> +Others are forwarded to the correct port.


For the introduction I would suggest the following rewording:

L3 Forwarding Sample Application
================================

The L3 Forwarding application is a simple example of packet processing using
the DPDK with Hash, LPM (Longest Prefix match) or Access Control.

The application performs L3 forwarding when Hash or LPM is used.
Alternatively, the application performs a security check on received packets
when Access Control is used.  Packets that are in the Access Control List
(ACL), which is loaded during initialization, are dropped.  Others packets are
forwarded to the correct port.




>  The main difference from the L2 Forwarding sample application is that the
> forwarding decision @@ -49,15 +55,263 @@ The hash object is used in
> correlation with a flow table to map each input packe  The hash lookup key
> is represented by a DiffServ 5-tuple composed of the following fields read
> from the input packet:
>  Source IP Address, Destination IP Address, Protocol, Source Port and
> Destination Port.

This is fine but would be a bit clearer as a list:


The hash lookup key is represented by a 5-tuple composed of the following fields read from the input packet:

* Source IP Address.
* Destination IP Address.
* Protocol.
* Source Port.
* Destination Port.



> +
> +.. _figure_ipv4_lpm_rule:
> +
> +.. figure:: img/ipv4_lpm_rule.*
> +
> +   A typical IPv4 LPM rule
> +
> +*   A typical IPv4 hash rule line should have a format as shown below:
> +
> +
> +.. _figure_ipv4_hash_rule:
> +
> +.. figure:: img/ipv4_hash_rule.*
> +
> +   A typical IPv4 hash rule
> +


Unfortunately these figures don't render very well. I would suggest replacing
them with text, like below:


A typical IPv4 LPM rule line in an input file would look like the following::


    # Dest Address/mask   Eth port
    # =================   ========

    L100.10.10.10/24      0


A typical IPv4 Hash rule line in an input file would look like the following::

    # Src Address  Dst Address  Src Port  Dst port  Protocol  Eth port
    # ===========  ===========  ========  ========  ========  ========

    E100.10.10.0  100.10.0.0    110       111       0x6       0


There a few other thing that could be improved in the doc but these issues were
already there in text that you are merging so apart from these suggestion
the rest of the doc is okay for now. We should try to come back and improve
the consistency at a later date.

John

^ permalink raw reply	[flat|nested] 10+ messages in thread

* [dpdk-dev] [PATCH v3] doc: Merge l3fwd and l3fwd-acl documentation files
  2017-05-08 21:00 ` [dpdk-dev] [PATCH v2] " Ravi Kerur
  2017-05-10 10:14   ` Mcnamara, John
@ 2017-05-11  1:49   ` Ravi Kerur
  2017-05-16  9:27     ` Mcnamara, John
  1 sibling, 1 reply; 10+ messages in thread
From: Ravi Kerur @ 2017-05-11  1:49 UTC (permalink / raw)
  To: dev; +Cc: john.mcnamara, Ravi Kerur

Merge l3fwd and l3fwd-acl documentation to reflect the code.
Add examples of LPM and Exact Match rules as text.

Signed-off-by: Ravi Kerur <rkerur@gmail.com>
---
v3:
	Incorporate John's comments.
	Remove svg files, instead include text format.

v2:
        Remove binary PNG from .svg files.

v1:
        Merge relevant contents of l3fwd and l3fwd-acl documentation.
        Modify l3fwd document with ACL specific information.
        Remove l3fwd-acl documentation file.
---
---
 doc/guides/sample_app_ug/index.rst                 |   1 -
 doc/guides/sample_app_ug/l3_forward.rst            | 332 +++++++++++++++++-
 .../sample_app_ug/l3_forward_access_ctrl.rst       | 385 ---------------------
 3 files changed, 322 insertions(+), 396 deletions(-)
 delete mode 100644 doc/guides/sample_app_ug/l3_forward_access_ctrl.rst

diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
index 02611ef..62cafb0 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -53,7 +53,6 @@ Sample Applications User Guides
     l2_forward_cat
     l3_forward
     l3_forward_power_man
-    l3_forward_access_ctrl
     l3_forward_virtual
     link_status_intr
     load_balancer
diff --git a/doc/guides/sample_app_ug/l3_forward.rst b/doc/guides/sample_app_ug/l3_forward.rst
index 6a6b8fb..f6a17b8 100644
--- a/doc/guides/sample_app_ug/l3_forward.rst
+++ b/doc/guides/sample_app_ug/l3_forward.rst
@@ -1,5 +1,5 @@
 ..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+    Copyright(c) 2010-2017 Intel Corporation. All rights reserved.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -31,12 +31,20 @@
 L3 Forwarding Sample Application
 ================================
 
-The L3 Forwarding application is a simple example of packet processing using the DPDK.
-The application performs L3 forwarding.
+The L3 Forwarding with Hash, LPM or Access Control application is a simple example of packet processing using
+the DPDK with Hash, LPM (Longest Prefix match) or Access Control..
+The application performs L3 forwarding when Hash or LPM is used.
+Alternatively, the application performs a security check on received packets
+when Access Control is used.  Packets that are in the Access Control List
+(ACL), which is loaded during initialization, are dropped.  Others packets are
+forwarded to the correct port.
 
 Overview
 --------
 
+Hash and LPM
+~~~~~~~~~~~~
+
 The application demonstrates the use of the hash and LPM libraries in the DPDK to implement packet forwarding.
 The initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
 The main difference from the L2 Forwarding sample application is that the forwarding decision
@@ -47,17 +55,267 @@ a hash object is used to emulate the flow classification stage.
 The hash object is used in correlation with a flow table to map each input packet to its flow at runtime.
 
 The hash lookup key is represented by a DiffServ 5-tuple composed of the following fields read from the input packet:
-Source IP Address, Destination IP Address, Protocol, Source Port and Destination Port.
+
+* Source IP Address.
+* Destination IP Address.
+* Protocol.
+* Source Port.
+* Destination Port.
+
 The ID of the output interface for the input packet is read from the identified flow table entry.
-The set of flows used by the application is statically configured and loaded into the hash at initialization time.
 When the selected lookup method is LPM based, an LPM object is used to emulate the forwarding stage for IPv4 packets.
 The LPM object is used as the routing table to identify the next hop for each input packet at runtime.
 
 The LPM lookup key is represented by the Destination IP Address field read from the input packet.
 The ID of the output interface for the input packet is the next hop returned by the LPM lookup.
-The set of LPM rules used by the application is statically configured and loaded into the LPM object at initialization time.
 
-In the sample application, hash-based forwarding supports IPv4 and IPv6. LPM-based forwarding supports IPv4 only.
+In the sample application, both hash-based and LPM forwarding supports IPv4 and IPv6.
+
+The application loads rules at initialization which are used for L3 forwarding.
+The application needs to acquire route rules before it runs.
+
+To read data from the specified file successfully, the application assumes the following:
+
+*   Each rule occupies a single line.
+
+*   Only the following four rule line types are valid in this application:
+
+*   Route rule line starts with a leading character 'L' for LPM
+
+*   Route rule line starts with a leading character 'E' for hash-based
+
+*   Comment line, which starts with a leading character '#'
+
+*   Empty line, which consists of a space, form-feed ('\f'), newline ('\n'),
+    carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
+
+Other lines types are considered invalid.
+
+A typical IPv4 LPM rule line in an input file would look like the following::
+
+    # Dest Address/mask   Eth port
+    # =================   ========
+
+    L100.10.10.10/24      0
+
+A typical IPv4 Hash rule line in an input file would look like the following::
+
+    # Src Address  Dst Address  Src Port  Dst port  Protocol  Eth port
+    # ===========  ===========  ========  ========  ========  ========
+
+    E100.10.10.0  100.10.0.0    110       111       0x6       0
+
+Access Control
+~~~~~~~~~~~~~~
+The application demonstrates the use of the ACL library in the DPDK to implement access control
+and packet L3 forwarding.
+The application loads two types of rules at initialization:
+
+*   Route information rules, which are used for L3 forwarding
+
+*   Access Control List (ACL) rules that blacklist (or block) packets with a specific characteristic
+
+When packets are received from a port,
+the application extracts the necessary information from the TCP/IP header of the received packet and
+performs a lookup in the rule database to figure out whether the packets should be dropped (in the ACL range)
+or forwarded to desired ports.
+The initialization and run-time paths are similar to those of the :doc:`l3_forward`.
+However, there are significant differences in the two applications.
+For example, the original L3 forwarding application uses either LPM or
+an exact match algorithm to perform forwarding port lookup,
+while this application uses the ACL library to perform both ACL and route entry lookup.
+The following sections provide more detail.
+
+Classification for both IPv4 and IPv6 packets is supported in this application.
+The application also assumes that all the packets it processes are TCP/UDP packets and
+always extracts source/destination port information from the packets.
+
+Tuple Packet Syntax
+^^^^^^^^^^^^^^^^^^^
+
+The application implements packet classification for the IPv4/IPv6 5-tuple syntax specifically.
+The 5-tuple syntax consist of a source IP address, a destination IP address,
+a source port, a destination port and a protocol identifier.
+The fields in the 5-tuple syntax have the following formats:
+
+*   **Source IP address and destination IP address**
+    : Each is either a 32-bit field (for IPv4), or a set of 4 32-bit fields (for IPv6) represented by a value and a mask length.
+    For example, an IPv4 range of 192.168.1.0 to 192.168.1.255 could be represented by a value = [192, 168, 1, 0] and a mask length = 24.
+
+*   **Source port and destination port**
+    : Each is a 16-bit field, represented by a lower start and a higher end.
+    For example, a range of ports 0 to 8192 could be represented by lower = 0 and higher = 8192.
+
+*   **Protocol identifier**
+    : An 8-bit field, represented by a value and a mask, that covers a range of values.
+    To verify that a value is in the range, use the following expression: "(VAL & mask) == value"
+
+The trick in how to represent a range with a mask and value is as follows.
+A range can be enumerated in binary numbers with some bits that are never changed and some bits that are dynamically changed.
+Set those bits that dynamically changed in mask and value with 0.
+Set those bits that never changed in the mask with 1, in value with number expected.
+For example, a range of 6 to 7 is enumerated as 0b110 and 0b111.
+Bit 1-7 are bits never changed and bit 0 is the bit dynamically changed.
+Therefore, set bit 0 in mask and value with 0, set bits 1-7 in mask with 1, and bits 1-7 in value with number 0b11.
+So, mask is 0xfe, value is 0x6.
+
+.. note::
+
+    The library assumes that each field in the rule is in LSB or Little Endian order when creating the database.
+    It internally converts them to MSB or Big Endian order.
+    When performing a lookup, the library assumes the input is in MSB or Big Endian order.
+
+Access Rule Syntax
+^^^^^^^^^^^^^^^^^^
+
+In this sample application, each rule is a combination of the following:
+
+*   5-tuple field: This field has a format described in Section.
+
+*   priority field: A weight to measure the priority of the rules.
+    The rule with the higher priority will ALWAYS be returned if the specific input has multiple matches in the rule database.
+    Rules with lower priority will NEVER be returned in any cases.
+
+*   userdata field: A user-defined field that could be any value.
+    It can be the forwarding port number if the rule is a route table entry or it can be a pointer to a mapping address
+    if the rule is used for address mapping in the NAT application.
+    The key point is that it is a useful reserved field for user convenience.
+
+ACL and Route Rules
+^^^^^^^^^^^^^^^^^^^
+
+The application needs to acquire ACL and route rules before it runs.
+Route rules are mandatory, while ACL rules are optional.
+To simplify the complexity of the priority field for each rule, all ACL and route entries are assumed to be in the same file.
+To read data from the specified file successfully, the application assumes the following:
+
+*   Each rule occupies a single line.
+
+*   Only the following four rule line types are valid in this application:
+
+*   ACL rule line, which starts with a leading character '@'
+
+*   Route rule line, which starts with a leading character 'R'
+
+*   Comment line, which starts with a leading character '#'
+
+*   Empty line, which consists of a space, form-feed ('\f'), newline ('\n'),
+    carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
+
+Other lines types are considered invalid.
+
+*   Rules are organized in descending order of priority,
+    which means rules at the head of the file always have a higher priority than those further down in the file.
+
+*   A typical IPv4 ACL rule line should have a format as shown below:
+
+
+.. _figure_ipv4_acl_rule:
+
+.. figure:: img/ipv4_acl_rule.*
+
+   A typical IPv4 ACL rule
+
+
+IPv4 addresses are specified in CIDR format as specified in RFC 4632.
+They consist of the dot notation for the address and a prefix length separated by '/'.
+For example, 192.168.0.34/32, where the address is 192.168.0.34 and the prefix length is 32.
+
+Ports are specified as a range of 16-bit numbers in the format MIN:MAX,
+where MIN and MAX are the inclusive minimum and maximum values of the range.
+The range 0:65535 represents all possible ports in a range.
+When MIN and MAX are the same value, a single port is represented, for example, 20:20.
+
+The protocol identifier is an 8-bit value and a mask separated by '/'.
+For example: 6/0xfe matches protocol values 6 and 7.
+
+*   Route rules start with a leading character 'R' and have the same format as ACL rules except an extra field at the tail
+    that indicates the forwarding port number.
+
+Rules File Example
+^^^^^^^^^^^^^^^^^^
+
+.. _figure_example_rules:
+
+.. figure:: img/example_rules.*
+
+   Rules example
+
+
+Each rule is explained as follows:
+
+*   Rule 1 (the first line) tells the application to drop those packets with source IP address = [1.2.3.*],
+    destination IP address = [192.168.0.36], protocol = [6]/[7]
+
+*   Rule 2 (the second line) is similar to Rule 1, except the source IP address is ignored.
+    It tells the application to forward packets with destination IP address = [192.168.0.36],
+    protocol = [6]/[7], destined to port 1.
+
+*   Rule 3 (the third line) tells the application to forward all packets to port 0.
+    This is something like a default route entry.
+
+As described earlier, the application assume rules are listed in descending order of priority,
+therefore Rule 1 has the highest priority, then Rule 2, and finally,
+Rule 3 has the lowest priority.
+
+Consider the arrival of the following three packets:
+
+*   Packet 1 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [6]
+
+*   Packet 2 has source IP address = [1.2.4.4], destination IP address = [192.168.0.36], and protocol = [6]
+
+*   Packet 3 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [8]
+
+Observe that:
+
+*   Packet 1 matches all of the rules
+
+*   Packet 2 matches Rule 2 and Rule 3
+
+*   Packet 3 only matches Rule 3
+
+For priority reasons, Packet 1 matches Rule 1 and is dropped.
+Packet 2 matches Rule 2 and is forwarded to port 1.
+Packet 3 matches Rule 3 and is forwarded to port 0.
+
+For more details on the rule file format,
+please refer to rule_ipv4.db and rule_ipv6.db files (inside <RTE_SDK>/examples/l3fwd-acl/).
+
+Application Phases
+^^^^^^^^^^^^^^^^^^
+
+Once the application starts, it transitions through three phases:
+
+*   **Initialization Phase**
+    - Perform the following tasks:
+
+*   Parse command parameters. Check the validity of rule file(s) name(s), number of logical cores, receive and transmit queues.
+    Bind ports, queues and logical cores. Check ACL search options, and so on.
+
+*   Call Environmental Abstraction Layer (EAL) and Poll Mode Driver (PMD) functions to initialize the environment and detect possible NICs.
+    The EAL creates several threads and sets affinity to a specific hardware thread CPU based on the configuration specified
+    by the command line arguments.
+
+*   Read the rule files and format the rules into the representation that the ACL library can recognize.
+    Call the ACL library function to add the rules into the database and compile them as a trie of pattern sets.
+    Note that application maintains a separate AC contexts for IPv4 and IPv6 rules.
+
+*   **Runtime Phase**
+    - Process the incoming packets from a port. Packets are processed in three steps:
+
+    *   Retrieval: Gets a packet from the receive queue. Each logical core may process several queues for different ports.
+        This depends on the configuration specified by command line arguments.
+
+    *   Lookup: Checks that the packet type is supported (IPv4/IPv6) and performs a 5-tuple lookup over corresponding AC context.
+        If an ACL rule is matched, the packets will be dropped and return back to step 1.
+        If a route rule is matched, it indicates the packet is not in the ACL list and should be forwarded.
+        If there is no matches for the packet, then the packet is dropped.
+
+    *   Forwarding: Forwards the packet to the corresponding port.
+
+*   **Final Phase** - Perform the following tasks:
+
+    Calls the EAL, PMD driver and ACL library to free resource, then quits.
 
 Compiling the Application
 -------------------------
@@ -93,14 +351,18 @@ The application has a number of command line options::
     ./l3fwd [EAL options] -- -p PORTMASK
                              [-P]
                              [-E]
+                             [-A]
                              [-L]
                              --config(port,queue,lcore)[,(port,queue,lcore)]
+                             --rule_ipv4 FILENAME
+                             --rule_ipv6 FILENAME
                              [--eth-dest=X,MM:MM:MM:MM:MM:MM]
                              [--enable-jumbo [--max-pkt-len PKTLEN]]
                              [--no-numa]
                              [--hash-entry-num]
                              [--ipv6]
                              [--parse-ptype]
+                             --scalar
 
 Where,
 
@@ -111,10 +373,18 @@ Where,
 
 * ``-E:`` Optional, enable exact match.
 
+* ``-A:`` Optional, enable access control list match.
+
 * ``-L:`` Optional, enable longest prefix match.
 
 * ``--config (port,queue,lcore)[,(port,queue,lcore)]:`` Determines which queues from which ports are mapped to which cores.
 
+* ``--rule_ipv4 FILENAME:`` Specifies the IPv4 hash-based, LPM, ACL and route rules file
+
+* ``--rule_ipv6 FILENAME:`` Specifies the IPv6 hash-based, LPM, ACL and route rules file
+
+* ``--scalar:`` Use a scalar function to perform ACL rule lookup
+
 * ``--eth-dest=X,MM:MM:MM:MM:MM:MM:`` Optional, ethernet destination for port X.
 
 * ``--enable-jumbo:`` Optional, enables jumbo frames.
@@ -137,7 +407,7 @@ To enable L3 forwarding between two ports, assuming that both ports are in the s
 
 .. code-block:: console
 
-    ./build/l3fwd -l 1,2 -n 4 -- -p 0x3 --config="(0,0,1),(1,0,2)"
+    ./build/l3fwd -l 1,2 -n 4 -- -p 0x3 --config="(0,0,1),(1,0,2) --rule_ipv4="./rule_ipv4.db" -- rule_ipv6="./rule_ipv6.db""
 
 In this command:
 
@@ -159,6 +429,12 @@ In this command:
 |          |           |           |                                     |
 +----------+-----------+-----------+-------------------------------------+
 
+*   The --rule_ipv4 option specifies the reading of IPv4 rules sets from the ./ rule_ipv4.db file.
+
+*   The --rule_ipv6 option specifies the reading of IPv6 rules sets from the ./ rule_ipv6.db file.
+
+*   The --scalar option specifies the performing of ACL rule lookup with a scalar function.
+
 Refer to the *DPDK Getting Started Guide* for general information on running applications and
 the Environment Abstraction Layer (EAL) options.
 
@@ -171,6 +447,22 @@ The following sections provide some explanation of the sample application code.
 the initialization and run-time paths are very similar to those of the :doc:`l2_forward_real_virtual`.
 The following sections describe aspects that are specific to the L3 Forwarding sample application.
 
+Parse Rules from File
+~~~~~~~~~~~~~~~~~~~~~
+
+As described earlier, Hash, LPM and ACL route rules are assumed to be saved in a file.
+For ACL both ACL and route rules are assumed to be saved in the same file.
+The application parses the rules from the file and adds them to the database by calling the respective library function.
+It ignores empty and comment lines, and parses and validates the rules it reads.
+If errors are detected, the application exits with messages to identify the errors encountered.
+
+The application needs to consider the userdata and priority fields for ACL.
+The ACL rules save the index to the specific rules in the userdata field,
+while route rules save the forwarding port number.
+In order to differentiate the two types of rules, ACL rules add a signature in the userdata field.
+As for the priority field, the application assumes rules are organized in descending order of priority.
+Therefore, the code only decreases the priority number with each rule it parses.
+
 Hash Initialization
 ~~~~~~~~~~~~~~~~~~~
 
@@ -194,7 +486,7 @@ for the convenience to execute hash performance test on 4M/8M/16M flows.
 
 .. code-block:: c
 
-    #if (APP_LOOKUP_METHOD == APP_LOOKUP_EXACT_MATCH)
+    #if (-E option used)
 
         static void
         setup_hash(int socketid)
@@ -228,7 +520,7 @@ The LPM object is created and loaded with the pre-configured entries read from a
 
 .. code-block:: c
 
-    #if (APP_LOOKUP_METHOD == APP_LOOKUP_LPM)
+    #if (-L option used)
 
     static void
     setup_lpm(int socketid)
@@ -358,3 +650,23 @@ for LPM-based lookups is done by the get_ipv4_dst_port() function below:
 
         return (uint8_t) ((rte_lpm_lookup(ipv4_l3fwd_lookup_struct, rte_be_to_cpu_32(ipv4_hdr->dst_addr), &next_hop) == 0)? next_hop : portid);
     }
+
+Setting Up the ACL Context
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For each supported AC rule format (IPv4 5-tuple, IPv6 6-tuple) application creates a separate context handler
+from the ACL library for each CPU socket on the board and adds parsed rules into that context.
+
+Note, that for each supported rule type,
+application needs to calculate the expected offset of the fields from the start of the packet.
+That's why only packets with fixed IPv4/ IPv6 header are supported.
+That allows to perform ACL classify straight over incoming packet buffer -
+no extra protocol field retrieval need to be performed.
+
+Subsequently, the application checks whether NUMA is enabled.
+If it is, the application records the socket IDs of the CPU cores involved in the task.
+
+Finally, the application creates contexts handler from the ACL library,
+adds rules parsed from the file into the database and build an ACL trie.
+It is important to note that the application creates an independent copy of each database for each socket CPU
+involved in the task to reduce the time for remote memory access.
diff --git a/doc/guides/sample_app_ug/l3_forward_access_ctrl.rst b/doc/guides/sample_app_ug/l3_forward_access_ctrl.rst
deleted file mode 100644
index a6aa4fb..0000000
--- a/doc/guides/sample_app_ug/l3_forward_access_ctrl.rst
+++ /dev/null
@@ -1,385 +0,0 @@
-..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
-    All rights reserved.
-
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions
-    are met:
-
-    * Redistributions of source code must retain the above copyright
-    notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-    notice, this list of conditions and the following disclaimer in
-    the documentation and/or other materials provided with the
-    distribution.
-    * Neither the name of Intel Corporation nor the names of its
-    contributors may be used to endorse or promote products derived
-    from this software without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-    OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-L3 Forwarding with Access Control Sample Application
-====================================================
-
-The L3 Forwarding with Access Control application is a simple example of packet processing using the DPDK.
-The application performs a security check on received packets.
-Packets that are in the Access Control List (ACL), which is loaded during initialization, are dropped.
-Others are forwarded to the correct port.
-
-Overview
---------
-
-The application demonstrates the use of the ACL library in the DPDK to implement access control
-and packet L3 forwarding.
-The application loads two types of rules at initialization:
-
-*   Route information rules, which are used for L3 forwarding
-
-*   Access Control List (ACL) rules that blacklist (or block) packets with a specific characteristic
-
-When packets are received from a port,
-the application extracts the necessary information from the TCP/IP header of the received packet and
-performs a lookup in the rule database to figure out whether the packets should be dropped (in the ACL range)
-or forwarded to desired ports.
-The initialization and run-time paths are similar to those of the :doc:`l3_forward`.
-However, there are significant differences in the two applications.
-For example, the original L3 forwarding application uses either LPM or
-an exact match algorithm to perform forwarding port lookup,
-while this application uses the ACL library to perform both ACL and route entry lookup.
-The following sections provide more detail.
-
-Classification for both IPv4 and IPv6 packets is supported in this application.
-The application also assumes that all the packets it processes are TCP/UDP packets and
-always extracts source/destination port information from the packets.
-
-Tuple Packet Syntax
-~~~~~~~~~~~~~~~~~~~
-
-The application implements packet classification for the IPv4/IPv6 5-tuple syntax specifically.
-The 5-tuple syntax consist of a source IP address, a destination IP address,
-a source port, a destination port and a protocol identifier.
-The fields in the 5-tuple syntax have the following formats:
-
-*   **Source IP address and destination IP address**
-    : Each is either a 32-bit field (for IPv4), or a set of 4 32-bit fields (for IPv6) represented by a value and a mask length.
-    For example, an IPv4 range of 192.168.1.0 to 192.168.1.255 could be represented by a value = [192, 168, 1, 0] and a mask length = 24.
-
-*   **Source port and destination port**
-    : Each is a 16-bit field, represented by a lower start and a higher end.
-    For example, a range of ports 0 to 8192 could be represented by lower = 0 and higher = 8192.
-
-*   **Protocol identifier**
-    : An 8-bit field, represented by a value and a mask, that covers a range of values.
-    To verify that a value is in the range, use the following expression: "(VAL & mask) == value"
-
-The trick in how to represent a range with a mask and value is as follows.
-A range can be enumerated in binary numbers with some bits that are never changed and some bits that are dynamically changed.
-Set those bits that dynamically changed in mask and value with 0.
-Set those bits that never changed in the mask with 1, in value with number expected.
-For example, a range of 6 to 7 is enumerated as 0b110 and 0b111.
-Bit 1-7 are bits never changed and bit 0 is the bit dynamically changed.
-Therefore, set bit 0 in mask and value with 0, set bits 1-7 in mask with 1, and bits 1-7 in value with number 0b11.
-So, mask is 0xfe, value is 0x6.
-
-.. note::
-
-    The library assumes that each field in the rule is in LSB or Little Endian order when creating the database.
-    It internally converts them to MSB or Big Endian order.
-    When performing a lookup, the library assumes the input is in MSB or Big Endian order.
-
-Access Rule Syntax
-~~~~~~~~~~~~~~~~~~
-
-In this sample application, each rule is a combination of the following:
-
-*   5-tuple field: This field has a format described in Section.
-
-*   priority field: A weight to measure the priority of the rules.
-    The rule with the higher priority will ALWAYS be returned if the specific input has multiple matches in the rule database.
-    Rules with lower priority will NEVER be returned in any cases.
-
-*   userdata field: A user-defined field that could be any value.
-    It can be the forwarding port number if the rule is a route table entry or it can be a pointer to a mapping address
-    if the rule is used for address mapping in the NAT application.
-    The key point is that it is a useful reserved field for user convenience.
-
-ACL and Route Rules
-~~~~~~~~~~~~~~~~~~~
-
-The application needs to acquire ACL and route rules before it runs.
-Route rules are mandatory, while ACL rules are optional.
-To simplify the complexity of the priority field for each rule, all ACL and route entries are assumed to be in the same file.
-To read data from the specified file successfully, the application assumes the following:
-
-*   Each rule occupies a single line.
-
-*   Only the following four rule line types are valid in this application:
-
-*   ACL rule line, which starts with a leading character '@'
-
-*   Route rule line, which starts with a leading character 'R'
-
-*   Comment line, which starts with a leading character '#'
-
-*   Empty line, which consists of a space, form-feed ('\f'), newline ('\n'),
-    carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
-
-Other lines types are considered invalid.
-
-*   Rules are organized in descending order of priority,
-    which means rules at the head of the file always have a higher priority than those further down in the file.
-
-*   A typical IPv4 ACL rule line should have a format as shown below:
-
-
-.. _figure_ipv4_acl_rule:
-
-.. figure:: img/ipv4_acl_rule.*
-
-   A typical IPv4 ACL rule
-
-
-IPv4 addresses are specified in CIDR format as specified in RFC 4632.
-They consist of the dot notation for the address and a prefix length separated by '/'.
-For example, 192.168.0.34/32, where the address is 192.168.0.34 and the prefix length is 32.
-
-Ports are specified as a range of 16-bit numbers in the format MIN:MAX,
-where MIN and MAX are the inclusive minimum and maximum values of the range.
-The range 0:65535 represents all possible ports in a range.
-When MIN and MAX are the same value, a single port is represented, for example, 20:20.
-
-The protocol identifier is an 8-bit value and a mask separated by '/'.
-For example: 6/0xfe matches protocol values 6 and 7.
-
-*   Route rules start with a leading character 'R' and have the same format as ACL rules except an extra field at the tail
-    that indicates the forwarding port number.
-
-Rules File Example
-~~~~~~~~~~~~~~~~~~
-
-.. _figure_example_rules:
-
-.. figure:: img/example_rules.*
-
-   Rules example
-
-
-Each rule is explained as follows:
-
-*   Rule 1 (the first line) tells the application to drop those packets with source IP address = [1.2.3.*],
-    destination IP address = [192.168.0.36], protocol = [6]/[7]
-
-*   Rule 2 (the second line) is similar to Rule 1, except the source IP address is ignored.
-    It tells the application to forward packets with destination IP address = [192.168.0.36],
-    protocol = [6]/[7], destined to port 1.
-
-*   Rule 3 (the third line) tells the application to forward all packets to port 0.
-    This is something like a default route entry.
-
-As described earlier, the application assume rules are listed in descending order of priority,
-therefore Rule 1 has the highest priority, then Rule 2, and finally,
-Rule 3 has the lowest priority.
-
-Consider the arrival of the following three packets:
-
-*   Packet 1 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [6]
-
-*   Packet 2 has source IP address = [1.2.4.4], destination IP address = [192.168.0.36], and protocol = [6]
-
-*   Packet 3 has source IP address = [1.2.3.4], destination IP address = [192.168.0.36], and protocol = [8]
-
-Observe that:
-
-*   Packet 1 matches all of the rules
-
-*   Packet 2 matches Rule 2 and Rule 3
-
-*   Packet 3 only matches Rule 3
-
-For priority reasons, Packet 1 matches Rule 1 and is dropped.
-Packet 2 matches Rule 2 and is forwarded to port 1.
-Packet 3 matches Rule 3 and is forwarded to port 0.
-
-For more details on the rule file format,
-please refer to rule_ipv4.db and rule_ipv6.db files (inside <RTE_SDK>/examples/l3fwd-acl/).
-
-Application Phases
-~~~~~~~~~~~~~~~~~~
-
-Once the application starts, it transitions through three phases:
-
-*   **Initialization Phase**
-    - Perform the following tasks:
-
-*   Parse command parameters. Check the validity of rule file(s) name(s), number of logical cores, receive and transmit queues.
-    Bind ports, queues and logical cores. Check ACL search options, and so on.
-
-*   Call Environmental Abstraction Layer (EAL) and Poll Mode Driver (PMD) functions to initialize the environment and detect possible NICs.
-    The EAL creates several threads and sets affinity to a specific hardware thread CPU based on the configuration specified
-    by the command line arguments.
-
-*   Read the rule files and format the rules into the representation that the ACL library can recognize.
-    Call the ACL library function to add the rules into the database and compile them as a trie of pattern sets.
-    Note that application maintains a separate AC contexts for IPv4 and IPv6 rules.
-
-*   **Runtime Phase**
-    - Process the incoming packets from a port. Packets are processed in three steps:
-
-    *   Retrieval: Gets a packet from the receive queue. Each logical core may process several queues for different ports.
-        This depends on the configuration specified by command line arguments.
-
-    *   Lookup: Checks that the packet type is supported (IPv4/IPv6) and performs a 5-tuple lookup over corresponding AC context.
-        If an ACL rule is matched, the packets will be dropped and return back to step 1.
-        If a route rule is matched, it indicates the packet is not in the ACL list and should be forwarded.
-        If there is no matches for the packet, then the packet is dropped.
-
-    *   Forwarding: Forwards the packet to the corresponding port.
-
-*   **Final Phase** - Perform the following tasks:
-
-    Calls the EAL, PMD driver and ACL library to free resource, then quits.
-
-Compiling the Application
--------------------------
-
-To compile the application:
-
-#.  Go to the sample application directory:
-
-    ..  code-block:: console
-
-        export RTE_SDK=/path/to/rte_sdk
-        cd ${RTE_SDK}/examples/l3fwd-acl
-
-#.  Set the target (a default target is used if not specified). For example:
-
-    ..  code-block:: console
-
-        export RTE_TARGET=x86_64-native-linuxapp-gcc
-
-    See the *DPDK IPL Getting Started Guide* for possible RTE_TARGET values.
-
-#.  Build the application:
-
-    ..  code-block:: console
-
-        make
-
-Running the Application
------------------------
-
-The application has a number of command line options:
-
-..  code-block:: console
-
-    ./build/l3fwd-acl [EAL options] -- -p PORTMASK [-P] --config(port,queue,lcore)[,(port,queue,lcore)] --rule_ipv4 FILENAME rule_ipv6 FILENAME [--scalar] [--enable-jumbo [--max-pkt-len PKTLEN]] [--no-numa]
-
-
-where,
-
-*   -p PORTMASK: Hexadecimal bitmask of ports to configure
-
-*   -P: Sets all ports to promiscuous mode so that packets are accepted regardless of the packet's Ethernet MAC destination address.
-    Without this option, only packets with the Ethernet MAC destination address set to the Ethernet address of the port are accepted.
-
-*   --config (port,queue,lcore)[,(port,queue,lcore)]: determines which queues from which ports are mapped to which cores
-
-*   --rule_ipv4 FILENAME: Specifies the IPv4 ACL and route rules file
-
-*   --rule_ipv6 FILENAME: Specifies the IPv6 ACL and route rules file
-
-*   --scalar: Use a scalar function to perform rule lookup
-
-*   --enable-jumbo: optional, enables jumbo frames
-
-*   --max-pkt-len: optional, maximum packet length in decimal (64-9600)
-
-*   --no-numa: optional, disables numa awareness
-
-For example, consider a dual processor socket platform with 8 physical cores, where cores 0-7 and 16-23 appear on socket 0,
-while cores 8-15 and 24-31 appear on socket 1.
-
-To enable L3 forwarding between two ports, assuming that both ports are in the same socket, using two cores, cores 1 and 2,
-(which are in the same socket too), use the following command:
-
-..  code-block:: console
-
-    ./build/l3fwd-acl -l 1,2 -n 4 -- -p 0x3 --config="(0,0,1),(1,0,2)" --rule_ipv4="./rule_ipv4.db" -- rule_ipv6="./rule_ipv6.db" --scalar
-
-In this command:
-
-*   The -l option enables cores 1, 2
-
-*   The -p option enables ports 0 and 1
-
-*   The --config option enables one queue on each port and maps each (port,queue) pair to a specific core.
-    The following table shows the mapping in this example:
-
-    +----------+------------+-----------+-------------------------------------+
-    | **Port** | **Queue**  | **lcore** |            **Description**          |
-    |          |            |           |                                     |
-    +==========+============+===========+=====================================+
-    | 0        | 0          | 1         | Map queue 0 from port 0 to lcore 1. |
-    |          |            |           |                                     |
-    +----------+------------+-----------+-------------------------------------+
-    | 1        | 0          | 2         | Map queue 0 from port 1 to lcore 2. |
-    |          |            |           |                                     |
-    +----------+------------+-----------+-------------------------------------+
-
-*   The --rule_ipv4 option specifies the reading of IPv4 rules sets from the ./ rule_ipv4.db file.
-
-*   The --rule_ipv6 option specifies the reading of IPv6 rules sets from the ./ rule_ipv6.db file.
-
-*   The --scalar option specifies the performing of rule lookup with a scalar function.
-
-Explanation
------------
-
-The following sections provide some explanation of the sample application code.
-The aspects of port, device and CPU configuration are similar to those of the :doc:`l3_forward`.
-The following sections describe aspects that are specific to L3 forwarding with access control.
-
-Parse Rules from File
-~~~~~~~~~~~~~~~~~~~~~
-
-As described earlier, both ACL and route rules are assumed to be saved in the same file.
-The application parses the rules from the file and adds them to the database by calling the ACL library function.
-It ignores empty and comment lines, and parses and validates the rules it reads.
-If errors are detected, the application exits with messages to identify the errors encountered.
-
-The application needs to consider the userdata and priority fields.
-The ACL rules save the index to the specific rules in the userdata field,
-while route rules save the forwarding port number.
-In order to differentiate the two types of rules, ACL rules add a signature in the userdata field.
-As for the priority field, the application assumes rules are organized in descending order of priority.
-Therefore, the code only decreases the priority number with each rule it parses.
-
-Setting Up the ACL Context
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For each supported AC rule format (IPv4 5-tuple, IPv6 6-tuple) application creates a separate context handler
-from the ACL library for each CPU socket on the board and adds parsed rules into that context.
-
-Note, that for each supported rule type,
-application needs to calculate the expected offset of the fields from the start of the packet.
-That's why only packets with fixed IPv4/ IPv6 header are supported.
-That allows to perform ACL classify straight over incoming packet buffer -
-no extra protocol field retrieval need to be performed.
-
-Subsequently, the application checks whether NUMA is enabled.
-If it is, the application records the socket IDs of the CPU cores involved in the task.
-
-Finally, the application creates contexts handler from the ACL library,
-adds rules parsed from the file into the database and build an ACL trie.
-It is important to note that the application creates an independent copy of each database for each socket CPU
-involved in the task to reduce the time for remote memory access.
-- 
2.7.4

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [dpdk-dev] [PATCH v2] doc: Merge l3fwd and l3fwd-acl documentation files
  2017-05-10 10:14   ` Mcnamara, John
@ 2017-05-11  1:51     ` Ravi Kerur
  0 siblings, 0 replies; 10+ messages in thread
From: Ravi Kerur @ 2017-05-11  1:51 UTC (permalink / raw)
  To: Mcnamara, John; +Cc: dev, thomas

On Wed, May 10, 2017 at 3:14 AM, Mcnamara, John <john.mcnamara@intel.com>
wrote:

>
>
> > -----Original Message-----
> > From: Ravi Kerur [mailto:rkerur@gmail.com]
> > Sent: Monday, May 8, 2017 10:00 PM
> > To: dev@dpdk.org
> > Cc: Mcnamara, John <john.mcnamara@intel.com>; thomas@monjalon.net; Ravi
> > Kerur <rkerur@gmail.com>
> > Subject: [PATCH v2] doc: Merge l3fwd and l3fwd-acl documentation files
> >
> > Merge l3fwd and l3fwd-acl documentation to reflect the code.
> > Add examples of LPM and Exact Match rules in .svg files.
> >
> > Signed-off-by: Ravi Kerur <rkerur@gmail.com>
> > ---
> > v2:
> >       Remove binary PNG from .svg files.
> >
> > v1:
> >       Merge relevant contents of l3fwd and l3fwd-acl documentation.
> >       Modify l3fwd document with ACL specific information.
> >       Remove l3fwd-acl documentation file.
> > ---
> >  doc/guides/sample_app_ug/img/ipv4_hash_rule.svg    | 108 ++++++
> >  doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg     |  96 +++++
> >  doc/guides/sample_app_ug/index.rst                 |   1 -
> >  doc/guides/sample_app_ug/l3_forward.rst            | 326
> > ++++++++++++++++-
> >  .../sample_app_ug/l3_forward_access_ctrl.rst       | 385
> ----------------
> > -----
> >  5 files changed, 521 insertions(+), 395 deletions(-)  create mode 100644
> > doc/guides/sample_app_ug/img/ipv4_hash_rule.svg
> >  create mode 100644 doc/guides/sample_app_ug/img/ipv4_lpm_rule.svg
> >
>
>
> Thanks once more for the doc. Some comments below.
>
>
> > ...
> >      Redistribution and use in source and binary forms, with or without
> @@
> > -31,12 +31,18 @@
> >  L3 Forwarding Sample Application
> >  ================================
> >
> > -The L3 Forwarding application is a simple example of packet processing
> > using the DPDK.
> > -The application performs L3 forwarding.
> > +The L3 Forwarding with Hash, LPM or Access Control application is a
> > simple example of packet processing using the DPDK.
> > +The application performs L3 forwarding when Hash or LPM is used.
> > +The application performs a security check on received packets when
> Access
> > Control is used.
> > +Packets that are in the Access Control List (ACL), which is loaded
> during
> > initialization, are dropped.
> > +Others are forwarded to the correct port.
>
>
> For the introduction I would suggest the following rewording:
>
> L3 Forwarding Sample Application
> ================================
>
> The L3 Forwarding application is a simple example of packet processing
> using
> the DPDK with Hash, LPM (Longest Prefix match) or Access Control.
>
> The application performs L3 forwarding when Hash or LPM is used.
> Alternatively, the application performs a security check on received
> packets
> when Access Control is used.  Packets that are in the Access Control List
> (ACL), which is loaded during initialization, are dropped.  Others packets
> are
> forwarded to the correct port.
>
>
>
>
> >  The main difference from the L2 Forwarding sample application is that
> the
> > forwarding decision @@ -49,15 +55,263 @@ The hash object is used in
> > correlation with a flow table to map each input packe  The hash lookup
> key
> > is represented by a DiffServ 5-tuple composed of the following fields
> read
> > from the input packet:
> >  Source IP Address, Destination IP Address, Protocol, Source Port and
> > Destination Port.
>
> This is fine but would be a bit clearer as a list:
>
>
> The hash lookup key is represented by a 5-tuple composed of the following
> fields read from the input packet:
>
> * Source IP Address.
> * Destination IP Address.
> * Protocol.
> * Source Port.
> * Destination Port.
>
>
>
> > +
> > +.. _figure_ipv4_lpm_rule:
> > +
> > +.. figure:: img/ipv4_lpm_rule.*
> > +
> > +   A typical IPv4 LPM rule
> > +
> > +*   A typical IPv4 hash rule line should have a format as shown below:
> > +
> > +
> > +.. _figure_ipv4_hash_rule:
> > +
> > +.. figure:: img/ipv4_hash_rule.*
> > +
> > +   A typical IPv4 hash rule
> > +
>
>
> Unfortunately these figures don't render very well. I would suggest
> replacing
> them with text, like below:
>
>
> A typical IPv4 LPM rule line in an input file would look like the
> following::
>
>
>     # Dest Address/mask   Eth port
>     # =================   ========
>
>     L100.10.10.10/24      0
>
>
> A typical IPv4 Hash rule line in an input file would look like the
> following::
>
>     # Src Address  Dst Address  Src Port  Dst port  Protocol  Eth port
>     # ===========  ===========  ========  ========  ========  ========
>
>     E100.10.10.0  100.10.0.0    110       111       0x6       0
>
>
> There a few other thing that could be improved in the doc but these issues
> were
> already there in text that you are merging so apart from these suggestion
> the rest of the doc is okay for now. We should try to come back and improve
> the consistency at a later date.
>
>
Thanks John. Sent a 'v3' with your inputs incorporated.

> John
>
>
>
>
>

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [dpdk-dev] [PATCH v3] doc: Merge l3fwd and l3fwd-acl documentation files
  2017-05-11  1:49   ` [dpdk-dev] [PATCH v3] " Ravi Kerur
@ 2017-05-16  9:27     ` Mcnamara, John
  2017-06-04 11:17       ` Thomas Monjalon
  0 siblings, 1 reply; 10+ messages in thread
From: Mcnamara, John @ 2017-05-16  9:27 UTC (permalink / raw)
  To: Ravi Kerur, dev



> -----Original Message-----
> From: Ravi Kerur [mailto:rkerur@gmail.com]
> Sent: Thursday, May 11, 2017 2:49 AM
> To: dev@dpdk.org
> Cc: Mcnamara, John <john.mcnamara@intel.com>; Ravi Kerur
> <rkerur@gmail.com>
> Subject: [PATCH v3] doc: Merge l3fwd and l3fwd-acl documentation files
> 
> Merge l3fwd and l3fwd-acl documentation to reflect the code.
> Add examples of LPM and Exact Match rules as text.
> 
> Signed-off-by: Ravi Kerur <rkerur@gmail.com>

Acked-by: John McNamara <john.mcnamara@intel.com>

^ permalink raw reply	[flat|nested] 10+ messages in thread

* Re: [dpdk-dev] [PATCH v3] doc: Merge l3fwd and l3fwd-acl documentation files
  2017-05-16  9:27     ` Mcnamara, John
@ 2017-06-04 11:17       ` Thomas Monjalon
  0 siblings, 0 replies; 10+ messages in thread
From: Thomas Monjalon @ 2017-06-04 11:17 UTC (permalink / raw)
  To: dev; +Cc: Mcnamara, John, Ravi Kerur

> > Merge l3fwd and l3fwd-acl documentation to reflect the code.
> > Add examples of LPM and Exact Match rules as text.
> > 
> > Signed-off-by: Ravi Kerur <rkerur@gmail.com>
> 
> Acked-by: John McNamara <john.mcnamara@intel.com>

This patch depends on a (not yet approved) code change:
	http://dpdk.org/dev/patchwork/patch/21696/

^ permalink raw reply	[flat|nested] 10+ messages in thread

end of thread, other threads:[~2017-06-04 11:17 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-04-25 18:39 [dpdk-dev] [PATCH v1] doc: Merge l3fwd and l3fwd-acl documentation files Ravi Kerur
2017-05-05 16:15 ` Mcnamara, John
2017-05-07 20:50 ` Thomas Monjalon
2017-05-08 21:04   ` Ravi Kerur
2017-05-08 21:00 ` [dpdk-dev] [PATCH v2] " Ravi Kerur
2017-05-10 10:14   ` Mcnamara, John
2017-05-11  1:51     ` Ravi Kerur
2017-05-11  1:49   ` [dpdk-dev] [PATCH v3] " Ravi Kerur
2017-05-16  9:27     ` Mcnamara, John
2017-06-04 11:17       ` Thomas Monjalon

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).