ASL Code中的_DSM方法

一、HID I2C设备的”_DSM”方法

_DSM方法一共有4个参数，分别为Arg0、Arg1、Arg2、Arg3。该方法的具体定义以及每个参数的含义请参看ACPI 5.0规范的9.14.1小节（可直接参看本文最后附录）。

该方法主要是提供了一些与设备相关的数据和操作方法，以供驱动去调用。根据微软给出的"WindowsACPI Design Guide for SOC Platforms”中的定义，对于HIDI2C设备，驱动在调用_DSM方法时传递的参数为：

·        Arg0: UUID =3cdff6f7-4267-4555-ad05-b30a3d8938de

·        Arg1: Revision ID = 1

·        Arg2: Function index = 1

·        Arg3: None

对于HIDI2C设置该方法的返回值是一个包含HID描述符地址的整数。这个地址也即HID I2C Driver向固件读取HID描述符的I2C寄存器地址，目前的Nanjing固件支持的HID描述符地址为：0x0000。

二、_DSM方法中各参数的意义

_DSM方法提供的都是与具体设备相关的操作及数据，该方法一共具备4个参数，我们对其中用到较多的前三个参数做一下详细的解释。

Arg0 – A Buffercontaining a UUID

Arg0是一个UUID，用于标识不同的设备，在Windows上对于不同的设备该UUID是有固定值的，具体可参看“WindowsACPI Design Guide for SOC Platforms”。

Arg1 – An Integercontaining the Revision ID

Arg1是Function的版本ID，它是于UUID相关联的。

Arg2 – An Integercontaining the Function Index

Arg2是Function索引号，它的设置较为复杂一些。该索引号从1开始，索引号0是被固定保留给了查询功能的。

当Driver调用_DSM方法时，会传递不同的Function索引号值给_DSM方法，如1、2、3或4等等，_DSM方法接收到Driver传递过来的索引号后，会根据具体的索引号值执行不同的操作或返回数据。

Driver和_DSM之间关于各个Function索引号的功能是有约定的，对于不同的UUID（Arg0）和版本ID（Arg1），相对应的Function索引号数量和各个Function索引号所对应的功能也会不同，比如：对于HID I2C设备，索引号1，也即Arg2=1，代表的是获取HID描述符所在的寄存器地址。

另外，对于索引号0，也即Arg2=0，是由系统所保留的一个功能，也即所有的_DSM都具备该方法，它返回的是一个整形数组，数组中的数据用于标识该_DSM支持哪几个Function索引号，具体如下：

switch(Arg2)
{
  //
  // Function 0: Return supportedfunctions, based on revision
  //
  case(0)
  {
    switch(Arg1)
    {
      // revision 0: functions 1-4 aresupported
        case(0) {return (Buffer(){0x1F})}
      // revision 1: functions 1-5 aresupported
        case(1) {return (Buffer(){0x3F})}
    }
    // revision 2+: functions 1-7 aresupported
    return (Buffer() {0xFF})
  }

…….

}

比如上面的一般示例代码，当Function索引号为0时，也即Arg2case 0时，_DSM会根据Function版本号的不同（也即Arg1的不同）返回不同的值。当Arg1=0时，返回值是0x1F，将其展开为二进制数据也即：00011111，从bit0到bit7，分别代表Function索引号0到7，当对应的bit位为1时表示支持相应的Function索引号。由于Function索引号0是必须具备的，所以00011111也即代表该_DSM支持Function 1-4。其实所谓支持的意思，也即在该_DSM中会有相应的Function索引号的语句动作。

三、示例代码

示例代码中标红的部分就是该方法对于HID I2C设备的返回值，也即Arg0=3CDFF6F7-4267-4555-AD05-B30A3D8938DE、Arg1=1、Arg2=1时，_DSM的返回值必须为0x0000。此时HID I2CDriver才会向固件发送读取I2C地址0x0000的命令，固件才会返回正确的HID描述符给HID I2C Driver。

具体的_DSM方法的定义，请参看如下示例代码：

Method(_DSM, 0x4,Serialized) {

 

     If(LEqual(Arg0, ToUUID("3CDFF6F7-4267-4555-AD05-B30A3D8938DE"))){

        // DSMFunction

       switch(ToInteger(Arg2)) {

              //Function 0: Query function, return based on revision

            case(0){

                //DSM Revision

               switch(ToInteger(Arg1)) {

                   // Revision 1: Function 1 supported

                 case(1) {

                   // Store ("Method _DSM Function Query", Debug)

                     Return(Buffer(One) { 0x03 })

                   }

                  default{

                     // Revision 2+: no functions supported

                     Return(Buffer(One) { 0x00 })

                   }

                }

              }

              //Function 1 : HID Function

            case(1){

             //Store ("Method _DSM Function HID", Debug)

               //HID Descriptor Address

               Return(0x0000)

            }

            default{

              //Functions 2+: not supported

             Return(0x0000)

            }

        }

      } else {

        // No otherGUIDs supported

       Return(Buffer(One) { 0x00 })

      }

   

}

