Copyright 2015-2020 Hale Landis. All rights reserved.
Note: See documentation files NVMETEST.HTM and CMD-SUM.HTM. Also see the example script files that are part of the NVMETEST distribution (the *.DSF files). The example script files are described below.
WARNING: Some email programs think that *.SCR files are "screen saver" files. *.DSF or *.TXT might be a better naming convention on on systems with these stupid email programs.
Execute any of these example scripts using the SCRIPT=x command line option, or, use the SCRipt command. For example:
NVMETEST SCRIPT=BASIC0.DSF SCRipt BASIC0.DSF
Most of these scripts use the command line option N5=66758493 (variable opt_n5) to run the script in 'batch mode'. This is useful if a DOS batch file is used to execute scripts. This 'magic value' causes the scripts to bypass any prompting of the user for input. This is very useful for over night testing when no one is present to respond to the prompts. For example:
rem an example DOS BAT file rem delete log files del *.log rem execute scripts without prompting for user input nvmetest script=basic0.dsf n5=66758493 if errorlevel 1 goto :fail nvmetest script=wrc0.dsf n5=66758493 if errorlevel 1 goto :fail echo PASSED goto :done :fail echo FAILED :done
This script shows how to use many NVMETEST commands for write/read/compare operations, including using multiple I/O queues.
This scripts tests PRP and SGL buffer pointer use with and without address offsets.
An example of how to use NVMETEST to download firmware to a drive using the NVME Firmware commands.
This script performs write/read/compare commands on multiple namespaces.
This script deletes and creates multiple namespaces and performs basic write/read/compare commands on those namespaces.
This script shows how to use the RWX command. On some drives it will expose problems in a drive's data buffering.
Script files are supported only in the commercial/full version of NVMETEST. A script file is an easy way to have NVMETEST issue a series of commands in a "batch" mode.
Most commands allowed in a script file are identical to the commands that may be entered from the keyboard. There are several additional commands that are valid only within script files.
Use the NVMETEST SCRIPT=x command line option or the SCRipt command to start the execution of a script file.
When a script is executed directly from the NVMETEST command line (using the SCRIPT=x command line option) the Nn=n comand line options can be used to pass numeric information to the script. When a script is executed using the SCRipt command the optional parameter 'n' can be used to pass a numeric value to the script via the scr_param variable (or via the OPTNUMset command). See the BASIC0.DSF script file to for an example.
If the script file terminates due to an EXit command or if ONERRor EXit is active when an error happens, NVMETEST will also terminate. If the script file terminates due to a QUit command or if ONERRor QUit is active when an error happens, NVMETEST will terminate the script file and enter keyboard mode. If the end of the script file is reached and there is no QUit or EXit command, NVMETEST will enter keyboard mode.
A group of scripts can be made into a test suite using the Script List described in the NVMETEST User Guide.
Create a script file with your favorite ASCII text editor. Each line of a script file may contain one NVMETEST command or a comment line.
In lines of a script file a TAB character is equivalent to a SPACE character. Whitespace is one or more TAB and/or SPACE characters. Excess whitespace before and within and at the end of a script file line are ignored. All characters following a semicolon (;) are ignored. All characters following the two slash characters (//) are ignored. Lines containing only whitespace are ignored.
All scripts files contain a main part and zero, one or more subroutine definitions.
The main part is executed immediately when the script file is loaded successfully. The main part execution terminates when the first BEGINSub, EXit or QUit command is encountered.
The following shows the basic layout:
; This is the "main" part. Execution of the script file ; starts with the first line of the main part. Execution ; of the main part ends if a BEGINSub, EXit or QUit command ; is encountered. SAY This is the main part of this script! IF dev_num ; just an example of an IF command CALL ALPHA ; the main part can call a subroutine ELSE CALL BETA ; the main part can call a subroutine ENDIF QUIT ; main part execution ends here ; The main part can be followed by zero, one or more subroutine ; definitions. Each subroutine definition starts with a ; BEGINSub command and ends with a ENDSub statement. BEGINSUB ALPHA ; Statements within subroutine ALPHA. SAY This is subroutine ALPHA! ENDSUB BEGINSUB BETA ; Statements within subroutine BETA. SAY This is subroutine BETA! ENDSUB ; More subroutine definitions...
A script file may contain a #INCLUDE or #NEXT directive that causes processing of the current script file to stop and processing of a different script file to begin.
The #INCLUDE directive tells the script file compiler to stop processing the current script file and begin processing another script file. At the end of the included file processing returns to the file containing the #INCLUDE directive immediately following the #INCLUDE directive. This is the same #include found in some programming languages.
The #NEXT directive tells the script file compiler to stop processing the current script file and begin processing another script file. The #NEXT is similar to but not the same as #include directives found in some programming languages as the script compiler does not return to processing the file containing the #NEXT directive.
Use #INCLUDE or #NEXT to append a file of common subroutines to a main script file.
When #INCLUDE OR #NEXT is used all files appended to the root script file are considered to be part of the root script file for line numbering.
A simple script file can be used to automate a task. This script file executes a number of NVME commands. It contains only a main part that is executed as soon as the script file is loaded and compiled.
; This is a sample NVMETEST script file. ; This is a commment line. // This is also a comment line. ; The following line is also ignored (all whitespace). reset // reset setup 1 // create i/o queue 1 r 1 1 0 // read lba 0 d 0 // dump the lba0 data
The main part can be used to set up modes and variables used throughout the entire script file, for example see the *.DSF files. These sample script files also show how subroutines can be used to create complex scripts. These files also shows how the NVMETEST WINdow command can be used to create menus.
A script file can used to define subroutines that act as if they are new NVMETEST commands. In this case the main part would probably contain only a QUIT statement. When this script is loaded, the subroutines are defined and can be called from the keyboard by using the CAll command. For example, NVMETEST does not have a high level command for all the NVME commands. A public subroutine could be created that looks like a NVME command:
QUit ; main part starts and ends here beginsub delallns public // must be public nsdelete 0xffffffff // delete all namespaces endsub delallns
These subroutines can then be executed when NVMETEST is in keyboard mode by entering the command:
call delallns
or just by entering the command:
delallns
Be careful when selecting subroutine names. Any NVMETEST command, including commands like QUit and Exit, can be replaced by a PUBlic subroutine of the same name. For example, the 'ID' command could be redefined as:
QUit ; main part starts and ends here beginsub identify public // parameter is the CNS number, defaults to 0 id sub_param1 endsub idcntrlExample use:
identify // ID 0 identify 1 // ID 1
Note that many NVMETEST commands have short spellings. To effectively replace these commands, multiple subroutines would need to be defined. For example, to replace the EXit command the following could be used:
QUit ; main part starts and ends here BEGINSub EX PUBLIC call myexit ENDSub BEGINSub EXI PUBLIC call myexit ENDSub BEGINSub EXIT PUBLIC call myexit ENDSub BEGINSub myexit private SAY ***** Exiting with return code {sub_param1} ***** EXit sub_param1 ENDSub
Note that subroutine "myexit" is private and can not be called from the keyboard.
Multiple scripts that work together can be created to automate complex tasks or to do things that would be too large for a single script. A script file can "call" another script file using the SCRipt command. This replaces the script file commands that are currently loaded but it does not alter the value of variables (expect script_flag). Variables can be passed between the scripts as they are loaded by one another. Note that when a script is completed a SCRipt command must be used to reload the calling script again. For example:
; script INIT.DSF, script that initializes everything ; and call the loop control script. ; initialize variables, etc, here set loopcntr = 0 set errcode = 0 ; call the script that runs the "main loop". script loop.dsf
; script LOOP.DSF, the script that loops calling ; script ONE and TWO. ; check for any error when ONE.DSF or TWO.DSF call ; this script. if errcode if ( loopcntr & 0x01 ) say SCRIPT ONE.DSF LOOP {loopcntr} error {errcode}. else say SCRIPT TWO.DSF LOOP {loopcntr} error {errcode}. endif quit endif ; update loop counter, check for end set loopcntr = ( loopcntr + 1 ) if ( loopcntr > 10 ) quit endif ; call ONE.DSF or TWO.DSF based on bit 0 of "loopcntr" if ( loopcntr & 0x01 ) script ONE.DSF else script TWO.DSF endif
; script ONE.DSF, called by the loop control script ; do something in this script. ; set errcode to a non-zero value if there is any error that ; should stop looping. ; this script should contain no QUit or EXit commands. It ; should return by using the following SCRipt command. call message script LOOP.DSF beginsub message say Hi, this is ONE.DSF talking. endsub message
; script TWO.DSF, called by the loop control script ; do something in this script. ; set errcode to a non-zero value if there is any error that ; should stop looping. ; this script should contain no QUit or EXit commands. It ; should return by using the following SCRipt command. call message script LOOP.DSF beginsub message say Hi, this is TWO.DSF talking. endsub message
This is an example of the #NEXT directive.
The "root" script file:
// this is the "root" script file containing the main part say I am the root script file. say I am calling a subroutine in another file. call sub1 // end of "root" -- append my subroutines #next mysubs.dsf
My subroutines script file:
// this is the mysubs.dsf script file beginsub sub1 say I am subroutine sub1 endsub sub1 beginsub sub2 say I am subroutine sub2 endsub sub2
The *free* EDVT Test Suite can be found at the ata-atapi.com web site.
The EDVT Test Suite scripts are described by the EDVTTEST.HTM User Guide.
The test suite user guide also describes the rules that these scripts should follow, such as how global test parameters are handled, the format of messages and more. Create your own EDVT tests.
Technical support can be found at:
http://www.ata-atapi.com/techsupp.html
-end-