Package ghidra.test.processors.support

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

      • BATCH_MODE_OUTPUT_DIR

        public static final java.lang.String BATCH_MODE_OUTPUT_DIR

      • traceDisabled

        public static boolean traceDisabled

      • processorDesignator

        protected java.lang.String processorDesignator

      • regDumpSet

        protected Register[] regDumpSet

      • floatRegSet

        protected java.util.Set<Register> floatRegSet

      • ignoredBlocks

        protected java.util.Set<java.lang.String> ignoredBlocks

    • Method Detail

      • deleteResultFilesOnStartup

        public static void deleteResultFilesOnStartup()

      • setIgnoredBlocks

        protected final void setIgnoredBlocks​(java.lang.String... blockNames)

      • getTestFailure

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

      • buildEmulatorTestSuite

        public static final junit.framework.Test buildEmulatorTestSuite​(java.lang.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,
                java.lang.String msg)

      • log

        public void log​(PCodeTestGroup testGroup,
                java.lang.String msg,
                java.lang.Throwable t)

      • setUp

        protected void setUp()
              throws java.lang.Exception
        Overrides:
        setUp in class junit.framework.TestCase
        Throws:
        java.lang.Exception

      • tearDown

        protected void tearDown()
                 throws java.lang.Exception
        Overrides:
        tearDown in class junit.framework.TestCase
        Throws:
        java.lang.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 java.lang.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

      • getProcessorDesignator

        protected java.lang.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 java.lang.String buildTestFileDesignator​(int fileIndex,
                                                   java.lang.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 java.lang.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:
        java.lang.Exception - if initialization criteria has not been satisfied

      • postImport

        protected void postImport​(Program program)
                   throws java.lang.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:
        java.lang.Exception

      • preAnalyze

        protected void preAnalyze​(Program program)
                   throws java.lang.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:
        java.lang.Exception

      • postAnalyze

        protected void postAnalyze​(Program program)
                    throws java.lang.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:
        java.lang.Exception

      • analyze

        protected void analyze​(Program program,
                       PCodeTestControlBlock testControlBlock)
                throws java.lang.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:
        java.lang.Exception

      • setAnalysisOptions

        protected void setAnalysisOptions​(Options analysisOptions)

      • getLoaderClass

        protected java.lang.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,
                                    java.lang.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()