四、附录

9.14.1_DSM (Device Specific Method)
This optional object is a control method thatenables devices to provide device specific control
functions that are consumed by the device driver.
Arguments: (4)
Arg0 – A Buffercontaining a UUID
Arg1 – An Integer containingthe Revision ID
Arg2 – An Integer containingthe Function Index
ACPI-DefinedDevices and Device-Specific Objects
468Hewlett-Packard/Intel/Microsoft/Phoenix/Toshiba
Arg3 – A Packagethat contains function-specific arguments
Return Value:
If Function Index = 0, a Buffercontaining a function index bitfield. Otherwise,the return value and type depends on the UUID and revision ID (see below).
ArgumentInformation:
Arg0: UUID– A Buffer containing the Universal UniqueIdentifier (16 Bytes)
Arg1: Revision ID –the function’s revision. This revision is specific to the UUID.
Arg2: Function Index –Represents a specific function whose meaning is specific to the UUID
and Revision ID. Function indices should start with 1. Function number zero isa query function (see the special return code defined below).
Arg3: Arguments – apackage containing the parameters for the function specified by theUUID, RevisionID and FunctionIndex. Successive revisions ofFunctionArguments must be backward compatiblewith earlier revisions. SeeSection 9 “ACPIDevices and Device Specific Objects”, for any _DSM definitions for ACPIdevices. New UUIDs may also be created by OEMs and IHVs for custom devices andother interface or device governing bodies (e.g. the PCI SIG), as long as the UUIDis different from other published UUIDs. Only the issuer of a UUID canauthorize a newFunction Index, RevisionID or FunctionArgument for that UUID.
ReturnValue Information:
If FunctionIndex is zero, the return is abuffer containing one bit for each function index, starting with zero. Bit 0indicates whether there is support for any functions other than function 0 forthe specified UUID and Revision ID. If set to zero, no functions are supported(other than function zero) for the specified UUID and Revision ID. If set toone, at least one additional function is supported. For all other bits in thebuffer, a bit is set to zero to indicate if that function index is notsupported for the specific UUID and Revision ID. (For example, bit 1 set to 0indicates that function index 1 is not supported for the specific UUID andRevision ID.) If the bit representing a particular function index would lieoutside of the buffer, it should be assumed to be 0 (that is, not supported).
If Function index isnon-zero, the return is any data object. The type and meaning of the returned dataobject depends on theUUIDand RevisionID.
ImplementationNote
Since the purpose of the _DSM method is to avoidthe namespace collision, the implementation of this method shall not use anyother method or data object which is not defined in this specification unlessits driver and usage is completely under the control of the platform vendor.
AdvancedConfiguration and Power Interface Specification
Hewlett-Packard/Intel/Microsoft/Phoenix/Toshiba469
Example:
//_DSM – Device Specific Method
//
// Arg0: UUID Unique function identifier
// Arg1: Integer Revision Level
// Arg2: Integer Function Index (0 = Return Supported Functions)
// Arg3: Package Parameters
Function(_DSM,{IntObj,BuffObj},{BuffObj, IntObj, IntObj, PkgObj})
{
//
// Switch based on which unique function identifier was passed in
//
switch(Arg0)
{
//
// First function identifier
//
case(ToUUID(“893f00a6-660c-494e-bcfd-3043f4fb67c0”))
{
switch(Arg2)
{
//
// Function 0: Return supported functions, based on revision
//
case(0)
{
switch(Arg1)
{
// revision 0: functions 1-4 are supported
case(0) {return (Buffer() {0x1F})}
// revision 1: functions 1-5 are supported
case(1) {return (Buffer() {0x3F})}
}
// revision 2+: functions 1-7 are supported
return (Buffer() {0xFF})
}
//
// Function 1:
//
case(1)
{
… function 1 code …
Return(Zero)
}
//
// Function 2:
//
case(2)
{
… function 2 code …
Return(Buffer(){0x00})
}
case(3) { … function 3 code …}
case(4) { … function 4 code …}
case(5) { if (LLess(Arg1,1) BreakPoint; … function 5 code … }
case(6) { if (LLess(Arg1,2) BreakPoint; … function 6 code … )
case(7) { if (LLess(Arg1,3) BreakPoint; … function 7 code … )
default {BreakPoint }
}
}
//
// Second function identifier
//
case(ToUUID(“107ededd-d381-4fd7-8da9-08e9a6c79644”))
{
//
// Function 0: Return supported functions (there is only one revision)
//
if (LEqual(Arg2,Zero))
return (Buffer() {0x3}) // only one function supported
//
// Function 1
//
if (LEqual(Arg2,One))
{
… function 1 code …
Return(Unicode(“text”))
}
//
// Function 2+: Runtime Error
//
else
BreakPoint;
}
}
//
// If not one of the function identifiers we recognize, then return a buffer
// with bit 0 set to 0 indicating no functions supported.
//
return(Buffer(){0})
}