| 1 | AF_VSOCK test suite |
| 2 | ------------------- |
| 3 | These tests exercise net/vmw_vsock/ host<->guest sockets for VMware, KVM, and |
| 4 | Hyper-V. |
| 5 | |
| 6 | The following tests are available: |
| 7 | |
| 8 | * vsock_test - core AF_VSOCK socket functionality |
| 9 | * vsock_diag_test - vsock_diag.ko module for listing open sockets |
| 10 | |
| 11 | The following prerequisite steps are not automated and must be performed prior |
| 12 | to running tests: |
| 13 | |
| 14 | 1. Build the kernel, make headers_install, and build these tests. |
| 15 | 2. Install the kernel and tests on the host. |
| 16 | 3. Install the kernel and tests inside the guest. |
| 17 | 4. Boot the guest and ensure that the AF_VSOCK transport is enabled. |
| 18 | |
| 19 | Invoke test binaries in both directions as follows: |
| 20 | |
| 21 | # host=server, guest=client |
| 22 | (host)# $TEST_BINARY --mode=server \ |
| 23 | --control-port=1234 \ |
| 24 | --peer-cid=3 |
| 25 | (guest)# $TEST_BINARY --mode=client \ |
| 26 | --control-host=$HOST_IP \ |
| 27 | --control-port=1234 \ |
| 28 | --peer-cid=2 |
| 29 | |
| 30 | # host=client, guest=server |
| 31 | (guest)# $TEST_BINARY --mode=server \ |
| 32 | --control-port=1234 \ |
| 33 | --peer-cid=2 |
| 34 | (host)# $TEST_BINARY --mode=client \ |
| 35 | --control-port=$GUEST_IP \ |
| 36 | --control-port=1234 \ |
| 37 | --peer-cid=3 |
| 38 | |
| 39 | Some tests are designed to produce kernel memory leaks. Leaks detection, |
| 40 | however, is deferred to Kernel Memory Leak Detector. It is recommended to enable |
| 41 | kmemleak (CONFIG_DEBUG_KMEMLEAK=y) and explicitly trigger a scan after each test |
| 42 | suite run, e.g. |
| 43 | |
| 44 | # echo clear > /sys/kernel/debug/kmemleak |
| 45 | # $TEST_BINARY ... |
| 46 | # echo "wait for any grace periods" && sleep 2 |
| 47 | # echo scan > /sys/kernel/debug/kmemleak |
| 48 | # echo "wait for kmemleak" && sleep 5 |
| 49 | # echo scan > /sys/kernel/debug/kmemleak |
| 50 | # cat /sys/kernel/debug/kmemleak |
| 51 | |
| 52 | For more information see Documentation/dev-tools/kmemleak.rst. |
| 53 | |
| 54 | vsock_perf utility |
| 55 | ------------------- |
| 56 | 'vsock_perf' is a simple tool to measure vsock performance. It works in |
| 57 | sender/receiver modes: sender connect to peer at the specified port and |
| 58 | starts data transmission to the receiver. After data processing is done, |
| 59 | it prints several metrics(see below). |
| 60 | |
| 61 | Usage: |
| 62 | # run as sender |
| 63 | # connect to CID 2, port 1234, send 1G of data, tx buf size is 1M |
| 64 | ./vsock_perf --sender 2 --port 1234 --bytes 1G --buf-size 1M |
| 65 | |
| 66 | Output: |
| 67 | tx performance: A Gbits/s |
| 68 | |
| 69 | Output explanation: |
| 70 | A is calculated as "number of bits to send" / "time in tx loop" |
| 71 | |
| 72 | # run as receiver |
| 73 | # listen port 1234, rx buf size is 1M, socket buf size is 1G, SO_RCVLOWAT is 64K |
| 74 | ./vsock_perf --port 1234 --buf-size 1M --vsk-size 1G --rcvlowat 64K |
| 75 | |
| 76 | Output: |
| 77 | rx performance: A Gbits/s |
| 78 | total in 'read()': B sec |
| 79 | POLLIN wakeups: C |
| 80 | average in 'read()': D ns |
| 81 | |
| 82 | Output explanation: |
| 83 | A is calculated as "number of received bits" / "time in rx loop". |
| 84 | B is time, spent in 'read()' system call(excluding 'poll()') |
| 85 | C is number of 'poll()' wake ups with POLLIN bit set. |
| 86 | D is B / C, e.g. average amount of time, spent in single 'read()'. |