FileDocCategorySizeDatePackage
DalvInsn.javaAPI DocAndroid 1.5 API13338Wed May 06 22:41:02 BST 2009com.android.dx.dex.code

DalvInsn

public abstract class DalvInsn extends Object
Base class for Dalvik instructions.

Fields Summary
private int
address
the actual output address of this instance, if known, or -1 if not
private final Dop
opcode
the opcode; one of the constants from {@link Dops}
private final com.android.dx.rop.code.SourcePosition
position
non-null; source position
private final com.android.dx.rop.code.RegisterSpecList
registers
non-null; list of register arguments
Constructors Summary
public DalvInsn(Dop opcode, com.android.dx.rop.code.SourcePosition position, com.android.dx.rop.code.RegisterSpecList registers)
Constructs an instance. The output address of this instance is initially unknown (-1).

Note: In the unlikely event that an instruction takes absolutely no registers (e.g., a nop or a no-argument no-result static method call), then the given register list may be passed as {@link RegisterSpecList#EMPTY}.

param
opcode the opcode; one of the constants from {@link Dops}
param
position non-null; source position
param
registers non-null; register list, including a result register if appropriate (that is, registers may be either ins and outs)

        if (opcode == null) {
            throw new NullPointerException("opcode == null");
        }

        if (position == null) {
            throw new NullPointerException("position == null");
        }

        if (registers == null) {
            throw new NullPointerException("registers == null");
        }

        this.address = -1;
        this.opcode = opcode;
        this.position = position;
        this.registers = registers;
Methods Summary
protected abstract java.lang.StringargString()
Gets the string form for any arguments to this instance. Subclasses must override this.

return
null-ok; the string version of any arguments or null if there are none

public abstract intcodeSize()
Gets the size of this instruction, in 16-bit code units.
return
>= 0; the code size of this instruction
public final intgetAddress()
Gets the output address of this instruction, if it is known. This throws
a RuntimeException if it has not yet been set.
see
#setAddress
return
>= 0; the output address
        if (address < 0) {
            throw new RuntimeException("address not yet known");
        }

        return address;
    
public final intgetMinimumRegisterRequirement()
Gets the minimum distinct registers required for this instruction.
This assumes that the result (if any) can share registers with the
sources (if any), that each source register is unique, and that
(to be explicit here) category-2 values take up two consecutive
registers.
return
>= 0; the minimum distinct register requirement
        boolean hasResult = hasResult();
        int regSz = registers.size();
        int resultRequirement = hasResult ? registers.get(0).getCategory() : 0;
        int sourceRequirement = 0;

        for (int i = hasResult ? 1 : 0; i < regSz; i++) {
            sourceRequirement += registers.get(i).getCategory();
        }

        return Math.max(sourceRequirement, resultRequirement);
    
public final intgetNextAddress()
Gets the address immediately after this instance. This is only
calculable if this instance's address is known, and it is equal
to the address plus the length of the instruction format of this
instance's opcode.
return
>= 0; the next address
        return getAddress() + codeSize();
    
public final DopgetOpcode()
Gets the opcode.
return
non-null; the opcode
        return opcode;
    
public final com.android.dx.rop.code.SourcePositiongetPosition()
Gets the source position.
return
non-null; the source position
        return position;
    
public final com.android.dx.rop.code.RegisterSpecListgetRegisters()
Gets the register list for this instruction.
return
non-null; the registers
        return registers;
    
public final booleanhasAddress()
Gets whether the address of this instruction is known.
see
#getAddress
see
#setAddress
        return (address >= 0);
    
public final booleanhasResult()
Returns whether this instance's opcode uses a result register.
This method is a convenient shorthand for
getOpcode().hasResult().
return
true iff this opcode uses a result register
        return opcode.hasResult();
    
public com.android.dx.dex.code.DalvInsnhrPrefix()
Gets the instruction prefix required, if any, to use in a high
register transformed version of this instance.
see
#hrVersion
return
null-ok; the prefix, if any
        RegisterSpecList regs = registers;
        int sz = regs.size();

        if (hasResult()) {
            if (sz == 1) {
                return null;
            }
            regs = regs.withoutFirst();
        } else if (sz == 0) {
            return null;
        }

        return new HighRegisterPrefix(position, regs);
    
public com.android.dx.dex.code.DalvInsnhrSuffix()
Gets the instruction suffix required, if any, to use in a high
register transformed version of this instance.
see
#hrVersion
return
null-ok; the suffix, if any
        if (hasResult()) {
            RegisterSpec r = registers.get(0);
            return makeMove(position, r, r.withReg(0));
        } else {
            return null;
        }
    
public com.android.dx.dex.code.DalvInsnhrVersion()
Gets the instruction that is equivalent to this one, except that
uses sequential registers starting at 0 (storing
the result, if any, in register 0 as well). The
sequence of instructions from {@link #hrPrefix} and {@link
#hrSuffix} (if non-null) surrounding the result of a call to
this method are the high register transformation of this
instance, and it is guaranteed that the number of low registers
used will be the number returned by {@link
#getMinimumRegisterRequirement}.
return
non-null; the replacement
        RegisterSpecList regs = 
            registers.withSequentialRegisters(0, hasResult());
        return withRegisters(regs);
    
public final java.lang.StringidentifierString()
Gets the short identifier for this instruction. This is its
address, if assigned, or its identity hashcode if not.
return
non-null; the identifier
        if (address != -1) {
            return String.format("%04x", address);
        }

        return Hex.u4(System.identityHashCode(this));
    
public final java.lang.StringlistingString(java.lang.String prefix, int width, boolean noteIndices)
Returns the string form of this instance suitable for inclusion in
a human-oriented listing dump. This method will return null
if this instance should not appear in a listing.
param
prefix non-null; prefix before the address; each follow-on
line will be indented to match as well
param
width >= 0; the width of the output or 0 for
unlimited width
param
noteIndices whether to include an explicit notation of
constant pool indices
return
null-ok; the string form or null if this
instance should not appear in a listing
        String insnPerSe = listingString0(noteIndices);

        if (insnPerSe == null) {
            return null;
        }

        String addr = prefix + identifierString() + ": ";
        int w1 = addr.length();
        int w2 = (width == 0) ? insnPerSe.length() : (width - w1);

        return TwoColumnOutput.toString(addr, w1, "", insnPerSe, w2);
    
protected abstract java.lang.StringlistingString0(boolean noteIndices)
Helper for {@link #listingString}, which returns the string
form of this instance suitable for inclusion in a
human-oriented listing dump, not including the instruction
address and without respect for any output formatting. This
method should return null if this instance should
not appear in a listing.
param
noteIndices whether to include an explicit notation of
constant pool indices
return
null-ok; the listing string
public static SimpleInsnmakeMove(com.android.dx.rop.code.SourcePosition position, com.android.dx.rop.code.RegisterSpec dest, com.android.dx.rop.code.RegisterSpec src)
Makes a move instruction, appropriate and ideal for the given arguments.
param
position non-null; source position information
param
dest non-null; destination register
param
src non-null; source register
return
non-null; an appropriately-constructed instance
        boolean category1 = dest.getCategory() == 1;
        boolean reference = dest.getType().isReference();
        int destReg = dest.getReg();
        int srcReg = src.getReg();
        Dop opcode;

        if ((srcReg | destReg) < 16) {
            opcode = reference ? Dops.MOVE_OBJECT :
                (category1 ? Dops.MOVE : Dops.MOVE_WIDE);
        } else if (destReg < 256) {
            opcode = reference ? Dops.MOVE_OBJECT_FROM16 :
                (category1 ? Dops.MOVE_FROM16 : Dops.MOVE_WIDE_FROM16);
        } else {
            opcode = reference ? Dops.MOVE_OBJECT_16 :
                (category1 ? Dops.MOVE_16 : Dops.MOVE_WIDE_16);
        }

        return new SimpleInsn(opcode, position,
                              RegisterSpecList.make(dest, src));
    
public final voidsetAddress(int address)
Sets the output address.
param
address >= 0; the output address
        if (address < 0) {
            throw new IllegalArgumentException("address < 0");
        }

        this.address = address;
    
public final java.lang.StringtoString()
{@inheritDoc}
        StringBuffer sb = new StringBuffer(100);

        sb.append(identifierString());
        sb.append(' ");
        sb.append(position);

        sb.append(": ");
        sb.append(opcode.getName());

        boolean needComma = false;
        if (registers.size() != 0) {
            sb.append(registers.toHuman(" ", ", ", null));
            needComma = true;
        }

        String extra = argString();
        if (extra != null) {
            if (needComma) {
                sb.append(',");
            }
            sb.append(' ");
            sb.append(extra);
        }

        return sb.toString();
    
public abstract com.android.dx.dex.code.DalvInsnwithOpcode(Dop opcode)
Returns an instance that is just like this one, except that its
opcode is replaced by the one given, and its address is reset.
param
opcode non-null; the new opcode
return
non-null; an appropriately-constructed instance
public abstract com.android.dx.dex.code.DalvInsnwithRegisterOffset(int delta)
Returns an instance that is just like this one, except that all
register references have been offset by the given delta, and its
address is reset.
param
delta the amount to offset register references by
return
non-null; an appropriately-constructed instance
public abstract com.android.dx.dex.code.DalvInsnwithRegisters(com.android.dx.rop.code.RegisterSpecList registers)
Returns an instance that is just like this one, except that the
register list is replaced by the given one, and its address is
reset.
param
registers non-null; new register list
return
non-null; an appropriately-constructed instance
public abstract voidwriteTo(com.android.dx.util.AnnotatedOutput out)
Writes this instance to the given output. This method should
never annotate the output.
param
out non-null; where to write to