Package ghidra.test.processors.support

Class ProcessorEmulatorTestAdapter

java.lang.Object

junit.framework.Assert

junit.framework.TestCase

ghidra.test.processors.support.ProcessorEmulatorTestAdapter

All Implemented Interfaces:

ExecutionListener, junit.framework.Test

public abstract class ProcessorEmulatorTestAdapter
extends junit.framework.TestCase
implements ExecutionListener

ProcessorEmulatorTestAdapter provides an abstract JUnit test implementation for processor-specific test cases. All test cases which extend this class must have a class name which ends with 'EmulatorTest' and starts with the processor designator which will be used to identify associated test binaries within either the processor module's data/pcodetests/ directory or the Ghidra/Test/TestResources/data/pcodetests/ directory generally contained within the binary repository (e.g., ghidra.bin).

Within the pcodetests directory all files and folders which start with the prefix <processor-designator>_pcodetest* will be processed. All files contained within a matching subdirectory will be treated as related binaries and imported. Any *.gzf file will be imported but assumed to be pre-analyzed. Binary files to be imported and analyzed must utilize the *.out file extension.

JUnit X86EmulatorTest could utilize the following binary file naming strategy:

 pcodetests/X86_PCodeTests
 - binary1.o
 - binary2.o
 - binary3.gzf
 pcodetests/X86_PCodeTests/data (could be used for any associated files not to be imported)
 - binary3.o
 - binary3.d

 or, a single binary file could suffice:
 - pcodetests/X86_PCodeTest.out
 

Any *.out binary found will be imported and analyzed. The resulting program will be stored as a gzf in the test-output cache directory. These cached files will be used instead of a test resource binary if that binary's md5 checksum has not changed since its cached gzf was created. This use of cache files will allow the tests to run quickly on subsequent executions. If re-analysis is required, the cache will need to be cleared manually. NOTES: 1. Dummy Test Methods must be added for all known test groups. See bottom of this file. This all allows for the single test trace mode execution to work within Eclipse. 2. Trace logging disabled by default when all test groups are run (see buildEmulatorTestSuite method). Specific traceLevel and traceLog file controlled via environment properties EmuTestTraceLevel and EmuTestTraceFile. 3. The TestInfo structure must be properly maintained within the datatype archive EmuTesting.gdt and field naming consistent with use in PCodeTestControlBlock.java 4. The initializeState(EmulatorTestRunner, Program) may be overriden to initialize the register values if needed. This should be based upon symbols or other program information if possible since hardcoded constants may not track future builds of a test binaries. An attempt is made to initialize the stack pointer automatically based upon well known stack initialization symbols.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	BATCH_MODE_OUTPUT_DIR
protected CompilerSpec	compilerSpec
protected Set<Register>	floatRegSet
protected Set<String>	ignoredBlocks
protected Language	language
protected String	processorDesignator
protected Register[]	regDumpSet
static boolean	traceDisabled

Constructor Summary

Constructors

Constructor	Description
ProcessorEmulatorTestAdapter(String name, String languageID, String compilerSpecID, String[] regDumpSetNames)
ProcessorEmulatorTestAdapter(String name, String languageID, String compilerSpecID, String[] regDumpSetNames, String[] floatRegSetNames)

Method Summary

Modifier and Type	Method	Description
protected void	addIgnoredTests(String... testNames)	Add specified test names to the set of tests which should be ignored due to know issues or limitations.
protected void	analyze(Program program, PCodeTestControlBlock testControlBlock)	Invoked for non-gzf files to perform auto-analysis.
static final junit.framework.Test	buildEmulatorTestSuite(Class<?> emulatorTestClass)	Create TestSuite based upon available test groups contained within binary test files associated with target processor.
protected String	buildTestFileDesignator(int fileIndex, String filePath)	Get CUint file designator if use of A, B, C...
static void	deleteResultFilesOnStartup()
boolean	failOnDisassemblyErrors()
boolean	failOnRelocationErrors()
protected Class<? extends Loader>	getLoaderClass()	Get the loader class which should be used.
protected static final Address	getMaxDefinedMemoryAddress(Program program)	Get the maximum defined memory address ignoring any overlays which have been defined.
protected String	getPreferredStackSymbolName()	Get symbol name which defines initial stack pointer offset
protected String	getProcessorDesignator()	Get the processor designator used to identify test binary files/folder.
static junit.framework.Test	getTestFailure(Class<?> emulatorTestClass, String message, Throwable t)
Symbol	getUniqueGlobalSymbol(Program program, String name)
protected void	initializeState(EmulatorTestRunner testRunner, Program program)	Invoked for each program immediately prior to executing a test group.
void	log(PCodeTestGroup testGroup, String msg)
void	log(PCodeTestGroup testGroup, String msg, Throwable t)
void	logRead(EmulatorTestRunner testRunner, Address address, int size, byte[] values)
void	logState(EmulatorTestRunner testRunner)
void	logState(EmulatorTestRunner emulatorTestRunner, Address dumpAddr, int dumpSize, int elementSize, EmulatorTestRunner.DumpFormat elementFormat, String comment)
void	logWrite(EmulatorTestRunner testRunner, Address address, int size, byte[] values)
protected void	postAnalyze(Program program)	Invoked for non-gzf files immediately after the analyze method to perform any follow-up changes of inspection of the program.
protected void	postImport(Program program)	Invoked immediately following import allow byte processing prior to control structure identification.
protected void	preAnalyze(Program program)	Invoked prior to analysis to allow analysis options or other pre-analysis inspection/modification to be performed.
final void	runTest()	Single unit test which handles named test group specified during test instantiation.
protected void	setAnalysisOptions(Options analysisOptions)
protected final void	setIgnoredBlocks(String... blockNames)
protected void	setUp()
void	stepCompleted(EmulatorTestRunner testRunner)
protected void	tearDown()
final void	test_asm()
final void	test_BIOPS()
final void	test_BIOPS_DOUBLE()
final void	test_BIOPS_FLOAT()
final void	test_BIOPS_LONGLONG()
final void	test_BIOPS2()
final void	test_BIOPS4()
final void	test_BitManipulation()
final void	test_DecisionMaking()
final void	test_GlobalVariables()
final void	test_IterativeProcessingDoWhile()
final void	test_IterativeProcessingFor()
final void	test_IterativeProcessingWhile()
final void	test_misc()
final void	test_ParameterPassing1()
final void	test_ParameterPassing2()
final void	test_ParameterPassing3()
final void	test_PointerManipulation()
final void	test_StructUnionManipulation()

