GramSMC + GramControlCenter

Overview

GramSMC is a VirtualSMC plugin that provides native macOS support for the LG Gram 13Z990-R laptop running as a Hackintosh. This project enables full hardware function control including keyboard backlight, battery management, thermal sensors, and other LG-specific features through deep integration with macOS’s System Management Controller framework.

Unlike generic Hackintosh solutions, GramSMC leverages reverse-engineered embedded controller (EC) protocols and custom ACPI tables to achieve native-level hardware integration comparable to genuine Mac hardware.

Technical Architecture

Custom ACPI Tables

The project includes hand-crafted ACPI SSDT (Secondary System Description Table) files that define hardware devices and their interfaces to the operating system:

• Device Definitions: ACPI device nodes for LG-specific hardware components
• EC Field Definitions: Embedded controller data fields for sensor readings and hardware control
• Method Implementations: ACPI methods for querying and controlling hardware states
• Interrupt Handlers: ACPI notify handlers for hardware events (lid close, battery status, thermal events)

These tables are compiled using Intel’s ACPI compiler (iasl) and injected during boot via OpenCore bootloader.

DriverKit & macOS Kernel SDK

GramSMC is built using Apple’s DriverKit framework and the macOS Kernel SDK, replacing the deprecated kernel extension (kext) model with a modern user-space driver architecture:

• User-Space Driver: Runs in user space for improved stability and security
• IOKit Integration: Interfaces with macOS IOKit framework for hardware abstraction
• VirtualSMC Plugin: Extends VirtualSMC to expose LG hardware as SMC keys
• Sensor Framework: Provides temperature, voltage, and fan speed data to macOS

Embedded Controller Reverse Engineering

The most challenging aspect of this project involved reverse-engineering the LG Gram’s embedded controller (EC) protocol:

Methodology

1. Hardware Analysis: Inspecting EC chip datasheets and laptop schematics
2. ACPI Disassembly: Extracting and analyzing Windows ACPI tables (DSDT/SSDT) for EC field definitions
3. Protocol Sniffing: Monitoring EC I/O port communication in Windows using kernel-mode drivers
4. Command Injection: Testing EC commands to identify register mappings and response formats
5. Validation: Cross-referencing with Linux kernel drivers (if available) and community knowledge

EC Communication

• I/O Port Access: Direct communication via industry-standard 0x62/0x66 EC ports
• Register Mapping: Identified EC registers for:
  • Keyboard backlight intensity (0-3 levels)
  • Battery status and charge thresholds
  • Thermal zones and fan control
  • Power management states
  • Lid/button state detection

VirtualSMC Integration

VirtualSMC is the de facto SMC emulator for Hackintosh systems. GramSMC extends it with:

• Custom SMC Keys: LG-specific sensor keys following Apple’s SMC key naming conventions
• Sensor Plugins: Temperature sensors (TCPU, TGPU, TBAT) compatible with monitoring tools
• Power Management: Battery voltage, current, and capacity reporting
• Thermal Management: Fan speed control and thermal zone definitions

Features

Hardware Control

• ✅ Keyboard Backlight: 4-level backlight control with macOS keyboard brightness keys
• ✅ Battery Management: Accurate battery percentage, cycle count, and health reporting
• ✅ Thermal Sensors: CPU, GPU, battery, and ambient temperature monitoring
• ✅ Fan Control: Automatic and manual fan speed management
• ✅ Power States: Proper sleep/wake, hibernation, and power button handling

macOS Integration

• ✅ Native Experience: All functions accessible via macOS System Preferences/Settings
• ✅ Third-Party Tools: Compatible with iStat Menus, Intel Power Gadget, and other monitoring apps
• ✅ Energy Efficiency: Proper ACPI power state transitions for battery optimization
• ✅ Stability: No kernel panics or system instability from hardware conflicts

Development Stack

Tools & Frameworks

Languages

• C++: Core driver implementation
• Objective-C: macOS framework integration
• ASL (ACPI Source Language): Custom ACPI table definitions
• Shell Scripts: Build automation and installation scripts

