Introduction to Assembler Tools Syntax

AsmTools introduce two formats of assembler syntax for the representation of class files: JASM and JCOD. While both formats represent a class file in it's entirety, each has strengths for representation of different facets of a class. This Chapter introduces the two formats.

A complete description of the JASM and JCOD formats can be found in Appendix A and Appendix B.

The Jasm format

The JASM format is well suited to represent semantics of byte-code instructions within the method of a class. The JASM format uses mnemonics descriptions for encoding instructions - the same mnemonic language described in Chapter 6 of the Java VM specification. The JASM format also uses a Java-like syntax for class/method/field descriptions, access_flag mask values (that are decoded into "public", "protected", etc modifiers), and indexes into the constant pool (that can optionally be replaced with the values).

For a complete description of the JASM format, see the JASM language description in Appendix A.

To illustrate the JASM format, consider a small, very familiar Java class, HelloWorld (HelloWorld.java):

public class HelloWorld {
    public static void main(String args[]) {
        System.out.println("Hello, world!");
    }
}

Now let's consider the JASM encoding of this. First, you would have to compile this class into it's object form to generate the .class file:

# Compile HelloWorld.java (to produce HelloWorld.class)
$javac HelloWorld.java

# Disassemble HelloWorld.class (to produce HelloWorld.jasm)
$java -jar asmtools.jar jdis HelloWorld.class > HelloWorld.jasm

When you open the JASM formatted disassembly (HelloWorld.jasm), you see the following:

super public class HelloWorld
        version 50:0

{


public Method  "<init>":"()V"
        stack 1 locals 1
{
                aload_0;
                invokespecial   Method java/lang/Object."<init>":"()V";
                return;
}

public static Method main:"([Ljava/lang/String;)V"
        stack 2 locals 1
{
                getstatic       Field java/lang/System.out:"Ljava/io/PrintStream;";
                ldc     String "Hello, world!";
                invokevirtual   Method java/io/PrintStream.println:"(Ljava/lang/String;)V";
                return;
}

} // end Class HelloWorld

In this listing, you can see how the syntax is a mixture of Java declarations (for describing member signatures), Strings (encoded in the format that constants are represented in the constant pool), and Java instruction mnemonics. This type of format lends itself well to create class files to test incorrect sequences of instructions.

The Jcod format

The JCOD format is well suited to represent the structure of a class file (more so than instruction sequences).

For a complete description of JCOD syntax, see Appendix B.

Let's reuse our HelloWorld example to generate a JCOD disassembly:

public class HelloWorld {
    public static void main(String args[]) {
        System.out.println("Hello, world!");
    }
}

Again, you need to compile this class into it's object form to generate the .class file and disassemble the object:

# Compile HelloWorld.java (to produce HelloWorld.class)
$javac HelloWorld.java

# Disassemble HelloWorld.class (to produce HelloWorld.jcod)
$java -jar asmtools.jar jdec HelloWorld.class > HelloWorld.jcod

When you open the JCOD formatted disassembly (HelloWorld.jcod), you see the following:

class HelloWorld {
  0xCAFEBABE;
  0; // minor version
  50; // version
  [] { // Constant Pool
    ; // first element is empty
    Method #6 #15; // #1   
    Field #16 #17; // #2   
    String #18; // #3   
    Method #19 #20; // #4   
    class #21; // #5   
    class #22; // #6   
    Utf8 "<init>"; // #7   
    Utf8 "()V"; // #8   
    Utf8 "Code"; // #9   
    Utf8 "LineNumberTable"; // #10   
    Utf8 "main"; // #11   
    Utf8 "([Ljava/lang/String;)V"; // #12   
    Utf8 "SourceFile"; // #13   
    Utf8 "HelloWorld.java"; // #14   
    NameAndType #7 #8; // #15   
    class #23; // #16   
    NameAndType #24 #25; // #17   
    Utf8 "Hello, world!"; // #18   
    class #26; // #19   
    NameAndType #27 #28; // #20   
    Utf8 "HelloWorld"; // #21   
    Utf8 "java/lang/Object"; // #22   
    Utf8 "java/lang/System"; // #23   
    Utf8 "out"; // #24   
    Utf8 "Ljava/io/PrintStream;"; // #25   
    Utf8 "java/io/PrintStream"; // #26   
    Utf8 "println"; // #27   
    Utf8 "(Ljava/lang/String;)V"; // #28   
  } // Constant Pool

  0x0021; // access
  #5;// this_cpx
  #6;// super_cpx

  [] { // Interfaces
  } // Interfaces

  [] { // fields
  } // fields

  [] { // methods
    { // Member
      0x0001; // access
      #7; // name_cpx
      #8; // sig_cpx
      [] { // Attributes
        Attr(#9) { // Code
          1; // max_stack
          1; // max_locals
          Bytes[]{
            0x2AB70001B1;
          };
          [] { // Traps
          } // end Traps
          [] { // Attributes
            Attr(#10) { // LineNumberTable
              [] { // LineNumberTable
                0  1;
              }
            } // end LineNumberTable
          } // Attributes
        } // end Code
      } // Attributes
    } // Member
    ;
    { // Member
      0x0009; // access
      #11; // name_cpx
      #12; // sig_cpx
      [] { // Attributes
        Attr(#9) { // Code
          2; // max_stack
          1; // max_locals
          Bytes[]{
            0xB200021203B60004;
            0xB1;
          };
          [] { // Traps
          } // end Traps
          [] { // Attributes
            Attr(#10) { // LineNumberTable
              [] { // LineNumberTable
                0  3;
                8  4;
              }
            } // end LineNumberTable
          } // Attributes
        } // end Code
      } // Attributes
    } // Member
  } // methods

  [] { // Attributes
    Attr(#13) { // SourceFile
      #14;
    } // end SourceFile
  } // Attributes
} // end class HelloWorld

In this listing, you can see how the syntax more directly correlates to the structure of a class file, in the same order and manner which a class file is described in Chapter 4 of the VM specification. Instructions themselves are not decoded (as they are in the JASM format), and appear as raw byte strings. Also, notice how references to the constant pool are treated as indexes (instead of being encoded as strings). As well, the constant pool is layed-out in the beginning of the listing.

Appendix A

Overview

Content Tools

ThemeBuilder

Chapter 3

Introduction to Assembler Tools Syntax

The Jasm format

The Jcod format