Semântica Operacional MB

Transações assíncronas

O modelo de driver MB pressupõe semântica operacional sem bloqueio entre o serviço MB e os drivers de miniporto, usando o mecanismo de notificação assíncrona fornecido no NDIS 6.x. Esse mecanismo permite que o Serviço MB continue a enviar solicitações OID para o driver de miniporto para processamento sem aguardar a conclusão da operação atual.

Uma transação assíncrona é um processo de três passos que começa com a solicitação inicial, seguido por uma resposta de status da solicitação e, em seguida, é concluído por uma indicação final da transação. A resposta de status da solicitação é provisória, pois só reconhece o recebimento da solicitação pelo driver de miniporto. A indicação assíncrona de acompanhamento é transacional, pois sinaliza a conclusão da transação. O driver miniport retorna o código de status, bem como os dados resultantes na indicação transacional.

Solicitações Assíncronas de Configuração e Consulta

Muitas das solicitações OID definidas e de consulta usadas pelo Serviço MB são processadas de forma assíncrona. Para obter mais informações sobre definir e consulta de requisições OID, consulte NDIS_OID_REQUEST. A tabela "OIDs específicas do WWAN" no tópico modelo de dados MB identifica quais OIDs são processados de forma assíncrona.

O diagrama a seguir representa a sequência de interação para uma transação de consulta assíncrona entre o Serviço MB e o driver de miniporto. Os rótulos em negrito representam identificadores OID ou controle de fluxo transacional e os rótulos em texto regular representam os sinalizadores importantes dentro da estrutura OID.

O handshake de três vias é o mesmo para solicitações de consulta e solicitações de configuração.

Com exceção de OID_WWAN_DRIVER_CAPS, todas as outras solicitações de OID específicas para MB seguem o mecanismo de transação assíncrona para troca de informações entre drivers de miniporto e o Serviço MB, com as seguintes notas adicionais:

• Os drivers de miniport devem imediatamente rejeitar um pedido OID em qualquer condição de erro, como um pedido OID inválido.

• Os drivers de miniport devem retornar quaisquer condições de erro específicas do WWAN com o código de erro correto (por exemplo, WWAN_STATUS_XXX) especificado no membro uStatus da estrutura de notificação do evento. Os drivers de miniporto também devem preencher de forma apropriada os membros que seguem o membro uStatus, conforme necessário. Por exemplo, os drivers de miniporto devem preencher o membro ContextState.uNwError da estrutura NDIS_WWAN_CONTEXT_STATE , se disponível. No entanto, no caso de uma falha ao processar OIDs relacionadas a PINs, os drivers de miniport podem não ter necessariamente as informações de estado do PIN atuais a serem especificadas no membro PinInfo.PinState do NDIS_WWAN_PIN_INFO.

• Os drivers de miniport devem retornar NDIS_STATUS_INDICATION_REQUIRED como uma resposta provisória para todas as solicitações OID assíncronas.

• Os drivers de miniporto devem ser capazes de distinguir as alterações de estado do dispositivo causadas por uma solicitação de OID de outras causas. Os drivers de miniport devem enviar notificações transacionais para alterações de estado resultantes de OID requests, e devem enviar notificações de eventos não solicitadas para alterações de estado por outras causas.

• Os drivers de miniport são responsáveis pelo gerenciamento da memória no modo kernel, embora o Serviço MB inicialmente aloque a memória para solicitações. Depois que o MB Service receber uma resposta de um driver de miniporto, o serviço poderá liberar a memória do modo de usuário que ele alocou para a solicitação de OID.

O diagrama a seguir representa a sequência de interação para uma transação set assíncrona entre o Serviço MB e o miniport driver. Os rótulos em negrito representam identificadores OID ou controle de fluxo transacional e os rótulos em texto regular representam os sinalizadores importantes dentro da estrutura OID.

Resposta assíncrona

A Especificação do NDIS 6.0 (lançada com o Windows Vista) introduziu um novo código de status, NDIS_STATUS_INDICATION_REQUIRED, para que os drivers de miniporto transmitam a natureza assíncrona de uma transação para o Serviço MB na resposta provisória de um driver de miniporto a uma solicitação de OID.

Conforme mencionado na Visão geral da interface MB, o Serviço MB não tem acesso direto à memória do modo kernel alocada por um driver de miniporto MB. O resultado da execução armazenado na memória do modo kernel é considerado copiado e disponibilizado para o Serviço MB por algum intermediário, como WMI ou um driver de filtro NDIS. Portanto, os drivers de miniport podem liberar a memória alocada no modo kernel após a chamada da função NdisMIndicateStatusEx retornar na indicação transacional.

Os procedimentos de handshake que os drivers de miniporto e o Serviço MB devem seguir são descritos no procedimento a seguir.

Procedimento de driver de miniporto MB

Ao receber uma solicitação OID, os drivers de miniport devem executar as seguintes etapas:

