packetforge: add packetforge for generic flow to extras

Add a new tool packetforge to extras. This tool is to support generic flow.
Packetforge is a library to translate naming or json profile format flow
pattern to the required input of generic flow, i.e. spec and mask. Using
python script flow_create.py, it can add and enable a new flow rule for
an interface via flow VAPI, and can delete an existed flow rule as well.
Command examples are shown below. Json profile examples can be found in
./parsegraph/samples.

Naming format input:
python flow_create.py --add -p "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
-a "redirect-to-queue 3" -i 1
python flow_create.py --del -i 1 -I 0

Json profile format input:
python flow_create.py -f "./flow_rule_examples/mac_ipv4.json" -i 1

With this command, flow rule can be added or deleted, and the flow
entry can be listed with "show flow entry" command in VPP CLI.

Packetforge is based on a parsegraph. The parsegraph can be built by
users. A Spec can be found in ./parsegraph as guidance. More details
about packetforge are in README file.

Type: feature

Signed-off-by: Ting Xu <ting.xu@intel.com>
Change-Id: Ia9f539741c5dca27ff236f2bcc493c5dd48c0df1

1 files changed, 71 insertions, 0 deletions

diff --git a/extras/packetforge/README.rst b/extras/packetforge/README.rst
new file mode 100644
index 00000000000..f477c0bab38
--- /dev/null
+++ b/extras/packetforge/README.rst
@@ -0,0 +1,71 @@
+.. _packetforge_doc:
+
+Packetforge for generic flow
+============================
+
+Packetforge is a tool to support generic flow. Since the input format of
+generic flow is hard to read and create, packetforge can help to create
+generic flow rules using a format of naming protocols (like Scapy) or json
+profile. Packetforge is built based on a parsegraph, users can modify the
+graph nodes and edges if needed.
+
+Command examples
+----------------
+
+::
+
+     $ python flow_create.py --add -p "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
+       -a "redirect-to-queue 3" -i 1
+
+     $ python flow_create.py --add
+       --pattern "mac()/ipv4(src=1.1.1.1,dst=2.2.2.2)/udp()"
+       --actions "redirect-to-queue 3" --interface 1
+
+     $ python flow_create.py --del -i 1 -I 0
+
+     $ python flow_create.py --del --interface 1 --flow-index 0
+
+Naming format input. There are two operations, add and delete flow rules.
+For add, it needs three parameters. Pattern is similar to Scapy protocols.
+Actions is the same as vnet/flow command. Interface is the device to which
+we want to add the flow rule. For delete, flow index is the index of the
+flow rule we want to delete. We can get the index number when we add the
+flow or use command to show the existed flow entry in CLI.
+
+::
+
+     $ python flow_create.py --add -f "./flow_rule_examples/mac_ipv4.json" -i 1
+
+     $ python flow_create.py --add --file "./flow_rule_examples/mac_ipv4.json"
+       --interface 1
+
+     $ python flow_create.py --add -f "./flow_rule_examples/mac_ipv4.json"
+       -a "redirect-to-queue 3" -i 1
+
+Json profile format input. This command takes a json profile as parameter.
+In the json profile, there will be protocols and their fields and values.
+Users can define spec and mask for each field. Actions can be added in the
+profile directly, otherwise "-a" option should be added in the command to
+specify actions. The example can be found in parsegraph/samples folder.
+Users can create their own json files according to examples and Spec.
+
+::
+
+      $ show flow entry
+
+It is a vnet/flow command, used in VPP CLI. It can show the added flow rules
+after using the above commands. Users can get the flow index with this command
+and use it to delete the flow rule.
+
+ParseGraph
+----------
+
+Packetforge is built based on a ParseGraph. The ParseGraph is constructed
+with nodes and edges. Nodes are protocols, including information about
+protocol's name, fields and default values. Edges are the relationship
+between two protocols, including some actions needed when connecting two
+protocols. For example, change the mac header ethertype to 0x0800 when
+connecting mac and ipv4. More details are in the Spec in parsegraph folder.
+Users can build the ParseGraph following the spec by themselves, like
+adding a new protocol. If NIC supports the new protocol, the rule can be
+created. Otherwise, it will return error.