-
Notifications
You must be signed in to change notification settings - Fork 729
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[WIP] Add documentation for tr.jit options #70
Conversation
Information on the fine grain debug and control knobs needs to live in the code near the knobs otherwise it will get very stale very fast. High-level overviews like how to log, how to control compilation etc are good to document in this kind of how-to, but low-level details need to live in the code near their use in my opinion. |
While it is a |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
doc/compiler/
exists for documenting things about the compiler in OpenJ9, though, it could make sense to retitle to JIT (though, with AOTs involvement, ¯\_(ツ)_/¯)- It's comparatively rare for people to refer to this as
tr.jit
; the OpenJ9 JIT, Testarossa are both names that seem to be in more common use.
doc/jit.md
Outdated
@@ -0,0 +1,44 @@ | |||
# Testarossa JIT (tr.jit) compiler | |||
|
|||
Testarossa JIT compiler is a high performant dynamic compiler that powers openj9 - an enterprise-grade Java Virtual Machine (JVM). It's characteristic features are to compress the application code for improved runtime performance by exploiting the exact host CPU model and apply profiling on the runtime behavior of the generated code, feed it back to the optimizer to further refine it. The component provides a wide range of command line options to (i) trace the actions of the compilation and the compiled code, and (ii) control the compiler behavior. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- 'high performance', or 'highly performant'
- 'OpenJ9', not 'openj9'
- Talking in the abstract about the component is odd -- I'd instead simply talk about the 'compiler'
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thanks @mgaudet - made those changes.
While care is taken at the design itself to derive optimal performance under default configurations for the most common workloads, these command line options help to derive insight into the efficiency of the compiler for a given workload, and fine tune the compilation behavior for maximizing the runtime performance / throughput. | ||
|
||
|
||
This page contains the full list of compiler options that are classified into: (i) optimization control knob options (which generally takes the form of enable | disable syntax), (ii) trace options (which generally take the form of traceXXX syntax), and (iii) debug options (which generally helps to manually control the execution on a specific compilation / compiled code event) and (iv) Environment variables that influences the behavior of JVMs that are spawned within that environment. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I tend to agree with Andrew, that detail should probably not live in this document; doubly so since a good chunk of this would end up reproducing the Testarossa Problem Determination Guide from OMR
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+1 to creating a problem determination guide or linking to the IBM J9 documentation given that there's existing documentation for many of the components there.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To clarify, the PD is not the main intent of this document. Excerpt from #33:
- Users to gain insight into the (so far) under-documented tr jit features, take advantage of it by applying fine grained compiler customizations based on the specific environment and workload.
- Community members to better acquiant with the optimizations, hack around with the code with ease, get upto speed for large scale collaboration.
However, I have now linked the section with the PD guide from Eclipse OMR page.
|
||
## Control options | ||
|
||
### Disable JIT |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I almost think it would be best to document -Xtrace
first :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thanks - sure, I will try to place a one liner for Xtrace
. I will keep it minimal as:
-Xtrace
usage in this document will be limited,- the limited usage of it here will be mostly intuitive to the readers.
Disabling the JIT is a very coarse tool - initial docs would be on logging a method, gathering vlogs etc which are things we have already discussed in some items here on the project. |
…ch as possible with the help of a sample code. Build incrementally, if possible by wider set of contributors, through squash and merge. Fixes: eclipse-openj9#33 Signed-off-by: Gireesh Punathil <[email protected]>
b3e9f38
to
86feaf1
Compare
Have left some comments above. In general, please consider this doc with the view of:
|
Thanks @andrewcraik - agree that |
Please add |
@DanHeidinga - sure, will follow that next time. |
@gireeshpunathil your enthusiasm and interest in OpenJ9 is very appreciated! The direction we should be taking for the initial set of documentation for the JIT (and frankly, all components) is to guide users and developers to:
These topics are covered in the OMR problem determination (PD) guide. OpenJ9 should provide link to that document and enhance it for Java-specific JIT PD.
End users should never have to fine tune the JIT to get maximum performance. When a user has to resort to esoteric options to control compilation, we as JVM developers have missed the boat. If the first google result is a page of JIT compilation options, the project is setting the wrong expectation for users. I'll repeat @andrewcraik's comment from above:
If you're interested in documenting those options, great! Please do so as comments directly in the code base where developers who may be working with them will see them, not as end user documentation. Thanks for interest and work on OpenJ9. |
If it is an external optimization option, that can be set from the command line or through system properties, how can it be documented only in the code ? We have three different personas that are the consumers of the OpenJ9 project - 1. a Virtual Machine developer or enthusiast who knows or wants to know the VM internals and wants to contribute to the OpenJ9, 2. a Cloud service administrator / Cloud dev-ops engineer / Cloud / SaaS support engineer who needs to deploy J9 based Runtime and 3. a Java Cloud application developer who wants to get the optimal performance from their Java application. What @DanHeidinga said above
makes perfect sense for persona 1. As a car driver (3), I do not want to look at the engine under the hood or even inside the wheel to know the optimal air pressure to have in my tires. |
@samkamer I still respectfully disagree. Experimental options added by developers for debugging and testing are not something personas 2 and 3 should care about or look at - they are not necessarily stable and should not be used in production settings. In general, failure of the JIT to perform under default settings is a bug - the JIT control logic is not working right or there is an optimization bug. I would rather have those issues brought to the community for them to be analyzed, explored and understood. We can then make improvements that benefit everyone and make things work even better out-of-the-box. If options proliferate in everyday usage and, as a community, we encourage that then changes in options etc will break people and worse, general performance improvements may not be seen. Documentation on how to log a failure and basic diagnostic options is a good idea since those are what people need to do to bring an issue to the community for discussion. Once you move beyond the diagnostic gathering you are going to be look at the code and so in code documentation should be fine and will remain more current. |
No disagreement there about experimental options. |
The tried and tested optimization options generally not -Xjit options - things like -Xquickstart, -Xshareclassess etc. Pretty much all of the options under -Xjit are for debug and experimentation. They are not generally used in production since the combination of more official -X options combined with the JIT logic should be enough. We may wish to document a few debugging strategies, but with only a very limited set of options. Documentation around perf analysis and how to bring the right data is certainly a good idea. Making sure everyone can bring perf issues to the table for discussion is very important in us having a great community and a good user run experience so I am very supportive of this aspect of the effort. |
The goal is to provide as much documentation around
Possibly with the help of a sample code, input and output.
Build incrementally, if possible by wider set of contributors.
Fixes: #33
Signed-off-by: Gireesh Punathil [email protected]