version_number=2.20.1.0087

Intel Corporation Modular Test Architecture For Linux(TM) User Guide

Revision 2.20

September 16, 2012
 
THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTIES  WHATSOEVER, 
INCLUDING ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE, 
OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE. 

A license is hereby granted to copy and reproduce this specification for 
internal use only.  No other license, express or implied, by estoppel or 
otherwise, to any other intellectual property rights is granted herein.

Intel disclaims all liability, including liability for infringement of any 
proprietary rights, relating to implementation of information in this 
specification. Intel does not warrant or represent that such implementation(s) 
will not infringe such rights.

Third-party trademarks are the property of their respective owners.

Copyright 1998-2012. Intel Corporation, All Rights Reserved. 
 
Version History
Version  Date    Author           Changes
0.1  11/03/2003  Sabrina Korpela  First Draft
0.2  12/18/2003  Sabrina Korpela  Changed font in table of commands
1.0  06/18/2004  Sabrina Korpela  Updated for 1.0 Release
1.5  11/02/2004  Sabrina Korpela  Updated for 1.5 Release Beta
1.5  06/13/2005  Sabrina Korpela  Updated for 1.5 Final Release
2.0  10/02/2006  Sabrina Korpela  Updated for 2.0 Release Beta
2.1  05/18/2007  Sabrina Korpela  Updated for 2.1 Release Beta
2.3  01/14/2008  Sabrina Korpela  Updated for 2.3 Release Beta
2.4  04/21/2008  Sabrina Korpela  Updated for 2.4 Release
2.5  12/24/2008  Sabrina Korpela  Updated for 2.5 Alpha Release
2.6  04/22/2009  Sabrina Korpela  Updated with /LF information
2.8  03/23/2012  Chong Lai Soon   Updated with /RECONFIG flag.
				  Updated with /RUN flag.
				  Updated with latest return code.
2.8  04/02/2012  Chong Lai Soon   Fixed tracker# EPSD100227936 - /RECONFIG without /FLOW will delete the original flows.
				  Fixed tracker# EPSD100227935 - return code issue.
2.9  04/26/2012  Chong Lai Soon   Fixed tracker# EPSD100227832 - T: Allow user to change license expiration notification setting.
				  Fixed tracker# EPSD100219076 - T: Allow autoconfiguration without starting test running.
2.9  06/13/2012  Chong Lai Soon	  Fixed tracker# EPSD100227832 - T: Allow user to change license expiration notification setting for Linux.
				  Fixed tracker# EPSD100226264 - T: Remove redundant header messages in log file with /LF flag.
				  Fixed tracker# EPSD100226131 - T: Please add INFO class messages to the /LF startup feature.
2.9  09/16/2012  Chong Lai Soon	  Klocwork issues fixed.


Table of Contents

Version History  
1.  Introduction  
2.  Reference Documents  
3.  Required Files  
4.  License
5.  Supported Operating Systems  
6.  "T" Quick Start  
7.  "T" Commands and Parameters  
8.  "T" Test Results  
9.  "T" Screen Output  
10. "T" Summary File  
11. Environment Variable 
12. Return Code 

 
1.  Introduction

Intel Modular Test Architecture is a test and stress evaluation 
solution for Intel x86/x64/IPF compatible systems.  Groups of tests, 
called test modules, support specific system subassemblies such as hard disks 
and memory.  

2.  Reference Documents

  Intel Modular Test Architecture for Linux Developer's Guide

