Copyright (c) 2015 Intel Corp. All rights reserved. version_number=2.35.1.0001
****************************************************************************
LINUX LXMEMORY MODULE                   V2.35.1.0001               02/26/2015
****************************************************************************
1. Memory

1.1. Overview

Version:	2.35.1.0001
Released:	02/26/2015


OVERVIEW
lxMemory is a memory test module for testing system memory, L2 cache and 
SMP (multi-CPU) operations. Super user (root) access is required to lock
memory from paging and if sending data to port 80 (debug port). 

1.2. Version Notes


11/07/03 FHL Initial release, supporting memory and cache on sliding1and0,
                    random data, random dword and random mixed ops. Also support
                    SMP operation and custom stress test. 
11/18/03 FHL Post code review, serialize message sending while multi-process
                    testing. 
12/02/03 FHL Finalizing on message handling, beta release with MTA. 
12/04/03 FHL Fix semaphore issue and added heartbeat update while waiting for
                    the SEM. Also added dynamic memory size lock. 
12/19/03 FHL Change the autoconfig to set the MemorySizeMB parameter correctly
                    for Windowed Cache tests, state better advisory messages. 
01/06/04 FHL Set of resource limit for memory lock, addition of physical memory
                    address lookup when failed (require test driver). 
03/04/04 FHL Update to license version.
04/05/05 FHL Update GetCacheSize to get from param, X-release.
05/12/05 FHL Update buffer size for proc filesystem scan, fix a hang bug,
                    X-release
11/15/05 FHL Turn down the status messages due to CPU affinity and fix get CPU
                    affinity error on Debian.
07/06/06 JPS Added parameter ReservedMemoryMB.
                    Updated FreeMemory calculation to include new parameter.
01/15/07 KPT Added parameter ReservedMemoryMB can be set into multiple option 
	         64mb, 128mb & 256mb during autoconfiguration after compare to system memory.
02/22/07 KPT Update and fixed help files hm3, chm and txt.
11/04/10 HKL Added parameter MemorySizeAccuracyMB to allow memory size accuracy.
11/01/10 HKL Added Westmere CPU support.
01/10/11 HKL Changed default value for parameter ReservedMemoryMB. 
			 Added new parameter Force. Fixed 6 core CPU cache error.
02/27/11 HKL Fixed semaphore time out issue and added heartbeat while waiting for the SEM 
			 in 12Gig Ram configuration. 
04/25/11 HKL Fixed semaphore time out issue in parent process while waiting for the SEM 
			 in 12Gig Ram configuration. 
07/14/11 HKL Changed default value for parameter ReservedMemoryMB for system > 31Gig Ram. 
08/30/12 KWK Fixed Timeout issue in CrownPass and Klocwork  issue. 
11/02/12 KWK Fixed tracker on LHP and some klocwork issues. 
02/26/15 CLS Fixed Updated with x86_64 support.


1.3. Installation

INSTALLATION

lxMemory require the following files: 
	lxMemory, lxMemory.snx, lxMemory.chm(help file). 

lxMemory also depends on the following library: 
	libpthread.so.0, librt.so.1, libstdc++.so.5, libc.so.6, libts.so.0, libm.so.6, libgcc_s.so.1 


1.4. Subtests

SUBTEST 0 - AutoConfigure
SUBTEST 1 - Memory Size check 
SUBTEST 2 - CPU Count check 
SUBTEST 3 - Memory Sliding Ones and Zeroes 
SUBTEST 4 - Memory Random Data 
SUBTEST 5 - Memory Address Pattern 
SUBTEST 6 - Memory Random Mixed Ops 
SUBTEST 7 - Memory Random DWORD Ops 
SUBTEST 8 -  <Windowed> Cached Sliding Ones And Zeroes, set WindowSize for Windowed testing. 
SUBTEST 9 -  <Windowed> Cached Random Data, set WindowSize for Windowed testing. 
SUBTEST 10 - <Windowed> Cached Address Pattern, set WindowSize for Windowed testing. 
SUBTEST 11 - <Windowed> Cached Random Mixed Ops, set WindowSize for Windowed testing. 
SUBTEST 12 - <Windowed> Cached Random DWORD Ops, set WindowSize for Windowed testing. 
SUBTEST 17 - <Windowed> Cached Coherency and Conflict test, BlockSize of 64k for Coherency and 4k for Conflict test.       SUBTEST 18 - Memory to disk drive transfer 
SUBTEST 75 - Custom Memory Stress test 

