Package org.spongepowered.asm.util

Class Locals

java.lang.Object
org.spongepowered.asm.util.Locals
public final class Locals extends Object
Utility methods for working with local variables using ASM

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Locals.Settings
    Settings for getLocalsAt containing the tunable options for the algorithm.
    static class 
    Locals.SyntheticLocalVariableNode
    A local variable entry added by mixin itself, eg.

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    computeFrameSize(org.objectweb.asm.tree.FrameNode frameNode, int initialFrameSize)
    Compute the size required to accomodate the entries described by the supplied frame node
    static List<org.objectweb.asm.tree.LocalVariableNode>
    generateLocalVariableTable(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method)
    Use ASM Analyzer to generate the local variable table for the specified method
    static String
    getFrameTypeName(Object frameEntry)
    Debug function to return printable name of a frame entry
    static List<org.objectweb.asm.tree.LocalVariableNode>
    getGeneratedLocalVariableTable(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method)
    Gets the generated the local variable table for the specified method.
    static org.objectweb.asm.tree.LocalVariableNode[]
    getLocalsAt(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AbstractInsnNode node, int fabricCompatibility)
    Attempts to identify available locals at an arbitrary point in the bytecode specified by node.
    static org.objectweb.asm.tree.LocalVariableNode[]
    getLocalsAt(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AbstractInsnNode node, Locals.Settings settings)
    Attempts to identify available locals at an arbitrary point in the bytecode specified by node.
    static org.objectweb.asm.tree.LocalVariableNode
    getLocalVariableAt(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AbstractInsnNode node, int var)
    Attempts to locate the appropriate entry in the local variable table for the specified local variable index at the location specified by node.
    static List<org.objectweb.asm.tree.LocalVariableNode>
    getLocalVariableTable(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method)
    Fetches or generates the local variable table for the specified method.
    static void
    loadLocals(org.objectweb.asm.Type[] locals, org.objectweb.asm.tree.InsnList insns, int pos, int limit)
    Injects appropriate LOAD opcodes into the supplied InsnList for each entry in the supplied locals array starting at pos

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • loadLocals

      public static void loadLocals(org.objectweb.asm.Type[] locals, org.objectweb.asm.tree.InsnList insns, int pos, int limit)
      Injects appropriate LOAD opcodes into the supplied InsnList for each entry in the supplied locals array starting at pos
      Parameters:
      locals - Local types (can contain nulls for uninitialised, TOP, or RETURN values in locals)
      insns - Instruction List to inject into
      pos - Start position
      limit - maximum number of locals to consume

    • getLocalsAt

      public static org.objectweb.asm.tree.LocalVariableNode[] getLocalsAt(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AbstractInsnNode node, int fabricCompatibility)

      Attempts to identify available locals at an arbitrary point in the bytecode specified by node.

      This method builds an approximate view of the locals available at an arbitrary point in the bytecode by examining the following features in the bytecode:

      • Any available stack map frames
      • STORE opcodes
      • The local variable table

      Inference proceeds by walking the bytecode from the start of the method looking for stack frames and STORE opcodes. When either of these is encountered, an attempt is made to cross-reference the values in the stack map or STORE opcode with the value in the local variable table which covers the code range. Stack map frames overwrite the entire simulated local variable table with their own value types, STORE opcodes overwrite only the local slot to which they pertain. Values in the simulated locals array are spaced according to their size (unlike the representation in FrameNode) and this TOP, NULL and UNINTITIALIZED_THIS opcodes will be represented as null values in the simulated frame.

      This code does not currently simulate the prescribed JVM behaviour where overwriting the second slot of a DOUBLE or LONG actually invalidates the DOUBLE or LONG stored in the previous location, so we have to hope (for now) that this behaviour isn't emitted by the compiler or any upstream transformers. I may have to re-think this strategy if this situation is encountered in the wild.

      Parameters:
      classNode - ClassNode containing the method, used to initialise the implicit "this" reference in simple methods with no stack frames
      method - MethodNode to explore
      node - Node indicating the position at which to determine the locals state. The locals will be enumerated UP TO the specified node, so bear in mind that if the specified node is itself a STORE opcode, then we will be looking at the state of the locals PRIOR to its invocation
      fabricCompatibility - Fabric compatibility level
      Returns:
      A sparse array containing a view (hopefully) of the locals at the specified location

    • getLocalsAt

      public static org.objectweb.asm.tree.LocalVariableNode[] getLocalsAt(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AbstractInsnNode node, Locals.Settings settings)

      Attempts to identify available locals at an arbitrary point in the bytecode specified by node.

      This method builds an approximate view of the locals available at an arbitrary point in the bytecode by examining the following features in the bytecode:

      • Any available stack map frames
      • STORE opcodes
      • The local variable table

      Inference proceeds by walking the bytecode from the start of the method looking for stack frames and STORE opcodes. When either of these is encountered, an attempt is made to cross-reference the values in the stack map or STORE opcode with the value in the local variable table which covers the code range. Stack map frames overwrite the entire simulated local variable table with their own value types, STORE opcodes overwrite only the local slot to which they pertain. Values in the simulated locals array are spaced according to their size (unlike the representation in FrameNode) and this TOP, NULL and UNINTITIALIZED_THIS opcodes will be represented as null values in the simulated frame.

      This code does not currently simulate the prescribed JVM behaviour where overwriting the second slot of a DOUBLE or LONG actually invalidates the DOUBLE or LONG stored in the previous location, so we have to hope (for now) that this behaviour isn't emitted by the compiler or any upstream transformers. I may have to re-think this strategy if this situation is encountered in the wild.

      Parameters:
      classNode - ClassNode containing the method, used to initialise the implicit "this" reference in simple methods with no stack frames
      method - MethodNode to explore
      node - Node indicating the position at which to determine the locals state. The locals will be enumerated UP TO the specified node, so bear in mind that if the specified node is itself a STORE opcode, then we will be looking at the state of the locals PRIOR to its invocation
      settings - Tunable settings for the state machine
      Returns:
      A sparse array containing a view (hopefully) of the locals at the specified location

    • getLocalVariableAt

      public static org.objectweb.asm.tree.LocalVariableNode getLocalVariableAt(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method, org.objectweb.asm.tree.AbstractInsnNode node, int var)
      Attempts to locate the appropriate entry in the local variable table for the specified local variable index at the location specified by node.
      Parameters:
      classNode - Containing class
      method - Method
      node - Instruction defining the location to get the local variable table at
      var - Local variable index
      Returns:
      a LocalVariableNode containing information about the local variable at the specified location in the specified local slot

    • getLocalVariableTable

      public static List<org.objectweb.asm.tree.LocalVariableNode> getLocalVariableTable(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method)
      Fetches or generates the local variable table for the specified method. Since Mojang strip the local variable table as part of the obfuscation process, we need to generate the local variable table when running obfuscated. We cache the generated tables so that we only need to do the relatively expensive calculation once per method we encounter.
      Parameters:
      classNode - Containing class
      method - Method
      Returns:
      local variable table

    • getGeneratedLocalVariableTable

      public static List<org.objectweb.asm.tree.LocalVariableNode> getGeneratedLocalVariableTable(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method)
      Gets the generated the local variable table for the specified method.
      Parameters:
      classNode - Containing class
      method - Method
      Returns:
      generated local variable table

    • generateLocalVariableTable

      public static List<org.objectweb.asm.tree.LocalVariableNode> generateLocalVariableTable(org.objectweb.asm.tree.ClassNode classNode, org.objectweb.asm.tree.MethodNode method)
      Use ASM Analyzer to generate the local variable table for the specified method
      Parameters:
      classNode - Containing class
      method - Method
      Returns:
      generated local variable table

    • computeFrameSize

      public static int computeFrameSize(org.objectweb.asm.tree.FrameNode frameNode, int initialFrameSize)
      Compute the size required to accomodate the entries described by the supplied frame node
      Parameters:
      frameNode - frame node with locals to compute
      initialFrameSize - Method initial frame size
      Returns:
      size of frame node locals

    • getFrameTypeName

      public static String getFrameTypeName(Object frameEntry)
      Debug function to return printable name of a frame entry
      Parameters:
      frameEntry - Frame entry
      Returns:
      string representation of the supplied frame entry