document tr.jit options

[gireeshpunathil]

It would be worthwhile to document the hidden treasures of trjjit optimizations (a significant portion of j9options.cpp) for:

• 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.

[gireeshpunathil]

I propose to have this format:

optimization name
usage:
meaning:
(optional) code sample:
caveat / side effect / caution:
link to any literature on the underlying optimization:

I am happy to get started / involed. Please 👍 on this to join this initiative.

[0xdaryl]

Great initiative! You are actually suggesting two important efforts here: the documentation of optimizations themselves, and the documentation of control knobs to allow finer grain control of those optimizations and many other aspects of the J9 JIT.

The Eclipse OMR project has begun to document optimizations where it can (it's an ongoing effort). Many of these optimizations are leveraged directly or extended by OpenJ9. The goal there is to provide as much documentation as close to the actual source code as possible. I think a similar effort as you propose for OpenJ9 is important too, and will set the proper context for documenting many of the J9Option knobs that control them.

For documenting the internal options, because many of them are fleeting or experimental I'd say its important to keep their documentation as close to the code as possible as well to ensure they stay current. Also, be aware that the JIT does make use of environment variables (usually queried with calls to feGetEnv) to guard and control some features as well. These are even more undocumented than J9Options (!) and often guard experimental and debug code, or are used in places in the JIT where an Options object is not available.

[DanHeidinga]

Closing this as there has been no action in many months and the suggested direction has been to document the options directly in the code.