wip

outscale · Sep 2, 2020 · 9fe9bdf · 9fe9bdf
1 parent b2a71cc
commit 9fe9bdf
Show file tree

Hide file tree

Showing 4 changed files with 79 additions and 1 deletion.
diff --git a/doc/BRICK_CONCEPT.md b/doc/BRICK_CONCEPT.md
@@ -38,6 +38,26 @@ And now 2 basic bricks linked together:<br>
 Why having sides?<br>
 Because it makes it easier to perform operations between two sides such as acting as a diode, filter...<br>
 
+### Warning!
+
+While creating links, make sure that there is not 2 bricks modifying packets (VXLAN, VTEP) on the same side!<br>
+Here is why:<br>
+To improve our perfs, we do not copy packets so if a brick modify them, they will be modified for all other bricks on this side.<br>
+<br>
+Example:<br>
+We want to link some VMs to a VTEP. So we need VHOST bricks for each VMs and a switch.<br>
+The VTEP must NOT be on the same side than VHOST bricks.<br>
+Sides are decided by the order of the arguments of the method `pg_brick_link(BRICK_A, BRICK_B)`.<br>
+So basically we will do so:
+
+* `pg_brick_link(SWITCH, VTEP);`
+* `pg_brick_link(VHOST_0, SWITCH);`
+* `pg_brick_link(VHOST_1, SWITCH);`
+* `pg_brick_link(VHOST_2, SWITCH);`
+
+So we are sure that VTEP and VHOST_n are not on the same side.<br>
+If we cannot isolate as we want the VTEP, a NOT recommended way would be to disable the `NOCOPY` flag.
+
 ## How monopole/single edge brick works:
 ### Single edge:
 As the following content shows it, `edge` and `edges` are in an `union` so basically one side can have `edge` OR `edges`.

diff --git a/doc/README.md b/doc/README.md
@@ -1,6 +1,7 @@
 # DOCUMENTATION
 
 Here is a documentation aiming at providing detailed information about Packetgraph's brick concept, about implemented technologies/features (with standards descriptions) and about each brick. The idea is to explain what's the purpose of each component, further optimizations and choices made.<br>
+All this documentation must be written in ASCII so we can access it through a terminal.<br>
 <br>
 An overview of the general concept of packetgraph:
 * [General concept.](PG_GENERAL_CONCEPT.md)
@@ -14,3 +15,6 @@ For specific brick'informations and shemas:
 * [VTEP brick.](VTEP.md)
 * [SWITCH brick.](SWITCH.md)
 
+About out testing architecture:
+* `wip`
+
diff --git a/doc/SWITCH.md b/doc/SWITCH.md
@@ -1,3 +1,47 @@
 # SWITCH Brick
 
 ## Introduction
+
+The switch brick is a brick doing what does a switch do in "real life" as described [here](https://en.wikipedia.org/wiki/Network_switch).<br>
+The core feature being that when we receive an incoming packet, trying to reach a mac address, there's two cases:
+
+* We know on which interface we can find it and so we forward it directly through the right interface..
+
+* We don't know where is the packet's destination so we broadcast it on all interfaces. Then, once we get the answer, we update the MAC TABLE linking MAC address with INTERFACES. So the next time we will know where to forward the packet.
+
+Another thing is the forget feature: if a line in the mac table hasn't been used since a long time, we forget it!<br>
+However it is not working yet!
+
+## Basic example: connect 3 VMs to a NIC.
+
+```
+
+ The outer     +---Host Machine---------------------------------------------------------------------+
+  World        |                                                                                    |
+               |   +--The GRAPH--------------------------------------+                              |
+               |   |                                                 |                              |
+               |   |                                             +-------+              +---------+ |
+               |   |      |                 |<------------------>| VHOST |<------------>|  VM     | |
+               |   |      |                 |                    +-------+              +---------+ |
+               |   |      |                 |                        |                              |
+           +---------+    |   +---------+   |                    +-------+              +---------+ |
+ <-------->|   NIC   |<-->|---|Switch   |---|<------------------>| VHOST |<------------>|  VM     | |
+           +---------+    |   +---------+   |                    +-------+              +---------+ |
+               |   |      |                 |                        |                              |
+               |   |      |                 |                    +-------+              +---------+ |
+               |   |      |                 |<------------------>| VHOST |<------------>|  VM     | |
+               |   |  WEST SIDE         EAST SIDE                +-------+              +---------+ |
+               |   |                                                 |                              |
+               |   +--------------------------------------------------                              |
+               |                                                                                    |
+               +------------------------------------------------------------------------------------+
+```
+
+Note: it's always a good practice to link to one side all "subnet" devices and to another the "upper" device (No matter if it's EAST or WEST!).<br>
+Here is the reason:<br>
+Basically, if we heve a brick modifying packets such as VTEP or VXLAN, we should isolate it on a side. In fact, to manage packets faster, we do not copy them so be careful to do not modify them! They would be modified for all bricks on this side.<br>
+Please refer to the [warning section of the brick concept's overview](BRICK_CONCEPT.md) for more informations.
+
+## Let's go deeper into the MAC TABLE.
+
+wip
diff --git a/doc/VHOST.md b/doc/VHOST.md
@@ -5,6 +5,7 @@
 The VHOST brick is the brick used to make the graph communicate with VMs.<br>
 The problem while communicating with VMs via "standard way" is that it's really slow.<br>
 So here we use the virtio protocol implemented as vhost in DPDK.<br>
+You can find a more detailed description here: https://www.redhat.com/en/blog/hands-vhost-user-warm-welcome-dpdk.<br>
 
 
 ## VHOST overview
@@ -33,6 +34,15 @@ As previously described, VHOST use an unix socket and a hugepage to communicate
 It manages a queue and reduce memmory write/free operatons.<br>
 It's based on a cient(s)/server model, meaning that one server can handle multiple connections through the socket.<br> Only packet address in the hugepage are flowing through the socket.<br>
 
+## How to use it
+
+* `pg_vhost_start("/tmp", &error)`: start the vhost driver and setup the socket's folder.
+* `pg_vhost_new("vhost-0", flags, &error);`: create the brick.<br>The socket will be named `qemu-vhost-0`.<br>Here are some flags availables:
+  * `PG_VHOST_USER_CLIENT`: means that the brick will be the client and the qemu the server.
+  * `PG_VHOST_USER_DEQUEUE_ZERO_COPY`: means that we will use zero copy. #FIXME: explain more.
+  * `PG_VHOST_USER_NO_RECONNECT`: disable reconnection after disconnection.
+
 ## Current VHOST brick's status
 
-Currently the VHOST brick only works in SERVER mode... Which means that if packetgraph crash, we will need to reboot VMs...<br>Not a good thing!
+Currently the VHOST brick only works in SERVER mode... Which means that if packetgraph crash, we will need to reboot VMs...<br>Not a good thing!<br>
+However, a PR in in progress to adress this issue.<br>