About This Document

You should also see:

About Jasmin

describes what Jasmin is, who might find it interesting, etc. Includes an example piece of code.

Jasmin Instructions

Describes the syntax of JVM instructions in Jasmin.

What is Jasmin?

Jasmin is an assembler for the Java Virtual Machine. It takes ASCII descriptions of Java classes, written in a simple assembler-like syntax using the Java Virtual Machine instruction set. It converts them into binary Java class files, suitable for loading by a Java runtime system.

Jasmin was originally created as a companion to the book "Java Virtual Machine", written by Jon Meyer and Troy Downing and published by O'Reilly Associates. The book is now out of print. Jasmin survives as a SourceForge Open Source project.

Jasmin Design

Jasmin is designed as a simple assembler. It has a clean easy-to-learn syntax with few bells and whistles. Where possible, Jasmin adopts a one-to-one mapping between its syntax and the conventions followed by Java class files. For example, package names in Jasmin are delimited with the '/' character (e.g. "java/lang/String") used by the class file format, instead of the '.' character (java.lang.String) used in the Java language.

The Jasmin assembler does little compile-time processing or checking of the input code. For example, it doesn't check that classes you reference actually exist, or that your type descriptors are well formed. Jasmin also lacks many of the feautures found in full macro assemblers. For example, it doesn't inline mathematical expressions, perform variable substitutions, or support macros.

On the other hand, using Jasmin you can quickly try out nearly all of the features of the Java Virtual Machine, including methods, fields, subroutines, exception handlers, and so on. The Jasmin syntax is also readable and compact.

Running Jasmin

The jasmin.jar file is an executable JAR file that runs Jasmin. For example:

    java -jar jasmin.jar myfile.j

    java Jasmin myfile.j

Jasmin looks at the .class directive contained in the myfile.j file to decide where to place the output class file. So if myfile.j starts with:

    .class mypackage/MyClass

then Jasmin will place the output class file "MyClass.class" in the subdirectory "mypackage" of the current directory. It will create the mypackage directory if it doesn't exist.

You can use the "-d" option to tell jasmin to place the output in an alternative directory. For example,

    java -jar jasmin.jar -d /tmp myfile.j 

will place the output in /tmp/mypackage/MyClass.class.

Finally, you can use the "-g" option to tell Jasmin to include line number information (used by debuggers) in the resulting .class file. Jasmin will number the lines in the Jasmin source file that JVM instructions appear on. Then, if an error occurs, you can see what instruction in the Jasmin source caused the error. Note that specifying "-g" causes any .line directives within the Jasmin file to be ignored.

Statements

Jasmin source files consists of a sequence of newline-separated statements. There are three types of statement:

• directives
• instructions
• labels

Directives and instructions can take parameters. These parameters are placed on the same line as the directive or instruction, separated by spaces.

Directives

Directive statements are used to give Jasmin meta-level information. Directive statements consist of a directive name, and then zero or more parameters separated by spaces, then a newline.

All directive names start with a "." character. The directives in Jasmin are:

    .catch .class .end .field .implements .interface .limit .line 
    .method .source .super .throws .var

Some example directive statements are:

    .limit stack 10

    .method public myMethod()V

    .class Foo

The parameters used by each directive are described in more detail later in the document.

Instructions

An instruction statement consists of an instruction name, zero or more parameters separated by spaces, and a newline.

Jasmin uses the standard mnemonics for JVM opcodes as instruction names. For example, aload_1, bipush and iinc are all Jasmin instruction names.

Here are some examples of instruction statements:

     ldc    "Hello World"
     iinc   1 -1
     bipush 10

Labels

    Foo:

    Label:

Label names cannot start with a numeric digit, and cannot contain any of the special characters:

   = : . " -

You cannot use directive names or instruction names as labels. Other than that, there are few restrictions on label names. For example, you could use the label:

   #_1:

Labels can only be used within method definitions. The names are local to that method.

The Jasmin Tokenizer

Jasmin tokenizes its input stream, splitting the stream into tokens by looking for whitespace characters (spaces, tabs and newlines). The tokenizer looks for:

• directive names
• instruction names
• labels
• comments
• type descriptor names
• class names
• numbers and quoted strings
• etc.

The rules used by the tokenizer are described below:

Comments

A comment is a token that starts with a ';' character, and terminates with the newline character at the end of the line.

Note that the semicolon must be preceded by a whitespace character (a space, tab, newline), i.e. embedded semicolons are ignored. For example,

   abc;def

