Adding Mac platform support to the user docs #82

SueChaplain · 2018-09-10T17:01:33Z

Work at OpenJ9 to port to Mac:

@DanHeidinga We need to plan any changes to the user documentation that are required for the Mac port at OpenJ9.

update to the support topic, including platform support and build environment
across the doc we mention differences per platform. What differences will exist for Mac?
- supported options
- supported GC policies
- any limitations etc

As the work progresses, perhaps the team can add any relevant notes here please?

DanHeidinga · 2018-09-10T17:15:40Z

The work is currently being tracked in eclipse-openj9/openj9#36

SueChaplain · 2018-11-07T15:52:56Z

macos.xlsx
@DanHeidinga - please can you get someone to go through this spreadsheet and provide the input for macOS?

SueChaplain · 2018-12-04T09:38:54Z

@babsingh - is this something you can help with please? The user docs have very little information about macOS and users will want to understand which options are supported / which GC policies etc.

babsingh · 2018-12-04T21:49:13Z

Majority of Linux documentation should be applicable to MacOS. There are few outliers. As a starting point, we can replicate Linux x86 documentation for OSX.

Answering doubts raised within macos.xlsx:

[GC] Currently, GC policy metronome is not supported on OSX. It might be enabled on OSX if they can support high-resolution clock. All other GC policies supported on Linux should be available on OSX. @dmitripivkine can you confirm this?
[GC] -Xconcurrentbackground is set to 1 by default on OSX. @dmitripivkine can you confirm this?
[JIT] @0xdaryl @nbhuiyan Is -Xjit/-Xnojit documentation valid for OSX? Is it identical to Linux x86?
[JIT/VM] -Xlp, -Xlp:codecache, -Xlp:objectheap behavior on OSX and Linux x86 should be the same. @0xdaryl @nbhuiyan @pshipton do you agree?
[VM] -Dcom.ibm.tools.attach.enable=[yes|no] is enabled by default on OSX similar to Linux.
[VM] -Xtrace behavior on OSX and Linux should be the same.
[VM] -Xdump behavior on OSX and Linux should be the same. Currently, DDR support is disabled on OSX. So, core files generated on OSX can't be viewed in jdmpview. @mikezhang1234567890 predicts DDR support to be available on OSX by Jan 2019.
[VM] -Xrs:sync behavior on OSX should be similar to behavior on other Unix platforms: Disables signal handling in the VM for SIGSEGV, SIGFPE, SIGBUS, SIGILL, SIGTRAP, and SIGABRT signals. However, the VM still handles the SIGQUIT and SIGTERM signals, among others.
[VM] -Xshareclasses behavior on OSX is identical to Linux x86. @hangshao0 can you confirm this?
[VM] For -Xthr, cfsYield | noCfsYield should be disabled on OSX. Currently, these options are enabled on OSX. Created Disable OMR_THR_YIELD_ALG on MacOS openj9#3921 and Disable OMR_THR_YIELD_ALG on MacOS eclipse-omr/omr#3283 to disable CFS support on OSX. All other -Xthr options should work on OSX.
https://www.eclipse.org/openj9/docs/openj9_defaults/ [Second table]. OSX behavior should be similar to Linux x86. @pshipton do you agree?
https://www.eclipse.org/openj9/docs/openj9_directories/ [First table]. OSX Java 8 - <install_dir>/jre/lib/default. OSX Java 11 - <install_dir>/lib/default. Unlike Linux SDKs, OSX SDKs don't have <arch> directory.
https://www.eclipse.org/openj9/docs/messages_intro/#finding-aix-messages. On Linux, messages are logged by the syslog daemon. On OSX, syslog is also available. But, Apple broke syslog on Sierra and High Sierra. On OSX, Console.app may be used if syslog - /var/log/system.log is unavailable. @DanHeidinga can you verify this?
https://www.eclipse.org/openj9/docs/env_var/. OSX behavior should be similar to Linux.

