tools/testing/vsock/README

   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()'.