Manual switching and manual power control¶

In this mode of use, the file /sys/kernel/debug/vgaswitcheroo/switchcan be read to retrieve the current vga_switcheroo state and commandscan be written to it to change the state. The file appears as soon astwo GPU drivers and one handler have registered with vga_switcheroo.The following commands are understood:

• OFF: Power off the device not in use.
• ON: Power on the device not in use.
• IGD: Switch to the integrated graphics device.Power on the integrated GPU if necessary, power off the discrete GPU.Prerequisite is that no user space processes (e.g. Xorg, alsactl)have opened device files of the GPUs or the audio client. If theswitch fails, the user may invoke lsof(8) or fuser(1) on /dev/dri/and /dev/snd/controlC1 to identify processes blocking the switch.
• DIS: Switch to the discrete graphics device.
• DIGD: Delayed switch to the integrated graphics device.This will perform the switch once the last user space process hasclosed the device files of the GPUs and the audio client.
• DDIS: Delayed switch to the discrete graphics device.
• MIGD: Mux-only switch to the integrated graphics device.Does not remap console or change the power state of either gpu.If the integrated GPU is currently off, the screen will turn black.If it is on, the screen will show whatever happens to be in VRAM.Either way, the user has to blindly enter the command to switch back.
• MDIS: Mux-only switch to the discrete graphics device.

For GPUs whose power state is controlled by the driver’s runtime pm,the ON and OFF commands are a no-op (see next section).

For muxless machines, the IGD/DIS, DIGD/DDIS and MIGD/MDIS commandsshould not be used.

Driver power control¶

In this mode of use, the discrete GPU automatically powers up and down atthe discretion of the driver’s runtime pm. On muxed machines, the user maystill influence the muxer state by way of the debugfs interface, howeverthe ON and OFF commands become a no-op for the discrete GPU.

This mode is the default on Nvidia HybridPower/Optimus and ATI PowerXpress.Specifying nouveau.runpm=0, radeon.runpm=0 or amdgpu.runpm=0 on the kernelcommand line disables it.

After the GPU has been suspended, the handler needs to be called to cutpower to the GPU. Likewise it needs to reinstate power before the GPUcan resume. This is achieved byvga_switcheroo_init_domain_pm_ops(),which augments the GPU’s suspend/resume functions by the requisitecalls to the handler.

When the audio device resumes, the GPU needs to be woken. This is achievedby a PCI quirk which callsdevice_link_add() to declare a dependency on theGPU. That way, the GPU is kept awake whenever and as long as the audiodevice is in use.

On muxed machines, if the mux is initially switched to the discrete GPU,the user ends up with a black screen when the GPU powers down after boot.As a workaround, the mux is forced to the integrated GPU on runtime suspend,cf.https://bugs.freedesktop.org/show_bug.cgi?id=75917

Public functions¶

intvga_switcheroo_register_handler(const structvga_switcheroo_handler * handler, enumvga_switcheroo_handler_flags_t handler_flags)¶

register handler

Parameters

conststructvga_switcheroo_handler*handler

handler callbacks

enumvga_switcheroo_handler_flags_thandler_flags

handler flags

Description

Register handler. Enable vga_switcheroo if two vga clients have alreadyregistered.

Return

0 on success, -EINVAL if a handler was already registered.

voidvga_switcheroo_unregister_handler(void)¶

unregister handler

Parameters

void

no arguments

Description

Unregister handler. Disable vga_switcheroo.

enumvga_switcheroo_handler_flags_tvga_switcheroo_handler_flags(void)¶

obtain handler flags

Parameters

void

no arguments

Description

Helper for clients to obtain the handler flags bitmask.

Return

Handler flags. A value of 0 means that no handler is registeredor that the handler has no special capabilities.

intvga_switcheroo_register_client(struct pci_dev * pdev, const structvga_switcheroo_client_ops * ops, bool driver_power_control)¶

register vga client

Parameters

structpci_dev*pdev

client pci device

conststructvga_switcheroo_client_ops*ops

client callbacks

booldriver_power_control

whether power state is controlled by the driver’sruntime pm

