Lunar 2.5.0 技术解析:DDC 实现回退 C 语言与多显示器支持
Lunar 2.5.0 技术解析:DDC 实现回退 C 语言与多显示器支持
导读
Lunar 是一款面向 macOS 外接显示器的智能亮度调节工具。2.5.0 是一个以"稳定优先"为核心的修复版本:它把 2.4.0 中刚迁移到 Swift 的 DDC(Display Data Channel)处理代码整体回退到 C 实现,同时补齐了多显示器场景下的支持,并修复了 2.4.0 引入的"仅部分连接器类型可工作"的回归问题。阅读本文后,你将理解 Lunar 的 DDC 读写链路如何在 Swift 与 C 之间分层协作、显示器是如何通过 EDID 与 IOKit 匹配的,以及 2.4.0 → 2.5.0 这次"回退"背后的工程动机。
一、背景:2.4.0 的 Swift 化重写及其代价
2.4.0 发布说明 中明确记录了一次架构层面的尝试:
- 新增诊断工具(菜单栏点击 Open Lunar diagnostics 可导出日志);
- 完整的多显示器支持;
- 使用系统生成的 UUID 按显示器存储设置;
- 将 DDC 处理代码转换为 Swift("Convert to DDC handling code to Swift")。
而 2.5.0 发布说明 则宣告这次迁移的纠偏:
- Revert DDC to C implementation with added multi-monitor support
- Fix 2.4.0 regression where only some types of connectors worked
也就是说,2.4.0 用 Swift 重写的 DDC 层在真实硬件上暴露了兼容性问题:只有部分类型的连接器(connector)能够正常工作。DDC/CI 依赖 I2C 总线事务,不同显卡厂商、不同连接方式(DP、HDMI、DVI、VGA 等)对 I2C 事务类型的支持差异很大,Swift 重写层对事务类型的探测与容错不如久经考验的 C 实现稳健。因此 2.5.0 的决定是回退到 C 实现,并在此基础上继续完善多显示器支持。
这一决策在当前仓库源码中有清晰的印证:Lunar/DDC/ 目录下保留着完整的 DDC.c(589 行)、DDC.h、SharedDDC.h,而 Swift 侧(Lunar/DDC/DDC.swift)仅承担高层调度与容错逻辑,通过 Lunar-Bridging-Header.h 桥接 DDC.h 与 DDC2.h 暴露的 C 函数。
二、回退后的架构:Swift 调度 + C 事务的双层结构
2.5.0 之后的 DDC 链路是清晰的两层结构:
Swift 层(DDC.swift)
├─ DDC.write(displayID:controlID:newValue:) 高层写入
├─ DDC.read(displayID:controlID:) 高层读取
└─ DDC.I2CController(displayID:) framebuffer 定位与缓存
C 层(DDC.c)
├─ DDCWriteIntel / DDCReadIntel 构造并发送 I2C 请求
├─ FramebufferI2CRequest I2C 请求的发送/重试
├─ IOFramebufferPortFromCGDisplayID EDID ↔ CGDisplayID 匹配
└─ SupportedTransactionType I2C 事务类型探测
IOKit(IOI2CInterface)→ 显卡 → 显示器
关键证据在 DDC.swift 的写入路径中:Swift 侧在调用 C 函数前会做大量前置判断(DC.screensSleeping、DC.locked、apply 开关),并按 CPU 架构分派——arm64 走 DCP(Apple Silicon 的 Display Control Path),Intel 走 I2CController 获取的 framebuffer 后调用 DDCWrite(fb:command:sourceAddr:)。这正是"C 实现 + 多平台兼容"的体现:
#if arch(arm64)
guard let dcp = DCP(displayID: displayID) else { return false }
#else
guard let fb = I2CController(displayID: displayID) else { return false }
#endif
var command = DDCWriteCommand(control_id: localControlID.rawValue, new_value: newValue)
let result = DDCWrite(fb: fb, command: &command, sourceAddr: localSourceAddr)
读取路径 DDC.read(DDC.swift)同样构造 DDCReadCommand 后交给 C 函数,并从 command.max_value / current_value 取出结果,封装为 DDCReadResult 返回。
三、多显示器支持:EDID 与 CGDisplayID 的匹配算法
2.5.0 强调的 "added multi-monitor support",其核心在 IOFramebufferPortFromCGDisplayID(DDC.c)这个 C 函数中实现。它的工作流程可以分解为四步:
- 生成显示 UUID:通过
CGDisplayCreateUUIDFromDisplayID(displayID)为当前 CG 显示生成 UUID; - 遍历所有 framebuffer:用
IOServiceMatching(IOFRAMEBUFFER_CONFORMSTO)枚举 IORegistry 中的全部 framebuffer 服务,逐个读取其 EDID(EDIDCreateFromFramebuffer); - EDID 去重匹配:维护一个
displayUUIDByEDID字典(CFMutableDictionary,以 EDID 数据为 key),若某 EDID 已关联过其他 UUID 则跳过,防止同一显示器被重复映射; - 元数据比对:读取 framebuffer 的
kDisplayVendorID、kDisplayProductID、kDisplaySerialNumber,与CGDisplayVendorNumber / CGDisplayModelNumber / CGDisplaySerialNumber逐一比对,全部吻合才判定为该 CGDisplayID 对应的 framebuffer,并写入缓存字典。
代码中的一段注释直指多显示器的难点(DDC.c):
// SN is zero in lots of cases, so duplicate-monitors can confuse us :-/
即很多显示器序列号(Serial Number)为零,同型号多显示器可能互相混淆,因此必须结合 vendor + product + EDID 多重特征做匹配,而不是依赖单一字段。
此外 SharedDDC.h 定义了与 EDID 1.3/1.4 标准逐位对应的 struct EDID(厂商 ID、产品码、序列号、时序描述符、扩展块等),Swift 侧通过 DDC.getEdid(displayID:) / getEdidData 可直接拿到解析后的 EDID 信息,用于显示器识别与名称提取。
四、连接器兼容性修复:事务类型探测与逐总线重试
2.5.0 修复的 "only some types of connectors worked",从源码看主要对应两个机制:
4.1 SupportedTransactionType:探测可用的 I2C 事务类型
SupportedTransactionType 会枚举 IOFramebufferI2CInterface 服务,读取其 kIOI2CTransactionTypesKey 属性,按位检查该总线支持哪些事务类型:
kIOI2CSimpleTransactionType(简单 I2C 消息)kIOI2CDDCciReplyTransactionType(DDC/CI 内嵌长度的回复事务)kIOI2CCombinedTransactionType、kIOI2CDisplayPortNativeTransactionType等(在 DEBUG 构建下也会逐一打印)
生产构建优先选择 Simple 或 DDCci 类型,且只要探测到任一可用类型就立即返回(注释说明 macOS 通常提供三个 framebuffer 设备,但拿到一个可用事务类型即可)。这意味着无论显示器通过哪种连接器接入,只要该总线上存在受支持的 I2C 事务类型,DDC 读写就能执行——这正是修复"仅部分连接器可用"的关键。
4.2 FramebufferI2CRequest:逐总线尝试 + 串行化
FramebufferI2CRequest 在发送请求时:
- 用
IOFBGetI2CInterfaceCount获取 framebuffer 的 I2C 总线数量; - 从 bus 0 开始逐条
IOFBCopyI2CInterfaceForBus打开接口,IOI2CSendRequest成功即跳出; - 每个 framebuffer 通过
dispatch_semaphore(见 I2CRequestQueue)串行化,避免并发 I2C 事务互相干扰; - 对无回复事务(
kIOI2CNoTransactionType)额外usleep(20000)(20ms),给显示器留出处理时间。
五、读写事务协议细节:校验和、重试与显卡延迟补偿
5.1 写入:7 字节 DDC/CI 写命令
DDCWriteIntel 构造一个 7 字节的写请求:
data[0] = sourceAddr; // 源地址(默认 0x51,LG 输入源切换时为 0x50)
data[1] = 0x84; // DDC/CI 协议标识
data[2] = 0x03; // 写命令操作码
data[3] = write->control_id; // VCP 控制码,如 BRIGHTNESS 0x10
data[4] = (write->new_value) >> 8; // 目标值高字节
data[5] = write->new_value & 255; // 目标值低字节
data[6] = 0x6E ^ ...; // 整包异或校验和
0x6E 为写目标地址(显示器端 DDC/CI 地址),整个包以异或方式校验,任何字节出错都会被显示器拒绝。
5.2 读取:最多 10 次重试 + 40ms 恢复间隔
DDCReadIntel 使用 11 字节回复缓冲区,发送 5 字节读命令(含 0x51 源地址、0x82 读操作码、控制码与校验和),并按 VESA DDC/CI 规范 4.4.1 节的通信错误恢复策略实现重试:
- 单次失败后
usleep(40000)(40ms)再试; - 上限
kMaxRequests = 10,全部失败则置success = false、max_value/current_value = 0并记录错误日志; - 每次回复都要校验 5 个地址/长度字段和末尾的异或校验和;
- 成功时
max_value = reply_data[7]、current_value = reply_data[9]。
5.3 显卡延迟补偿:AMD 需要"多一点时间"
DDCDelay 根据 framebuffer 的 IORegistry 路径判断显卡厂商,对 AMD 显卡将最小回复延迟上调 30ms,代码注释写道:
if (CFStringFind(ioRegPath, CFSTR("/AMD"), kCFCompareCaseInsensitive).location != kCFNotFound) {
return DDCDelayBase + 30000000; // Team Red needs more time, as usual!
}
Swift 侧的常量亦与此对应(DDC.swift):DDC_MIN_REPLY_DELAY_AMD = 30_000_000,Intel/NVIDIA 为 1。延迟值不当在极端情况下甚至可能引发内核问题(源码注释明确警告 "kernel panics are possible if value is wrong"),这也是此类底层代码更倾向保守的 C 实现的原因之一。
六、Swift 侧的容错与可观测性
虽然底层回退到 C,Swift 层仍承担着重要的运行保护与诊断职责(这些能力源自 2.4.0 引入的诊断体系并在 2.5.0 得以延续):
- 超时熔断:单次读超过
MAX_READ_DURATION_MS = 1500ms、写超过MAX_WRITE_DURATION_MS = 2000ms 会被记为严重故障(DDC.swift); - 故障累积:
readFault/writeFault按显示器 + 控制码累计故障分,分别超过MAX_READ_FAULTS = 10、MAX_WRITE_FAULTS = 20后,通过skipReadingProperty/skipWritingProperty永久跳过该属性,避免对不响应 DDC 的显示器反复发请求(DDC.swift); - 耗时统计:每次读/写耗时通过
DC.averageDDCReadNanoseconds / averageDDCWriteNanoseconds(DisplayController.swift)记录并平滑,作为诊断日志的一部分。
这些机制与 2.4.0 的 Open Lunar diagnostics 菜单互为表里:当用户反馈某台显示器 DDC 异常时,开发者可以通过日志看到"哪块 framebuffer、哪个 VCP 控制码、失败次数与耗时",快速定位是硬件、连接器还是驱动层面的问题。
七、VCP 控制码速查(源码级参考)
DDC.h 与 DDC.swift 中定义了大量 VCP 控制码,其中与 Lunar 日常功能最相关的是:
| 控制码 | 十六进制 | 用途 |
|---|---|---|
| BRIGHTNESS | 0x10 | 亮度(Lunar 核心调节项) |
| CONTRAST | 0x12 | 对比度 |
| INPUT_SOURCE | 0x60 | 输入源切换(HDMI/DP/DVI 等) |
| AUDIO_SPEAKER_VOLUME | 0x62 | 扬声器音量 |
| AUDIO_MUTE | 0x8D | 音频静音 |
| RED/GREEN/BLUE_GAIN | 0x16/0x18/0x1A | 色彩增益 |
| POWER_CONTROL | 0xE1 | 电源控制 |
| RESET_BRIGHTNESS_AND_CONTRAST | 0x05 | 亮度/对比度复位 |
输入源切换还涉及一段特殊的兼容逻辑(DDC.swift):当目标输入源属于 LG 厂商特定编码(如 lgSpecificHdmi1 = 0x90)时,Swift 层会自动把源地址改为 0x50、控制码改用 MANUFACTURER_SPECIFIC_F4,这是对 LG 显示器专有命令的适配。
结语
2.5.0 的意义并非"新功能",而是一次审慎的架构回退:在功能(多显示器)与稳定(连接器兼容)发生冲突时,选择以经过长期验证的 C 实现作为地基。从当前仓库源码看,这条"Swift 调度 + C 事务"的分层至今仍是 Lunar DDC 链路的骨架——Swift 负责状态判断、超时、熔断与统计,C 负责精确到字节的 I2C 协议交互。对于想要深入 DDC/CI 开发或排查多显示器亮度调节问题的开发者,Lunar/DDC/DDC.c 与 Lunar/DDC/DDC.swift 是最直接的参考实现。