-
Notifications
You must be signed in to change notification settings - Fork 99
Command Line Options
tnvme’s command line options will most likely be forever growing. The most accurate place to gather details of those options are via the command line itself by requesting help: ./tnvme --help. However certain options are complex and so it warrants a more extensive background explanation as will be found herein.
The command line options implement short and long versions. The short versions work by specifying any associated parameters immediately after without any whitespace as follows: ./tnvme --t3:0.04. The long options work by specifying an equal sign after the option without any whitespace as follows: ./tnvme --test=3:0.0.4.
tnvme executes test cases based upon a targeted NVMe specification. As new revisions of the specification are released from the working group, changes must be made to the test cases to adapt. Programmatically tnvme solves this via C++ polymorphism. A developer will derive child classes from older base classes and modify/enhance the appropriate logic. A developer can specify which revision all tests will target via this command line option. For more details refer to Test Strategy.
Reports a summary of all tests cases which tnvme actively supports. The output from this option is filtered by command line option -v(--rev) .
This option reports lengthy, highly detail, test documentation. The output of this option is filtered by command line option -v(--rev) . The intention of this option is meant to reasonably answer the question, “What does this test do?”. The optional parameter, if absent, instructs tnvme to report all details for all tests in all groups. If a single group number is supplied, then tnvme reports all details for all tests contained within that group only. If a single test is supplied by qualifying it with its associated group number, then the details for that test only is reported.
[username@server ~/tnvme]$ ./tnvme --detail=3:0.0.4
tnvme binary: v/2.4
tnvme compiled against dnvme API: v/1.4.0
dnvme API residing within kernel: v/1.4.0
3: Group:Basic Initialization
0.0.7: Test:Create contiguous IOCQ(irq) and IOSQ's
Compliance: revision 1.0b, section 7
Issue the admin commands Create contiguous I/O SQ and Create I/Q
CQ(irq) to the ASQ and reap the resulting CE's from the ACQ to certify
those Q's have been created.
This option executes tests. The output of this option is filtered by command line option -v(--rev) . If the optional parameter is missing tnvme runs all tests. If only a group number is specified it runs all the tests within that group. If a specific test case is specified it will run only that tests, if and only if, there are no dependencies. The framework automatically handles test case dependencies on our behalf since they can be very complicated. The rules governing test case dependencies are detailed by the Test Numbering scheme. In addition to test dependencies, the execution of all tests in GrpInformative is a requirement and may not be over-ridden. The reasons behind the mandatory GrpInformative operation are due to the entire framework relying upon the data being extracted during this group's execution.
[username@server ~/tnvme]$ ./tnvme --test=3:0.0.4 tnvme binary: v/2.4 tnvme compiled against dnvme API: v/1.4.0 dnvme API residing within kernel: v/1.4.0 ....... 2012-04-18_20:00:44.86921 tnvme: SUCCESSFUL test case run 2012-04-18_20:00:44.86931 tnvme: ------------------END TEST------------------ 2012-04-18_20:00:44.86938 tnvme: Iteration SUMMARY passed : 9 2012-04-18_20:00:44.86947 tnvme: failed : 0 2012-04-18_20:00:44.86956 tnvme: skipped: 0 2012-04-18_20:00:44.86977 tnvme: total : 9 2012-04-18_20:00:44.86984 tnvme: Stop loop execution #0 2012-04-18_20:00:44.86990 SUCCESS: testing
This option lists all the devices that have been exported by a successful load of dnvme. This is also the list of devices which tnvme may target for testing.
[username@server ~/tnvme]$ ./tnvme --list Devices available for test: /dev/nvme0
This option forces that instance of tnvme to target the specified device for testing, data extraction, manipulation of its settings or read/write its configuration space.
Issues a controller reset to the device via the devices CC.EN register bit in PCIe configuration space.
Forces tnvme to loop the test cases <count> times. Thus this option only makes sense unless it is partnered with -t(--test) [<grp> | <grp>:<test>]. The looping continues until such time an error is detected, unless tnvme has also been instructed to ignore errors as per command line option -i(--ignore)
Forces tnvme to skip entire groups of tests or a specific individual test case. The mandatory filename has special formatting requirements which may be learned by peeking into the example file tnvme/skiptest.cfg.
tnvme defaults to a dumping its many dump files to a sub-directory called ./Dump. This default location can be changed via this option. Do not confuse this directory with the logging macros embedded within tnvme's source code called LOG_DBG(), LOG_NRM(), etc. These logging macros get sent to stderr. It is possible however to re-direct stderr into the <dirname> directory like which is being done by the shell script manage/runtnvme.sh using a utility called svlogd. Without explicitly re-directing stderr to the <dirname> the logging macros will be directed to where ever stderr is being piped.
This option is only useful if paired with -t(--test) [<grp> | <grp>:<test>] since ignoring errors is of course a function of running tests. The specific behavior surrounding the ignorance of errors has some peculiar outcomes which are detailed in the discussion about the Framework.
When a test executes it can be decided that it fails to comply with the NVMe specification and an exception will result. However, a test could privately fail if say it didn't pay attention to the PCI configuration space's error bits. Therefore the framework checks these error bits after each test case. Incidentally, the framework resets all error bits before each test has started execution so as to not propagate errors to subsequent tests. This option allows controlling how the framework views those bits. Specifically, this option is setting a bitmask for which bits of the indicated PCI register should be checked for errors. Thus values of all zero(0) indicates nothing is to be considered an error. If this bitmask is absent from the command line, the framework takes the liberty of assigning its own notion of a bitmask. See source file tnvme/tnvme.cpp for these defaulted bitmask values.