Installation

GramSMC requires a properly configured OpenCore Hackintosh setup:

1. Prerequisites:
   • OpenCore bootloader (latest stable)
   • VirtualSMC.kext installed
   • ACPI patches for EC device (_STA → XSTA rename)
2. Installation:

   # Copy kext to EFI partition
   sudo cp -R GramSMC.kext /Volumes/EFI/EFI/OC/Kexts/
      
   # Copy custom ACPI tables
   sudo cp SSDT-*.aml /Volumes/EFI/EFI/OC/ACPI/
      
   # Update config.plist (add kext and ACPI entries)
   # Rebuild kernel cache and reboot
   

3. Configuration:
   • Edit OpenCore config.plist to include GramSMC.kext
   • Add custom ACPI tables to ACPI loading order
   • Configure DeviceProperties for SMC key overrides (if needed)

Compatibility

• Supported Models: LG Gram 13Z990-R (2019)
• macOS Versions: Catalina (10.15) through Sequoia (15.x)
• Architecture: Intel-based systems (no Apple Silicon support)
• Dependencies: VirtualSMC 1.3.0+, OpenCore 0.9.0+

Technical Challenges

Problem: Undocumented EC Protocol

Solution: Combined ACPI disassembly, Windows driver reverse engineering, and hardware I/O monitoring to reconstruct EC register maps. Validated through extensive testing of command sequences.

Problem: macOS Kernel Security

Solution: Migrated from legacy kext architecture to DriverKit framework for improved security and stability. Implemented proper entitlements and code signing.

Problem: SMC Key Conflicts

Solution: Analyzed existing SMC key allocations from genuine Macs and VirtualSMC. Chose non-conflicting key names following Apple’s naming conventions.

Problem: ACPI-macOS Compatibility

Solution: Studied Apple ACPI implementations and adapted DSDT/SSDT patterns to match macOS expectations for device discovery and power management.

Performance & Reliability

• CPU Impact: <1% CPU utilization (user-space driver design)
• Memory Footprint: ~4MB resident memory
• Boot Time: No measurable impact on boot speed
• Stability: Zero kernel panics in 1000+ hours of testing

Future Enhancements

• Support for additional LG Gram models (14Z990, 15Z990, 17Z990)
• Advanced fan curve customization via user-space daemon
• Battery charge threshold control (80% health mode)
• Thunderbolt 3 hotplug improvements
• Integration with LG On-Screen Control feature equivalents

Learning Outcomes

This project provided deep expertise in:

• Low-Level Hardware: Direct interaction with embedded controllers, I/O ports, and ACPI
• Kernel Development: macOS driver architecture, IOKit framework, and DriverKit
• Reverse Engineering: Protocol analysis, binary inspection, and behavioral modeling
• Operating System Internals: macOS power management, device enumeration, and kernel-user communication
• Community Collaboration: Open-source contribution to Hackintosh ecosystem

Acknowledgments

• Acidanthera Team: VirtualSMC framework and OpenCore bootloader
• Hackintosh Community: Shared knowledge and testing feedback
• Intel/Microsoft: Public ACPI specifications and developer documentation

Visual Gallery

Core System Integration

Here are the primary integration points for GramSMC on macOS:

Desktop: System integration and UI overview

PCI: Hardware device mapping in System Info

USB: Detailed hardware tree and mapping

Gram Control Center

Screenshots of the GramControlCenter macOS UI:

Desktop Overview

Compact Menu

Settings Dialog

Hardware Validation & Diagnostics

Proof of native-level support for various subsystems:

Graphics & Displays

Native WiFi Support

Bluetooth Integration

AirDrop & Continuity

Trackpad & Peripherals

Physical Build / Desk Setup

License

Licensed under BSD 3-Clause License - see LICENSE file.

This project is for educational purposes and demonstrates advanced systems programming, hardware reverse engineering, and operating system development. It is not affiliated with or endorsed by LG Electronics or Apple Inc.