RehabMan / OS-X-ACPI-Debug

A kernel extension and DSDT patches to enable debug tracing from ACPI code (DSDT) to system.log

Written by RehabMan 2013-10-15

Advanced Configuration and Power Interface (ACPI) based kernel extension for debugging DSDT code.  This kext allows one to easily trace variables and execution path from DSDT (or SSDT) code.

Installation:

To use it you must install the two components that make up the software.  First of all, you must patch your DSDT to add the RMDT (RehabMan Debug Trace) device.  The presence of this device allows the kext to load.  Apply the debug.txt patch via MaciASL.  You can also add this repo as a MaciASL "source" in MaciASL preferences: http://raw.github.com/RehabMan/OS-X-ACPI-Debug/master.

Second, you must install the kext (ACPIDebug.kext).  You can build it at the command line with 'make' and install it with Kext Wizard (or your favorite kext installer), or you can install it at the command line with 'make install'.  Of course, you can also build it with Xcode.  I'm using Xcode 5.0 at the moment.  You can also use my pre-built kext downloaded from bitbucket.  Links are provided below.

Third, add code to your DSDT to where you wish to cause trace messages to system.log (call \RMDT.PUSH).


Change Log:

2015-05-07

- fix minor thread sync bug that would cause a spurious 0x0 to be output


2013-01-17

- added ability to force calls into DBGx methods in RMDT device via 'ioio' utility


2013-10-15

- initial release


Downloads and more information:


Downloads are available on Bitbucket: https://bitbucket.org/RehabMan/os-x-acpi-debug/downloads/


Please see this thread on tonymacx86.com: http://www.tonymacx86.com/dsdt/111868-dsdt-debugging-tracing-system-log.html

-or-

http://www.insanelymac.com/forum/topic/292800-dsdt-debuggingtracing-to-systemlog/



Using the tracing facility:

The DSDT patch adds the RMDT device at the root of your DSDT.  There are several methods you can use from within the DSDT to "push" debug output to the kext:

PUSH: Takes a single parameter (of any type, including Packages and Buffers).  The contents of this parameter will be displayed by the kext to system.log.

P1, P2 through P7.  P1 does exactly the same as PUSH.  Each of these utility methods takes 1 to 7 parameters (according to the name of the method).  This makes it easy to provide descriptions for your data or have multiple variables displayed on one line in system.log.

The other methods COUN, and FTCH are part of the implementation.  These methods are called by ACPIDebug.kext to pull information.


Examples:

\RMDT.PUSH("Entering _WAK")
output: ACPIDebug: "Entering _WAK"

\RMDT.PUSH(Local0)
example output: ACPIDebug: 0x10

\RMDT.P2("Local0", Local0)
example output: ACPIDebug: { "Local0", 0x10, }

\RMDT.P4("OSFL() returns", OSFL(), "OSVR is", OSVR)
example output: ACPIDebug: { "OSFL() returns", 0xABC, "OSVR is", 0x60, }

Name(TEST, Buffer() { 128, 255, 10, 127 }
\RMDT.P1(TEST)
example output: ACPIDebug: { 0x80, 0xFF, 0x0A, 0x7F, }

Name(TEST, Package() { Package() { 128, 255 }, Package() { 1, 2, 3, 10 })
example output: ACPIDebug: { { 0x80, 0xFF }, { 0x1, 0x2, 0x3, 0xA }, }


How it works:

Internally the RMDT device maintains a ring buffer of objects added via PUSH (ring buffer uses a Package).  The ring buffer size is 256.  The ACPIDebug.kext polls the RMDT device (via FTCH) every 100ms to see if any objects are available for printing.  If they are they are pulled from the ring buffer and output to system.log (it is a FIFO ring).  Objects added to the ring buffer when it is full are ignored.


Forcing calls into RMDT from Terminal:

With the latest changes you can also force calls into methods in RMDT by using ioio.  For ioio, see: https://github.com/RehabMan/OS-X-ioio

The mapping of properties to methods is as follows:

dbg0 -> DBG0
dbg1 -> DBG1
...
dbg9 -> DBG9

The methods will take one parameter (which is the value that the property was set to).  The return value of the method is ignored.

So, in the RMDT device, you can add a method as such:

Method(DBG0, 1, Serialized)
{
   \RMDT.P2("DBG0 Arg0=", Arg0)
   If (LEqual(Arg0, 5))
   {
      \RMDT.P1("You set dbg0 to 5")
   }
   Else 
   { 
      \RMDT.P1("You set dbg0 to something other than 5")
   }
}

You could, of course, output any other DSDT data you wanted to in that method.

In order to trigger the method, set the 'dbg0' property with ioio:

# in Terminal
ioio -s org_rehabman_ACPIDebug dbg0 5