Description

Register vga client (GPU). Enable vga_switcheroo if another GPU and ahandler have already registered. The power state of the client is assumedto be ON. Beforehand,vga_switcheroo_client_probe_defer() shall be calledto ensure that all prerequisites are met.

Return

0 on success, -ENOMEM on memory allocation error.

intvga_switcheroo_register_audio_client(struct pci_dev * pdev, const structvga_switcheroo_client_ops * ops, struct pci_dev * vga_dev)¶

register audio client

Parameters

structpci_dev*pdev

client pci device

conststructvga_switcheroo_client_ops*ops

client callbacks

structpci_dev*vga_dev

pci device which is bound to current audio client

Description

Register audio client (audio device on a GPU). The client is assumedto use runtime PM. Beforehand,vga_switcheroo_client_probe_defer()shall be called to ensure that all prerequisites are met.

Return

0 on success, -ENOMEM on memory allocation error, -EINVAL on gettingclient id error.

boolvga_switcheroo_client_probe_defer(struct pci_dev * pdev)¶

whether to defer probing a given client

Parameters

structpci_dev*pdev

client pci device

Description

Determine whether any prerequisites are not fulfilled to probe a givenclient. Drivers shall invoke this early on in their ->probe callbackand return-EPROBE_DEFER if it evaluates totrue. Thou shalt notregister the client ere thou hast called this.

Return

true if probing should be deferred, otherwisefalse.

enumvga_switcheroo_statevga_switcheroo_get_client_state(struct pci_dev * pdev)¶

obtain power state of a given client

Parameters

structpci_dev*pdev

client pci device

Description

Obtain power state of a given client as seen from vga_switcheroo.The function is only called from hda_intel.c.

Return

Power state.

voidvga_switcheroo_unregister_client(struct pci_dev * pdev)¶

unregister client

Parameters

structpci_dev*pdev

client pci device

Description

Unregister client. Disable vga_switcheroo if this is a vga client (GPU).

voidvga_switcheroo_client_fb_set(struct pci_dev * pdev, struct fb_info * info)¶

set framebuffer of a given client

Parameters

structpci_dev*pdev

client pci device

structfb_info*info

framebuffer

Description

Set framebuffer of a given client. The console will be remapped to thison switching.

intvga_switcheroo_lock_ddc(struct pci_dev * pdev)¶

temporarily switch DDC lines to a given client

Parameters

structpci_dev*pdev

client pci device

Description

Temporarily switch DDC lines to the client identified bypdev(but leave the outputs otherwise switched to where they are).This allows the inactive client to probe EDID. The DDC lines mustafterwards be switched back by callingvga_switcheroo_unlock_ddc(),even if this function returns an error.

Return

Previous DDC owner on success or a negative int on error.Specifically,-ENODEV if no handler has registered or if the handlerdoes not support switching the DDC lines. Also, a negative valuereturned by the handler is propagated back to the caller.The return value has merely an informational purpose for any callerwhich might be interested in it. It is acceptable to ignore the returnvalue and simply rely on the result of the subsequent EDID probe,which will beNULL if DDC switching failed.

intvga_switcheroo_unlock_ddc(struct pci_dev * pdev)¶

switch DDC lines back to previous owner

Parameters

structpci_dev*pdev

client pci device

Description

Switch DDC lines back to the previous owner after callingvga_switcheroo_lock_ddc(). This must be called even ifvga_switcheroo_lock_ddc() returned an error.

Return

Previous DDC owner on success (i.e. the client identifier ofpdev)or a negative int on error.Specifically,-ENODEV if no handler has registered or if the handlerdoes not support switching the DDC lines. Also, a negative valuereturned by the handler is propagated back to the caller.Finally, invoking this function without callingvga_switcheroo_lock_ddc()first is not allowed and will result in-EINVAL.

intvga_switcheroo_process_delayed_switch(void)¶

helper for delayed switching

Parameters

void

no arguments

Description

Process a delayed switch if one is pending. DRM drivers should call thisfrom their ->lastclose callback.

Return