1. Aloque memória no modo kernel para copiar o conteúdo da estrutura de dados NDIS_OID_REQUEST associada à solicitação OID.

2. Entre os parâmetros da requisição, verifique se os membros RequestId e RequestHandle da estrutura de requisição OID também são copiados. Esses membros serão usados posteriormente na indicação transacional.

3. Retorne uma resposta de status de NDIS_STATUS_INDICATION_REQUIRED provisória para informar ao Serviço MB que o driver de miniporto concluirá a solicitação de forma assíncrona.

4. Após a conclusão da operação, armazene o resultado na memória local ou alocada pelo driver, conforme apropriado.

5. Chame a função NdisMIndicateStatusEx para notificar o Serviço MB de que a operação pendente foi concluída. Os drivers de miniporto devem preencher os membros da estrutura NDIS_STATUS_INDICATION da seguinte maneira:

   1. Defina o membro statusCode como o tipo de notificação de status. Por exemplo, NDIS_STATUS_WWAN_XXX.
   2. Defina o membro DestinationHandle como o membro RequestHandle que foi recebido na estrutura de dados NDIS_OID_REQUEST quando o driver de miniporto recebeu a solicitação OID correspondente.
   3. Defina o membro RequestId para corresponder ao membro RequestId da estrutura de status NDIS_OID_REQUEST quando o driver de miniporto recebeu a solicitação OID correspondente.
   4. Defina os membros StatusBuffer e StatusBufferSize para apontar para a memória alocada pelo driver do miniporto e o tamanho do buffer de memória, respectivamente. Esse buffer de memória contém o resultado da operação concluída.
   5. Se a operação for concluída com êxito, defina o membro uStatus como WWAN_STATUS_SUCCESS. Caso contrário, defina o membro uStatus como o valor de WWAN_STATUS_XXX apropriado para indicar o tipo de falha.

6. Quando a chamada de função retorna, o driver de miniporto deve liberar a memória que ele alocou para a solicitação OID.

Procedimento de serviço MB

O Serviço MB processa transações assíncronas usando o seguinte procedimento:

1. Aloque memória de buffer para a solicitação com base na estrutura de dados OID. Preencha os membros da estrutura de dados com os valores apropriados.

2. Chame a função NdisOidRequest com o membro InformationBuffer apontando para a estrutura de dados OID para a solicitação OID e aguarde a resposta do driver de miniporto.

3. Após o recebimento de uma resposta provisória de NDIS_STATUS_INDICATION_REQUIRED do driver de miniporta, o Serviço MB salva a RequestId, libera a memória alocada e marca a transação como aberta. A partir deste ponto, o Serviço MB está livre para processar solicitações e notificações OID subsequentes.

4. Após o recebimento de uma notificação com NDIS_STATUS_WWAN_XXX como o valor do StatusCode , verifique se a RequestId corresponde à de qualquer transação marcada como aberta. Se houver uma correspondência, o serviço encerrará a transação. Se nenhuma correspondência for encontrada, trate a notificação como uma notificação de evento não solicitada.

5. Processe os dados retornados no membro StatusBuffer e faça alterações de estado no Serviço MB conforme apropriado.

Indicações

Existem dois tipos de indicações específicas do WWAN que os miniport drivers podem gerar:

• Notificações de evento resultantes de uma alteração de estado de objeto no dispositivo MB.

• Notificações transacionais que sinalizam a conclusão de uma operação assíncrona.

Em ambos os casos, os drivers de miniport devem chamar a função NdisMIndicateStatusEx.

Notificação de eventos

A notificação de evento não é solicitada no sentido de que o driver de miniporto envia proativamente a indicação para o Serviço MB como um evento de alteração de estado. A alteração de estado é causada por uma ação de alguma entidade diferente do Serviço MB. O Serviço MB pressupõe que os controladores de miniport sejam capazes de detectar a causa da mudança.

Para qualquer notificação de evento específica do WWAN, os drivers de miniporto devem definir o membro RequestId da estrutura NDIS_STATUS_INDICATION como zero. O membro StatusCode especifica qual objeto no dispositivo MB foi alterado. O driver de miniporto pode definir esse objeto para qualquer um dos seguintes 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

O Serviço MB também pode processar outras notificações de evento do NDIS. Essas notificações de evento não MB não estão necessariamente sujeitas ao requisito de que seus valores RequestId sejam definidos como zero.

Notificações transacionais

Os drivers de miniport usam notificações transacionais para informar ao Serviço MB que uma transação assíncrona foi concluída e o Serviço MB usa notificações transacionais para fechar transações abertas e atualizar seu computador de estado.

O Serviço MB espera notificações transacionais para que possa fechar transações abertas. É a troca final do handshake de três vias entre o serviço MB e o driver de miniporto em uma transação assíncrona. O valor do membro RequestId do NDIS_STATUS_INDICATION em qualquer notificação transacional deve ser diferente de zero, que é copiado da solicitação correspondente na mesma transação.

