Summary

The JDWP spec needs some minor corrections related to the OPAQUE_FRAME and INVALID_SLOT errors.

Problem

StackFrame.SetValues, StackFrame.GetValues, ThreadReference.PopFrames, and ThreadReference.ForceEarlyReturn all need updated language related to OPAQUE_FRAME and INVALID_SLOT errors.

(1) The spec for JVMTI says the following for GetLocalsXXX and SetLocalsXXX

The implementation is unable to set the frame locals
(e.g. the frame at depth is executing a native method).

However, the JDWP StackFrame.SetValues and GetValues commands only mention OPAQUE_FRAME for SetValues when the topmost frame of a virtual thread is suspended but not at an event. I don't think there is anything to prevent OPAQUE_FRAME due to the thread being native or some other reason as mentioned in the JVMTI spec. The JDWP spec should be updated to reflect this.

(2) The spec for JDWP ThreadReference.PopFrames, and ThreadReference.ForceEarlyReturn says:

Attempted to return early from a frame
corresponding to a native method,
the thread is a suspended virtual thread and the target
VM is unable to force its current frame to return,
or the implementation is unable to provide this
functionality on this frame.

The virtual thread reference is unnecessary since this is already covered by the last clause, and the virtual thread support is already described in the general description of these APIs.

(3) Another issue is that INVALID_SLOT is missing in the JDWP spec for SetValues, but is there for GetValues. It should be mentioned for both commands.

Solution

For (1), add language similar to what we have for other APIs that can return OPAQUE_FRAME. This is covered in the 2nd diff below (sans the INVALID_SLOT change) For (2), simply remove the virtual thread reference from the OPAQUE_FRAME description. Virtual thread support is already described in the general description of these APIs. This is covered in the 1st and 3rd diffs below. For (3), add INVALID_SLOT as a potential error for SetValues. This is part of the 2nd diff below.

Specification

Link to PR webrev: https://openjdk.github.io/cr/?repo=jdk&pr=26336&range=00

diff --git a/src/java.se/share/data/jdwp/jdwp.spec b/src/java.se/share/data/jdwp/jdwp.spec
index 5206a0c6ae95d..77a0b24069180 100644
--- a/src/java.se/share/data/jdwp/jdwp.spec
+++ b/src/java.se/share/data/jdwp/jdwp.spec
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -2150,8 +2150,6 @@ JDWP "Java(tm) Debug Wire Protocol"
             (Error THREAD_NOT_SUSPENDED)
             (Error OPAQUE_FRAME      "Attempted to return early from a frame "
                                      "corresponding to a native method, "
-                                     "the thread is a suspended virtual thread and the target "
-                                     "VM is unable to force its current frame to return, "
                                      "or the implementation is unable to provide this "
                                      "functionality on this frame.")
             (Error NO_MORE_FRAMES)
@@ -2625,6 +2623,10 @@ JDWP "Java(tm) Debug Wire Protocol"
             (Error INVALID_OBJECT)
             (Error INVALID_FRAMEID)
             (Error INVALID_SLOT)
+            (Error OPAQUE_FRAME      "Attempted to get the value of local variables in a frame "
+                                     "corresponding to a native method, "
+                                     "or the implementation is unable to provide this "
+                                     "functionality on this frame.")
             (Error VM_DEAD)
         )
     )
@@ -2662,9 +2664,11 @@ JDWP "Java(tm) Debug Wire Protocol"
             (Error INVALID_THREAD)
             (Error INVALID_OBJECT)
             (Error INVALID_FRAMEID)
-            (Error OPAQUE_FRAME      "The thread is a suspended virtual thread and the target VM "
-                                     "does not support setting the value of local "
-                                     "variables in the frame.")
+            (Error INVALID_SLOT)
+            (Error OPAQUE_FRAME      "Attempted to set the value of local variables in a frame "
+                                     "corresponding to a native method, "
+                                     "or the implementation is unable to provide this "
+                                     "functionality on this frame.")
             (Error VM_DEAD)
         )
     )
@@ -2714,9 +2718,9 @@ JDWP "Java(tm) Debug Wire Protocol"
             (Error THREAD_NOT_SUSPENDED)
             (Error NO_MORE_FRAMES)
             (Error OPAQUE_FRAME      "If one or more of the frames to pop is a native "
-                                     "method or its caller is a native method, or the "
-                                     "thread is a suspended virtual thread and the implementation "
-                                     "was unable to pop the frames.")
+                                     "method or its caller is a native method, "
+                                     "or the implementation is unable to provide this "
+                                     "functionality on this frame.")
             (Error NOT_IMPLEMENTED)
             (Error VM_DEAD)
         )