0 on success. -EINVAL if no delayed switch is pending, if the clienthas unregistered in the meantime or if there are other clients blocking theswitch. If the actual switch fails, an error is reported and 0 is returned.

intvga_switcheroo_init_domain_pm_ops(structdevice * dev, structdev_pm_domain * domain)¶

helper for driver power control

Parameters

structdevice*dev

vga client device

structdev_pm_domain*domain

power domain

Description

Helper for GPUs whose power state is controlled by the driver’s runtime pm.After the GPU has been suspended, the handler needs to be called to cutpower to the GPU. Likewise it needs to reinstate power before the GPUcan resume. To this end, this helper augments the suspend/resume functionsby the requisite calls to the handler. It needs only be called on platformswhere the power switch is separate to the device being powered down.

Public structures¶

structvga_switcheroo_handler¶

handler callbacks

Definition

struct vga_switcheroo_handler {  int (*init)(void);  int (*switchto)(enum vga_switcheroo_client_id id);  int (*switch_ddc)(enum vga_switcheroo_client_id id);  int (*power_state)(enum vga_switcheroo_client_id id, enum vga_switcheroo_state state);  enum vga_switcheroo_client_id (*get_client_id)(struct pci_dev *pdev);};

Members

init

initialize handler.Optional. This gets called when vga_switcheroo is enabled, i.e. whentwo vga clients have registered. It allows the handler to performsome delayed initialization that depends on the existence of thevga clients. Currently only the radeon and amdgpu drivers use this.The return value is ignored

switchto

switch outputs to given client.Mandatory. For muxless machines this should be a no-op. Returning 0denotes success, anything else failure (in which case the switch isaborted)

switch_ddc

switch DDC lines to given client.Optional. Should return the previous DDC owner on success or anegative int on failure

power_state

cut or reinstate power of given client.Optional. The return value is ignored

get_client_id

determine if given pci device is integrated or discrete GPU.Mandatory

Description

Handler callbacks. The multiplexer itself. Theswitchto andget_client_idmethods are mandatory, all others may be set to NULL.

structvga_switcheroo_client_ops¶

client callbacks

Definition

struct vga_switcheroo_client_ops {  void (*set_gpu_state)(struct pci_dev *dev, enum vga_switcheroo_state);  void (*reprobe)(struct pci_dev *dev);  bool (*can_switch)(struct pci_dev *dev);  void (*gpu_bound)(struct pci_dev *dev, enum vga_switcheroo_client_id);};

Members

set_gpu_state

do the equivalent of suspend/resume for the card.Mandatory. This should not cut power to the discrete GPU,which is the job of the handler

reprobe

poll outputs.Optional. This gets called after waking the GPU and switchingthe outputs to it

can_switch

check if the device is in a position to switch now.Mandatory. The client should return false if a user space processhas one of its device files open

gpu_bound

notify the client id to audio client when the GPU is bound.

Description

Client callbacks. A client can be either a GPU or an audio device on a GPU.Theset_gpu_state andcan_switch methods are mandatory,reprobe may beset to NULL. For audio clients, thereprobe member is bogus.OTOH,gpu_bound is only for audio clients, and not used for GPU clients.

Public constants¶

enumvga_switcheroo_handler_flags_t¶

handler flags bitmask

Constants

VGA_SWITCHEROO_CAN_SWITCH_DDC

whether the handler is able to switch theDDC lines separately. This signals to clients that they should calldrm_get_edid_switcheroo() to probe the EDID

VGA_SWITCHEROO_NEEDS_EDP_CONFIG

whether the handler is unable to switchthe AUX channel separately. This signals to clients that the activeGPU needs to train the link and communicate the link parameters to theinactive GPU (mediated by vga_switcheroo). The inactive GPU may thenskip the AUX handshake and set up its output with these pre-calibratedvalues (DisplayPort specification v1.1a, section 2.5.3.3)

Description

Handler flags bitmask. Used by handlers to declare their capabilities uponregistering with vga_switcheroo.

enumvga_switcheroo_client_id¶

client identifier

Constants

VGA_SWITCHEROO_UNKNOWN_ID