1.4.1. Test 0 - AutoConfigure

Description
This test is called when Intel Modular Test Architecture executes an AutoConfigure or Recalculation command.  Its job is to detect the correct values for the MemorySizeMB, TotalMemorySizeMB, CacheSize, ReservedMemoryMB, WindowSize, BlockSize and CPUCount parameters.  


1.4.2. Test 1 - Memory Size Check

Overview
Memory Size Check detects the total system memory size in MegaBytes(MB). This
test gets the memory size data from system info API to obtain the system memory size, convert to
MB and compare it with value from parameter TotalMemorySizeMB. 

Use By Subtest
Memory Size Check

Parameters
TotalMemorySizeMB.
MemorySizeAccuracyMB.

1.4.3. Test 2 - CPU Count Check

Description
CPU Count Check detects the number of CPU(s) on system and compares it with the parameter CPUCount.

Use By Subtest
CPU Count Check

Parameters
CPUCount


1.4.4. Test 3 - Memory Sliding Ones And Zeros

Description
Memory Sliding Ones and Zeroes shifts a single one through every bit in each DWORD of available memory, then a single zero through every bit. All available memory is written before being read back. This is one of the slowest tests as each DWORD is written 64 times. Refer to IWMTA memory module for the algorithm. 

Use By Subtest
Memory Sliding Ones and Zeros

Note:
If WindowSize is set, ensure it is 2 times the CPU cache size so that the cache is refreshed at each read or write. 

Parameters
MemorySizeMB, WindowSize, TotalMemorySizeMB

1.4.5. Test 4 - Memory Random Data

Description
Memory Random Data test each DWORD of available memory with a random pattern and its complement. The random seed is taken from the process ID number or set from parameter RandomSeed. 

Use By Subtest
Memory Random Data

Parameters
MemorySizeMB, WindowSize, ReservedMemoryMB, 

1.4.6. Test 5 - Memory Address Patterns

Description
Memory Address Pattern writes every DWORD of available memory with its virtual address and its complement. 

Use By Subtest
Memory Address Patterns

Parameters
MemorySizeMB, ReservedMemoryMB, WindowSize, 


1.4.7. Test 6 - Memory Mixed Operations

Description
Memory Random Mixed Ops writes the available memory with random data and with size of random in byte, word, and double word accesses. 

Use By Subtest
Memory Mixed Operations

Note
Memory Mixed Operation test is stress test for memory, running continues looping test for SERVER BLADE PRODUCT may cause system unstable. By default this subtest is disable during autoconfugation, mannual enabling require by user.

Parameters
MemorySizeMB, WindowSize, ReservedMemoryMB, 


1.4.8. Test 7 - Memory Random Dword Operations

Description
Memory Random DWORD Operations writes, reads and compare tested memory space with random double word accesses.

Use By Subtest
Memory Random Dword Operations

Note
Memory Random Dword Operation test is stress test for memory, running continues looping test for SERVER BLADE PRODUCT may cause system unstable. By default this subtest is disable during autoconfugation, mannual enabling require by user.

Parameters
MemorySizeMB, WindowSize, ReservedMemoryMB, 


1.4.9. Test 8 - <Windowed> Cache Sliding Ones And Zeros

