com.android.dx.cf.code

Interface Machine

All Known Implementing Classes:

BaseMachine, ValueAwareMachine

public interface Machine

Interface for machines capable of executing bytecode by acting upon a Frame. A machine conceptually contains four arbitrary-value argument slots, slots for several literal-value arguments, and slots for branch target information.

Method Summary

Modifier and Type	Method and Description
void	auxCstArg(Constant cst) Indicates that there is an auxiliary (inline, not stack) object argument, with the value based on the given constant.
void	auxInitValues(ArrayList<Constant> initValues) Indicates that there is an auxiliary (inline, not stack) argument consisting of a list of initial values for a newly created array.
void	auxIntArg(int value) Indicates that there is an auxiliary (inline, not stack) argument of type int, with the given value.
void	auxSwitchArg(SwitchList cases) Indicates that there is an auxiliary (inline, not stack) argument consisting of a switch* table.
void	auxTargetArg(int target) Indicates that there is an auxiliary (inline, not stack) argument indicating a branch target.
void	auxType(Type type) Indicates that the salient type of this operation is as given.
void	clearArgs() Clears the regular and auxiliary arguments area.
Prototype	getPrototype() Gets the effective prototype of the method that this instance is being used for.
void	localArg(Frame frame, int idx) Loads the local variable with the given index as the sole argument in the arguments area.
void	localInfo(boolean local) Used to specify if a loaded local variable has info in the local variable table.
void	localTarget(int idx, Type type, LocalItem local) Indicates that the target of this operation is the given local.
void	popArgs(Frame frame, int count) Pops the given number of values from the stack (of either category), and store them in the arguments area, indicating that there are now that many arguments.
void	popArgs(Frame frame, Prototype prototype) Pops values from the stack of the types indicated by the given Prototype (popped in reverse of the argument order, so the first prototype argument type is for the deepest element of the stack), and store them in the arguments area, indicating that there are now that many arguments.
void	popArgs(Frame frame, Type type) Pops a value from the stack of the indicated type, and store it in the arguments area, indicating that there are now that many arguments.
void	popArgs(Frame frame, Type type1, Type type2) Pops values from the stack of the indicated types (popped in reverse argument order, so the first indicated type is for the deepest element of the stack), and store them in the arguments area, indicating that there are now that many arguments.
void	popArgs(Frame frame, Type type1, Type type2, Type type3) Pops values from the stack of the indicated types (popped in reverse argument order, so the first indicated type is for the deepest element of the stack), and store them in the arguments area, indicating that there are now that many arguments.
void	run(Frame frame, int offset, int opcode) "Runs" the indicated opcode in an appropriate way, using the arguments area as appropriate, and modifying the given frame in response.

Method Detail

getPrototype

Prototype getPrototype()

Gets the effective prototype of the method that this instance is being used for. The effective prototype includes an initial this argument for instance methods.

Returns:

non-null; the method prototype

clearArgs

void clearArgs()

Clears the regular and auxiliary arguments area.

popArgs

void popArgs(Frame frame,
             int count)

Pops the given number of values from the stack (of either category), and store them in the arguments area, indicating that there are now that many arguments. Also, clear the auxiliary arguments.

Parameters:

frame - non-null; frame to operate on

count - >= 0; number of values to pop

popArgs

void popArgs(Frame frame,
             Prototype prototype)

Pops values from the stack of the types indicated by the given Prototype (popped in reverse of the argument order, so the first prototype argument type is for the deepest element of the stack), and store them in the arguments area, indicating that there are now that many arguments. Also, clear the auxiliary arguments.

Parameters:

frame - non-null; frame to operate on

prototype - non-null; prototype indicating arguments to pop

popArgs

void popArgs(Frame frame,
             Type type)

Pops a value from the stack of the indicated type, and store it in the arguments area, indicating that there are now that many arguments. Also, clear the auxiliary arguments.

