Enumeración de dispositivos secundarios y métodos de control
En un espacio de nombres ACPI, un objeto que es un dispositivo(por ejemplo, un dispositivo denominado "ABCD"- puede tener objetos secundarios que son dispositivos secundarios del dispositivo o que son métodos de control admitidos por el dispositivo. Cualquier objeto secundario que sea un dispositivo secundario de un dispositivo primario puede, a su vez, tener objetos secundarios que sean dispositivos secundarios o métodos de control.
Por ejemplo, en el siguiente espacio de nombres ACPI simplificado, la raíz del espacio de nombres ACPI se designa mediante '\' y el objeto 'ABCD' es un dispositivo que es un elemento secundario inmediato de la raíz del espacio de nombres ACPI. Además, el dispositivo "ABCD" tiene dos dispositivos secundarios inmediatos denominados "CHL1" y "CHL2" y un objeto secundario que es un método de control denominado "_FOO". Además, el dispositivo secundario "CHL2" tiene un dispositivo secundario denominado "CHL3" y el dispositivo "CHL3" tiene un objeto secundario que es un método de control denominado "_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
Para usar IOCTL_ACPI_EVAL_METHOD_EX o IOCTL_ACPI_ASYNC_EVAL_METHOD_EX, un controlador para un dispositivo proporciona la ruta de acceso y el nombre del método de control en un espacio de nombres ACPI. Para ayudar a obtener la ruta de acceso y el nombre de un dispositivo y los objetos secundarios de un dispositivo, Windows admite la solicitud IOCTL_ACPI_ENUM_CHILDREN . Al hacer referencia al espacio de nombres ACPI simplificado proporcionado en esta sección como ejemplo, un controlador de la pila de dispositivos del dispositivo "ABCD" puede usar esta solicitud para hacer lo siguiente:
Enumerar el dispositivo "ABCD" y los dispositivos secundarios inmediatos de "ABCD". Por ejemplo, la solicitud se puede usar para devolver '\ABCD', '\ABCD. CHL1" y "\ABCD. CHL2.'
Enumera de forma recursiva todos los dispositivos del espacio de nombres "ABCD". Por ejemplo, la solicitud se puede usar para devolver '\ABCD', '\ABCD. CHL1", '\ABCD. CHL2" y "\ABCD. CHL2. CHL3.'
Enumera de forma recursiva todos los objetos secundarios descendientes de "ABCD" de un nombre proporcionado. El nombre proporcionado actúa como filtro para que solo se enumeren los objetos secundarios que tienen el mismo nombre. Por ejemplo, para un nombre proporcionado '_FOO', la solicitud se puede usar para devolver '\ABCD._FOO' y '\ABCD. CHL2. CHL3._FOO.'
Después de que un controlador obtenga la ruta de acceso y el nombre de un método de control, puede proporcionar la ruta de acceso y el nombre como entrada para IOCTL_ACPI_EVAL_METHOD_EX o IOCTL_ACPI_ASYNC_EVAL_METHOD_EX, como se describe en Evaluación de métodos de control ACPI de forma sincrónica.
Una solicitud de IOCTL_ACPI_ENUM_CHILDREN toma como entrada una estructura ACPI_ENUM_CHILDREN_INPUT_BUFFER de longitud variable asignada por el controlador que contiene los siguientes miembros:
Signature
Firma del búfer de entrada, que se debe establecer en ACPI_ENUM_CHILDREN_INPUT_BUFFER_SIGNATURE.
Flags
Marca que determina qué objetos del espacio de nombres ACPI de un dispositivo que el controlador ACPI enumera. El controlador ACPI devuelve la ruta de acceso completa y el nombre del objeto enumerado a partir de la raíz del espacio de nombres ACPI. La marca debe establecerse en uno de los siguientes valores:
| Marca | Descripción |
|---|---|
| ENUM_CHILDREN_IMMEDIATE_ONLY | Enumera el dispositivo y enumera los dispositivos secundarios inmediatos del dispositivo. |
| ENUM_CHILDREN_MULTILEVEL | Enumera el dispositivo y enumera de forma recursiva todos los dispositivos secundarios del dispositivo. |
| ENUM_CHILDREN_NAME_IS_FILTER | Un OR bit a bit de ENUM_CHILDREN y ENUM_CHILDREN_NAME_IS_FILTER enumera los objetos secundarios del dispositivo cuyo nombre es idéntico al proporcionado por el miembro Name . |
NameLength
Número de caracteres ASCII que contiene la matriz Name .
Name
Matriz ASCII terminada en NULL de cuatro caracteres que contiene el nombre de un objeto secundario que usa el controlador ACPI para restringir la enumeración de objetos secundarios a los objetos que tienen el mismo nombre.
La solicitud de IOCTL_ACPI_ENUM_CHILDREN devuelve la ruta de acceso y el nombre de los objetos secundarios en un ACPI_ENUM_CHILDREN_OUTPUT_BUFFER de longitud variable asignada por el controlador que contiene los miembros siguientes:
Signature
Firma del búfer de salida, que se debe establecer en ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE.
NumberOfChildren
Número de elementos de tipo ACPI_ENUM_CHILD en la matriz Children .
Children
Matriz de elementos de tipo ACPI_ENUM_CHILD. El miembro Name de una estructura de ACPI_ENUM_CHILD contiene la ruta de acceso y el nombre del objeto secundario, y el miembro Flags indica si el objeto secundario tiene objetos secundarios.
Si el búfer de salida que asigna el controlador no es lo suficientemente grande como para devolver todos los nombres secundarios enumerados, el controlador ACPI no devuelve ningún nombre secundario y establece el miembro Status del IO_STATUS_BLOCK para que la solicitud STATUS_BUFFER_OVERFLOW. En este caso, si el tamaño, en bytes, del búfer de salida es al menos sizeof(ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE), el controlador ACPI también establece NumberOfChildren en el tamaño, en bytes, necesario para recuperar las rutas de acceso y los nombres solicitados.