redonkable
/
remarkable-linux
1
0
Fork 0
Code Releases Activity
remarkable-linux/drivers/staging/greybus/tools
History
Greg Kroah-Hartman b24413180f License cleanup: add SPDX GPL-2.0 license identifier to files with no license 
Many source files in the tree are missing licensing information, which
makes it harder for compliance tools to determine the correct license.

By default all files without license information are under the default
license of the kernel, which is GPL version 2.

Update the files which contain no license information with the 'GPL-2.0'
SPDX license identifier.  The SPDX identifier is a legally binding
shorthand, which can be used instead of the full boiler plate text.

This patch is based on work done by Thomas Gleixner and Kate Stewart and
Philippe Ombredanne.

How this work was done:

Patches were generated and checked against linux-4.14-rc6 for a subset of
the use cases:
 - file had no licensing information it it.
 - file was a */uapi/* one with no licensing information in it,
 - file was a */uapi/* one with existing licensing information,

Further patches will be generated in subsequent months to fix up cases
where non-standard license headers were used, and references to license
had to be inferred by heuristics based on keywords.

The analysis to determine which SPDX License Identifier to be applied to
a file was done in a spreadsheet of side by side results from of the
output of two independent scanners (ScanCode & Windriver) producing SPDX
tag:value files created by Philippe Ombredanne.  Philippe prepared the
base worksheet, and did an initial spot review of a few 1000 files.

The 4.13 kernel was the starting point of the analysis with 60,537 files
assessed.  Kate Stewart did a file by file comparison of the scanner
results in the spreadsheet to determine which SPDX license identifier(s)
to be applied to the file. She confirmed any determination that was not
immediately clear with lawyers working with the Linux Foundation.

Criteria used to select files for SPDX license identifier tagging was:
 - Files considered eligible had to be source code files.
 - Make and config files were included as candidates if they contained >5
   lines of source
 - File already had some variant of a license header in it (even if <5
   lines).

All documentation files were explicitly excluded.

The following heuristics were used to determine which SPDX license
identifiers to apply.

 - when both scanners couldn't find any license traces, file was
   considered to have no license information in it, and the top level
   COPYING file license applied.

   For non */uapi/* files that summary was:

   SPDX license identifier                            # files
   ---------------------------------------------------|-------
   GPL-2.0                                              11139

   and resulted in the first patch in this series.

   If that file was a */uapi/* path one, it was "GPL-2.0 WITH
   Linux-syscall-note" otherwise it was "GPL-2.0".  Results of that was:

   SPDX license identifier                            # files
   ---------------------------------------------------|-------
   GPL-2.0 WITH Linux-syscall-note                        930

   and resulted in the second patch in this series.

 - if a file had some form of licensing information in it, and was one
   of the */uapi/* ones, it was denoted with the Linux-syscall-note if
   any GPL family license was found in the file or had no licensing in
   it (per prior point).  Results summary:

   SPDX license identifier                            # files
   ---------------------------------------------------|------
   GPL-2.0 WITH Linux-syscall-note                       270
   GPL-2.0+ WITH Linux-syscall-note                      169
   ((GPL-2.0 WITH Linux-syscall-note) OR BSD-2-Clause)    21
   ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)    17
   LGPL-2.1+ WITH Linux-syscall-note                      15
   GPL-1.0+ WITH Linux-syscall-note                       14
   ((GPL-2.0+ WITH Linux-syscall-note) OR BSD-3-Clause)    5
   LGPL-2.0+ WITH Linux-syscall-note                       4
   LGPL-2.1 WITH Linux-syscall-note                        3
   ((GPL-2.0 WITH Linux-syscall-note) OR MIT)              3
   ((GPL-2.0 WITH Linux-syscall-note) AND MIT)             1

   and that resulted in the third patch in this series.

 - when the two scanners agreed on the detected license(s), that became
   the concluded license(s).

 - when there was disagreement between the two scanners (one detected a
   license but the other didn't, or they both detected different
   licenses) a manual inspection of the file occurred.

 - In most cases a manual inspection of the information in the file
   resulted in a clear resolution of the license that should apply (and
   which scanner probably needed to revisit its heuristics).

 - When it was not immediately clear, the license identifier was
   confirmed with lawyers working with the Linux Foundation.

 - If there was any question as to the appropriate license identifier,
   the file was flagged for further research and to be revisited later
   in time.

In total, over 70 hours of logged manual review was done on the
spreadsheet to determine the SPDX license identifiers to apply to the
source files by Kate, Philippe, Thomas and, in some cases, confirmation
by lawyers working with the Linux Foundation.

Kate also obtained a third independent scan of the 4.13 code base from
FOSSology, and compared selected files where the other two scanners
disagreed against that SPDX file, to see if there was new insights.  The
Windriver scanner is based on an older version of FOSSology in part, so
they are related.

Thomas did random spot checks in about 500 files from the spreadsheets
for the uapi headers and agreed with SPDX license identifier in the
files he inspected. For the non-uapi files Thomas did random spot checks
in about 15000 files.

In initial set of patches against 4.14-rc6, 3 files were found to have
copy/paste license identifier errors, and have been fixed to reflect the
correct identifier.

Additionally Philippe spent 10 hours this week doing a detailed manual
inspection and review of the 12,461 patched files from the initial patch
version early this week with:
 - a full scancode scan run, collecting the matched texts, detected
   license ids and scores
 - reviewing anything where there was a license detected (about 500+
   files) to ensure that the applied SPDX license was correct
 - reviewing anything where there was no detection but the patch license
   was not GPL-2.0 WITH Linux-syscall-note to ensure that the applied
   SPDX license was correct

This produced a worksheet with 20 files needing minor correction.  This
worksheet was then exported into 3 different .csv files for the
different types of files to be modified.

These .csv files were then reviewed by Greg.  Thomas wrote a script to
parse the csv files and add the proper SPDX tag to the file, in the
format that the file expected.  This script was further refined by Greg
based on the output to detect more types of files automatically and to
distinguish between header and source .c files (which need different
comment types.)  Finally Greg ran the script using the .csv files to
generate the patches.

Reviewed-by: Kate Stewart <kstewart@linuxfoundation.org>
Reviewed-by: Philippe Ombredanne <pombredanne@nexb.com>
Reviewed-by: Thomas Gleixner <tglx@linutronix.de>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
 		2017-11-02 11:10:55 +01:00
..
.gitignore staging: greybus: remove .gitignore file 2016-09-19 12:37:09 +02:00
Android.mk greybus: tools: Add tools directory to greybus repo and add loopback 2015-12-17 18:17:07 -08:00
Makefile License cleanup: add SPDX GPL-2.0 license identifier to files with no license 2017-11-02 11:10:55 +01:00
README.loopback greybus: tools: Add tools directory to greybus repo and add loopback 2015-12-17 18:17:07 -08:00
lbtest greybus: tools: Add tools directory to greybus repo and add loopback 2015-12-17 18:17:07 -08:00
loopback_test.c Staging: greybus: Match alignment with open parenthesis. 2017-08-18 15:57:17 -07:00

README.loopback 


        1 - LOOPBACK DRIVER

The driver implements the main logic of the loopback test and provides
sysfs files to configure the test and retrieve the results.
A user could run a test without the need of the test application given
that he understands the sysfs interface of the loopback driver.

The loopback kernel driver needs to be loaded and at least one module
with the loopback feature enabled must be present for the sysfs files to be
created and for the loopback test application to be able to run.

To load the module:
# modprobe gb-loopback


When the module is probed,  New files are available on the sysfs
directory of the detected loopback device.
(typically under "/sys/bus/graybus/devices").

Here is a short summary of the sysfs interface files that should be visible:

* Loopback Configuration Files:
    async - Use asynchronous operations.
    iteration_max - Number of tests iterations to perform.
    size - payload size of the transfer.
    timeout - The number of microseconds to give an individual
              asynchronous request before timing out.
    us_wait - Time to wait between 2 messages
    type - By writing the test type to this file, the test starts.
           Valid tests are:
             0 stop the test
             2 - ping
             3 - transfer
             4 - sink

* Loopback feedback files:
    error - number of errors that have occurred.
    iteration_count - Number of iterations performed.
    requests_completed - Number of requests successfully completed.
    requests_timedout - Number of requests that have timed out.
    timeout_max - Max allowed timeout
    timeout_min - Min allowed timeout.

* Loopback result files:
    apbridge_unipro_latency_avg
    apbridge_unipro_latency_max
    apbridge_unipro_latency_min
    gpbridge_firmware_latency_avg
    gpbridge_firmware_latency_max
    gpbridge_firmware_latency_min
    requests_per_second_avg
    requests_per_second_max
    requests_per_second_min
    latency_avg
    latency_max
    latency_min
    throughput_avg
    throughput_max
    throughput_min



            2 - LOOPBACK TEST APPLICATION

The loopback test application manages and formats the results provided by
the loopback kernel module. The purpose of this application
is to:
    - Start and manage multiple loopback device tests concurrently.
    - Calculate the aggregate results for multiple devices.
    - Gather and format test results (csv or human readable).

The best way to get up to date usage information for the application is
usually to pass the "-h" parameter.
Here is the summary of the available options:

 Mandatory arguments
   -t     must be one of the test names - sink, transfer or ping
   -i     iteration count - the number of iterations to run the test over
 Optional arguments
   -S     sysfs location - location for greybus 'endo' entires default /sys/bus/greybus/devices/
   -D     debugfs location - location for loopback debugfs entries default /sys/kernel/debug/gb_loopback/
   -s     size of data packet to send during test - defaults to zero
   -m     mask - a bit mask of connections to include example: -m 8 = 4th connection -m 9 = 1st and 4th connection etc
                 default is zero which means broadcast to all connections
   -v     verbose output
   -d     debug output
   -r     raw data output - when specified the full list of latency values are included in the output CSV
   -p     porcelain - when specified printout is in a user-friendly non-CSV format. This option suppresses writing to CSV file
   -a     aggregate - show aggregation of all enabled devies
   -l     list found loopback devices and exit.
   -x     Async - Enable async transfers.
   -o     Timeout - Timeout in microseconds for async operations.



             3 - REAL WORLD EXAMPLE USAGES

 3.1 - Using the driver sysfs files to run a test on a single device:

* Run a 1000 transfers of a 100 byte packet. Each transfer is started only
after the previous one finished successfully:
    echo 0 > /sys/bus/greybus/devices/1-2.17/type
    echo 0 > /sys/bus/greybus/devices/1-2.17/async
    echo 2000 > /sys/bus/greybus/devices/1-2.17/us_wait
    echo 100 > /sys/bus/greybus/devices/1-2.17/size
    echo 1000 > /sys/bus/greybus/devices/1-2.17/iteration_max
    echo 0 > /sys/bus/greybus/devices/1-2.17/mask
    echo 200000 > /sys/bus/greybus/devices/1-2.17/timeout
    echo 3 > /sys/bus/greybus/devices/1-2.17/type

* Run a 1000 transfers of a 100 byte packet. Transfers are started without
waiting for the previous one to finish:
    echo 0 > /sys/bus/greybus/devices/1-2.17/type
    echo 3 > /sys/bus/greybus/devices/1-2.17/async
    echo 0 > /sys/bus/greybus/devices/1-2.17/us_wait
    echo 100 > /sys/bus/greybus/devices/1-2.17/size
    echo 1000 > /sys/bus/greybus/devices/1-2.17/iteration_max
    echo 0 > /sys/bus/greybus/devices/1-2.17/mask
    echo 200000 > /sys/bus/greybus/devices/1-2.17/timeout
    echo 3 > /sys/bus/greybus/devices/1-2.17/type

* Read the results from sysfs:
    cat /sys/bus/greybus/devices/1-2.17/requests_per_second_min
    cat /sys/bus/greybus/devices/1-2.17/requests_per_second_max
    cat /sys/bus/greybus/devices/1-2.17/requests_per_second_avg

    cat /sys/bus/greybus/devices/1-2.17/latency_min
    cat /sys/bus/greybus/devices/1-2.17/latency_max
    cat /sys/bus/greybus/devices/1-2.17/latency_avg

    cat /sys/bus/greybus/devices/1-2.17/apbridge_unipro_latency_min
    cat /sys/bus/greybus/devices/1-2.17/apbridge_unipro_latency_max
    cat /sys/bus/greybus/devices/1-2.17/apbridge_unipro_latency_avg

    cat /sys/bus/greybus/devices/1-2.17/gpbridge_firmware_latency_min
    cat /sys/bus/greybus/devices/1-2.17/gpbridge_firmware_latency_max
    cat /sys/bus/greybus/devices/1-2.17/gpbridge_firmware_latency_avg

    cat /sys/bus/greybus/devices/1-2.17/error
    cat /sys/bus/greybus/devices/1-2.17/requests_completed
    cat /sys/bus/greybus/devices/1-2.17/requests_timedout


3.2 - using the test application:

* Run a transfer test 10 iterations of size 100 bytes on all available devices
    #/loopback_test -t transfer -i 10 -s 100
    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
    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


* Show the aggregate results of both devices. ("-a")
    #/loopback_test -t transfer -i 10 -s 100  -a
    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
    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
    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

* Example usage of the mask option to select which devices will
  run the test (1st, 2nd, or both devices):
    # /loopback_test -t transfer -i 10 -s 100 -m 1
    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
    # /loopback_test -t transfer -i 10 -s 100 -m 2
    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
    # /loopback_test -t transfer -i 10 -s 100 -m 3
    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
    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

* Show output in human readable format ("-p")
    # /loopback_test -t transfer -i 10 -s 100 -m 3 -p

    1970-1-1 0:12:37
    test:                       transfer
    path:                       1-4.17
    size:                       100
    iterations:                 10
    errors:                     0
    async:                      Disabled
    requests per-sec:           min=390, max=547, average=469.299988, jitter=157
    ap-throughput B/s:          min=90480 max=126904 average=108762.101562 jitter=36424
    ap-latency usec:            min=1826 max=2560 average=2146.000000 jitter=734
    apbridge-latency usec:      min=1620 max=1982 average=1882.099976 jitter=362
    gpbridge-latency usec:      min=56 max=57 average=57.099998 jitter=1


    1970-1-1 0:12:37
    test:                       transfer
    path:                       1-5.17
    size:                       100
    iterations:                 10
    errors:                     0
    async:                      Disabled
    requests per-sec:           min=397, max=538, average=461.700012, jitter=141
    ap-throughput B/s:          min=92104 max=124816 average=106998.898438 jitter=32712
    ap-latency usec:            min=1856 max=2514 average=2185.699951 jitter=658
    apbridge-latency usec:      min=1460 max=2296 average=1828.599976 jitter=836
    gpbridge-latency usec:      min=56 max=57 average=57.099998 jitter=1