Package ghidra.program.database

Class SpecExtension

java.lang.Object
ghidra.program.database.SpecExtension
public class SpecExtension extends 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:

  • <callfixup> - describing a Call Fixup
  • <callotherfixup> - describing a Callother Fixup
  • <prototype> - describing a typical Prototype Model
  • <resolveprototype> - 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 <callotherfixup> 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 Details

  • Constructor Details

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

    • getExtensionType

      public static SpecExtension.Type getExtensionType(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 List<Pair<String,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 String getCompilerSpecExtension(Program program, SpecExtension.Type type, 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 String getFormalName(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(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 Object parseExtension(String optionName, String extension, CompilerSpec cspec, boolean provideDummy) throws SAXException, XmlParseException, SleighException
      Parse an XML string and build the corresponding compiler spec extension object. Currently this can either be a
      • PrototypeModel
      • InjectPayload
      For InjectPayloadCallfixup or InjectPayloadCallother, the p-code <body> 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:
      SAXException - is there are XML format errors
      XmlParseException - if the XML document is badly formed
      SleighException - if internal p-code does not parse

    • clearAllExtensions

      protected static void clearAllExtensions(Program program, TaskMonitor monitor) throws CancelledException
      Clear all spec extension options for the given program. This is intended for internal use. ProgramDB.installExtensions() must be called at some later time to see the effect.
      Parameters:
      program - is the given Program
      monitor - is a monitor for the operation
      Throws:
      CancelledException - if something externally cancels the operation

    • testExtensionDocument

      public SpecExtension.DocInfo testExtensionDocument(String document) throws SleighException, 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
      SAXException - if there are parse errors

    • addReplaceCompilerSpecExtension

      public void addReplaceCompilerSpecExtension(String document, TaskMonitor monitor) throws LockException, SleighException, 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
      SAXException - for parse errors in the extension document
      SleighException - for a document that fails verification

    • removeCompilerSpecExtension

      public void removeCompilerSpecExtension(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