SafeEjectGPU(8)              System Manager's Manual             SafeEjectGPU(8)

     SafeEjectGPU – Facilitate safe eject/disconnect of eGPU(s) from system

     SafeEjectGPU [gpuid <gpuid>] [gpuids <gpuid1>,<gpuid2>,...] [gpus] [apps]
                  [status] [Eject] [Initiate] [Relaunch] [Finalize] [Cancel]
                  [RelaunchPID <PID>] ...

     The SafeEjectGPU command is used to prepare for safe eject/disconnect of
     eGPUs from the system.  This involves interacting with apps to migrate off
     of ejecting eGPU(s), and triggering the eject itself.  This tool can also
     be used to view what GPUs are attached to the system, their eject status,
     and what apps hold references to each.

     A list of commands and their descriptions - note that commands affecting
     state are capitalized, and that multiple (including repeated) commands can
     occupy the same command line:

     gpus               Lists attributes of GPUs currently attached to system
                        (gpuid, vendor/model, flags)

     gpuid <gpuid>      Specifies which GPU(s) subsequent commands apply to.
                        The default (0x0000) means all eGPUs.  See output of
                        gpus command for valid <gpuid> values (of the form
                        0x7005) to use.

     gpuids <gpuid1>,...
                        Comma seperated list of GPU(s) for the app to select
                        from. See output of gpus command for valid <gpuid>
                        values (of the form 0x7005) to use.

     apps               Lists apps holding references to specified GPU - and app
                        attributes/properties like PID, RPID, USER, PROCESS,
                        APIS (Metal, GL/CL, GVA), BUNDLE_IDENTIFIER, PATH,
                        GPUEjectPolicy and GPUSelectionPolicy where specified.

     status             Shows eject state of specified eGPU(s) (Present,
                        Initiated, Finalized).

     Eject              Performs the full Eject sequence ( Initiate + Relaunch +
                        Finalize ) of specified GPU(s).

     Initiate           Initiates eject of specified eGPU(s).  These eGPUs are
                        temporarily hidden from API instantiations.

     Relaunch           Interacts with apps that hold references to specified
                        eGPU(s) - to facilitate migration to remaining GPUs.

     Finalize           Finalizes eject of specified eGPU(s) - must be
                        physically unplugged before they can be used again.

     Cancel             Cancels initiated eject of specified GPU(s) - instead of

     RelaunchPID <PID>  Apply relaunch stimulus to one particular PID - for app
                        relaunch stimulus testing.

     RelaunchPIDOnGPU <PID>
                        Apply relaunch stimulus to one particular PID with set
                        of limited GPUs to select from, use gpuids to limit the
                        GPUs seen by an app.

     LaunchOnGPU <path>
                        Launch application from given bundle path with set of
                        limited GPUs, use gpuids to limit the GPUs seen by an
                        app. If the instance of an app is already running, this
                        command has no effect.

     $ SafeEjectGPU gpus
     List eGPUs.  Output is useful for cut-n-paste of example specified gpuid
     values used below $ SafeEjectGPU gpus apps status
     List all eGPUs and Apps on all eGPUs along with eject status of all eGPUs

     $ SafeEjectGPU Eject
     Perform full Eject sequence on all eGPUs

     $ SafeEjectGPU gpuid 0x7005 Eject
     Perform full Eject sequence on specified eGPU

     $ SafeEjectGPU gpus apps gpuid 0x7153 apps
     Lists all eGPUs and apps on all eGPUs and on integrated GPU as well

     $ SafeEjectGPU Initiate RelaunchPID 12345 Cancel
     Hide eGPUs and send relaunch stimulus to PID without doing full eject

     $ SafeEjectGPU gpuids 0x7005,0x7153 RelaunchPIDOnGPU <pid>
     Limits GPU selection for PID to either eGPU or Integrated GPU on relaunch

     $ SafeEjectGPU gpuids 0x7005 LaunchOnGPU /Applications/
     Launches calculator app on specified eGPU

     The following properties are generally inferred.  Some values can be
     specified in the app's Info.plist.  They affect eGPU eject and API
     selection behaviors.  Generally, these properties won't need to be

             Inferred/Settable GPUEjectPolicy values for dealing with apps that
             needs to drop references to ejecting eGPU.  Establisehd in app
             bundle's Info.plist.  Possible values:

             relaunch   Send AppKit quit-with-save event followed by open-with-
                        restore (relaunch app using alternate GPU(s)).

             wait       Just wait for GPU references to drop (without sending
                        events or signals).

             kill       Use sigKill to force app exit (for apps that will
                        relaunch via launchd - using alternate GPU(s)).

             ignore     Ignore - necessary for some internal GPU/display
                        components - working to eliminate its use.

             Inferred-Only GPUEjectPolicy values (you can't specify these
             values, but you'll see them as defaulted/inferred policies in apps

             wrelaunch  Wait momentarily for processing of Metal GPU change
                        notifications before resorting to relaunch
                         (as necessary).

             jrelaunch  Just relaunch
                         without waiting (since OpenGL/OpenCL are in use).

             rwait      When a process is subordinate to another, "responsible",
                        process (see RPID column), Eject actions apply to the
                        responsible process, who in turn deals with subordinates
                        to eliminate their ejecting eGPU references.

              Settable values that affect instantiation of Metal and OpenGL/CL
              contexts (wrt eGPU use).  Established in app bundle's Info.plist.
              Possible values:

              avoidRemovable   Avoid creation of MTLCommandQueues, and OpenGL/CL
                               contexts on eGPUs.

              preferRemovable  Prefer creation of MTLCommandQueues, and
                               OpenGL/CL contexts on eGPUs.

     plist(5) sudo(8) launchd(8)

     The command line SafeEjectGPU tool first appeared in the 10.13.4 release of
     Mac OS X.

Mac OS X                        January 22, 2018                        Mac OS X