-
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.
The framework requires a place to write dump files and refuses to create the directory if it doesn't exist. The dump directory may be specified, but if not the default value is w/r to the working directory and is called "./Dump".
mkdir Dump
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 your 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 creation of the framework causes interaction with a DUT before any test can execute. The reasons behind this mandatory interaction is detailed under the singleton gInformative. Basically, the entire framework relies upon the data provided by gInformative.
[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.
While running the test suite the current preservation state of the DUT may be desired to remain intact. Preservation means any changes which are permanent cannot be performed. Permanent changes are defined to be changes that will remain through a cold power cycle. This is normally, but not limited to, writing to the media, formatting the media, or downloading firmware. Any test which must preserve the DUT and causes permanent change is considered NOT runnable. Each test developer must write the logic to adhere to the desires preservation flag by returning the correct value from function RunnableCoreTest.
A method to supply the framework data classified as "golden" data to attempt verification that a DUT reports the proper configuration data before any test is executed is possible with this cmd line option. This option only allows verification of the admin identify cmd, but all structures are supported, namely the controller and namespace structures. The supplied <filename> must be of a specific format, but is meant to be generic to handle any possible identify cmd syntax for any possible device. An example file is provided with detailed notes as an example to follow at identify.gold.xml. The data supplied in the cmd line file is considered the golden data, tnvme subsequently issues an identical identify cmd to the DUT and runs a comparison between the data. The golden data file must also supply masking bits to identify which of the bits should be used in the comparison.
This option is meant to be run alone, no other options will be honored.
The default behavior of the framework, after a failure has been detected, is to do nothing to the DUT. The DUT will remain in exactly the state of failure. If state information is desired to be dumped after a failure then --postfail performs this action by dumping state information to the specified --dump directory. The names of the files will be of the form post.failure.<resource>
If a test modifies the configuration of the DUT, and a failure occurs, the state of the DUT is not restored by default. However, by supplying this option a callback into the framework will occur to attempt to restore that which was saved at the start of any particular group. This logic will be dependent upon the group, some groups contain test cases which will permanently modify the configuration from which a cold power cycle won't fix. Thus these groups of tests must save the state of the DUT, so if a failure occurs within one of its containing tests, a callback will be performed in an attempt to restore that which was previously saved.
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.
A thorough explanation of the [Number of Queues}(https://github.com/nvmecompliance/tnvme/wiki/Number-of-queues) should be read to understand this option.
This option is meant to be run alone, no other options will be honored.
A device namespace can support many different formats. A compliance suite will be interested in changing the format of a namespace for testing. This will be done within the framework by issuing an admin cmd set Format NVM cmd. However, tnvme also allows issuing formatting instructions via the cmd line. A file specifying format instructions in XML style language results in correlating, consecutive cmds being issued to the target device. An example file is provided with detailed notes as an example to follow at format.xml.
This option is meant to be run alone, no other options will be honored.
Read any register in the PCI configuration address space or also within the mapped addresses of BAR0 and BAR1, i.e. the ctrlr address space.
Write any register in the PCI configuration address space or also within the mapped addresses of BAR0 and BAR1, i.e. the ctrlr address space.
[username@server ~/tnvme]$ ./tnvme --wmmap=BAR01:0x14:0x04:0xffffffff:b
....
tnvme: Writing ctrl'r space register...
0x00000014: 0xFF FF FF FF
[username@server ~/tnvme]$ ./tnvme --rmmap=BAR01:0x14:0x04:b
....
tnvme: Reading ctrl'r space register...
0x00000014: 0xF1 FF FF 00
NOTES:
1) In the example above reading of the register did not produce the exact value written due to Read Only(RO) bits in the register
2) The only registers which won't be readable, via the command line only, are the AQA, ASQ and ACQ registers. These registers are special, and dnvme will always reset them to zero(0) to avoid a misunderstanding by the device that any non-zero value could be interpreted as actual memory backing admin Q's if the device is enabled. This action occurs both when the file descriptor to the device is opened and closed, which incidentally occurs every time tnvme is launched.