Parameters:

frame - non-null; frame to operate on

type - non-null; type of the argument

popArgs

void popArgs(Frame frame,
             Type type1,
             Type type2)

Pops values from the stack of the indicated types (popped in reverse argument order, so the first indicated type is for the deepest element of the stack), and store them in the arguments area, indicating that there are now that many arguments. Also, clear the auxiliary arguments.

Parameters:

frame - non-null; frame to operate on

type1 - non-null; type of the first argument

type2 - non-null; type of the second argument

popArgs

void popArgs(Frame frame,
             Type type1,
             Type type2,
             Type type3)

Pops values from the stack of the indicated types (popped in reverse argument order, so the first indicated type is for the deepest element of the stack), and store them in the arguments area, indicating that there are now that many arguments. Also, clear the auxiliary arguments.

Parameters:

frame - non-null; frame to operate on

type1 - non-null; type of the first argument

type2 - non-null; type of the second argument

type3 - non-null; type of the third argument

localArg

void localArg(Frame frame,
              int idx)

Loads the local variable with the given index as the sole argument in the arguments area. Also, clear the auxiliary arguments.

Parameters:

frame - non-null; frame to operate on

idx - >= 0; the local variable index

localInfo

void localInfo(boolean local)

Used to specify if a loaded local variable has info in the local variable table.

Parameters:

local - true if local arg has info in local variable table

auxType

void auxType(Type type)

Indicates that the salient type of this operation is as given. This differentiates between, for example, the various arithmetic opcodes, which, by the time they hit a Machine are collapsed to the int variant. (See BytecodeArray.parseInstruction(int, com.android.dx.cf.code.BytecodeArray.Visitor) for details.)

Parameters:

type - non-null; the salient type of the upcoming operation

auxIntArg

void auxIntArg(int value)

Indicates that there is an auxiliary (inline, not stack) argument of type int, with the given value.

Note: Perhaps unintuitively, the stack manipulation ops (e.g., dup and swap) use this to indicate the result stack pattern with a straightforward hex encoding of the push order starting with least-significant nibbles getting pushed first). For example, an all-category-1 dup2_x1 sets this to 0x12312, and the other form of that op sets this to 0x121.

Also Note: For switch* instructions, this is used to indicate the padding value (which is only useful for verification).

Parameters:

value - the argument value

auxCstArg

void auxCstArg(Constant cst)

Indicates that there is an auxiliary (inline, not stack) object argument, with the value based on the given constant.

Note: Some opcodes use both int and constant auxiliary arguments.

Parameters:

cst - non-null; the constant containing / referencing the value

auxTargetArg

void auxTargetArg(int target)

Indicates that there is an auxiliary (inline, not stack) argument indicating a branch target.

Parameters:

target - the argument value

auxSwitchArg

void auxSwitchArg(SwitchList cases)

Indicates that there is an auxiliary (inline, not stack) argument consisting of a switch* table.

Note: This is generally used in conjunction with auxIntArg(int) (which holds the padding).

Parameters:

cases - non-null; the list of key-target pairs, plus the default target

auxInitValues

void auxInitValues(ArrayList<Constant> initValues)

Indicates that there is an auxiliary (inline, not stack) argument consisting of a list of initial values for a newly created array.

Parameters:

initValues - non-null; the list of constant values to initialize the array

localTarget

void localTarget(int idx,
                 Type type,
                 LocalItem local)

Indicates that the target of this operation is the given local.

Parameters:

idx - >= 0; the local variable index

type - non-null; the type of the local

local - null-ok; the name and signature of the local, if known

run

void run(Frame frame,
         int offset,
         int opcode)

"Runs" the indicated opcode in an appropriate way, using the arguments area as appropriate, and modifying the given frame in response.

Parameters:

frame - non-null; frame to operate on

offset - >= 0; byte offset in the method to the opcode being run

opcode - >= 0; the opcode to run