Package ghidra.program.model.lang

# Interface CompilerSpec

All Known Implementing Classes:
  `BasicCompilerSpec`, `ProgramCompilerSpec`

public interface CompilerSpec
Interface for requesting specific information about the compiler used to build a Program being analyzed. Major elements that can be queried include: - AddressSpaces from the Language plus compiler specific ones like "stack" - DataOrganization describing size and alignment of primitive data-types: int, long, pointers, etc. - PrototypeModels describing calling conventions used by the compiler: __stdcall, __thiscall, etc. - InjectPayloads or p-code that can used for - Call-fixups, substituting p-code for compiler bookkeeping functions during analysis. - Callother-fixups, substituting p-code for user-defined p-code operations. - Memory ranges that the compiler treats as global - Context and register values known to the compiler over specific memory ranges

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `CompilerSpec.EvaluationModelType`
  Labels for PrototypeModels that are used by default for various analysis/evaluation use-cases, when the true model isn't known.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `CALLING_CONVENTION_cdecl`
  `static final String`
  `CALLING_CONVENTION_default`
  `static final String`
  `CALLING_CONVENTION_fastcall`
  `static final String`
  `CALLING_CONVENTION_pascal`
  `static final String`
  `CALLING_CONVENTION_rustcall`
  `static final String`
  `CALLING_CONVENTION_stdcall`
  `static final String`
  `CALLING_CONVENTION_thiscall`
  `static final String`
  `CALLING_CONVENTION_unknown`
  `static final String`
  `CALLING_CONVENTION_vectorcall`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `applyContextSettings(DefaultProgramContext ctx)`
  Apply context settings to the ProgramContext as specified by the configuration
  `boolean`
  `doesCDataTypeConversions()`
  Return true if function prototypes respect the C-language data-type conversion conventions.
  `void`
  `encode(Encoder encoder)`
  Encode this entire specification to a stream.
  `PrototypeModel`
  `findBestCallingConvention(Parameter[] params)`
  Find the best guess at a calling convention model from this compiler spec given an ordered list of (potential) parameters with storage assignments.
  `AddressSpace`
  `getAddressSpace(String spaceName)`
  Get an address space by name.
  `PrototypeModel[]`
  `getAllModels()`
  `PrototypeModel`
  `getCallingConvention(String name)`
  Returns the Calling Convention Model with the given name.
  `PrototypeModel[]`
  `getCallingConventions()`
  `CompilerSpecDescription`
  `getCompilerSpecDescription()`
  `CompilerSpecID`
  `getCompilerSpecID()`
  `DataOrganization`
  `getDataOrganization()`
  `DecompilerLanguage`
  `getDecompilerOutputLanguage()`
  Get the language that the decompiler produces
  `PrototypeModel`
  `getDefaultCallingConvention()`
  Returns the prototype model that is the default calling convention or else null.
  `Language`
  `getLanguage()`
  Get the Language this compiler spec is based on.
  `PcodeInjectLibrary`
  `getPcodeInjectLibrary()`
  `String`
  `getProperty(String key)`
  Gets a property defined for this language, or null if that property isn't defined.
  `String`
  `getProperty(String key, String defaultString)`
  Gets the value of a property as a String, returning defaultString if undefined.
  `boolean`
  `getPropertyAsBoolean(String key, boolean defaultBoolean)`
  Gets the value of a property as a boolean, returning defaultBoolean if undefined.
  `int`
  `getPropertyAsInt(String key, int defaultInt)`
  Gets the value of a property as an int, returning defaultInt if undefined.
  `Set<String>`
  `getPropertyKeys()`
  Returns a read-only set view of the property keys defined on this language.
  `PrototypeModel`
  `getPrototypeEvaluationModel(CompilerSpec.EvaluationModelType modelType)`
  Get the evaluation model matching the given type.
  `AddressSpace`
  `getStackBaseSpace()`
  Get the physical space used for stack data storage
  `Register`
  `getStackPointer()`
  Get the default Stack Pointer register for this language if there is one.
  `AddressSpace`
  `getStackSpace()`
  Get the stack address space defined by this specification
  `boolean`
  `hasProperty(String key)`
  Returns whether this language has a property defined.
  `boolean`
  `isEquivalent(CompilerSpec obj)`
  Determine if this CompilerSpec is equivalent to another specified instance
  `boolean`
  `isGlobal(Address addr)`
  `boolean`
  `isStackRightJustified()`
  Indicates whether variables are right-justified within the stack alignment.
  `static boolean`
  `isUnknownCallingConvention(String callingConventionName)`
  Determine if the specified calling convention name is treated as the unknown calling convention (blank or {code "unknown"}).
  `PrototypeModel`
  `matchConvention(String conventionName)`
  Get the PrototypeModel which corresponds to the given calling convention name.
  `boolean`
  `stackGrowsNegative()`

