Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8059557

JEP 245: Validate JVM Command-Line Flag Arguments

    Details

    • JEP Type:
      Feature
    • Exposure:
      Open
    • Subcomponent:
    • Scope:
      JDK
    • Discussion:
      hotspot dash dev at openjdk dot java dot net
    • Effort:
      M
    • Duration:
      M
    • Alert Status:
       Green
    • JEP Number:
      245

      Description

      Summary

      Validate the arguments to all JVM command-line flags so as to avoid crashes, and ensure that appropriate error messages are displayed when they are invalid.

      Non-goals

      • We will not validate arguments to flags that are not processed by the JVM.

      • We will not attempt to adjust arguments to fall within allowed ranges; we will only detect incorrect arguments, not correct them.

      Success Metrics

      Any JVM flag that takes a value and is provided an out-of-range value is shown to not cause a JVM crash but rather issue an informative error message. This will be done for JVM flags whether they are set ergonomically (e.g., in include files), set on the command line, set via tool input, or set via APIs (e.g., attachListener/jcmd, or java.lang.management).

      Description

      Any interface, whether it be programmatic or user-visible, must provide adequate capability to validate input values. In the case of command lines, it is critical to implement range checks for arguments which require a user-specified value. The globals.hpp source file contains the origin of the flag value and rudimentary range checking. Expanding and completing this can provide correct coverage.

      In addition, we should define a framework to make it very easy for someone adding a new JVM command-line flag to take advantage of this validity checking. The framework should be flexible, allowing for checks of a single value, being between a minimum and maximum value, or being within a set of values, etc.

      We will implement this feature by expanding existing macro tables (e.g., RUNTIME_FLAGS) to add optional range(min, max) and constraint(function_pointer) entries. Current range-checking and other ad-hoc validation code will be ported over and then removed.

      The range and constraints checks are done every time a flag changes, as well as late in the JVM initialization routine (i.e., in init_globals() after stubRoutines_init2()) at the time when all flags have their final values set. We will continue to check the manageable flags as long as the JVM runs.

      For those flags that depend on others that might not be set at the time of setting the flag in question, we will provide a mechanism in form of an API (CommandLineFlags::finishedInitializing()) to let constraint functions know when all flags have their final values set and change their behavior from NOP to error as needed.

      Intercepting flag value changes is done at a low level in CommandLineFlags::xxxxAtPut setters to guarantee that manageable flags are checked for their ranges and constraints (e.g., flags set via jcmd). For example, using jcmd PID VM.set_flag MinHeapFreeRatio 101, which is outside the allowed range, will print out

      PID:
      MinHeapFreeRatio error: must have value in range [0...100]

      in the jcmd output.

      The range checks do not impose any behavioral changes upon the JVM initialization process. In particular they do not terminate the JVM, but instead they propagate their status up to the code that uses them. The constraint functions can terminate the JVM to match existing custom behavior as needed.

      The range/constraint checks are non-verbose by default, to inhibit their messages from being printed out. Range checks do print error messages on the error stream during JVM initialization, in order to match current behavior. Printing to the error stream for manageable flags is inhibited; any error status will, rather, be handled by the WriteableFlags code to provide verbose status into the provided FormatBuffer so that it can be then printed by jcmd process itself instead of by the target process.

      In the event of range-check failure during JVM initialization, an error message is printed by default in the following form:

      uintx UnguardOnExecutionViolation = 3 is outside the allowed range [ 0 ... 2 ]

      We are not, however, committing to any particular format at this time. Existing tests that expect a certain message format will have to be modified to allow the new format.

      The existing behavior is not changed with respect to clamping flags to fit within a specified range (i.e., we do not clamp), even though we have that capability. We conform to the existing behavior during error detection while initializing the JVM (i.e., we terminate the process).

      Alternatives

      Variadic macros offered a slightly different, and possibly a cleaner, way to define ranges and constraints, but a "trailing comma with empty args" issue in the Solaris C++ compiler prevented the adoption of this approach.

        Issue Links

          Activity

          Hide
          gziemski Gerard Ziemski added a comment -
          Re 1) I do agree that at the moment the exception is not very meaningful

          Re 2) It was mentioned to me that we could consider C++ templates to replace macros, but after I experimented with the variadic macros, they seemed to offer an easy implementation with the least code changes required, which was desirable. Perhaps we can file a task to tackle changing macros to C++ templates or another solution?
          Show
          gziemski Gerard Ziemski added a comment - Re 1) I do agree that at the moment the exception is not very meaningful Re 2) It was mentioned to me that we could consider C++ templates to replace macros, but after I experimented with the variadic macros, they seemed to offer an easy implementation with the least code changes required, which was desirable. Perhaps we can file a task to tackle changing macros to C++ templates or another solution?
          Hide
          twisti Christian Thalinger added a comment -
          But Risks talks about variadic macros being a problem. Will that be fixed by a compiler upgrade?
          Show
          twisti Christian Thalinger added a comment - But Risks talks about variadic macros being a problem. Will that be fixed by a compiler upgrade?
          Hide
          gziemski Gerard Ziemski added a comment - - edited
          Only variadic macros with "trailing comma with empty args" is a problem (on Solaris). Variadic macros themselves are fine.

          Also, I found that when using an IDE (in my case Xcode) I can expand the macros by using a "Preprocessor menu" command, which alleviates to some extend the issues working with macros.
          Show
          gziemski Gerard Ziemski added a comment - - edited Only variadic macros with "trailing comma with empty args" is a problem (on Solaris). Variadic macros themselves are fine. Also, I found that when using an IDE (in my case Xcode) I can expand the macros by using a "Preprocessor menu" command, which alleviates to some extend the issues working with macros.
          Hide
          gziemski Gerard Ziemski added a comment -
          Updated JEP to reflect Staffan Larsen concerns that jcmd error should appear in jcmd process, not the target process.
          Show
          gziemski Gerard Ziemski added a comment - Updated JEP to reflect Staffan Larsen concerns that jcmd error should appear in jcmd process, not the target process.
          Hide
          gziemski Gerard Ziemski added a comment -
          Feature passes JPRT (-testset hotspot, ie. JTREG) and UTE (vm.quick.testlist)
          Show
          gziemski Gerard Ziemski added a comment - Feature passes JPRT (-testset hotspot, ie. JTREG) and UTE (vm.quick.testlist)

            People

            • Assignee:
              gziemski Gerard Ziemski
              Reporter:
              mlautman Mary Lautman
              Owner:
              Gerard Ziemski
              Reviewed By:
              Christian Thalinger, Karen Kinnear, Mikael Vidstedt
              Endorsed By:
              Mikael Vidstedt
            • Votes:
              0 Vote for this issue
              Watchers:
              12 Start watching this issue

              Dates

              • Due:
                Created:
                Updated:
                Resolved:
                Integration Due: