ligang/vpp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

libmemif: update documentation

Browse Source 
Type: refactor

Signed-off-by: Jakub Grajciar <jgrajcia@cisco.com>
Change-Id: I0094ea8627cd8bcd5ea119c2fd48f077c8e2e4bb
This commit is contained in:
Jakub Grajciar
2021-01-04 11:36:44 +01:00
committed by Dave Wallace
parent 3d3dc2966d
commit 87e90830b8
4 changed files with 167 additions and 341 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
extras/libmemif/docs/buildinstructions_doc.md
View File

@@ -2,7 +2,7 @@
#### Install dependencies
```
# sudo apt-get install -y git cmake autoconf pkg_config libtool check
# sudo apt-get install -y git cmake autoconf pkg_config libtool
```
Libmemif is now part of VPP repository. Follow fd.io wiki to pull source code from VPP repository.
@@ -18,30 +18,28 @@ Libmemif is located under extras/libmemif. From extras/libmemif:
#### Verify installation:
```
build# ./examples/icmpr-epoll
build# ./examples/icmp_responder -?
```
Use _help_ command to display build information and commands:
Use `-?` flag to display help:
```
LIBMEMIF EXAMPLE APP: ICMP_Responder
LIBMEMIF EXAMPLE APP: icmp_responder_example
==============================
libmemif version: 3.0
memif version: 512
use CTRL+C to exit
MEMIF DETAILS
libmemif version: 4.0, memif version: 2.0
==============================
interface name: memif_connection
app name: ICMP_Responder
remote interface name:
remote app name:
id: 0
secret: (null)
role: slave
mode: ethernet
socket filename: /run/vpp/memif.sock
socket filename: /run/vpp/memif.sock
rx queues:
tx queues:
link: down
In this example, memif endpoint connects to an external application.
The example application can resolve ARP and reply to ICMPv4 packets.
The program will exit once the interface is disconnected.
==============================
Usage: icmp_responder [OPTIONS]
Options:
-r Interface role <slave|master>. Default: slave
-s Socket path. Supports abstract socket using @ before the path. Default: /run/vpp/memif.sock
-i Interface id. Default: 0
-a IPv4 address. Default: 192.168.1.1
-h Mac address. Default: aa:aa:aa:aa:aa:aa
-? Show help and exit.
-v Show libmemif and memif version information and exit.
```
#### Examples

94
extras/libmemif/docs/devperftest_doc.md
View File