is treated as a single token "abc;def", and

   Ljava/lang/String;

is the token "Ljava/lang/String;", whereas

   foo ; baz ding

is the token "foo" followed by a comment "baz ding".

Numbers and Strings

In Jasmin, only simple decimal and integer numeric formats are recognized. Floats in scientific or exponent format are not yet supported. Character codes and octal aren't currently supported either. This means you can have:

    1, 123, .25, 0.03, 0xA

but not

    1e-10, 'a', '\u123'

Quoted strings are also very basic. The full range of backslash escape sequences are not supported yet, although "\n" and "\t" are.

Class Names

Type Descriptors

Type information is also written as they appear in class files (e.g. the descriptor I speficies an integer, [Ljava/lang/Thread; is an array of Threads, etc.).

Methods

Method names are specified using a single token, e.g.

     java/io/PrintStream/println(Ljava/lang/String;)V

is the method called "println" in the class java.io.PrintStream, which has the type descriptor "(Ljava/lang/String;)V" (i.e. it takes a String and returns no result). In general, a method specification is formed of three parts: the characters before the last '/' form the class name. The characters between the last '/' and '(' are the method name. The rest of the string is the type descriptor for the method.

     foo/baz/Myclass/myMethod(Ljava/lang/String;)V
     ---------------         ---------------------
           |         --------         |
           |            |             |
         class        method       descriptor

As another example, you would call the Java method:

   class mypackage.MyClass {
       int foo(Object a, int b[]) { ... }
   }

using:

   invokevirtual mypackage/MyClass/foo(Ljava/lang/Object;[I)I

Fields

Field names are specified in Jasmin using two tokens, one giving the name and class of the field, the other giving its descriptor. For example:

    getstatic mypackage/MyClass/my_font   Ljava/lang/Font;

gets the value of the field called "my_font" in the class mypackage.MyClass. The type of the field is "Ljava/lang/Font;" (i.e. a Font object).

FILES

Jasmin files start by giving information on the class being defined in the file - such as the name of the class, the name of the source file that the class originated from, the name of the superclass, etc.

Typically, a Jasmin file starts with the three directives:

    .source <source-file>
    .class  <access-spec> <class-name>
    .super  <class-name>

For example, the file defining MyClass might start with the directives:

    .source MyClass.j
    .class  public MyClass
    .super  java/lang/Object

.source directive

The .source directive is optional. It specifies the value of the "SourceFile" attribute for the class file. (This is used by Java to print out debugging info if something goes wrong in one of the methods in the class). If you generated the Jasmin file automatically (e.g. as the result of compiling a file written in another syntax) you should use the .source directive to tell Java the name of the originating file. Note that the source file name should not include any pathname. Use "foo.src" but not "/home/user/foo.src".

If no .source directive is given, the name of the Jasmin file you are compiling is used instead as the SourceFile attribute instead.

.class and .super directives

The .class and .super directive tell the JVM the name of this class and its superclass. These directives take parameters as follows:

<class-name>

is the full name of the class, including any package names. For example foo/baz/MyClass.

<access-spec>

defines access permissions and other attributes for the class. This is a list of zero or more of the following keywords:

public, final, super, interface, abstract

.interface directive

Note that, instead of using the directive .class, you can alternatively use the directive .interface. This has the same syntax as the .class directive, but indicates that the Jasmin file is defining a Java interface. e.g.

    .interface public foo

.implements directive

After .source, .class and .super, you can list the interfaces that are implemented by the class you are defining, using the .implements directive. The syntax of .implements is:

    .implements <class-name>

where <class-name> has the same format as was used by .class and .super. For example:

    .class foo
    .super java/lang/Object
    .implements Edible
    .implements java/lang/Throwable

Field Definitions

After the header information, the next section of the Jasmin file is a list of field definitions.

A field is defined using the .field directive:

    .field <access-spec> <field-name> <descriptor> [ = <value> ]

where:

<access-spec>

is one of the keywords:

public, private, protected, static, final, volatile, transient

    public int foo;

    .field public foo I

    public static final float PI = 3.14;

    .field public static final PI F = 3.14

    .method <access-spec> <method-spec>
        <statements>
    .end method

   .method foo()V
       return     ; must give a return statement
   .end method

    .method abstract myAbstract()V
    .end method

    .method abstract anotherAbstract()V
        .throws java/io/IOException
    .end method

    iinc 1 -3    ; decrement local variable 1 by 3

    bipush 10    ; push the integer 10 onto the stack

    pop          ; remove the top item from the stack.