3.  Required Files

  Linux and Solaris-specific: files will be wrapped into a "tar" file:  
        iMTA-2.xx.x.xxxx.tgz (example: iMTA-2.03.01.0022.tgz)
  The files will be automatically installed in a subdirectory called
  "./iMTA-2.xx.x.xxxx", based on user's "tar" commands.

  All Operating Systems: the test executive files needed include the following.
  "t" and "texec" for Linux/Solaris, "t.exe" for Windows
  t.pkx (or other package file)
  libmta.so.2.0
  libmta.so.2
  libmta.so
  libseq.so.2.0
  libseq.so.2
  libseq.so
  libts.so.2.0
  libts.so.2
  libts.so
  xmlpkg.dtd

  To run the graphical test executive (CTC), additional files are required.
  "ctc" and "ctcbin" for Linux/Solaris, ctc.exe for Windows
  libFOX.so
  libFOX-1.6.so.0       
  libFOX-1.6.so.0.0.4
  Note that FOX libraries are not created by Intel, and are stored in a
  sub-directory titled "fox", especially when distributed to customers.

  To test using either CTC or T, test modules are needed.  There are three 
  pieces for each test module: a module file, a configuration file, and a 
  help file.
  
  Module files
     Linux/Solaris examples: lxBMC, lxcmos, lxCPU, lxdiskdrv
     Windows examples: iwCPU.exe, iwDiskDrv.exe, iwMemory.exe
  Configuration files for each module
     Linux/Solaris examples: lxBMC.snx, lxcmos.snx, lxCPU.snx, lxdiskdrv.snx
     Windows examples: iwCPU.snx, iwDiskDrv.snx, iwMemory.snx
  Help files for each module (both CHM - compiled HMTL - and text)
     Linux/Solaris examples: lxBMC.chm, lxcmos.chm, lxCPU.chm, lxdiskdrv.chm
     Windows examples: iwCPU.chm, iwDiskDrv.chm, iwMemory.chm

  Some modules require drivers to successfully run.  See each module's help 
  file for full details.  

  For Linux, the most common required drivers are the IOMMAP and IMB.  They are
  released with the Linux package for ease of usage.  Manually install them 
  from the imbdrvr and iommap subdirectories of "iMTA-2.xx.x.xxxx".  
  See "iommap.txt" and "imb.txt" for details.  The iommap libraries are 
  included in this directory.  
  libiommap.so
  libiommap.so.2.00.i386
  libiommap.so.2.i386

4.  License
All software components used in the Intel Modular Test Architecture 
will require a license key to operate.  The license key is stored in a file, 
"license.key", which needs to be stored in the same directory as the test 
executive, executive libraries, and modules.  
Linux-specific: Only the super user ("root") may invoke testing if the 
license key is based on the BIOS ID.

5.  Supported Operating Systems
    Linux:
	RedHat Advanced Server 4.0 (2.6.9-5.ELsmp) * see notes in Errata 
	RedHat Advanced Server 4.0 U2 (2.6.9-22.EL)
	RedHat Advanced Server 4.0 U3 (2.6.9-30.ELsmp)
	RedHat Advanced Server 4.0 U4 (2.6.9-39.EL)
        RedHat Advanced Server 5 (2.6.18-el5)
	SLES 9.1 (2.6.4-52-smp)
	SLES 9.2 (2.6.8-22-smp)
	SLES 9.3 (2.6.5-7.244-default)
	SuSE 10 (2.6.13-15-default)
        SLES 10.1 (2.6.16.46-0-12-xenpae)
    Windows:
        Windows Server 2003 SP1 32-bit
        Windows Server 2003 SP1 x64
  * See kernel installation notes in cmd_release.txt

6.  "T" Command Line Test Executive Quick Start 
NOTE: If the current directory is not included in the "PATH" environment 
variable, replace all "t" references with "./t".

a.  Move to directory containing all files listed in "Required Files" above.

b.  Import all module configuration files (.snx extension) into a new package 
    file (default name: "t.pkx").
      t /autoi

c.  Alternatively, to only import one module configuration file, type the name 
    of the file after the "autoi" option:
      Linux/Solaris: 	./t /autoi lxCPU.snx
      Windows:		t /autoi iwCPU.snx

d.  To save data to a different package file, use the "-pkg" option.  
      t /autoi /pkg new_pkg_file_name.pkx
    NOTE: If a different package file name is used, all following commands 
    must include:
      -pkg new_pkg_file_name.pkx