pshipton · 2018-12-04T21:58:36Z

Re -Xlp how are large pages enabled on MacOS? What large pages are available when running -verbose:sizes?

pshipton · 2018-12-04T22:01:16Z

Re https://www.eclipse.org/openj9/docs/openj9_defaults/ please confirm via providing the -verbose:sizes output.

hangshao0 · 2018-12-04T22:03:31Z

[VM] -Xshareclasses behavior on OSX is identical to Linux x86. @hangshao0 can you confirm this?

Shared class is enabled by default on Java 11 and up on all platforms except OSX.
Once eclipse-openj9/openj9#3858 is merged. Shared class will be enabled by default on Java 8 on all platforms except OSX

babsingh · 2018-12-04T22:09:09Z

-verbose:sizes output on OSX:

Java 8:
  -Xmca32K        RAM class segment increment
  -Xmco128K       ROM class segment increment
  -Xmcrs200M      compressed references metadata initial size
  -Xmns2M         initial new space size
  -Xmnx128M       maximum new space size
  -Xms8M          initial memory size
  -Xmos6M         initial old space size
  -Xmox510M       maximum old space size
  -Xmx512M        memory maximum
  -Xmr16K         remembered set size
  -Xlp:objectheap:pagesize=4K	 large page size
                  available large page sizes:
                  4K
  -Xlp:codecache:pagesize=4K	 large page size for JIT code cache
                  available large page sizes for JIT code cache:
                  4K
  -Xmso256K       operating system thread stack size
  -Xiss2K         java thread stack initial size
  -Xssi16K        java thread stack increment
  -Xss1M          java thread stack maximum size


Java 11:
  -Xmca32K        RAM class segment increment
  -Xmco128K       ROM class segment increment
  -Xmcrs200M      compressed references metadata initial size
  -Xmns2M         initial new space size
  -Xmnx1G         maximum new space size
  -Xms8M          initial memory size
  -Xmos6M         initial old space size
  -Xmox4094M      maximum old space size
  -Xmx4G          memory maximum
  -Xmr16K         remembered set size
  -Xlp:objectheap:pagesize=4K	 large page size
                  available large page sizes:
                  4K
  -Xlp:codecache:pagesize=4K	 large page size for JIT code cache
                  available large page sizes for JIT code cache:
                  4K
  -Xmso256K       operating system thread stack size
  -Xiss2K         java thread stack initial size
  -Xssi16K        java thread stack increment
  -Xss1M          java thread stack maximum size

For -Xlp:objectheap|codecache, only 4K is available for large page size.

The above information can also be used to fill the second table in https://www.eclipse.org/openj9/docs/openj9_defaults/.

babsingh · 2018-12-04T22:11:28Z

@hangshao0 are all cmdline options listed in -Xshareclasses available on OSX?

hangshao0 · 2018-12-04T22:24:46Z

are all cmdline options listed in -Xshareclasses available on OSX?

Yes

dmitripivkine · 2018-12-04T22:30:24Z

[GC] Currently, GC policy metronome is not supported on OSX. It might be enabled on OSX if they can support high-resolution clock. All other GC policies supported on Linux should be available on OSX. @dmitripivkine can you confirm this?

This is correct. Currently -Xgcpolicy:metronome is supported on xLinux and AIX only. Also Concurrent Scavenger -Xgc:concurrentScavenge is supported on xLinux but is not on OSX (can be supported in future)

[GC] -Xconcurrentbackground is set to 1 by default on OSX. @dmitripivkine can you confirm this?

This is correct. The default value for -Xconcurrentbackground is set to 1 for all platforms except zLinux

dmitripivkine · 2018-12-04T22:34:20Z

-Xlp behaviour is not the same as far as we have support for 4K pages only on OSX (xLinux supports Huge pages and we would try to use them by default)

SueChaplain · 2018-12-06T10:28:43Z

