README.loopback (9406B)
1 2 3 1 - LOOPBACK DRIVER 4 5The driver implements the main logic of the loopback test and provides 6sysfs files to configure the test and retrieve the results. 7A user could run a test without the need of the test application given 8that he understands the sysfs interface of the loopback driver. 9 10The loopback kernel driver needs to be loaded and at least one module 11with the loopback feature enabled must be present for the sysfs files to be 12created and for the loopback test application to be able to run. 13 14To load the module: 15# modprobe gb-loopback 16 17 18When the module is probed, New files are available on the sysfs 19directory of the detected loopback device. 20(typically under "/sys/bus/graybus/devices"). 21 22Here 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 67The loopback test application manages and formats the results provided by 68the loopback kernel module. The purpose of this application 69is 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 74The best way to get up to date usage information for the application is 75usually to pass the "-h" parameter. 76Here 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 103after 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 114waiting 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 1463.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