Semántica operativa de MB

Transacciones asincrónicas

El modelo de controlador de MB asume una semántica operativa sin bloqueo entre el servicio de MB y los controladores de miniport mediante el mecanismo de notificación asincrónica proporcionado en NDIS 6.x. Este mecanismo permite que el servicio MB continúe enviando solicitudes OID al controlador de miniportar para su procesamiento sin esperar a que se complete la operación actual.

Una transacción asincrónica es un proceso de tres fases que comienza con la solicitud inicial, seguida de una respuesta de estado y finaliza con una indicación transaccional final. La respuesta de estado de la solicitud es provisional en que solo reconoce que el controlador de miniporte ha recibido la solicitud. La indicación asincrónica de seguimiento es transaccional en que indica la finalización de la transacción. El controlador de miniporte devuelve el código de estado, así como los datos resultantes en la indicación transaccional.

Conjunto asincrónico y solicitudes de consulta

Muchas de las solicitudes OID de conjunto y consulta que usa el servicio MB se procesan de forma asincrónica. Para obtener más información sobre las solicitudes OID establecidas y de consulta , consulte NDIS_OID_REQUEST. La tabla "WWAN-specific OIDs" del tema MB Data Model identifica qué OID se procesan de forma asincrónica.

El diagrama siguiente representa la secuencia de interacción de una transacción de consulta asincrónica entre el servicio MB y el controlador de miniport. Las etiquetas en negrita representan identificadores OID o control de flujo transaccional, y las etiquetas del texto normal representan las marcas importantes dentro de la estructura OID.

El handshake de tres vías es el mismo para las solicitudes de consulta y de configuración.

Excepto por OID_WWAN_DRIVER_CAPS, todas las demás solicitudes OID específicas de MB siguen el mecanismo de transacción asincrónico para el intercambio de información entre los controladores de miniport y el servicio MB, con las notas adicionales siguientes:

• Los controladores de miniport deben fallar inmediatamente una solicitud OID en cualquier condición de error, como una solicitud de OID no válida.

• Los controladores de miniport deben devolver cualquier condición de error específica de WWAN con el código de error correcto (por ejemplo, WWAN_STATUS_XXX) especificado en el miembro uStatus de la estructura de notificación de eventos. Los controladores de miniport también deben rellenar adecuadamente los miembros que siguen al miembro uStatus, según sea necesario. Por ejemplo, los controladores de miniport deben rellenar el miembro ContextState.uNwError de la estructura NDIS_WWAN_CONTEXT_STATE, si está disponible. Sin embargo, en el caso de un error al procesar identificadores de objetos (OID) relacionados con los PINs, es posible que los controladores de miniporte no tengan necesariamente la información del estado actual del PIN para especificar en el miembro PinInfo.PinState de NDIS_WWAN_PIN_INFO.

• Los controladores de miniport deben devolver NDIS_STATUS_INDICATION_REQUIRED como respuesta provisional para todas las solicitudes de OID asincrónicas.

• Los controladores de miniportar deben poder distinguir los cambios de estado del dispositivo causados por una solicitud OID de otras causas. Los controladores de miniportadores deben enviar notificaciones transaccionales para los cambios de estado resultantes de las solicitudes OID; deben enviar notificaciones de eventos no solicitadas para los cambios de estado que se deriven de otras causas.

• Los controladores de miniport son responsables de administrar la memoria en modo kernel, aunque el servicio MB asigna inicialmente la memoria para las solicitudes. Después de que el servicio MB reciba una respuesta de un controlador de miniport, el servicio puede liberar la memoria en modo de usuario que asignó para la solicitud OID.

El diagrama siguiente representa la secuencia de interacción de una transacción de conjunto asincrónica entre el servicio MB y el controlador de miniport. Las etiquetas en negrita representan identificadores OID o control de flujo transaccional, y las etiquetas del texto normal representan las marcas importantes dentro de la estructura OID.

Respuesta asincrónica

La especificación NDIS 6.0 (publicada con Windows Vista) introdujo un nuevo código de estado, NDIS_STATUS_INDICATION_REQUIRED, para que los controladores de miniporte transmitan la naturaleza asincrónica de una transacción al servicio MB en una respuesta provisional del controlador de miniport a una solicitud de OID.

