IRETURN (0xAC)

The IRETURN instruction terminates a method invocation and returns control to the calling method. The value on the top of the stack (the function return value) prior to the execution of IRETURN will also be on the top of the stack following the execution of IRETURN.

Interpreter Microcode

The microinstructions are listed in the order in which they are executed; not the order in which they are stored in the control store. Since microinstructions can do several things at once, there is no simple progression of tasks; they are somewhat intermingled. Some comments have been included in an effort to make it easier to follow what is happening in the code.

0x0ac  SP=MAR=LV; rd; goto 0x58      // Set SP and read return address pointer
...
0x058  ALU=0; goto 0x5a
...
0x05a  LV=MAR=MDR; rd; goto 0x5b     // Read return address
0x05b  MAR=LV+1; goto 0x5c
0x05c  PC=MDR; rd; fetch; goto 0x5d  // PC = return address; read previous LV
0x05d  MAR=SP; goto 0x5e
0x05e  LV=MDR; goto 0x61             // Restore the previous LV value
...
0x061  MDR=TOS; wr; goto 0x2         // Copy function return value to top of stack

Example Program

//---------------------------------------------
// Demonstrate the INVOKEVIRTUAL and IRETURN
// instructions.
//
// 1. Clear Memory
// 2. Assemble this program.
// 3. Reset the computer.
// 4. Click the "Display Words" radio button
//    below the memory display.
// 5. Click the "Run" button.
//
// The local variable 'sum' in main (at offset
// zero from LV) will contain the value 10.
//---------------------------------------------
.constant
    OBJREF 0
.end-constant

.main
    .var
        sum
    .end-var

    ldc_w OBJREF
    bipush 6
    bipush 4
    invokevirtual add
    istore sum
    halt
.end-main

//---------------------------------------------
// Note: normally, you would not use a local
// variable in the method below; it is not
// needed. You would just execute 'ireturn'
// immediately after the 'iadd' instruction.
// The variable was included to help illustrate
// how stack frames are created.
//---------------------------------------------
.method add(a, b)
    .var
        sum
    .end-var

    iload a
    iload b
    iadd
    istore sum  // Store sum

    iload sum   // Place sum on stack as return value
    ireturn
.end-method

Before invoking a method (see INVOKEVIRTUAL) you must place an object reference (an implicit parameter) onto the stack followed by the method's explicit parameters (if any). The INVOKEVIRTUAL instruction creates a stack frame and resumes program execution with the first instruction in the method.

Every IJVM method returns a value. When implementing a "value-returning" function, the calling routine should do something with this value. When implementing a void function (a procedure), the calling routine should just pop this value off the stack.

It is the responsibility of the method to insure that its return value (if any) is on the top of the stack prior to the execution of the IRETURN statement. During its execution, the IRETURN statement performs these basic tasks:

1. Loads the PC with the return address.
2. Restores the LV register with its previous value.
3. Removes the stack frame by setting the SP register to point to the base of the stack frame.
4. Copies the function return value that was on the top of the stack (prior to IRETURN) as the top element in the adjusted stack.

In the graphic below are two "snapshots" of memory: one taken just before the execution of the IRETURN instruction in the method of the example program above and one taken immediately afterward. Notice in the second snapshot that the stack frame has been removed and that the value that was on the top of the stack prior to its removal has been copied to the new top of stack position.