- ## Field Details

  - ### CALLING_CONVENTION_unknown

    static final String CALLING_CONVENTION_unknown
    See Also:
      - Constant Field Values

  - ### CALLING_CONVENTION_default

    static final String CALLING_CONVENTION_default
    See Also:
      - Constant Field Values

  - ### CALLING_CONVENTION_cdecl

    static final String CALLING_CONVENTION_cdecl
    See Also:
      - Constant Field Values

  - ### CALLING_CONVENTION_pascal

    static final String CALLING_CONVENTION_pascal
    See Also:
      - Constant Field Values

  - ### CALLING_CONVENTION_thiscall

    static final String CALLING_CONVENTION_thiscall
    See Also:
      - Constant Field Values

  - ### CALLING_CONVENTION_stdcall

    static final String CALLING_CONVENTION_stdcall
    See Also:
      - Constant Field Values

  - ### CALLING_CONVENTION_fastcall

    static final String CALLING_CONVENTION_fastcall
    See Also:
      - Constant Field Values

  - ### CALLING_CONVENTION_vectorcall

    static final String CALLING_CONVENTION_vectorcall
    See Also:
      - Constant Field Values

  - ### CALLING_CONVENTION_rustcall

    static final String CALLING_CONVENTION_rustcall
    See Also:
      - Constant Field Values

