CS 562: Project 2: Hawkbeans JVM

Coding Task 1

Your first task is to complete method and class resolution in Hawkbeans. This will involve filling in the implementations for two functions in src/class.c, hb_resolve_class and hb_resolve_method. The latter relies on the former, so start with hb_resolve_class. You'll want to use the Oracle JVM docs for class resolution and method resolution as references when writing your implementation.

In general, when a constant pool entry is resolved, the implementer of the JVM is given flexibility on what this means in practice. For our purposes, the pointer to the constant info structure (whether it be for a class, a method, a field, etc.) is replaced with an internal pointer to a structure representing the appropriate entry. To indicate that the entry is resolved, we rely on some insider information about virtual addresses and set the highest bit of the pointer's address to 1 (sometimes this is called a tagged pointer. For example, for classes, this means that a CONST_Class_info_t* is replaced with a java_class_t*. For methods, it means a CONST_Methodref_info_t* is replaced with a method_info_t* (both structs are defined in include/class.h).

hb_resolve_class

This function is used by other parts of the JVM to resolve symbolic references to classes, for example to access their fields or methods. It relies on an existing class loader (there is currently only one, in jvm/arch/x64-linux/bootstrap_loader.c). The goal here is to transform a constant pool entry (a pointer to a descriptor) into a pointer to our internal representation of classes (see the definition of java_class_t in include/class.h).

Note that this function takes two arguments, an index into the constant pool and a pointer to the source class. This pointer should correspond to the currently used class, i.e. the one that was specified at the command line. Your code should do the following:

1. Check if the given index is 0. This is a special case. See the documentation.
2. If not, you should derive a pointer to a CONSTANT_Class_info_t struct, which is defined in include/constants.h.
3. Check if the constant pool entry has been resolved already (using the IS_RESOLVED(), MASK_RESOLVED_BIT(), and MARK_RESOLVED() macros). If it's already resolved, you should mask off the high-order bit and return the class pointer directly.
4. If it hasn't been resolved, you need to resolve it. First you should check the class map (using the class name). You can derive the class name using the provided hb_get_const_str() function. You can lookup in the classmap using hb_get_class().
5. If the class is in the class map, it should be returned and the constant pool entry should be replaced with a pointer to it (with the high order bit set!).
6. If it's not been loaded, you need to invoke the class loader using the class name, add the class to the class map, prep the class, initialize the class, and overwrite the constant pool entry appropriately. You'll want to use hb_add_class(), hb_prep_class(), and hb_init_class(), all defined in include/class.h.

hb_resolve_method()

Method resolution is slightly more subtle, as what we are doing here is implementing the machinery to support polymorphism! We cannot simply resolve a method by just its name. We also have to consider on which Object it was invoked and its method signature, i.e. the number and types of its arguments. This is why a descriptor for a method (CONSTANT_Methodref_info_t) contains two constant pool offsets, one for the name of the method, and another for its signature.

The general flow of this function is that we should first look and see which class the method in the method descriptor (determined by its class_idx) belongs to. This class may or may not need to be resolved, hence the order of implementation. Once it is resolved, we iterate through each method descriptor of that class and try to match it to the descriptor given to us (namely, do both the method name and method parameter descriptor match?). If so, we're done, and we set the constant pool entry to resolved and return the method_info_t*. Otherwise, we cannot just fail. We now must search up the class hierarchy to see if the method is implemented by this class's superclasses. This should give you a hint about the algorithmic technique you choose.

Note that this method adds an extra argument, the target_cls argument. This should help with the above hint. The initial call to hb_resolve_method() should provide NULL for this argument. If it is not, it means we've failed the initial search on the method's attached class, and we're now trying to trace back through its superclasses.

Note, you can follow the instructions here, but you don't need to worry about implementing access permissions or exceptions. You really only need to implement the steps outlined in point (2).

Coding Task 2

Your task here is to add some important functionality to the interpreter. Namely, you will complete the implementations of the following functions:

• istore/iload
• istore_<n>/iload_<n>
• iadd
• imul
• idiv
• irem
• isub
• ineg
• new
• newarray
• arraylength

You should use the Java ISA reference to complete the implementation of these instructions. I will not give you much more information here, but some existing support functions in the Hawkbeans codebase that you will want to leverage include:

• push_val() and pop_val() functions. These are used to manipulate the current frame's operand stack.
hb_resolve_class() you will need for new.
• gc_obj_alloc you will also need for new
• You will need gc_array_alloc() for newarray

Note that in some cases you might need to look at the C structure representing a Java object. This is the native_obj_t defined in include/class.h. You will need this at least for arraylength.

