枚举子设备和控制方法

  • 项目

在 ACPI 命名空间中，作为设备的对象（例如，名为“ABCD”的设备）可以具有子对象，这些子对象是设备的子设备，也可以是设备支持的控制方法。 作为父设备的子设备的任何子对象反过来也可以采用递归方式拥有作为子设备或控制方法的子对象。

例如，在以下简化的 ACPI 命名空间中，ACPI 命名空间的根由“\”指定，对象“ABCD”是作为 ACPI 命名空间根的直接子级的设备。 此外，设备“ABCD”有两个名为“CHL1”和“CHL2”的直接子设备，以及作为名为“_FOO”的控制方法的子对象。 此外，子设备“CHL2”具有名为“CHL3”的子设备，设备“CHL3”具有作为名为“_FOO”的控制方法的子对象。

\     root of ACPI namespace
 ABCD            parent device 
    CHL1         child device of ABCD
    CHL2         child device of ABCD
       CHL3      child device of CHL2
          _FOO   control method
 _FOO            control method

若要使用 IOCTL_ACPI_EVAL_METHOD_EX 或 IOCTL_ACPI_ASYNC_EVAL_METHOD_EX，设备的驱动程序应在 ACPI 命名空间中提供控制方法的路径和名称。 为了帮助获取设备的路径和名称以及设备的子对象，Windows 支持 IOCTL_ACPI_ENUM_CHILDREN 请求。 以本部分提供的简化的 ACPI 命名空间为例，设备“ABCD”设备堆栈中的驱动程序可以使用此请求执行以下操作：

  • 枚举设备“ABCD”以及“ABCD”的直接子设备。 例如，该请求可用于返回“\ABCD”、“\ABCD.CHL1”和“\ABCD.CHL2”。

  • 以递归方式枚举“ABCD”命名空间中的所有设备。 例如，该请求可用于返回“\ABCD”、“\ABCD.CHL1”、“\ABCD.CHL2”和“\ABCD.CHL2.CHL3”。

  • 以递归方式枚举提供名称的“ABCD”的所有后代子对象。 提供的名称充当筛选器，以便仅枚举具有相同名称的子对象。 例如，对于提供的名称“_FOO”，该请求可用于返回“\ABCD._FOO”和“\ABCD.CHL2.CHL3._FOO”。

驱动程序获取控制方法的路径和名称后，可以提供路径和名称作为 IOCTL_ACPI_EVAL_METHOD_EX 或 IOCTL_ACPI_ASYNC_EVAL_METHOD_EX 的输入，如同步评估 ACPI 控制方法中所述。

IOCTL_ACPI_ENUM_CHILDREN 请求将采用驱动程序分配的可变长度 ACPI_ENUM_CHILDREN_INPUT_BUFFER 结构作为输入，该结构包含以下成员：

Signature

输入缓冲区的签名，必须设置为 ACPI_ENUM_CHILDREN_INPUT_BUFFER_SIGNATURE。

Flags

一个标志，用于确定 ACPI 驱动程序枚举的设备 ACPI 命名空间中的对象。 ACPI 驱动程序返回以 ACPI 命名空间根开头的枚举对象的完整路径和名称。 必须将此标志设置为以下值之一：

标记 说明
ENUM_CHILDREN_IMMEDIATE_ONLY 枚举设备并枚举设备的直接子设备。
ENUM_CHILDREN_MULTILEVEL 枚举设备，并以递归方式枚举设备的所有子设备。
ENUM_CHILDREN_NAME_IS_FILTER ENUM_CHILDREN 和 ENUM_CHILDREN_NAME_IS_FILTER 的按位 OR 会枚举名称与 Name 成员提供的名称相同的设备子对象。

NameLength

Name 数组包含的 ASCII 字符数。

Name

以 NULL 结尾的四个字符 ASCII 数组，其中包含 ACPI 驱动程序用于将子对象枚举限制为具有相同名称的对象的子对象的名称。

IOCTL_ACPI_ENUM_CHILDREN 请求会返回驱动程序分配的可变长度 ACPI_ENUM_CHILDREN_OUTPUT_BUFFER 中子对象的路径和名称，其中包含以下成员：

Signature

输出缓冲区的签名，必须设置为 ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE。

NumberOfChildren

Children 数组中 ACPI_ENUM_CHILD 类型的元素数。

Children

ACPI_ENUM_CHILD 类型的元素数组。 ACPI_ENUM_CHILD 结构的 Name 成员包含子对象的路径和名称，Flags 成员指示子对象是否具有子对象。

如果驱动程序分配的输出缓冲区不够大，无法返回所有枚举的子名称，ACPI 驱动程序将不返回任何子名称，并且会将设置 请求的 IO_STATUS_BLOCK 的 Status 成员设置为 STATUS_BUFFER_OVERFLOW。 在这种情况下，如果输出缓冲区的大小（以字节为单位）至少为 sizeof(ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE)，ACPI 驱动程序还会将 NumberOfChildren 设置为检索所请求路径和名称所需的大小（以字节为单位）。

另请参阅

发送 IOCTL_ACPI_ENUM_CHILDREN 请求。