Methods inherited from class junit.framework.TestCase

assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, countTestCases, createResult, fail, fail, failNotEquals, failNotSame, failSame, format, getName, run, run, runBare, setName, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

BATCH_MODE_OUTPUT_DIR

public static final String BATCH_MODE_OUTPUT_DIR

traceDisabled

public static boolean traceDisabled

processorDesignator

protected String processorDesignator

language

protected Language language

compilerSpec

protected CompilerSpec compilerSpec

regDumpSet

protected Register[] regDumpSet

floatRegSet

protected Set<Register> floatRegSet

ignoredBlocks

protected Set<String> ignoredBlocks

Constructor Details

ProcessorEmulatorTestAdapter

public ProcessorEmulatorTestAdapter(String name,
 String languageID,
 String compilerSpecID,
 String[] regDumpSetNames)
                             throws LanguageNotFoundException,
CompilerSpecNotFoundException

Throws:

LanguageNotFoundException

CompilerSpecNotFoundException

ProcessorEmulatorTestAdapter

public ProcessorEmulatorTestAdapter(String name,
 String languageID,
 String compilerSpecID,
 String[] regDumpSetNames,
 String[] floatRegSetNames)
                             throws LanguageNotFoundException,
CompilerSpecNotFoundException

Throws:

LanguageNotFoundException

CompilerSpecNotFoundException

Method Details

deleteResultFilesOnStartup

public static void deleteResultFilesOnStartup()

setIgnoredBlocks

protected final void setIgnoredBlocks(String... blockNames)

getTestFailure

public static junit.framework.Test getTestFailure(Class<?> emulatorTestClass,
 String message,
 Throwable t)

buildEmulatorTestSuite

public static final junit.framework.Test buildEmulatorTestSuite(Class<?> emulatorTestClass)

Create TestSuite based upon available test groups contained within binary test files associated with target processor.

Parameters:

emulatorTestClass - test which extends ProcessorEmulatorTestAdapter and whose name ends with "EmulatorTest".

Returns:

test suite

log

public void log(PCodeTestGroup testGroup,
 String msg)

log

public void log(PCodeTestGroup testGroup,
 String msg,
 Throwable t)

logState

public void logState(EmulatorTestRunner testRunner)

logState

public void logState(EmulatorTestRunner emulatorTestRunner,
 Address dumpAddr,
 int dumpSize,
 int elementSize,
 EmulatorTestRunner.DumpFormat elementFormat,
 String comment)

logRead

public void logRead(EmulatorTestRunner testRunner,
 Address address,
 int size,
 byte[] values)

Specified by:

logRead in interface ExecutionListener

logWrite

public void logWrite(EmulatorTestRunner testRunner,
 Address address,
 int size,
 byte[] values)

Specified by:

logWrite in interface ExecutionListener

stepCompleted

public void stepCompleted(EmulatorTestRunner testRunner)

Specified by:

stepCompleted in interface ExecutionListener

setUp

protected void setUp()
              throws Exception

Overrides:

setUp in class junit.framework.TestCase

Throws:

Exception

tearDown

protected void tearDown()
                 throws Exception

Overrides:

tearDown in class junit.framework.TestCase

Throws:

Exception

runTest

public final void runTest()

Single unit test which handles named test group specified during test instantiation.

Overrides:

runTest in class junit.framework.TestCase

