Difference between pages "r7.1.1:Usage Guide (test)" and "r7.1.1:Usage Guide (testing)"

From liblfds.org
(Difference between pages)
Jump to navigation Jump to search
m (1 revision imported)
 
m (1 revision imported)
 
Line 1: Line 1:
{{DISPLAYTITLE:Usage Guide (test)}}
{{DISPLAYTITLE:Usage Guide (testing)}}
==Introduction==
==Introducton==
The ''test'' programme is a thin command line veneer to ''libtest''.  It runs a series of tests, first for the porting abstraction layer (and so can be used to validate any new ports) and then upon each data structure, and stops running on any test failure or error of any kind.
Testing functionality is implemented in a library, ''libtest'', which offers a small and simple API, so it can be used on arbitrary platforms.  Using the ''libtest'' library also requires using one API exposed by the ''libshared'' library, for memory management.  Finally, a convenience thin command line veneer, ''test'', is provided, which is used from the command line to run the test suite and see the results.


Testing lock-free code is problematic since a large class of bugs are race conditions, which are impossible or nearly impossible to methodically reproduce.  As such testing consists in part of simple API tests to enure every function does what it is supposed to do at least when in the absence of race conditions, but in the main of best-effort attempts to provoke race conditions and detect them.
As such, usage is either the use of the ''libtest'' API (and also the ''libshared'' API, for memory management), or the use of the command line ''test'' programme.


Make sure you run the release build - the debug build does so much extra work that it misses race conditions the release build will pick up on.
===API Usage Guides===
* [[r7.1.1:Usage Guide (libshared)|Usage Guide (libshared)]]
* [[r7.1.1:Usage Guide (libtest)|Usage Guide (libtest)]]


==Running==
===Command Line Usage Guide===
The test programme is run from the command line.  Change directory into ''test_and_benchmark/test/bin/'' and type;
* [[r7.1.1:Usage Guide (test)|Usage Guide (test)]]
 
  test -r
 
The full command line (which is printed by ''-h'' or by running with no arguments) is as follows;
 
test -e -h -i [n] -m [n] -r -v
  -e    : empirically determine Exclusive Reservation Granule
            (currently supports only ARM32)
  -h    : help
  -i [n] : number of iterations    (default : 1)
  -m [n] : memory for tests, in mb  (default : 512)
  -r    : run (causes test to run; present so no args gives help)
  -v    : version
 
===Arguments===
'''-e''' : Attempts to determine the Exclusive Reservation Granule.  See [[r7.1.1:Usage Guide (liblfds)#Exclusive Reservation Granule (ARM, POWERPC)|Exclusive Reservation Granule (ARM, POWERPC)]] for details; this is only needed on ARM and POWERPC, and only currently supported for ARM32.
 
'''-h''' : Show help.
 
'''-i [n]''' : The test programme will loop ''n'' times.  Any error (e.e. allocation failure) or test failure will cause the test programme to print and error and exit completely, rather than merely abort the current iteration.
 
'''-m [n]''' : There are a large number of tests.  Mainly these tests run one thread per logical core, but there are a few API tests and a few single-threaded tests.  Each test being run typically allocates a large number of data structure elements with which to perform the test.  The value supplied to the ''-m'' argument is the amount of memory to be used for element allocation, in megabytes.  The code does not properly or consistently check for memory exhaustion; a safe absolute minimum is 4mb, 64mb is a reasonable minimum for testing, and anything more than 1gb gives no advantage.
 
'''-r''' : If run with no arguments, the help text is displayed.  As such, an argument is needed to inform the test programme that it is in fact to run tests, which is why the "-r" argument exists.
 
'''-v''' : Shows the build version, like so;
 
test 7.1.1 (release, user-mode)
libshared 7.1.1 (release, Linux, user-mode)
libtest 7.1.1 (release, Linux, user-mode)
liblfds 7.1.1 (release, Linux, user-mode, x64, GCC >= 4.7.3)


==See Also==
==See Also==
* [[r7.1.1:Usage Guide (testing)|Usage Guide (testing)]]
* [[r7.1.1:Release_7.1.1_Documentation|Release 7.1.1 Documentation]]

Latest revision as of 20:16, 17 February 2017

Introducton

Testing functionality is implemented in a library, libtest, which offers a small and simple API, so it can be used on arbitrary platforms. Using the libtest library also requires using one API exposed by the libshared library, for memory management. Finally, a convenience thin command line veneer, test, is provided, which is used from the command line to run the test suite and see the results.

As such, usage is either the use of the libtest API (and also the libshared API, for memory management), or the use of the command line test programme.

API Usage Guides

Command Line Usage Guide

See Also