Package ghidra.program.database

Class SpecExtension

  • public class SpecExtension
extends java.lang.Object
    Utility class for installing/removing "specification extensions" to a Program. A specification extension is a program specific version of either a: - Prototype Model - Call Fixup or - Callother Fixup Normally these objects are provided by the language specific configuration files (.cspec or .pspec), but this class allows additional objects to be added that are specific to the program. Internally, each spec extension is stored as an XML document as a formal Program Option. Each type of extension is described by a specific XML tag and is parsed as it would be in a .cspec or .pspec file. The XML tags are: - \ - describing a Call Fixup - \ - describing a Callother Fixup - \ - describing a typical Prototype Model - \ - describing a Prototype Model merged from other models Each type of object has a unique name or target, which must be specified as part of the XML tag, which is referred to in this class as the extension's "formal name". In the \ tag, the formal name is given by the "targetop" attribute; for all the other tags, the formal name is given by the "name" attribute". The parent option for all extensions is given by the static field SPEC_EXTENSION. Under the parent option, each extension is stored as a string with an option name, constructed by concatenating the extension's formal name with a prefix corresponding to the extension's XML tag name. testExtensionDocument() is used independently to extensively test whether a document describes a valid extension. Extensions are installed on a program via addReplaceCompilerSpecExtension(). Extensions are removed from a program via removeCompilerSpecExtension().

    • Field Detail

      • FORMAT_VERSION_OPTIONNAME

        public static final java.lang.String FORMAT_VERSION_OPTIONNAME
        See Also:
        Constant Field Values

      • VERSION_COUNTER_OPTIONNAME

        public static final java.lang.String VERSION_COUNTER_OPTIONNAME
        See Also:
        Constant Field Values

    • Constructor Detail

      • SpecExtension

        public SpecExtension​(Program program)
        Construct an extension manager attached to a specific program. Multiple add/remove/test actions can be performed. Validator state is cached between calls.
        Parameters:
        program - is the specific Program

    • Method Detail

      • getExtensionType

        public static SpecExtension.Type getExtensionType​(java.lang.String nm,
                                                  boolean isXML)
                                           throws SleighException
        Get the extension type either from the XML tag name or the option name
        Parameters:
        nm - is the XML tag or option name
        isXML - is true for an XML tag, false for an option name
        Returns:
        the extension type
        Throws:
        SleighException - if no type matches the name

      • getVersionCounter

        public static int getVersionCounter​(Program program)
        Get version of CompilerSpec extensions stored with the Program
        Parameters:
        program - is the given Program
        Returns:
        the version number

      • getCompilerSpecExtensions

        public static java.util.List<Pair<java.lang.String,​java.lang.String>> getCompilerSpecExtensions​(Program program)
        Get all compiler spec extensions for the program. The extensions are XML documents strings, with an associated "option name" string. Return a list of (optionname,document) pairs, which may be empty
        Parameters:
        program - is the Program to get extensions for
        Returns:
        the list of (optionname,document) pairs

      • getCompilerSpecExtension

        public static java.lang.String getCompilerSpecExtension​(Program program,
                                                        SpecExtension.Type type,
                                                        java.lang.String name)
        Get the raw string making up an extension, given its type and name
        Parameters:
        program - is the program to extract the extension from
        type - is the type of extension
        name - is the formal name of the extension
        Returns:
        the extension string or null

      • checkFormatVersion

        public static void checkFormatVersion​(Program program)
                               throws VersionException
        Check the format version for spec extensions for a given program. If the program reports a version that does not match the current number attached to the running tool (FORMAT_VERSION), a VersionException is thrown
        Parameters:
        program - is the given Program
        Throws:
        VersionException - the reported version does not match the tool

      • registerOptions

        public static void registerOptions​(Program program)
        Register the options system allowing spec extensions with the given Program
        Parameters:
        program - is the given Program

      • getFormalName

        public static java.lang.String getFormalName​(java.lang.String optionName)
        Get the formal name of an extension from its option name.
        Parameters:
        optionName - is the option name
        Returns:
        the formal name

      • isValidFormalName

        public static boolean isValidFormalName​(java.lang.String formalName)
        Determine if the desired formal name is a valid identifier
        Parameters:
        formalName - is the formal name to check
        Returns:
        true if the name is valid

      • parseExtension

        public static java.lang.Object parseExtension​(java.lang.String optionName,
                                              java.lang.String extension,
                                              CompilerSpec cspec,
                                              boolean provideDummy)
                                       throws org.xml.sax.SAXException,
                                              XmlParseException,
                                              SleighException
        Parse an XML string and build the corresponding compiler spec extension object. Currently this can either be a - PrototypeModel or - InjectPayload For InjectPayloadCallfixup or InjectPayloadCallother, the p-code \ tag is also parsed, and the caller can control whether any parse errors cause an exception or whether a dummy payload is provided instead.
        Parameters:
        optionName - is the option name the extension is attached to
        extension - is the XML document as a String
        cspec - is the compiler spec the new extension is for
        provideDummy - if true, provide a dummy payload if necessary
        Returns:
        the extension object
        Throws:
        org.xml.sax.SAXException - is there are XML format errors
        XmlParseException - if the XML document is badly formed
        SleighException - if internal p-code does not parse

      • testExtensionDocument

        public SpecExtension.DocInfo testExtensionDocument​(java.lang.String document)
                                            throws SleighException,
                                                   org.xml.sax.SAXException,
                                                   XmlParseException
        Test if the given XML document describes a suitable spec extension. The document must fully parse and validate and must not conflict with the existing spec; otherwise an exception is thrown. If all tests pass, an object describing basic properties of the document is returned.
        Parameters:
        document - is the given XML document
        Returns:
        info about the document
        Throws:
        SleighException - if validity checks fail
        XmlParseException - if the XML is badly formed
        org.xml.sax.SAXException - if there are parse errors

      • addReplaceCompilerSpecExtension

        public void addReplaceCompilerSpecExtension​(java.lang.String document,
                                            TaskMonitor monitor)
                                     throws LockException,
                                            SleighException,
                                            org.xml.sax.SAXException,
                                            XmlParseException
        Install or replace a spec extension to the program. The extension is presented as an XML document, from which a name is extracted. If an extension previously existed with the same name, it is overwritten. Otherwise the document is treated as a new extension. Testing is performed before installation: - Document is parsed as XML and is verified against spec grammars - Internal p-code tags from InjectPayloads are compiled - Name collisions are checked for
        Parameters:
        document - is the XML document describing the extension
        monitor - is a task monitor
        Throws:
        LockException - if the caller does not exclusive access to the program
        XmlParseException - for a badly formed extension document
        org.xml.sax.SAXException - for parse errors in the extension document
        SleighException - for a document that fails verification

      • removeCompilerSpecExtension

        public void removeCompilerSpecExtension​(java.lang.String optionName,
                                        TaskMonitor monitor)
                                 throws LockException,
                                        CancelledException
        Remove the indicated spec extension from the program. Depending on the type, references to the extension are removed or altered first, to facilitate final removal of the extension. All changes are made in a single transaction that can be cancelled.
        Parameters:
        optionName - is the option name where the extension is stored
        monitor - is a provided monitor that can trigger cancellation
        Throws:
        LockException - if the caller does not have exclusive access to the program
        CancelledException - if the caller cancels the operation via the task monitor