acidanthera · vit9696 · Jun 25, 2019 · Mar 28, 2019 · Mar 28, 2019 · Mar 28, 2019
diff --git a/Changelog.md b/Changelog.md
@@ -8,6 +8,8 @@ WhateverGreen Changelog
 - Disabled NVIDIA performance fix on 10.15, as it now is built-in
 - Enable HDMI 2.0 patches on 10.14+ (Use at own risk in case of undiscovered change)
 - Added CFL graphics kernel panic workaround on 10.14.4+
+- Added infinite loop fix when calculating dividers for Intel HDMI connections on SKL, KBL and CFL platforms.
+- Added driver support for onboard LSPCON chips to enable DisplayPort to HDMI 2.0 output on Intel IGPUs (by @0xFireWolf)
 
 #### v1.2.9
 - Added AMD Radeon VII to detected list
@@ -17,7 +19,7 @@ WhateverGreen Changelog
 
 #### v.1.2.8
 - Added KBL graphics kernel panic workaround on 10.14.4+
-- Added IGPU DPDCD link incompatible rate patch (thanks @Firewolf)
+- Added IGPU DPCD link incompatible rate patch (thanks @0xFireWolf)
 
 #### v1.2.7
 - Added more IGPU device-ids to detected list

diff --git a/Manual/FAQ.IntelHD.cn.md b/Manual/FAQ.IntelHD.cn.md
@@ -1734,6 +1734,95 @@ EDID 信息可以通过诸如使用 [Linux](https://unix.stackexchange.com/quest
 可选值为 `0x06` (RBR)，`0x0A` (HBR)，`0x14` (HBR2) 以及 `0x1E` (HBR3)。  
 若指定了其他值，则补丁默认使用 `0x14`。若不定义此属性的话，同样默认使用 `0x14`。  
 
+
+## 修复核显驱动在尝试点亮外接 HDMI 高分辨率显示器时造成的死循环问题
+**适用平台：** 第六代酷睿 Skylake 核显，第七代酷睿 Kaby Lake 核显以及第八代酷睿 Coffee Lake。  
+使用 `-igfxhdmidivs` 启动参数以解决核显驱动在试图点亮外接 HDMI 高分辨率显示器时造成的系统死机问题。  
+具体症状表现为插入 HDMI 线后，笔记本内屏变黑但有背光，系统无响应，并且外屏也无输出。
+#### 关于使用此修复补丁的一些建议
+- 如果你的笔记本或台式机主板有 HDMI 1.4 接口，并且想使用 2K 或 4K HDMI 显示器的话，你可能需要这个补丁。
+- 如果你的笔记本或台式机主板有 HDMI 2.0 接口，并且当前 HDMI 输出有问题，那么建议你启用 LSPCON 驱动支持以获得更好的 HDMI 2.0 体验。（详情请阅读下方 LSPCON 章节）
+
+## 启用 LSPCON 驱动以支持核显 DisplayPort 转 HDMI 2.0 输出
+#### 简述
+近几年的笔记本都开始配备了 HDMI 2.0 输出端口。这个端口可能直接连到核显上也有可能连在独显上。  
+如果连在了独显上，那么在 macOS 下这个 HDMI 2.0 端口直接废掉了，因为苹果不支持 Optimus 等双显卡切换技术。  
+如果连在了核显上，那么笔记本厂商需要在主板上安装额外的信号转换器来把 DP 信号转换成 HDMI 2.0 信号，  
+这是因为现阶段英特尔的核显并不能原生提供 HDMI 2.0 信号输出。（类似主板厂商使用第三方芯片以提供 USB 3.0 功能）  
+这个信号转换器名为 LSPCON，全称 **L**evel **S**hifter and **P**rotocol **Con**verter，并且有两种工作模式。  
+当工作在 LS 模式下，它可以把 DP 转换成 HDMI 1.4 信号。在 PCON 模式下，它可以把 DP 转换成 HDMI 2.0 信号。  
+然而有些厂商在转换器的固件里把 LS 设为了默认的工作模式，这就导致在 macOS 下 HDMI 2.0 连接直接黑屏或者根本不工作。    
+从 1.3.0 版本开始，WhateverGreen 提供了对 LSPCON 的驱动支持。驱动会自动将转换器调为 PCON 模式以解决 HDMI 2.0 输出黑屏问题。  
+
+#### 使用前必读
+- LSPCON 驱动适用于所有配备 HDMI 2.0 接口并接在核显上的笔记本和台式机。
+- 目前来看，英特尔的新处理器所配备的核显仍然不支持原生 HDMI 2.0 输出，所以在新平台上你可能仍然需要此驱动。
+- 适用的英特尔平台: Skylake, Kaby Lake, Coffee Lake 以及以后。  
+      Skylake 平台案例: 英特尔在 Skull Canyon NUC 上搭载了 HDMI 2.0 接口，使用了型号为 Parade PS175 的 LSPCON 信号转换器。  
+  Coffee Lake 平台案例: 部分笔记本如 Dell XPS 15 搭载了 HDMI 2.0 接口，同样使用了型号为 Parade PS175 的 LSPCON 信号转换器。  
+- 如果你已确认你的 HDMI 2.0 接口是连在核显上并且目前输出没有任何问题，那么你不需要特意启用此驱动。你的转换器可能已经出厂时就把 PCON 设为了默认的工作模式。
+
+#### 如何使用
+- 为核显添加 `enable-lspcon-support` 属性或者直接使用 `-igfxlspcon` 启动参数来启用驱动。
+- 接下来你需要知道 HDMI 2.0 对应的端口号是多少。这个你可以直接在 IORegistryExplorer 里看到。也就是在 `AppleIntelFramebuffer@0/1/2/3` 下面找到你的外接显示器。  
+*如果你身边只有 2K/4K HDMI 显示器的话，你可能需要先启用上面的死循环修复补丁，否则当你连接显示器时系统直接死机，所以就看不到对应的端口号了。*  
+- 为核显添加 `framebuffer-conX-has-lspcon` 属性来通知驱动哪个接口下面有 LSPCON 信号转换器。  
+把 `conX` 里的 X 替换成你在上一步找到的端口值。  
+这个属性的对应值请设为 `Data` 类型。如果接口下存在转换器的话，请设为 `01000000`，反之设为 `00000000`。  
+若不定义这个属性的话，驱动默认认为对应接口下**不存在**转换器。
+- *(可选)* 为核显添加 `framebuffer-conX-preferred-lspcon-mode` 属性以指定 LSPCON 应该工作在何种模式下。  
+这个属性的对应值请设为 `Data` 类型。  
+如果希望转换器工作在 PCON (DP 转 HDMI 2.0) 模式下的话，请设为 `01000000`。  
+如果希望转换器工作在 &nbsp;&nbsp;LS (DP 转 HDMI 1.4) 模式下的话，请设为 `00000000`。  
+若指定其他值的话，驱动默认认为转换器应工作在 PCON 模式下。  
+若不定义此属性的话，同上。  
+![](Img/lspcon.png)
+
+#### 排查错误
+完成上述步骤后，重建缓存重启电脑，插上 HDMI 2.0 线和 HDMI 2.0 显示器应该可以正常看到输出的图像了。  
+如果提取内核日志的话，你应该可以看到类似如下的日志。  
+
+```
+// 插入 HDMI 2.0 线
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] called with controller at 0xffffff81a8680000 and framebuffer at 0xffffff81a868c000.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] No LSPCON chip associated with this framebuffer.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] Will call the original method.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] Returns 0x0.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] called with controller at 0xffffff81a8680000 and framebuffer at 0xffffff81a869a000.
+igfx @ (DBG) SC:   LSPCON::probe() DInfo: [FB2] Found the LSPCON adapter: Parade PS1750.
+igfx @ (DBG) SC:   LSPCON::probe() DInfo: [FB2] The current adapter mode is Level Shifter (DP++ to HDMI 1.4).
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] LSPCON driver has detected the onboard chip successfully.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] LSPCON driver has been initialized successfully.
+igfx @ (DBG) SC: LSPCON::getMode() DInfo: [FB2] The current mode value is 0x00.
+igfx @ (DBG) SC: LSPCON::getMode() DInfo: [FB2] The current mode value is 0x00.
+igfx @ (DBG) SC: LSPCON::getMode() DInfo: [FB2] The current mode value is 0x00.
+igfx @ (DBG) SC: LSPCON::getMode() DInfo: [FB2] The current mode value is 0x01.
+igfx @ (DBG) SC: LSPCON::setMode() DInfo: [FB2] The new mode is now effective.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] The adapter is running in preferred mode [Protocol Converter (DP++ to HDMI 2.0)].
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] Will call the original method.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] Returns 0x0.
+
+// 拔出 HDMI 2.0 线
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] called with controller at 0xffffff81a8680000 and framebuffer at 0xffffff81a868c000.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] No LSPCON chip associated with this framebuffer.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] Will call the original method.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] Returns 0x0.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] called with controller at 0xffffff81a8680000 and framebuffer at 0xffffff81a869a000.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] LSPCON driver (at 0xffffff802ba3afe0) has already been initialized for this framebuffer.
+igfx @ (DBG) SC: LSPCON::setModeIfNecessary() DInfo: [FB2] The adapter is already running in Protocol Converter (DP++ to HDMI 2.0) mode. No need to update.
+igfx @ (DBG) SC: LSPCON::wakeUpNativeAUX() DInfo: [FB2] The native AUX channel is up. DPCD Rev = 0x12.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] Will call the original method.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] Returns 0x0.
+```
+
+另外你也能在 IORegistryExplorer 下找到驱动在对应的 Framebuffer 下注入的属性。**（此功能仅限 DEBUG 版驱动）**  
+
+`fw-framebuffer-has-lspcon` 显示当前端口是否存在 LSPCON 信号转换器，为布尔值类型。  
+`fw-framebuffer-preferred-lspcon-mode` 显示当前指定的 LSPCON 工作模式，为数据类型。1 为 PCON 模式，0 为 LS 模式。  
+
+![](Img/lspcon_debug.png)
+
+
 ## 已知问题
 *兼容性*：
 - 受限制的显卡：HD2000 和 HD2500，它们只能用于 IQSV (因为在白苹果中它们只用来干这个)，无解。

diff --git a/Manual/FAQ.IntelHD.en.md b/Manual/FAQ.IntelHD.en.md
@@ -1665,6 +1665,87 @@ All possible values are `0x06` (RBR), `0x0A` (HBR), `0x14` (HBR2) and `0x1E` (HB
 If an invalid value is specified, the default value `0x14` will be used instead.  
 If this property is not specified, same as above.  
 
+## Fix the infinite loop on establishing Intel HDMI connections with a higher pixel clock rate on Skylake, Kaby Lake and Coffee Lake platforms
+Add the `-igfxhdmidivs` boot argument to fix the infinite loop when the graphics driver tries to establish a HDMI connection with a higher pixel clock rate, for example connecting to a 2K/4K display with HDMI 1.4, otherwise the system just hangs (and your builtin laptop display remains black) when you plug in the HDMI cable.  
+#### General Notes
+- For those who want to have "limited" 2K/4K experience (i.e. 2K@59Hz or 4K@30Hz) with their HDMI 1.4 port, you might find this fix helpful.
+- For those who have a laptop or PC with HDMI 2.0 routed to Intel IGPU and have HDMI output issues, please note that this fix is now succeeded by the LSPCON driver solution, and it is still recommended to enable the LSPCON driver support to have full HDMI 2.0 experience.  
+*(You might still need this fix temporarily to figure out the framebuffer index of your HDMI port. See the LSPCON section below.)*
+
+## LSPCON driver support to enable DisplayPort to HDMI 2.0 output on Intel IGPU
+#### Brief Introduction
+Recent laptops (Kaby Lake/Coffee Lake-based) are typically equipped with a HDMI 2.0 port. This port could be either routed to IGPU or DGPU, and you can have a confirmation on Windows 10. Intel (U)HD Graphics, however, does not provide native HDMI 2.0 output, so in order to solve this issue OEMs add an additional hardware named LSPCON on the motherboard to convert DisplayPort into HDMI 2.0.  
+
+LSPCON works in either Level Shifter (LS) or Protocol Converter (PCON) mode. When the adapter works in LS mode, it is capable of producing HDMI 1.4 signals from DisplayPort, while in PCON mode, it could provide HDMI 2.0 output. Some onboard LSPCON adapters (e.g. the one on Dell XPS 15 9570) have been configured in the firmware to work in LS mode by default, resulting a black screen on handling HDMI 2.0 connections.  
+
+Starting from version 1.3.0, WhateverGreen now provides driver support for the onboard LSPCON by automatically configuring the adapter to run in PCON mode on new HDMI connections, and hence solves the black screen issue on some platforms.  
+#### Before you start
+- LSPCON driver is only applicable for laptops and PCs **with HDMI 2.0 routed to Intel IGPU**.
+- LSPCON driver is necessary for all newer platforms unless the new Intel IGPU starts to provide native HDMI 2.0 output.
+- Supported Intel Platform: Skylake, Kaby Lake, Coffee Lake and later.  
+Skylake Case: Intel NUC Skull Canyon; Iris Pro 580 + HDMI 2.0 with Parade PS175 LSPCON.  
+Coffee Lake Case: Some laptops, e.g. Dell XPS 15 9570, are equipped with HDMI 2.0 and Parade PS175 LSPCON.  
+- If you have confirmed that your HDMI 2.0 is routed to Intel IGPU and is working properly right now, you don't need to enable this driver, because your onboard LSPCON might already be configured in the firmware to work in PCON mode.
+
+#### Instructions
+- Add the `enable-lspcon-support` property to `IGPU` to enable the driver, or use the boot-arg `-igfxlspcon` instead.  
+- Next, you need to know the corresponding connector index (one of 0,1,2,3) of your HDMI port. You could find it under IGPU in IORegistryExplorer. (i.e. `AppleIntelFramebuffer@0/1/2/3`)  
+*If you only have a 2K/4K HDMI monitor, you might need to enable the infinite loop fix before connecting a HDMI monitor to your build, otherwise the system just hangs, so you won't be able to run the IORegistryExplorer and find the framebuffer index.*
+- Add the `framebuffer-conX-has-lspcon` property to `IGPU` to inform the driver which connector has an onboard LSPCON adapter.  
+Replace `X` with the index you have found in the previous step.  
+The value must be of type `Data` and should be one of `01000000` (True) and `00000000` (False).
+- (*Optional*) Add the `framebuffer-conX-preferred-lspcon-mode` property to `IGPU` to specify a mode for your onboard LSPCON adapter.  
+The value must be of type `Data` and should be one of `01000000` (PCON, DP to HDMI 2.0) and `00000000` (LS, DP to HDMI 1.4).  
+Any other invalid values are treated as PCON mode.  
+If this property is not specified, the driver assumes that PCON mode is preferred.
+![](Img/lspcon.png)
+
+#### Debugging
+Once you have completed the steps above, rebuild the kext cache and reboot your computer.
+After plugging into your HDMI 2.0 cable (and the HDMI 2.0 monitor), you should be able to see the output on your monitor.  
+
+Dump your kernel log and you should also be able to see something simillar to lines below.
+```
+// When you insert the HDMI 2.0 cable
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] called with controller at 0xffffff81a8680000 and framebuffer at 0xffffff81a868c000.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] No LSPCON chip associated with this framebuffer.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] Will call the original method.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] Returns 0x0.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] called with controller at 0xffffff81a8680000 and framebuffer at 0xffffff81a869a000.
+igfx @ (DBG) SC:   LSPCON::probe() DInfo: [FB2] Found the LSPCON adapter: Parade PS1750.
+igfx @ (DBG) SC:   LSPCON::probe() DInfo: [FB2] The current adapter mode is Level Shifter (DP++ to HDMI 1.4).
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] LSPCON driver has detected the onboard chip successfully.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] LSPCON driver has been initialized successfully.
+igfx @ (DBG) SC: LSPCON::getMode() DInfo: [FB2] The current mode value is 0x00.
+igfx @ (DBG) SC: LSPCON::getMode() DInfo: [FB2] The current mode value is 0x00.
+igfx @ (DBG) SC: LSPCON::getMode() DInfo: [FB2] The current mode value is 0x00.
+igfx @ (DBG) SC: LSPCON::getMode() DInfo: [FB2] The current mode value is 0x01.
+igfx @ (DBG) SC: LSPCON::setMode() DInfo: [FB2] The new mode is now effective.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] The adapter is running in preferred mode [Protocol Converter (DP++ to HDMI 2.0)].
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] Will call the original method.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] Returns 0x0.
+
+// When you remove the HDMI 2.0 cable
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] called with controller at 0xffffff81a8680000 and framebuffer at 0xffffff81a868c000.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] No LSPCON chip associated with this framebuffer.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] Will call the original method.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB0] Returns 0x0.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] called with controller at 0xffffff81a8680000 and framebuffer at 0xffffff81a869a000.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] LSPCON driver (at 0xffffff802ba3afe0) has already been initialized for this framebuffer.
+igfx @ (DBG) SC: LSPCON::setModeIfNecessary() DInfo: [FB2] The adapter is already running in Protocol Converter (DP++ to HDMI 2.0) mode. No need to update.
+igfx @ (DBG) SC: LSPCON::wakeUpNativeAUX() DInfo: [FB2] The native AUX channel is up. DPCD Rev = 0x12.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] Will call the original method.
+igfx @ (DBG) SC:     GetDPCDInfo() DInfo: [FB2] Returns 0x0.
+```
+
+Additionally, you can find these properties injected by the driver under the corresponding framebuffer.  
+**(Only available in DEBUG version)**  
+
+`fw-framebuffer-has-lspcon` indicates whether the onboard LSPCON adapter exists or not.  
+`fw-framebuffer-preferred-lspcon-mode` indicates the preferred adapter mode. 1 is PCON, and 0 is LS.  
+
+![](Img/lspcon_debug.png)
+
 ## Known Issues  
 *Compatibility*:  
 - Limited cards: HD2000, HD2500 can only be used for [IQSV](https://www.applelife.ru/threads/zavod-intel-quick-sync-video.817923/) (they are used in real Macs only for this), there are no solutions.  

diff --git a/Manual/Img/lspcon.png b/Manual/Img/lspcon.png
diff --git a/Manual/Img/lspcon_debug.png b/Manual/Img/lspcon_debug.png
diff --git a/README.md b/README.md
@@ -23,6 +23,9 @@ WhateverGreen
 - Injects IOVARendererID into GPU properties (required for Shiki-based solution for non-freezing Intel and/or any discrete GPU)
 - For Intel HD digital audio HDMI, DP, Digital DVI (Patches connector-type DP -> HDMI)
 - Fixes NVIDIA GPU interface stuttering on 10.13 (official and web drivers)
+- Fixes the kernel panic caused by an invalid link rate reported by DPCD on some laptops with Intel IGPU.
+- Fixes the infinite loop on establishing Intel HDMI connections with a higher pixel clock rate on Skylake, Kaby Lake and Coffee Lake platforms.
+- Implements the driver support for onboard LSPCON chips to enable DisplayPort to HDMI 2.0 output on some platforms with Intel IGPU.
 
 #### Documentation
 Read [FAQs](https://github.com/acidanthera/WhateverGreen/blob/master/Manual/) and avoid asking any questions. No support is provided for the time being.
@@ -54,12 +57,15 @@ Read [FAQs](https://github.com/acidanthera/WhateverGreen/blob/master/Manual/) an
 - `igfxcflbklt=1` boot argument (and `enable-cfl-backlight-fix` property) to enable CFL backlight patch
 - `applbkl=0` boot argument to disable AppleBacklight.kext patches for IGPU. In case of custom AppleBacklight profile- [read here.](https://github.com/acidanthera/WhateverGreen/blob/master/Manual/FAQ.OldPlugins.en.md)  
 - `-igfxmlr` boot argument (and `enable-dpcd-max-link-rate-fix` property) to apply the maximum link rate fix.
+- `-igfxhdmidivs` boot argument to fix the infinite loop on establishing Intel HDMI connections with a higher pixel clock rate on SKL, KBL and CFL platforms.
+- `-igfxlspcon` boot argument (and `enable-lspcon-support` property) to enable the driver support for onboard LSPCON chips. [Read the manual](https://github.com/acidanthera/WhateverGreen/blob/master/Manual/FAQ.IntelHD.en.md)
+- `-igfxi2cdbg` boot argument to enable verbose output in I2C-over-AUX transactions (only for debugging purposes).
 
 #### Credits
 - [Apple](https://www.apple.com) for macOS
 - [AMD](https://www.amd.com) for ATOM VBIOS parsing code
 - [The PCI ID Repository](http://pci-ids.ucw.cz) for multiple GPU model names
-- [FireWolf](https://github.com/0xFireWolf/) for the DPCD maximum link rate fix
+- [FireWolf](https://github.com/0xFireWolf/) for the DPCD maximum link rate fix, infinite loop fix for Intel HDMI connections and LSPCON driver support
 - [Floris497](https://github.com/Floris497) for the CoreDisplay [patches](https://github.com/Floris497/mac-pixel-clock-patch-v2)
 - [Fraxul](https://github.com/Fraxul) for original CFL backlight patch
 - [headkaze](https://github.com/headkaze) for Intel framebuffer patching code and CFL backlight patch improvements