initial identifier assigned to vga clients.Determining the id requires the handler, so GPUs are given theirtrue id in a delayed fashion in vga_switcheroo_enable()

VGA_SWITCHEROO_IGD

integrated graphics device

VGA_SWITCHEROO_DIS

discrete graphics device

VGA_SWITCHEROO_MAX_CLIENTS

currently no more than two GPUs are supported

Description

Client identifier. Audio clients use the same identifier & 0x100.

enumvga_switcheroo_state¶

client power state

Constants

VGA_SWITCHEROO_OFF

off

VGA_SWITCHEROO_ON

on

VGA_SWITCHEROO_NOT_FOUND

client has not registered with vga_switcheroo.Only used invga_switcheroo_get_client_state() which in turn is onlycalled from hda_intel.c

Description

Client power state.

Private structures¶

structvgasr_priv¶

vga_switcheroo private data

Definition

struct vgasr_priv {  bool active;  bool delayed_switch_active;  enum vga_switcheroo_client_id delayed_client_id;  struct dentry *debugfs_root;  int registered_clients;  struct list_head clients;  const struct vga_switcheroo_handler *handler;  enum vga_switcheroo_handler_flags_t handler_flags;  struct mutex mux_hw_lock;  int old_ddc_owner;};

Members

active

whether vga_switcheroo is enabled.Prerequisite is the registration of two GPUs and a handler

delayed_switch_active

whether a delayed switch is pending

delayed_client_id

client to which a delayed switch is pending

debugfs_root

directory for vga_switcheroo debugfs interface

registered_clients

number of registered GPUs(counting only vga clients, not audio clients)

clients

list of registered clients

handler

registered handler

handler_flags

flags of registered handler

mux_hw_lock

protects mux state(in particular while DDC lines are temporarily switched)

old_ddc_owner

client to which DDC lines will be switched back on unlock

Description

vga_switcheroo private data. Currently only one vga_switcheroo instanceper system is supported.

structvga_switcheroo_client¶

registered client

Definition

struct vga_switcheroo_client {  struct pci_dev *pdev;  struct fb_info *fb_info;  enum vga_switcheroo_state pwr_state;  const struct vga_switcheroo_client_ops *ops;  enum vga_switcheroo_client_id id;  bool active;  bool driver_power_control;  struct list_head list;  struct pci_dev *vga_dev;};

Members

pdev

client pci device

fb_info

framebuffer to which console is remapped on switching

pwr_state

current power state if manual power control is used.For driver power control, call vga_switcheroo_pwr_state().

ops

client callbacks

id

client identifier. Determining the id requires the handler,so gpus are initially assigned VGA_SWITCHEROO_UNKNOWN_IDand later given their true id in vga_switcheroo_enable()

active

whether the outputs are currently switched to this client

driver_power_control

whether power state is controlled by the driver’sruntime pm. If true, writing ON and OFF to the vga_switcheroo debugfsinterface is a no-op so as not to interfere with runtime pm

list

client list

vga_dev

pci device, indicate which GPU is bound to current audio client

Description

Registered client. A client can be either a GPU or an audio device on a GPU.For audio clients, thefb_info andactive members are bogus. For GPUclients, thevga_dev is bogus.

apple-gmux Handler¶

gmux is a microcontroller built into the MacBook Pro to support dual GPUs:ALattice XP2 on pre-retinas, aRenesas R4F2113 on retinas.

(The MacPro6,1 2013 also has a gmux, however it is unclear why since it hasdual GPUs but no built-in display.)

gmux is connected to the LPC bus of the southbridge. Its I/O ports areaccessed differently depending on the microcontroller: Driver functionsto access a pre-retina gmux are infixed_pio_, those for a retina gmuxare infixed_index_.

gmux is also connected to a GPIO pin of the southbridge and thereby is ableto trigger an ACPI GPE. On the MBP5 2008/09 it’s GPIO pin 22 of the NvidiaMCP79, on all following generations it’s GPIO pin 6 of the Intel PCH.The GPE merely signals that an interrupt occurred, the actual type of eventis identified by reading a gmux register.