There are places in the JVMTI spec where OPAQUE_FRAME can mean something other than a native method. This doesn't impact the debug agent other than spec clarification, since it just passes OPAQUE_FRAME on to JDI. However, JDI often needs to determine if OPAQUE_FRAME is due to a native method, and throw NativeMethodException if it is. Therefore it needs to understand the reason OPAQUE_FRAME might be returned, both for spec clarification and proper implementation regarding which exception OPAQUE_FRAME is converted to.

Before loom, the JVMTI spec said the following for ForceEarlyReturn:

        <error id="JVMTI_ERROR_OPAQUE_FRAME">
          Attempted to return early from a frame
          corresponding to a native method.
          Or the implementation is unable to provide
          this functionality on this frame.

At this time JDI always produced NativeMethodException for OPAQUE_FRAME. However, the second sentence above indicates that OPAQUE_FRAME can be for something other than a native method. It seems there are a few other ways JVMTI can fail with OPAQUE_FRAME, including a failure to deopt or being blocked in MONITOR_WAIT. In this regard, JDI always throwing NativeMethodException for OPAQUE_FRAME does not seem like correct behavior, since the frame may not be native, and also the JDI spec does not cover this as a reason for throwing NativeMethodException.

     * @throws NativeMethodException if the frame to be returned from
     * is that of a native method.

Moving forward to Loom changes, the problem becomes a bit worse, since JVMTI added the following as a reason for returning OPAQUE_FRAME:

          The thread is a suspended virtual thread and the implementation was
          unable to force its current frame to return.

If JDI sees OPAQUE_FRAME on a virtual thread, it checks if the frame is native. If it is it throws NativeMethodException, otherwise it throws OpaqueFrameException. This means for virtual threads the "implementation is unable to provide this functionality on this frame" failure reason results in OpaqueFrameException, whereas for platform threads it result in NativeMethodException. So now we've added an inconsistency between virtual and platform threads w.r.t. the exception thrown for the same JVMTI failure reason.

One way to resolve this is to have to allow OpaqueFrameException for platform threads whenever JDI gets OPAQUE_FRAME and the frame is not native. But before we can go down that path, we need to have a good understanding of all the reasons why JVMTI might return OPAQUE_FRAME. For example, PopFrame says:

        <error id="JVMTI_ERROR_OPAQUE_FRAME">
          Called or calling method is a native method.
          The implementation is unable to pop this frame.
        </error>
        <error id="JVMTI_ERROR_OPAQUE_FRAME">
          The thread is a suspended virtual thread and the implementation
          was unable to pop the current frame.
        </error>

However, it turns out that it too can result in OPAQUE_FRAME due to a failure to deopt or being blocked on MONITOR_WAIT. This needs to be clarified int the spec.

Then there is GetLocalXXX, which may return OPAQUE_FRAME, and the spec says it means "Not a visible frame.". It's unclear is this is just different wording for the same reason given for ForceEarlyReturn. This needs to be clarified as part of this CR.

There might be other places where OPAQUE_FRAME can be returned that need clarification. They should all be looked at as part of this CR.

See JDK-8309400 for the JDI part of this OPAQUE_FRAME clarification.