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

NAME

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

SYNOPSIS

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

DESCRIPTION

     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) com-
     mands 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.

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

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

EXAMPLES

     $ 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

PLIST PROPERTIES

     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 specified:

     GPUEjectPolicy
	     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 out-
	     put):

	     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.

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

SEE ALSO

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

HISTORY

     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