Você deve definir o membro RequestId da estrutura NDIS_STATUS_INDICATION corretamente para que o mecanismo assíncrono funcione corretamente. O Serviço MB garante que o valor RequestId seja exclusivo e diferente de zero entre todas as solicitações pendentes. Os drivers de miniport devem retornar o mesmo valor RequestId na indicação correspondente para que o Serviço MB correlacione a indicação com uma transação aberta.

Estrutura de indicação de status

Tanto a resposta assíncrona para uma determinada solicitação OID quanto as estruturas de notificação de eventos não solicitadas compartilham os seguintes membros da estrutura que são apontados pelo membro StatusBuffer do parâmetro StatusIndication para 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;

Um valor zero no membro RequestId da estrutura de NDIS_STATUS_INDICATION significa que é uma notificação de evento não solicitada e pode ocorrer a qualquer momento.

Se o membro uStatus na indicação retornada de qualquer solicitação de OID de conjunto ou de consulta não for igual a WWAN_STATUS_SUCCESS, os membros da estrutura NDIS_WWAN_XXX associada não precisam ser válidos.

No caso de notificações de eventos não solicitados com base em eventos de rede, os drivers de miniporto devem preencher o membro uNwError conforme apropriado, quando aplicável.

A tabela a seguir mostra os valores de falha dos códigos de causa de registro, anexação de pacotes e desanexação de pacotes, definidos na Especificação 3GPP TS 24.008 para redes baseadas em GSM:

Por exemplo, se a rede iniciar um evento de desativação de contexto porque o roaming não é permitido na área de localização, os drivers de miniport devem definir o membro uNwError como 13 de acordo com os códigos de causa definidos no 3GPP TS 24.008 para redes baseadas em GSM.

Lógica semelhante também deve ser aplicada a redes baseadas em CDMA. No entanto, não há padrão para códigos de erro de rede baseados em CDMA. Os dispositivos baseados em CDMA devem usar a rede -specific ou códigos de erro específicos do dispositivo.

No caso da resposta assíncrona de um driver de miniporto às solicitações de OID, o membro RequestId da estrutura NDIS_STATUS_INDICATION é um número diferente de zero que foi passado para o driver de miniporto como parte de um pedido de set ou consulta. O driver de miniport deve preencher o membro uStatus conforme apropriado. Por exemplo, WWAN_STATUS_SUCCESS ou qualquer um dos valores de erro apropriados listados na seção a seguir. Além disso, o driver de miniporto deve preencher o membro uNwError quando apropriado e disponível.

Status da notificação de evento

A tabela a seguir lista os códigos de WWAN_STATUS que os drivers de miniport de MB podem especificar no membro uStatus das estruturas de notificação de eventos NDIS_WWAN_XXX.

A tabela a seguir mostra valores de status específicos de SMS.

Nota Esses códigos de status específicos do WWAN são usados apenas para transações assíncronas no membro uStatus das estruturas de NDIS_WWAN_XXX.

Os drivers de miniport usam notificações de evento para informar o Serviço MB sobre uma alteração de estado de objeto em seu dispositivo MB sem antes ter recebido uma solicitação de OID. O Serviço MB usa notificações de evento apenas para atualizar seu computador de estado.

Lembre-se de que, embora o NDIS serialize todas as solicitações enviadas aos drivers de miniporto, os drivers de miniporto podem não retornar as respostas na mesma ordem. Isso ocorre porque as solicitações enfileiradas no miniport driver podem ser processadas em paralelo. Portanto, o Serviço MB garante que, se duas solicitações dependerem umas das outras, ela não enviará a segunda solicitação até que o driver de miniporte conclua a primeira solicitação.

Notificação de alteração de estado

Em geral, os drivers miniport devem sempre notificar o Serviço MB sobre o estado atualizado do seu dispositivo MB, seja por meio de notificações transacionais, seja através de notificações de eventos não solicitadas. Os cenários a seguir são algumas exceções em que os miniport drivers não devem responder com informações de estado atualizadas. O Serviço MB pode determinar o estado atualizado a partir do status de conclusão de outras operações.

1. Os drivers de miniporto não precisam enviar uma indicação de evento NDIS_STATUS_WWAN_PIN_LIST quando ocorrerem alterações no estado do PIN, porque foi o próprio Serviço MB que solicitou habilitar ou desabilitar o PIN.

2. Os drivers de miniporto não precisam retornar a lista atualizada dos contextos provisionados em respostas transacionais para OID_WWAN_PROVISIONED_CONTEXT definir operações.

3. Os drivers de miniporto não precisam responder com a lista dos provedores preferenciais atualizada em respostas transacionais para as operações de set OID_WWAN_PREFERRED_PROVIDERS. O Serviço MB pode determinar essas informações com base na lista inicial e no status de êxito da operação definida .

4. Os drivers de miniporto não precisam responder com o valor atual de WWAN_SMS_CONFIGURATION para as operações definir de OID_WWAN_SMS_CONFIGURATION.