e.  Autoconfigure the package file for the current system (replace 
    'new_config_name' with your own configuration name).
      t /auto new_config_name
    
    NOTE: Tests will run immediately after they are configured. All 
    destructive tests are disabled.
    
    NOTE: Messages colors can be configured for either a black or white 
    background. If the messages are hard to read or don't display on the 
    screen, type "-bg black" or "-bg white" at the end of any of the commands.  
    The chosen color configuration is saved and used for all future commands.

f.  To re-run the same configuration:
      t /pc new_config_name

g.  To also save all messages to a file:
      t /pc new_config_name /rr new_file_name.txt
  
h.  To list all tests in the default section of a package file:
      t /dt

i.  To list the pre-configured options in the package file:
      t /dt /pc

See "T Commands and Parameters" section for additional command line options.
 
7.  "T" Commands and Parameters
NOTE: If the current directory is not included in the "PATH" environment 
variable, replace all "t" references with "./t".

The command line syntax is as follows:

t [runlist] [flags]

Both runlist and flags are optional.  If the Test Executive is run with no 
command line arguments, all enabled tests will execute in the order they 
appear in the module definition list.

Below are examples of valid run lists, assuming the following test 
configuration (displayed with "t /dt"):

Available Modules
      2     device-memory
G--E  3       test-Memory Sliding Ones and Zeroes 
G--E  4       test-Memory Random Data
G--E  5       test-Memory Address Pattern
      6     device-CPU
G--E  7       test-clock_speed
G--E  8       test-MMX_instructions
      9     device-Drive
G--E  10      test-Physical Disk Sequential Read
G--E  11      test-Physical Disk Sequential WRC

t           // Run all tests in main section of package file
t 2         // Run all tests of "memory" device in package file
t memory    // Run all tests of "memory" device in package file
t 3         // Run test 1 of "memory" device in package file
t memory.Memory Sliding Ones and Zeroes
            // Run test 1 of "memory" device in package file

Valid Test Executive flags are listed below.  Note that unrecognized flags are 
passed to the tests in addition to the common and specific command line 
arguments found in the module definition file.

NOTE: "Any valid string" is defined as alphanumeric characters, dashes and 
underscores (-, _), brackets ([, ]), and spaces.
 
NOTE: "Any valid Linux filename" specifically excludes all keyword names: 
AUTO, AUTOI, etc, in all case variations.

FLAG:              /AUTO [configname]
ACCEPTABLE RANGE:  Any valid string
DESCRIPTION:       Run each test in self-sense mode to determine the hardware 
                   configuration of the system. Write a new configuration 
                   override section into the test package file.  If the 
                   configuration name is not entered, the user will be prompted
                   for it. If the configuration name already exists, the 
                   existing configuration will be overwritten.
		   Use with /RUN to execute the tests after auto configuration.

FLAG:              /AUTOI  [snx_file]
ACCEPTABLE RANGE:  Valid SNP file name in current directory.
DESCRIPTION:       Import SNP file(s) into package file.  If used together with
                   PKG flag, will import files to the specified PKG file.  
                   Otherwise, will use the default PKG file.  If file already 
                   exists, user is given the option to override the current 
                   file or append to it. If SNP file name is specified, import 
                   only that file.  Otherwise, import all files with ".SNP" 
                   or ".SNX" extensions (for Linux), or a ".SNX" extension (for
                   Windows) in current directory.

FLAG:              /BG color
ACCEPTABLE RANGE:  "BLACK" or "WHITE"
DESCRIPTION:       Set message colors to appear correctly based on indicated 
                   background color.  Color choices will remain until /BG is 
                   run again. If /BG is never run, the default is "BLACK".

FLAG:              /DLL dll_name[cmd_line_switches]
ACCEPTABLE RANGE:  Valid dll name.  May enter arguments after dll name by
                   separating them with commas.  No spaces between arguments.
DESCRIPTION:       Dynamically loads all available functions from the
                   extension library.  Typically used for data collection in
                   the manufacturing environment.
                   Example: /DLL libcb.so.1[a,b,c,d]     --- or ---
                            /DLL libcb.so.1              (no arguments)

