Class StackMapTableAttribute

The stack map attribute is used during the process of verification by typechecking ('4.11.1).

A stack map attribute consists of zero or more stack map frames. Each stack map frame specifies (either explicitly or implicitly) a bytecode offset, the verification types ('4.11.1) for the local variables, and the verification types for the operand stack.

The type checker deals with and manipulates the expected types of a method's local variables and operand stack. Throughout this section, a location refers to either a single local variable or to a single operand stack entry.

We will use the terms stack frame map and type state interchangeably to describe a mapping from locations in the operand stack and local variables of a method to verification types. We will usually use the term stack frame map when such a mapping is provided in the class file, and the term type state when the mapping is inferred by the type checker.

If a method's Code attribute does not have a StackMapTable attribute, it has an implicit stack map attribute. This implicit stack map attribute is equivalent to a StackMapTable attribute with number_of_entries equal to zero. A method's Code attribute may have at most one StackMapTable attribute, otherwise a java.lang.ClassFormatError is thrown.

The format of the stack map in the class file is given below. In the following, if the length of the method's byte code is 65535 or less, then uoffset represents the type u2; otherwise uoffset represents the type u4. If the maximum number of local variables for the method is 65535 or less, then ulocalvar represents the type u2; otherwise ulocalvar represents the type u4. If the maximum size of the operand stack is 65535 or less, then ustack represents the type u2; otherwise ustack represents the type u4.

 stack_map { // attribute StackMapTable
   u2 attribute_name_index;
   u4 attribute_length
   uoffset number_of_entries;
   stack_map_frame entries[number_of_entries];
 }
 

Each stack_map_frame structure specifies the type state at a particular byte code offset. Each frame type specifies (explicitly or implicitly) a value, offset_delta, that is used to calulate the actual byte code offset at which it applies. The byte code offset at which the frame applies is given by adding 1 + offset_delta to the offset of the previous frame, unless the previous frame is the initial frame of the method, in which case the byte code offset is offset_delta.

Note that the length of the byte codes is not the same as the length of the Code attribute. The byte codes are embedded in the Code attribute, along with other information.

By using an offset delta rather than the actual byte code offset we ensure, by definition, that stack map frames are in the correctly sorted order. Furthermore, by consistently using the formula offset_delta + 1 for all explicit frames, we guarantee the absence of duplicates.

All frame types, even full_frame, rely on the previous frame for some of their semantics. This raises the question of what is the very first frame? The initial frame is implicit, and computed from the method descriptor. See the Prolog code for methodInitialStacFrame.

The stack_map_frame structure consists of a one-byte tag followed by zero or more bytes, giving more information, depending upon the tag.

A stack map frame may belong to one of several frame types

 union stack_map_frame {
   same_frame;
   same_locals_1_stack_item_frame;
   chop_frame;
   same_frame_extended;
   append_frame;
   full_frame;
 }
 

The frame type same_frame is represented by tags in the range [0-63]. If the frame type is same_frame, it means the frame has exactly the same locals as the previous stack map frame and that the number of stack items is zero. The offset_delta value for the frame is the value of the tag field, frame_type. The form of such a frame is then:

 same_frame {
   u1 frame_type = SAME;  // 0-63
 }
 

The frame type same_locals_1_stack_item_frame is represented by tags in the range [64, 127]. If the frame_type is same_locals_1_stack_item_frame, it means the frame has exactly the same locals as the previous stack map frame and that the number of stack items is 1. The offset_delta value for the frame is the value (frame_type - 64). There is a verification_type_info following the frame_type for the one stack item. The form of such a frame is then:

 same_locals_1_stack_item_frame {
   u1 frame_type = SAME_LOCALS_1_STACK_ITEM;  // 64-127
    verification_type_info stack[1];
 }
 

Tags in the range [128-247] are reserved for future use.

The frame type chop_frame is represented by tags in the range [248-250]. If the frame_type is chop_frame, it means that the current locals are the same as the locals in the previous frame, except that the k last locals are absent. The value of k is given by the formula 251-frame_type.

The form of such a frame is then:

 chop_frame {
   u1 frame_type=CHOP;  // 248-250
   uoffset offset_delta;
 }
 

The frame type same_frame_extended is represented by the tag value 251. If the frame type is same_frame_extended, it means the frame has exactly the same locals as the previous stack map frame and that the number of stack items is zero. The form of such a frame is then:

 same_frame_extended {
   u1 frame_type = SAME_FRAME_EXTENDED;  // 251
   uoffset offset_delta;
 }
 

The frame type append_frame is represented by tags in the range [252-254]. If the frame_type is append_frame, it means that the current locals are the same as the locals in the previous frame, except that k additional locals are defined. The value of k is given by the formula frame_type-251.

The form of such a frame is then:

 append_frame {
   u1 frame_type =APPEND;  // 252-254
   uoffset offset_delta;
   verification_type_info locals[frame_type -251];
 }
 

The 0th entry in locals represents the type of the first additional local variable. If locals[M] represents local variable N, then locals[M+1] represents local variable N+1 if locals[M] is one of Top_variable_info, Integer_variable_info, Float_variable_info, Null_variable_info, UninitializedThis_variable_info, Object_variable_info, or Uninitialized_variable_info, otherwise locals[M+1] represents local variable N+2. It is an error if, for any index i, locals[i] represents a local variable whose index is greater than the maximum number of local variables for the method.

The frame type full_frame is represented by the tag value 255. The form of such a frame is then:

 full_frame {
   u1 frame_type = FULL_FRAME;  // 255
   uoffset offset_delta;
   ulocalvar number_of_locals;
   verification_type_info locals[number_of_locals];
   ustack number_of_stack_items;
   verification_type_info stack[number_of_stack_items];
 }
 

The 0th entry in locals represents the type of local variable 0. If locals[M] represents local variable N, then locals[M+1] represents local variable N+1 if locals[M] is one of Top_variable_info, Integer_variable_info, Float_variable_info, Null_variable_info, UninitializedThis_variable_info, Object_variable_info, or Uninitialized_variable_info, otherwise locals[M+1] represents local variable N+2. It is an error if, for any index i, locals[i] represents a local variable whose index is greater than the maximum number of local variables for the method.

The 0th entry in stack represents the type of the bottom of the stack, and subsequent entries represent types of stack elements closer to the top of the operand stack. We shall refer to the bottom element of the stack as stack element 0, and to subsequent elements as stack element 1, 2 etc. If stack[M] represents stack element N, then stack[M+1] represents stack element N+1 if stack[M] is one of Top_variable_info, Integer_variable_info, Float_variable_info, Null_variable_info, UninitializedThis_variable_info, Object_variable_info, or Uninitialized_variable_info, otherwise stack[M+1] represents stack element N+2. It is an error if, for any index i, stack[i] represents a stack entry whose index is greater than the maximum operand stack size for the method.

We say that an instruction in the byte code has a corresponding stack map frame if the offset in the offset field of the stack map frame is the same as the offset of the instruction in the byte codes.

The verification_type_info structure consists of a one-byte tag followed by zero or more bytes, giving more information about the tag. Each verification_type_info structure specifies the verification type of one or two locations.

 union verification_type_info {
   Top_variable_info;
   Integer_variable_info;
   Float_variable_info;
   Long_variable_info;
   Double_variable_info;
   Null_variable_info;
   UninitializedThis_variable_info;
   Object_variable_info;
   Uninitialized_variable_info;
 }
 

The Top_variable_info type indicates that the local variable has the verification type top (T.)

 Top_variable_info {
   u1 tag = ITEM_Top; // 0
 }
 

The Integer_variable_info type indicates that the location contains the verification type int.

 Integer_variable_info {
   u1 tag = ITEM_Integer; // 1
 }
 

The Float_variable_info type indicates that the location contains the verification type float.

 Float_variable_info {
   u1 tag = ITEM_Float; // 2
 }
 

The Long_variable_info type indicates that the location contains the verification type long. If the location is a local variable, then:

• It must not be the local variable with the highest index.
• The next higher numbered local variable contains the verification type T.

If the location is an operand stack entry, then:

• The current location must not be the topmost location of the operand stack.
• the next location closer to the top of the operand stack contains the verification type T.

This structure gives the contents of two locations in the operand stack or in the local variables.

 Long_variable_info {
   u1 tag = ITEM_Long; // 4
 }
 

The Double_variable_info type indicates that the location contains the verification type double. If the location is a local variable, then:

• It must not be the local variable with the highest index.
• The next higher numbered local variable contains the verification type T.

If the location is an operand stack entry, then:

• The current location must not be the topmost location of the operand stack.
• the next location closer to the top of the operand stack contains the verification type T.

This structure gives the contents of two locations in in the operand stack or in the local variables.

 Double_variable_info {
   u1 tag = ITEM_Double; // 3
 }
 

The Null_variable_info type indicates that location contains the verification type null.

 Null_variable_info {
   u1 tag = ITEM_Null; // 5
 }
 

The UninitializedThis_variable_info type indicates that the location contains the verification type uninitializedThis.

 UninitializedThis_variable_info {
   u1 tag = ITEM_UninitializedThis; // 6
 }
 

The Object_variable_info type indicates that the location contains an instance of the class referenced by the constant pool entry.

 Object_variable_info {
   u1 tag = ITEM_Object; // 7
   u2 cpool_index;
 }
 

The Uninitialized_variable_info indicates that the location contains the verification type uninitialized(offset). The offset item indicates the offset of the new instruction that created the object being stored in the location.

 Uninitialized_variable_info {
   u1 tag = ITEM_Uninitialized // 8
   uoffset offset;
 }
 

Author: Eugene Kuleshov

See Also: "ClassFileFormat-Java6.fm Page 138 Friday, April 15, 2005 3:22 PM"