Solicitudes de E/S de SPB
La macro de CTL_CODE proporcionada por el sistema, que se describe en Definición de códigos de control de E/S, se usa para definir códigos de control IOCTL_SPB_* en Spb.h.
IOCTL_SPB_EXECUTE_SEQUENCE código de control
El IOCTL_SPB_EXECUTE_SEQUENCE código de control de E/S permite que un cliente (controlador periférico) del controlador del controlador SPB realice una secuencia de transferencias (lecturas y escrituras) como una única operación atómica con una solicitud de E/S. El dispositivo designado en el bus es el destino de todas las transferencias de la secuencia.
Al especificar una secuencia de transferencias de longitud fija como una única operación atómica, la solicitud de control de E/S de IOCTL_SPB_EXECUTE_SEQUENCE permite al controlador del controlador optimizar las transferencias de E/S y mejorar el rendimiento.
El cliente envía esta solicitud de control de E/S al objeto de archivo del dispositivo de destino.
Un controlador del controlador SPB registra una función de devolución de llamada EvtSpbControllerIoSequence para realizar las transferencias de bus para una secuencia de transferencia de E/S. La extensión del marco spB (SpbCx) llama a esta función para pasar una solicitud de IOCTL_SPB_EXECUTE_SEQUENCE al controlador del controlador SPB para su procesamiento.
IOCTL_SPB_EXECUTE_SEQUENCE búfer de entrada
El búfer de entrada es una estructura SPB_TRANSFER_LIST, que contiene una lista de punteros a los búferes de datos del cliente. Esta lista contiene un búfer de datos para cada transferencia (lectura o escritura) en la secuencia de transferencia de E/S.
IOCTL_SPB_EXECUTE_SEQUENCE longitud del búfer de entrada
Tamaño de una estructura de SPB_TRANSFER_LIST.
bloque de estado de IOCTL_SPB_EXECUTE_SEQUENCE
Si la operación se realiza correctamente, el controlador del controlador establece el miembro Status en STATUS_SUCCESS y establece el miembro Information en el número total de bytes transferidos durante la secuencia.
Esta operación puede producir un error por diversos motivos, lo que puede incluir recursos bajos, entradas de cliente no válidas y errores de funcionamiento del dispositivo.
Si el controlador del controlador comienza a procesar la solicitud de E/S, pero se produce un error durante una de las transferencias de la secuencia (por ejemplo, el dispositivo de destino señala una NACK para rechazar la transferencia), el controlador del controlador anula las transferencias restantes en la secuencia. A continuación, el controlador establece el estado de finalización en STATUS_SUCCESS, establece el miembro Information en el número de bytes que se transfirieron correctamente antes de que se produjera el error y completa la solicitud.
IOCTL_SPB_FULL_DUPLEX código de control
Un cliente (controlador periférico) usa el código de control IOCTL_SPB_FULL_DUPLEX para solicitar una operación de E/S dúplex completa. Las operaciones de E/S dúplex completas son compatibles con controladores para buses como SPI que pueden leer y escribir datos simultáneamente. La macro de CTL_CODE proporcionada por el sistema, que se describe en Definición de códigos de control de E/S, se usa para definir IOCTL_SPB_FULL_DUPLEX de la siguiente manera.
El controlador en modo de usuario o el controlador en modo kernel de un dispositivo del bus envía esta solicitud de control de E/S al objeto de archivo del dispositivo de destino.
Este IOCTL solo es compatible con los controladores del controlador SPB para autobuses, como SPI, que pueden leer y escribir datos simultáneamente.
Los búferes de escritura y lectura para la transferencia dúplex completa se describen mediante una estructura de SPB_TRANSFER_LIST. Esta estructura debe usar el formato siguiente:
La matriz de estructuras de SPB_TRANSFER_LIST_ENTRY contiene exactamente dos elementos. El primer elemento describe el búfer de escritura (Direction = SpbTransferDirectionToDevice). El segundo elemento describe el búfer de lectura (Direction = SpbTransferDirectionFromDevice).
Los miembros DelayInUs de las dos estructuras SPB_TRANSFER_LIST_ENTRY deben ser cero. Los formatos de búfer para el búfer de escritura y el búfer de lectura pueden ser cualquiera de los siguientes:
- SpbTransferBufferFormatSimple
- SpbTransferBufferFormatList
- SpbTransferBufferFormatSimpleNonPaged
- SpbTransferBufferFormatMdl
Los clientes en modo kernel pueden usar los dos últimos formatos de la lista anterior. No es necesario que los formatos de los búferes de escritura y lectura sean los mismos. Para obtener más información sobre estos formatos de búfer, consulte SPB_TRANSFER_BUFFER_FORMAT.
Una operación correcta podría establecer el miembro Information en un valor menor que la suma de los tamaños del búfer de escritura y el búfer de lectura, que puede producirse si se cancela la solicitud, o si la operación no puede escribir el contenido completo del búfer de escritura en el dispositivo o rellenar completamente el búfer de lectura con datos leídos del dispositivo.
No es necesario que los tamaños de búfer de escritura y lectura sean los mismos. Si el búfer de escritura es mayor que el búfer de lectura, la operación continúa escribiendo datos desde el búfer de escritura después de que el búfer de lectura esté lleno. Si el búfer de lectura es mayor que el búfer de escritura, la operación continúa rellenando el búfer de lectura después de vaciar el búfer de escritura.
Si un controlador del controlador SPB registra una función de devolución de llamada EvtSpbControllerIoOther, la extensión del marco SPB (SpbCx) llama a esta función para pasar una solicitud de IOCTL_SPB_FULL_DUPLEX al controlador del controlador SPB para su procesamiento. SpbCx no realiza ninguna comprobación de parámetros, validación de lista de transferencia u otro procesamiento para una solicitud de IOCTL_SPB_FULL_DUPLEX.
Para obtener más información sobre cómo un controlador de controlador SPB implementa la compatibilidad con este IOCTL, consulte Control de solicitudes de IOCTL_SPB_FULL_DUPLEX.
IOCTL_SPB_FULL_DUPLEX búfer de entrada
Puntero a una estructura de SPB_TRANSFER_LIST que contiene punteros a los búferes de datos de entrada y salida del cliente. Esta estructura contiene una matriz De transferencias de exactamente dos elementos. El primer elemento describe el búfer que contiene los datos que se van a escribir en el dispositivo. El segundo elemento describe el búfer usado para contener los datos leídos del dispositivo. Para obtener más información sobre cómo un controlador de controlador SPB implementa una solicitud de control de E/S (IOCTL) personalizada que usa estructuras de SPB_TRANSFER_LIST para describir los búferes, consulte Uso de la estructura de SPB_TRANSFER_LIST para ICTLs personalizados.
IOCTL_SPB_FULL_DUPLEX longitud del búfer de entrada
Tamaño de una estructura de SPB_TRANSFER_LIST.
bloque de estado de IOCTL_SPB_FULL_DUPLEX
Si la operación se realiza correctamente, el controlador del controlador establece el miembro Status en STATUS_SUCCESS y establece el miembro Information en el número total de bytes transferidos (bytes leídos más bytes escritos) durante la operación dúplex completa.
Esta operación puede producir un error por diversos motivos, lo que puede incluir recursos bajos, entradas de cliente no válidas y errores de funcionamiento del dispositivo.
IOCTL_SPB_LOCK_CONNECTION código de control
Un cliente (controlador periférico) usa el código de control IOCTL_SPB_LOCK_CONNECTION para adquirir el bloqueo de conexión en un dispositivo de destino conectado a SPB que se comparte con otro cliente. Mientras un cliente contiene el bloqueo de conexión, este cliente tiene acceso exclusivo al dispositivo. La macro de CTL_CODE proporcionada por el sistema, que se describe en Definición de códigos de control de E/S, se usa para definir IOCTL_SPB_LOCK_CONNECTION de la siguiente manera.
Las solicitudes IOCTL_SPB_LOCK_CONNECTION y IOCTL_SPB_UNLOCK_CONNECTION adquieren y liberan el bloqueo de conexión en un dispositivo de destino que está conectado a un bus periférico simple. La mayoría de los clientes no usan estas solicitudes de control de E/S. Estas solicitudes solo se usan si dos clientes comparten acceso al mismo dispositivo de destino. Para obtener más información, consulte Bloqueos de conexión de SPB.
Dos clientes pueden abrir conexiones lógicas independientes al mismo dispositivo de destino y usar el bloqueo de conexión cuando cualquiera de los clientes requiere acceso exclusivo al dispositivo. Cuando un cliente contiene el bloqueo, las solicitudes de E/S al dispositivo del segundo cliente se aplazan automáticamente hasta que el primer cliente libera el bloqueo.
Un cliente puede contener simultáneamente un bloqueo de conexión en el dispositivo de destino y un bloqueo de controlador en el controlador SPB. Las solicitudes IOCTL_SPB_LOCK_CONTROLLER y IOCTL_SPB_UNLOCK_CONTROLLER adquieren y liberan el bloqueo del controlador. El cliente debe adquirir el bloqueo de conexión antes de adquirir el bloqueo del controlador y debe liberar el bloqueo del controlador antes de liberar el bloqueo de conexión. Un cliente usa un bloqueo de controlador para realizar un conjunto ordenado de transferencias de bus (operaciones de lectura y escritura) como una única operación de bus atómico. Para obtener más información, consulte Secuencias de transferencia de E/S.
Se finaliza automáticamente un bloqueo de conexión si se envía una solicitud de IRP_MJ_CLEANUP a un dispositivo de destino mientras la conexión está bloqueada en el dispositivo. Una solicitud de limpieza se envía a un dispositivo de destino cuando un cliente cierra su identificador de archivo en el dispositivo.
bloque de estado de IOCTL_SPB_LOCK_CONNECTION
Si la operación se realiza correctamente, el miembro Status se establece en STATUS_SUCCESS.
Si se produce un error en la operación, el miembro Status se establece en un código de estado de error adecuado.
Si el cliente ya contiene el bloqueo de conexión en el dispositivo de destino o el bloqueo del controlador en el controlador SPB, esta operación produce un error con Status = STATUS_INVALID_DEVICE_REQUEST. Esta operación puede producir errores por otros motivos, lo que puede incluir recursos bajos, entrada de cliente no válida y mal funcionamiento del dispositivo.
IOCTL_SPB_LOCK_CONTROLLER código de control
Un cliente (controlador periférico) usa el código de control IOCTL_SPB_LOCK_CONTROLLER para bloquear el controlador SPB. Mientras el controlador está bloqueado, el cliente tiene un uso exclusivo del bus para acceder al dispositivo de destino especificado para el bloqueo. La macro de CTL_CODE proporcionada por el sistema, que se describe en Definición de códigos de control de E/S, se usa para definir IOCTL_SPB_LOCK_CONTROLLER de la siguiente manera.
Para obtener el uso exclusivo del bus para acceder a un dispositivo de destino, un cliente (controlador periférico) envía este IOCTL al objeto de archivo para el destino. Una vez completado este IOCTL, el controlador está bloqueado y todas las transferencias de E/S (lectura o escritura) en el bus acceden al destino designado. Entre transferencias, el controlador mantiene seleccionado el dispositivo de destino, pero detiene el reloj.
El controlador permanece bloqueado hasta que el cliente envía una solicitud de IOCTL_SPB_UNLOCK_CONTROLLER para desbloquear el controlador. Cuando se completa la secuencia de transferencias del cliente hacia o desde el dispositivo de destino, el cliente debe desbloquear el controlador para que el controlador pueda procesar solicitudes de E/S para otros destinos del bus.
Un bloqueo finaliza automáticamente si se envía una solicitud de IRP_MJ_CLEANUP a un dispositivo de destino mientras el controlador está bloqueado en el destino. Una solicitud de limpieza se envía a un destino cuando un cliente cierra su identificador al destino.
Los controladores SPB no son necesarios para admitir solicitudes de IOCTL_SPB_LOCK_CONTROLLER y IOCTL_SPB_UNLOCK_CONTROLLER, y los controladores de dispositivos periféricos no deben suponer que son compatibles.
Si un controlador del controlador SPB registra una función de devolución de llamada EvtSpbControllerLock, la extensión del marco SPB (SpbCx) llama a esta función para pasar una solicitud de IOCTL_SPB_LOCK_CONTROLLER al controlador del controlador SPB para su procesamiento.
bloque de estado de IOCTL_SPB_LOCK_CONTROLLER
Si la operación se realiza correctamente, el miembro Status se establece en STATUS_SUCCESS. Este IOCTL puede devolver un estado de error por varios motivos, incluido el error de configurar el controlador para que funcione en modo de acceso exclusivo. En este modo, el controlador mantiene seleccionado el dispositivo de destino para que sea el destino exclusivo para todas las transferencias de E/S en el bus. El controlador permanece en este modo hasta que se desbloquea.
IOCTL_SPB_UNLOCK_CONNECTION código de control
Un cliente (controlador periférico) usa el código de control de E/S IOCTL_SPB_UNLOCK_CONNECTION para liberar el bloqueo de conexión en un dispositivo de destino conectado a SPB que se comparte con otro cliente. El cliente envió previamente una solicitud de IOCTL_SPB_LOCK_CONNECTION para adquirir acceso exclusivo al dispositivo.
Las solicitudes IOCTL_SPB_LOCK_CONNECTION y IOCTL_SPB_UNLOCK_CONNECTION adquieren y liberan el bloqueo de conexión en un dispositivo de destino que está conectado a un bus periférico simple. La mayoría de los clientes no usan estas solicitudes de control de E/S. Estas solicitudes solo se usan si dos clientes comparten acceso al mismo dispositivo de destino. Para más información, consulte Bloqueos de conexión de SPB.
Una vez que un cliente (controlador periférico) envía una solicitud de IOCTL_SPB_LOCK_CONNECTION a un dispositivo de destino en el bus y la solicitud se completa correctamente, la conexión permanece bloqueada hasta que el cliente envía una solicitud de IOCTL_SPB_UNLOCK_CONNECTION para desbloquear la conexión.
El cliente envía una solicitud de IOCTL_SPB_UNLOCK_CONNECTION para liberar el bloqueo de conexión al dispositivo de destino cuando el cliente ya no requiere acceso exclusivo al dispositivo. La conexión debe desbloquearse para que el otro cliente pueda acceder al dispositivo.
bloque de estado de IOCTL_SPB_UNLOCK_CONNECTION
Si la operación se realiza correctamente, el miembro Status se establece en STATUS_SUCCESS.
Si se produce un error en la operación, el miembro Status se establece en un código de estado de error adecuado. Si el cliente no contiene el bloqueo de conexión en el dispositivo de destino o si el cliente sigue manteniendo el bloqueo de conexión en el controlador SPB, esta operación produce un error con Status = STATUS_INVALID_DEVICE_REQUEST. Esta operación puede producir un error por otros motivos, lo que puede incluir recursos bajos, entradas de cliente no válidas y un error en el dispositivo.
código de control de IOCTL_SPB_UNLOCK_CONTROLLER
Un cliente (controlador periférico) usa el código de control de E/S IOCTL_SPB_UNLOCK_CONTROLLER para desbloquear el controlador SPB. El cliente ha bloqueado previamente el controlador para obtener un uso exclusivo del bus para acceder a un dispositivo de destino en el bus.
Después de que un cliente (controlador periférico) envíe una solicitud de control de E/S IOCTL_SPB_LOCK_CONTROLLER a un dispositivo de destino en el bus, el controlador permanece bloqueado hasta que el cliente envía una solicitud de control de E/S de IOCTL_SPB_UNLOCK_CONTROLLER para desbloquear el controlador. El cliente envía estas solicitudes de control de E/S al objeto de archivo para el dispositivo de destino.
El cliente envía una solicitud de IOCTL_SPB_UNLOCK_CONTROLLER cuando ha completado una secuencia de transferencias en el bus y desea liberar el dispositivo de destino. El controlador debe desbloquearse para que pueda procesar solicitudes de E/S para otros destinos en el bus.
Los controladores SPB no son necesarios para admitir solicitudes de IOCTL_SPB_LOCK_CONTROLLER y IOCTL_SPB_UNLOCK_CONTROLLER, y los controladores de dispositivos periféricos no deben suponer que son compatibles.
La extensión del marco spB (SpbCx) llama a la función de devolución de llamada opcional del controlador SPB EvtSpbControllerUnlock para pasar una solicitud de IOCTL_SPB_LOCK_CONTROLLER al controlador spb para su procesamiento.
bloque de estado de IOCTL_SPB_UNLOCK_CONTROLLER
Si la operación se realiza correctamente, el miembro Status se establece en STATUS_SUCCESS.
Este IOCTL solo puede producir un error si un cliente que no tiene bloqueado el controlador para el acceso exclusivo al destino designado.