Como se menciona en Resumen de la interfaz MB, el servicio MB no tiene acceso directo a la memoria del modo kernel asignada por un controlador miniport MB. Se supone que el resultado de la ejecución almacenado en la memoria en modo kernel se copia y se pone a disposición del servicio MB por parte de algún intermediario, como WMI o un controlador de filtro NDIS. Por lo tanto, los controladores de miniport pueden liberar la memoria en modo kernel asignada después de que la llamada de función NdisMIndicateStatusEx devuelva en la indicación transaccional.

Los procedimientos de enlace que deben seguir los controladores miniport y el servicio MB se describen en el siguiente procedimiento.

Procedimiento del controlador de miniporte MB

Tras recibir una solicitud de OID, los controladores de miniport deben realizar los pasos siguientes:

1. Asigne memoria en modo kernel para copiar el contenido de la estructura de datos de NDIS_OID_REQUEST asociada a la solicitud OID.

2. Entre los parámetros de la solicitud, asegúrese de que los miembros RequestId y RequestHandle de la estructura de solicitud OID también se copien. Estos miembros se usarán más adelante en la indicación transaccional.

3. Devuelve una respuesta de estado de NDIS_STATUS_INDICATION_REQUIRED provisional para informar al servicio MB de que el controlador de miniporte completará la solicitud de forma asincrónica.

4. Tras la finalización de la operación, almacene el resultado en la memoria local o asignada por el controlador, según corresponda.

5. Llame a la función NdisMIndicateStatusEx para notificar al servicio MB que se ha completado la operación pendiente. Los controladores miniport deben rellenar los miembros de la estructura NDIS_STATUS_INDICATION de la siguiente manera:

   1. Establezca el campo StatusCode para el tipo de notificación de estado. Por ejemplo, NDIS_STATUS_WWAN_XXX.
   2. Establezca el miembro DestinationHandle en el miembro RequestHandle que se recibió en la estructura de datos NDIS_OID_REQUEST cuando el controlador de miniporte recibió la solicitud OID correspondiente.
   3. Establezca el miembro RequestId para que coincida con el miembro RequestId de la estructura de estado de NDIS_OID_REQUEST cuando el controlador de miniporte recibió la solicitud OID correspondiente.
   4. Establezca los miembros StatusBuffer y StatusBufferSize para que estos apunten respectivamente a la memoria asignada por el controlador de miniporte y al tamaño del búfer de memoria. Este búfer de memoria contiene el resultado de la operación completada.
   5. Si la operación se completa correctamente, establezca el miembro uStatus en WWAN_STATUS_SUCCESS. De lo contrario, establezca el miembro uStatus en el valor de WWAN_STATUS_XXX adecuado para indicar el tipo de error.

6. Cuando la llamada a la función regresa, el controlador miniport debe liberar la memoria que asignó para la solicitud OID.

Procedimiento del servicio MB

El servicio MB procesa transacciones asincrónicas mediante el procedimiento siguiente:

1. Asigne memoria de búfer para la solicitud en función de la estructura de datos OID. Rellene los miembros de la estructura de datos con los valores adecuados.

2. Llame a la función NdisOidRequest con el miembro InformationBuffer apuntando a la estructura de datos OID para la solicitud OID y espere a que el controlador de miniport responda.

3. Tras recibir un NDIS_STATUS_INDICATION_REQUIRED respuesta provisional del controlador de miniport, el servicio MB guarda requestId, libera la memoria asignada y marca la transacción como abierta. En este momento, el servicio MB es gratuito para procesar las posteriores solicitudes y notificaciones de OID.

4. Después de recibir una notificación con NDIS_STATUS_WWAN_XXX como valor statusCode , compruebe si requestId coincide con el de cualquier transacción marcada como abierta. Si hay una coincidencia, el servicio cierra la transacción. Si no se encuentra ninguna coincidencia, trate la notificación como una notificación de eventos no solicitada.

5. Procese los datos devueltos en el miembro StatusBuffer y realice cambios de estado en el servicio MB según corresponda.

Indicaciones

Hay dos tipos de indicaciones específicas de WWAN que los controladores de miniporte pueden generar:

• Notificaciones de eventos que se derivan de un cambio de estado de objeto en el dispositivo MB.

