From 658ef2fb9b7ca6ed5abe14e5dec1f3ae772d5bf8 Mon Sep 17 00:00:00 2001
From: zhen-zen <66577170+zhen-zen@users.noreply.github.com>
Date: Sun, 1 Nov 2020 17:29:00 -0800
Subject: [PATCH] Update readme with special handling for ThinkPads (#8)

---
 BrightnessKeys/BrightnessKeys.cpp |  4 +-
 README.md                         | 84 ++++++++++++++++++++++++++++++-
 2 files changed, 85 insertions(+), 3 deletions(-)

diff --git a/BrightnessKeys/BrightnessKeys.cpp b/BrightnessKeys/BrightnessKeys.cpp
index 030b9ec..830e694 100644
--- a/BrightnessKeys/BrightnessKeys.cpp
+++ b/BrightnessKeys/BrightnessKeys.cpp
@@ -225,7 +225,7 @@ IOReturn BrightnessKeys::_panelNotification(void *target, void *refCon, UInt32 m
         
         auto self = OSDynamicCast(BrightnessKeys, reinterpret_cast<OSMetaClassBase*>(target));
         if (NULL == self) {
-            DBGLOG("brkeys", "%s kIOACPIMessageDeviceNotification target is not a ApplePS2Keyboard\n", provider->getName());
+            DBGLOG("brkeys", "%s kIOACPIMessageDeviceNotification target is not a ApplePS2Keyboard", provider->getName());
             return kIOReturnError;
         }
         
@@ -252,7 +252,7 @@ IOReturn BrightnessKeys::_panelNotification(void *target, void *refCon, UInt32 m
                         clock_get_uptime(&info.time);
                         self->dispatchKeyboardEventX(BRIGHTNESS_UP, false, info.time);
                     }
-                    DBGLOG("brkeys", "%s ACPI brightness up\n", provider->getName());
+                    DBGLOG("brkeys", "%s ACPI brightness up", provider->getName());
                     break;
                     
                 case kIOACPIMessageBrightnessDown:
diff --git a/README.md b/README.md
index 8d24493..e4b6fee 100644
--- a/README.md
+++ b/README.md
@@ -3,4 +3,86 @@ BrightnessKeys
 
 [![Build Status](https://travis-ci.com/acidanthera/BrightnessKeys.svg?branch=main)](https://travis-ci.com/acidanthera/BrightnessKeys)
 
-Automatic handling of brightness keys without DSDT patches by @zhen-zen
+Automatic handling of brightness keys based on ACPI Specification, Appendix B: Video Extensions.
+
+Requires Lilu 1.2.0 or newer.
+
+#### Special cases
+
+Typically no DSDT patches are required. Please remove old `_QXX` to `XQXX` ones.
+
+<details>
+<summary>Spoiler: On some old ThinkPad models, additional handling may be required.</summary>
+<br>
+Here is an example for their "brightness up" EC event.
+
+```
+Method (_Q14, 0, NotSerialized)
+{
+    If (^HKEY.MHKK (0x8000))
+    {
+        ^HKEY.MHKQ (0x1010)                // Vendor-specific event: TP_HKEY_EV_BRGHT_UP
+    }
+
+    If (NBCF) // Whether
+    {
+        If (VIGD)
+        {
+            Notify (^^^VID.LCD0, 0x86)     // Send 0x86 "Increase Brightness" to integrated graphics
+        }
+        Else
+        {
+            Notify (^^^PEG.VID.LCD0, 0x86) // Send 0x86 "Increase Brightness" to discrete graphics
+        }
+    }
+    Else
+    {
+        Local0 = BRLV                      // Local variable to store current brightness level
+        If ((Local0 != 0x0F))
+        {
+            Local0++
+            BRLV = Local0
+        }
+
+        If (VIGD)
+        {
+            UCMS (0x16)                    // SMI access for integrated graphics
+            BRNS ()
+        }
+        Else
+        {
+            VBRC (Local0)                  // SMI access for discrete graphics
+        }
+
+        ^HKEY.MHKQ (0x6050)                // Vendor-specific event: TP_HKEY_EV_BACKLIGHT_CHANGED
+    }
+}
+```
+
+When `NBCF` is set to zero by default, the method will not notify graphics devices and try to adjust brightness directly. To override that, set `NBCF = 0x01` in SSDT hotpatch, or just replace its declaration using a simple patch.
+
+- For DSDT compiled with older iasl:
+
+Replace `Name (NBCF, 0x00)` to `Name (NBCF, 0x01)`:
+
+Find: `08 4E424346 0A 00` `// NameOp "NBCF" BytePrefix "00"`
+
+Repl: `08 4E424346 0A 01` `// NameOp "NBCF" BytePrefix "01"`
+
+- For DSDT compiled with newer iasl:
+
+Replace `Name (NBCF, Zero)` to `Name (NBCF, One)`:
+
+Find: `08 4E424346 00` `// NameOp "NBCF" ZeroOp`
+
+Repl: `08 4E424346 01` `// NameOp "NBCF" OneOp`
+
+Thanks [Sniki](https://github.com/Sniki) for raising this issue.
+</details>
+
+#### Credits
+
+- [Apple](https://www.apple.com) for macOS
+- [usr-sse2](https://github.com/usr-sse2) for seperating this driver from VoodooPS2
+- [vit9696](https://github.com/vit9696) for `DeviceInfo` API from Lilu
+- [zhen-zen](https://github.com/zhen-zen) for implementation