FLAG:              /DT [line_count]
ACCEPTABLE RANGE:  1 ... 2^30
DESCRIPTION:       Display all available tests.  If a number is specified, up 
                   to that many lines of text will display on the screen at one
                   time.

FLAG:              /FLOW [flowname] 
ACCEPTABLE RANGE:  Any valid string, Must match name of FLOW section in package
                   file.  
DESCRIPTION:       Whether running tests or displaying a list of tests, refer 
                   to the indicated "flowname" section of the package file.

FLAG:              /HE
ACCEPTABLE RANGE:  None
DESCRIPTION:       Halt on error.

FLAG:              /HELP [line_count]
ACCEPTABLE RANGE:  1 ... 2^30
DESCRIPTION:       Display help file.  If parameter is specified, display that 
                   number of lines at a time.

FLAG:              /LF [filename]
ACCEPTABLE RANGE:  Any valid file name
DESCRIPTION:       The LF flag causes the auto-creation of a log file 
                   containing all Error, Status, Info and Advisory messages.
                   If no file name is specified, the log file will be named 
                   <package filename>_<timestamp>.txt.  If a file name is 
                   specified, the log file created will have that name.
                   No change occurs to other redirection or verbose/quiet 
                   message settings.
                   
FLAG:              /MINUTES number
ACCEPTABLE RANGE:  1 ... 2^31 (unsigned long)
DESCRIPTION:       Loop on running the specified test(s) until the number of 
                   minutes specified has elapsed.

FLAG:              /N [number]
ACCEPTABLE RANGE:  0 ... 2^31 (unsigned long)
DESCRIPTION:       Number of loops.  (default: 1 loop, 0 = forever)

FLAG:              /PC [configname]
ACCEPTABLE RANGE:  Any valid string, must match configuration name in pkg file.  
DESCRIPTION:       Whether running tests or displaying a list of tests, refer 
                   to the indicated "configname" section of the package file.

FLAG:              /PKG filename
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Use the specified filename as the test package file.  
                   The default is "T.PKG".

FLAG:              /PORT port
ACCEPTABLE RANGE:  1024 ... 65535
DESCRIPTION:       This switch specifies the port to use for communication 
                   between the Test Executive and Run Engine.

FLAG:              /Q
ACCEPTABLE RANGE:  None
DESCRIPTION:       Suppress most output to screen.  Does not suppress Info and 
                   Prompt messages, as they are intended to always be viewed.

FLAG:              /QQ
ACCEPTABLE RANGE:  None
DESCRIPTION:       Suppress all output to screen, including Info and Prompt 
                   messages.

FLAG:              /RA filename
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Redirect advisories to a file in addition to the screen.

FLAG:              /RE filename
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Redirect errors to a file in addition to the screen.

FLAG:              /RI filename
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Redirect info messages to a file in addition to the screen.

FLAG:              /RP filename
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Redirect prompt messages and user responses to a file in 
                   addition to the screen.

FLAG:              /RR filename  
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Redirect all output to a file in addition to the screen.

FLAG:              /RS filename
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Redirect status to a file in addition to the screen.

FLAG:              /RT filename
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Redirect statistic messages to a file (not displayed on 
                   screen).

FLAG:              /RV filename
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Redirect verbose messages to a file in addition to screen

FLAG:              /SELF
ACCEPTABLE RANGE:  None
DESCRIPTION:       Self sense the hardware and run tests.  Similar to /AUTO but
                   does not save the result in a configuration override section
                   of the package file

FLAG:              /SF [filename]
ACCEPTABLE RANGE:  Any valid Linux filename
DESCRIPTION:       Generate a summary file of tests executed.  The default file
                   name is "SUMMARY_T.TXT". If file name is specified, the name 
                   cannot be the same as any file names used with redirect file
                   flags (RA, RE, RI, RR, RS, RT, and RV).