• Notificaciones transaccionales que indican la finalización de una operación asincrónica.

En ambos casos, los controladores de miniport deben llamar a la función NdisMIndicateStatusEx.

Notificación de evento

La notificación de eventos no está solicitada en el sentido de que el controlador de miniporte envía proactivamente la indicación al servicio MB como evento de cambio de estado. El cambio de estado se debe a una acción de alguna entidad distinta del servicio MB. El servicio MB supone que los controladores de miniporte pueden detectar la causa del cambio.

Para cualquier notificación de eventos específica de WWAN, los controladores de miniport deben establecer el miembro RequestId de la estructura de NDIS_STATUS_INDICATION en cero. El miembro StatusCode especifica qué objeto del dispositivo MB ha cambiado. El controlador de miniport puede establecer este objeto en cualquiera de los siguientes valores:

NDIS_STATUS_WWAN_DEVICE_CAPS

NDIS_STATUS_WWAN_READY_INFO

NDIS_STATUS_WWAN_RADIO_STATE

NDIS_STATUS_WWAN_PIN_INFO

NDIS_STATUS_WWAN_PIN_LIST

NDIS_STATUS_WWAN_HOME_PROVIDER

NDIS_STATUS_WWAN_PREFERRED_PROVIDERS

NDIS_STATUS_WWAN_VISIBLE_PROVIDERS

NDIS_STATUS_WWAN_REGISTER_STATE

NDIS_STATUS_WWAN_PACKET_SERVICE

NDIS_STATUS_WWAN_SIGNAL_STATE

NDIS_STATUS_WWAN_CONTEXT_STATE

NDIS_STATUS_WWAN_PROVISIONED_CONTEXTS

NDIS_STATUS_WWAN_SERVICE_ACTIVATION

NDIS_STATUS_WWAN_SMS_CONFIGURATION

NDIS_STATUS_WWAN_SMS_RECEIVE

NDIS_STATUS_WWAN_SMS_SEND

NDIS_STATUS_WWAN_SMS_DELETE

NDIS_STATUS_WWAN_SMS_STATUS

NDIS_STATUS_WWAN_VENDOR_SPECIFIC

El servicio MB también puede procesar otras notificaciones de eventos de NDIS. Estas notificaciones de eventos que no son MB no están necesariamente sujetas al requisito de que sus valores RequestId se establezcan en cero.

Notificaciones transaccionales

Los controladores de miniportar usan notificaciones transaccionales para informar al servicio MB de que se ha completado una transacción asincrónica y el servicio MB usa notificaciones transaccionales para cerrar las transacciones abiertas y actualizar su máquina de estado.

El servicio MB espera notificaciones transaccionales para que pueda cerrar las transacciones abiertas. Es el intercambio final del protocolo de enlace triple entre el servicio MB y el controlador de miniport en una transacción asincrónica. El valor del miembro RequestId del NDIS_STATUS_INDICATION en cualquier notificación transaccional debe ser distinto de cero, que se copia de la solicitud correspondiente en la misma transacción.

Debe establecer el miembro RequestId de la estructura de NDIS_STATUS_INDICATION correctamente para que el mecanismo asincrónico funcione correctamente. El servicio MB garantiza que el valor requestId sea único y distinto de cero entre todas las solicitudes pendientes. Los controladores de miniport deben devolver el mismo valor RequestId en la indicación correspondiente para que el servicio MB ponga en correlación la indicación con una transacción abierta.

Estructura de indicación de estado

Tanto la respuesta asincrónica para una solicitud de OID determinada como las estructuras de notificación de eventos no solicitadas comparten los siguientes miembros de estructura a los que apunta el miembro StatusBuffer del parámetro StatusIndication a NdisMIndicateStatusEx:

typedef struct _NDIS_WWAN_XXX {
  NDIS_OBJECT_HEADER Header;
  WWAN_STATUS uStatus;
  ULONG uNwError;//Optional. Only used for network operations.
  WWAN_XXX XxxStruct;
} NDIS_WWAN_XXX, *PNDIS_WWAN_XXX;

Un valor de cero en el miembro RequestId de la estructura NDIS_STATUS_INDICATION significa que es una notificación de eventos no solicitada y puede producirse en cualquier momento.

