Package ghidra.program.database
Class SpecExtension
- java.lang.Object
-
- ghidra.program.database.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().
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SpecExtension.DocInfo
Helper class for collecting information about an extension XML document and constructing its option name for storagestatic class
SpecExtension.Type
The possible types of spec extensions.
-
Field Summary
Fields Modifier and Type Field Description static int
FORMAT_VERSION
static java.lang.String
FORMAT_VERSION_OPTIONNAME
static java.lang.String
SPEC_EXTENSION
static java.lang.String
VERSION_COUNTER_OPTIONNAME
-
Constructor Summary
Constructors Constructor Description SpecExtension(Program program)
Construct an extension manager attached to a specific program.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addReplaceCompilerSpecExtension(java.lang.String document, TaskMonitor monitor)
Install or replace a spec extension to the program.static void
checkFormatVersion(Program program)
Check the format version for spec extensions for a given program.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 namestatic java.util.List<Pair<java.lang.String,java.lang.String>>
getCompilerSpecExtensions(Program program)
Get all compiler spec extensions for the program.static SpecExtension.Type
getExtensionType(java.lang.String nm, boolean isXML)
Get the extension type either from the XML tag name or the option namestatic java.lang.String
getFormalName(java.lang.String optionName)
Get the formal name of an extension from its option name.static int
getVersionCounter(Program program)
Get version of CompilerSpec extensions stored with the Programstatic boolean
isValidFormalName(java.lang.String formalName)
Determine if the desired formal name is a valid identifierstatic java.lang.Object
parseExtension(java.lang.String optionName, java.lang.String extension, CompilerSpec cspec, boolean provideDummy)
Parse an XML string and build the corresponding compiler spec extension object.static void
registerOptions(Program program)
Register the options system allowing spec extensions with the given Programvoid
removeCompilerSpecExtension(java.lang.String optionName, TaskMonitor monitor)
Remove the indicated spec extension from the program.SpecExtension.DocInfo
testExtensionDocument(java.lang.String document)
Test if the given XML document describes a suitable spec extension.
-
-
-
Field Detail
-
SPEC_EXTENSION
public static final java.lang.String SPEC_EXTENSION
- See Also:
- Constant Field Values
-
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
-
FORMAT_VERSION
public static final int FORMAT_VERSION
- 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 nameisXML
- 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 fromtype
- is the type of extensionname
- 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 toextension
- is the XML document as a Stringcspec
- is the compiler spec the new extension is forprovideDummy
- if true, provide a dummy payload if necessary- Returns:
- the extension object
- Throws:
org.xml.sax.SAXException
- is there are XML format errorsXmlParseException
- if the XML document is badly formedSleighException
- 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 failXmlParseException
- if the XML is badly formedorg.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 extensionmonitor
- is a task monitor- Throws:
LockException
- if the caller does not exclusive access to the programXmlParseException
- for a badly formed extension documentorg.xml.sax.SAXException
- for parse errors in the extension documentSleighException
- 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 storedmonitor
- is a provided monitor that can trigger cancellation- Throws:
LockException
- if the caller does not have exclusive access to the programCancelledException
- if the caller cancels the operation via the task monitor
-
-