Description
Cache Sliding Ones and Zeroes shift a single one through every bit in each DWORD of available memory sized of CacheSize, then a single zero through every bit. All Available memory is written before being read back. If WindowSized is specified, it will allocate memory of size MemorySizeMB and repeat the algorithm by incrementing a block of size CacheSize at a time until end of allocated memory size. If SMP, each CPU is given a thread to perform the similar task using separate block of memory with sized CacheSize. This is one of the slowest tests as each DWORD is written 64 times.

Use By Subtest
Cache Sliding Ones And Zeros
Window Cache Sliding Ones And Zeros

Note: 
Maximum of 500MB is testable for Windowed Cache test.

Parameters
CacheSize and CPUCount (use in normal Cache Test)
Force, MemorySizeMB, CacheSize, CPUCount and WindowSize (use in Windowed Cache Test).


1.4.10. Test 9 - <Windowed> Cache Random Data

Description
Cache Random Data tests each DWORD of memory sized CacheSize with a random pattern and its complement. The random seed is taken from the process ID number or set from parameter RandomSeed. If WindowSized is specified, it will allocate memory of size MemorySizeMB and repeat the algorithm by incrementing a block, of sized CacheSize, each time until end of allocated memory size. If SMP, each CPU is given a thread to perform the similar task using separate block of memory with sized CacheSize. 

Use By Subtest
Cache Random Data
Window Cache Random Date

Note: 
Maximum of 500MB is testable for Windowed Cache test.

Parameters
CacheSize and CPUCount (use in normal Cache Test)
MemorySizeMB, CacheSize, CPUCount and WindowSize (use in Windowed Cache Test).


1.4.11. Test 10 - <Windowed> CacheAddress Patterns

Description
Cache Address Pattern writes every DWORD of available memory with its virtual address and its complement. If WindowSized is specified, it will allocate memory of size MemorySizeMB and repeat the algorithm by incrementing a block, of sized CacheSize, each time until end of allocated memory size. If SMP, each CPU is given a thread to perform the similar task using separate block of memory with sized CacheSize. 

Use By Subtest
Cache Address Patterns
Window Cache Address Patterns

Note: 
Maximum of 500MB is testable for Windowed Cache test.

Parameters
CacheSize and CPUCount (use in normal Cache Test)
MemorySizeMB, CacheSize, CPUCount and WindowSize (use in Windowed Cache Test).




1.4.12. Test 11 - <Windowed> Cache Mixed Operations

Description
Cache Random Mixed Ops writes the available memory with random data and with size of random in byte, word, and double word accesses. The random seed is from process ID number or from parameter RandomSeed. If WindowSized is specified, it will allocate memory of size MemorySizeMB and repeat the algorithm by incrementing a block, of sized CacheSize, each time until end of allocated memory size. If SMP, each CPU is given a thread to perform the similar task using separate block of memory with sized CacheSize. 

Use By Subtest
Cache Mixed Operations
Windows Mixed Operations

Note: 
Maximum of 500MB is testable for Windowed Cache test.

Parameters
CacheSize and CPUCount (use in normal Cache Test)
MemorySizeMB, CacheSize, CPUCount and WindowSize (use in Windowed Cache Test).


1.4.13. Test 12 - <Windowed> Cache Random Dword Operations

Description
Cache Random DWORD Operations writes, reads and compare tested memory space with random double word accesses. If WindowSized is specified, it will allocate memory of size MemorySizeMB and repeat the algorithm by incrementing a block, of sized CacheSize, each time until end of allocated memory size. If SMP, each CPU is given a thread to perform the similar task using separate block of memory with sized CacheSize.

Use By Subtest
Cache Random Dword Operations
Windows Cache Random Dword Operations

Note: 
Maximum of 500MB is testable for Windowed Cache test.

Parameters
CacheSize and CPUCount (use in normal Cache Test)
MemorySizeMB, CacheSize, CPUCount and WindowSize (use in Windowed Cache Test).