One pitfall to avoid here is to be very careful with the types used by the elements in a var_t (defined in include/class.h). For example, you may have code like:

        
        var_t x;
        x.int_val = 1;
        x.int_val = -x.int_val;
        
        

Some of the required actions for these instructions have similarities that might point towards using macros to avoid repeating code (see DRY).

Coding Task 3

The interface to exceptions used by the rest of the JVM is defined in include/exceptions.h. The two main functions are:

• hb_throw_exception(): Used to throw an exception given a reference to an existing Exception object (which ultimately derives from the Throwable class). This is the function used by the JVM when a programmer explicitly throws an exception (see testcode/TestNullPointerThrow.java). This ultimately turns into the execution of the athrow bytecode instruction (which you will also implement).
• hb_throw_and_create_excp(): Used to throw an exception without an object reference. This is used when the JVM throws exceptions indirectly caused by the execution of some instruction. For example, if an access to an array element with an index past the length of an array is attempted, the JVM would invoke this method with the EXCP_NULL_PTR argument (defined in include/exceptions.h).

Your task here is to implement hb_throw_exception() and hb_throw_and_create_excp() in src/exceptions.c, as well as the handler for the athrow instruction in src/bc_interp.c.

I'm not going to give you too much instruction here, but the general principle is that you need to scan the exception table for method corresponding to the current frame and look for a matching exception entry. If the entry is found, we invoke the handler for that entry. If not, we pop a frame and continue searching. If we reach the base frame and still have not found a matching exception table entry, it means that no method explicitly provided a handler for the exception that was thrown, so we must kill the current thread and exit. You can expect that if the current code (which threw the exception) has a catch clause somewhere, you should be finding its exception table within the scope of that method.

You should look at the documentation for exceptions and the documentation for athrow to complete your implementation.

Note, you'll want to look at and leverage these functions which already exist:

• hb_get_or_load_class()
• gc_obj_alloc()
• hb_invoke_ctor()
• hb_get_class_name()
• hb_pop_frame()
• hb_get_super_class()
• hb_resolve_class()
• get_excp_str()

You'll notice that I've given you less help in terms of skeleton code here. This is intentional. Reading the documentation is your best bet here. You'll probably want to break down your implementation into several support functions that handle each subtask of exception throwing rather than trying to throw it all into one function.

Coding Task 4

There is significantly more skeleton code for you to work with for this part. You should start by taking a look at gc_init()in src/gc.c. This is where the GC is initialized. The important bits here that you should look at are the calls to add_root() and init_ref_tbl(). Each call to add_root() is registering a root object which the GC shall scan during the mark phase. Each root is associated with a callback function for scanning that particular root. Your job will be to implement these scanning functions. The framework for them is there, you just must fill them in.

Here are the important roots:

• The base object (this is the instantiated object corresponding to the class that was provided at the command line): You must scan all of the fields of this object for references and any reference you find, you must then descend into the object referred to by that reference and scan its fields as well.
• The base object reference: This is the reference to the above object. Because it was created before the GC was initialized, it must be special cased. The code for scanning this reference is already implemented.
• The class map: you must scan all classes loaded into the class map, and check their static fields for references. Recall these fields are those which are the same for every instance of the class, so you cannot access them from a given object instance. You can find them in the field_vals of a java_class_t structure.
• The base frame: This is the frame corresponding to the main function invoked at the beginning of the JVM's execution. This frame's local variables and operand stack are scanned for references to objects just like before. Each successive frame must also be scanned.

Note that the framework for invoking the scanning functions is already in place (see gc_collect(), mark(), and scan_roots()).

Mark

You must first finish the following functions:

• scan_base_obj()
• scan_base_frame()
• scan_class_map()

One programming idiom you will see here that you might not recognize is the pattern involving opaque pointers and callback functions. The scan_X functions are considered callbacks because we pass them as function pointers to the add_roots() registration function at initialization time. When the GC is invoked, it will call each of these functions in turn. This pattern makes it easy to add other GC roots later on if we want. See how each of the functions above each takes a void * priv_data as an argument. This is there so that when the callback function is invoked, it can re-derive whatever state it needs from that pointer. This state is passed in during callback registration (add_root()). You can see that each callback will be given a pointer to the GC's state, i.e. a gc_state_t pointer.

Sweep

You now must complete the sweep phase of the collector. This means you must fill in the sweep() function. This function must iterate through the reference table (see an example of how to do this in clear_ref_tbl()) and collect all entries whose status is set to GC_REF_ABSENT. To collect an object, you must first free the reference table entry for it, then you must free the object using the memory allocator's object_free() function. Make sure to update the collectors stats (namely obj_collected and bytes_reclaimed). Finally, after the object has been freed, you should free() the reference itself.