drivers/staging/greybus/tools/README.loopback

   1
   2
   3         1 - LOOPBACK DRIVER
   4
   5 The driver implements the main logic of the loopback test and provides
   6 sysfs files to configure the test and retrieve the results.
   7 A user could run a test without the need of the test application given
   8 that he understands the sysfs interface of the loopback driver.
   9
  10 The loopback kernel driver needs to be loaded and at least one module
  11 with the loopback feature enabled must be present for the sysfs files to be
  12 created and for the loopback test application to be able to run.
  13
  14 To load the module:
  15 # modprobe gb-loopback
  16
  17
  18 When the module is probed,  New files are available on the sysfs
  19 directory of the detected loopback device.
  20 (typically under "/sys/bus/graybus/devices").
  21
  22 Here is a short summary of the sysfs interface files that should be visible:
  23
  24 * Loopback Configuration Files:
  25     async - Use asynchronous operations.
  26     iteration_max - Number of tests iterations to perform.
  27     size - payload size of the transfer.
  28     timeout - The number of microseconds to give an individual
  29               asynchronous request before timing out.
  30     us_wait - Time to wait between 2 messages
  31     type - By writing the test type to this file, the test starts.
  32            Valid tests are:
  33              0 stop the test
  34              2 - ping
  35              3 - transfer
  36              4 - sink
  37
  38 * Loopback feedback files:
  39     error - number of errors that have occurred.
  40     iteration_count - Number of iterations performed.
  41     requests_completed - Number of requests successfully completed.
  42     requests_timedout - Number of requests that have timed out.
  43     timeout_max - Max allowed timeout
  44     timeout_min - Min allowed timeout.
  45
  46 * Loopback result files:
  47     apbridge_unipro_latency_avg
  48     apbridge_unipro_latency_max
  49     apbridge_unipro_latency_min
  50     gpbridge_firmware_latency_avg
  51     gpbridge_firmware_latency_max
  52     gpbridge_firmware_latency_min
  53     requests_per_second_avg
  54     requests_per_second_max
  55     requests_per_second_min
  56     latency_avg
  57     latency_max
  58     latency_min
  59     throughput_avg
  60     throughput_max
  61     throughput_min
  62
  63
  64
  65             2 - LOOPBACK TEST APPLICATION
  66
  67 The loopback test application manages and formats the results provided by
  68 the loopback kernel module. The purpose of this application
  69 is to:
  70     - Start and manage multiple loopback device tests concurrently.
  71     - Calculate the aggregate results for multiple devices.
  72     - Gather and format test results (csv or human readable).
  73
  74 The best way to get up to date usage information for the application is
  75 usually to pass the "-h" parameter.
  76 Here is the summary of the available options:
  77
  78  Mandatory arguments
  79    -t     must be one of the test names - sink, transfer or ping
  80    -i     iteration count - the number of iterations to run the test over
  81  Optional arguments
  82    -S     sysfs location - location for greybus 'endo' entries default /sys/bus/greybus/devices/
  83    -D     debugfs location - location for loopback debugfs entries default /sys/kernel/debug/gb_loopback/
  84    -s     size of data packet to send during test - defaults to zero
  85    -m     mask - a bit mask of connections to include example: -m 8 = 4th connection -m 9 = 1st and 4th connection etc
  86                  default is zero which means broadcast to all connections
  87    -v     verbose output
  88    -d     debug output
  89    -r     raw data output - when specified the full list of latency values are included in the output CSV
  90    -p     porcelain - when specified printout is in a user-friendly non-CSV format. This option suppresses writing to CSV file
  91    -a     aggregate - show aggregation of all enabled devies
  92    -l     list found loopback devices and exit.
  93    -x     Async - Enable async transfers.
  94    -o     Timeout - Timeout in microseconds for async operations.
  95
  96
  97
  98              3 - REAL WORLD EXAMPLE USAGES
  99
 100  3.1 - Using the driver sysfs files to run a test on a single device:
 101
 102 * Run a 1000 transfers of a 100 byte packet. Each transfer is started only
 103 after the previous one finished successfully:
 104     echo 0 > /sys/bus/greybus/devices/1-2.17/type
 105     echo 0 > /sys/bus/greybus/devices/1-2.17/async
 106     echo 2000 > /sys/bus/greybus/devices/1-2.17/us_wait
 107     echo 100 > /sys/bus/greybus/devices/1-2.17/size
 108     echo 1000 > /sys/bus/greybus/devices/1-2.17/iteration_max
 109     echo 0 > /sys/bus/greybus/devices/1-2.17/mask
 110     echo 200000 > /sys/bus/greybus/devices/1-2.17/timeout
 111     echo 3 > /sys/bus/greybus/devices/1-2.17/type
 112
 113 * Run a 1000 transfers of a 100 byte packet. Transfers are started without
 114 waiting for the previous one to finish:
 115     echo 0 > /sys/bus/greybus/devices/1-2.17/type
 116     echo 3 > /sys/bus/greybus/devices/1-2.17/async
 117     echo 0 > /sys/bus/greybus/devices/1-2.17/us_wait
 118     echo 100 > /sys/bus/greybus/devices/1-2.17/size
 119     echo 1000 > /sys/bus/greybus/devices/1-2.17/iteration_max
 120     echo 0 > /sys/bus/greybus/devices/1-2.17/mask
 121     echo 200000 > /sys/bus/greybus/devices/1-2.17/timeout
 122     echo 3 > /sys/bus/greybus/devices/1-2.17/type
 123
 124 * Read the results from sysfs:
 125     cat /sys/bus/greybus/devices/1-2.17/requests_per_second_min
 126     cat /sys/bus/greybus/devices/1-2.17/requests_per_second_max
 127     cat /sys/bus/greybus/devices/1-2.17/requests_per_second_avg
 128
 129     cat /sys/bus/greybus/devices/1-2.17/latency_min
 130     cat /sys/bus/greybus/devices/1-2.17/latency_max
 131     cat /sys/bus/greybus/devices/1-2.17/latency_avg
 132
 133     cat /sys/bus/greybus/devices/1-2.17/apbridge_unipro_latency_min
 134     cat /sys/bus/greybus/devices/1-2.17/apbridge_unipro_latency_max
 135     cat /sys/bus/greybus/devices/1-2.17/apbridge_unipro_latency_avg
 136
 137     cat /sys/bus/greybus/devices/1-2.17/gpbridge_firmware_latency_min
 138     cat /sys/bus/greybus/devices/1-2.17/gpbridge_firmware_latency_max
 139     cat /sys/bus/greybus/devices/1-2.17/gpbridge_firmware_latency_avg
 140
 141     cat /sys/bus/greybus/devices/1-2.17/error
 142     cat /sys/bus/greybus/devices/1-2.17/requests_completed
 143     cat /sys/bus/greybus/devices/1-2.17/requests_timedout
 144
 145
 146 3.2 - using the test application:
 147
 148 * Run a transfer test 10 iterations of size 100 bytes on all available devices
 149     #/loopback_test -t transfer -i 10 -s 100
 150     1970-1-1 0:10:7,transfer,1-4.17,100,10,0,443,509,471.700012,66,1963,2256,2124.600098,293,102776,118088,109318.898438,15312,1620,1998,1894.099976,378,56,57,56.799999,1
 151     1970-1-1 0:10:7,transfer,1-5.17,100,10,0,399,542,463.399994,143,1845,2505,2175.800049,660,92568,125744,107393.296875,33176,1469,2305,1806.500000,836,56,57,56.799999,1
 152
 153
 154 * Show the aggregate results of both devices. ("-a")
 155     #/loopback_test -t transfer -i 10 -s 100  -a
 156     1970-1-1 0:10:35,transfer,1-4.17,100,10,0,448,580,494.100006,132,1722,2230,2039.400024,508,103936,134560,114515.703125,30624,1513,1980,1806.900024,467,56,57,57.299999,1
 157     1970-1-1 0:10:35,transfer,1-5.17,100,10,0,383,558,478.600006,175,1791,2606,2115.199951,815,88856,129456,110919.703125,40600,1457,2246,1773.599976,789,56,57,57.099998,1
 158     1970-1-1 0:10:35,transfer,aggregate,100,10,0,383,580,486.000000,197,1722,2606,2077.000000,884,88856,134560,112717.000000,45704,1457,2246,1789.000000,789,56,57,57.000000,1
 159
 160 * Example usage of the mask option to select which devices will
 161   run the test (1st, 2nd, or both devices):
 162     # /loopback_test -t transfer -i 10 -s 100 -m 1
 163     1970-1-1 0:11:56,transfer,1-4.17,100,10,0,514,558,544.900024,44,1791,1943,1836.599976,152,119248,129456,126301.296875,10208,1600,1001609,101613.601562,1000009,56,57,56.900002,1
 164     # /loopback_test -t transfer -i 10 -s 100 -m 2
 165     1970-1-1 0:12:0,transfer,1-5.17,100,10,0,468,554,539.000000,86,1804,2134,1859.500000,330,108576,128528,124932.500000,19952,1606,1626,1619.300049,20,56,57,57.400002,1
 166     # /loopback_test -t transfer -i 10 -s 100 -m 3
 167     1970-1-1 0:12:3,transfer,1-4.17,100,10,0,432,510,469.399994,78,1959,2313,2135.800049,354,100224,118320,108785.296875,18096,1610,2024,1893.500000,414,56,57,57.200001,1
 168     1970-1-1 0:12:3,transfer,1-5.17,100,10,0,404,542,468.799988,138,1843,2472,2152.500000,629,93728,125744,108646.101562,32016,1504,2247,1853.099976,743,56,57,57.099998,1
 169
 170 * Show output in human readable format ("-p")
 171     # /loopback_test -t transfer -i 10 -s 100 -m 3 -p
 172
 173     1970-1-1 0:12:37
 174     test:                       transfer
 175     path:                       1-4.17
 176     size:                       100
 177     iterations:                 10
 178     errors:                     0
 179     async:                      Disabled
 180     requests per-sec:           min=390, max=547, average=469.299988, jitter=157
 181     ap-throughput B/s:          min=90480 max=126904 average=108762.101562 jitter=36424
 182     ap-latency usec:            min=1826 max=2560 average=2146.000000 jitter=734
 183     apbridge-latency usec:      min=1620 max=1982 average=1882.099976 jitter=362
 184     gpbridge-latency usec:      min=56 max=57 average=57.099998 jitter=1
 185
 186
 187     1970-1-1 0:12:37
 188     test:                       transfer
 189     path:                       1-5.17
 190     size:                       100
 191     iterations:                 10
 192     errors:                     0
 193     async:                      Disabled
 194     requests per-sec:           min=397, max=538, average=461.700012, jitter=141
 195     ap-throughput B/s:          min=92104 max=124816 average=106998.898438 jitter=32712
 196     ap-latency usec:            min=1856 max=2514 average=2185.699951 jitter=658
 197     apbridge-latency usec:      min=1460 max=2296 average=1828.599976 jitter=836
 198     gpbridge-latency usec:      min=56 max=57 average=57.099998 jitter=1