1.4.14. Test 17 - <Windowed> Cache Coherency and Conflict

Description
Cache Coherency and Conflict test writes the available memory with random data and with size of random in byte, word, and double word accesses. The random seed is from process ID number or from parameter RandomSeed. 

Coherency and Conflict test are SMP tests, it spins off multiple threads, one thread per CPU and each thread is accessing same block of memory coherently causing the multiple CPUs to do memory snoop operation on each access. Coherency test uses larger size blocksize (64k) versus the conflict test which is utilizing only 4k. Smaller access block causes more cache line conflict. 

If WindowSized is specified, it will allocate memory of size MemorySizeMB and repeat the algorithm by incrementing a block, of sized CacheSize, each time until end of allocated memory size. 

Use By Subtest
Cache Coherency
Window Cache Coherency
Cache Conflict

Note: 
Maximum of 500MB is testable for Windowed Cache test.

Parameters
CacheSize, BlockSize and CPUCount (use in normal Cache Test)
MemorySizeMB, CacheSize, CPUCount, BlockSize and WindowSize (use in Windowed Cache Test).




1.4.15. Test 18 - Memory to Disk Drive Transfer

Description
Memory to Disk Drive Transfer tests transfer of I/O device to and from all testable locations in memory. The Data pattern generated randomly and the patterns are written to disk using asynchronous I/O. Then the data is read back and checked for errors.

Use By Subtest
Memory To Device I/O Transfer 

Note: 
Maximum of 500MB is testable for Windowed Cache test.

Parameters
MemorySizeMB, WindowSize, ReservedMemoryMB,



1.4.16. Test 75 - ConfigStress.Custom

Description
Custom Memory Stress Test writes the available memory with data pattern taken from file name parameter PatternFile (for PatternType of Custom) or from parameter DataPattern (if PatternType is SimpleFill or SimpleFillToggle). Size of access can be specified to be byte (DataSize=1), word (DataSize=2), double word (DataSize=4) and quad word (DataSize=8). 

The sequence of memory access can be set using parameter AddressSequence, with a positive number for incrementing forward and negative number for decrementing backward. 

Example:
Setting AddressSequence=-2 & DataSize=4 will start at the end address and decrementing every 2 DWORD until the start address and vice versa for positive number. 

Lastly, the memory access type will be determined by parameter SubPatternType, where one can set for Read, Write, WriteRead and WriteReadCompare. It is recommended to have a WindowSize to be of Cache Size (for custom cache test) or 2 times of Cache Size (for custom memory test), this is to ensure smaller memory size is allocated for data pattern and thus maximizing the tested memory space. 

Use By Subtest
Custom Stress Test

Note:
Maximum of 500MB is testable for Threaded Custom Cache test. Custom Memory Stress test is for customize validation, hence autoconfig will by default disable this subtest, human intervention needed for customizing the parameters.

Parameters
MemorySizeMB, ReservedMemoryMB, DataSize, AddressSequence, WindowSize, PatternType, PatternFile SubPatternType,
ReadLoop, 









Debug Hints
Miscompares are a serious hardware problem.  Check for noise on the memory buses, bad cache, bad memory.

1.5. Parameters


AddressSequence
BlockSize
CacheSize
CPUCount
DataSize
DeleteFile
DriveDevice
MemorySizeMB
PatternFile
PatternType
Port80Out
RandomSeed
ReadLoop
ReservedMemoryMB
SubPatternType
TotalMemorySizeMB
WindowSize
MemorySizeAccuracyMB
Force

1.5.1. CacheSize

Description
CacheSize is used to describe the size in bytes of the L2 cache on the processor or motherboard.  This value is then used to scale the test algorithms to make sure the algorithms stays within the cache for cache-related tests.  The parameter is autoconfigured on 32-bit systems with processors that have internal L2 caches.  The value of this parameter is rounded down to the nearest power of two for testing purposes.

