From f0f69257452f6a451f8c794d050e9b14e4dba53a Mon Sep 17 00:00:00 2001 From: Sreekala Gopakumar Date: Thu, 17 Oct 2024 01:18:55 +0530 Subject: [PATCH] CRIU enable JDWP support post-restore https://github.com/eclipse-openj9/openj9-docs/issues/1407 Added the -Xrunjdwp option with the new SuspendOnRestore parameter. Updated the related topics. Incorporated feedback. Content related to -XX:+debugonrestore deleted. Closes #1407 Signed-off-by: Sreekala Gopakumar sreekala.gopakumar@ibm.com --- docs/interface_jvmti.md | 4 +- docs/version0.48.md | 13 ++++- docs/xrunjdwp.md | 115 ++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 130 insertions(+), 3 deletions(-) create mode 100644 docs/xrunjdwp.md diff --git a/docs/interface_jvmti.md b/docs/interface_jvmti.md index f35aa1b2c0..d0193ca980 100644 --- a/docs/interface_jvmti.md +++ b/docs/interface_jvmti.md @@ -39,10 +39,12 @@ or -agentpath:= -In the example that follows (see [Sample JVMTI agent](#sample-jvmti-agent)), the directory containing the `jdwp` library is assumed to be on the library path. If you require a specific library, such as `jdwp`, with your JVMTI agent, you can specify the path at startup, for example: +In the example that follows (see [Sample JVMTI agent](#sample-jvmti-agent)), the directory containing the `jdwp` library is assumed to be on the library path. If you require a specific library, such as `jdwp`, with your JVMTI agent, you can specify the path at startup, for example: -agentlib:jdwp= +For more information about `-agentlib:jdwp`, see [`-Xrunjdwp`](xrunjdwp.md). + For more information about JVMTI, see [https://docs.oracle.com/javase/8/docs/technotes/guides/management/index.html](https://docs.oracle.com/javase/8/docs/technotes/guides/management/index.html). For a guide about writing a JVMTI agent, see [http://www.oracle.com/technetwork/articles/javase/jvmti-136367.html](https://www.oracle.com/technetwork/articles/javase/jvmti-136367.html). diff --git a/docs/version0.48.md b/docs/version0.48.md index 8ebd61ccf3..4bce1dbd66 100644 --- a/docs/version0.48.md +++ b/docs/version0.48.md @@ -27,6 +27,7 @@ The following new features and notable changes since version 0.47.0 are included - [New binaries and changes to supported environments](#binaries-and-supported-environments) - [Loading of the `zlibnx` library on AIX is disabled by default](#loading-of-the-zlibnx-library-on-aix-is-disabled-by-default) +- ![Start of content that applies to Java 11 (LTS) and later](cr/java11plus.png) [JDWP support on Checkpoint/Restore In Userspace (CRIU) restore is enabled](#jdwp-support-on-checkpointrestore-in-userspace-criu-restore-is-enabled) ![End of content that applies to Java 11 (LTS) and later](cr/java_close.png) ## Features and changes @@ -42,8 +43,16 @@ From release 0.25.0 onwards, `zlibNX` hardware-accelerated data compression and For more information, see [`-XX:[+|-]UseZlibNX`](xxusezlibnx.md). +### ![Start of content that applies to Java 11 (LTS) and later](cr/java11plus.png) JDWP support on Checkpoint/Restore In Userspace (CRIU) restore is enabled + +You can use the options that enable the JDWP support both on CRIU pre-checkpoint, and on restore as well. + +Also, a new parameter `suspendOnRestore` for the `Xrunjdwp` option is added to control the suspension of the target VM application on restore. This option is specific to OpenJ9. You can use the `suspendOnRestore=n` setting to prevent the suspension of the target application. + +For more information, see [`-Xrunjdwp`](xrunjdwp.md). ![End of content that applies to Java 11 (LTS) and later](cr/java_close.png) + ## Known problems and full release information -To see known problems and a complete list of changes between Eclipse OpenJ9 v0.46.0 and v0.47.0 releases, see the [Release notes](https://github.com/eclipse-openj9/openj9/blob/master/doc/release-notes/0.47/0.47.md). +To see known problems and a complete list of changes between Eclipse OpenJ9 v0.47.0 and v0.48.0 releases, see the [Release notes](https://github.com/eclipse-openj9/openj9/blob/master/doc/release-notes/0.48/0.48.md). - + diff --git a/docs/xrunjdwp.md b/docs/xrunjdwp.md new file mode 100644 index 0000000000..13a2df4fbc --- /dev/null +++ b/docs/xrunjdwp.md @@ -0,0 +1,115 @@ + + +# -Xrunjdwp + +The `-Xrunjdwp` option enables the Java™ Debug Wire Protocol (JDWP) agent in the VM. The JDWP agent provides a connection point for the debugger to debug a Java application in that VM. + +:fontawesome-solid-pencil:{: .note aria-hidden="true"} **Note:** You can enable the JDWP support on Checkpoint/Restore In Userspace (CRIU) restore by specifying the following command-line options pre-checkpoint: + +- `-Xrunjdwp` +- `-agentlib:jdwp` +- `-agentpath:/path/to/libjdwp.so` + + + +## Parameters + +These parameters are applicable for both the `-Xrunjdwp` and `-agentlib:jdwp` options. + +### `address` + + -Xrunjdwp:address= + +: Specifies the *transport* address for the connection. If [`server=y`](#server) and `address` is specified, the VM listens for a connection at this address. If `server=y` and `address` is not specified, the VM chooses a [`transport`](#transport) address to listen for a debugger application. If `server=n`, the `address` parameter is mandatory. The VM attempts to attach to the debugger application at the specified address. + +### `help` + + -Xrunjdwp:help + +: Prints a brief help message that describes all the available options for the `-Xrunjdwp` option and exits the VM. + +### `launch` + + -Xrunjdwp:launch= + +: Starts the debugger process from the specified path. The values of the `address` and `transport` parameters, if available, are also added to the specified path. These parameters help the debugger to connect to the target VM. This option is used with `onthrow`, `onuncaught` or both the parameters to provide *Just-In-Time debugging* in which a debugger process is started when a particular event occurs in this VM. + +### `onthrow` + + -Xrunjdwp:onthrow= + +: Delays the debugging process until the specified exception is thrown in this VM. The JDWP agent attaches to the VM and starts debugging when the exception is thrown. + +### `onuncaught` + + -Xrunjdwp:onuncaught=[y|n] + +: If `onuncaught=y`, delays the debugging process until an uncaught exception is thrown in this VM. + +### `server` + + -Xrunjdwp:server=[y|n] + +: If `server=n`, the VM does not listen to any incoming debugger connection and it attempts to attach to the local debugger application at the specified [`address`](#address). In this case, specifying the`address` parameter is mandatory. If `server=y`, the target VM acts as a server listening for an incoming debugger connection through the JDWP agent. If `server=y` and `address` is specified, the VM listens for a debugger connection at this address. If `server=y` and `address` is not specified, the VM selects a [`transport`](#transport) address at which to listen for a debugger application. + +### `suspend` + + -Xrunjdwp:suspend=[y|n] + +: If `suspend=y`, the VM suspends running of the target Java application until the debugger is attached successfully and is ready for debugging. If `suspend=n`, the VM does not suspend running of the target Java application while the debug connection is established. The VM continues running the application as normal. The debugger can attach to the running application at any time. + +: When a debug session is restored from a checkpoint, the VM suspends the running of the Java application that was being debugged even if `suspend=n`. The VM waits for the debugger to send a `Resume` request before it restarts the Java application to continue the debug session. When the debug session is complete, the debugger disconnects from the JDWP agent, and the agent resumes normal running of the Java application. + +### ![Start of content that applies to Java 11 (LTS) and later](cr/java11plus.png) `suspendOnRestore` + +**(Linux® x86, Linux on POWER® (Little Endian), Linux on AArch64, and Linux on IBM Z® only)** + +`suspendOnRestore` is an OpenJ9 specific parameter and is similar to the `suspend` parameter. But unlike `suspend`, this parameter only affects a VM on restore. + + -Xrunjdwp:suspendOnRestore=[y|n] + +: If `suspendOnRestore=y`, the VM suspends running of the target Java application until the debugger is attached successfully and is ready for debugging on CRIU restore. If `suspendOnRestore=n`, the VM does not suspend the running of the target Java application while the debug connection is established on restore. + +: If [`suspend=y`](#suspend) is set pre-checkpoint, the VM suspends the application pre-checkpoint, and on restore. The application remains suspended when you restore the VM even if you specify `suspend=n` pre-checkpoint. Therefore, to ensure that the application is not suspended on restore, you can use the `suspendOnRestore=n` setting. ![End of content that applies to Java 11 (LTS) and later](cr/java_close.png) + +### `timeout` + + -Xrunjdwp:timeout= + +: If [`server=y`](#server), the `timeout` parameter specifies the time the VM waits for the debugger to attach before the VM ends the connection. If `server=n`, the parameter specifies the time until the VM tries attaching to the debugger before it ends the connection. + +### `transport` + + -Xrunjdwp:transport= + +: Specifies the name of the transport to use in connecting to the debugger application. Transport refers to a method of communication between a debugger and the VM that is being debugged. `` can be `dt_socket` or `dt_shmem`. `dt_socket` or the socket transport relies on TCP sockets that listen on a port for debugger connections, and uses that connection to transfer the debug session packets. This transport mechanism enables debugging remote target VM application. `dt_shmem` or the shared memory transport uses shared memory to send and receive packets. This transport mechanism enables debugging only locally running applications. + +For more information, see [-agentlib:jdwp and -Xrunjdwp sub-options](https://docs.oracle.com/en/java/javase/11/docs/specs/jpda/conninv.html#jdwpoptions). + +## See also + +- [CRIU support](criusupport.md) +- [What's new in version 0.48.0](version0.48.md#jdwp-support-on-checkpointrestore-in-userspace-criu-restore-is-enabled) + + diff --git a/mkdocs.yml b/mkdocs.yml index 384b85e23a..5c4dea4f4a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -360,6 +360,7 @@ nav: - "-Xoptionsfile" : xoptionsfile.md - "-Xquickstart" : xquickstart.md - "-Xrs" : xrs.md + - "-Xrunjdwp" : xrunjdwp.md - "-XsamplingExpirationTime" : xsamplingexpirationtime.md - "-Xscdmx" : xscdmx.md - "-Xscmaxaot" : xscminaot.md # redirect