Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-09-24 08:53:09 +00:00
Code Issues Packages Projects Releases Wiki Activity

apple-gmux: Sphinxify docs

Browse Source 
Convert asciidoc-formatted docs to rst in accordance with Jonathan's and
Jani's effort to use sphinx for kernel-doc rendering in 4.8.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Lukas Wunner <lukas@wunner.de>
Acked-by: Darren Hart <dvhart@linux.intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/4c1b29986fa77772156b1af0c965d3799e43a47b.1467628307.git.lukas@wunner.de
This commit is contained in:
Lukas Wunner 2016-07-04 12:40:35 +02:00 committed by Daniel Vetter
parent 3c31760e76
commit 305964b7a0
1 changed files with 29 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
drivers/platform/x86/apple-gmux.c
View File

@ -31,19 +31,21 @@
/** /**
* DOC: Overview * DOC: Overview
* *
* :1: http://www.latticesemi.com/en/Products/FPGAandCPLD/LatticeXP2.aspx
* :2: http://www.renesas.com/products/mpumcu/h8s/h8s2100/h8s2113/index.jsp
*
* gmux is a microcontroller built into the MacBook Pro to support dual GPUs: * gmux is a microcontroller built into the MacBook Pro to support dual GPUs:
* A {1}[Lattice XP2] on pre-retinas, a {2}[Renesas R4F2113] on retinas. * 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 * (The MacPro6,1 2013 also has a gmux, however it is unclear why since it has
* dual GPUs but no built-in display.) * dual GPUs but no built-in display.)
* *
* gmux is connected to the LPC bus of the southbridge. Its I/O ports are * gmux is connected to the LPC bus of the southbridge. Its I/O ports are
* accessed differently depending on the microcontroller: Driver functions * accessed differently depending on the microcontroller: Driver functions
* to access a pre-retina gmux are infixed `_pio_`, those for a retina gmux * to access a pre-retina gmux are infixed ``_pio_``, those for a retina gmux
* are infixed `_index_`. * are infixed ``_index_``.
*
* .. _Lattice XP2:
* http://www.latticesemi.com/en/Products/FPGAandCPLD/LatticeXP2.aspx
* .. _Renesas R4F2113:
* http://www.renesas.com/products/mpumcu/h8s/h8s2100/h8s2113/index.jsp
*/ */
struct apple_gmux_data { struct apple_gmux_data {
@ -272,15 +274,15 @@ static bool gmux_is_indexed(struct apple_gmux_data *gmux_data)
/** /**
* DOC: Backlight control * DOC: Backlight control
* *
* :3: http://www.ti.com/lit/ds/symlink/lp8543.pdf
* :4: http://www.ti.com/lit/ds/symlink/lp8545.pdf
*
* On single GPU MacBooks, the PWM signal for the backlight is generated by * 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 * 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 * to conserve energy. Hence the PWM signal needs to be generated by a separate
* backlight driver which is controlled by gmux. The earliest generation * backlight driver which is controlled by gmux. The earliest generation
* MBP5 2008/09 uses a {3}[TI LP8543] backlight driver. All newer models * MBP5 2008/09 uses a `TI LP8543`_ backlight driver. All newer models
* use a {4}[TI LP8545]. * use a `TI LP8545`_.
*
* .. _TI LP8543: http://www.ti.com/lit/ds/symlink/lp8543.pdf
* .. _TI LP8545: http://www.ti.com/lit/ds/symlink/lp8545.pdf
*/ */
static int gmux_get_brightness(struct backlight_device *bd) static int gmux_get_brightness(struct backlight_device *bd)
@ -312,28 +314,20 @@ static const struct backlight_ops gmux_bl_ops = {
/** /**
* DOC: Graphics mux * DOC: Graphics mux
* *
* :5: http://pimg-fpiw.uspto.gov/fdd/07/870/086/0.pdf
* :6: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf
* :7: http://www.ti.com/lit/ds/symlink/hd3ss212.pdf
* :8: https://www.pericom.com/assets/Datasheets/PI3VDP12412.pdf
* :9: http://www.ti.com/lit/ds/symlink/sn74lv4066a.pdf
* :10: http://pdf.datasheetarchive.com/indexerfiles/Datasheets-SW16/DSASW00308511.pdf
* :11: http://www.ti.com/lit/ds/symlink/ts3ds10224.pdf
*
* On pre-retinas, the LVDS outputs of both GPUs feed into gmux which muxes * 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 * 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 * 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 * synchronize it with the GPU switched to. This allows for a flicker-free
* switch that is imperceptible by the user ({5}[US 8,687,007 B2]). * 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 * 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 * chip which is controlled by gmux. The chip is triple sourced, it is
* either an {6}[NXP CBTL06142], {7}[TI HD3SS212] or {8}[Pericom PI3VDP12412]. * either an `NXP CBTL06142`_, `TI HD3SS212`_ or `Pericom PI3VDP12412`_.
* The panel is driven with eDP instead of LVDS since the pixel clock * The panel is driven with eDP instead of LVDS since the pixel clock
* required for retina resolution exceeds LVDS' limits. * required for retina resolution exceeds LVDS' limits.
* *
* Pre-retinas are able to switch the panel's DDC pins separately. * Pre-retinas are able to switch the panel's DDC pins separately.
* This is handled by a {9}[TI SN74LV4066A] which is controlled by gmux. * 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 inactive GPU can thus probe the panel's EDID without switching over
* the entire panel. Retinas lack this functionality as the chips used for * the entire panel. Retinas lack this functionality as the chips used for
* eDP muxing are incapable of switching the AUX channel separately (see * eDP muxing are incapable of switching the AUX channel separately (see
@ -344,15 +338,15 @@ static const struct backlight_ops gmux_bl_ops = {
* *
* The external DP port is only fully switchable on the first two unibody * 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 * MacBook Pro generations, MBP5 2008/09 and MBP6 2010. This is done by an
* {6}[NXP CBTL06141] which is controlled by gmux. It's the predecessor of the * `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. * 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 * 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, * combined DP/Thunderbolt port and lost the ability to switch it between GPUs,
* connecting it either to the discrete GPU or the Thunderbolt controller. * connecting it either to the discrete GPU or the Thunderbolt controller.
* Oddly enough, while the full port is no longer switchable, AUX and HPD * Oddly enough, while the full port is no longer switchable, AUX and HPD
* are still switchable by way of an {10}[NXP CBTL03062] (on pre-retinas * are still switchable by way of an `NXP CBTL03062`_ (on pre-retinas
* MBP8 2011 and MBP9 2012) or two {11}[TI TS3DS10224] (on retinas) under the * 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, * control of gmux. Since the integrated GPU is missing the main link,
* external displays appear to it as phantoms which fail to link-train. * external displays appear to it as phantoms which fail to link-train.
* *
@ -365,10 +359,19 @@ static const struct backlight_ops gmux_bl_ops = {
* of this feature. * of this feature.
* *
* gmux' initial switch state on bootup is user configurable via the EFI * gmux' initial switch state on bootup is user configurable via the EFI
* variable `gpu-power-prefs-fa4ce28d-b62f-4c99-9cc3-6815686e30f9` (5th byte, * 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 * 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 * switch the panel and the external DP connector and allocates a framebuffer
* for the selected GPU. * for the selected GPU.
*
* .. _US 8,687,007 B2: http://pimg-fpiw.uspto.gov/fdd/07/870/086/0.pdf
* .. _NXP CBTL06141: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf
* .. _NXP CBTL06142: http://www.nxp.com/documents/data_sheet/CBTL06141.pdf
* .. _TI HD3SS212: http://www.ti.com/lit/ds/symlink/hd3ss212.pdf
* .. _Pericom PI3VDP12412: https://www.pericom.com/assets/Datasheets/PI3VDP12412.pdf
* .. _TI SN74LV4066A: http://www.ti.com/lit/ds/symlink/sn74lv4066a.pdf
* .. _NXP CBTL03062: http://pdf.datasheetarchive.com/indexerfiles/Datasheets-SW16/DSASW00308511.pdf
* .. _TI TS3DS10224: http://www.ti.com/lit/ds/symlink/ts3ds10224.pdf
*/ */
static void gmux_read_switch_state(struct apple_gmux_data *gmux_data) static void gmux_read_switch_state(struct apple_gmux_data *gmux_data)