Example
CacheSize=0x80000	Various ways to indicate a cache size of 512KB.
CacheSize=524288



1.5.2. CPUCount

Description
This parameter holds the number of CPU (both physical and logical) installed and detected on the system.

Example
CPUCount=2	Tests for the presence of two and only two processors.


1.5.3. ReservedMemoryMB

Description
This parameter is used to specify the amount of free memory to reserve for the OS during memory testing. The amount of memory is in terms of Mega Bytes and must be a valid integer in the range of 1 to the size of free memory. The reserved memory will be able to set into multiple option value such as:
* If Current System Memory > 3GB Set ReservedMemoryMB = 256MB
* If Current System Memory > 7GB Set ReservedMemoryMB = 512MB
* If Current System Memory > 15GB Set ReservedMemoryMB = 512MB
* If Current System Memory > 31GB Set ReservedMemoryMB = 1024MB
The default and recommended value for this parameter is 50MB. Using values below the recommended default could result in test instability.



1.5.4. MemorySizeMB

Description
This parameter sets the memory size in Mega Bytes to be tested. The size must be smaller than the system available memory space, if it is set higher than the system available memory space, the system available memory space will be used instead. Look at MemFree field in /proc/meminfo for system available memory space. The MAXIMUM testable size for all the Windowed Cache Test is 500MB or half of total system memory size, but the maximum memory lockable (from paging) size could be less than 500MB. Recommend to use memory test for large memory testing or run the Windowed Cache test in parallel.

1.5.5. TotalMemorySizeMB

Description
This parameter holds the system total memory in Mega Bytes.

Used by
Memory Size Check

1.5.6. BlockSize

Description
This parameter is only use in some tests like RandomDWORD Ops, Random Mixed Ops, Cache Coherency and Cache Conflict. It specify the steps or total memory per access in bytes, it needs to be equal or smaller than the Window Size and smaller value increase the granulary of step per Window Size.

Example:
A 512k WindowSize with BlockSize of 4k will have 128 steps of memory operation per stated WindowSize. 

1.5.7. WindowSize

Description
This parameter sets the per "VIEW" memory size in bytes of the total tested memory size MemorySizeMB. Test algorithm are performed on the stated "VIEW" size and increment to the next "VIEW" until all the memory is covered. The Window Size can be same or lesser than MemorySizeMB (tested memory size), it is recommended to use Window Size same as the cache size for cache type testing and at least 2 times the cache size for memory testing to ensure the cache is refreshed (flush) after each read or write. 

When used in Cache tests, it will sets the Windowed option ON and allocation of MemorySizeMB is perform and the algorithm is repeated for each cache size limit until the MemorySizeMB is fulfill. 

1.5.8. DataSize

Description
This parameter determines the access size of each operation, whether it should be in "Bytes" (1), "Word" (2), "Double Word" (4) or "Quad Word" (8). 



1.5.9. PatternFile

Description
This parameter names the pattern file to be used to fill in the tested memory space. It is use only by "Custom" and "ThreadedCustom" test.


1.5.10. SubPatternType

Description
This parameter used by Custom Memory Stress test. Valid strings are "Read", "Write", "WriteRead" and "WriteReadCompare". This parameter determines what operation to be done on the tested memory space as per stated words.

1.5.11. PatternType

Description
This parameter used by Custom Memory Stress test. Valid strings are "SimpleFill", "SimpleFillToggle", "Custom" and "ThreadedCustom". "SimpleFill" will get the parameter DataPattern for test pattern and fills it to the memory space; "SimpleFillToggle" acts the same but it complements the data pattern before filling the memory; "Custom" gets the data pattern from a PatternFile; "ThreadedCustom" gets test data from PatternFile and do its operation coherently on all CPU. 

1.5.12. AddressSequence