Thanks for all the input here. What would be really helpful is if someone could download the spreadsheet in the earlier comment (#82 (comment)) and update that. Then we know we have covered all the content we need.

babsingh · 2018-12-06T19:11:54Z

I will update the spread sheet once the JIT team responds to the below question:

[JIT] @0xdaryl @nbhuiyan Is -Xjit/-Xnojit documentation (https://www.eclipse.org/openj9/docs/xjit/) valid for OSX? Are there any special cases for Xjit/-Xnojit on OSX?

@SueChaplain in the spreadsheet, should i assume yes for empty slots in the macOS column C with no doubts? or do we need to verify all options in the spreadsheet?

nbhuiyan · 2018-12-10T17:11:17Z

@babsingh -Xjit and -Xnojit works on macOS the same way it does on Linux on x86-64. So far, I have not come across any case of a parameter working on x86-64 Linux and not on macOS.

babsingh · 2018-12-11T00:01:27Z

@SueChaplain would you like me to verify all options in the spreadsheet or just the ones with a doubt associated?

SueChaplain · 2018-12-11T09:25:15Z

@babsingh - please can you run your eye over all of them? I made some assumptions about ones that probably didn't apply or might have some differences but I'm not really best placed to do that.

SueChaplain · 2019-01-03T13:17:34Z

Hi @babsingh - how is this work progressing please? I'm just back from the Christmas break and wondering if we can handle this work in our first iteration this year. Thanks!

babsingh · 2019-01-03T14:19:29Z

@SueChaplain before vacation, i had reviewed half of the list. i still have to review the remaining half of the list. when is the first iteration due?

SueChaplain · 2019-01-03T14:28:51Z

@babsingh Iteration is due 14 Jan. I figured that we need the docs complete for 0.12.0 as we will be claiming full support for macOS by this date. Depends how much work is needed, but leaving it until the next iteration might make things too tight. Appreciate you have a lot going on though!

babsingh · 2019-01-03T14:34:43Z

@SueChaplain i will provide a first draft tomorrow.

babsingh · 2019-01-04T21:09:03Z

Updated excel: macos-babneet.xlsx. I have filled column C (macOS? yes/no). I have used column D and column F for questions/notes. Added Column E; it contains a link to the online documentation for each option.

Questions for @DanHeidinga or @pshipton -

-Xcheck:dump doesn't work on OSX because function J9RASCheckDump is unimplemented for OSX in OpenJ9. -Xcheck:dump seems relevant for OSX. Do you guys agree? If so, I will open an OpenJ9 issue to add OSX support for -Xcheck:dump.
Should -Xnuma:none and -XX:[+|-]InterleaveMemory be disabled on OSX due to absence of NUMA support?
- OSX doesn't have NUMA support: https://news.ycombinator.com/item?id=9500592.
- Instead, OSX has a thread affinity API: https://developer.apple.com/library/archive/releasenotes/Performance/RN-AffinityAPI.
- On Mac Pros with Xeon processors, QPI, Intel's implementation of NUMA, takes place fully within the processor just as HyperTransport is AMDs.
Should -XX:[+|-]IdleTuningCompactOnIdle, -XX:[+|-]IdleTuningGcOnIdle,-XX:IdleTuningMinFreeHeapOnIdle and -XX:IdleTuningMinIdleWaitTime be supported on OSX? The first three options are used by the GC and enabled by the J9VM_GC_IDLE_HEAP_MANAGER flag. J9VM_GC_IDLE_HEAP_MANAGER is enabled on OSX since Linux spec files were used to create OSX spec files. The fourth option is always enabled, used by the JIT and related to the first three options. The online doc says that the four options are only supported on Linux. After looking at the code, all four options should work on OSX. I am not sure if we want to support these options on OSX.
Currently, -Xthr:cfsYield | noCfsYield is enabled on OSX. Since OSX doesn't have a Completely Fair Scheduler, this feature should be disabled on OSX. Created Disable OMR_THR_YIELD_ALG on MacOS openj9#3921 to disable -Xthr:cfsYield | noCfsYield on OSX.
-XtlhPrefetch is only supported on AIX and Windows. But, -XtlhPrefetch gets accepted as cmdline option on Linux, OSX and other platforms. Should -XtlhPrefetch be unrecognized on unsupported platforms?
In the documentation of -Xtrace, there is a reference to ibm_gpu component, which represents class library graphics processing unit (GPU) native code (supported on Linux only). I am guessing ibm_gpu component won't be supported on OSX. Can you confirm this?
Other than NLS messages, I couldn't find the source code or history related to -Xrdbginfo in OpenJ9. What happens to the documentation of -Xrdbginfo? Do we remove it or do we keep it with a note?
For -Xshareclasses, I have assumed that the Linux content applies to OSX. Is this assumption correct? Also, I have proposed that "an OSX user may need to set, kern.sysv.shmmax and kern.sysv.shmall, for shared classes to work".
In the -Xdump documentation, there is a section named System dumps on Linux at the end. Should we add a section for System dumps on OSX since system dumps may not generate by default on OSX?

Modify command line topics to indicate which ones do/don't apply to OS X, plus any specific information for this platform. Updates also for the directory conventions topic, environment variables topic, and messages. Closes: eclipse-openj9#82 Signed-off-by: Sue Chaplain <[email protected]>

SueChaplain · 2019-01-07T15:42:55Z

Whilst working through the list I have the following additional questions:

On OS X, what is the equivalent variable for LIBPATH (AIX) and LD_LIBRARY_PATH (Linux)
Please confirm ulimits also apply on OS X and might need increasing under similar circumstances to AIX/Linux.

pshipton · 2019-01-07T16:16:21Z

Agree
What do you mean by "disabled"? The options can still be parsed. i.e. z/OS recognizes -Xnuma:none
We should not claim support for these options on MacOS until such time as they have been confirmed working. Based on some softmx test results, I'm not sure madvise(..., MADV_DONTNEED) gives the same behavior as Linux.
Ok.
Accepting the option on unsupported platforms is fine.
I believe the ibm_gpu trace component is obsolete on all platforms, the code was re-written before OpenJ9 was created. GPU may be supported on macOS in the future, but an NVIDIA gpu is required, which I don't believe is a common occurrence.
-Xrdbginfo is obsolete and should be removed from the doc
Yes, -Xshareclasses support is the same as Linux. Setting kern.sysv.shmmax and kern.sysv.shmall is only required to use the nonpersistent -Xshareclasses option, which is not the default.
Makes sense to describe any special behavior on MacOS.

babsingh · 2019-01-07T17:31:42Z

fyi - @pshipton

What do you mean by "disabled"? The options can still be parsed. i.e. z/OS recognizes -Xnuma:none

"disabled": should options -Xnuma:none and -XX:[+|-]InterleaveMemory be unrecognized since they are unsupported on OSX? Based upon prior answers, accepting the options on unsupported platforms is fine. But, we should not claim support in the documentation until the options are confirmed to be working.

fyi - @SueChaplain

On OS X, what is the equivalent variable for LIBPATH (AIX) and LD_LIBRARY_PATH (Linux)

The equivalent variable is DYLD_LIBRARY_PATH: eclipse-openj9/openj9#3765.

Please confirm ulimits also apply on OS X and might need increasing under similar circumstances to AIX/Linux.

ulimit works on OSX. On OSX, resource limits can be set using launchctl, ulimit, or kern.<VARIABLES>. Also, instructions on setting resource limits vary depending upon OSX version:

Modify command line topics to indicate which ones do/don't apply to OS X, plus any specific information for this platform. Updates also for the directory conventions topic, environment variables topic, and messages. Closes: eclipse-openj9#82 Signed-off-by: Sue Chaplain <[email protected]>

SueChaplain added the enhancement label Sep 10, 2018

SueChaplain self-assigned this Oct 16, 2018

SueChaplain mentioned this issue Dec 17, 2018

Add defaults settings for macOS & fix env vars #167

Merged

SueChaplain mentioned this issue Jan 7, 2019

Add information for macOS into the user docs #180

Merged

doveye closed this as completed in #180 Jan 14, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding Mac platform support to the user docs #82

Adding Mac platform support to the user docs #82

SueChaplain commented Sep 10, 2018 •

edited

Loading

DanHeidinga commented Sep 10, 2018

SueChaplain commented Nov 7, 2018

SueChaplain commented Dec 4, 2018

babsingh commented Dec 4, 2018 •

edited

Loading

pshipton commented Dec 4, 2018

pshipton commented Dec 4, 2018

hangshao0 commented Dec 4, 2018 •

edited

Loading

babsingh commented Dec 4, 2018 •

edited

Loading

babsingh commented Dec 4, 2018

hangshao0 commented Dec 4, 2018

dmitripivkine commented Dec 4, 2018 •

edited

Loading

dmitripivkine commented Dec 4, 2018 •

edited

Loading

SueChaplain commented Dec 6, 2018 •

edited

Loading

babsingh commented Dec 6, 2018 •

edited

Loading

nbhuiyan commented Dec 10, 2018

babsingh commented Dec 11, 2018

SueChaplain commented Dec 11, 2018

SueChaplain commented Jan 3, 2019

babsingh commented Jan 3, 2019

SueChaplain commented Jan 3, 2019

babsingh commented Jan 3, 2019

babsingh commented Jan 4, 2019 •

edited

Loading

SueChaplain commented Jan 7, 2019

pshipton commented Jan 7, 2019 •

edited

Loading

babsingh commented Jan 7, 2019 •

edited

Loading

Adding Mac platform support to the user docs #82

Adding Mac platform support to the user docs #82

Comments

SueChaplain commented Sep 10, 2018 • edited Loading

DanHeidinga commented Sep 10, 2018

SueChaplain commented Nov 7, 2018

SueChaplain commented Dec 4, 2018

babsingh commented Dec 4, 2018 • edited Loading

pshipton commented Dec 4, 2018

pshipton commented Dec 4, 2018

hangshao0 commented Dec 4, 2018 • edited Loading

babsingh commented Dec 4, 2018 • edited Loading

babsingh commented Dec 4, 2018

hangshao0 commented Dec 4, 2018

dmitripivkine commented Dec 4, 2018 • edited Loading

dmitripivkine commented Dec 4, 2018 • edited Loading

SueChaplain commented Dec 6, 2018 • edited Loading

babsingh commented Dec 6, 2018 • edited Loading

nbhuiyan commented Dec 10, 2018

babsingh commented Dec 11, 2018

SueChaplain commented Dec 11, 2018

SueChaplain commented Jan 3, 2019

babsingh commented Jan 3, 2019

SueChaplain commented Jan 3, 2019

babsingh commented Jan 3, 2019

babsingh commented Jan 4, 2019 • edited Loading

SueChaplain commented Jan 7, 2019

pshipton commented Jan 7, 2019 • edited Loading

babsingh commented Jan 7, 2019 • edited Loading

SueChaplain commented Sep 10, 2018 •

edited

Loading

babsingh commented Dec 4, 2018 •

edited

Loading

hangshao0 commented Dec 4, 2018 •

edited

Loading

babsingh commented Dec 4, 2018 •

edited

Loading

dmitripivkine commented Dec 4, 2018 •

edited

Loading

dmitripivkine commented Dec 4, 2018 •

edited

Loading

SueChaplain commented Dec 6, 2018 •

edited

Loading

babsingh commented Dec 6, 2018 •

edited

Loading

babsingh commented Jan 4, 2019 •

edited

Loading

pshipton commented Jan 7, 2019 •

edited

Loading

babsingh commented Jan 7, 2019 •

edited

Loading