@@ -1,94 +0,0 @@
## Development performance test {#libmemif_devperftest_doc}
Simple test cases using ICMP. icmpr-epoll example app generates and transmits packets over memif interface.
#### TC1: LIB-VPP
Start icmpr-epoll example app and VPP.
VPP-side config:
```
DBGvpp# create interface memif id 0 master
DBGvpp# set int state memif0/0 up
DBGvpp# set int ip address memif0/0 192.168.1.1/24
```
icmpr-epoll:
```
conn 0 0 1
```
> Last argument specifies interrupt function to use. This function only responds to ARP requests. This is important because, packet generation and transmitting is handled by a separate thread. Calling memif_tx_burst from multiple threads writing on same queue could transmit uninitialized buffers.
Once connection is established, you can send ping from VPP to icmpr-epoll app to learn its mac address.
```
DBGvpp# ping 192.168.1.2
```
> There should be no ICMP response. Only ARP response.
Now send ICMP requests from icmpr-epoll:
```
send <index> <num-of-packets> <ip_daddr> <hw_daddr>
send 0 5 192.168.1.1 02:fe:ff:ff:ff:ff
```
this command will create new thread which will generate icmp packets and transmit them over memif connection with specified index. Once the sequence is finished status will be printed.
###### Example results (overview of test data)
(This test was run with modification in VPP-memif plugin. The modification disallows memif tx node to allocate last ring buffer)
lib-tx: 200M (if ring full don't drop packets)
vpp-rx: 200M
vpp-tx: 200M - 50K (if ring full drop packets)
lib-rx: =vpp-tx
drop: ~0.025% (full ring)
pps: ~650K
multiple interfaces:
pps: divided
drop: constant
#### TC2: LIB-LIB
This test case will not drop packets if memif ring is full. Instead it will loop until all required packets have been sent.
Start two instances of icmpr-epoll example app.
instance 1:
```
conn 0 1 0
```
instance 2:
```
conn 0 0 1
send 0 5 192.168.1.1 aa:aa:aa:aa:aa:aa
```
> icmpr-epoll example app doesn't check ip or mac address so as long as the format is correct you can type anything as ip_daddr and hw_daddr arguments.
###### Example results (overview of test data)
lib1-tx: 200M (if ring full don't drop packets)
lib2-rx: 200M
lib2-tx: 200M (if ring full don't drop packets)
lib1-rx: 200M
drop: obsolete
pps: 4.5M
multiple interfaces:
not tested (expected same as TC1)
#### TC3: LIB-LIB
Start two instances of icmpr-epoll example app.
instance 1:
```
conn 0 1
```
instance 2:
```
conn 0 0 1
send 0 5 192.168.1.1 aa:aa:aa:aa:aa:aa
```
###### Example results (overview of test data)
lib1-tx: 200M (if ring full don't drop packets)
lib2-rx: 200M
lib2-tx: 169626182 (if ring full drop packets)
lib1-rx: =lib2-tx
drop: ~15%
pps: ~6M
multiple interfaces:
not tested (expected same as TC1)

337
extras/libmemif/docs/gettingstarted_doc.md
View File

File diff suppressed because it is too large Load Diff

37
extras/libmemif/libmemif_doc.md
View File

@@ -20,52 +20,34 @@ Shared memory packet interface (memif) provides high performance packet transmit
- [x] Multiple queues
- [x] Multi-thread support
- [x] Master mode
- [ ] Multiple regions (TODO)
- [ ] Performance testing (TODO)
- [x] Multiple regions
- [x] Loopback
## Quickstart
This setup will run libmemif ICMP responder example app in container. Install [docker](https://docs.docker.com/engine/installation) engine.
Useful link: [Docker documentation](https://docs.docker.com/get-started).
Pull image:
Build the docker image:
```
# docker pull ligato/libmemif-sample-service
# docker build . -t libmemif
```
Now you should be able to see ligato/libmemif-sample-service image on your local machine (IMAGE ID in this README may be outdated):
Now you should be able to see libmemif image on your local machine:
```
# docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
ligato/libmemif-sample-service latest 32ecc2f9d013 About a minute ago 468MB
libmemif latest 32ecc2f9d013 About a minute ago 468MB
...
```
Run container:
```
# docker run -it --rm --name icmp-responder --hostname icmp-responder --privileged -v "/run/vpp/:/run/vpp/" ligato/libmemif-sample-service
```
Example application will start in debug mode. Output should look like this:
```
ICMP_Responder:add_epoll_fd:233: fd 0 added to epoll
ICMP_Responder:add_epoll_fd:233: fd 5 added to epoll
LIBMEMIF EXAMPLE APP: ICMP_Responder (debug)
==============================
libmemif version: 2.0 (debug)
memif version: 512
commands:
help - prints this help
exit - exit app
conn <index> <mode> [<interrupt-desc>] - create memif. index is also used as interface id, mode 0 = slave 1 = master, interrupt-desc none = default 0 = if ring is full wait 1 = handle only ARP requests
del <index> - delete memif
show - show connection details
ip-set <index> <ip-addr> - set interface ip address
rx-mode <index> <qid> <polling|interrupt> - set queue rx mode
sh-count - print counters
cl-count - clear counters
send <index> <tx> <ip> <mac> - send icmp
# docker run -it --rm --name icmp-responder --hostname icmp-responder --privileged -v "/run/vpp/:/run/vpp/" libmemif
```
The interface will by default connect to a master interface listening on `/run/vpp/master.sock`. The example will handle ARP requests and respond to ICMPv4 requests to `192.168.1.1`.
Continue with @ref libmemif_example_setup which contains instructions on how to set up connection between icmpr-epoll example app and VPP-memif.
#### Next steps
@@ -74,4 +56,3 @@ Continue with @ref libmemif_example_setup which contains instructions on how to
- @subpage libmemif_examples_doc
- @subpage libmemif_example_setup_doc
- @subpage libmemif_gettingstarted_doc
- @subpage libmemif_devperftest_doc