Description
This parameter specify the order of memory access in the system. Positive number specify incrementing upward in memory address and a negative number specify decrementing backward in memory address starting at memory end barrier. It is specified as the number of data element to skip between accesses, where the data element size is determined by parameter DataSize. If the absolute value of this parameter exceeds half of the value in WindowSize, it will be set to the value of half of WindowSize. 

1.5.13. ReadLoop

Description
When the parameter of SubPatternType is set to "WriteRead" or "WriteReadCompare", this parameter controls the number of read or read-compare loop it must perform after each write. 

1.5.14. MemorySizeAccuracyMB

Description
Some BIOSes reserve memory for its own, and this reduces the total memory seeen by OS. This MemorySizeAccuracyMB allows user to factor in this amount so that the total memory seen by OS will be = the total memory installed.

1.5.15. Force

Description
This parameter works with the MemorySizeMB and Reserved parameters to determine how much memory to test.  If this parameter is non-zero, tests will fail if they cannot increase the process working set size by MemorySizeMB bytes and successfully lock the memory. If this parameter is zero, the tests will never allocate more than available physical memory less the Reserved amount at the time the test was invoked.


1.6. Error Codes


The first three hexadecimal digits of any Intel Modular Test Architecture error code represent a unique number assigned to the module.  The middle two digits represent the test number.  The last three digits are unique with each module and represent the message index in this list.

ERROR codes formatted as 0xMMMTTEEE 
MMM - Module number 
TT - Test number 
EEE - Error code number, as below: 

001 - Error during setting up of cleanup routine. 
002 - Error for System check, total memory size or CPU count on system
        mis-matched. 
003 - Error for data mis-compare between the write and read buffer. It will 
        display the memory virtual address and the read DWORD versus the write
        DWORD. 
004 - Error for data mis-compare for random test. It will display the memory
        virtual address and the read DWORD versus the write DWORD, and also
        the seed used for random data generation. 
005 - Error during runtime memory or resource allocation. Cause by low system
        resources available. 
006 - Main memory allocation failure. Unable to allocate the specified memory
        length for testing. 
007 - Runtime synchronizing error for multiple threads. It might due to threads
        terminate pre-maturely. 
008 - Error during initialization of cache coherency or cache conflict test. 
009 - Thread creation error, unable to spawn new threads in system. 
00A - Error during runtime branch option selection. 
00B - Initialization of Mixed Ops Log object failure. Possible cause of low
        system resources. 
00C - Error while acquiring system memory resource information. Possible due to
        unsupported kernel. 
00D - Memory to Device I/O transfer test initialize error. 
00E - Data mis-compare during Custom test while comparing the read-back buffer
        with write buffer. 
00F - Invalid Parameter specify in package file, check help file for detail
        description of parameter used. 
010 - Error while processing the Pattern File for data patterns. 
011 - Unsupported use of virtual function called during runtime. 
012 - Multiple processor test running on a single processor system. 
013 - Data mis-compare during Multi-threaded Custom test (SMP) while comparing
        the read-back buffer with write buffer. 
014 - File open error for device I/O file. 
015 - Short of data read/write during device I/O transfer, possible cause of
        bad sector on disk. 
016 - Error launching asynchronous I/O worker threads, AIO batch cannot be
        en-queue. 
017 - Transient data mis-compare detected during memory to device I/O transfer. 
018 - Data read back error detected during memory to device I/O transfer. 
019 - Memory lock failure, unalbe to lock the tested memory from swapping after
        trying to the last 1Meg. 
020 - Setting of resource limit for memory lock size failure. Try use the 
        utility "ulimit -l" from bash shell to set the limit before running 
        the test. 
021 - Initializing of driver and library for memory address translation failed,
        ensure libiommap.so is in library search path and the driver device is
        installed correctly. 
022 - Unable to close or terminate interface with test driver. Possible driver
        hang or busy. 
023 - Failed to set CPU affinity, CPU count parameter might be set wrongly or 
        one of the CPU is not detected.


	 

