Introduction

This chapter describes the code assembly process in general, introduces the AsmTools, its features, characteristics, requirements and contains the following sections:

AsmTools are a set of utilities used for the creation and deconstruction of Java class files. They can be used for creating class files to test a VM. They can also be used to synthesize class files that can not be constructed by normal means (such as class files constructed by a compiler).

The AsmTools introduce two formats of the human readable representation of the class file: JASM and JCOD. The AsmTools also contain tools to translate a class file into a text representation (JASM or JCOD format), and conversly to convert these text representations into the binary class file form.  A JASM (or Java Assembler) file syntax is something like a hybrid of a java file and assembler code (based on the mnemonics descriptions from the VM Spec Chapter 6). A JCOD (or Java Code) file is a low level text representation of the class file structure with dedicated class items (such as magic, minor_version, major_version, constant_pool, Interfaces, Fields etc). Instruction sequences are not represented in JCOD format.

JASM and JCOD files are regular text files and they can be viewed and modified with your favorite text editor. The process of creating a desired class file with AsmTools consists of obtaining a corresponding JASM or JCOD file and further compiling it with the jasm or jcoder utility.

Other Asmtools utilities (jdis, jdec, jcdec) disassemble/decode class files into their text representation. They can be used for the analysis of the class file as well as for creating an assembler source from a class file (for further modification and compilation back to a class file).

The AsmTools include the following functionality:

• Support for all Java platforms, including the Java Platform, Standard Edition (Java SE), the Java Platform, Micro Edition (Java ME), (CDC and CLDC), and the Java Card 3.0 platform

• The ability to produce valid and invalid class files.

• The ability to produce valid class files that can not be produced by a compiler.

• Support for disassembling class files into text representations in assembler formats.

• The JASM and JCOD syntax closely follow the language of the class file specifications in the VM Spec.

Introduction to class file assembly

Class file assembly and dissassembly is closely tied to how a VM specifies a class file, instruction sequencing, and typical compiler behavior.  For one to understand how to synthesize a class file using assembler syntax, one must first understand the structure of the class file format.

This section introduces the class file format, and describes the domain and scope of Asm Tools.

Introduction to the class file format

The Java virtual machine knows nothing of the Java programming language, only of a particular binary format, the class file format. A class file contains Java virtual machine instructions (or bytecodes) and a symbol table, as well as other ancillary information. A class file consists of a stream of 8-bit bytes (u1). All 16-bit (u2), 32-bit (u4), and 64-bit (u8) quantities are constructed by reading in two, four, and eight consecutive 8-bit bytes, respectively.

FIGURE 1-1   Basic class file format

ClassFile {
    u4 magic;
    u2 minor_version;
    u2 major_version;
    u2 constant_pool_count;
    cp_info constant_pool[constant_pool_count-1];
    u2 access_flags;
    u2 this_class;
    u2 super_class;
    u2 interfaces_count;
    u2 interfaces[interfaces_count];
    u2 fields_count;
    field_info fields[fields_count];
    u2 methods_count;
    method_info methods[methods_count];
    u2 attributes_count;
    attribute_info attributes[attributes_count];
}

See the JVM Spec Chapter 4 for complete detail about the class file format.

Area of applicability

Asmtools were originally designed for the purposes of VM testing to make possible to obtain classes that cannot be produced by a compiler. Development of the VM tests continues to be the major area of applicability of Asmtools. They allow to generate arbitrary valid class file as well as invalid one.

JASM language supports the entire VM instruction set, that allows to program any logic.

The output of jdis, jdec, jcdec utilities can be used for the analysis of the class file. Text representation can be used for the comparison of two classes for equivalence.

Supported class file formats

Asmtools work with all existing class file formats, including new features introduced in JDK 7.

JavaCard .cap and .exp files can be decoded and encoded with jcdec and jcoder utilities.

Why do we need Assembler Tools?

AsmTools remove various restrictions a compiler is subject to:

• impossibility to get an invalid class

• not each valid class file can be obtained from the Java source with a compiler (i.e. keyword as an identifier)

• dependency on the particular compiler implementation

• Java code is not a vivid representation of the class file

• The compiler provides only one way transformation

AsmTools Tool System Requirements

The AsmTools themselves require Java SE version 1.5 or higher.

The AsmTools Components

The AsmTools are comprised of the following utilities:

• jasm tool, which generates class files from the JASM representation

• jdis tool, which translates class file into the JASM format

• jcoder tool, which generates class files from the JCOD representation

• jdec tool, which translates class file into the JCOD format

• jcdec tool, which translates JavaCard cap and exp files in JCOD format

An AsmTools distribution contains those utilities, and contains the following files and folders:

• AsmTools-Dir/lib

• AsmTools-Dir/lib/asmtools.jar

• AsmTools-Dir/license.html

• AsmTools-Dir/README.html
  
  

Chapter 2