Package ghidra.program.model.lang

Class PrototypeModel

java.lang.Object
ghidra.program.model.lang.PrototypeModel
Direct Known Subclasses:
PrototypeModelError, PrototypeModelMerged
public class PrototypeModel extends Object
A function calling convention model. Formal specification of how a compiler passes arguments between functions.

  • Field Details

    • UNKNOWN_EXTRAPOP

      public static final int UNKNOWN_EXTRAPOP
      See Also:

    • name

      protected String name

    • isExtension

      protected boolean isExtension

  • Constructor Details

    • PrototypeModel

      public PrototypeModel(String name, PrototypeModel model)
      Create a named alias of another PrototypeModel. All elements of the original model are copied except: 1) The name 2) The generic calling convention (which is based on name) 3) The hasThis property (which allows __thiscall to alias something else) 4) The "fact of" the model being an alias
      Parameters:
      name - is the name of the alias
      model - is the other PrototypeModel

    • PrototypeModel

      public PrototypeModel()

  • Method Details

    • getUnaffectedList

      public Varnode[] getUnaffectedList()
      Returns:
      list of registers unaffected by called functions

    • getKilledByCallList

      public Varnode[] getKilledByCallList()
      Returns:
      list of registers definitely affected by called functions

    • getLikelyTrash

      public Varnode[] getLikelyTrash()
      Returns:
      list of registers whose input value is likely meaningless

    • getInternalStorage

      public Varnode[] getInternalStorage()
      Returns:
      list of registers used to store internal compiler constants

    • getReturnAddress

      public Varnode[] getReturnAddress()
      Returns:
      list of registers/memory used to store the return address

    • isMerged

      public boolean isMerged()
      If this returns true, it indicates this model is an artificial merge of other models. A merged model can be used as part of the analysis process when attempting to distinguish between different possible models for an unknown function.
      Returns:
      true if this model is an artificial merge of other models

    • isProgramExtension

      public boolean isProgramExtension()
      Returns:
      true if this model is a Program specific extension to the CompilerSpec

    • getName

      public String getName()
      Returns:
      the formal name of the model

    • getExtrapop

      public int getExtrapop()
      Returns the number of extra bytes popped from the stack when a function that uses this model returns to its caller. This is usually just the number of bytes used to store the return value, but some conventions may do additional clean up of stack parameters. A special value of UNKNOWN_EXTRAPOP indicates that the number of bytes is unknown.
      Returns:
      the number of extra bytes popped

    • getStackshift

      public int getStackshift()
      Returns:
      the number of bytes on the stack used, by this model, to store the return value

    • hasThisPointer

      public boolean hasThisPointer()
      Returns:
      true if this model has an implied "this" parameter for referencing class data

    • isConstructor

      public boolean isConstructor()
      Returns:
      true if this model is used specifically for class constructors

    • getInputListType

      public InputListType getInputListType()
      Returns:
      the allocation strategy for this model

    • hasInjection

      public boolean hasInjection()
      Return true if this model has specific p-code injections associated with it (either an "uponentry" or "uponreturn" payload), which are used to decompile functions with this model.
      Returns:
      true if this model uses p-code injections

    • getReturnLocation

      public VariableStorage getReturnLocation(DataType dataType, Program program)
      Get the preferred return location given the specified dataType. If the return value is passed back through a hidden input pointer, i.e. AutoParameterType.RETURN_STORAGE_PTR, this routine will not pass back the storage location of the pointer, but will typically pass back the location of the normal return register which holds a copy of the pointer.
      Parameters:
      dataType - first parameter dataType or null for an undefined type.
      program - is the Program
      Returns:
      return location or VariableStorage.UNASSIGNED_STORAGE if unable to determine suitable location

    • getNextArgLocation

      public VariableStorage getNextArgLocation(Parameter[] params, DataType dataType, Program program)
      Get the preferred parameter location for a new parameter which will appended to the end of an existing set of params. If existing parameters use custom storage, this method should not be used.
      Parameters:
      params - existing set parameters to which the next parameter will be appended. (may be null)
      dataType - dataType associated with next parameter location or null for a default undefined type.
      program - is the Program
      Returns:
      next parameter location or VariableStorage.UNASSIGNED_STORAGE if unable to determine suitable location

    • getArgLocation

      public VariableStorage getArgLocation(int argIndex, Parameter[] params, DataType dataType, Program program)
      Get the preferred parameter location for a specified index, which will be added/inserted within the set of existing function params. If existing parameters use custom storage, this method should not be used.
      Parameters:
      argIndex - is the index
      params - existing set parameters to which the parameter specified by argIndex will be added/inserted be appended (may be null).
      dataType - dataType associated with next parameter location or null for a default undefined type.
      program - is the Program
      Returns:
      parameter location or VariableStorage.UNASSIGNED_STORAGE if unable to determine suitable location

    • assignParameterStorage

      public void assignParameterStorage(PrototypePieces proto, DataTypeManager dtManager, ArrayList<ParameterPieces> res, boolean addAutoParams)
      Calculate input and output storage locations given a function prototype The data-types of the function prototype are passed in. Based on this model, a location is selected for each (input and output) parameter and passed back to the caller. The passed back storage locations are ordered with the output storage as the first entry, followed by the input storage locations. The model has the option of inserting a hidden return value pointer in the input storage locations. If the model cannot assign storage, the ParameterPieces will have a null Address.
      Parameters:
      proto - is the function prototype parameter data-types
      dtManager - is the manager used to create indirect data-types
      res - will hold the storage addresses for each parameter
      addAutoParams - is true if auto parameters (like the this pointer) should be processed

    • getStorageLocations

      public VariableStorage[] getStorageLocations(Program program, DataType[] dataTypes, boolean addAutoParams)
      Compute the variable storage for a given array of return/parameter datatypes. The first array element is the return datatype, which is followed by any input parameter datatypes in order. If addAutoParams is true, pointer datatypes will automatically be inserted for "this" or "hidden return" input parameters, if needed. In this case, the dataTypes array should not include explicit entries for these parameters. If addAutoParams is false, the dataTypes array is assumed to already contain explicit entries for any of these parameters.
      Parameters:
      program - is the Program
      dataTypes - return/parameter datatypes (first element is always the return datatype, i.e., minimum array length is 1)
      addAutoParams - true if auto-parameter storage locations can be generated
      Returns:
      dynamic storage locations orders by ordinal where first element corresponds to return storage. The returned array may also include additional auto-parameter storage locations.

    • getAliasParent

      public PrototypeModel getAliasParent()
      If this is an alias of another model, return that model. Otherwise null is returned.
      Returns:
      the parent model or null

    • isErrorPlaceholder

      public boolean isErrorPlaceholder()
      If a PrototypeModel fails to parse (from XML) a substitute model may be provided, in which case this method returns true. In all other cases this method returns false;
      Returns:
      true if this object is a substitute for a model that didn't parse

    • encode

      public void encode(Encoder encoder, PcodeInjectLibrary injectLibrary) throws IOException
      Encode this object to an output stream
      Parameters:
      encoder - is the stream encoder
      injectLibrary - is a library containing any inject payloads associated with the model
      Throws:
      IOException - for errors writing to the underlying stream

    • getInjectName

      protected String getInjectName()

    • restoreXml

      public void restoreXml(XmlPullParser parser, CompilerSpec cspec) throws XmlParseException
      Restore the model from an XML stream.
      Parameters:
      parser - is the XML parser (initialized to the start of the stream)
      cspec - is the parent compiler specification owning the model
      Throws:
      XmlParseException - is there are problems parsing the XML

    • possibleInputParamWithSlot

      public boolean possibleInputParamWithSlot(Address loc, int size, ParamList.WithSlotRec res)
      Determine if the given address range is possible input parameter storage for this model. If it is, "true" is returned, and additional information about the parameter's position is passed back in the provided record.
      Parameters:
      loc - is the starting address of the range
      size - is the size of the range in bytes
      res - is the pass-back record
      Returns:
      true if the range is a possible parameter

    • possibleOutputParamWithSlot

      public boolean possibleOutputParamWithSlot(Address loc, int size, ParamList.WithSlotRec res)
      Determine if the given address range is possible return value storage for this model. If it is, "true" is returned, and additional information about the storage position is passed back in the provided record.
      Parameters:
      loc - is the starting address of the range
      size - is the size of the range in bytes
      res - is the pass-back record
      Returns:
      true if the range is possible return value storage

    • getStackParameterAlignment

      public int getStackParameterAlignment()
      Assuming the model allows open ended storage of parameters on the stack, return the byte alignment required for individual stack parameters.
      Returns:
      the stack alignment in bytes

    • getStackParameterOffset

      public Long getStackParameterOffset()
      Return the byte offset where the first input parameter on the stack is allocated. The value is relative to the incoming stack pointer of the called function. For normal stacks, this is the offset of the first byte in the first parameter. For reverse stacks, this is the offset immediately after the last byte of the parameter.
      Returns:
      the byte offset of the first param

    • getPotentialInputRegisterStorage

      public VariableStorage[] getPotentialInputRegisterStorage(Program prog)
      Get a list of all input storage locations consisting of a single register
      Parameters:
      prog - is the current Program
      Returns:
      a VariableStorage ojbect for each register

    • isEquivalent

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

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • setReturnAddress

      protected void setReturnAddress(Varnode[] returnaddress)
      Set the return address
      Parameters:
      returnaddress - return address