vga_switcheroo is the Linux subsystem for laptop hybrid graphics. These come in two flavors:
Hybrid graphics started to appear in the late Naughties and were initially all muxed. Newer laptops moved to a muxless architecture for cost reasons. A notable exception is the MacBook Pro which continues to use a mux. Muxes come with varying capabilities: Some switch only the panel, others can also switch external displays. Some switch all display pins at once while others can switch just the DDC lines. (To allow EDID probing for the inactive GPU.) Also, muxes are often used to cut power to the discrete GPU while it is not used.
DRM drivers register GPUs with vga_switcheroo, these are henceforth called clients. The mux is called the handler. Muxless machines also register a handler to control the power state of the discrete GPU, its ->switchto callback is a no-op for obvious reasons. The discrete GPU is often equipped with an HDA controller for the HDMI/DP audio signal, this will also register as a client so that vga_switcheroo can take care of the correct suspend/resume order when changing the discrete GPU’s power state. In total there can thus be up to three clients: Two vga clients (GPUs) and one audio client (on the discrete GPU). The code is mostly prepared to support machines with more than two GPUs should they become available.
The GPU to which the outputs are currently switched is called the active client in vga_switcheroo parlance. The GPU not in use is the inactive client. When the inactive client’s DRM driver is loaded, it will be unable to probe the panel’s EDID and hence depends on VBIOS to provide its display modes. If the VBIOS modes are bogus or if there is no VBIOS at all (which is common on the MacBook Pro), a client may alternatively request that the DDC lines are temporarily switched to it, provided that the handler supports this. Switching only the DDC lines and not the entire output avoids unnecessary flickering.
In this mode of use, the file /sys/kernel/debug/vgaswitcheroo/switch can be read to retrieve the current vga_switcheroo state and commands can be written to it to change the state. The file appears as soon as two GPU drivers and one handler have registered with vga_switcheroo. The following commands are understood:
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 commands should not be used.
In this mode of use, the discrete GPU automatically powers up and down at the discretion of the driver’s runtime pm. On muxed machines, the user may still influence the muxer state by way of the debugfs interface, however the 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 kernel command line disables it.
When the driver decides to power up or down, it notifies vga_switcheroo thereof so that it can (a) power the audio device on the GPU up or down, and (b) update its internal power state representation for the device. This is achieved by vga_switcheroo_set_dynamic_switch().
After the GPU has been suspended, the handler needs to be called to cut power to the GPU. Likewise it needs to reinstate power before the GPU can resume. This is achieved by vga_switcheroo_init_domain_pm_ops(), which augments the GPU’s suspend/resume functions by the requisite calls to the handler.
When the audio device resumes, the GPU needs to be woken. This is achieved by vga_switcheroo_init_domain_pm_optimus_hdmi_audio(), which augments the audio device’s resume function.
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
register handler
Parameters
Description
Register handler. Enable vga_switcheroo if two vga clients have already registered.
Return
0 on success, -EINVAL if a handler was already registered.
unregister handler
Parameters
Description
Unregister handler. Disable vga_switcheroo.
obtain handler flags
Parameters
Description
Helper for clients to obtain the handler flags bitmask.
Return
Handler flags. A value of 0 means that no handler is registered or that the handler has no special capabilities.
register vga client
Parameters
Description
Register vga client (GPU). Enable vga_switcheroo if another GPU and a handler have already registered. The power state of the client is assumed to be ON. 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.
register audio client
Parameters
Description
Register audio client (audio device on a GPU). The power state of the client is assumed to be ON. 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.
whether to defer probing a given client
Parameters
Description
Determine whether any prerequisites are not fulfilled to probe a given client. Drivers shall invoke this early on in their ->probe callback and return -EPROBE_DEFER if it evaluates to true. Thou shalt not register the client ere thou hast called this.
Return
true if probing should be deferred, otherwise false.
obtain power state of a given client
Parameters
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.
unregister client
Parameters
Description
Unregister client. Disable vga_switcheroo if this is a vga client (GPU).
set framebuffer of a given client
Parameters
Description
Set framebuffer of a given client. The console will be remapped to this on switching.
temporarily switch DDC lines to a given client
Parameters
Description
Temporarily switch DDC lines to the client identified by pdev (but leave the outputs otherwise switched to where they are). This allows the inactive client to probe EDID. The DDC lines must afterwards be switched back by calling vga_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 handler does not support switching the DDC lines. Also, a negative value returned by the handler is propagated back to the caller. The return value has merely an informational purpose for any caller which might be interested in it. It is acceptable to ignore the return value and simply rely on the result of the subsequent EDID probe, which will be NULL if DDC switching failed.
switch DDC lines back to previous owner
Parameters
Description
Switch DDC lines back to the previous owner after calling vga_switcheroo_lock_ddc(). This must be called even if vga_switcheroo_lock_ddc() returned an error.
Return
Previous DDC owner on success (i.e. the client identifier of pdev) or a negative int on error. Specifically, -ENODEV if no handler has registered or if the handler does not support switching the DDC lines. Also, a negative value returned by the handler is propagated back to the caller. Finally, invoking this function without calling vga_switcheroo_lock_ddc() first is not allowed and will result in -EINVAL.
helper for delayed switching
Parameters
Description
Process a delayed switch if one is pending. DRM drivers should call this from their ->lastclose callback.
Return
0 on success. -EINVAL if no delayed switch is pending, if the client has unregistered in the meantime or if there are other clients blocking the switch. If the actual switch fails, an error is reported and 0 is returned.
helper for driver power control
Parameters
Description
Helper for GPUs whose power state is controlled by the driver’s runtime pm. When the driver decides to power up or down, it notifies vga_switcheroo thereof using this helper so that it can (a) power the audio device on the GPU up or down, and (b) update its internal power state representation for the device.
helper for driver power control
Parameters
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 cut power to the GPU. Likewise it needs to reinstate power before the GPU can resume. To this end, this helper augments the suspend/resume functions by the requisite calls to the handler. It needs only be called on platforms where the power switch is separate to the device being powered down.
helper for driver power control
Parameters
Description
Helper for GPUs whose power state is controlled by the driver’s runtime pm. When the audio device resumes, the GPU needs to be woken. This helper augments the audio device’s resume function to do that.
Return
0 on success, -EINVAL if no power management operations are defined for this device.
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
Description
Handler callbacks. The multiplexer itself. The switchto and get_client_id methods are mandatory, all others may be set to NULL.
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);
};
Members
Description
Client callbacks. A client can be either a GPU or an audio device on a GPU. The set_gpu_state and can_switch methods are mandatory, reprobe may be set to NULL. For audio clients, the reprobe member is bogus.
handler flags bitmask
Constants
Description
Handler flags bitmask. Used by handlers to declare their capabilities upon registering with vga_switcheroo.
client identifier
Constants
Description
Client identifier. Audio clients use the same identifier & 0x100.
client power state
Constants
Description
Client power state.
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;
struct dentry * switch_file;
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
Description
vga_switcheroo private data. Currently only one vga_switcheroo instance per system is supported.
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;
};
Members
Description
Registered client. A client can be either a GPU or an audio device on a GPU. For audio clients, the fb_info, active and driver_power_control members are bogus.
gmux is a microcontroller built into the MacBook Pro to support dual GPUs: A Lattice XP2 on pre-retinas, a Renesas R4F2113 on retinas.
(The MacPro6,1 2013 also has a gmux, however it is unclear why since it has dual GPUs but no built-in display.)
gmux is connected to the LPC bus of the southbridge. Its I/O ports are accessed differently depending on the microcontroller: Driver functions to access a pre-retina gmux are infixed _pio_, those for a retina gmux are infixed _index_.
gmux is also connected to a GPIO pin of the southbridge and thereby is able to trigger an ACPI GPE. On the MBP5 2008/09 it’s GPIO pin 22 of the Nvidia MCP79, 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 event is identified by reading a gmux register.
On pre-retinas, the LVDS outputs of both GPUs feed into gmux which muxes either of them to the panel. One of the tricks gmux has up its sleeve is to lengthen the blanking interval of its output during a switch to synchronize it with the GPU switched to. This allows for a flicker-free switch that is imperceptible by the user (US 8,687,007 B2).
On retinas, muxing is no longer done by gmux itself, but by a separate chip which is controlled by gmux. The chip is triple sourced, it is either an NXP CBTL06142, TI HD3SS212 or Pericom PI3VDP12412. The panel is driven with eDP instead of LVDS since the pixel clock required for retina resolution exceeds LVDS’ limits.
Pre-retinas are able to switch the panel’s DDC pins separately. This is handled by a TI SN74LV4066A which is controlled by gmux. The inactive GPU can thus probe the panel’s EDID without switching over the entire panel. Retinas lack this functionality as the chips used for eDP muxing are incapable of switching the AUX channel separately (see the linked data sheets, Pericom would be capable but this is unused). However the retina panel has the NO_AUX_HANDSHAKE_LINK_TRAINING bit set in its DPCD, allowing the inactive GPU to skip the AUX handshake and set up the output with link parameters pre-calibrated by the active GPU.
The external DP port is only fully switchable on the first two unibody MacBook Pro generations, MBP5 2008/09 and MBP6 2010. This is done by an NXP CBTL06141 which is controlled by gmux. It’s the predecessor of the eDP mux on retinas, the difference being support for 2.7 versus 5.4 Gbit/s.
The following MacBook Pro generations replaced the external DP port with a combined DP/Thunderbolt port and lost the ability to switch it between GPUs, connecting it either to the discrete GPU or the Thunderbolt controller. Oddly enough, while the full port is no longer switchable, AUX and HPD are still switchable by way of an NXP CBTL03062 (on pre-retinas MBP8 2011 and MBP9 2012) or two TI TS3DS10224 (on retinas) under the control of gmux. Since the integrated GPU is missing the main link, external displays appear to it as phantoms which fail to link-train.
gmux receives the HPD signal of all display connectors and sends an interrupt on hotplug. On generations which cannot switch external ports, the discrete GPU can then be woken to drive the newly connected display. The ability to switch AUX on these generations could be used to improve reliability of hotplug detection by having the integrated GPU poll the ports while the discrete GPU is asleep, but currently we do not make use of this feature.
Our switching policy for the external port is that on those generations which are able to switch it fully, the port is switched together with the panel when IGD / DIS commands are issued to vga_switcheroo. It is thus possible to drive e.g. a beamer on battery power with the integrated GPU. The user may manually switch to the discrete GPU if more performance is needed.
On all newer generations, the external port can only be driven by the discrete GPU. If a display is plugged in while the panel is switched to the integrated GPU, both GPUs will be in use for maximum performance. To decrease power consumption, the user may manually switch to the discrete GPU, thereby suspending the integrated GPU.
gmux’ initial switch state on bootup is user configurable via the EFI variable gpu-power-prefs-fa4ce28d-b62f-4c99-9cc3-6815686e30f9 (5th byte, 1 = IGD, 0 = DIS). Based on this setting, the EFI firmware tells gmux to switch the panel and the external DP connector and allocates a framebuffer for the selected GPU.
gmux is able to cut power to the discrete GPU. It automatically takes care of the correct sequence to tear down and bring up the power rails for core voltage, VRAM and PCIe.
On single GPU MacBooks, the PWM signal for the backlight is generated by the GPU. On dual GPU MacBook Pros by contrast, either GPU may be suspended to conserve energy. Hence the PWM signal needs to be generated by a separate backlight driver which is controlled by gmux. The earliest generation MBP5 2008/09 uses a TI LP8543 backlight driver. All newer models use a TI LP8545.
detect if gmux is built into the machine
Parameters
Description
Drivers may use this to activate quirks specific to dual GPU MacBook Pros and Mac Pros, e.g. for deferred probing, runtime pm and backlight.
Return
true if gmux is present and the kernel was configured with CONFIG_APPLE_GMUX, false otherwise.