- ## Method Details

  - ### isUnknownCallingConvention

    static boolean isUnknownCallingConvention(String callingConventionName)
    Determine if the specified calling convention name is treated as the unknown calling convention (blank or {code "unknown"}). Other unrecognized names will return false. This static method does not assume any specific compiler specification.
    Parameters:
      `callingConventionName` - calling convention name or null
    Returns:
      true if specified name is blank or {code "unknown"}

  - ### getLanguage

    Language getLanguage()
    Get the Language this compiler spec is based on. Note that compiler specs may be reused across multiple languages in the cspec files on disk, but once loaded in memory are actually separate objects. (M:N on disk, 1:N in memory)
    Returns:
      the language this compiler spec is based on

  - ### getCompilerSpecDescription

    CompilerSpecDescription getCompilerSpecDescription()
    Returns:
      a brief description of the compiler spec

  - ### getCompilerSpecID

    CompilerSpecID getCompilerSpecID()
    Returns:
      the id string associated with this compiler spec;

  - ### getStackPointer

    Register getStackPointer()
    Get the default Stack Pointer register for this language if there is one.
    Returns:
      default stack pointer register.

  - ### isStackRightJustified

    boolean isStackRightJustified()
    Indicates whether variables are right-justified within the stack alignment.
    Returns:
      true if right stack justification applies.

  - ### getAddressSpace

    AddressSpace getAddressSpace(String spaceName)
    Get an address space by name. This can be value added over the normal AddressFactory.getAddressSpace routine because the compiler spec can refer to special internal spaces like the stack space
    Parameters:
      `spaceName` - is the name of the address space
    Returns:
      the corresponding AddressSpace object

  - ### getStackSpace

    AddressSpace getStackSpace()
    Get the stack address space defined by this specification
    Returns:
      stack address space

  - ### getStackBaseSpace

    AddressSpace getStackBaseSpace()
    Get the physical space used for stack data storage
    Returns:
      address space which contains the stack

  - ### stackGrowsNegative

    boolean stackGrowsNegative()
    Returns:
      true if the stack grows with negative offsets

  - ### applyContextSettings

    void applyContextSettings(DefaultProgramContext ctx)
    Apply context settings to the ProgramContext as specified by the configuration
    Parameters:
      `ctx` - is the ProgramContext

  - ### getCallingConventions

    PrototypeModel[] getCallingConventions()
    Returns:
      an array of the prototype models. Each prototype model specifies a calling convention.

  - ### getCallingConvention

    PrototypeModel getCallingConvention(String name)
    Returns the Calling Convention Model with the given name.
    Parameters:
      `name` - the name of the calling convention to retrieve
    Returns:
      the calling convention with the given name or null if there is none with that name.

  - ### getAllModels

    PrototypeModel[] getAllModels()
    Returns:
      all possible PrototypeModels, including calling conventions and merge models

  - ### getDefaultCallingConvention

    PrototypeModel getDefaultCallingConvention()
    Returns the prototype model that is the default calling convention or else null.
    Returns:
      the default calling convention or null.

  - ### getDecompilerOutputLanguage

    DecompilerLanguage getDecompilerOutputLanguage()
    Get the language that the decompiler produces
    Returns:
      an enum specifying the language

  - ### getPrototypeEvaluationModel

    PrototypeModel getPrototypeEvaluationModel(CompilerSpec.EvaluationModelType modelType)
    Get the evaluation model matching the given type. If analysis needs to apply a PrototypeModel to a function but a specific model is not known, then this method can be used to select a putative PrototypeModel based on the analysis use-case: - EVAL_CURRENT indicates the model to use for the "current function" being analyzed - EVAL_CALLED indicates the model to use for a function called by the current function
    Parameters:
      `modelType` - is the type of evaluation model
    Returns:
      prototype evaluation model

  - ### isGlobal

    boolean isGlobal(Address addr)
    Parameters:
      `addr` - is the (start of the) storage location
    Returns:
      true if the specified storage location has been designated "global" in scope

  - ### getDataOrganization

    DataOrganization getDataOrganization()

  - ### getPcodeInjectLibrary

    PcodeInjectLibrary getPcodeInjectLibrary()

  - ### matchConvention

    PrototypeModel matchConvention(String conventionName)
    Get the PrototypeModel which corresponds to the given calling convention name. If no match is found the default prototype model is returned.
    Parameters:
      `conventionName` - calling convention name.
    Returns:
      the matching model or the defaultModel if nothing matches

  - ### findBestCallingConvention

    PrototypeModel findBestCallingConvention(Parameter[] params)
    Find the best guess at a calling convention model from this compiler spec given an ordered list of (potential) parameters with storage assignments.
    Parameters:
      `params` - is the ordered list of parameters
    Returns:
      prototype model corresponding to the specified function signature

  - ### hasProperty

    boolean hasProperty(String key)
    Returns whether this language has a property defined.
    Parameters:
      `key` - the property key
    Returns:
      if the property is defined

  - ### doesCDataTypeConversions

    boolean doesCDataTypeConversions()
    Return true if function prototypes respect the C-language data-type conversion conventions. This amounts to converting array data-types to pointer-to-element data-types. In C, arrays are passed by reference (structures are still passed by value)
    Returns:
      if the prototype does C-language data-type conversions

  - ### getPropertyAsInt

    int getPropertyAsInt(String key, int defaultInt)
    Gets the value of a property as an int, returning defaultInt if undefined.
    Parameters:
      `key` - the property key
      `defaultInt` - the default value to return if property is undefined
    Returns:
      the property value as an int, or the default value if undefined

  - ### getPropertyAsBoolean

    boolean getPropertyAsBoolean(String key, boolean defaultBoolean)
    Gets the value of a property as a boolean, returning defaultBoolean if undefined.
    Parameters:
      `key` - the property key
      `defaultBoolean` - the default value to return if property is undefined
    Returns:
      the property value as a boolean, or the default value if undefined

  - ### getProperty

    String getProperty(String key, String defaultString)
    Gets the value of a property as a String, returning defaultString if undefined.
    Parameters:
      `key` - the property key
      `defaultString` - the default value to return if property is undefined
    Returns:
      the property value as a String, or the default value if undefined

  - ### getProperty

    String getProperty(String key)
    Gets a property defined for this language, or null if that property isn't defined.
    Parameters:
      `key` - the property key
    Returns:
      the property value, or null if not defined

  - ### getPropertyKeys

    Set<String> getPropertyKeys()
    Returns a read-only set view of the property keys defined on this language.
    Returns:
      read-only set of property keys

  - ### encode

    void encode(Encoder encoder) throws IOException
    Encode this entire specification to a stream. A document is written with root element `<compiler_spec>`.
    Parameters:
      `encoder` - is the stream encoder
    Throws:
      `IOException` - for errors writing to the underlying stream

  - ### isEquivalent

    boolean isEquivalent(CompilerSpec obj)
    Determine if this CompilerSpec is equivalent to another specified instance
    Parameters:
      `obj` - is the other instance
    Returns:
      true if they are equivalent