Si el miembro uStatus de la indicación devuelta de cualquier solicitud OID de establecer o consulta no es igual a WWAN_STATUS_SUCCESS, los miembros de la estructura NDIS_WWAN_XXX asociada no necesitan ser válidos.

En el caso de las notificaciones de eventos no solicitadas basadas en eventos de red, los controladores de miniport deben rellenar el miembro uNwError según sea necesario.

En la tabla siguiente se muestran los valores de código de causa de fallo para registro, conexión de paquetes (attach) y desasociación de paquetes (detach) que se definen en la especificación TS 24.008 de 3GPP para redes basadas en GSM:

Por ejemplo, si la red inicia un evento de contexto de desactivación porque no se permite la itinerancia en el área de ubicación, los controladores de miniporte deben establecer el miembro uNwError en 13 según los códigos de causa 3GPP TS 24.008 para las redes basadas en GSM.

También se debe aplicar una lógica similar a las redes basadas en CDMA. Sin embargo, no hay ningún estándar para los códigos de error de red basados en CDMA. Los dispositivos basados en CDMA deben usar el código de red -specific o los códigos de error específicos del dispositivo.

En el caso de una respuesta asincrónica del controlador miniport a las solicitudes OID, el miembro RequestId de la estructura de NDIS_STATUS_INDICATION es un número distinto de cero que se pasó al controlador miniport como parte de una solicitud de conjunto o consulta. El controlador de miniport debe rellenar el miembro uStatus según corresponda. Por ejemplo, WWAN_STATUS_SUCCESS o cualquiera de los valores de error adecuados enumerados en la sección siguiente. Además de esto, el controlador de miniport debe rellenar el miembro uNwError cuando corresponda y esté disponible.

Estado de notificación de evento

En la tabla siguiente se enumeran los códigos de WWAN_STATUS que los controladores de miniporte MB pueden especificar en el miembro uStatus de las estructuras de notificación de eventos de NDIS_WWAN_XXX.

En la tabla siguiente se muestran los valores de estado específicos de SMS.

Nota Estos códigos de estado específicos de WWAN solo se usan para transacciones asincrónicas en el miembro uStatus de las estructuras de NDIS_WWAN_XXX.

Los controladores de miniport usan notificaciones de eventos para informar al servicio MB sobre un cambio de estado de objeto en su dispositivo MB sin primero haber recibido una solicitud de OID. El servicio MB usa notificaciones de eventos para actualizar solo su máquina de estado.

Tenga en cuenta que, aunque NDIS serializa todas las solicitudes que se envían a los controladores de miniport, es posible que los controladores de miniporte no devuelvan las respuestas en el mismo orden. Esto se debe a que las solicitudes en cola del controlador de miniport pueden procesarse en paralelo. Por lo tanto, el servicio MB garantiza que si dos solicitudes dependen entre sí, no enviará la segunda solicitud hasta que el controlador de miniporte complete la primera solicitud.

Notificación de cambio de estado

En general, los controladores de miniport siempre deben notificar al servicio MB el estado actualizado de su dispositivo MB a través de notificaciones transaccionales o notificaciones de eventos no solicitados. Los escenarios siguientes son algunas excepciones en las que no se supone que los controladores de miniporte respondan con información de estado actualizada. El servicio MB puede determinar el estado actualizado a partir del estado de finalización de otras operaciones:

1. Los controladores miniport no necesitan enviar una indicación de evento NDIS_STATUS_WWAN_PIN_LIST cuando se produce un cambio de estado de PIN debido a que el Servicio MB solicitó habilitar o deshabilitar el PIN.

2. Los controladores de miniport no necesitan devolver la lista actualizada de los contextos aprovisionados en las respuestas transaccionales a las operaciones de establecer OID_WWAN_PROVISIONED_CONTEXT.

3. Los controladores miniport no necesitan responder con la lista actualizada de los proveedores preferidos en las respuestas transaccionales a las operaciones set de OID_WWAN_PREFERRED_PROVIDERS. El servicio MB puede determinar esta información en función de la lista inicial y el estado de éxito de la operación set.

4. Los controladores de miniport no necesitan responder con el valor actual de WWAN_SMS_CONFIGURATION para las operaciones de OID_WWAN_SMS_CONFIGURATION definidas.