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

  • 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()