Package ghidra.program.model.listing

# Interface StackFrame

public interface StackFrame
Definition of a stack frame. All offsets into a stack are from a zero base. Usually negative offsets are parameters and positive offsets are locals. That does not have to be the case, it depends on whether the stack grows positively or negatively. On an a 80x86 architecture, the stack grows negatively. When a value is pushed onto the stack, the stack pointer is decremented by some size.

Each frame consists of a local sections, parameter section, and save information (return address, saved registers, etc...). A frame is said to grow negative if the parameters are referenced with negative offsets from 0, or positive if the parameters are referenced with negative offsets from 0.

      Negative Growth
                        -5      local2 (2 bytes)
                        -3      local1 (4 bytes)
       frame base        0      stuff (4 bytes)
       return offset     4      return addr (4 bytes)
       param offset      8      param2 (4 bytes)
                        12      param1

      Positive Growth
                       -15     param offset 1
                       -11     param offset 2
       param offset     -8
       return offset    -7     return address
                        -3     stuff
       frame base        0     local 1
                         4     local 2
                         8

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `GROWS_NEGATIVE`
  Indicator for a Stack that grows negatively.
  `static final int`
  `GROWS_POSITIVE`
  Indicator for a Stack that grows positively.
  `static final int`
  `UNKNOWN_PARAM_OFFSET`
  Indicator for a unknown stack parameter offset

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clearVariable(int offset)`
  Clear the stack variable defined at offset
  `Variable`
  `createVariable(String name, int offset, DataType dataType, SourceType source)`
  Create a stack variable.
  `int`
  `getFrameSize()`
  Get the size of this stack frame in bytes.
  `Function`
  `getFunction()`
  Get the function that this stack belongs to.
  `Variable[]`
  `getLocals()`
  Get all defined local variables.
  `int`
  `getLocalSize()`
  Get the local portion of the stack frame in bytes.
  `int`
  `getParameterOffset()`
  Get the offset to the start of the parameters.
  `Variable[]`
  `getParameters()`
  Get all defined parameters as stack variables.
  `int`
  `getParameterSize()`
  Get the parameter portion of the stack frame in bytes.
  `int`
  `getReturnAddressOffset()`
  Get the return address stack offset.
  `Variable[]`
  `getStackVariables()`
  Get all defined stack variables.
  `Variable`
  `getVariableContaining(int offset)`
  Get the stack variable containing offset.
  `boolean`
  `growsNegative()`
  A stack that grows negative has local references negative and parameter references positive.
  `boolean`
  `isParameterOffset(int offset)`
  Returns true if specified offset could correspond to a parameter
  `void`
  `setLocalSize(int size)`
  Set the size of the local stack in bytes.
  `void`
  `setReturnAddressOffset(int offset)`
  Set the return address stack offset.

- ## Field Details

  - ### GROWS_NEGATIVE

    static final int GROWS_NEGATIVE
    Indicator for a Stack that grows negatively.
    See Also:
      - Constant Field Values

  - ### GROWS_POSITIVE

    static final int GROWS_POSITIVE
    Indicator for a Stack that grows positively.
    See Also:
      - Constant Field Values

  - ### UNKNOWN_PARAM_OFFSET

    static final int UNKNOWN_PARAM_OFFSET
    Indicator for a unknown stack parameter offset
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getFunction

    Function getFunction()
    Get the function that this stack belongs to. This could return null if the stack frame isn't part of a function.
    Returns:
      the function

  - ### getFrameSize

    int getFrameSize()
    Get the size of this stack frame in bytes.
    Returns:
      stack frame size

  - ### getLocalSize

    int getLocalSize()
    Get the local portion of the stack frame in bytes.
    Returns:
      local frame size

  - ### getParameterSize

    int getParameterSize()
    Get the parameter portion of the stack frame in bytes.
    Returns:
      parameter frame size

  - ### getParameterOffset

    int getParameterOffset()
    Get the offset to the start of the parameters.
    Returns:
      offset

  - ### isParameterOffset

    boolean isParameterOffset(int offset)
    Returns true if specified offset could correspond to a parameter
    Parameters:
      `offset` -

  - ### setLocalSize

    void setLocalSize(int size)
    Set the size of the local stack in bytes.
    Parameters:
      `size` - size of local stack

  - ### setReturnAddressOffset

    void setReturnAddressOffset(int offset)
    Set the return address stack offset.
    Parameters:
      `offset` - offset of return address.

  - ### getReturnAddressOffset

    int getReturnAddressOffset()
    Get the return address stack offset.
    Returns:
      return address offset.

  - ### getVariableContaining

    Variable getVariableContaining(int offset)
    Get the stack variable containing offset. This may fall in the middle of a defined variable.
    Parameters:
      `offset` - offset of on stack to get variable.

  - ### createVariable

    Variable createVariable(String name, int offset, DataType dataType, SourceType source) throws DuplicateNameException, InvalidInputException
    Create a stack variable. It could be a parameter or a local depending on the direction of the stack.

    WARNING! Use of this method to add parameters may force the function to use custom variable storage. In addition, parameters may be appended even if the current calling convention does not support them.

    Throws:
      `DuplicateNameException` - if another variable(parameter or local) already exists in the function with that name.
      `InvalidInputException` - if data type is not a fixed length or variable name is invalid.
      `VariableSizeException` - if data type size is too large based upon storage constraints.

  - ### clearVariable

    void clearVariable(int offset)
    Clear the stack variable defined at offset
    Parameters:
      `offset` - Offset onto the stack to be cleared.

  - ### getStackVariables

    Variable[] getStackVariables()
    Get all defined stack variables. Variables are returned from least offset (-) to greatest offset (+)
    Returns:
      an array of parameters.

  - ### getParameters

    Variable[] getParameters()
    Get all defined parameters as stack variables.
    Returns:
      an array of parameters.

  - ### getLocals

    Variable[] getLocals()
    Get all defined local variables.
    Returns:
      an array of all local variables

  - ### growsNegative

    boolean growsNegative()
    A stack that grows negative has local references negative and parameter references positive. A positive growing stack has positive locals and negative parameters.
    Returns:
      true if the stack grows in a negative direction.