FLAG:              /V [maskvalue]
ACCEPTABLE RANGE:  32-bit int, can be negative
DESCRIPTION:       Maskvalue is a 32-bit value that is bitwise ANDed with the 
                   nVerboseMask parameter of any Verbose Test Library function 
                   calls the tests make.  If the result is non-zero for a 
                   particular call, the calls message is displayed.  The 
                   default maskvalue is zero.  This flag is intended for module
                   debugging purposes only.  A test developer can assign 
                   message types to each bit and use them to control tracing of
                   test logic flow.  A maskvalue of -1 will display all 
                   verbose messages in all tests.

FLAG:              /W
ACCEPTABLE RANGE:  None  
DESCRIPTION:       Do not wait for replies to user prompts.  Default values 
                   will be used instead. Intended for automated scripting.

FLAG:              /RECONFIG
ACCEPTABLE RANGE:  None  
DESCRIPTION:       Re Selfsense the hardware under specific configuration & flow. 
		   Configuration is a must to run this flag while flow is optional.
		   If the flow is not specified, the default flow will be reconfig.

FLAG:              /RUN
ACCEPTABLE RANGE:  None  
DESCRIPTION:       Execute the test after reconfig or autoconfig. This flag will 
		   only work with /RECONFIG or /AUTO.

 
8.  "T" Test Results
The results of an invocation of the Test Executive are reported several 
ways.  As each test is invoked, a line is written to the screen at the 
beginning and end of each test.  Test results are also stored cumulatively in 
a summary file whose default name is "SUMMARY_T.TXT".  The file name can be 
changed with the /SF command line argument.  In addition, for each invocation 
of the Test Executive, a volatile environment variable records the results of 
the invocation.

9.  "T" Screen Output
The format of screen output as each test is invoked is as follows:

MM-DD-YYYY HH:MM:SS [handle] STARTED module_name.test_name 
MM-DD-YYYY HH:MM:SS [handle] PASSED  module_name.test_name 
MM-DD-YYYY HH:MM:SS [handle] FAILED  module_name.test_name 

"Test Start" messages are reported in white, "Test Passed" messages are 
reported in green, "Test Failed" messages are reported in red, error messages 
are reported in red text, advisory messages are reported in cyan text, user 
prompting is displayed in yellow text, status messages are displayed in gray 
text, info messages are displayed in white text, and verbose messages are 
displayed in magenta text.  Color values can be changed by using the "BG" flag 
or manually editing the hidden ".mta" file in the same directory as the "T" 
Test Executive.

10.  "T" Summary File
The summary file is a text file that records the cumulative test results for 
all invocations of the Test Executive.  In the file is a line for each test 
that summarizes the number of passes, failures, and errors that each test has 
reported.  The format of the file is as follows:

--- Module.Subtest -----------------   Pass   Fail Errors Last Updated:
module_name.test_name                ###### ###### ###### MM-DD-YYYY HH:MM:SS

Note that the file is cumulative across Test Executive invocations, so to 
reset the counters the file must be deleted.

11.  Environment Variable
The volatile environment variable MTA_RETURN_CODE is set to "0" if all the 
tests are successful, and "1" if any tests report a failure.

12.  Return Code
T supports the following return codes:

0 - PASS condition, tests have never been manually aborted and have never failed.
1 - ABORT condition, indicates the test have been manually aborted. This return code 
    takes precedence over all other return codes. 
2 - FAIL condition, at least one error occurred and the tests were never manually aborted.
3 - INVALID condition, at least one error occurred and the tests were never started.

13.  License Key Expiration Notification Setting
T allows user to change the license key expiration notification setting through the .mta file.
There are three newly added parameters inside the .mta file that support this changes:

license_expiration_notification	     - Allows user to enable or disable the notification message.
				       "on" to enable, "off" to disable. Default is "on".           
license_expiration_notification_days - Allows user to set the remaining days to trigger the
				       notification message, default is 10.
license_expiration_notification_frequency - Allows user to set the message pop up frequency.
					    The value is in seconds. Default is 86400 = 1 day.


