NVMETEST

NVME Test Program

Script File User Guide

Versions 2A4d and higher

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.

TABLE OF CONTENTS

(Go To TOC)

EXAMPLE SCRIPTS

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

BASIC0.DSF

This script shows how to use many NVMETEST commands for write/read/compare operations, including using multiple I/O queues.

BUFFER.DSF

This scripts tests PRP and SGL buffer pointer use with and without address offsets.

FWDL.DSF

An example of how to use NVMETEST to download firmware to a drive using the NVME Firmware commands.

MULTINS.DSF

This script performs write/read/compare commands on multiple namespaces.

NSCHK.DSF

This script deletes and creates multiple namespaces and performs basic write/read/compare commands on those namespaces.

WRC0.DSF

This script shows how to use the RWX command. On some drives it will expose problems in a drive's data buffering.

(Go To TOC)

OVERVIEW

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.

(Go To TOC)

BASIC LAYOUT OF A SCRIPT FILE

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.

(Go To TOC)

USING SCRIPT FILES

Example 1

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

Example 2

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.

Example 3

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

Example 4

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 idcntrl

Example 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.

Example 5

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

Example 6

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

(Go To TOC)

EDVT TEST SUITE SCRIPTS

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.

(Go To TOC)

QUESTIONS OR PROBLEMS?

Technical support can be found at:

http://www.ata-atapi.com/techsupp.html

-end-