getPreferredStackSymbolName

protected String getPreferredStackSymbolName()

Get symbol name which defines initial stack pointer offset

Returns:

stack symbol or null

getMaxDefinedMemoryAddress

protected static final Address getMaxDefinedMemoryAddress(Program program)

Get the maximum defined memory address ignoring any overlays which have been defined.

Returns:

max defined physical address

addIgnoredTests

protected void addIgnoredTests(String... testNames)

Add specified test names to the set of tests which should be ignored due to know issues or limitations. The tests will still be executed, if present, however they will not be included in pass/fail counts. They will appear in log as "(IGNORED)" test result.

Parameters:

testNames - one or more test names to be ignored

getProcessorDesignator

protected String getProcessorDesignator()

Get the processor designator used to identify test binary files/folder. The default implementation requires the JUnit test class name to end with "EmulatorTest" where the portion of the name proceeding this suffix will be used as the processor designator

Returns:

processor designator

buildTestFileDesignator

protected String buildTestFileDesignator(int fileIndex,
 String filePath)

Get CUint file designator if use of A, B, C... is not suitable.

Parameters:

fileIndex - file index within sorted list

filePath - binary file path

Returns:

short file designator for use in qualified test name

initializeState

protected void initializeState(EmulatorTestRunner testRunner,
 Program program)
                        throws Exception

Invoked for each program immediately prior to executing a test group. By default this method will initialize the register states based upon the specific register values/context stored at the test group function entry point. Such register values may have been established via the processor specification, loader or analyzers. A specific test may override or extend this behavior for other registers as needed.

Parameters:

testRunner - emulator group test runner/facilitator

program -

Throws:

Exception - if initialization criteria has not been satisfied

postImport

protected void postImport(Program program)
                   throws Exception

Invoked immediately following import allow byte processing prior to control structure identification. NOTE: This method will only be invoked once during the first test setup for all test binaries found. This method will not be invoked during subsequent tests since the analyzed program will be cached.

Parameters:

program -

Throws:

Exception

preAnalyze

protected void preAnalyze(Program program)
                   throws Exception

Invoked prior to analysis to allow analysis options or other pre-analysis inspection/modification to be performed. NOTE: This method will only be invoked once during the first test setup for all test binaries found. This method will not be invoked during subsequent tests since the analyzed program will be cached.

Parameters:

program -

Throws:

Exception

postAnalyze

protected void postAnalyze(Program program)
                    throws Exception

Invoked for non-gzf files immediately after the analyze method to perform any follow-up changes of inspection of the program. NOTE: This method will only be invoked once during the first test setup for all test binaries found. This method will not be invoked during subsequent tests since the analyzed program will be cached.

Parameters:

program -

Throws:

Exception

analyze

protected void analyze(Program program,
 PCodeTestControlBlock testControlBlock)
                throws Exception

Invoked for non-gzf files to perform auto-analysis. NOTE: This method will only be invoked once during the first test setup for all test binaries found. This method will not be invoked during subsequent tests since the analyzed program will be cached.

Parameters:

program -

Throws:

Exception

setAnalysisOptions

protected void setAnalysisOptions(Options analysisOptions)

getLoaderClass

protected Class<? extends Loader> getLoaderClass()

Get the loader class which should be used. A null value should be return to use the preferred loader.

Returns:

loader class or null

failOnDisassemblyErrors

public boolean failOnDisassemblyErrors()

Returns:

true if test run should fail up-front if binary contains disassembly errors

failOnRelocationErrors

public boolean failOnRelocationErrors()

Returns:

true if test run should fail up-front if binary contains relocation errors

getUniqueGlobalSymbol

public Symbol getUniqueGlobalSymbol(Program program,
 String name)

test_asm

public final void test_asm()

test_BIOPS_DOUBLE

public final void test_BIOPS_DOUBLE()

test_BIOPS_FLOAT

public final void test_BIOPS_FLOAT()

test_BIOPS_LONGLONG

public final void test_BIOPS_LONGLONG()

test_BIOPS

public final void test_BIOPS()

test_BIOPS2

public final void test_BIOPS2()

test_BIOPS4

public final void test_BIOPS4()

test_BitManipulation

public final void test_BitManipulation()

test_DecisionMaking

public final void test_DecisionMaking()

test_GlobalVariables

public final void test_GlobalVariables()

test_IterativeProcessingDoWhile

public final void test_IterativeProcessingDoWhile()

test_IterativeProcessingFor

public final void test_IterativeProcessingFor()

test_IterativeProcessingWhile

public final void test_IterativeProcessingWhile()

test_misc

public final void test_misc()

test_ParameterPassing1

public final void test_ParameterPassing1()

test_ParameterPassing2

public final void test_ParameterPassing2()

test_ParameterPassing3

public final void test_ParameterPassing3()

test_PointerManipulation

public final void test_PointerManipulation()

test_StructUnionManipulation

public final void test_StructUnionManipulation()