Actual initial commit

dge8 · dge8 · commit b8052aa38456 · 2024-11-02T17:28:24.000+11:00
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "cmdf2/lib/Karabiner-VirtualHIDDevice"]
+	path = cmdf2/lib/Karabiner-VirtualHIDDevice
+	url = https://github.com/pqrs-org/Karabiner-VirtualHIDDevice-archived
diff --git a/README.md b/README.md
@@ -1,2 +1,80 @@
 # TargetDisplayModeTools
-Tools and notes on Apple's Target Display Mode for 2009-2011 era iMacs
+This is a repo with some tools and notes on Apple's Target Display Mode for 2009-2011-era iMacs.
+A few years ago during COVID lockdown I purchased a broken 27" 2011 iMac to use as a cheap external monitor and made a few notes along the way. Key discoveries:
+- Newer Macs can use these iMacs as external displays when connected via appropriate Thunderbolt cables/adapters
+- Target Display Mode works on macOS 10.13 High Sierra (the latest supported by these iMacs) by copying the binary `/usr/libexec/dpd` from a 10.9 Mavericks installer.
+- Target Display Mode is handled by the motherboard and doesn't need a working GPU (handy since failure of the Radeon 6xx0M series GPUs in these iMacs is common)
+- Target Display Mode can be activated over SSH using the Karabiner VirtualHIDDevice kext (`cmdf2` code in this repo) so no keyboard or mouse is needed
+Hopefully sharing these notes will keep a few more 27" iMacs from being thrown out.
+
+## Repo contents
+- `cmdf2` simulates connecting a physical keyboard and pressing Cmd-F2 to activate Target Display Mode. It works over SSH and even without console login (IIRC. Otherwise create a regular user and enable auto-login). It uses Karabiner's VirtualHIDDevice kext and is based on [this example code](https://github.com/pqrs-org/Karabiner-VirtualHIDDevice-archived/tree/master/example/virtual_keyboard_example). You'll need Xcode Command Line Tools to compile.
+- `tdm.fish` contains a fish shell function for controlling TDM over SSH and e.g. demonstrates use of `cmdf2` via SSH.
+- `com.local.LimitHDDFan.plist` is a `launchd` job file to limit fan speed on startup using smcFanControl.
+ 
+## Procedure
+- Install fresh macOS 10.13 High Sierra from USB
+- If GPU is faulty, move graphics kexts out of `/System/Library/Extensions` and rebuild kext cache (more details below). Probably need to disable SIP. Graphics and VNC screen sharing will be slow.
+- Connect to network and install updates, enable SSH and VNC access for admin user
+- Replace `/usr/libexec/dpd` with version from latest Mavericks installer (more details below)
+- If hard drive is missing, install smcFanControl and add launchd job to limit fan speed (more details below)
+- Success!
+
+## Problems and solutions
+
+### Booting macOS when the GPU is faulty
+*Problem*: 2011 27” iMac boots to grey screen after progress bar completes
+*Cause*: faulty AMD Radeon card, common issue with machines of this era
+*Workaround*: Move `ATIRadeonX3000.kext` and `ATI6000Controller.kext` (AMD… in later MacOS) from `/System/Library/Extensions` to e.g. `/System/Library/DisabledExtensions`. In later versions of macOS with a kext cache run `touch /System/Library/Extensions` to force a cache rebuild.
+- Some sites suggest moving all ATI* or AMD* kexts but this doesn’t appear to be necessary
+- Some sites suggest changing nvram `boot-args` to `agc=0` or `agc=-1` but this also doesn’t appear to do anything on an iMac (might be relevant to MBP graphics switching)
+
+*Problem*: Can’t move kexts while SIP is enabled, can’t disable SIP since Recovery Partition is inaccessible due to attempting to load above kexts
+*Solution A*: Boot into single-user recovery mode by holding Option, then pressing Cmd-S immediately after selecting the recovery partition. Couldn’t get this working with the 10.13.6 recovery partition, so may need to use an older recovery partition (e.g. 10.11.6). Run `csrutil disable` from single-user-recovery mode. See also <https://apple.stackexchange.com/questions/332587/single-user-recovery-mode-on-high-sierra-10-13-6>
+*Solution B*: Plug boot media into another Mac and move kexts from there (or maybe Target Disk Mode)
+*Possible solution*: (not tried) disable SIP directly using the nvram command from single-user mode using an older pre-SIP macOS (e.g. 10.6.8): `nvram csr-active-config="w%00%00%00"`
+
+### Getting Target Display Mode to work on macOS 10.13 High Sierra
+*Problem*: Target Display Mode will not start. Console contains repeated messages every 10 seconds:
+	`com.apple.xpc.launchd[1] (com.apple.dpd[182]): Service exited with abnormal code: 75`
+*Cause*: Target Display Mode is toggled by `com.apple.dpd` (a single binary located at `/usr/libexec/dpd`) which listens for the Cmd-F2 sequence. dpd is repeatedly crashing which means TDM cannot be triggered.
+*Solution*: The issue seems to just affect `dpd` binaries from 10.10 Yosemite onwards (tested on 10.10.5, 10.11.6, 10.13.6 `dpd`). Replacing the later `dpd` binary with the 10.9.5 Mavericks `dpd` (MD5: `6355f7378348de906ad1ace46c936c8c`) resolves the issue. This can be directly extracted by mounting the Mavericks installer PKG with `hdiutil attach` and opening `/Packages/BSD.pkg` in e.g. Suspicious Package.
+
+### Triggering Target Display Mode without a physical keyboard or mouse
+*Problem*: Want to remotely toggle Target Display Mode over SSH. 
+*Solution*: Install [Karabiner Elements](https://karabiner-elements.pqrs.org), which includes a compiled and signed kext for [Karabiner-VirtualHIDDevice](https://github.com/pqrs-org/Karabiner-VirtualHIDDevice-archived). Compile `cmdf2` code in this repo (based on `Karabiner-VirtualHIDDevice/example/virtual_keyboard_example`) and run as sudo over SSH to trigger TDM.
+Use `modifier::left_command` followed by `kHIDUsage_Csmr_DisplayBrightnessIncrement`.
+`AppleVendorKeyboard_Brightness_Up` doesn’t work for some reason.
+*Other useful references*:
+- <https://github.com/pqrs-org/Karabiner-VirtualHIDDevice-archived/blob/master/src/include/karabiner_virtual_hid_device.hpp.tmpl>
+<https://opensource.apple.com/source/IOHIDFamily/IOHIDFamily-700/IOHIDFamily/AppleHIDUsageTables.h>
+*Possible solution*: Remap some keys using Karabiner as per
+<https://apple.stackexchange.com/questions/170175/switch-to-target-display-mode-without-keyboard>
+*Possible solution*: Remap keys with `hidutil` and `launchd` as per <https://rakhesh.com/mac/using-hidutil-to-map-macos-keyboard-keys/> and <https://hidutil-generator.netlify.app>
+*Almost solution*: `osascript` over SSH works on macOS 10.6.8 (apparently up to 10.9.5 according to above link): `osascript -e 'tell application "System Events" to key code 144 using command down'`. Confirmed not working on 10.13.6 despite enabling Accessibility access for Terminal and Script Editor. <https://apple.stackexchange.com/questions/362787/automator-and-or-applescript-to-automatically-command-f2-to-enter-target-display>
+*Almost solution*: [VirtualKVM](https://github.com/duanefields/VirtualKVM) seems like it might work for those that want TDM triggered upon attach/detach of Thunderbolt between their MacBook and iMac (along with simultaneous enable/disable of Bluetooth to facilitate transfer of mouse/keyboard control) and don’t mind a helper app running on both devices. However, couldn’t get it to work, possibly due to network issues blocking client-host connection or possibly due to daisy-chaining my iMac off an Apple Thunderbolt Display (MBP connects to TBD).
+*Almost solution*: <https://github.com/BlueM/cliclick> - didn’t work over SSH, tried Cmd with F2, brightness, etc.
+
+### Reducing fan speed when iMac hard drive is removed
+*Problem*: iMac HDD fan runs loudly all the time with no hard drive
+*Cause*: Apple hard drives contain a built-in temperature sensor which is now absent, so the SMC runs the fan at maximum to be safe.
+*Solution*: Install [smcFanControl](https://www.eidac.de). Set the maximum HDD fan speed using the `smc` tool within using a `launchd` script (here as `com.local.LimitHDDFan.plist`).
+*Command*: `/Applications/smcFanControl.app/Contents/Resources/smc -k F1Mx -w 1130`
+`smc` tool info: <https://discussions.apple.com/thread/2554924>
+launchd template: <https://superuser.com/questions/229773/run-command-on-startup-login-mac-os-x>
+Note: use RunAtLoad instead of LaunchOnlyOnce
+
+Problem: Want to track iMac temperatures over SSH to avoid overheating with the fan turned down
+Solution: Install [HardwareMonitor](https://www.bresink.com/osx/HardwareMonitor.html) and use command-line tool: `/Applications/HardwareMonitor.app/Contents/MacOS/hwmonitor -c`
+
+### Miscellaneous notes
+- `dpd` has an associated binary `dpaudiothru` responsible for passing through audio which seems to work fine on newer macOS versions.
+- macOS Mavericks installer can be downloaded from the Mac App Store using `mas-cli` with `mas install 675248567` as long as it has already been purchased, as per <https://forums.macrumors.com/threads/can-someone-give-me-a-mavericks-download-link.2279301/>
+- `dmtest` reinstalls missing recovery partitions: `./dmtest ensureRecoveryPartition` <https://davidjb.com/blog/2016/12/creating-a-macos-recovery-partition-without-reinstalling-osx-or-re-running-your-installer/>
+- To stop Screen Sharing locking the screen when disconnecting: `sudo defaults write /Library/Preferences/com.apple.RemoteManagement RestoreMachineState -bool NO`
+- SilentKnight checks EFI is up-to-date and can install updates for e.g. Gatekeeper and XProtect <https://eclecticlight.co/lockrattler-systhist/>
+    - Command-line version `silnite` requires Swift Runtime for Command Line Tools: <https://support.apple.com/kb/dl1998?locale=en_US>
+- 2011 iMac graphics card upgrade megathread: <https://forums.macrumors.com/threads/2011-imac-graphics-card-upgrade.1596614/>
+- Some macOS install packages combine the installer PKG file and the InstallESD DMG and can be mounted directly using `hdiutil attach`
+- Older macOS (e.g. 10.6.8) don’t support ed25519 SSH keys
+
diff --git a/cmdf2/Makefile b/cmdf2/Makefile
@@ -0,0 +1,14 @@
+CXXFLAGS = -Ilib/Karabiner-VirtualHIDDevice/dist/include -std=c++14 -Wall -Werror -O2
+
+all: main.o
+	c++ -framework IOKit main.o -o cmdf2
+
+install:
+	cp cmdf2 /usr/local/bin/cmdf2
+
+clean:
+	rm -f *.o
+	rm -f cmdf2
+
+run: all
+	sudo ./cmdf2
diff --git a/cmdf2/lib/Karabiner-VirtualHIDDevice b/cmdf2/lib/Karabiner-VirtualHIDDevice
@@ -0,0 +1 @@
+Subproject commit 31c06975c82996fdb12f6298113015cb5c4c453d
diff --git a/cmdf2/main.cpp b/cmdf2/main.cpp
@@ -0,0 +1,117 @@
+#include "karabiner_virtual_hid_device_methods.hpp"
+#include <CoreFoundation/CoreFoundation.h>
+#include <IOKit/IOKitLib.h>
+#include <IOKit/hid/IOHIDDevice.h>
+#include <IOKit/hid/IOHIDElement.h>
+#include <IOKit/hid/IOHIDManager.h>
+#include <IOKit/hid/IOHIDQueue.h>
+#include <IOKit/hid/IOHIDValue.h>
+#include <IOKit/hidsystem/IOHIDShared.h>
+#include <IOKit/hidsystem/ev_keymap.h>
+#include <cmath>
+#include <iostream>
+#include <thread>
+
+int main(int argc, const char* argv[]) {
+  if (getuid() != 0) {
+    std::cerr << "dispatch_keyboard_event_example requires root privilege." << std::endl;
+  }
+
+  //std::cout << pqrs::karabiner_virtual_hid_device::get_kernel_extension_name() << std::endl;
+
+  kern_return_t kr;
+  io_connect_t connect = IO_OBJECT_NULL;
+  auto service = IOServiceGetMatchingService(kIOMasterPortDefault, IOServiceNameMatching(pqrs::karabiner_virtual_hid_device::get_virtual_hid_root_name()));
+  if (!service) {
+    std::cerr << "IOServiceGetMatchingService error" << std::endl;
+    goto finish;
+  }
+
+  kr = IOServiceOpen(service, mach_task_self(), kIOHIDServerConnectType, &connect);
+  if (kr != KERN_SUCCESS) {
+    std::cerr << "IOServiceOpen error" << std::endl;
+    goto finish;
+  }
+
+  {
+    pqrs::karabiner_virtual_hid_device::properties::keyboard_initialization properties;
+    kr = pqrs::karabiner_virtual_hid_device_methods::initialize_virtual_hid_keyboard(connect, properties);
+    if (kr != KERN_SUCCESS) {
+      std::cerr << "initialize_virtual_hid_keyboard error" << std::endl;
+    }
+
+    while (true) {
+      //std::cout << "Checking virtual_hid_keyboard is ready..." << std::endl;
+
+      bool ready;
+      kr = pqrs::karabiner_virtual_hid_device_methods::is_virtual_hid_keyboard_ready(connect, ready);
+      if (kr != KERN_SUCCESS) {
+        std::cerr << "is_virtual_hid_keyboard_ready error: " << kr << std::endl;
+      } else {
+        if (ready) {
+          //std::cout << "virtual_hid_keyboard is ready." << std::endl;
+          break;
+        }
+      }
+
+      std::this_thread::sleep_for(std::chrono::milliseconds(100));
+    }
+  }
+
+  {
+    pqrs::karabiner_virtual_hid_device::properties::keyboard_initialization properties;
+    //properties.country_code = 33;
+    kr = pqrs::karabiner_virtual_hid_device_methods::initialize_virtual_hid_keyboard(connect, properties);
+    if (kr != KERN_SUCCESS) {
+      std::cerr << "initialize_virtual_hid_keyboard error" << std::endl;
+    }
+    std::this_thread::sleep_for(std::chrono::milliseconds(500));
+  }
+
+  // left_command key down
+  {
+    pqrs::karabiner_virtual_hid_device::hid_report::keyboard_input report;
+    report.modifiers.insert(pqrs::karabiner_virtual_hid_device::hid_report::modifier::left_command);
+
+    kr = pqrs::karabiner_virtual_hid_device_methods::post_keyboard_input_report(connect, report);
+    if (kr != KERN_SUCCESS) {
+      std::cerr << "post_keyboard_input_report error" << std::endl;
+    }
+  }
+
+  // brightness_up (f2) key down
+  {
+    // Apple brightness key doesn't work for enabling TDM
+    //pqrs::karabiner_virtual_hid_device::hid_report::apple_vendor_keyboard_input report;
+    //report.keys.insert(0x0020); // kHIDUsage_AppleVendorKeyboard_Brightness_Up
+
+    // F2 key doesn't work for enabling TDM
+    //pqrs::karabiner_virtual_hid_device::hid_report::keyboard_input report;
+    //report.keys.insert(kHIDUsage_KeyboardF2);
+
+    // Consumer display brightness increment does...?
+    pqrs::karabiner_virtual_hid_device::hid_report::consumer_input report;
+    report.keys.insert(kHIDUsage_Csmr_DisplayBrightnessIncrement);
+
+    kr = pqrs::karabiner_virtual_hid_device_methods::post_keyboard_input_report(connect, report);
+    if (kr != KERN_SUCCESS) {
+      std::cerr << "post_keyboard_input_report error" << std::endl;
+    }
+  }
+
+  // keyboard reset
+  kr = pqrs::karabiner_virtual_hid_device_methods::reset_virtual_hid_keyboard(connect);
+  if (kr != KERN_SUCCESS) {
+    std::cerr << "reset_virtual_hid_keyboard error" << std::endl;
+  }
+
+finish:
+  if (connect) {
+    IOServiceClose(connect);
+  }
+  if (service) {
+    IOObjectRelease(service);
+  }
+
+  return 0;
+}
diff --git a/com.local.LimitHDDFan.plist b/com.local.LimitHDDFan.plist
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>com.local.LimitHDDFan</string>
+	<key>UserName</key>
+	<string>root</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>/Applications/smcFanControl.app/Contents/Resources/smc</string>
+		<string>-k</string>
+		<string>F1Mx</string>
+		<string>-w</string>
+		<string>1130</string>
+	</array>
+	<key>OnDemand</key>
+	<false/>
+	<key>RunAtLoad</key>
+	<true/>
+</dict>
+</plist>
diff --git a/tdm.fish b/tdm.fish
@@ -0,0 +1,28 @@
+function tdm --argument-names cmd --description "Shortcuts for Target Display Mode"
+	switch "$cmd"
+		case cmdf2 toggle tog
+			ssh tdm.local "sudo cmdf2"
+		case goodnight
+			ssh tdm.local 'bash -c "sudo cmdf2; sleep 10; sudo shutdown -h now" </dev/null >/dev/null 2>/dev/null &'
+		case fans
+			ssh tdm.local /Applications/smcFanControl.app/Contents/Resources/smc -f
+		case temps
+			# https://apple.stackexchange.com/questions/54329/can-i-get-the-cpu-temperature-and-fan-speed-from-the-command-line-in-os-x
+			ssh tdm.local /Applications/HardwareMonitor.app/Contents/MacOS/hwmonitor -c
+		case hwinfo
+			ssh tdm.local system_profiler SPHardwareDataType
+		case tbinfo
+			ssh tdm.local system_profiler SPThunderboltDataType
+		case shutdown
+			ssh tdm.local sudo /sbin/shutdown -h now
+		case reboot
+			ssh tdm.local sudo /sbin/shutdown -r now
+		case ssh
+			ssh tdm.local
+		case screenshare
+			#ssh -xfNMS "$HOME/.ssh/tdm-fwd" -L 5901:localhost:5900 tdm.local
+			open vnc://tdm._rfb._tcp.local
+		case \*
+			echo "Usage: tdm {cmdf2|goodnight|fans|temps|hwinfo|tbinfo|shutdown|reboot|wake|ssh|screenshare}"
+	end
+end

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+[submodule "cmdf2/lib/Karabiner-VirtualHIDDevice"]`
	`2`	`+ path = cmdf2/lib/Karabiner-VirtualHIDDevice`
	`3`	`+ url = https://github.com/pqrs-org/Karabiner-VirtualHIDDevice-archived`