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
199