DriverEntry - Did you think it'd be easy?

Último post pelo Blogger

fernando@driverentry.com.br (Fernando Roberto da Silva) — Wed, 28 Apr 2010 23:47:00 +0000

Olá cambada! Puts, eu já estava com saudade de postar alguma coisa. Pena este ser mais um daqueles chatos posts Off-Topic. O que posso fazer? É o que temos para o momento.

Hoje pela manhã recebi um mais um e-mail de aviso do Blogger dizendo que o suporte à publicação via FTP estão com os dias contatos. Como este recurso é utilizado por menos de 5% dos seus usuários, resolveram dar fim à ele. Mas essa não foi a principal razão pela qual eu decidi deixar de postar pelo Blogger para usar o WordPress. Eu já vinha ensaiando essa transição há pelo menos dois anos. A faculdade e outras desculpinhas esfarrapadas não me deixavam pôr essa idéia em prática. Alguns leitores já vinham reclamando da falta de um índice geral e da separação dos posts em categorias, coisas que o WordPress faz com uma mão nas costas.

Como um web designer, eu sou um excelente desenvolvedor de drivers, e eu já tinha ouvido falar que o WordPress usava PHP e MySQL, assuntos os quais eu não tenho a menor intimidade. Inicialmente contei com a ajuda do meu irmão que já possuia um blog pelo WordPress, mas assim como eu, ele também tinha faculdade e outras prioridades. Por um tempo eu contratei os serviços de um web designer que colocava em prática as minhas ídéias com relação ao novo layout, mas por fim ele se envolveu com algo maior e fiquei na mão novamente.

A idéia de migrar o blog persistia, mas a preguiça, a falta de tempo e de domínio de HTML e CSS me fizeram ir empurrando esse problema com a barriga. Cheguei até a ler o guia o oficial da famosa série "Preciso aprender isso de qualquer jeito", o livro "WordPress for Dummies". Pra quem está acostumado a ler livros de assuntos um tanto mais cabeludos, as mais de 380 páginas do livro foram como um passeio no parque. O mais surpreendente pra mim foi descobrir que o WordPress é uma ferramenta que não requer prática nem tampouco habilidade, e isso incluia as habilidades de PHP e MySQL que eu não tenho. Uma ferramenta poderosa, flexível e simples. A parte desagradável dessa história é que tudo que o livro falou sobre HTML e CSS é que ele não falava a respeito.

Até aqui excelente. Os 67 posts poderiam ser migrados mas o layout ainda foi o meu carma. Outras tentativas de encontrar alguém disposto a fazer o design pra mim me mostrou que estou no emprego errado. Esse negócio de desenvolver drivers não está com nada. Pra ganhar dinheiro mesmo o negócio é fazer Web Design.

Há uns três meses, quando recebi o primeiro aviso do Blogger sobre o fim do suporte ao FTP foi o momento "Agora ou nunca". Minha faculdade não me servia mais de desculpa e aos poucos fui colocando a mão na massa. Depois de muito trabalho manual de migrar cada post e cada comentário, veio o layout. Graças ao site W3Schools, às aulas particulares de Photohop do meu irmão e à ajuda de alguns amigos, essa semana consegui publicar o novo blog. Ainda faltam muitas coisas. A página "About Me" ainda não tem nada about me. A página de treinamentos, que vai falar sobre os cursos que ofereço ainda fala exatamente isso: "Essa página vai falar sobre os cursos que ofereço". Ainda estou instalando alguns plug-ins que vão ajudar em uma coisa aqui e outra ali. Mas o fato é que há dois dias do prazo final do suporte ao FTP, o novo blog já está no ar.

Esse post foi o último a ser contruído no Blogger com o objetivo principal de avisar àqueles que seguem o RSS original de que o endereço agora mudou. O novo RSS será provido em um novo endereço.

Eu não poderia terminar esse blog sem agraceder às pessoas que tiveram a paciência de me aturar com testes e dúvidas sobre HTML, CSS e sei-lá mais o que. Um muito obrigado aos meus amigos Lesma, Thiago Oliveira, Thiago Brito, meu irmão Kabloc, Willam, Francisco, à minha esposa Magda que migrou todos os comentários e a todos os outros que não me lembro agora (eu perturbei muita gente).

Se você não conhecia o blog antigo, aqui estão as páginas do velho aposentado.
Valeu!

Sexto Encontro de Programadores C/C++

fernando@driverentry.com.br (Fernando Roberto da Silva) — Fri, 26 Feb 2010 21:42:00 +0000

Começo de ano é sempre a mesma correria. Depois que a gente começa a se acostumar com a idéia de que o feriadão de Natal e Ano Novo acabaram, logo vem o carnaval e desanda tudo. Aproveitei este início de ano para tirar merecidas férias, já que finalmente meu curso de Engenharia da Computação terminou. Como um belo start para minha reintegração à sociedade, nada melhor que uma viajem ao nordeste brasileiro. Semanas antes desta viajem fiquei sabendo do novo encontro da comunidade de programadores C/C++. Por causa da viagem eu perderia o evento.

Um mês se passou e semana passada vi que o evento foi adiado para o próximo dia seis de março. Muito boa notícia já que além de poder participar do evento também vou falar um pouquinho. Já participei de outro encontro de programadores e fiquei muito feliz de poder falar para tantas pessoas sobre esse assunto tão misterioso para muitos, que é o desenvolvimento de drivers para Windows.

Sob meu ponto de vista os resultados foram muito bons. A palestra deu uma introdução ao assunto de desenvolvimento de drivers e obviamente os 60 minutos de palestra não foram suficientes para explicar o assunto com detalhes, mas foi interessante mostrar a ponta do iceberg e poder responder a algumas perguntas dos presentes. Eu escrevi um post que comenta sobre o encontro, mas recomendo o post do meu amigo Lesma que ficou muito bom.

Lidando com Memória Virtual em Drivers

Bem, neste novo encontro não vou dar novamente uma introdução ao assunto, mas vou comentar sobre algumas carasterísticas e curiosidades sobre Memória Virtual no desenvolvimento de drivers. Entenda que não vou fazer um resumo do capítulo 9 do Windows Internals, "Memory Management" que fala sobre Page Table Entries e Working Sets, mas sim demonstrar que, diferentes de uma aplicação User-Mode, drivers precisam estar cientes dos conceitos fundamentais de memória virtual e paginação, controlando paginação de objetos e atendendo à requisítos de paginação de memória e espaço de endereçamento.

Os tópicos a serem discutidos na palestra serão os seguintes:

Overview de Memória Virtual e Paginação.
Operações de I/O e manipulação de Buffers.
Prioridade de thread e acesso à memória.
Pools de alocação, Tags e Quotas.
Evitando Fragmentação.
Drivers no caminho da paginação.
Controlando paginação de funções.
Obtendo endereços reais de memória.
Dispositivos de acesso direto à memória (DMA).
Recursos do Driver Verifier.
Hands on: Operações de memórias por drivers no WinDbg.
Dúvidas.

Esta é a página oficial do evento e as inscrições estão abertas. Até lá!

Download dos slides

Escrevendo Filtros

fernando@driverentry.com.br (Fernando Roberto da Silva) — Wed, 20 Jan 2010 20:48:00 +0000

Vamos brincar de algo mais interessante agora. Obviamente ainda vamos dar passos pequenos para não nos perder com tantos detalhes. Hoje falarei sobre filtros de drivers. O IoManager do Windows nos permite adicionar funcionalidade a determinados drivers sem que tenhamos que substituí-lo. Um exemplo clássico seria um driver de criptografia de arquivos. Você não precisa escrever um novo driver de file system para que se tenha tal funcionalidade. Você pode simplesmente escrever um filtro que ficaria entre o driver de file system e o restante do sistema.

Na figura abaixo podemos observar o fluxo de IRPs que vão do IoManager para um certo driver, um filtro é instalado sobre o driver existente e passa a receber as IRPs no lugar do driver original. Com isso o filtro tem a oportunidade de alterar os parâmetros das IRPs recebidas, ou logar a atividade do driver original, ou duplicar solicitações do sistema para esse driver, ou mesmo negar serviço do driver original.

Numa operação de escrita, um filtro poderia criptografar os dados antes de enviá-los ao driver original, e de maneira similar, numa operação de leitura o filtro poderia decriptografar dados antes de entregá-los ao sistema.

Ainda não vai ser desta vez que construiremos um filtro de criptografia de file system. Filtros de criptografia de arquivos em tempo real estão entre os drivers mais complexos a serem escritos. Vamos escolher um driver mais simples, pra não dizer um bem besta, para aplicar os conceitos básicos demonstrados aqui.

Por falar em driver besta, vamos utilizar o driver deste post que já foi visto aqui. Este driver simplesmente armazena uma lista de strings enviadas por uma aplicação em operações de escrita. Tais strings são retornadas à aplicação em operações de leituras.

Escrevendo a DriverEntry

Como vimos neste outro post, uma das das coisas que a função DriverEntry() faz num driver comum é setar as Dispatch Routines que o driver vai atender para certo dispositivo. Para isso deve-se preencher o array de Major Functions que fica na estrutura DRIVER_OBJECT.

    //-f--> Seta as dispatch routines do driver.
    pDriverObj->MajorFunction[IRP_MJ_CREATE] = OnCreate;
    pDriverObj->MajorFunction[IRP_MJ_CLEANUP] = OnCleanup;
    pDriverObj->MajorFunction[IRP_MJ_CLOSE] = OnClose;
    pDriverObj->MajorFunction[IRP_MJ_READ] = OnRead;
    pDriverObj->MajorFunction[IRP_MJ_WRITE] = OnWrite;

No caso do nosso filtro de exemplo, queremos apenas monitorar a atividade do driver ao qual estamos atachados, dessa forma teremos sempre que encaminhar quaisquer IRPs recebidas ao driver de baixo. Uma forma simples e comum de fazer isso é setar todas dispath routines para uma única função. Essa função se encarrega de simplesmente logar a solicitação recebida e passá-la a diante.

Se dermos uma olhada na definicão de IRP_MJ_CREATE e seus amigos, veremos o seguinte trecho do arquivo wdm.h.

//
// Define the major function codes for IRPs.
//
 
 
#define IRP_MJ_CREATE                   0x00
#define IRP_MJ_CREATE_NAMED_PIPE        0x01
#define IRP_MJ_CLOSE                    0x02
#define IRP_MJ_READ                     0x03
#define IRP_MJ_WRITE                    0x04
#define IRP_MJ_QUERY_INFORMATION        0x05
#define IRP_MJ_SET_INFORMATION          0x06
#define IRP_MJ_QUERY_EA                 0x07
#define IRP_MJ_SET_EA                   0x08
#define IRP_MJ_FLUSH_BUFFERS            0x09
#define IRP_MJ_QUERY_VOLUME_INFORMATION 0x0a
#define IRP_MJ_SET_VOLUME_INFORMATION   0x0b
#define IRP_MJ_DIRECTORY_CONTROL        0x0c
#define IRP_MJ_FILE_SYSTEM_CONTROL      0x0d
#define IRP_MJ_DEVICE_CONTROL           0x0e
#define IRP_MJ_INTERNAL_DEVICE_CONTROL  0x0f
#define IRP_MJ_SHUTDOWN                 0x10
#define IRP_MJ_LOCK_CONTROL             0x11
#define IRP_MJ_CLEANUP                  0x12
#define IRP_MJ_CREATE_MAILSLOT          0x13
#define IRP_MJ_QUERY_SECURITY           0x14
#define IRP_MJ_SET_SECURITY             0x15
#define IRP_MJ_POWER                    0x16
#define IRP_MJ_SYSTEM_CONTROL           0x17
#define IRP_MJ_DEVICE_CHANGE            0x18
#define IRP_MJ_QUERY_QUOTA              0x19
#define IRP_MJ_SET_QUOTA                0x1a
#define IRP_MJ_PNP                      0x1b
#define IRP_MJ_PNP_POWER                IRP_MJ_PNP      // Obsolete....
#define IRP_MJ_MAXIMUM_FUNCTION         0x1b

Note que existe uma definição especial, a IRP_MJ_MAXIMUM_FUNCTION, que indica o índice máximo da tabela de dispatch rotines. Utilizaremos um loop simples para fazer com que todas rotinas em nossa tabela aponte para uma única rotina que daremos o nome de OnForwardDispatch.

    //-f--> Seta todas as dispatch routines do driver para
    //      uma que encaminhe a IRP para o driver original.
    for (i = 0; i <= IRP_MJ_MAXIMUM_FUNCTION; i++)
        pDriverObj->MajorFunction[i] = OnForwardDispatch;

Veremos a implementação dessa rotina mais tarde. O próximo passo que daremos aqui é localizar o device ao qual vamos nos atachar. Para fazer isso, usaremos a rotina IoGetDeviceObjectPointer(). Ela basicamente recebe o nome do device e nos retorna uma referência para ele.

NTSTATUS 
  IoGetDeviceObjectPointer(
    IN PUNICODE_STRING  ObjectName,
    IN ACCESS_MASK  DesiredAccess,
    OUT PFILE_OBJECT  *FileObject,
    OUT PDEVICE_OBJECT  *DeviceObject
    );

Observe que são dois os parâmetros de saída dessa rotina. Além do ponteiro para o device object ainda recebemos um ponteiro para um file object. Já ví algumas pessoas fazerem confusão com estes dois parâmetros, então vou dar alguma ênfase nisso.

O ponteiro para o file object representa uma conexão criada entre seu driver e o device que você abriu. Como vimos neste post, um file object é criado para respresentar conexões entre aplicações user mode e seu driver. Aplicações usam esse file object através do handle obtido na chamada à rotina CreateFile(). Aqui temos algo similar, mas apenas o Kernel foi envolvido. Isso significa que se você quizesse, você poderia lançar IRPs para o device solicitando operações como uma aplicação faria, mas não veremos isso hoje, ainda temos um filtro para terminar.

A grande confusão referente a estes dois parâmetros é com relação às referências entre os objetos. Na documentação vemos que o chamador desta rotina deverá liberar a referência que ganhou quando o device não for mais utilizado. Fazemos isso simplesmente usando a rotina ObDereferenceObject().

VOID 
  ObDereferenceObject(
    IN PVOID  Object
    );

"Já sei! Como estamos obtendo uma referência para um device object, então devo passar o ponteiro do device object. Certo?"

Er... Na verdade não. O file object é uma referência indireta ao device object. Conforme a figura abaixo, se imaginarmos que os contadores de referência apenas dizem respeito às nossas referências, quando chamarmos ObDereferenceObject() para o file object, seu contador de referência cairia para zero e uma nova chamada para ObDeferenceObject() seria feita indiretamente para o device object, fazendo com que seu contador de referência também caisse para zero destruindo o objeto.

Depois de obter o ponteiro para o device destino, teremos que criar nosso próprio device, o qual receberá as IRPs no lugar do device original. Para isso ainda usaremos a rotina IoCreateDevice() como faziamos com drivers, mas com algumas diferenças.

A primeira diferença é que seu device normalmente não tem nome. É possível criar filtros com nomes, mas isso pode gerar uma falha de segurança. Isso acontece pois quando um nome é consultado no Object Manager, suas regras de segurança são avaliadas. Quando criamos um filtro com nome, criamos a possibilidade de o mesmo objeto ser obtido por um nome diferente e que pode ter regras menos restritivas de segurança. Mas esse é outro assunto.

Quando criamos um device, precisamos informar o tamanho do device extension.

"O que vem a ser um device extension?"

Device extension é simplesmente um espaço de memória que está associada ao device object. Tal espaço normalmente mantém informações que dizem respeito ao device. O endereço do device ao qual estamos atachados normalmente fica no device extension. Desta forma, podemos definir que nosso device extension deve conter a seguinte estrutura.

//-f--> Nosso device externsion conterá apenas o endereço
//      do device ao qual estamos atachados.
typedef struct _DEVICE_EXTENSION
{
    PDEVICE_OBJECT  pNextDeviceObj;
 
} DEVICE_EXTENSION, *PDEVICE_EXTENSION;

Depois de criar nosso device object, configuramos o método de I/O copiando os bits DO_BUFFERED_IO e DO_DIRECT_IO. Se você não se lembra destes bits, dê uma olhada neste post. O filtro deve propagar a escolha do driver original e o driver tem o compromisso de não mudar método durante seu tempo de vida.

Agora estamos prontos para nos atachar ao device escolhido, e faremos isso utilizando a rotina IoAttachDeviceToDeviceStackSafe() para fazer nosso device entrar na pilha de dispositivos.

NTSTATUS
  IoAttachDeviceToDeviceStackSafe(
    IN PDEVICE_OBJECT  SourceDevice,
    IN PDEVICE_OBJECT  TargetDevice,
    IN OUT PDEVICE_OBJECT  *AttachedToDeviceObject 
    );

Com esta chamada obteremos o ponteiro do device ao qual estaremos atachados, esse device será o próximo device que receberá a IRP depois que você a passar a diante.

"Mas Fernando, nós já não temos o ponteiro do device de destino?"

Muito bem, quando você obtém o ponteiro para um device, você teoricamente não sabe se existem filtros já atachados sobre ele. O ponteiro que você recebe nesta rotina pode não ser o ponteiro para o device de destino. Na figura abaixo podemos entender como essa relação acontece.

"Fernando, existe uma versão unsafe desta rotina?"

Na verdade existe, a IoAttachDeviceToDeviceStack().

PDEVICE_OBJECT 
  IoAttachDeviceToDeviceStack(
    IN PDEVICE_OBJECT  SourceDevice,
    IN PDEVICE_OBJECT  TargetDevice
    );

Ela é considerada unsafe por causa de uma pequena janela de tempo que pode causar um race condition. Repare que a diferença entre estas rotinas é a forma de obter o endereço do próximo device. Na versão original, este endereço é obtido pelo retorno na função. Se colocarmos essa função para rodar em câmera lenta veremos os seguintes passos.

Seu device é atachado à pilha de dispositivos.
O endereço do próximo device é retornado pela função.
Seu driver recebe este endereço no retorno da função e atualiza o device extension.
IRPs começam a chegar e seu driver às encaminham para o próximo device da lista.

Tudo parece lindo e até dá a impressão de que tudo vai funcionar muito bem em qualquer situação, mas desenvolvedor de driver é um bixo treinado para buscar race conditions. Dê mais uma olhada na sequência, mas agora em câmera super lenta. Com essa câmera super lenta agora podemos observar os passos que podem ocorrer entre os passos 2 e 3.

Seu device é atachado à lista de dispositivos.
O endereço do próximo device é retornado pela função.
1. Sua thread é interrompida e uma IRP lançada por uma aplicação que roda em paralelo começa sua viagem por essa pilha de dispositivos.
2. Seu device, que já está atachado, recebe a IRP e tenta encaminhá-la ao device de baixo.
3. Oops! Nosso device extension ainda não foi atualizado com tal endereço.
4. Seu driver se lembra de quando era uma criança e de tudo o que vivera até ali.
5. Ele decide entrar de vez naquela dança e enviar a IRP para um device cujo ponteiro ainda é NULL causando um BSOD.
"Jeremias, eu sou homem. Coisa que você não é e não atiro pelas costas não..."

Enfim, entenda que mesmo que você utilize o retorno da rotina IoAttachDeviceToDeviceStack() diretamente para atualizar seu device extension, ainda assim existe uma janela de tempo em que seu device estará atachado, mas que o valor ainda não foi atualizado no device extension. Isso porque o valor de retorno de uma rotina vem por um registrador. Pegar o valor desse registrador e atualizar uma variável ainda dá chances para o azar.

    //-f--> ----==== NÃO COPIE ISSO ====----
    //      Aqui ainda temos uma janela de tempo entre o device ser
    //      atachado e o valor de pNextDeviceObj ser atualizado.
    pDeviceExt->pNextDeviceObj = IoAttachDeviceToDeviceStack(pMyDeviceObj,
                                                             pTargetDeviceObj);

A rotina IoAttachDeviceToDeviceStackSafe() faz o sistema interromper o fluxo de IRPs nesta pilha até que a variável apontada pelo ponteiro de saída seja atualizado. Por essa razão, o endereço passado nesta rotina deve ser o endereço final da variável onde este valor será armazenado, que em nosso caso é pDeviceExt->pNextDeviceObj sem passar por variáveis intermediárias.

Esses detalhes são importantes e farão você entender que usar a versão safe desta rotina não é garantia de que tudo dará certo. Imagine que usando a versão safe você receba o endereço do próximo device em uma variável local e depois atualize seu device extension. Esse é um daqueles típicos casos que é necessário substituir aquele componente que fica entre o teclado e a cadeira.

Acha preciosismo? Tente ler o capítulo 5 do livro "Programming the Microsoft Windows Driver Model" onde Walter Oney fala sobre como lidar com cancelamento de IRPs.

Depois de atacharmos nosso device já podemos liberar a referência obtida por IoGetDeviceObjectPointer() utilizando a rotina ObDereferenceObject(), já que a rotina IoAttachDeviceToDeviceStackSafe() já garantiu a referência até que essa ligação seja desfeita.

Muito bem. Pra quem não conseguiu entender quase nada do que eu disse, segue o código fonte da implementação da nossa DriverEntry() de exemplo. Sabe como é cabeça de programador, as vezes um if vale mais que mil páginas de explicação.

/****
***     DriverEntry
**
**      Ponto de entrada do driver.
**      Bem vindo ao inferno.
*/
extern "C"
NTSTATUS
DriverEntry(IN PDRIVER_OBJECT  pDriverObj,
            IN PUNICODE_STRING pusRegistryPath)
{
    NTSTATUS            nts;
    PDEVICE_OBJECT      pMyDeviceObj;
    int                 i;
    UNICODE_STRING      usDeviceName;
    PDEVICE_OBJECT      pTargetDeviceObj;
    PFILE_OBJECT        pFileObj;
    PDEVICE_EXTENSION   pDeviceExt;
 
    //-f--> Seta a rotina de descarga do driver.
    pDriverObj->DriverUnload = OnDriverUnload;
 
    //-f--> Seta todas as dispatch routines do driver para
    //      uma que encaminhe a IRP para o driver original.
    for (i = 0; i <= IRP_MJ_MAXIMUM_FUNCTION; i++)
        pDriverObj->MajorFunction[i] = OnForwardDispatch;
 
    //-f--> Inicializamos a string com o nome do device ao
    //      qual queremos nos atachar.
    RtlInitUnicodeString(&usDeviceName,
                         L"\\Device\\StringList");
 
    //-f--> Obtemos o ponteito do device de destino
    nts = IoGetDeviceObjectPointer(&usDeviceName,
                                   FILE_READ_DATA,
                                   &pFileObj,
                                   &pTargetDeviceObj);
    if (!NT_SUCCESS(nts))
        return nts;
 
    //-f--> Criamos nosso device object
    nts = IoCreateDevice(pDriverObj,
                         sizeof(DEVICE_EXTENSION),
                         NULL,
                         pTargetDeviceObj->DeviceType,
                         pTargetDeviceObj->Characteristics,
                         FALSE,
                         &pMyDeviceObj);
    if (!NT_SUCCESS(nts))
    {
        //-f--> Oops!
        ObDereferenceObject(pFileObj);
        return nts;
    }
 
    //-f--> Obtem nosso DEVICE_EXTENSION
    pDeviceExt = (PDEVICE_EXTENSION)pMyDeviceObj->DeviceExtension;
 
    //-f--> Utiliza o mesmo método de IO do driver original
    pMyDeviceObj->Flags |= pTargetDeviceObj->Flags & (DO_BUFFERED_IO | DO_DIRECT_IO);
 
    //-f--> Aqui nosso driver entra na pilha de dispositivos
    nts = IoAttachDeviceToDeviceStackSafe(pMyDeviceObj,
                                          pTargetDeviceObj,
                                          &pDeviceExt->pNextDeviceObj);
    if (!NT_SUCCESS(nts))
    {
        //-f--> Oops!
        IoDeleteDevice(pMyDeviceObj);
        //-f--> Aqui não está faltando um return.
    }
 
    //-f--> Independente de estarmos atachados ou não, devemos liberar
    //      a referência obtida do device de destino.
    ObDereferenceObject(pFileObj);
    return nts;
}

Escrevendo a OnDriverUnload

Aqui é onde a festa acaba, antes de o nosso driver ser descarregado pelo sistema, teremos que remover nosso device da pilha de dispositivos e destruí-lo. (Risadas maléficas)

O código aqui é simples e não requer explicações se você for capaz de ler os comentários contidos nele.

/****
***     OnDriverUnload
**
**      Rotina de descarga do driver.
*/
VOID
OnDriverUnload(IN PDRIVER_OBJECT  pDriverObj)
{
    PDEVICE_OBJECT      pMyDeviceObj;
    PDEVICE_EXTENSION   pDeviceExt;
 
    //-f--> Nosso device está na lista de devices criados por este driver
    //      então vamos obtê-lo simples assim:
    pMyDeviceObj = pDriverObj->DeviceObject;
 
    //-f--> Aqui obtêmos o device extension.
    pDeviceExt = (PDEVICE_EXTENSION)pMyDeviceObj->DeviceExtension;
 
    //-f--> Aqui removemos nosso device da pilha passando o endereço do
    //      próximo device para a rotina abaixo.
    IoDetachDevice(pDeviceExt->pNextDeviceObj);
 
    //-f--> Agora podemos destruir nosso device (risadas maléficas)
    IoDeleteDevice(pMyDeviceObj);
}

"Fernando, nosso driver é forçado a se descarregar quando o driver original é descarregado?"

Essa é a filosofia do WDM, drivers são carregados automáticamente quandos seus dispositivos são detectados e descarregados quando seus dispositivos são desativados ou removidos. Os filtros seguem as mesmas regras e são carregados/descarregados basendo-se nestes eventos.

Mas não é isso o que acontece aqui. Os drivers de exemplo que uso neste blog são do modelo Legacy, e não WDM. No modelo Legacy, drivers são iniciados seguindo sua ordem de carga no registry, e não tem nada a ver com a detecção do seu dispositivo. Os filtros precisam iniciar depois dos drivers originais, e isso também é controlado pela sua ordem de carga. Este post fala sobre a ordem de carga dos legacy drivers.

"Tá! Falou, falou e não respondeu minha pergunta. O que acontece se eu solicitar a descarga do driver original enquanto houver um filtro atachado sobre ele?"

A descarga dos drivers que formam uma pilha deve ocorrer de forma inversa à sua carga. Neste caso o filtro deve ser descarregado antes do driver original, desempilhando os devices de cima para baixo. Caso o driver original receba uma solicitação de descarga enquanto ainda hoverem referências a seus devices, seja por um filtro ou por uma aplicação, a descarga é adiada até que suas referências sejam desfeitas. Até lá, a tentativa de obter novas referências para um device que recebeu a solicitação de descarga serão negadas.

Escrevendo Dispatch Routines

As dispatch routines de um filtro também são diferentes das dispatch routines de um driver. Apensar de elas poderem completar uma IRP chamando IoCompleteRequest(), elas normalmente repassam a socilitação adiante utilizando a rotina IoCallDriver(). Vou falar mais sobre o comportamento das dispatch routines de um filtro em posts futuros. Neste filtro de exemplo vamos apenas logar a atividade e repassar a solicitação ao próximo driver.

Quando falamos em repassar uma solicitação estamos na verdade falando de repassar IRPs. A leitura deste outro post é essencial para o que vamos fazer na implementação de nossas dispatch routines.

Para acabar esse post ainda nessa vida, segue código da implementação de nossa dispatch routine. Depois de ler o post sobre IRPs que acabei de recomendar, ler os comentários deste código devem ser suficientes para entender tudo o que foi feito aqui, ou não.

/****
***     OnForwardDispatch
**
**      Nossa dispatch routine simplesmente loga a IRP
**      recebida e repassa a solicitação adiante.
**
*/
NTSTATUS
OnForwardDispatch(IN PDEVICE_OBJECT    pDeviceObj,
                  IN PIRP              pIrp)
{
    PDEVICE_EXTENSION   pDeviceExt;
    PIO_STACK_LOCATION  pStack;
 
    //-f--> Obtém ponteiro para o device extesion
    pDeviceExt = (PDEVICE_EXTENSION)pDeviceObj->DeviceExtension;
 
    //-f--> Obtém stack location corrente
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> Manda o nome na major routine da IRP
    ASSERT(pStack->MajorFunction <= IRP_MJ_MAXIMUM_FUNCTION);
    DbgPrint("[StringFilter] : %s\n", g_szMajorNames[pStack->MajorFunction]);
 
    //-f--> Como não estamos modificando nada na stack location,
    //      vamos deixá-la para que o próximo device a use.
    IoSkipCurrentIrpStackLocation(pIrp);
 
    //-f--> Encaminha a IRP para o próximo device.
    return IoCallDriver(pDeviceExt->pNextDeviceObj,
                        pIrp);
}

Caso não tenham entendido nada, não esqueçam de me mandar um e-mail expondo suas dúvidas (sem ofenças pessoais). Isso me ajudará a entender suas dificuldades e a melhorar minhas explicações.

Testando o Filtro

Essa é a parte fácil do post. Para testar o filtro teremos primeiro que compilar, instalar e iniciar o driver deste post. Se você ainda não sabe como fazer isso, este outro post pode te dar um ponto de partida. Depois disso, compile, instale e inicie o filtro.

Depois de instalados, podemos utilizar a aplicação de teste para exercitar o driver. Poderemos acompanhar a atividade do filtro observando suas mensagens de debug que podem ser vistas no depurador de Kernel ou simplemente usando esta aplicação, que dispensa o uso de um depurador para ver as mensagens de debug de um driver.

"Fernando, fiz um teste aqui e ví que ao iniciar o filtro ele loga um evento de IRP_MJ_CLOSE mesmo antes de iniciar a aplicação de teste. O que eu fiz de errado?"

Não há nada de errado. Isso acontece por causa da sequência de passos seguidos na rotina DriverEntry() do filtro. Inicialmente o driver chama a rotina IoGetDeviceObjectPointer(), isso faz com que o IoManager envie uma solicitação de IRP_MJ_CREATE para o driver original. Depois disso nos atachamos à pilha de dispositivos e por fim chamamos a rotina ObDereferenceObject() que vai finalizar a única referência do file object que recebemos, enviando uma solicitação de IRP_MJ_CLOSE para o driver de baixo. Como já estamos atachados a ele, então somos capazes de ver nossa própria atividade sobre o driver original. Isso pode ser observado pela pilha de chamadas que teremos se houver um breakpoint em nossa dispatch routine quando liberarmos a referência do file object ao final da DriverEntry().

kd> k
ChildEBP RetAddr  
f8af9bcc 804ee129 StringFilter!OnForwardDispatch
f8af9bdc 80578f6a nt!IopfCallDriver+0x31
f8af9c14 805b0b18 nt!IopDeleteFile+0x132
f8af9c30 80522bd1 nt!ObpRemoveObjectRoutine+0xe0
f8af9c54 f8c80663 nt!ObfDereferenceObject+0x5f
f8af9c7c 805767ff StringFilter!DriverEntry+0xf3
f8af9d4c 8057690f nt!IopLoadDriver+0x66d
f8af9d74 80534c12 nt!IopLoadUnloadDriver+0x45
f8af9dac 805c61ee nt!ExpWorkerThread+0x100
f8af9ddc 80541de2 nt!PspSystemThreadStartup+0x34
00000000 00000000 nt!KiThreadStartup+0x16

Como de costume, o fonte do filtro que foi implementado neste post está disponível para download. Nosso filtro não faz quase nada, mas já servirá de base para posts futuros que darão mais funcionalidade a ele explicando como tais funcionalidades são implementadas.

Até mais!

Download StringFilter.zip

Drivers de Boot no Windows

fernando@driverentry.com.br (Fernando Roberto da Silva) — Thu, 17 Dec 2009 12:37:00 +0000

Tenho acompanhado o trabalho do meu amigo Lesma, que em seu blog tem descrito como o processo de boot transforma um apanhado de bytes no disco rígido em um sistema operacional vivo. Pegando carona nesse tema, vou aproveitar para comentar sobre a ordem de carga dos drivers durante este processo. Com isso posso tentar responder uma pergunta frequente dos leitores: "Como fazer para que meu driver seja o primeiro a ser carregado?". Talvez este post possa clarear um pouco as coisas neste sentido, ou não.

Eu primeiro! Eu primeiro!

Um ponto importante a ser considerado no modelo Legacy quando escrevemos um driver é o referente ao momento no qual seu driver é carregado. Isso é configurado no valor "Start" na chave do driver no registro. Quatro valores configuram o momento da carga do seu driver, sendo eles:

Boot (0) - Drivers são carregados durante o boot, antes mesmo sistema operacional estar completamente pronto para execução.
System (1) - Drivers são carregados depois dos drivers de boot, quando o Kernel já está completamente funcional.
Automatic (2) - Neste grupo os drivers são carregados quando os subsistemas forem carregados. Basicamente junto com os serviços de User Mode.
Manual (3) - Nenhuma carga automática é realizada aqui, o driver é carregado somente quando alguém, ou algum componente, solicita sua carga.
Disabled (4)- Mesmo que o driver seja solicitado, sua carga é negada.

"Bom, então para meu driver ser o primeiro a ser carregado ele precisa ser iniciado como boot e pronto?"

Na verdade seu driver vai disputar um lugar na fila de drivers que querem ser iniciados no boot. Vários drivers estão configurados para ser iniciados nesse momento e o seu será apenas mais um. Mesmo entre os drivers de boot, uma ordem de carga precisa ser seguida para que certos drivers possam contar com os serviços de outros drivers. Por esse motivo, drivers se separam em grupos. Um grupo de cada vez vai sendo iniciado até que todos os drivers de boot passem por esse processo.

Drivers identificam seu grupo pelo valor "Group" encontrado em sua chave de registro. Esta chave deve conter o nome do grupo ao qual o driver pertence. Os nomes de todos os grupos podem ser encontrados na chave HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ServiceGroupOrder. Nela existe um valor do tipo REG_MULTI_SZ chamado "List" que contém a lista de todos os grupos existentes dispostos em sua ordem de carga.

"Tudo bem, meu driver está configurado para ser iniciado em Boot e está configurado para iniciar com o primeiro grupo de drivers. Pronto agora?"

Quase. Quando falamos em iniciar grupos de drivers, já fica sub-entendido que mais de um driver será carregado. A ordem que tais drivers são carregados dentro de cada grupo também pode ser determinada.

A chave KHEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\GroupOrderList mantém uma série de valores, cada um com o nome de um grupo. O valor é do tipo REG_BINARY e sua interpretação é um array de conjuntos de quatro bytes. O primeiro conjunto indica quantas tags estão contidas naquele buffer binário. Os demais conjuntos são as representações numéricas de cada tag. Dessa forma, a interpretação do buffer exibido na figura abaixo nos dá a informação de que temos seis tags, sendo elas: 1, 2, 3, 4, 5 e 6.

"Mas o que é uma tag?"

Uma tag é a identificação numérica de um driver dentro de um determinado grupo. Um driver se identifica pelo valor "Tag" que podemos encontrar na chave do driver no registro.

Apesar de o exemplo nos mostrar uma ordem crescente de tags, o valor da tag não determina a ordem de carga dos drivers. A ordem é determinada por sua posição dentro do buffer binário.

Ficou com nojinho de mexer em buffers binários? Você pode utilizar o OSR Driver Loader que configura tudo isso pra você quando utilizado para instalar um driver.

Colocar sua tag como primeiro na lista de tags classifica sua ordem de carga dentro de um determinado grupo, mas ainda não é fator determinante para ter seu driver carregado antes de todos os drivers do universo. Um novo grupo sempre pode ser criado e ter sua ordem de carga configurada para antes do seu grupo.

Todas essas regras sobre grupos, tags e afins não fazem sentido nos drivers gerenciados pelo Plug-And-Play (Pnp) Manager, já que a carga de tais drivers é solicitada quando o dispositivo ao qual seu driver está relacionado é detectado pelo driver de barramento.

"Aff! Fernando, pega leve e tenta explicar isso de novo."

Tudo bem, vamos lá. Quando você instala um driver Pnp, você o associa a um determinado dispositivo. Apenas como exemplo, digamos que esse dispositivo seja um conversor USB/Serial. Seu driver será carregado automagicamente quando seu dispositivo for detectado e será descarregado quando o dispositivo for removido.

Para que ele seja detectado, outros dispositivos precisam ser detectados antes, tais como controladora PCI, controladora USB e hub USB. Essa lista de dependência cria a pilha de dispositivos USB.

A controladora PCI, ao ser detectada, tem seu driver carregado e este enumera seus dispositivos filhos, já que PCI é um barramento. Para cada disposivito detectado, esse driver utiliza o barramento para detectar a identidade de cada dispositivo e cria um Phisical Device Object (PDO) para cada um deles. O Pnp Manager carrega o driver de cada dispositivo atachado a esse barramento. Esse driver criará o Functional Device Object (FDO) do dispositivo, dando funcionalidade a ele.

Um desses dispositivos é a controladora do barramento USB. Seguindo o ritual, o driver de barramento USB enumera seus dispositivos filhos, criando novos PDOs. Assim, os hubs USB são detectados e seu driver será carregado. Este driver criará um novo FDO para cada hub. O driver de hub USB vai enumerar seus dispositivos filhos e é nesse momento que seu dispositivo é detectado. O driver que você escreveu será carregado e o Pnp Manager irá chamar sua rotina AddDevice, que receberá o PDO que o driver de hub criou referente ao seu dispositivo.

Ufa! Tudo bem, tenham calma. O assunto Plug-And-Play não é o foco deste post e já está na minha lista de posts futuros.

Toda essa atividade que age recursivamente serve para montar a árvore de dispositivos do sistema. Sabendo que esta árvore é formada pelos nossos drivers e seus devices, fica explícito aqui que no fundo "As árveres somos nozes". A figura abaixo dá uma idéia de como a árvore de dispositivos é organizada.

Ainda falando sobre ordem de carga de drivers, não faria sentido ter seu driver carregado antes de todos os outros drivers, já que os componentes básicos para a comunicação com seu dispositivo ainda não foram carregados, e por isso, não possuem funcionalidade nenhuma. Além do mais, ter seu driver carregado muito cedo lhe trará problemas em lidar com outros componentes do sistema que ainda não estarão prontos para atender seu pedido. Mais detalhes neste post.

Depurando no Boot

Outro assunto curioso e que pode gerar alguma confusão é o referente ao debug de drivers que são carregados no boot. Apesar de a conexão de Debug usar o meio serial, firewire ou mesmo USB, os drivers referentes a estes meios não precisam estar carregados para que você possa realizar o debug do sistema. Em outras palavras, o driver de porta serial não é utilizado para fazer debug do sistema quando se usa o meio serial. Isso seria um problema se pensarmos que alguns drivers são carregados e inciados antes do driver de porta serial. Como estes drivers seriam depurados?

O fato é que o algoritmo que lida com os meios de depuração do sistema são definidos no próprio Kernel (mais precisamente no módulo ntoskrnl.exe e seus irmãos). Este módulo lida diretamente com o hardware responsável pelo meio utilizado. Essa é também a explicação para outra pergunta frequente: "Meu computador não tem porta serial. Posso usar um conversor USB/Serial do lado Target para fazer debug do sistema?". Como acabamos de ver, um conversor USB/Serial depende de toda uma pilha de dispositivos para que a porta serial esteja disponível. Tal funcionalidade não está implementada no algoritmo de debug do sistema, e como comentei neste outro post, sistemas mais novos implementam novas funcionalidades de debug no Kernel.

Mesmo que seu driver seja de boot, ele ainda pode ser depurado. Este outro post mostra ainda como fazer mapeamento de um driver de boot pelo WinDbg. Não sabe do que estou falando? É sobre ter seu driver substituído por uma nova versão automaticamente no lado target quando este for carregado. Vale a pena dar uma olhada.

Have fun!

Mais um Engenheiro à solta

fernando@driverentry.com.br (Fernando Roberto da Silva) — Fri, 27 Nov 2009 14:34:00 +0000

Ufa! Quarta-feira passada foi minha última prova da universidade. Parece mentira mas finalmente o curso de Engenharia da Computação chegou ao fim. Ainda temos que entregar uma papelada do projeto de conclusão de curso, mas são apenas papéis. Acabaram as provas, os trabalhos, os relatórios e agora um baita peso começa a sair das minhas costas à medida que as notas vão sendo liberadas no site da universidade. Quem me segue no Twitter teve uma idéia da correria que tem sido. Esse ano foi especialmente apertado por conta das dependêcias que tive que cursar, do estágio que tive que fazer, e por fim, do projeto de formatura que tivemos que apresentar.

O projeto foi o maior responsável pela minha ausência no blog, foram muitos testes, sustos, sensores queimados, apresentações e feiras.

Pera aí! Você disse sensores queimados?

Isso mesmo. Murphy pode ser considerado um integrante do nosso grupo já que esteve sempre presente no desenvolvimento do projeto. Nas vésperas da apresentação para a banca avaliadora, um mal contato nos reguladores de tensão, originado pela trepidação do motor do helimodelo, fez com que quase tudo se queimasse. Foi um desespero geral, já que os sensores eram importados. Sem falar da grana que teríamos que desembolsar, ainda teríamos que aguardar a entrega que ocorre em média em duas semanas. Nesse momento Murphy nos deu uma trégua. Particularmente acho que ele ficou com pena de nós. Digo isso porque no dia seguinte encontramos uma revenda de sensores similares aos que estávamos usando no projeto aqui em Santo André (cidade onde moro). Quando entramos em contato com a revenda, descobrimos que eles tinham os sensores em estoque. Inacreditável não?

Depois da apresentação que fizemos para a banca avaliadora, ainda fomos convidados a participar da apresentação de gala da universidade, onde os melhores projetos do ano foram exibidos.

Também ficamos em segundo lugar no concurso "Melhor Aplicação Acadêmica Baseada em PC" promovido pela National Instruments, e com isso fomos convidados a expor nosso trabalho no stand da National no ISA Show 2009. O mais legal é que o primeiro lugar deste concurso foi conquistado por um grupo também da minha sala na Universidade São Judas Tadeu. Isso evidenciou que além de ficarmos na frente de várias outras universidades, mostrou que nossa sala né brinquedo não.

A National Instruments produziu este vídeo explicativo onde eu falo sobre a idéia básica do projeto. O vídeo foi feito na chácara de um dos componentes do grupo, onde ficamos internados nas últimas semanas antes das apresentações finais.

Este é apenas um post de "Ei, estou voltando do coma!". Agora vou parar de falar sobre o projeto e voltar a falar sobre o que realmente interessa: "Telas Azuis da Morte". O meu grande dilema agora é se devo também comentar algo sobre firmware e hardware. Desenvolvi muitas atividades com software embarcado não só durante a produção do projeto.

Durante o projeto, sobretudo desenvolvendo protocolo USB em um 8051 utilizando o Keil, além de ler sensores e trabalhar com barramentos em um PIC utilizando o compilador C18 no MPLAB.

Além disso, tive a oportunidade de contribuir no desenvolvimento de um projeto do IPEI. O hardware deste projeto mede os resultados de uma máquina de tração e os envia a um computador via USB. Contribui no desenvolvimento do firmware PIC implementando o protocolo HID mais uma vez utilizando o MPLAB.

Por último e não menos importante, também contribui no desenvolvimento de firmware FreeScale durante meu estágio na Commodity. Este firmware também lida com protocolo USB, e conta com o auxílio de um chip que dispoê desta interface, já que o DSP que compunha a solução não o fazia. Desta vez tive que utilizar o Code Warrior no desenvolvimento, e revivi o tempo em que trabalhei na Provectus desenvolvendo um Bootloader para a atualização do próprio firmware via rede 485, só que dessa vez foi através da USB.

Tanta interação com a USB de ambos os lados do cabo é principalmente fruto dos conhecimentos adquiridos com o livro "USB Complete" de Jan Alexlson. Não me lembro se já comentei sobre esse livro aqui antes, mas vale a pena falar dele principalmente sobre do ponto de vista eletrônico/firmware. O livro é simplesmente ótimo, mas diz não cobrir o desenvolvimento de drivers para USB pois tal assunto daria um livro à parte. Com isso ele indica um velho conhecido nosso, o "Programming the Windows Driver Model" de Walter Oney.

De qualquer forma, aguardem por reformas neste blog. Durante muito tempo tenho trabalhado no limite para conseguir postar e ainda dar conta de todo o resto. Agora meu tempo extra me permitirá fazer posts com mais frequência e finalmente montar turmas abertas do Curso de Drivers para Windows.

Como alguns de vocês já sabem, mantenho uma lista de interessados no curso e que serão notificados por e-mail quando as turmas forem abertas. Independente disso, gostaria de receber e-mails sobre preferências de horários e especialidades, tais como WDM/KMFD/UMDF/File Systems ou ainda sobre ênfase em USB/PCI.

É isso aí. Para um post que não tinha nada a dizer, até que esse disse muito.
Até breve!

Um Helimodelo no XV Simpósio Multidisciplinar

fernando@driverentry.com.br (Fernando Roberto da Silva) — Tue, 08 Sep 2009 15:19:00 +0000

Esse é mais um daqueles posts Off-Topic que não tem nada a ver com nada. Ou quase nada. Acho que a maioria de vocês já esta cansada de saber que este é meu último ano da universidade e que este ano estou todo enrolado com nosso Trabalho de Graduação (TG). Quem acompanha meu Twitter tem uma idéia de como isso tem tomado meu tempo. Você pode estar se perguntando: "O que faz este projeto?". Em uma palavra: "Nada". Estamos trabalhando a mais de um ano desenvolvendo hardware, firmware, driver, software e controle para que o projeto não faça nada. Na verdade, o objetivo é que não aconteça nada com um helimodelo em voo. Tá, tudo bem, desde o começo agora.

Era uma vez um helimodelo

Alguns de vocês já sabem que além de programador retardado, também tento gastar o tempo que não tenho como helimodelista. Um helimodelo é um helicóptero em escala reduzida, equipado com motor à combustão ou mesmo elétrico. Com as funcionalidades de um helicóptero convencional, é capaz de realizar voos com as mesmas características e liberdade de movimentos. Na verdade, quanto à capacidade de voo, um helimodelo pode fazer mais que um helicóptero real. Não é incomum ver um helimodelo voando de cabeça para baixo.

Um helimodelo é controlado por um sistema de rádio controle que determina os movimentos de servomotores instalados na aeronave. Cada servo tem seu papel específico dentro do helimodelo. Um controla o acelerador, outro a inclinação das pás do rotor de cauda e assim por diante.

É fácil controlar um helimodelo?

Não mesmo. O rádio controle possui dois sticks, e assim, são 4 os movimentos que você deve comandar ao mesmo tempo, isso além das chaves adicionais. O grande problema é que para ganhar os reflexos necessários para fazer a correção leva um certo tempo de treino. Acredite, você não vai querer um helimodelo voando desgovernado perto de você. Além do risco de se ferir, é quase certo que o helimodelo acertará algo e se dividirá em vários pedaços. Posso dizer que este não é um equipamento barato e cada queda pode significar centenas de reais para colocar tudo para funcionar novamente. Para começar com esse hobby normalmente utilizamos um simulador.

Um simulador é muito parecido com um vídeo-game. Com ele você recebe um joystick especial que é uma réplica de um rádio controle, mas que faz interface USB com seu computador. Você utiliza tal joystick para controlar um helimodelo na tela do seu computador. Assim, a cada queda que o modelo sofrer, basta apertar um botão de reset no próprio controle para que você possa tentar novamente. Quando eu estava começando no hobby, todos me indicaram um simulador até que comprei um. Fiquei pensando: "Que dificil que nada... Pra cima de mim? Só se for pra esses coroas. Tenho mais de vinte anos de vídeo-game nas costas". Quando comecei a brincar com o simulador ví que não era tão fácil assim. Dezenas e dezenas de quedas. Os simuladores são realmente um excelente início. Eles conseguem reproduzir com grandes detalhes o comportamento de um modelo.

Depois do simulador, você normalmente faz aulas de voo. E para isso você contrata um instrutor. Mas o que pode fazer um instrutor além de lhe desejar boa sorte? O que acontece é que rádios controles podem ser ligados por um cabo de treinamento. Esse cabo permite que o instrutor possa controlar o helimodelo, e com o mudar de uma chave, o controle passa para a mão do aluno. Se o aluno perder o controle sobre o modelo, o instrutor pode tomar o controle de volta e evitar que seu helimodelo novinho se transforme num monte de lixo.

Legal, mas e o projeto?

Nosso projeto tem como objetivo controlar um helimodelo em voo de forma a estabilizá-lo. Por isso digo que nosso projeto vai fazer nada. Houve professor que ainda disse: "Caramba! Vocês vão fazer tudo isso para fazer um helicóptero ficar parado?". Se você é um helimodelista, sabe que manter o helimodelo parado é o primeiro desafio de um piloto. Mesmo em ambientes sem vento, estabilizar um helimodelo requer uma boa quantidade de experiência. Nosso objetivo final seria descrever um plano de voo simples onde ele decole, estabilize no ar, faça alguns movimentos e finalmente pouse. Não queremos dar um passo maior que a perna. Vamos ver o que conseguimos até o dia da apresentação.

Para detectar os movimentos do helimodelo, nós instalamos alguns sensores no helimodelo, os dados dos sensores são reunidos por um microcontrolador que está instalado numa placa também a bordo do helimodelo. Depois de reunidos, os dados são enviados à uma outra placa em solo através de um módulo ZigBee. Na foto abaixo pode-se ver nossa plaquinha. Essa placa em solo é um kit da Atmel que tem suporte a diversas interfaces, sendo a USB uma delas. Assim, escrevemos o firmware e o driver USB para fazer com que tais leituras agora fossem recebidas pelo nosso software de controle.

Para fazer o controle, utilizaremos o novo Toolkit de lógica Fuzzy que está disponível no novo LabVIEW 2009 da National Instruments. Para quem não conhece, o LabVIEW é uma das principais ferramentas de controle utilizadas pela engenharia moderna. É possível fazer programas de controle apenas desenhando e arrastando componentes sobre a tela, pode parecer contraditório um desenvolvedor de baixo nível dizer isso, mas toda essa abstração nos dá tempo para dedicar às coisas que realmente precisam de tempo. A ferramenta também dispõe de interfaces de I/O permitindo trabalhar com sensores e atuadores diretamente sobre o meio eletrônico.

Uma outra informação interessante é que o Toolkit de PID e Lógica Fuzzy foi completamente re-escrito e reformulado com a ajuda de um brasileiro. Isso mesmo, Bruno Cesar (na foto ao lado) trabalha na National Instruments Brasil e foi um dos responsáveis por esse desenvolvimento. Acha isso conhecidência? Então o que você me diria ao saber que ele também se formou na Universidade São Judas Tadeu? Bruno esteve semana passada no campus da Mooca dando uma palestra sobre o novo módulo de lógica Fuzzy. Isso nos deu mais certeza de que a lógica Fuzzy é a ideal para nosso problema de controle, já que ela é perfeita para lidar com problemas complexos onde não se tem o modelo matemático que descreva o comportamento de um helimodelo. A lógica Fuzzy se baseia na experiência de um operador para atuar sobre os controles. É bem interessante.

O LabVIEW também nos permite que façamos chamadas à DLLs. Essa foi uma maneira simples que conseguimos para fazer com os dados que estavam no driver chagar ao software de controle. Assim, criamos uma DLL que abstraísse muitas das complicações de se interagir com um dispositivo USB. O LabVIEW apenas chama funções do tipo LeAmostra() que já retorna o dado pronto para o uso. Todo aquele código com CreateFile() e DeviceIoControl() ficou por conta da DLL, além de outras funções auxiliares.

Agora vocês podem estar se perguntando: "Mas como o LabVIEW vai atuar sobre o helimodelo?". Lembra daquele cabo de treinamento? Nossa placa USB vai receber as ações de controle do LabVIEW através da mesma DLL. Para fazer com que tais comandos sejam aplicados sobre o helimodelo, fizemos com que nossa placa USB se comporte como um rádio controle, que utilizará o cabo de treinamento para aplicar o controle sobre o helimodelo. Obviamente ainda teremos um piloto segurando o rádio no papel de instrutor, principalmente para evitar acidentes, onde um mal funcionamento de nosso projeto poderia transformar meu helimodelo num monte de lixo.

O Simpósio Multidisciplinar

Desde que comecei a escrever sobre o projeto neste blog, algumas pessoas ficaram curiosas e disseram: "Me avise quando houver alguma apresentação". Bom, esta é a sua chance de dar uma olhada em alguns projetos. Nosso projeto foi aceito para ter um espaço neste evento que vai acontecer de 18 a 25 de setembro na Universidade São Judas Tadeu. Serão várias apresentações curtas de 15 cada. Os projetos ainda não estão terminados, e dessa forma, você ainda não verá nenhum helimodelo voando sozinho por lá, mas estaremos com nosso equipamento dispostos a responder algumas perguntas. O simpósio é aberto à visitação pública. Não é necessário ser aluno para participar, basta se inscrever gratuitamente no site da universidade e pronto. Se quiser discutir um pouco sobre sensores, microcontroladores, firmwares, drivers, controle ou ainda helimodelismo, mesmo que durante um café, é só aparecer.

Bom, é isso aí. Já escrevi demais. Agora preciso voltar ao meu projeto.
Até mais!

Notificando eventos à aplicação

fernando@driverentry.com.br (Fernando Roberto da Silva) — Tue, 18 Aug 2009 19:32:00 +0000

Há algumas semanas, cá estava eu todo enrolado com meu projeto da faculdade. Com toda essa atividade, o que tenho comentado com meus amigos é que meu Twitter mais parece um cronograma. Mas em fim, em meio a tanta correria, recebi a seguinte dúvida do leitor Júlio César (Rio de Janeiro - RJ):

"Como implementar a comunicação entre um driver e uma aplicação de modo que o driver inicie a comunicação? Ou seja, não quero que a aplicação envie uma mensagem ao driver, mas sim que o driver envie uma mensagem à aplicação."

Minha resposta curta, porém grossa, é que não existem meios de um driver simplesmente acordar numa manhã ensolarada, coçar a barriga enquanto se espreguiça e dizer a si mesmo: "Hoje vou fazer uma surpresa ao meu amigo notepad.exe. Vou mandar lhe um cartão postal da Kernel-lândia."

Um modelo Cliente-Servidor

O Windows funciona num modelo Cliente-Servidor, onde o lado Servidor seria o Kernel, que atende às requisições de seus clientes, que nesse caso são as aplicações. Nenhuma atividade é iniciada pelo Kernel por vontade própria. Sempre são as aplicações, que utilizando a API nativa do sistema, solicitam notificações do sistema de uma série de eventos.

"Mas Fernando, como ficam as notificações do plug-and-play às aplicações em user-mode?"

Na verdade elas são solicitadas pelas aplicações utilizando a rotina RegisterDeviceNotification(). Esse assunto é bem legal para se comentar num post futuro. Deixa eu anotar aqui na minha lista de posts a escrever.

"Mas Fernando, quando o sistema inicia, as coisas não começam automagicamente?"

O Boot é um procedimento especial no qual o Kernel inicia apenas o Gerenciador de Sessão na User-lândia, também conhecido pelos mais chegados como Smss. O Smss é um processo nativo (que utiliza apenas API nativa) e é considerado um componente de confiança. Ele não utiliza API Windows porque o Subsistema Windows (Csrss) ainda não existe. Daí em diante ocorre uma série de inicializações originadas pelo Smss e seus processos filhos, mas vou deixar os detalhes sobre isso com o Lesma. Isso me fez lembrar que Csrss se extende por "Client Server Run-Time Subsystem".

"Mas Fernando, e quanto aos serviços?"

Serviços são iniciados por um processo chamado Services.exe, que por sua vez também foi iniciado por outro componente durante o processo de Boot.

"Mas Fernando, e quanto aos drivers de boot?"

A carga de drivers não é considerada uma notificação para o user-mode.

"Mas Fernando, setembro chove?"

Bom, chega né? Vamos falar do que interessa agora.

Operações de I/O pendentes

Já vimos em um outro post que uma aplicação pode solicitar serviços ao driver. Para dar a impressão de que o driver enviou uma notificação à aplicação, podemos utilizar uma operação que ficaria pendente até que o evento desejado ocorra. Tal como uma operação de leitura numa porta serial, que ficaria presa na chamada ReadFile() até que um ou mais caracteres fossem recebidos.

Isso funciona razoavelmente bem, mas teríamos algumas complicações caso o evento nunca ocorra e sua aplicação precise sair porque deixou o feijão no fogo ou coisa assim. Dessa forma, teríamos que adotar uma solução multi-threaded, onde uma segunda thread avisaria à thread pendente de que é tarde demais, que não adianta mais esperar pelo evento, já era, miou, esquece, cai na real.

Para as pessoas que sofrem de "thread-fobia", uma solução utilizando Overlapped I/O cairia como uma luva, mas não vou falar sobre isso hoje. Na verdade isso já está na minha lista, mas não vai ser hoje.

Compartilhando um evento

A maneira que mais gosto de trabalhar é compartilhando um evento. Todos sabem o que é um evento? Pode parecer besteira, mas tem muita gente não sabe direito o que é um handle e quer programar o Kernel. Isso me preocupa um pouco. Que tipo de drivers essas pessoas podem gerar? Me permitam abrir um parenteses aqui para fazer uma pergunta: O que vocês acham de além de eu oferecer posts de drivers, eu oferecer posts sobre System Programming? Coisas como Processos, Threads, Objetos, Handles, Memória Virtual, Heaps, Dispatch Objects, Sincronismo e por aí vai. Me mandem e-mails com sugestões, que serão muito bem vindas.

Voltando ao que interessa, se uma aplicação cria um evento e manda seu handle para o driver, este poderá sinalizar a existência de uma informação relevante à aplicação. Assim a aplicação pode esperar por este evento, e quando este for sinalizado, a aplicação faz o I/O para buscar tal informação usando os meios de comunicação que já vimos em outros posts.

Image Notifier

Para exemplificar a recepção de eventos gerados por um driver, vamos ver hoje um driver que nos avisará sempre que uma imagem for mapeada em um processo.

Primeiro vamos definir uma interface para essa comunicação. A aplicação precisará enviar o handle de um evento para o driver, isso também vai avisar o driver que a aplicação deseja receber notificações sobre o mapeamento de imagens. Para isso vamos definir nossas IOCTLs como já vimos neste outro post.

//-f--> Este será o IOCTL para notificar o driver de que uma
//      aplicação está interessada nos eventos de carga de
//      imagens. Este IOCTL deverá levar o handle do evento
//      a ser sinalizado quando houver dados para a aplicação.
#define IOCTL_IMG_START_NOTIFYING   CTL_CODE(FILE_DEVICE_UNKNOWN,   \
                                             0x800,                 \
                                             METHOD_BUFFERED,       \
                                             FILE_ANY_ACCESS)
 
 
//-f--> Sei que é besteira criar uma estrutura com um só membro,
//      mas isso além de ser mais didático, facilita para aquela
//      galera que vai fazer "Copy and Paste" do meu código para
//      outros projetos. Depois eles vão querer mandar mais dados
//      ao driver e vão se enrolar com isso. Aí já viu de quem é
//      a culpa: "Peguei esse código no blog daquela besta!".
typedef struct _IMG_START_NOTIFYING
{
    HANDLE  hEvent;
 
} IMG_START_NOTIFYING, *PIMG_START_NOTIFYING;
 
 
//-f--> Este será o IOCTL que a aplicação lançará ao driver para
//      obter os detalhes sobre a carga de imagens num processo.
#define IOCTL_IMG_GET_IMAGE_DETAIL  CTL_CODE(FILE_DEVICE_UNKNOWN,   \
                                             0x801,                 \
                                             METHOD_BUFFERED,       \
                                             FILE_ANY_ACCESS)
 
 
//-f--> Aqui vou definir um path máximo de 260 caracteres, mas
//      podem haver casos de paths mais longos. Não vou tratar
//      todos os casos e nem otimizar o transporte deste buffer
//      pegando apenas os bytes válidos.
#define IMG_MAX_IMAGE_NAME  260
 
 
//-f--> Aqui segue path da imagem que o driver obterá
//      antes de notificar a aplicação.
typedef struct _IMG_IMAGE_DETAIL
{
    CHAR    ImageName[IMG_MAX_IMAGE_NAME];
 
} IMG_IMAGE_DETAIL, *PIMG_IMAGE_DETAIL;
 
 
//-f--> Aqui a aplicação diz que não está mais interessada nas
//      notificações sobre imagens. Isso fará com que o driver
//      libere a referência que fez ao handle.
#define IOCTL_IMG_STOP_NOTIFYING    CTL_CODE(FILE_DEVICE_UNKNOWN,   \
                                             0x802,                 \
                                             METHOD_BUFFERED,       \
                                             FILE_ANY_ACCESS)

Não vou colocar todo o código aqui no post, mas está tudo disponível no exemplo para download ao final deste post. Lembrem-se que nove em cada dez dentistas recomendam a leitura dos comentários para o melhor entendimento do exemplo. A aplicação basicamente criará um evento e enviará seu handle para o driver através de um IOCTL.

    //-f--> Cria o evento que será compartilhado.
    hNotificationEvt = CreateEvent(NULL,
                                   TRUE,
                                   FALSE,
                                   NULL);
    _ASSERT(hNotificationEvt);
 
    printf("Requesting device to start notifying.\n");
 
    //-f--> Copiamos o handle do evento para a estrutura
    //      que será enviada ao driver. Como sabemos, handles
    //      são válidos apenas no contexto deste processo,
    //      então estamos admitindo que nosso driver estará
    //      no topo da device stack.
    StartNotifying.hEvent = hNotificationEvt;
    if (!DeviceIoControl(hDevice,
                         IOCTL_IMG_START_NOTIFYING,
                         &StartNotifying,
                         sizeof(StartNotifying),
                         NULL,
                         0,
                         &dwBytes,
                         NULL))
    {
        //-f--> Respira fundo e abre o WinDbg...
        dwError = GetLastError();
        printf("Error #%d on starting device notification.\n",
               dwError);
        __leave;
    }

Quando o driver receber este IOCTL, este irá adquirir uma referência ao objeto apontado pelo handle. Notem que para isso o driver utiliza a rotina ObReferenceObjectByHandle() do Object Manager, que além de incrementar o contador de referência do objeto, também certifica que o handle é do tipo de objeto que você espera receber. Isso evitaria que, por algum motivo, o handle de um outro objeto tenha sido passado no lugar do handle do evento. O resultado dessa chamada será um ponteiro para um evento recebido pelo driver. Como sabemos, objetos têm seu header num formato padrão, mas o corpo do objeto varia dependendo do seu tipo. Imagine que alguém enviasse um handle para uma thread no lugar de um handle para um evento, poderiamos usar as rotinas de evento para manipular uma thread e a chance de tudo ficar azul é alta. Por isso o uso do parâmetro ObjectType, apesar de opcional, é muito recomendado.

    //-f--> Obtém uma referência ao objeto
    nts =  ObReferenceObjectByHandle(pStartNotifying->hEvent,
                                     EVENT_ALL_ACCESS,
                                     *ExEventObjectType,
                                     UserMode,
                                     (PVOID*)&g_pEvent,
                                     NULL);

"Fernando, isso é mesmo necessário? Minha aplicação é a única que vai usar esse driver, e ela sempre vai enviar um handle para evento."

Esse tipo de precaução evita que um programa engraçadinho envie qualquer coisa para seu driver produzindo uma tela azul propositalmente.

"Fernando, na minha opinião você gosta mesmo é de complicar as coisas. Eu não poderia simplesmente fazer uma cópia do handle e usar as rotinas do tipo ZwSetEvent() que recebem o handle do evento como parâmetro?"

Veja bem, o handle é válido apenas dentro do processo que o obteve. No nosso caso, tal handle é válido apenas no contexto da nossa aplicação de teste. As notificações de imagens rodam em contexto arbitrário, ou seja, sabe Deus em qual contexto de processo. Por isso teremos que obter uma referência que seja válida em qualquer contexto. O ponteiro obtido pela rotina ObReferenceObjectByHandle() é válido em qualquer contexto, pois aponta para o próprio objeto que reside em System Space. Se você não sabe o que significa System Space, então dê uma passeada por este post.

Bom, depois disso a aplicação vai ficar aguardando o evento ser sinalizado pelo driver. No código abaixo, dois eventos são monitorados, um deles é sinalizado pelo driver enquanto o outro é sinalizado pela própria aplicação no momento de encerrar sua atividade.

    //-f--> Aqui criamos um array de handles para a espera
    //      por múltiplos objetos.
    hObjects[0] = hFinishEvt;
    hObjects[1] = hNotificationEvt;
 
    do
    {
        //-f--> Espera ou por um sinal do device indicando a
        //      presença de dados no driver, ou um sinal da
        //      thread primária dizendo aquela baboseira de
        //      novela e tals.
        dwWait = WaitForMultipleObjects(2,
                                        hObjects,
                                        FALSE,
                                        INFINITE);
        switch(dwWait)
        {
        case WAIT_FAILED:
            //-f--> Pô Murphy, dá um tempo!
            dwError = GetLastError();
            printf("Error #%d on waiting for device notification.\n",
                   dwError);
            __leave;
 
        case WAIT_OBJECT_0 + 1:
            //-f--> Opa! O driver tem algo para nós, vamos buscar.
            if (GetImageDetail(hDevice) != ERROR_SUCCESS)
                __leave;
            break;
        }
 
        //-f--> Ficaremos nisso enquanto o evento de finalização
        //      não for sinalizado pela thread primária.
    } while(dwWait != WAIT_OBJECT_0);

Quando o evento é sinalizado, a aplicação enviará um IOCTL para obter os dados do driver. Nossa aplicação de teste também imprime esse dado na tela por pura diversão. Vamos dar uma olhada no código do driver para saber como isso acontece.

Durante a inicialização, o driver chama a rotina PsSetLoadImageNotifyRoutine() para registrar uma rotina de callback que é chamada sempre que uma imagem for mapeada para algum processo.

    //-f--> Registra rotina de callback para receber
    //      as notificações de imagens mapeadas para
    //      processos.
    nts = PsSetLoadImageNotifyRoutine(OnLoadImage);
    ASSERT(NT_SUCCESS(nts));

Nossa rotina de callback converte o path da imagem mapeada de Unicode para ANSI. Mais detalhes sobre conversão de strings neste post. Em seguida a rotina coloca esse path numa lista e seta o evento enviado pela aplicação. Se você ainda não sabe brincar de listas ligadas no kernel do Widows, então leia este post.

VOID
OnLoadImage(IN PUNICODE_STRING  pusFullImageName,
            IN HANDLE           hProcessId,
            IN PIMAGE_INFO      pImageInfo)
{
    PIMG_EVENT_NODE pNode;
    ANSI_STRING     asImageName;
    NTSTATUS        nts;
 
    //-f--> Vamos adquirir o controle das variáveis
    //      compartilhadas por diferentes threads.
    nts = KeWaitForMutexObject(&g_EventMtx,
                               UserRequest,
                               KernelMode,
                               FALSE,
                               NULL);
    ASSERT(NT_SUCCESS(nts));
 
    __try
    {
        //-f--> Verifica se a aplicação está interessada neste
        //      evento.
        if (!g_pEvent)
            __leave;
 
        //-f--> Aloca um nó para a lista de paths de imagens
        pNode = (PIMG_EVENT_NODE)ExAllocatePoolWithTag(PagedPool,
                                                       sizeof(IMG_EVENT_NODE),
                                                       IMG_TAG);
        if (!pNode)
        {
            //-f--> Ops!
            ASSERT(FALSE);
            __leave;
        }
 
        //-f--> Inicializa uma ANSI_STRING para usar na conversão
        //      do path da imagem. Vamos fornecer sempre um byte
        //      a menos para nos reservar espaço para adicionar um
        //      terminador nulo.
        RtlInitEmptyAnsiString(&asImageName,
                               pNode->ImageDetail.ImageName,
                               sizeof(pNode->ImageDetail.ImageName) - 1);
 
        //-f--> Faz a conversão sem alocação do resultado.
        nts = RtlUnicodeStringToAnsiString(&asImageName,
                                           pusFullImageName,
                                           FALSE);
        if (!NT_SUCCESS(nts))
        {
            //-f--> Ops!
            ASSERT(FALSE);
            ExFreePool(pNode);
            __leave;
        }
 
        //-f--> Coloca o terminador nulo para que a aplicação de
        //      teste possa contar com ele na hora de fazer o print.
        asImageName.Buffer[asImageName.Length] = 0;
 
        //-f--> Insere o nó na lista.
        InsertTailList(&g_ListHead,
                       &pNode->Entry);
 
        //-f--> Setamos o evento informando a aplicação que existem
        //      dados na lista a serem lidos.
        KeSetEvent(g_pEvent,
                   IO_NO_INCREMENT,
                   FALSE);
    }
    __finally
    {
        //-f--> Por fim, libera o mutex e corre pro abraço.
        KeReleaseMutex(&g_EventMtx,
                       FALSE);
    }
}

Quando o evento é sinalizado, a aplicação acorda de seu sono profundo e descobre que o driver tem dados para ela. Então ela envia um IOCTL para obter tais dados. Este IOCTL vai executar a rotina abaixo removendo o primeiro elemento da lista e verificar se ainda existem mais dados a serem coletados pela aplicação. Caso a lista esvazie nesta chamada, o driver reseta o evento para que a aplicação volte a dormir esperando pelos registros de novas imagens mapeadas.

NTSTATUS
OnGetImageDetail(PIMG_IMAGE_DETAIL  pImageDetail)
{
    NTSTATUS        nts;
    PLIST_ENTRY     pEntry;
    PIMG_EVENT_NODE pNode;
 
    //-f--> Adquire o mutex
    nts = KeWaitForMutexObject(&g_EventMtx,
                               UserRequest,
                               KernelMode,
                               FALSE,
                               NULL);
    ASSERT(NT_SUCCESS(nts));
 
    //-f--> Verifica se a lista está vazia. Sempre
    //      use esta rotina antes de tentar remover
    //      um elemento da lista.
    if (!IsListEmpty(&g_ListHead))
    {
        //-f--> Obtém o endereço do Entry
        pEntry = RemoveHeadList(&g_ListHead);
 
        //-f--> Obtém o endereço do nó
        pNode = CONTAINING_RECORD(pEntry,
                                  IMG_EVENT_NODE,
                                  Entry);
 
        //-f--> Copia para o buffer da aplicação.
        RtlCopyMemory(pImageDetail,
                      &pNode->ImageDetail,
                      sizeof(IMG_IMAGE_DETAIL));
 
        //-f--> Libera o nó e balezia
        ExFreePool(pNode);
        nts = STATUS_SUCCESS;
    }
    else
        nts = STATUS_NO_MORE_ENTRIES;
 
    //-f--> Pode ser que nesta chamada a lista tenha
    //      ficado vazia. Então verificamos novamente
    //      e resetamos o evento para que a aplicação
    //      não volte aqui.
    if (IsListEmpty(&g_ListHead))
        KeResetEvent(g_pEvent);
 
    //-f--> Libera o mutex e pronto.
    KeReleaseMutex(&g_EventMtx,
                   FALSE);
    return nts;
}

O resultado de tanto bla-bla-bla

Depois que o driver for compilado, instalado e iniciado, poderemos executar nossa aplicação de teste e esperar que algo seja executado. Quando um processo é criado, tanto seu módulo como as DLLs que ele depende são mapeadas no sistema. Isso vai disparar nossa rotina de callback no driver e fazer a coisa toda funcionar. Se você não sabe como compilar, instalar e iniciar um driver, este post pode te ajudar.

A imagem acima é o resultado da execução do notepad.exe enquanto nossa aplicação de teste esperava por eventos, mas qualquer outro processo poderia disparar tais eventos. Este post além de nos fornecer este exemplo de chamada invertida, também nos mostra como brincar com Mutex Objects, que foi a dúvida de outro leitor, Ismael Rocha (Brasília - DF).

Agora deixa eu voltar para o meu projeto da faculdade.
Até mais!

Download ImgNotifier.zip

Strings no Kernel

fernando@driverentry.com.br (Fernando Roberto da Silva) — Tue, 07 Jul 2009 15:01:00 +0000

Tem coisa mais besta que manipular strings? Creio que a resposta correta seria "Depende". Quando eu tinha terminado meu curso técnico de Informática Industrial em 1995, eu pensava que sabia muito de linguagem C. Afinal de contas eu já sabia manipular strings. Copiar, concatenar, inverter, fazer buscas por palavras... O que mais um programador deveria saber? Quando comecei a fazer meu estágio e a pegar programas do mundo real, descobri que eu não sabia nada. Mas uma coisa é certa, eu sabia manipular strings. Este post deve ajudar bastante os programadores C++ que manjam tudo de Templates, Smart Pointers, STL e coisas mágicas que abstraem a realidade facilitando a vida do programador. Com todos esses recursos de contadores de referências e sobrecarga de tudo que é operador, as coisas começam a ficar nebulosas e você começa a se perguntar: "Mas onde está o buffer mesmo?". Hoje vamos apenas dar uma passadinha de leve nas estruturas UNICODE_STRING, ANSI_STRING e algumas funções de conversão entre elas. Pode parecer besteira, mas se você não souber brincar de strings, pra quê aprender o resto? Vai tudo acabar em tela azul mesmo.

E no prézinho...

Nós aprendemos com a tia da escolinha que strings são cadeias de caracteres. Assim poderíamos contar a história de nossas vidas apenas colocando um caractere na frente do outro.

CHAR    szExemplo[] = "Tava ruim lá na Bahia, profissão de bóia-fria\n"
                      "Trabalhando noite e dia, num era isso que eu queria\n"
                      "Eu vim-me embora pra \"Sum Paulo\",\n"
                      "Eu vim no lombo dum jumento com pouco conhecimento\n"
                      "Enfrentando chuva e vento e dando uns peido fedorento (vish)\n"
                      "Até minha bunda fez um calo\n"
                      "Chegando na capital, uns puta predião legal\n"
                      "As mina pagando um pau, mas meu jumento tava mal\n"
                      "Precisando reformar\n"
                      "Fiz a pintura, importei quatro ferradura\n"
                      "Troquei até dentadura e pra completar a belezura\n"
                      "Eu instalei um Road-Star!";

Jumento Celestino / Mamonas Assassinas

Duas coisas são obrigatórias que você saiba para que você possa continuar lendo este post. Uma delas é que estes caracteres precisam estar armazenados em algum lugar, seja em uma variável local, alocadas no heap ou mesmo no segmento de dados inicializados. A outra coisa é que strings normalmente são terminadas por um caractere NULL, mas a falta dele não descaracteriza uma string. Isso significa que podemos ter strings sem terminadores onde seu tamanho é indicado por uma outra variável. Deixo aqui um gancho para o Lesma explicar essas coisas aos meninos e meninas interessados.

Uma outra característica importante é que nem sempre um caractere é igual a um Byte. Existem strings compostas por caracteres largos. Caracteres largos, ao contrário do que se pensa, não são caracteres sortudos, mas sim, caracteres formados por valores de 16 bits. Com strings formadas por tais caracteres pode-se expressar palavras em qualquer idioma. Isso explica como o Windows consegue lidar com nomes de arquivos alienígenas quando você tenta instalar os drivers do HiPhone que você comprou no China.

Além disso, imagine que ocorra um erro durante o processo de criptografia do seu disco rídigo. Seria vital que uma mensagem de erro detalha lhe fosse exibida independente da nacionalidade do produto. Se a informação vai ajudar já é outro assunto.

Quatro tipos de strings

Destes temos duas strings que já estamos acostumados a ver em user-Mode, ambas terminadas com caractere NULL.

CHAR    szString[] = "Uma string de CHAR";
WCHAR   wzString[] = L"Uma string de WCHAR";

As outras duas strings são as que normalmente vemos em kernel-mode.

typedef struct _UNICODE_STRING {
  USHORT  Length;
  USHORT  MaximumLength;
  PWSTR  Buffer;
} UNICODE_STRING, *PUNICODE_STRING;
 
typedef struct _STRING {
  USHORT  Length;
  USHORT  MaximumLength;
  PCHAR  Buffer;
} ANSI_STRING, *PANSI_STRING;

Estas strings são definidas por estruturas com três membros, os quais descrevo abaixo. O comportamento das rotinas e macros que às manipulam é muito similar. Por isso vou concentrar meus exemplos em UNICODE_STRING já que o sub-sistema Win32 converte tudo para unicode quando passa uma chamada para o kernel.

Buffer: E um ponteiro para a região de memória onde os caracteres são armazenados.
Length: Indica a quantidade de bytes válidos da string. Este tamanho é sempre expresso em bytes, mesmo que esta seja uma string de WCHAR.
MaximumLength: Indica o tamanho máximo que esta string pode ter.

Para entender de como estes membros são interpretados, dê uma olhada no exemplo abaixo:

void OsTresMembros(void)
{
    WCHAR           wsUmArray[200];
    UNICODE_STRING  usString;
 
    //--f-> Indico onde os caracteres desta string
    //      serão armazenados.
    usString.Buffer = wsUmArray;
 
    //-f--> Ainda não escrevemos nada no buffer,
    //      por isso, nada do que esteja no buffer
    //      é válido.
    usString.Length = 0;
 
    //-f--> Embora o buffer não esteja inicializado
    //      ele ainda está lá e pode conter uma string
    //      de no máximo seu tamanho em bytes.
    usString.MaximumLength = sizeof(wsUmArray);
}

Aqui vemos uma string unicode vazia, pois tem zero bytes válidos, mas sua capacidade de armazenar é de até 200 caracteres. Notem que os caracteres são armazenados em um array que está na pilha. Isso significa que nenhum leak de memória será causado com o termino desta rotina.

Inicializando Strings

Podemos ainda utilizar algumas macros que fazem a inicialização destas estruturas.

void InitString(void)
{
    UNICODE_STRING  usOutraConstante;
    UNICODE_STRING  usVazia;
    WCHAR           wzBuffer[30] = L"Isso não será considerado.";
 
    //-f--> Inicaliza uma string na sua criação.
    UNICODE_STRING  usConstante = RTL_CONSTANT_STRING(L"Uma string.");
 
    //-f--> Inicializa uma string constante.
    RtlInitUnicodeString(&usOutraConstante,
                         L"Uma outra string constante que não muda.");
 
    //-f--> Inicializa uma string vazia para uso posterior
    RtlInitEmptyUnicodeString(&usVazia,
                              wzBuffer,
                              sizeof(wzBuffer));
}

Reparem nos valores destas estruturas.

kd> ?? usConstante
struct _UNICODE_STRING
 "Uma string."
   +0x000 Length           : 0x16
   +0x002 MaximumLength    : 0x18
   +0x004 Buffer           : 0xf8cd8600  "Uma string."
 
kd> db 0xf8cd8600 L0x18
f8cd8600  55 00 6d 00 61 00 20 00-73 00 74 00 72 00 69 00  U.m.a. .s.t.r.i.
f8cd8610  6e 00 67 00 2e 00 00 00                          n.g.....

Embora a capacidade máxima desta string seja de 0x18 caracteres, somente 0x16 bytes são válidos. Isso porque a macro desconsidera o terminador NULL que o compilador C/C++ deixou de brinde.

A macro RTL_CONSTANT_STRING() nos permite inicializar a string na sua criação, mas um outro notável recurso dela é que ela ferra o IntelliSence do Visual Studio (2008 pelo menos). Então se você gosta mesmo do IntelliSence, prefira utilizar a macro RtlInitUnicodeString().

kd> ?? usVazia
struct _UNICODE_STRING
 "Isso não será considerado."
   +0x000 Length           : 0
   +0x002 MaximumLength    : 0x3c
   +0x004 Buffer           : 0xf8ae5c34  "Isso não será considerado."

Oops! Como pode uma string com zero bytes válidos ser exibida pelo WinDbg? Na verdade, o que acontece é que o WinDbg desmonta a estrutura UNICODE_STRING e mostra cada um dos mebros aqui. No caso, existe um array de WCHAR com valores bem comportados aqui. Não culpe o coitadinho. Você é que está mal acostumado com o Visual Studio.

kd> db 0xf8ae5c34 L0x3c
f8ae5c34  49 00 73 00 73 00 6f 00-20 00 6e 00 e3 00 6f 00  I.s.s.o. .n...o.
f8ae5c44  20 00 73 00 65 00 72 00-e1 00 20 00 63 00 6f 00   .s.e.r... .c.o.
f8ae5c54  6e 00 73 00 69 00 64 00-65 00 72 00 61 00 64 00  n.s.i.d.e.r.a.d.
f8ae5c64  6f 00 2e 00 00 00 00 00-00 00 00 00              o...........

Mas estes dados só estão aí por acaso. Eles não são considerados como parte válida de uma string unicode. Isso atrapalha um pouco na hora de fazer o debug pois mesmo a janela de variáveis locais também mostra esse conteúdo inválido.

A extensão !ustr mostra apenas os dados válidos de uma string unicode.

kd> !ustr usConstante
String(22,24) at f899fc6c: Uma string.
 
kd> !ustr usVazia
String(0,60) at f8ae5c1c:

O terminador é necessário?

Não mesmo! Você pode bem observar que nos exemplos anteriores, a macro deixou o terminador de fora dos bytes válidos. Considerar o terminador como byte válido é um erro e pode gerar confusão. Imagine comparar duas strings distintas que carregam o mesmo conteúdo, mas uma delas considera o terminador como informação válida. Tais strings serão diferentes, já que possuem comprimento diferente.

Creio que o importante mesmo é não contar com o terminador nas strings que você recebe de outros componentes. É fato que na maioria das vezes, o buffer possui um terminador, e que apesar de não ser considerado informação válida, o terminador ainda está lá. Nunca conte com isso a menos que haja alguma nota na documentação. Já vi pessoas que utilizarem o membro Buffer como parâmetro para uma chamada à rotina wcslen() por exemplo. Além do risco de obter a informação incorreta, ainda tem um plus de poder gerar uma tela azul.

"Mas Fernando, eu já testei isso em vários sistemas operacionais e sempre funcionou."

Isso não justifica nada, você não pode se apoiar em testes, mas em documentações. Quando seu produto se espalha no mercado, ele enfrenta muitos ambientes diferentes, com os mais diversos filtros, anti-virus, monitores e por aí vai. Não se pode ter certeza da implementação de qualquer software. O melhor que podemos esperar deles é que se apoiem na documentação.

Manipulando Strings

Os membros da estrutura UNICODE_STRING são basicamente utilizados por rotinas de manipulação a fim de verificar se o buffer existente é suficiente para a operação desejada. Portanto, antes de utilizar uma string, certifique-se de esta foi inicializada corretamente. No caso de uma cópia de strings, a string de destino precisará ser inicilizada mesmo que vazia.

void CopyString(void)
{
    UNICODE_STRING  usSource;
    UNICODE_STRING  usTarget;
    WCHAR           wzTarget[10];
 
    //-f--> Aqui inicializamos nossa string de origem.
    RtlInitUnicodeString(&usSource,
                         L"12345678901234567890");
 
    //-f--> Aqui inicializamos nossa string de destino.
    RtlInitEmptyUnicodeString(&usTarget,
                              wzTarget,
                              sizeof(wzTarget));
 
    //-f--> Realiza a cópia
    RtlCopyUnicodeString(&usTarget,
                         &usSource);
}

Aqui vemos o exemplo de uma cópia de string onde a string de origem é maior que a de destino. Nessa situação não teremos uma violação de acesso, mas o buffer de destino será preenchido completamente. Notem que a rotina não nos deixou o confortável terminador.

kd> !ustr usTarget
String(20,20) at f89a3c6c: 1234567890
 
kd> ?? usTarget
struct _UNICODE_STRING
 "1234567890"
   +0x000 Length           : 0x14
   +0x002 MaximumLength    : 0x14
   +0x004 Buffer           : 0xf89a3c54  "1234567890"
 
kd> db 0xf89a3c54 L0x20
f89a3c54  31 00 32 00 33 00 34 00-35 00 36 00 37 00 38 00  1.2.3.4.5.6.7.8.
f89a3c64  39 00 30 00 98 5d 5f 00-14 00 14 00 54 3c 9a f8  9.0..]_.....T<..

Diferentes da rotina RtlCopyUnicodeString(), algumas outras rotinas nos retornam STATUS_BUFFER_TOO_SMALL quando o buffer é insuficiente.

VOID 
  RtlCopyUnicodeString(
    IN OUT PUNICODE_STRING  DestinationString,
    IN PCUNICODE_STRING  SourceString
    );
 
NTSTATUS 
  RtlAppendUnicodeStringToString(
    IN OUT PUNICODE_STRING  Destination,
    IN PUNICODE_STRING  Source
    );

Existe uma série de rotinas de manipulação de strings no WDK, mas sempre fica faltando alguma rotina se comparado com a ampla biblioteca de rotinas da biblioteca padrão C/C++. Rotinas como strrchr() por exemplo. Quando necessário teremos que construir uma versão que manipule estruturas UNICODE_STRING da mesma maneira. Aqui está uma lista básica de rotinas de string que o WDK suporta. Outras funções são listadas aqui, mas falaremos delas mais tarde.

Mas onde está o buffer mesmo?

A estrutura UNICODE_STRING não armazena buffer, mas sim um ponteiro para ele. Dessa forma, a maneira de descartar uma string varia dependendo da maneira que você a obteve. Nos exemplos que vimos até agora, os bufferes utilizados estão em dados inicializados ou de arrays locais da função de exemplo. Existem rotinas que inicializam e alocam strings como forma de retornar a informação desejada. Nestes casos, é necessário liberar o buffer que você recebeu. É o caso das rotinas que fazem a conversão de ANSI_STRING para UNICODE_STRING e vice versa. São elas RtlUnicodeStringToAnsiString() e RtlAnsiStringToUnicodeString().

NTSTATUS 
  RtlAnsiStringToUnicodeString(
    IN OUT PUNICODE_STRING  DestinationString,
    IN PANSI_STRING  SourceString,
    IN BOOLEAN  AllocateDestinationString
    );
 
NTSTATUS 
  RtlUnicodeStringToAnsiString(
    IN OUT PANSI_STRING  DestinationString,
    IN PUNICODE_STRING  SourceString,
    IN BOOLEAN  AllocateDestinationString
    );

O exemplo abaixo faz uma conversão de ANSI para UNICODE com alocação do resultado, e em seguida, libera o buffer recebido.

void ConvertString(void)
{
    ANSI_STRING     asString;
    UNICODE_STRING  usString;
 
    //-f--> Aqui inicializamos nossa string de origem.
    RtlInitAnsiString(&asString,
                      "Um exemplo simples.");
 
    //-f--> Neste caso não precisaremos inicializar a
    //     string de destino. A rotina fará isso por nós.
    RtlAnsiStringToUnicodeString(&usString,
                                 &asString,
                                 TRUE);
 
    //-f--> Imprime a string resultante
    DbgPrint("String convertida: %wZ\n",
             &usString);
 
    //-f--> Liberamos o buffer alocado na conversão.
    RtlFreeUnicodeString(&usString);
}

Você mesmo pode escrever uma rotina que gere UNICODE_STRINGs alocando o buffer dinamicamente. O buffer pode ser alocado dinamicamente utilizando ExAllocatePoolWithTag() ou uma de suas irmãs. No entanto, na hora de liberar o buffer desta string, utilize a função adequada, que neste exemplo seria ExFreePoolWithTag(). Não saia utilizando RtlFreeUnicodeString() a torto e a direito. Aprecie com moderação. Apenas utilize essa rotina para liberar strings que foram obtidas por funções como RtlAnsiStringToUnicodeString(), cuja documentação indica o uso de RtlFreeUnicodeString().

"..., the caller must deallocate the buffer by calling RtlFreeUnicodeString."

Safe Strings em Kernel

Uma parte das rotinas de manipulação de strings da biblioteca padrão do C/C++, tais como strcpy() e sprintf(), também estão disponíveis em kernel, mas a crescente preocupação com a seguraça na manipulação de buffers fez com que as funções seguras fossem disponibilizadas tanto para user-mode como para kernel-mode. Para ter detalhes sobre o uso destas funções consulte este link.

Mais um driver de exemplo

Este outro post traz o exemplo de um driver que guarda uma lista de strings em memória. Já neste outro post, esse mesmo exemplo foi evoluido para que diferentes listas fossem mantidas sob diferentes contextos. Agora vou evoluir esse exemplo novamente. A aplicação continuará enviando strings com terminadores NULL durante a escrita, o driver criará ANSI_STRINGs a partir delas e às converterão em UNICODE_STRINGs antes de colocá-las na lista.

A maior parte das modificações estão nas rotinas de leitura e escrita, então vou apenas exibir o código dessas rotinas aqui. De qualquer forma, todo o projeto incluindo o driver e uma aplicação de teste estão disponíveis para download ao final deste post. Vamos começar com a rotina de escrita que envia as strings ao driver. Como sempre, toda informação revelante estão nos comentários.

/****
***     OnWrite
**
**      A aplicação está enviando uma string.
*/
NTSTATUS
OnWrite(IN PDEVICE_OBJECT  pDeviceObj,
        IN PIRP            pIrp)
{
    PIO_STACK_LOCATION  pStack;
    ANSI_STRING         asString;
    PSTRING_LIST        pStringList;
    PSTRING_REG         pStringReg;
    ULONG               ulBytes;
    KIRQL               kIrql;
    NTSTATUS            nts;
 
    //-f--> Obtemos a Stack Location corrente.
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> Obtém a ponta da lista.
    pStringList = (PSTRING_LIST)pStack->FileObject->FsContext;
 
    //-f--> O que temos no buffer de sistema aqui é um array
    //      de bytes terminados com NULL. Vamos inicializar
    //      uma ANSI_STRING com este buffer.
    RtlInitAnsiString(&asString,
                      (PCSZ)pIrp->AssociatedIrp.SystemBuffer);
 
    //-f--> Aqui alocamos o nó que vai ser colocado na lista
    pStringReg = (PSTRING_REG) ExAllocatePoolWithTag(NonPagedPool,
                                                     sizeof(STRING_REG),
                                                     STR_LST_TAG);
 
    //-f--> Para fazer a conversão para UNICODE_STRING, vamos
    //      solicitar que a rotina faça a alocação do bufer
    //      resultante. Por essa razão, não precisaremos inicializar
    //      a string de saída.
    nts = RtlAnsiStringToUnicodeString(&pStringReg->usString,
                                       &asString,
                                       TRUE);
    if (!NT_SUCCESS(nts))
    {
        //-f--> Ops! Provavelmente não tivemos memória para isso.
        //      Vamos sinalizar a falha e informar ao IoManager
        //      que zero bytes foram copiados.
        ExFreePoolWithTag(pStringReg, STR_LST_TAG);
        pIrp->IoStatus.Information = 0;
    }
    else
    {
        //-f--> Vamos segurar o spinlock para evitar concorrência
        //      no acesso à lista.
        KeAcquireSpinLock(&pStringList->SpinLock,
                          &kIrql);
 
        //-f--> Insere o nó na lista.
        InsertTailList(&pStringList->ListHead,
                       &pStringReg->Entry);
 
        //-f--> Libera o spinlock.
        KeReleaseSpinLock(&pStringList->SpinLock,
                          kIrql);
 
        //-f--> Aqui informamos ao IoManager que todos os bytes
        //      enviados pela aplicação foram recebidos com
        //      sucesso pelo driver.
        pIrp->IoStatus.Information = pStack->Parameters.Write.Length;
    }
 
    //-f--> O campo de Information já foi preenchido, vamos apenas
    //      copiar o status da operação e completar a IRP.
    pIrp->IoStatus.Status = nts;
    IoCompleteRequest(pIrp, IO_NO_INCREMENT);
    return nts;
}

Agora vejamos a recuperação das strings na leitura.

/****
***     OnRead
**
**      A aplicação está querendo receber as strings eviadas
**      por ela.
*/
NTSTATUS
OnRead(IN PDEVICE_OBJECT  pDeviceObj,
       IN PIRP            pIrp)
{
    ANSI_STRING         asString;
    PIO_STACK_LOCATION  pStack;
    PSTRING_LIST        pStringList;
    PSTRING_REG         pStringReg;
    PLIST_ENTRY         pEntry;
    KIRQL               kIrql;
    NTSTATUS            nts;
 
    //-f--> Vamos deixar este campo com zero até que tenhamos
    //      certeza de que a cópia foi feita paro o buffer da
    //      aplicação
    pIrp->IoStatus.Information = 0;
 
    //-f--> Obtemos a Stack Location corrente.
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> Obtém a ponta da lista.
    pStringList = (PSTRING_LIST)pStack->FileObject->FsContext;
 
    //-f--> Vamos retornar para aplicação apenas um array de CHAR
    //      com terminador NULL. As strings estão armexadas como
    //      UNICODE_STRING. Vamos convertê-las para ANSI_STRING.
    //      Aqui vamos inicializar a ANSI_STRING que receberá
    //      o resultado da conversão de UNICODE_STRING.
 
    //-f--> Vamos oferecer Lengh-1 para reservar um byte para
    //      o terminador null após conversão.
    RtlInitEmptyAnsiString(&asString,
                           (PCHAR)pIrp->AssociatedIrp.SystemBuffer,
                           (USHORT)pStack->Parameters.Read.Length - 1);
 
    //-f--> Aqui vamos adquirir o spinlock para evitar concorrência
    //      no acesso à lista.
    KeAcquireSpinLock(&pStringList->SpinLock,
                      &kIrql);
 
    //-f--> Verifica se a lista está vazia.
    if (IsListEmpty(&pStringList->ListHead))
    {
        //-f--> Sinaliza erro na leitura e já libera o spinlock.
        nts = STATUS_NO_MORE_ENTRIES;
        KeReleaseSpinLock(&pStringList->SpinLock,
                          kIrql);
    }
    else
    {
        //-f--> Remove o registro da lista e já libera o spinlock.
        pEntry = RemoveHeadList(&pStringList->ListHead);
        KeReleaseSpinLock(&pStringList->SpinLock,
                          kIrql);
 
        pStringReg = CONTAINING_RECORD(pEntry,
                                       STRING_REG,
                                       Entry);
 
        //-f--> Aqui convertemos a string. Reparem que não solicitamos
        //      a alocação do buffer. Estamos utilizando o buffer de
        //      sistema para receber o resultado da conversão. Neste
        //      caso a string de destino deve estar inicializada.
        nts = RtlUnicodeStringToAnsiString(&asString,
                                           &pStringReg->usString,
                                           FALSE);
        if (NT_SUCCESS(nts))
        {
            //-f--> Aqui usamos aquele byte que reservamos e assim
            //      o terminador null também é copiado pelo IoManager
            //      do SystemBuffer para o buffer da aplicação
            asString.Buffer[asString.Length] = 0;
 
            //-f--> Precisamos informar ao IoManager a quantidade de
            //      bytes que serão copiados para o buffer da aplicação.
            //      Esse tamanho é o tamanho da string convertida mais
            //      um byte ocupado pelo terminador NULL que colocamos.
            pIrp->IoStatus.Information = asString.Length+1;
        }
 
        //-f--> Neste exemplo, não estamos lidando com o caso de erro
        //      na conversão, isso pode acontecer se a aplicação mandar
        //      um buffer pequeno para a string. Caso algum erro ocorra
        //      durante a conversão, vamos simplesmente descartar a string
 
        //-f--> Libera o buffer da string e em seguida o registro que ela
        //      ocupava na lista.
        RtlFreeUnicodeString(&pStringReg->usString);
        ExFreePoolWithTag(pStringReg, STR_LST_TAG);
    }
 
    //-f--> O campo de Information já foi preenchido, vamos apenas
    //      copiar o status da operação e completar a IRP.
    pIrp->IoStatus.Status = nts;
    IoCompleteRequest(pIrp, IO_NO_INCREMENT);
    return nts;
}

Com este driver rodando, já posso pensar em alguns exemplos de filtros. Já venho pensando em exemplos de filtros há algum tempo, além de receber sujestões de post sobre esse assunto. O fato é que não tinhamos base para tal. O importante é termos um driver simples o suficiente para o fácil entendimento das coisas. Não adianta eu fazer um post com um filtro de disco rígido, um filtro de rede ou qualquer outro driver com plug-and-play e gerenciamento de energia. Estes precisariam de muito conhecimento acumulado e não caberiam num post.

Enfim, mais uma vêz espero ter ajudado. E se alguma dúvida surgir é só me mandar um e-mail.

Have fun!

Download StringList.zip

Levando a tela azul pra casa

fernando@driverentry.com.br (Fernando Roberto da Silva) — Thu, 18 Jun 2009 18:46:00 +0000

Nada melhor que uma bela choraderia para começar este post. Meu rítmo está baixo por conta da universidade estar sugando todas as minhas energias vitais. Se você tem acompanhado meu blog nos últimos posts, já sabe do que estou falando. No meu tempo livre estive correndo com meu projeto, meu estágio e meu emprego. Meu blog também participa dessa lista de tarefas, mas o coitadinho tem menos prioridade aqui. Alguns de vocês devem saber que sou helimodelista por hobby, mas como eu disse ao meu amigo Heldai outro dia: "Hobby é o nome que se dá àquilo que fazemos para ocupar o tempo que temos livre, mas ainda estou para descobrir o nome que daríamos àquilo que gostaríamos de fazer se tivéssemos tempo livre...". Enfim, como isso não tem nada a ver com o post de hoje, vamos mudar de assunto.

Entre uma coisa e outra, estive tentando pensar em algo simples para um post pequeno. Foi então que a dúvida do leitor Ismael Rocha (Brasília - DF) gerou este post.

"Existe uma maneira de salvar as BSOD's para posteriormente verificar eventuais problemas?"

Salvar uma tela azul? Salvar o quê? A máquina já morreu meu amigo! Já era! Acabou! O que você ainda pode tentar salvar é seu emprego.

Brincadeiras à parte, existe sim.

O sistema operacional está pré-configurado para reiniciar automagicamente quando uma falha crítica acontece. Falha crítica é a maneira polida de se dizer que a casa caiu, a vaca foi pro brejo, o jacaré te abraçou, o tambor girou, o ferro berrou, o tempo fechou, ficou pequeno pra você... enfim, uma tela azul aconteceu. Não que eu não goste de telas azuis, mas do efeito colateral que ela nos traz. Pela norma mundial dos consumidores de drivers de terceiros, se você é o autor de um driver que estiver instalado em uma máquina no momento da falha, esteja ele rodando ou não, então a culpa da falha é sua até que se prove o contrário. É triste, mas é a realidade. A partir do momento que uma tela azul acontece, você é o culpado padrão e terá que ficar aguentando piadinhas pelo resto da eternidade. Gostaria de aproveitar o contexto para mandar um abraço pro meu amigo Heldai.

Exibindo a tela azul

Na tentativa de salvar sua dignidade, você tenta provar que a culpa não é sua. Dizer que o reset da máquina é uma feature do seu driver e que felizmente funcionou muito bem não vai colar, não na segunda vez. Mas o que você pode fazer se a tela azul é apenas um flash de informações enquanto a máquina não reinicia? Felizmente você pode mudar isso. Clicando com o botão direito do mouse sobre o "Meu computador", selecionando "Propriedades". Daí em diante é só dar uma olhada na figura abaixo para descobrir que você pode evitar que a máquina reinicie automaginamente.

Você terá de desmarcar a opção "Reiniciar automaticamente", e assim ter todo o tempo que for necessário para mostrar a todos que o problema não é seu. Na maioria das vezes o sistema consegue detectar o driver que provavelmente é o causador de toda essa dor de cabeça e exibir o nome do arquivo na tela azul como podemos ver na figura abaixo.

Desmontando uma tela azul

"Nossa! Então o Windows tem um algorítmo de inteligência artificial, que provalvelmente usa nanotecnologia de alguma forma para descobrir o driver culpado?"

Na verdade é um pouco mais simples que isso, o Windows simplesmemte pega a imagem do driver que lançou uma exceção que não foi manipulada ou que voluntariamente derrubou o sistema por detectar alguma incoerência. Por isso, nem sempre o nome do driver exibido é de fato o nome do driver culpado. Se pensarmos no simples exemplo onde o driver MetralhadoraGiratoria.sys escreve onde não deveria corrompendo algum Pool de alocações, esse erro mais tarde pode ser detectado pelo driver Laranja.sys que, na hora de fazer uma alocação de memória, chama uma rotina de sistema que por sua vez chama a rotina KeBugCheckEx() ao detectar tal incoerência. Consegue adivinhar o nome do driver que aparecerá no BO?

Outras informações ainda podem ser obtidas da tela azul. Se é o nome do seu driver que aparece na tela, então você ainda pode obter o endereço da instrução onde a desgraça ocorreu. Em nosso exemplo o endereço é o 0xF8DD8A415 partir daí podemos chegar na função que estava sendo executada no momento da falha se tivermos o arquivo de mapa gerado pelo linker. Também é possível obter a data da imagem do arquivo e tirar aquela dúvida de que realmente era a versão certa que estava sendo executada. A data do arquivo é obtida no campo DateStamp e é expressa em um valor hexadecimal de 32 bits representando a quantidade de segundos deste meia noite de primeiro de Janeiro de 1970. Difícil mesmo é achar alguém com paciência suficiente para calcular isso diante de uma tela azul. Existem meios bem menos trabalhosos de descobrir que a culpa foi sua mesmo.

Na minha opinião, a informação mais relevante que a tela azul oferece é o Stop Code. Como o nome já sugere, Stop Code é um código que vai indicar o motivo da falha do sistema. você pode consultar a lista de Stop Codes neste link ou ainda dar uma olhada no arquivo C:\WinDDK\6001.18002\inc\api\BugCodes.h que vem no WDK.

Stop Codes vêm com até quatro parâmetros que trazem informações adicionais ao código de parada. A interpretação destes valores dependerá do código de falha, que em nosso exemplo é 0x7E. Consultando no link que informei a pouco, teremos a seguinte interpretação para os valores que nos foi apresentado.

Mas existe um jeito de salvar a BSOD ou não?

Tá tá tá... É que começo a escrever e acabo me empolgando. Mas enfim, quando uma falha crítica ocorre, o sistema cria um arquivo conhecido como Crash Dump. Existem três opções de crash dumps que podem ser geradas.

Dump Completo: Nesta opção, todo o conteúdo da memória física no momento da falha será copiado em um arquivo. Obviamente o tamanho deste arquivo será a quantidade de memória presente na máquina com um acréssimo de 1MB de header. Essa opção não aparece nas máquinas que possuam mais de 2GB de memória física, mas ainda é possivel configurar o dump completo sem utilizar essa interface gráfica escrevendo diretamente no registro. Esse método é também conhecido como "configurar na unha". O dump completo é muito útil quando a informação presente em páginas de memória em User Space for relevante para o problema, tal como situações de Dead Locks. Se você não sabe o que significa User Space, este post pode ajudar.
Dump de Kernel: Aqui somente as páginas em System Space serão copiadas para disco. O tamanho deste arquivo vai variar dependendo de quantidade de memória física a máquina tem instalada, mas não existe uma proporção exata. Muito do balanceamento de páginas utilizado pelo gerenciador de memória virtual vai determinar o tamanho deste arquivo, mas ele fica pela ordem de 200MB num sistema com 4GB de memória total (já dá pra levar no pen drive). Essa opção é normalmente a mais viável, já que só carrega a informação mais relevante para um crash de sistema.
Dump Mínimo: Aqui um arquivo de 64KB será gerado para sistemas 32 bits ( 128KB para sistemas 64 bits). Neste arquivo temos apenas o Stop Code e seus parâmetros, a lista de drivers carregados no momento da falha, informações sobre o processo e thread corrente e o Call Stack da thread que causou a falha.

Na mesma janela onde você configura o reinicio automático do sistema, existem dois outros campos que vão configurar o tipo de dump desejado e o caminho onde este será gerado. Agora você já pode levar sua tela azul no coração e depurar onde você quiser. Em casa, no trabalho, no trêm, no metrô... Você pode ainda pedir que clientes enviem seus crash dumps para que você possa diagnosticar o problema ser ter que se deslocar através de rios e montanhas sob o frio e a chuva.

Tenho o Crash Dump, e agora?

Agora que você é um feliz proprietário de um maravilhoso arquivo de Crash Dump, o que mais você poderia querer da vida? Talvez ser capaz descobrir a causa do problema já seria um bom começo. Para isso vamos utilizar o depurador nativo do sistema operacional. Se você ainda não conhece o WinDbg, então dê uma olhada neste post para que você sabia do que estamos falando aqui.

Admitindo que você tenha Windbg instalado em sua máquina de desenvolvimento, e que este esteja com o servidor de símbolos configurado, tudo que temos a fazer agora é abrir o WinDbg, selecionar o ítem "Open Crash Dump..." no menu "File" e apontar o caminho do arquivo de dump que você copiou da pobre máquina que ousou rodar seu driver. O texto abaixo é o resultado exibido na janela de comandos quando o Crash Dump é aberto.

Microsoft (R) Windows Debugger Version 6.11.0001.404 AMD64
Copyright (c) Microsoft Corporation. All rights reserved.
 
 
Loading Dump File [Z:\Sources\MEMORY.DMP]
Kernel Summary Dump File: Only kernel address space is available
 
Symbol search path is: srv*
Executable search path is: 
Windows XP Kernel Version 2600 (Service Pack 3) UP Free x86 compatible
Product: WinNt, suite: TerminalServer SingleUserTS
Built by: 2600.xpsp.080413-2111
Machine Name:
Kernel base = 0x804d7000 PsLoadedModuleList = 0x80553fc0
Debug session time: Thu Jun 18 14:46:24.969 2009 (GMT-3)
System Uptime: 0 days 0:03:20.375
Loading Kernel Symbols
...............................................................
.........................................................
Loading User Symbols
 
Loading unloaded module list
...........
*******************************************************************************
*                                                                             *
*                        Bugcheck Analysis                                    *
*                                                                             *
*******************************************************************************
 
Use !analyze -v to get detailed debugging information.
 
BugCheck 7E, {c0000005, f8d9f415, f8af1bb4, f8af18b0}
 
Probably caused by : Useless.sys ( Useless!DriverEntry+5 )
 
Followup: MachineOwner
---------

Agora se simplesmente executarmos o comando sugerido, já teremos uma boa descrição do que aconteceu com máquina que sofreu a falha crítica.

kd> !analyze -v
*******************************************************************************
*                                                                             *
*                        Bugcheck Analysis                                    *
*                                                                             *
*******************************************************************************
 
SYSTEM_THREAD_EXCEPTION_NOT_HANDLED (7e)
This is a very common bugcheck.  Usually the exception address pinpoints
the driver/function that caused the problem.  Always note this address
as well as the link date of the driver/image that contains this address.
Arguments:
Arg1: c0000005, The exception code that was not handled
Arg2: f8d9f415, The address that the exception occurred at
Arg3: f8af1bb4, Exception Record Address
Arg4: f8af18b0, Context Record Address
 
Debugging Details:
------------------
 
 
EXCEPTION_CODE: (NTSTATUS) 0xc0000005 - The instruction at 0x%08lx referenced
memory at 0x%08lx. The memory could not be %s.
 
FAULTING_IP: 
Useless!DriverEntry+5 [z:\sources\driverentry\useless\useless.c @ 7]
f8d9f415 c7050000000000000000 mov dword ptr ds:[0],0
 
EXCEPTION_RECORD:  f8af1bb4 -- (.exr 0xfffffffff8af1bb4)
ExceptionAddress: f8d9f415 (Useless!DriverEntry+0x00000005)
   ExceptionCode: c0000005 (Access violation)
  ExceptionFlags: 00000000
NumberParameters: 2
   Parameter[0]: 00000001
   Parameter[1]: 00000000
Attempt to write to address 00000000
 
CONTEXT:  f8af18b0 -- (.cxr 0xfffffffff8af18b0)
eax=07263867 ebx=00000000 ecx=bb40e64e edx=1be10003 esi=e19feea8 edi=81eb41d0
eip=f8d9f415 esp=f8af1c7c ebp=f8af1c7c iopl=0         nv up ei ng nz na po nc
cs=0008  ss=0010  ds=0023  es=0023  fs=0030  gs=0000             efl=00010282
Useless!DriverEntry+0x5:
f8d9f415 c7050000000000000000 mov dword ptr ds:[0],0  ds:0023:00000000=????????
Resetting default scope
 
PROCESS_NAME:  System
 
ERROR_CODE: (NTSTATUS) 0xc0000005 - The instruction at 0x%08lx referenced memory
at 0x%08lx. The memory could not be %s.
 
EXCEPTION_PARAMETER1:  00000001
 
EXCEPTION_PARAMETER2:  00000000
 
WRITE_ADDRESS:  00000000 
 
FOLLOWUP_IP: 
Useless!DriverEntry+5 [z:\sources\driverentry\useless\useless.c @ 7]
f8d9f415 c7050000000000000000 mov dword ptr ds:[0],0
 
BUGCHECK_STR:  0x7E
 
DEFAULT_BUCKET_ID:  NULL_DEREFERENCE
 
LAST_CONTROL_TRANSFER:  from 8057677f to f8d9f415
 
STACK_TEXT:  
f8af1c7c 8057677f 81eb41d0 81d46000 00000000 Useless!DriverEntry+0x5
 [z:\sources\driverentry\useless\useless.c @ 7]
f8af1d4c 8057688f 80000360 00000001 00000000 nt!IopLoadDriver+0x66d
f8af1d74 80534c02 80000360 00000000 823c68b8 nt!IopLoadUnloadDriver+0x45
f8af1dac 805c6160 b29accf4 00000000 00000000 nt!ExpWorkerThread+0x100
f8af1ddc 80541dd2 80534b02 00000001 00000000 nt!PspSystemThreadStartup+0x34
00000000 00000000 00000000 00000000 00000000 nt!KiThreadStartup+0x16
 
 
FAULTING_SOURCE_CODE:  
     3: NTSTATUS DriverEntry(IN PDRIVER_OBJECT  pDriverObject,
     4:                      IN PUNICODE_STRING pusRegistryPath)
     5: {
     6:     //-f--> Diga olá à BSOD e vá se acostumando com ela...
>    7:     *(PVOID*)0x00000000 = 0;
     8:
     9:     //-f--> Não vamos viver para ver isso.
    10:     return STATUS_SUCCESS;
    11: }
 
 
SYMBOL_STACK_INDEX:  0
 
SYMBOL_NAME:  Useless!DriverEntry+5
 
FOLLOWUP_NAME:  MachineOwner
 
MODULE_NAME: Useless
 
IMAGE_NAME:  Useless.sys
 
DEBUG_FLR_IMAGE_TIMESTAMP:  4a3844ef
 
STACK_COMMAND:  .cxr 0xfffffffff8af18b0 ; kb
 
FAILURE_BUCKET_ID:  0x7E_Useless!DriverEntry+5
 
BUCKET_ID:  0x7E_Useless!DriverEntry+5
 
Followup: MachineOwner
---------

Se a máquina que está abrindo o arquivo de dump for a máquina de desenvolvimento do seu driver, o Windbg será capaz de automagicamente achar os fontes do seu driver e apontar a causa da falha com grandes detalhes. Então certifique-se que seu gerente não esteja por perto nesse momento. Isso já é muito mais informação do que você poderia obter simplesmente olhando para a tela azul do computador. Neste exemplo utilizei o driver de exemplo do post Getting Started para reproduzir a tela azul. Mas não se preocupe com isso, mesmo sendo um programador novato em drivers, uma das primeiras coisas que você aprenderá é como gerar telas azuis.

Mais uma vez espero ter ajudado.
Have fun!

Enumerando dispositivos

fernando@driverentry.com.br (Fernando Roberto da Silva) — Fri, 01 May 2009 13:23:00 +0000

Dentre minhas tarefas atuais, estava a de ler as amostras de um giroscópio utilizando uma porta serial e gerar um arquivo com elas. Este arquivo seria lido por um driver semelhante ao demonstrado no post anterior a este. No datasheet do giroscópio há uma descrição do protocolo, sem falar do exemplo feito em Visual Basic que existe no site do fabricante, que demonstra a aceleração angular em cada eixo bem como as acelerações lineares deles como mostra abaixo.

Toda a interface de configuração e obtenção dos dados do giroscópio é realizada através da serial. Mesmo sem uma aplicação dedicada pode-se utilizar um programa qualquer, como o HyperTerminal, para ter acesso aos menus oferecidos pelo dispositivo. Utilizando uma porta serial, qualquer kit de microcontrolador que não tenha display e nem mesmo um teclado pode oferecer uma interface bem amigável.

Escrever protocolos seriais não é algo que me assuste. Duro é ter que lembrar como programar uma aplicação User-Mode que tenha janelas, botões e outros controles, mas nada que um pouco de MSDN não resolva. Programadores de drivers normalmente testam tudo que podem utilizando aplicações console, então desenvolvi um pequeno software de terminal para lidar diretamente com o dispositivo. O fonte dele segue abaixo e fica de brinde para quem precisar brincar com portas seriais qualquer dia.

 
/****
***     main
**
**      E lá vamos nós...
*/
int _tmain(int argc, _TCHAR* argv[])
{
    DWORD           dwBytes,
                    dwError = ERROR_SUCCESS;
    HANDLE          hCom;
    ULONG           i;
    UCHAR           ucByteIn[512], ucByteOut;
    DCB             dcb;
    COMMTIMEOUTS    CommTimeouts;
 
    //-f--> Aqui abrimos aporta serial desejada
    hCom = CreateFile(L"COM3",
                      GENERIC_READ | GENERIC_WRITE,
                      0,
                      NULL,
                      OPEN_EXISTING,
                      0,
                      NULL);
 
    //-f--> Verifica se obtivemos sucesso
    if (hCom == INVALID_HANDLE_VALUE) 
    {
        //-f--> Oops!
        dwError = GetLastError();
        printf("CreateFile failed with error %d.\n",
                dwError);
        return dwError;
    }
 
    //-f--> Existem 7 kilos de configurações da porta serial.
    //      Ao invés de configirar cada uma delas, vamos apenas
    //      obter as configurações padrão do sistema e modificar
    //      apenas as que nos interessa.
    if (!GetCommState(hCom, &dcb))
    {
        //-f--> Oops!
        dwError = GetLastError();
        printf ("GetCommState failed with error %d.\n",
                dwError);
        CloseHandle(hCom);
        return dwError;
    }
 
    //-f--> Aqui modificamos as configurações para setar as
    //      configurações exigidas pelo giroscópio.
    //      57600, 8 N 1 (sem controle de fluxo)
    dcb.DCBlength = sizeof(DCB);
    dcb.BaudRate = CBR_57600;
    dcb.ByteSize = 8;
    dcb.Parity = NOPARITY;
    dcb.StopBits = ONESTOPBIT;
    dcb.fDtrControl = DTR_CONTROL_DISABLE;
    dcb.fRtsControl = RTS_CONTROL_DISABLE;
 
    //-f--> Aqui aplicamos as configurações que modificamos
    if (!SetCommState(hCom, &dcb))
    {
        //-f--> Oops!
        dwError = GetLastError();
        printf ("SetCommState failed with error %d.\n",
                dwError);
        CloseHandle(hCom);
        return dwError;
    }
 
    //-f--> Vou configurar os timeouts de forma que uma
    //      leitura seja completada depois de 100ms mesmo
    //      nenhum caracter seja recebido pela aplicação.
    //      Isso evita da aplicação ficar travada em ReadFile
    //      até que um byte seja recebido pela porta serial
    CommTimeouts.ReadIntervalTimeout = 0;
    CommTimeouts.ReadTotalTimeoutMultiplier = 0;
    CommTimeouts.ReadTotalTimeoutConstant = 100;
    CommTimeouts.WriteTotalTimeoutConstant = 0;
    CommTimeouts.WriteTotalTimeoutMultiplier = 0;
 
    //-f--> Aplica as configurações de timeouts
    if (!SetCommTimeouts(hCom, &CommTimeouts))
    {
        //-f--> Oops!
        dwError = GetLastError();
        printf ("SetCommTimeouts failed with error %d.\n",
                dwError);
        CloseHandle(hCom);
        return dwError;
    }
 
    //-f--> Aqui começa o loop infinito que vai executar
    //      para todo o sempre até o fim dos dias.
    //      Na verdade, se você teclar [ESC] ele termina.
    while(1)
    {
        //-f--> Verifica se há um byte a ser recebido pela
        //      aplicação no buffer de teclado.
        if (_kbhit())
        {
            //-f--> Obtém a tecla
            ucByteOut = _getch();
 
            //-f--> Verifica se a tecla recebida é [ESC]
            if (ucByteOut == 27)
                break;
 
            //-f--> Envia o byte recebido para a porta serial
            if (!WriteFile(hCom,
                           &ucByteOut,
                           1,
                           &dwBytes,
                           NULL))
            {
                //--> Oops!
                dwError = GetLastError();
                break;
            }
        }
 
        //-f--> Verifica se algum byte foi recebido pela
        //      porta serial. Observe que neste loop não
        //      existe o típico Sleep() para não levar a CPU
        //      a 100%. Esta espera é realizada dentro da
        //      chamada à ReadFile(). A função espera por um
        //      byte por até 100ms, conforme configurado nos
        //      timeouts.
        if (!ReadFile(hCom,
                      ucByteIn,
                      sizeof(ucByteIn),
                      &dwBytes,
                      NULL))
        {
            //-f--> Oops!
            dwError = GetLastError();
            break;
        }
 
        //-f--> Imprime na tela a sequência de caracteres recebida
        for (i=0; i<dwBytes; i++)
        {
            if (ucByteIn[i] == 0x0d)
                puts("");
            else
                printf("%c", ucByteIn[i]);
        }
    }
 
    //-f--> Bom se chegamos neste ponto é porque chegamos
    //      ao fim dos dias ou a tecle ESC foi pressionada.
    //      Vamos fechar a porta serial e sair correndo.
    CloseHandle(hCom);
    return dwError;
}

Abrir uma porta serial é a parte mais simples desta história, o problema é decidir qual porta abrir. Como qualquer programa decente, deveria haver um combo list com as portas seriais disponíveis no computador, onde o usuário escolheria uma e pronto. A partir daí é só obter a porta selecionada pelo usuário e montar uma chamada para a rotina CreateFile() como ilustrado no cógido acima.

Tudo bem, arrastei o controle para a janela que eu estava programando e agora é só preenchê-lo. Então pensei: "Deve haver alguma função do tipo EnumerateCommPorts() na API", mas não foi o que a página da referência me mostrava. - Como assim não tem? O Google deve saber algo a respeito. - Acabei descobrindo que esta é uma dúvida bem comum por aí. Uns resolvem este problema fazendo um loop que tenta abrir as portas seriais em sequência (COM1, COM2,... ), outros utilizam a função QueryDosDevice() e filtram os Symbolic Links que iniciam com "COM(n)", mas o método que vou mostrar aqui é capaz de enumerar qualquer tipo de interface utilizando a SetupAPI.

Setup quem?

A SetuAPI é uma parte do Plug-And-Play que fornece serviços às aplicações User-Mode. O Plug-And-Play tem como um dos seus objetivos, unificar a configuração, uso e a enumeração de dispositivos e serviços semelhantes. Desta forma todos os fabricantes de placas que oferecem serviços de porta serial podem ter seus dispositivos configurados de uma única maneira. Dispositivos que oferecem serviços de porta serial devem implementar uma interface pré-definida, ou seja, devem se mostrar dispostos a receber IOCTLs e responder a eles de maneira prevista na documentação.

O driver que desejar criar devices que implementem a interface de porta serial deverá declarar isso através da chamada à rotina IoRegisterDeviceInterface(). Aqui um device é associado à uma classe de interface de dispositivo, a qual é identificada por um GUID. Existem diversas classes de interfaces de dispositivos pré-definidas no sistema, como listado aqui, e a classe de portas seriais é uma delas. A partir daí, seu device será enumerado por rotinas do Plug-and-Play como provedor de uma determinada interface.

Então tá. O que temos que fazer é utilizar estas funções de enumeração de interfaces para descobrir quais os dispositivos que implementam a interface de porta serial. A SetupAPI vai nos ajudar com essa tarefa. Mas antes de darmos uma olhada no fonte, vamos resolver uma coisinha. Tenho visto diferentes maneiras de usar GUID_DEVINTERFACE_COMPORT, uns incluem o header de Kernel-Mode Ntddser.h, outros definem o GUID na unha, mas qual seria o jeito correto?

Definindo o GUID de interface

Tudo começa com a chamada à rotina SetupDiGetClassDevs() que vai reunir informações sobre o grupo de dispositivos que correspondem aos critérios de busca adotados nos parâmetros. Vamos querer dispositivos que implementem a interface identificada por GUID_DEVINTERFACE_COMPORT, mas se simplesmente fizermos a chamada como mostra abaixo obteremos o erro exibido em seguida.

        hDevInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_COMPORT,
                                          NULL,
                                          NULL,
                                          DIGCF_PRESENT | DIGCF_INTERFACEDEVICE);

1>z:\sources\samples\enumserialport.obj : error LNK2001: unresolved external
 symbol _GUID_DEVINTERFACE_COMPORT

Isso ocorre porque GUID_DEVINTERFACE_COMPORT está declarado em WinIoCtl.h. Lembre-se que este header é indiretamente incluído por Windows.h quando o símbolo WIN32_LEAN_AND_MEAN não é definido, como já comentei neste outro post. Mas mesmo incluindo este header ainda temos o mesmo problema. Vamos olhar isso um pouco mais de perto.

No header WinIoCtl.h temos:

DEFINE_GUID(GUID_DEVINTERFACE_COMPORT, 0x86e0d1e0L, 0x8089, 0x11d0,
            0x9c, 0xe4, 0x08, 0x00, 0x3e, 0x30, 0x1f, 0x73);

Mas o que é DEFINE_GUID afinal?

Em GuidDef.h temos:

#ifdef INITGUID
#define DEFINE_GUID(name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8) \
        EXTERN_C const GUID DECLSPEC_SELECTANY name \
                = { l, w1, w2, { b1, b2,  b3,  b4,  b5,  b6,  b7,  b8 } }
#else
#define DEFINE_GUID(name, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8) \
    EXTERN_C const GUID FAR name
#endif // INITGUID

Então agora nos vem o sonoro "Aaaah táaa!". GUID_DEVINTERFACE_COMPORT é uma constante que é definida quando o símbolo INITGUID é definido, caso contrário, esta constante é apenas declarada. O símbolo INITGUID é definido no header InitGuid.h. Assim, quando você quiser utilizar os GUIDs declarados com DEFINE_GUID, você terá que em um dos seus módulos incluir o header Initguid.h antes de Windows.h. Como nosso exemplo só tem um módulo, então fica fácil. Como de costume, todo código fonte está contido num exemplo disponível para download.

//-f--> Vamos ter que colocar estes includes na ordem certa
//      para que o GUID que identifica a interface
//      GUID_DEVINTERFACE_COMPORT seja definido.
#include <InitGuid.h>
#include <Windows.h>
#include <SetupApi.h>

Enumerando interfaces

/****
***     EnumSerialInterfaces
**
**      Rotina que enumera dispositivos que
**      implementam a interface de porta serial
*/
 
DWORD EnumSerialInterfaces(void)
{
    CHAR                        szFriendlyName[100];
    HDEVINFO                    hDevInfoSet = NULL;
    SP_DEVICE_INTERFACE_DATA    DevInterfaceData;
    SP_DEVINFO_DATA             DevInfoData;
    DWORD                       dwReturn,
                                dwInterfaceIndex = 0;
    try
    {
        //-f--> Reunindo informações sobre dispositivos que implementam
        //      a interface desejada que estejam presentes no
        //      momento em que esta rotina é chamada.
        hDevInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_COMPORT,
                                          NULL,
                                          NULL,
                                          DIGCF_PRESENT | DIGCF_INTERFACEDEVICE);
 
        if (hDevInfoSet == INVALID_HANDLE_VALUE)
            throw GetLastError();
 
        DevInterfaceData.cbSize = sizeof(SP_DEVICE_INTERFACE_DATA);
 
        //-f--> Agora enumera cada uma das interfaces
        while (SetupDiEnumDeviceInterfaces(hDevInfoSet,
                                           0,
                                           &GUID_DEVINTERFACE_COMPORT,
                                           dwInterfaceIndex++,
                                           &DevInterfaceData))
        {
            DevInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
 
            //-f--> Para cada uma das interfaces, obtemos o
            //      device que a implementa.
            if (SetupDiGetDeviceInterfaceDetail(hDevInfoSet,
                                                &DevInterfaceData,
                                                NULL,
                                                0,
                                                NULL,
                                                &DevInfoData))
                throw GetLastError();
 
            //-f--> Agora apenas obtemos o nome camarada do dispositivo
            if (!SetupDiGetDeviceRegistryProperty(hDevInfoSet,
                                                  &DevInfoData,
                                                  SPDRP_FRIENDLYNAME,
                                                  NULL,
                                                  (PBYTE)szFriendlyName,
                                                  sizeof(szFriendlyName),
                                                  NULL))
                throw GetLastError();
 
            //-f--> Printf neles...
            printf("%d) %s\n",
                   dwInterfaceIndex,
                   szFriendlyName);
        }
    }
    catch(DWORD dwError)
    {
        //-f--> Oops!

        printf("Error %d on trying enumerate device interfaces.\n",
               dwError);
 
        dwReturn = dwError;
    }
 
    //-f--> Libera as informações obtidas
    if (hDevInfoSet)
        SetupDiDestroyDeviceInfoList(hDevInfoSet);
 
    return dwReturn;
}

Com essa implementação, teremos a seguinte saída.

Legal, mas não era bem isso...

Muito bem. As portas foram enumeradas, mas como eu passaria uma string dessas para a função CreateFile()? Terei que ficar interpretando essa string para pegar a parte "COM1" que está entre parênteses?

Na verdade existem meios de você obter o Symbolic Link dos dispositivos também utilizando funções da SetupAPI, mas eu imagino que o que você queria é o mesmo que eu quero. Preencher um Combo Box com o nome simples das portas seriais, como qualquer programa normal.

O port name, que é a string "COMx" que estamos procurando, está escrito como um valor de registro na chave do dispotivo. Todo driver de porta serial tem que ter esse valor conforme mostra esta página. Para obter a chave de registro referente ao dispositivo, utilizaremos uma outra rotina da SetupAPI. O fonte abaixo vai enumerar as portas seriais da maneira que estamos querendo.

/****
***     EnumSerialPorts
**
**      Rotina que enumera dispositivos que
**      implementam a interface de porta serial e
**      imprime um nome que não é camarada mas que
**      ainda servem para alguma coisa.
*/
 
DWORD EnumSerialPorts(void)
{
    CHAR                        szPortName[10];
    HDEVINFO                    hDevInfoSet = NULL;
    SP_DEVICE_INTERFACE_DATA    DevInterfaceData;
    SP_DEVINFO_DATA             DevInfoData;
    DWORD                       dwReturn,
                                dwSize,
                                dwInterfaceIndex = 0;
    HKEY                        hKey;
 
    try
    {
        //-f--> Reunindo informações sobre dispositivos que implementam
        //      a interface desejada que estejam presentes no
        //      momento em que esta rotina é chamada.

        hDevInfoSet = SetupDiGetClassDevs(&GUID_DEVINTERFACE_COMPORT,
                                          NULL,
                                          NULL,
                                          DIGCF_PRESENT | DIGCF_INTERFACEDEVICE);
 
        if (hDevInfoSet == INVALID_HANDLE_VALUE)
            throw GetLastError();
 
        DevInterfaceData.cbSize = sizeof(SP_DEVICE_INTERFACE_DATA);
 
        //-f--> Agora enumera cada uma das interfaces
        while (SetupDiEnumDeviceInterfaces(hDevInfoSet,
                                           0,
                                           &GUID_DEVINTERFACE_COMPORT,
                                           dwInterfaceIndex++,
                                           &DevInterfaceData))
        {
            DevInfoData.cbSize = sizeof(SP_DEVINFO_DATA);
 
            //-f--> Para cada uma das interfaces, obtemos o
            //      device que a implementa.
            if (SetupDiGetDeviceInterfaceDetail(hDevInfoSet,
                                                &DevInterfaceData,
                                                NULL,
                                                0,
                                                NULL,
                                                &DevInfoData))
                throw GetLastError();
 
            //-f--> Aqui obtemos a chave de registro do
            //      device que implementa a interface.
            hKey = SetupDiOpenDevRegKey(hDevInfoSet,
                                        &DevInfoData,
                                        DICS_FLAG_GLOBAL,
                                        0,
                                        DIREG_DEV,
                                        KEY_QUERY_VALUE);
 
            if (hKey == INVALID_HANDLE_VALUE)
                throw GetLastError();
 
            //-f--> Aqui obtemos o valor PortName do Registry
            dwSize = sizeof(szPortName);
            dwReturn = RegQueryValueEx(hKey,
                                       "PortName",
                                       NULL,
                                       NULL,
                                       (LPBYTE)szPortName,
                                       &dwSize);
            RegCloseKey(hKey);
 
            if (dwReturn != ERROR_SUCCESS)
                throw dwReturn;
 
            //-f--> Printf neles...
            printf("%d) %s\n",
                   dwInterfaceIndex,
                   szPortName);
        }
    }
    catch(DWORD dwError)
    {
        //-f--> Oops!
        printf("Error %d on trying enumerate device interfaces.\n",
               dwError);
 
        dwReturn = dwError;
    }
 
    //-f--> Libera as informações obtidas
    if (hDevInfoSet)
        SetupDiDestroyDeviceInfoList(hDevInfoSet);
 
    return dwReturn;
}

Agora sim...

Colocar isso num combo box já é assunto para um outro blog. Até que para um desenvolvedor de drivers, a janela abaixo não está tão ruim assim.

Até mais! ;-)

Download EnumSerialPort.zip

Lendo Arquivos

fernando@driverentry.com.br (Fernando Roberto da Silva) — Wed, 01 Apr 2009 17:28:00 +0000

Como vocês viram em meu último post, meu trabalho de graduação utilizará uma ferramenta chamada LabView para receber e tratar os dados de uma placa USB. Estes dados serão coletados de um dispositivo chamado giroscópio usando TTL 232, que é um RS 232 com tensões de 0 e 5 volts. Mas como uma prova de conceito, teríamos que fazer o driver simular a recepção de dados para enviar ao LabView. Utilizamos um circuito que transforma TTL 232 em RS 232 apenas para permitir que os dados pudessem ser lidos de uma porta serial convencional. Então fiz um programinha idiota que grava em um arquivo tudo que recebe pela porta serial. Como o firmware ainda não estava nem começado, resolvi fazer um driver que lesse esse arquivo e repassasse os dados para a camada de aplicação. Perguntas sobre como manipular arquivos são especialmente frequentes. Muitos leitores gostariam de saber como criar, ler, escrever e até mesmo apagar arquivos em Kernel Mode. Talvez eu possa desapontá-los um pouco ao dizer que não é assim tão diferente de User Mode, mas já que estamos aqui sem fazer nada, por que não demonstrar?

Acredito que a maior diferença esteja no passo onde obtemos o handle para o arquivo. Vamos começar dando uma olhada na rotina ZwCreateFile().

NTSTATUS  
  ZwCreateFile(
    OUT PHANDLE  FileHandle,
    IN ACCESS_MASK  DesiredAccess,
    IN POBJECT_ATTRIBUTES  ObjectAttributes,
    OUT PIO_STATUS_BLOCK  IoStatusBlock,
    IN PLARGE_INTEGER  AllocationSize  OPTIONAL,
    IN ULONG  FileAttributes,
    IN ULONG  ShareAccess,
    IN ULONG  CreateDisposition,
    IN ULONG  CreateOptions,
    IN PVOID  EaBuffer  OPTIONAL,
    IN ULONG  EaLength
    );

A parte interessante desse passo é que a rotina não tem o clássico parâmetro FileName que vimos na API equivalente CreateFile() para User Mode. O nome do arquivo é descrito na estrutura OBJECT_ATTRIBUTES descrita abaixo.

typedef struct _OBJECT_ATTRIBUTES {
    ULONG  Length;
    HANDLE  RootDirectory;
    PUNICODE_STRING  ObjectName;
    ULONG  Attributes;
    PVOID  SecurityDescriptor;
    PVOID  SecurityQualityOfService;
 
} OBJECT_ATTRIBUTES, *POBJECT_ATTRIBUTES;
 
typedef CONST OBJECT_ATTRIBUTES *PCOBJECT_ATTRIBUTES;

Para preencher esta estrutura utilizamos a macro InitializeObjectAttributes().

VOID 
  InitializeObjectAttributes(
    OUT POBJECT_ATTRIBUTES  InitializedAttributes,
    IN PUNICODE_STRING  ObjectName,
    IN ULONG  Attributes,
    IN HANDLE  RootDirectory,
    IN PSECURITY_DESCRIPTOR  SecurityDescriptor
    );

O caminho do arquivo é descrito no parâmetro ObjectName, que é um ponteiro para uma UNICODE_STRING. Em Kernel, o caminho completo para um arquivo seria descrito como "\Device\HarddiskVolume0\Diretorio\Arquivo.ext" por exemplo. Isso acontece porque a parte "C:", que normalmente utilizamos no caminho de arquivo em User Mode, é um Symbolic Link. Symbolic quem? Um Symbolic Link seria como um atalho para o nome em Kernel Mode. Aplicações em User Mode não podem abrir qualquer objeto do Kernel assim de cara. Então cada driver cria Symbolic Links para os objetos que desejam torná-los disponíveis para User Mode. Quando uma aplicação quer abrir o arquivo "C:\Temp\Test.txt", o sub-sistema Win32 prefixa este caminho com "\??\", que é o diretório inicial desta busca, resultando em "\??\C:\Temp\Test.txt". Quando este nome chega ao Object Manager, o prefixo indica que a busca deve iniciar no diretório "\DosDevices", o mesmo que utilizamos na chamada à API IoCreateSymbolicLink(). Enfim, pulando alguns detalhes para terminar esse post ainda nessa vida, o prefixo vai nos levar ao diretório "\GLOBAL??\". Depois que o prefixo "\??" foi processado, a próxima parte a ser processada é "C:". Utilizando a ferramenta WinObj da Systernals ilustrada na figura abaixo, vemos que aqui em minha máquina "C:" será substituído por "\Device\HarddiskVolume3", que neste caso é o caminho para o device que receberá o restante da string a ser processada. Depois de realizada esta substituição, a string agora é "\Device\HarddiskVolume3\Temp\Test.txt". O Object Manager agora recomeça a processar a string e encontra o device nela descrito.

Depois disso, sabendo que se trata de um device de volume de dados, o sistema consulta uma estrutura chamada Volume Parameter Block (VPB). Ela cria um link que vai nos informar se o volume indicado foi montado por algum driver de File System. No meu caso, o NTFS seria este driver. O device que ele criou faria o restante do tratamento da string para encontrar o arquivo desejado. Você não vai ter que percorrer todo esse caminho para abrir o arquivo. Basta colocar o prefixo "\??\" no caminho do arquivo que desejar abrir e todos os seus problemas se acabaram-se. Se você quiser mais detalhes sobre as traduções de nomes que ocorrem durante a abertura de um arquivo, este artigo da OSR Online é ótimo. Este é o link para a referência que fala sobre isso.

Depois de aberto, ler o arquivo fica fácil com a rotina ZwReadFile().

NTSTATUS 
  ZwReadFile(
    IN HANDLE  FileHandle,
    IN HANDLE  Event  OPTIONAL,
    IN PIO_APC_ROUTINE  ApcRoutine  OPTIONAL,
    IN PVOID  ApcContext  OPTIONAL,
    OUT PIO_STATUS_BLOCK  IoStatusBlock,
    OUT PVOID  Buffer,
    IN ULONG  Length,
    IN PLARGE_INTEGER  ByteOffset  OPTIONAL,
    IN PULONG  Key  OPTIONAL
    );

Os passos necessários para se abrir e ler um arquivo podem ser resumidos neste pequeno exemplo a seguir.

/****
***     ReadTestFile
**
**      Rotina que demostra de maneira simples como abrir e
**      ler um arquivo.
*/
 
NTSTATUS ReadTestFile(PVOID     pBuffer,
                      ULONG     cbBuffer,
                      PULONG    pulBytesRead)
{
    UNICODE_STRING      usFileName;
    OBJECT_ATTRIBUTES   ObjAttributes;
    IO_STATUS_BLOCK     IoStatusBlock;
    HANDLE              hFile = NULL;
    NTSTATUS            nts = STATUS_SUCCESS;
 
    //-f--> Montamos o UNICODE_STRING contendo o caminho
    //      do arquivo que desejamos abrir
    RtlInitUnicodeString(&usFileName,
                         L"\\??\\C:\\Temp\\Test.txt");
 
    //-f--> Aqui a macro nos ajuda com a estrutura
    //      OBJECT_ATTRIBUTES
    InitializeObjectAttributes(&ObjAttributes,
                               &usFileName,
                               OBJ_KERNEL_HANDLE | OBJ_CASE_INSENSITIVE,
                               NULL,
                               NULL);
 
    //-f--> Aqui abrimos o arquivo.
    nts = ZwCreateFile(&hFile,
                       GENERIC_READ | SYNCHRONIZE,
                       &ObjAttributes,
                       &IoStatusBlock,
                       NULL,
                       FILE_ATTRIBUTE_NORMAL,
                       FILE_SHARE_READ,
                       FILE_OPEN,
                       FILE_SYNCHRONOUS_IO_NONALERT,
                       NULL,
                       0);
 
    //-f--> Retorna o erro em caso de falha.
    if (!NT_SUCCESS(nts))
        return nts;
 
    //-f--> Uma simples leitura no arquivo.
    nts = ZwReadFile(hFile,
                     NULL,
                     NULL,
                     NULL,
                     &IoStatusBlock,
                     Buffer,
                     cbBuffer,
                     NULL,
                     NULL);
 
    //-f--> Em caso de falha, fecha o arquivo, retorna o
    //      erro e finge que não é com você.
    if (!NT_SUCCESS(nts))
    {
        ZwClose(hFile);
        return nts;
    }
 
    //-f--> Aqui obtemos a quantidade de bytes lidos
    *pulBytesRead = IoStatusBlock.Information;
 
    //-f--> Fecha o handle do arquivo
    ZwClose(hFile);
    return nts;
}

A prova de conceito

Agora que todos nós sabemos como ler um arquivo, fica mais fácil de explicar como fiz um driver que simularia as leituras de um giroscópio apenas lendo o conteúdo de um arquivo. Durante a existência deste blog, já vimos como criar um projetinho do zero, como compilar drivers utilizando o Visual Studio, já vimos também o que é uma IRP, como oferecer serviços de leitura e escrita, como utilizar o FsContext para manter o contexto entre diferentes operações, e como debug é parte do desenvolvimento, também vimos como depurar drivers mesmo em uma máquina virtual. Vamos utilizar toda essa tranqueirada para montar um driver que abra um arquivo, armazene seu handle em uma área de contexto, e que conforme realizamos leituras ao device criado e exportado por ele, este retorne os dados de um arquivo em disco. Isso vai servir direitinho para simular leituras contínuas que o LabView fará ao meu driver USB.

Abrindo o Device e Arquivo

O driver receberá uma chamada de IRP_MJ_CREATE quando um handle para o device for aberto. Vou aproveitar esse evento para já abrir o arquivo e guardar seu handle resultante no FsContext do FILE_OBJECT que receberei. Se você está boiando, dê uma olhada nos posts indicados anteriormente.

E se o arquivo não existir?

Bom, caso tais eventos infelizes ocorram, vou retornar o erro pela própria IRP recebida. Assim, caso o arquivo não exista ou você não tenha permissão para abri-lo, o código de erro poderá ser verificado através da rotina GetLastError() caso obtivermos INVALID_HANDLE_VALUE como retorno da abertura do handle do device.

Dêem uma olhada como ficou a abertura do handle do device, que na mesma operação, abre o handle para o arquivo. Atenção, não misture as coisas. A aplicação vai obter o handle para o device, e através dele, fará leituras ao device. O device por sua vez utilizará o handle do arquivo para fazer leituras e retornar os dados à aplicação.

/****
***     OnCreate
**
**      A aplicação está chamado CreateFile com o path
**      do nosso device.
*/
 
NTSTATUS OnCreate(PDEVICE_OBJECT    pDeviceObj,
                  PIRP              pIrp)
{
    UNICODE_STRING      usFileName;
    OBJECT_ATTRIBUTES   ObjAttributes;
    IO_STATUS_BLOCK     IoStatusBlock;
    PIO_STACK_LOCATION  pStack;
    NTSTATUS            nts = STATUS_SUCCESS;
    HANDLE              hFile = NULL;
 
    //-f--> Montamos o UNICODE_STRING contendo o caminho
    //      do arquivo que desejamos abrir
    RtlInitUnicodeString(&usFileName,
                         L"\\??\\C:\\Temp\\Test.txt");
 
    //-f--> Aqui a macro nos ajuda com a estrutura
    //      OBJECT_ATTRIBUTES
    InitializeObjectAttributes(&ObjAttributes,
                               &usFileName,
                               OBJ_KERNEL_HANDLE | OBJ_CASE_INSENSITIVE,
                               NULL,
                               NULL);
 
    //-f--> Aqui abrimos o arquivo. Como vamos repassar qualquer
    //      erro para a aplicação, então podemos utilizar a estrutura
    //      IO_STATUS_BLOCK da nossa IRP. Caso contrário poderiamos
    //      utilizar uma criada como variavel local.
    nts = ZwCreateFile(&hFile,
                       GENERIC_READ | SYNCHRONIZE,
                       &ObjAttributes,
                       &pIrp->IoStatus,
                       NULL,
                       FILE_ATTRIBUTE_NORMAL,
                       FILE_SHARE_READ,
                       FILE_OPEN,
                       FILE_SYNCHRONOUS_IO_NONALERT,
                       NULL,
                       0);
 
    //-f--> Vamos guardar o handle do arquivo em nossa área de
    //      contexto. Isso permite que várias aplicações de teste
    //      possam ser executas ao mesmo tempo. Para isso teremos
    //      obter a Stack Location atual.
    pStack = IoGetCurrentIrpStackLocation(pIrp);
    pStack->FileObject->FsContext = (PVOID)hFile;
 
    //-f--> Agora é só ler o arquivo, mas vamos fazer isso na IRP
    //      de leitura, só pra...
    IoCompleteRequest(pIrp,
                      IO_NO_INCREMENT);
    return nts;
}

Repare que a API ZwCreateFile() pede um ponteiro para IO_STATUS_BLOCK. Utilizei a mesma estrutura que está contida na IRP que recebemos. Assim eu não tenho que repassar o status de uma operação para a outra. A aplicação continua obtendo o handle para o device da mesma maneira como sempre foi feito, mas lembre-se que se houver uma falha nessa obtenção, o erro pode ter sido gerado por um problema ao abrir o handle do arquivo. Confira como a aplicação vai utilizar o driver.

/****
***     main
**
**      Ponto de entrada da aplicação
**
*/
 
int __cdecl main(int argc,
                 char* argv[])
{
    char    szBuffer[4096];
    HANDLE  hDevice = NULL;
    DWORD   dwError = ERROR_SUCCESS,
            dwBytes,
            i;
 
    //-f--> Obtendo um handle para o device
    printf("Opening the device \"\\\\.\\FileReader\"...\n");
 
    hDevice = CreateFile("\\\\.\\FileReader",
                         GENERIC_ALL,
                         0,
                         NULL,
                         OPEN_EXISTING,
                         0,
                         NULL);
 
    //-f--> Verifica se o handle foi aberto.
    if (hDevice == INVALID_HANDLE_VALUE)
    {
        //-f--> Ops!
        dwError = GetLastError();
        printf("Error #%d opening device...\n",
               dwError);
        return dwError;
    }
 
    //-f--> Realiza as leituras no device
    while (ReadFile(hDevice,
                    szBuffer,
                    sizeof(szBuffer),
                    &dwBytes,
                    NULL))
    {
        //-f--> Exibe dados na tela
        //      Tá tá, eu sei que não é a maneira mais eficiente do mundo.
        for (i = 0; i < dwBytes; i++)
            printf("%c", szBuffer[i]);
    }
 
    //-f--> Qualquer falha da chamada à função ZwReadFile é repassada para
    //      a estrutura IO_STATUS_BLOCK da IRP. Por isso é que vemos este
    //      erro aqui.
    if ((dwError = GetLastError()) != ERROR_NO_MORE_ITEMS)
        printf("\n\n Error #%d reading device...\n");
 
    //-f--> Põe a casa em ordem.
    printf("Closing device...\n");
    CloseHandle(hDevice);
 
    //-f--> Fim de festa! Chega!
    return dwError;
}

Lendo o Device e o Arquivo

Faremos a leitura do arquivo de forma similar à abertura. Vamos obter o handle do arquivo a partir do FsContext. Este ponteiro foi originalmente disponibilizado para que o driver pudesse armazenar nele o endereço de uma estrutura definida pelo desenvolvedor. Este ponteiro sempre será o mesmo para todas as operações que utilizam o mesmo FILE_OBJECT até que a operação de IRP_MJ_CLOSE seja chamada. Como um handle é algo muito pequeno, podemos gravar seu valor ao invés de um ponteiro para uma estrutura alocada em memória que contenha o valor do handle.

Aqui também vamos utilizar a repassagem da estrutura IO_STATUS_BLOCK para transferir o status da operação de leitura do arquivo para a aplicação.

/****
***     OnRead
**
**      Rotina que realiza leitura do arquivo já
**      aberto.
*/
 
NTSTATUS OnRead(PDEVICE_OBJECT    pDeviceObj,
                PIRP              pIrp)
{
    NTSTATUS            nts = STATUS_SUCCESS;
    PIO_STACK_LOCATION  pStack;
    HANDLE              hFile;
 
    //-f--> Obtemos a stack location atual
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> Aqui recuperamos o handle do arquivo.
    ASSERT(pStack->FileObject->FsContext != NULL);
    hFile = (HANDLE)pStack->FileObject->FsContext;
 
    //-f--> Uma simples leitura no arquivo.
    nts = ZwReadFile(hFile,
                     NULL,
                     NULL,
                     NULL,
                     &pIrp->IoStatus,
                     pIrp->AssociatedIrp.SystemBuffer,
                     pStack->Parameters.Read.Length,
                     NULL,
                     NULL);
 
    //-f--> STATUS_END_OF_FILE não é repassado para a camada aplicação
    //      como uma falha de leitura, então vamos usar um erro mais
    //      fácil de detectar.
    if (pIrp->IoStatus.Status == STATUS_END_OF_FILE)
        nts = pIrp->IoStatus.Status = STATUS_NO_MORE_ENTRIES;
 
    //-f--> Completa a IRP.
    IoCompleteRequest(pIrp,
                      IO_NO_INCREMENT);
    return nts;
}

Se nosso driver retornar STATUS_END_OF_FILE para a aplicação, a API ReadFile() não sinalizará uma falha, mas apenas informará que zero bytes foram lidos. Para facilitar a detecção do fim de arquivo lá na aplicação, vou retornar um código de erro diferente, assim a rotina ReadFile() retornará FALSE e o loop de leitura será interrompido.

Fechando o handle do Device e do Arquivo

Agora fica muito fácil. Vamos fechar o handle do arquivo quando o handle do device for fechado. Sem muitas novidades por aqui.

/****
***     OnCleanup
**
**      O handle para nosso device foi fechado. Vamos
**      aproveitar e fechar o handle do arquivo também.
*/
 
NTSTATUS OnCleanup(PDEVICE_OBJECT    pDeviceObj,
                   PIRP              pIrp)
{
    PIO_STACK_LOCATION  pStack;
    HANDLE              hFile;
 
    //-f--> Obtemos a stack location atual
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> Aqui recuperamos o handle do arquivo.
    ASSERT(pStack->FileObject->FsContext != NULL);
    hFile = (HANDLE)pStack->FileObject->FsContext;
 
    //-f--> Fecha o handle
    ZwClose(hFile);
 
    //-f--> Completa a IRP normalmente
    pIrp->IoStatus.Status = STATUS_SUCCESS;
    pIrp->IoStatus.Information = 0;
    IoCompleteRequest(pIrp,
                      IO_NO_INCREMENT);
 
    return STATUS_SUCCESS;
}

Se vocês já são leitores deste blog há algum tempo, verão que o restante do driver contém código elementar e que já foi comentado em outros posts. De qualquer forma, tanto o fonte do driver quando o fonte da aplicação de teste estão disponíveis para download. Caso vocês tenham alguma dúvida é só mandar um e-mail. Normalmente eu digo que vocês só precisarão torcer para eu saber a resposta, mas ultimamente vocês terão que torcer para eu também ter tempo de responder.

Como sempre, espero ter ajudado.
Have fun!

Download FileReader.zip

110% de CPU

fernando@driverentry.com.br (Fernando Roberto da Silva) — Fri, 20 Mar 2009 03:54:00 +0000

Eu não queria postar algo que começasse com choradeiras dizendo que estou sem tempo, que tive que buscar minha tia no aeroporto e coisa e tal, mas estou vendo que não vai ter jeito. Até comecei a escrever uns posts para tirar dúvidas de leitores, mas aí eles começam a tomar tempo quando tenho que montar um exemplo, fazer uma figura, etc. Por fim, já tenho dois posts começados, mas que foram abandonados durante sua concepção por falta de tempo. Tenho recebido alguns e-mails do tipo "Você ainda está vivo por aí?" de alguns leitores. As coisas estão realmente complicadas para mim esse ano, mas não vou deixar de postar. Só estou precisando arrumar um tempinho pra sentar. Já tentei escrever posts enquanto almoçava ou tomava banho, mas não deu muito certo. De fato eu consegui escrever um post enquanto dormia, mas quando acordei, por algum motivo, o post não estava publicado. Nota: "Reclamar com o pessoal do blogger". Mas enfm, na falta de tempo suficiente para escrever algo que os ajudem a desenvolver algo, neste post vou apenas relatar o que tenho feito. De repente vocês precisem de algo parecido e queiram me pedir alguma ajuda ou referência.

O Último Ano...

Parece mentira, mas este é meu último ano da minha graduação em Engenharia da Computação, e por ser o último ano, três agravantes aparecem para disputar meu tempo (como se eu tivesse algum), sendo eles: Dependências, Trabalho de graduação (TG) e o Estágio.

As Dependências...

Para quem não lembra ou não sabe o que são dependências, são matérias as quais você não conseguiu ser aprovado no ano em que você estudou, mas consegue passar de ano mesmo assim, só que você terá que estudar estas matérias em separado, seja de sábado ou num horário em que você tenha livre (dá até vontade de rir...). Enfim, cheguei ao sexto ano com três matérias para fazer em meu horário livre. Assim, parte do meu sábado foi e será dedicado a essa atividade. Para fazer uma dependência, é necessário que a universidade agrupe alunos com a mesma matéria para fechar uma turma. Duas das três dependências já formaram turmas, mas ainda preciso rezar para que a terceira turma se forme. Dessa forma eu poderei me matricular. Caso contrário, terei que vir para universidade mais um ano para estudar a matéria restante. Isola...(Toc, toc, toc) vai dar tudo certo.

O Estágio...

Em paralelo à essa aventura de estudar três matérias adicionais e ainda ter que passar em tudo, terei que fazer o estágio. Estágio é uma das matérias que preciso fazer para me formar. Terei que cumprir 192 horas de estágio para passar nesta matéria. Felizmente, meu curso pode ter o estágio tanto com ênfase eu software como em hardware, já que a Engenharia da Computação desenvolve as duas especialidades no estudante.

Mas Fernando, se me lembro bem, você trabalha na IBM e seu estágio pode sair sem que você tenha que mover um único músculo. Basta alguém assinar seu estágio e pronto.

Pois é, acho que tenho sérias tendências para querer me enrolar. É como meu amigo Heldai me disse uma vez: "Ê seu Fêrnando, o senhor é como eu. Não pode ver uma corda que já quer enrolar no pescoço". O fato é que eu gostaria imensamente de desenvolver meu lado mais fraco, e sabendo que já brinco de fazer telas azuis há um tempo razoável, meu objetivo seria arrumar um estágio em hardware. Mas como isso seria possível se já trabalho numa empresa de software durante a semana?

Bom, há um ano atrás, eu dei um curso de desenvolvimento de drivers para Windows em uma empresa que projeta hardware. Uma empresa dessa não se acha assim em qualquer esquina. A Commodity é uma empresa que desenvolve um hardware que faz interface USB, cujo firmware é escrito em linguagem C e roda num chip da Freescale, e como se não fosse o bastante, o hardware ainda faz compressão de audio utilizando um chip da Altera com FPGA. Quem entende de eletrônica sabe que este seria um excelente lugar para fazer estágio e aprender muito. O problema é que eu não poderia fazer o estágio de domingo, que é meu único dia disponível, já que tenho aulas aos sábados e trabalho durante toda a semana. Já que não posso fazer o estágio de domingo, então posso trabalhar de domingo. Mais uma grande vantagem de se fazer Home Office. A solução foi me oferecer para fazer o estágio que seria cumprido apenas de segunda-feira. Estes dias seriam compensados trabalhando de domingo. Pedi autorização para meus gerentes do Brasil e dos Estados Unidos e pronto. Sabendo que um estagiário que aparece uma vez por semana mais atrapalha que ajuda, facilitei minha entrada na empresa solicitando um estágio não remunerado. Como eles já me conheciam, ficou fácil.

Apesar de eu não receber nem um centavo e ainda pagar minha gasolina e refeição, tenho certeza de que fiz a escolha certa. Meu estágio começou há duas semanas e tenho tido contato com coisas bem interessantes. Para dar uma acelerada no acúmulo de horas, trabalharei no estágio durantes todos os dias da semana enquanto eu estiver de férias da IBM. Juntando tudo, meu estágio terminará no início de agosto.

O TG...

Bom, eu já não tinha os sábados e agora não tenho mais os domingos. Só preciso dar um jeito que acabar com qualquer fragmento de tempo livre que eu puder encontrar. Para isso, a universidade nos abençoou com o trabalho de graduação. Nós teremos que montar um projeto que utilize as especialidades que vimos durante o curso de engenharia da computação. Como meta pessoal, não importa o que o projeto faça, terá que haver um driver. Afinal de contas é a única coisa que sei fazer direito. Não posso perder essa oportunidade. Nosso projeto tem como objetivo estabilizar um helimodelo em vôo.

Ah tá, e onde o driver entra na história mesmo?

Para resumir muito (mas muito mesmo), faremos leituras de um giroscópio embarcado num helimodelo à distância utilizando o protocolo ZigBee. Tais leituras serão realizadas por um kit de desenvolvimento com microcontrolador que fará interface USB com um computador. O driver encaminhará as leituras de movimentos para uma ferramenta chamada LabView. Em resposta à percepção dos movimentos, o sistema reagirá enviando comandos via USB para a placa. A mesma placa fará interface com o rádio controle do helimodelo a fim de corrigir o curso.

Em linhas gerais é isso que faremos. Eu poderia escrever muito à respeito de como estamos fazendo isso. Começamos a trabalhar no projeto no ano passado por que já sabíamos que não seria nada fácil. Aproveitei uma das minhas idas para os Estados Unidos para comprar os sensores e kits necessários. O importante é que o projeto está indo bem até aqui, mas ainda vamos apanhar muito. Estou escrevendo o firmware do microcontrolador e obviamente o driver que fará interface com ele, mas nosso principal desafio será fechar a malha de controle e fazer o helimodelo ficar parado no ar.

Parado? Você não tem vergonha de dizer que está fazendo tudo isso para fazer um helimodelo ficar parado?

Nosso sonho dourado é definir dois pontos distintos e fazer o trajeto completo com decolagem, delsocamento e pouso, mas quem é helimodelista como eu sabe que fazer um helimodelo ficar parado é um excelente primeiro passo. Nosso orientador já nos disse que nosso projeto é o mais desafiador das engenharias e que se nós fizéssemos apenas a parte da leitura à distância já seria um bom trabalho de graduação.

Eu escreveria muito mais sobre o projeto, mas isso vai ficar para depois. Este post já está ficando longo para mais um Off-Topic. Meus agradecimentos à prefeitura municipal de São Paulo por ter criado o rodízio municipal de veículos, e por consequência, ter me trazido para a faculdade com duas horas de antecedência. Isso me deu a oportunidade de começar este post. Agora são 01:45 da manhã e ainda tenho que revisar e publicar esse post.

Vou tentar escrever mais. Talvêz minhas aventuras com o TG ou com o estágio me tragam assuntos interessantes e curtos o suficiente para publicar aqui.

Até mais mais. :-)

Gerenciando paginação do driver

fernando@driverentry.com.br (Fernando Roberto da Silva) — Tue, 18 Nov 2008 17:20:00 +0000

Depois de tanto falar sobre memória virtual e paginação, recebi uma pergunta que coincidentemente tem tudo a ver com o assunto dos últimos posts. "Para que servem os pragma alloc_text que vemos nos exemplos do WDK?" (Thiago Cardoso, Recife-PE). Essa pergunta já deve ter passado pela cabeça de muitos que já deram uma olhada nos exemplos do WDK. Visto que todos os exemplos do WDK que conheço utilizam este pragma, até que demorou para alguém perguntar sobre isso. Mas enfim, vamos ao que interessa.

Como já vimos, páginas de memória podem estar tanto nos chips de RAM como em disco. Também já vimos que threads que estão em alta prioridade de execução não podem acessar dados que são pagináveis. Mas como saberiamos quais dados são pagináveis ou não?

Controlando Paginação de Dados

Quando alocamos memória dinamicamente, podemos escolher se a área de memória a ser alocada será paginável ou não. A função ExAllocatePool, e suas irmãs (ExAllocatePoolWithTag, ExAllocatePoolWithQuota, ExAllocatePoolWithQuotaTag e ExAllocatePoolWithTagPriority), recebem um parâmetro do tipo POOL_TYPE que define se a memória a ser alocada será paginável ou não.

typedef enum _POOL_TYPE {
  NonPagedPool,
  PagedPool,
  NonPagedPoolMustSucceed,
  DontUseThisType,
  NonPagedPoolCacheAligned,
  PagedPoolCacheAligned,
  NonPagedPoolCacheAlignedMustS
} POOL_TYPE;
 
 
PVOID 
  ExAllocatePool(
    IN POOL_TYPE  PoolType,
    IN SIZE_T  NumberOfBytes
    );

Você terá que gerenciar quais alocações serão acessadas por diferentes prioridades de execução. Por exemplo: Uma determinada lista ligada é consultada apenas por funções que rodam somente em IRQL baixa, logo, todos os seus elementos podem ser alocados em memória paginável (PagedPool). Por outro lado, uma lista ligada que é consultada por funções que rodam em IRQLs altas, deve ter seus elementos alocados em memória não paginável (NonPagedPool).

Legal Fernando, mas nem tudo é alocado dinamicamente. Como ficam as variáveis estáticas?

Por padrão, todas as variáveis globais são não pagináveis. Isso é ruim se seu driver possui muitas variáveis globais, o que exigiria mais memória não paginável para que seu driver pudesse ser carregado, e como também já foi visto, memória não paginável deve ser poupada. Felizmente, podemos definir que um conjunto de variáveis globais possa ser paginável, desde que estas sejam apenas acessadas por threads em baixa IRQL.

Dentro de um módulo, seja uma aplicação, uma DLL ou mesmo um driver, o controle de paginação da memória é aplicado nas sessões que os compõem. Para que um grupo de variáveis seja definido em uma sessão paginável, podemos utilizar o pragma data_seg. Porém, não é todo compilador que nos permite fazer isso. Para saber se o compilador que estamos utilizando suporta o uso deste pragma, contamos com os headers do WDK, que definem o símbolo ALLOC_DATA_PRAGMA quando o compilador oferece suporte a este recurso. Isso, obviamente, tem se tornado menos significante, já que o aconselhável é utilizar o compilador do próprio WDK, mas não custa nada prever que seu código possa ser compilado por algum outro compilador. Veja o exemplo abaixo que define tanto variáveis não pagináveis como pagináveis.

//-f--> Estas são variáveis definidas em uma sessão não paginável
PDEVICE_OBJECT  g_pControlDeviceObj;
PDRIVER_OBJECT  g_pDriverObj;
 
//-f--> Aqui eu verifico se o compilador que estou utilizando
//      suporta o uso do #pragma data_seg.
//      Se sim, eu abro a sessão PAGEDATA que é uma sessão de
//      dados paginável.
#ifdef ALLOC_DATA_PRAGMA
    #pragma data_seg("PAGEDATA")
#endif
 
//-f--> Todas as variáveis declaradas aqui serão pagináveis.
//      Assim, apenas threads que rodam em baixo nível de
//      prioridades poderão acessar tais variáveis
 
//-f--> Definimos um buffer gigante. Ainda bem que é paginável
UCHAR   g_Buffer[100000];
 
//-f--> Aqui marcamos o fim da sessão paginável. As variáveis
//      definidas após este #pragma serão não pagináveis.
#ifdef ALLOC_DATA_PRAGMA
    #pragma data_seg()
#endif

Controlando Paginação de Código

Memória é memória, seja para armazenar dados ou código. Podemos também controlar onde as funções que você escreve serão definidas. Assim, podemos colocar todas as funções que executam em baixa prioridade em sessões de código pagináveis. Aqui usaremos o pragma que originou a dúvida do Thiago, o pragma alloc_text.

Este pragma tem duas limitações. A primeira delas é que o pragma deve ser aplicado depois da declaração da função, mas antes da definição da mesma. A outra é que este pragma não é aplicável em funções C++, ou seja, métodos de classes ou funções com sobrecargas não terão esse luxo de ser pagináveis. Se você é como eu, que prefere utilizar a tipagem forte do C++ em drivers, mesmo que você só escreva simples funções, você deverá utilizar o modificador extern "C" nas declarações das funções.

Esse pragma não é obrigatoriamente suportado por todos os compiladores, e assim como o data_seg, os headers do WDK definem o símbolo ALLOC_PRAGMA para sinalizar que o compilador utilizado suporta esse recurso. Segue mais um exemplo.

//-f--> Normalmente esta declaração é feita em um arquivo de
//      header. Observe que se estivermos compilando em C++,
//      teremos que usar o extern "C" para poder definir a
//      sessão onde as funções aqui declaradas serão definidas.
#ifdef __cplusplus
extern "C"
{
#endif
    //-f--> Declara uma
    ULONG SumOne(IN ULONG ulParam);
 
    //-f--> Declara outra
    ULONG SumTwo(IN ULONG ulParam);
 
#ifdef __cplusplus
}
#endif
 
 
//-f--> A parte a seguir fica no mesmo módulo onde a função é
//      definida, e deve ficar antes da definição da função.
//      Repare que aqui testamos se este pragma é suportado, e
//      se sim, cada função deve receber seu pragma alloc_text
#ifdef ALLOC_PRAGMA
    #pragma alloc_text(PAGE, SumOne);
    #pragma alloc_text(PAGE, SumTwo);
#endif
 
 
//-f--> Depois disso, podemos definir as funções normalmente
 
ULONG SumOne(IN ULONG ulParam);
{
    //--f-> Função SumOne que foi escrita por alguém.
 
    //-f--> Esse comentário só tem graça em Inglês.
    //
    //      Function SumOne that has been written by someone
 
    PAGED_CODE();
 
    return ulParam + 1;
}
 
ULONG SumTwo(IN ULONG ulParam);
{
    //-f--> Função desgraçada. (que não tem graça nenhuma)
    PAGED_CODE();
 
    return SumOne(SomeOne(ulParam));
}

Fernando, para quê servem estas macros PAGED_CODE que você usou no exemplo?

Bom, lá vem histórinha. Uma coisa desconfortável é que problemas com paginação de memória vão ocorrer apenas quando a página que você está acessando estiver em disco. Isso significa que você pode escrever um driver com problema, testá-lo, e se por "sorte", as páginas estiverem todas em RAM durante o teste, você não verá nenhum problema. Uma das coisas que ajuda bastante é essa macro PAGED_CODE. Em Checked Build, esta macro é traduzida para uma função que irá verificar se a prioridade corrente é baixa suficiente para executar código paginável. Caso não seja, uma exceção de breakpoint será lançada. Espero que você esteja com o depurador atachado para ver isso acontecer. Caso contrário, não se preocupe, uma linda tela azul irá aparecer e você vai acabar conectando o depurador mais cedo ou mais tarde. Quando compilado em Free Build, essa macro é traduzida para nada, evitando perda de performance. Concluindo, isso evita de você chamar uma função paginável em IRQL alta e tudo funcionar por "sorte".

...
 
#elif DBG
 
#define PAGED_CODE() {                                                       \
    if (KeGetCurrentIrql() > APC_LEVEL) {                                    \
        KdPrint(("EX: Pageable code called at IRQL %d\n", KeGetCurrentIrql())); \
        NT_ASSERT(FALSE);                                                    \
    }                                                                        \
}
 
...
 
#else
 
#define PAGED_CODE()        NOP_FUNCTION;
 
...
 
#endif

Uma excelente maneira de pegar problemas de paginação de cógido é utilizar o Driver Verifier com a opção de Force IRQL Checking habilitada. Esta opção, além de verificar se você está chamando as funções da API nas prioridades corretas, também força a paginação de tudo que seja paginável em seu driver toda vez que a IRQL subir para DISPATCH_LEVEL ou superior. Isso acaba com aquela "sorte" de utilizar um recurso paginável em IRQL alta quando o recurso já estiver em RAM.

Sessão Descartável

Além da sessão de código paginável PAGE que vimos, uma outra sessão também é vista com grande frequência nos exemplos do WDK. A sessão INIT é descartada quando a chamada à função DriverEntry do seu driver retornar ao sistema, e se for o caso do seu driver, depois que qualquer função de reinicialização for terminada. Se você não sabe o que é uma função de reinicialização, então dê uma passada por este post. Assim, se você tem funções que são somente utilizadas durante a inicialização do seu driver (que neste caso significa: funções chamadas pela DriverEntry, ou funções chamadas por funções que foram chamadas pela DriverEntry, ou ainda funções chamadas por funções que foram chamadas por funções... Ah! Eu acho que você entendeu), vocé pode utilizar o mesmo procedimento para defini-las na sessão INIT da mesma maneira como foi feito anteriormente. Mas não custa deixar um exemplo.

//-f--> As funções aqui declaradas serão removidas da RAM quando
//      a chamada à função DriverEntry retornar. Não tente chamá-las
//      depois disso, porque estas já foram para o céu das funções
//      de inicialização.
 
#ifdef ALLOC_PRAGMA
    #pragma alloc_text(INIT, DriverEntry);
    #pragma alloc_text(INIT, FunctionCalledByDriverEntry);
    #pragma alloc_text(INIT, AnotherFunctionCalledByDriverEntry);
 
    #pragma alloc_text(PAGE, SumOne);
    #pragma alloc_text(PAGE, SumTwo);
#endif

Isso é especialmente útil em Legacy Drivers, que realizam muitos passos na inicialização. Legacy drivers, além de procurar o hardware que vão controlar, ainda precisam fazer a associação dos recursos disponíveis (portas, interrupções, canais de DMA e etc), e isso acaba consumido uma quantidade expressiva de código. Por outro lado, drivers de WDM recebem tudo mastigadinho do Plug-and-Play Manager. O hardware foi detectado e a associação de recursos já foi negociada. Coisa linda de Deus!

Paginável ou não paginável, eis a questão

Supondo que você tenha muitas funções que rodem em IRQL alta, e que por isso, devem estar em memória não paginável, isso faria com que uma grande quantidade de memória não paginável seja utilizada para manter tais funções, mesmo que ninguém esteja utilizando o driver. Também podemos definir nossas próprias sessões e assim torná-las pagináveis ou não pagináveis quando nos for conveniente. Isso permitiria que todas aquelas funções não pagináveis sejam pagináveis enquanto ninguém obtiver uma referência para nosso driver. Desta forma, quando recebermos um IRP_MJ_CREATE ou quando programarmos o hardware para disparar interrupções, podemos dizer ao sistema que agora precisaremos tornar a sessão onde tais funções foram definidas como não paginável.

Primeiro de tudo, teremos que criar nossas sessões do coração, e faremos isso utilizando o pragma alloc_text para definir sessões que devem ter seu nome no formato com PAGExxxx, onde xxxx seja um nome único no seu driver. Veja o exemplinho de desencargo de consciência.

//-f--> As funções aqui declaradas serão definidas em uma sessão
//      que pode ser não paginável quando nos for conveniente.
 
#ifdef ALLOC_PRAGMA
    #pragma alloc_text(PAGEABCD, FunctionOne);
    #pragma alloc_text(PAGEABCD, FunctionTwo);
#endif
 
 
//-f--> As funções aqui declaradas serão definidas em uma outra 
//      sessão que pode ser não paginável. Assim podemos definir
//      diferentes grupos de funções em diferentes sessões.
 
#ifdef ALLOC_PRAGMA
    #pragma alloc_text(PAGE1234, FunctionThree);
    #pragma alloc_text(PAGE1234, FunctionFour);
#endif

Agora que já definimos quais funções estarão definidas nessa sessão, podemos torná-la não paginável somente quando tais funções forem utilizadas. Para tal devemos utilizar a função MmLockPagableCodeSection.

 
PVOID 
  MmLockPagableCodeSection(
    IN PVOID  AddressWithinSection
    );

Para identificar qual sessão será marcada como não paginável, teremos que passar um endereço que esteja dentro da sessão. Um nome de função definida na sessão já resolve o problema, mas lembre-se que todas as funções dentro da mesma sessão serão marcadas como não paginável.

A função MmLockPagableCodeSection nos retorna um endereço opaco que pode ser utilizado como parâmetro para a chamada à função MmUnlockPagableImageSection, que marca a sessão novamente como paginável. Essa função é normalmente chamada antes do driver ser descarregado. Seguindo a linha do nosso exemplo, poderiamos chamar esta função ao receber um IRP_MJ_CLOSE. O mesmo endereço retornado por MmLockPagableCodeSection pode ser utilizado como parâmetro às chamadas à função MmLockPagableSectionByHandle para novamente tornar uma sessão não paginável, o que é muito mais rápido que a chamada à MmLockPagableCodeSection. Assim, devemos chamar MmLockPagableCodeSection pelo menos uma vez para obter o ponteiro opaco, e depois disso, podemos chamar MmLockPagableSectionByHandle e MmUnlockPagableImageSection.

VOID 
  MmLockPagableSectionByHandle(
    IN PVOID  ImageSectionHandle
    );
 
VOID 
  MmUnlockPagableImageSection(
    IN PVOID  ImageSectionHandle
    );

O mesmo pode ser feito em sessões customizadas que definem dados, mas devemos utilizar a função MmLockPagableDataSection para obter o ponteiro opaco que identifica a sessão.

Minha função pode ser paginável?

Fernando, se minha função é chamada em PASSIVE_LEVEL, então ela pode ser paginável?

Não é bem assim. Sua função, mesmo sendo chamada em PASSIVE_LEVEL, pode conter intervalos de código que precisam ser não pagináveis. Se você chamar funções que elevam a IRQL, tais como KeAcquireSpinLock, sua função não pode ser definida em sessão paginável.

Mas Fernando, acompanhe o meu raciocínio. Se a função foi chamada e está em execução no momento, não é obvio que a página à qual ela está contida está em RAM?

Você pode até não acreditar, mas uma função é composta por uma cadeia de bytes que podem estar nas fronteiras de páginas. Isso significa que o inicio da sua função pode estar no final de uma página, que de fato foi paginada para RAM quando a chamada foi feita, mas não sabemos onde uma nova página pode começar. Esta nova página pode estar em disco, e se for acessada em IRQL alta, a paginação causará uma tela azul. Veja o código abaixo para ter uma idéia do que estou falando e não esqueça de ler os comentários.

/****
***     FunctionCalledAtPassiveLevel
**
**      Rotina que é chamada em PASSIVE_LEVEL,
**      mas tem elevação de IRQL durante a chamada.
*/
 
PLIST_ENTRY
FunctionCalledAtPassiveLevel(VOID)
{
    KIRQL       Irql;
    PLIST_ENTRY pEntry = NULL;
 
    PAGED_CODE();
 
    //-f--> Aqui nossa IRQL vai para as alturas, se o codigo que
    //      vier depois desta chamada estiver na próxima página
    //      de memória que estiver em disco, então (CABUM !!!)
    KeAquireSpinLock(&g_SpinLock, &Irql);
 
 
    //-f-->    -------======= Fronteira de página =======-------
 
 
    //-f--> O código aqui é executado em DISPATCH_LEVEL, o que
    //      impede esta função de ser definida em uma sessão
    //      paginável.
 
    if (!IsListEmpty(&g_NonPagedList))
    {
        pEntry = RemoveHeadList(&g_NonPagedList);
    }
 
    //-f--> Tudo bem que você acesse apenas dados não pagináveis,
    //      mas o código que você usa para tal acesso também precisa
    //      estar em memória não paginável. Afinal, esse código está
    //      sendo executado em IRQL alta e recuperar uma página de
    //      código em disco resultaria em coisas horríveis.
 
    //-f--> Voltamos a PASSIVE_LEVEL
    KeReleaseSpinLock(Irql);
 
    return pEntry;
}

Se você possui funções que são grandes, mas que contém intervalos pontuais com elevação de IRQL, então separe tais intervalos em funções isoladas que podem ser definidas em sessões não pagináveis, permitindo assim que você defina sua grande e complexa funcão em uma sessão paginável.

Ufa! Eu ainda poderia escrever mais alguns comentários sobre este assunto, mas se eu já estou cansado de escrever, imagino como vocês estão. O assunto é tratado com todos detalhes na referência. Mas se tiverem qualquer dúvida a respeito, é só me enviar um e-mail e torcer pra eu saber responder.

Até mais!

Buffered, Direct ou Neither em IOCTLs

fernando@driverentry.com.br (Fernando Roberto da Silva) — Thu, 16 Oct 2008 14:07:00 +0000

Depois de uma pitada de memória virtual para entendermos os conceitos mais relevantes e darmos uma boa passeada nos métodos de transferências de dados entre aplicação e driver, hoje vamos fechar essa trilogia falando sobre os métodos de transferências de dados em IOCTLs. Se você não sabe criar ou utilizar IOCTLs, este outro post pode ajudar.

Flags não ajudam aqui

No post referente aos métodos de transferências de dados foi visto que definimos o método de transferência através de uma máscara de bits que está localizada no campo Flags em um DEVICE_OBJECT. O método escolhido aqui define como o I/O Manager vai manipular os dados nas operações de leitura (IRP_MJ_READ) e escrita (IRP_MJ_WRITE) do driver. O método escolhido é aplicado para ambas as operações. Não podemos ter escritas utilizando um método enquanto as leituras são realizadas utilizando outro. No caso das IOCTLs, a história é diferente. O método de transferência é escolhido quando se define o control code utilizando a macro CTL_CODE.

 
#define IOCTL_Device_Function CTL_CODE(DeviceType, Function, Method, Access)

Para se ter uma explicação mais detalhada sobre o uso desta macro, visite este post, ou dê uma olhada na referência. Aqui comentarei apenas sobre os métodos de transfêrencias de dados que é selecionado pelo parâmetro Method desta macro. A utilização desta macro para definir IOCTLs é normalmente feita em um arquivo de header que será compartilhado entre a aplicação e o driver. A definição desta macro é obtida a partir do header Windows.h para User-Mode e Ntddk.h para Kernel-Mode. Abaixo segue a definição dos IOCTLs que implementaremos neste post.

 
//-f--> Aqui definimos os IOCTLs de cópia utilizando os
//      deferentes métodos de transferência de dados entre
//      aplicação e driver.
 
//-f--> Utilizando cópia de sistema
#define IOCTL_COPY_BUFFERED CTL_CODE(FILE_DEVICE_UNKNOWN,   \
                                     0x800,                 \
                                     METHOD_BUFFERED,       \
                                     FILE_ANY_ACCESS)
 
//-f--> Travando as páginas da aplicação
#define IOCTL_COPY_DIRECT   CTL_CODE(FILE_DEVICE_UNKNOWN,   \
                                     0x801,                 \
                                     METHOD_OUT_DIRECT,     \
                                     FILE_ANY_ACCESS)
 
//-f--> Seja o que Deus quiser
#define IOCTL_COPY_NEITHER  CTL_CODE(FILE_DEVICE_UNKNOWN,   \
                                     0x802,                 \
                                     METHOD_NEITHER,        \
                                     FILE_ANY_ACCESS)

Como se pode observar, podemos ter diferentes métodos de transferência de dados para diferentes IOCTLs. Neste post vou criar um driver que ofereça três IOCTLs que simplesmente copiam os dados recebidos no buffer de entrada para buffer de saída. O que teremos que fazer inicialmente é utilizar a macro CTL_CODE para criar as IOCTLs dos serviços que nosso driver de exemplo irá oferecer. O código completo do driver de exemplo está disponível para download ao final deste post.

Pô Fernando, eu incluí o Windows.h em minha aplicação de teste, mas ainda está faltando a definição da macro CTL_CODE e recebo a mensagem de erro abaixo. Estou usando um Windows.h incompleto?

Z:\sources\testapp.cpp(45) : error C3861: 'CTL_CODE': identifier not found

O negócio é o seguinte: O Wizard das versões mais recentes do Visual Studio cria o arquivo StdAfx.h contendo, entre outras, as seguintes linhas:

#define WIN32_LEAN_AND_MEAN             // Exclude rarely-used stuff from Windows headers
// Windows Header Files:
#include <windows.h>

Observe que o símbolo WIN32_LEAN_AND_MEAN é definido antes da inclusão do arquivo Windows.h. A fim de ganhar velocidade de compilação, este símbolo evita a declaração de algumas toneladas de definições que raramente são utilizadas por aplicações. O que está acontecendo é que a macro CTL_CODE é uma destas coisas raramente utilizadas. É rapaz, interagir com drivers não é pra qualquer um não. Enfim, para resolver este problema é só comentar a definição deste símbolo e todos viverão felizes para sempre.

Calma lá Fernando! Todos menos eu, que não usei o Wizard do Visual Studio. Estou utilizando o arquivo SOURCES para compilar minha aplicação. O fato é que em meu fonte não existe nenhuma definição desse tal de "Win32 Lemming". Qual é a desculpinha agora?

Se você está utilizando o arquivo SOURCES para compilar sua aplicação de teste, assim como estou fazendo no exemplo deste post, você precisará adicionar a linha em destaque abaixo para que o símbolo WIN32_LEAN_AND_MEAN não seja definido pelo makefile padrão do WDK.

TARGETNAME=TestApp
TARGETTYPE=PROGRAM
USE_LIBCMT=1
UMTYPE=console
NOT_LEAN_AND_MEAN=1
 
SOURCES=TestApp.cpp

Utilizando um buffer de sistema

O primeiro método que veremos aqui é o Buffered I/O, definido pela utilização do valor METHOD_BUFFERED como parâmetro da macro CTL_CODE. Aqui não teremos grandes novidades para quem leu o post anterior. A grande diferença aqui é que na mesma chamada ao driver, dois bufferes são passados para a função DeviceIoControl, um de entrada e outro de saída. Aqui o I/O Manager vai alocar um único buffer de sistema com o tamanho igual ao maior deles. Complicou? Um exemplo ajuda. Numa chamada em que a aplicação ofereça o buffer de entrada com 50 bytes e um buffer de saída com 100 bytes, o buffer de sistema será alocado com 100 bytes. O I/O Manager vai copiar os 50 bytes do buffer de entrada da aplicação para o buffer de sistema. A IRP é enviada ao driver, e ao ser completada, o I/O Manager copia o conteúdo do buffer de sistema para o buffer de saída da aplicação. Quantidade de bytes copiada de volta à aplicação é determinada pelo campo pIrp->IoStatus.Information, assim como no post anterior.

Uma coisa importante a ser notada aqui é que já que o buffer de sistema é único tanto para a entrada como para saída dos dados, o driver precisa ler os dados de entrada antes de começar a escrever os dados de saída, que sobrescreveriam o buffer de entrada.

Conforme já comentei, nosso driver de exemplo vai copiar o buffer de entrada para o buffer de saída. Vamos dar uma olhada na implementação da nossa rotina que vai tratar o IOCTL que usará um buffer de sistema. Leiam os comentários.

/****
***     OnCopyBuffered
**
**      Rotina de tratamento da IOCTL responsável por
**      fazer a cópia do buffer de entrada para o buffer
**      de saída. (usando METHOD_BUFFERED)
*/
 
NTSTATUS
OnCopyBuffered(IN PDEVICE_OBJECT    pDeviceObj,
               IN PIRP              pIrp)
{
    NTSTATUS            nts;
    PIO_STACK_LOCATION  pStack;
 
    //-f--> Obtemos um ponteiro para a stack location
    //      corrente.
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> Output dos valores obtidos.
    //      Reparem que o buffer de entrada e o buffer
    //      de saída é o mesmo. Isso significa que você
    //      não pode escrever no buffer de saída até que
    //      tenha lido todos os bytes do buffer de entrada.
    DbgPrint("========== OnCopyBuffered ===========\n"
             "Input buffer address: 0x%p\n"
             "Input buffer size:    %d\n"
             "Output buffer addres: 0x%p\n"
             "Output buffer size:   %d\n\n",
             pIrp->AssociatedIrp.SystemBuffer,
             pStack->Parameters.DeviceIoControl.InputBufferLength,
             pIrp->AssociatedIrp.SystemBuffer,
             pStack->Parameters.DeviceIoControl.OutputBufferLength);
 
    //-f--> Vamos verificar se o buffer de entrada cabe no buffer
    //      de saída antes de fazer a cópia.
    if (pStack->Parameters.DeviceIoControl.OutputBufferLength <
        pStack->Parameters.DeviceIoControl.InputBufferLength)
    {
        //-f--> Ops!
        nts = STATUS_BUFFER_TOO_SMALL;
        pIrp->IoStatus.Information = 0;
    }
    else
    {
        //-f--> Copiar pra quê?
        //      Como o buffer de entrada e o buffer de saída
        //      oferecidos pela aplicação são copiados para um
        //      único buffer de sistema, não precisamos fazer
        //      nenhuma cópia. O I/O Manager já fará isso por
        //      nós. Vamos apenas informar à aplicação quantos
        //      bytes são válidos no buffer de saída.
        nts = STATUS_SUCCESS;
        pIrp->IoStatus.Information =
            pStack->Parameters.DeviceIoControl.InputBufferLength;
    }
 
    //-f--> Fecha a conta e passa a régua.
    pIrp->IoStatus.Status = nts;
    IoCompleteRequest(pIrp, IO_NO_INCREMENT);
    return nts;
}

Travando a memória da Aplicação

Apesar de o IOCTL ser uma solicitação normalmente utilizada para controle, nada nos impede de utilizar este meio de comunicação para obter ou enviar dados para o driver. Se nestas leituras ou escritas, grandes volumes de dados forem trocados, o método Buffered passa a ser pouco eficiente. Utilizando o método Direct não haverá cópias intermediárias em buffer de sistema. Nada muito diferente do que já vimos no post anterior, mas aqui temos dois bufferes em uma só chamada. O buffer de entrada faltou na escola bem no dia da aula sobre MDLs, e por isso ainda chega ao driver utilizando um buffer de sistema. É isso mesmo! Igualzinho ao método buffered. Por esta razão, não usaremos o buffer de entrada para enviar grandes quantidades de dados ao driver.

Mas e se eu quiser enviar uma grande quantidade de dados para o driver através de um IOCTL? Aqui a conversa entorta um pouco. Repare que para utilizar o método Direct em IOCTLs, podemos usar tanto o parâmetro METHOD_IN_DIRECT como o METHOD_OUT_DIRECT. Com o método Direct, você pode utilizar o buffer de saída como entrada para o driver. Hein? Tá bom, vamos mais devagar. Ambas as opções criam uma MDL para descrever as páginas que compõem o buffer de saída oferecido pela aplicação. Quando a IRP chega ao driver, você utiliza a função MmGetSystemAddressForMdlSafe para obter um ponteiro de System Space que mapeia as mesmas páginas físicas oferecidas pela aplicação. Isso significa que o ponteiro que você recebe vai escrever diretamente nas páginas oferecidas pela aplicação. Já sei! Se o ponteiro aponta para as mesmas páginas da aplicação, então podemos ler os dados contidos nestas páginas? É exatamente isso. Podemos enviar dados ao driver preenchendo o buffer de saída antes de chamar a função DeviceIoControl. Assim, quando o driver receber a IRP, ele pode ler estes dados. Isso permite que o driver receba grandes quantidades de dados de entrada, mas utilizando o buffer de saída. O parâmetro METHOD_IN_DIRECT sinaliza ao I/O Manager que o buffer que será utilizado para montar a MDL será utilizado para leitura, assim o buffer é testado para leituras no processo de criação da MDL. Alternativamente, o parâmetro METHOD_OUT_DIRECT indica que o buffer receberá leituras e escritas do driver.

Lembre-se que METHOD_IN_DIRECT ou METHOD_OUT_DIRECT define apenas o tipo de teste que será feito sobre o buffer de saída, permitindo do driver ler o buffer de saída. O buffer de entrada sempre virá por intermédio de um buffer de sistema. Tá tá tá, vamos ao código por favor?

/****
***     OnCopyDirect
**
**      Rotina de tratamento da IOCTL responsável por
**      fazer a cópia do buffer de entrada para o buffer
**      de saída. (usando METHOD_DIRECT_XXX)
*/
 
NTSTATUS
OnCopyDirect(IN PDEVICE_OBJECT  pDeviceObj,
             IN PIRP            pIrp)
{
    NTSTATUS            nts;
    PIO_STACK_LOCATION  pStack;
    PVOID               pOutputBuffer;
 
    //-f--> Obtemos um ponteiro para a stack location
    //      corrente.
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> O ponteiro de saída vem de uma MDL criada
    //      pelo I/O Manager.
    pOutputBuffer = MmGetSystemAddressForMdlSafe(pIrp->MdlAddress,
                                                 LowPagePriority);
 
    if (!pOutputBuffer)
    {
        //-f--> Ops! Estamos sem recursos para mapear as
        //      páginas descritas pelo MDL em System Space.
        pIrp->IoStatus.Status = STATUS_INSUFFICIENT_RESOURCES;
        pIrp->IoStatus.Information = 0;
        IoCompleteRequest(pIrp, IO_NO_INCREMENT);
        return STATUS_INSUFFICIENT_RESOURCES;
    }
 
    //-f--> Já o ponteiro de entrada sempre vem por um
    //      buffer de sistema como no método Buffered
    DbgPrint("=========== OnCopyDirect ============\n"
             "Input buffer address: 0x%p\n"
             "Input buffer size:    %d\n"
             "Output buffer addres: 0x%p\n"
             "Output buffer size:   %d\n\n",
             pIrp->AssociatedIrp.SystemBuffer,
             pStack->Parameters.DeviceIoControl.InputBufferLength,
             pOutputBuffer,
             pStack->Parameters.DeviceIoControl.OutputBufferLength);
 
    //-f--> Vamos verificar de o buffer de entrada cabe no buffer
    //      de saída antes de fazer a cópia.
    if (pStack->Parameters.DeviceIoControl.OutputBufferLength <
        pStack->Parameters.DeviceIoControl.InputBufferLength)
    {
        //-f--> Ops!
        nts = STATUS_BUFFER_TOO_SMALL;
        pIrp->IoStatus.Information = 0;
    }
    else
    {
        //-f--> Neste caso teremos que fazer a cópia, já que o buffer
        //      de entrada e o buffer de saída são fisicamente distintos
        RtlCopyMemory(pOutputBuffer,
                      pIrp->AssociatedIrp.SystemBuffer,
                      pStack->Parameters.DeviceIoControl.InputBufferLength);
 
        //-f--> Sinaliza sucesso ao I/O Manager e informa à aplicação a
        //      quantidade de bytes válidos no buffer de saída.
        nts = STATUS_SUCCESS;
        pIrp->IoStatus.Information =
            pStack->Parameters.DeviceIoControl.InputBufferLength;
    }
 
    //-f--> Fecha a conta e passa a régua.
    pIrp->IoStatus.Status = nts;
    IoCompleteRequest(pIrp, IO_NO_INCREMENT);
    return nts;
}

Nem Buffered I/O nem Direct I/O

Isso pode parecer repetitivo para você, mas neste método, indicado pelo parâmetro METHOD_NEITHER, o I/O Manager não fará nada por você. Assim, você terá que testar o contexto do processo e também testar o acesso aos bufferes como vimos no post anterior. Mais uma vez, a grande diferença aqui é que teremos dois bufferes. O buffer de entrada virá por pStack->Parameters.DeviceIoControl.Type3InputBuffer e o buffer de saída é obtido por pIrp->UserBuffer. O buffer de entrada deve ser testado com ProbeForRead, já que o driver fará leituras neste buffer, e o buffer de saída deve ser testado com ProbeForWrite. Acho que o resto o código de exemplo é capaz de explicar. Para testar o contexto do processo, utilizamos a função que já foi explicada no post anterior.

/****
***     OnCopyNeither
**
**      Rotina de tratamento da IOCTL responsável por
**      fazer a cópia do buffer de entrada para o buffer
**      de saída. (usando METHOD_NEITHER)
*/
 
NTSTATUS
OnCopyNeither(IN PDEVICE_OBJECT pDeviceObj,
              IN PIRP           pIrp)
{
    NTSTATUS            nts;
    PIO_STACK_LOCATION  pStack;
 
    //-f--> Obtemos um ponteiro para a stack location
    //      corrente.
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> Output dos valores obtidos.
    DbgPrint("=========== OnCopyNeither ===========\n"
             "Input buffer address: 0x%p\n"
             "Input buffer size:    %d\n"
             "Output buffer addres: 0x%p\n"
             "Output buffer size:   %d\n\n",
             pStack->Parameters.DeviceIoControl.Type3InputBuffer,
             pStack->Parameters.DeviceIoControl.InputBufferLength,
             pIrp->UserBuffer,
             pStack->Parameters.DeviceIoControl.OutputBufferLength);
 
    //-f--> Como estamos utilizando o método Neither, temos que
    //      estar executando no mesmo contexto do processo que
    //      gerou a IRP., pois vamos acessar o User Space em Kernel-Mode.
    if (!EstouNoContextoDoProcessoQueGerouEssaIrp(pIrp))
    {
        //-f--> Ops!
        pIrp->IoStatus.Status = STATUS_INVALID_ADDRESS;
        pIrp->IoStatus.Information = 0;
        IoCompleteRequest(pIrp, IO_NO_INCREMENT);
        return STATUS_INVALID_ADDRESS;
    }
 
    //-f--> Aqui já sabemos que estamos no contexto certo, mas ainda
    //      precisamos testar os bufferes oferecidos pela aplicação.
    //      Não queremos que uma aplicação infeliz envie um ponteiro
    //      inválido e o sistema termine em tela azul por conta disso.
    __try
    {
        //-f--> O driver fará leituras no buffer de entrada
        ProbeForRead(pStack->Parameters.DeviceIoControl.Type3InputBuffer,
                     pStack->Parameters.DeviceIoControl.InputBufferLength,
                     1);
 
        //-f--> E fará escritas no buffer de saída
        ProbeForWrite(pIrp->UserBuffer,
                      pStack->Parameters.DeviceIoControl.OutputBufferLength,
                      1);
    }
    __except(EXCEPTION_EXECUTE_HANDLER)
    {
        //-f--> Ahaaa!!
        nts = GetExceptionCode();
 
        //-f--> Completa a IRP e xinga a mãe do cara que escreveu
        //      a aplicação (a menos que tenha sido você mesmo).
        pIrp->IoStatus.Status = nts;
        pIrp->IoStatus.Information = 0;
        IoCompleteRequest(pIrp, IO_NO_INCREMENT);
        return nts;
    }
 
    //-f--> Vamos verificar de o buffer de entrada cabe no buffer
    //      de saída antes de fazer a cópia.
    if (pStack->Parameters.DeviceIoControl.OutputBufferLength <
        pStack->Parameters.DeviceIoControl.InputBufferLength)
    {
        //-f--> Ops!
        nts = STATUS_BUFFER_TOO_SMALL;
        pIrp->IoStatus.Information = 0;
    }
    else
    {
        //-f--> Feche os olhos, diga "Sangue de Jesus tem poder",
        //      acredita em São Walter Oney e copia o buffer de
        //      entrada para o buffer de saída.
        RtlCopyMemory(pIrp->UserBuffer,
                      pStack->Parameters.DeviceIoControl.Type3InputBuffer,
                      pStack->Parameters.DeviceIoControl.InputBufferLength);
 
        //-f--> Ufa! Todos vivos?
        //      Sinaliza sucesso ao I/O Manager e informa à aplicação a
        //      quantidade de bytes válidos no buffer de saída.
        nts = STATUS_SUCCESS;
        pIrp->IoStatus.Information =
            pStack->Parameters.DeviceIoControl.InputBufferLength;
    }
 
    //-f--> Fecha a conta e passa a régua.
    pIrp->IoStatus.Status = nts;
    IoCompleteRequest(pIrp, IO_NO_INCREMENT);
    return nts;
}

Compilando o exemplo

Para compilar o exemplo disponível para download, você pode utilizar o atalho de ambiente instalado pelo WDK e chamar o Build do diretório raiz do exemplo. Repare que em um único passo compilamos o driver e a aplicação de teste. A figura abaixo ilustra isso. Ou você pode usar o DDKBUILD como eu já expliquei neste outro post para compilar a partir do Visual Studio.

Fernando, mais uma dúvida antes de você sumir na névoa. Na tabela de Dispatch Routines, que preenchemos na estrutura DRIVER_OBJECT, contém apenas uma entrada para IRP_MJ_DEVICE_CONTROL. Como você criou uma rotina para cada método? Essa eu vou deixar o código de exemplo abaixo responder, mas se ainda assim você tiver alguma dúvida, é só me mandar um e-mail, que está em meu perfil do Blogger, e aí a gente sai na porrada.

/****
***     OnDeviceControl
**
**      Aqui recebemos todos os DeviceIoControl
**      enviados para o driver e separamos em rotinas
**      específicas para o tratamento de cada IOCTL.
**      Todo o tratamento de todas as IOCTLs poderiam
**      estar em uma só função, mas não custa nada ser
**      organizado de vez em quando.
*/
 
NTSTATUS
OnDeviceControl(IN PDEVICE_OBJECT   pDeviceObj,
                IN PIRP             pIrp)
{
    PIO_STACK_LOCATION  pStack;
 
    //-f--> Obtemos um ponteiro para a stack location
    //      corrente.
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> Obtém o código do IOCTL para encaminhar
    //      para a rotina certa, ou não. :-)
    switch(pStack->Parameters.DeviceIoControl.IoControlCode)
    {
    case IOCTL_COPY_BUFFERED:
        return OnCopyBuffered(pDeviceObj,
                              pIrp);
 
    case IOCTL_COPY_DIRECT:
        return OnCopyDirect(pDeviceObj,
                            pIrp);
 
    case IOCTL_COPY_NEITHER:
        return OnCopyNeither(pDeviceObj,
                             pIrp);
    }
 
    //-f--> Ops! Recebemos um IOCTL diferente dos que
    //      estávamos esperando.
    pIrp->IoStatus.Status = STATUS_NOT_IMPLEMENTED;
    pIrp->IoStatus.Information = 0;
    IoCompleteRequest(pIrp, IO_NO_INCREMENT);
 
    return STATUS_NOT_IMPLEMENTED;
}

Hoje vou me despedir ao estilo mr4nd3r50n, que é um amigo que trabalhou comigo na SCUA.

Intel mais, já vou Windows!
:-)

Download IoctlCopy.zip

Buffered, Direct ou Neither

fernando@driverentry.com.br (Fernando Roberto da Silva) — Wed, 01 Oct 2008 19:43:00 +0000

No post passado apresentei uma breve introdução sobre alguns pontos referentes à memória virtual que considero ser os mais relevantes aos desenvolvedores de drivers. Com essa pequena carga de conhecimento, ficará mais simples de explicar as diferenças entre os métodos de transferências de dados entre aplicações e drivers, assim como outras questões, tais como o atendimento de interrupções, mapeamento de memória e contexto de execução.

Se formos pensar de maneira bem simplificada (e bota simplificada nisso), drivers são basicamente os módulos que extraem dados de dispositivos e os disponibilizam para as aplicações e vice-versa. Deste ponto de vista, parece mesmo que escrever drivers seja fácil. Parece até uma maneira de fazer um memcpy de software para hardware. Hoje veremos um pouco sobre as maneiras as quais um driver pode optar para fazer essa transferência de dados.

Utilizando um Buffer de sistema

O primeiro método é o chamado Buffered I/O. Este método utiliza um buffer de sistema para fazer a transferência de dados entre a aplicação e o driver. Quando uma aplicação chama a função WriteFile passando os dados a serem enviados para o driver, o I/O Manager faz uma cópia dos dados da aplicação para um buffer de sistema. Mas o que é um buffer de sistema? Se trata de uma alocação em System Space que foi feita em Kernel-Mode, e por isso, é acessível em qualquer contexto de processo. Já falamos disso no post passado.

BOOL WINAPI WriteFile(
  __in         HANDLE hFile,
  __in         LPCVOID lpBuffer,
  __in         DWORD nNumberOfBytesToWrite,
  __out_opt    LPDWORD lpNumberOfBytesWritten,
  __inout_opt  LPOVERLAPPED lpOverlapped
);

O I/O Manager obtém o tamanho do buffer a ser alocado do parâmetro nNumberOfBytesToWrite, então realiza uma alocação de memória do tipo não paginada e faz a cópia dos dados que estão em User Space para System Space. Se você estiver derrapando nos termos System Space, User Space e tipos de alocação de memória, dê uma lida neste post para que as coisas fiquem menos obscuras para você.

No driver, o ponteiro para este buffer é obtido pela IRP e seu tamanho é obtido pela stack location da IRP. Legal, mas o que é uma IRP? Dê uma olhada neste mini exemplo abaixo para ter uma idéia, ou você pode ver o exemplo utilizado neste outro post que também utiliza o método Buffered para enviar e receber strings de um driver de exemplo.

//-f--> Rotina de tratamento da IRP_MJ_WRITE.
//      Exemplo de obtenção do buffer de sistema
//      alocado pelo I/O Manager no método Buffered
 
NTSTATUS
OnDispatchWrite(__in PDEVICE_OBJECT pDeviceObj,
                __in PIRP           pIrp)
{
    PIO_STACK_LOCATION  pStack;
    PVOID               pBuffer;
    ULONG               ulLength;
 
    //-f--> Obtém a stack corrente da IRP
    pStack = IoGetCurrentIrpStackLocation();
 
    //-f--> Aqui obtemos o ponteiro para o buffer
    pBuffer = pIrp->AssociatedIrp.SystemBuffer;
 
    //-f--> Aqui o tamanho do buffer
    ulLength = pStack->Parameters.Write.Length;
 
    ...
}

Nas operações de leitura, o método é bem parecido, mas apesar de neste caso o I/O Manager também fazer a locação em memória não paginada, ele não faz nenhuma cópia para o buffer de sistema. O buffer de sistema é recebido pelo driver também através de pIrp->AssociatedIrp.SystemBuffer, mas o seu tamanho é obtido em pStack->Parameters.Read.Length. O driver preencherá o buffer com os dados vindos do dispositivo, o I/O Manager fará a cópia do buffer de System Space para User Space quando a IRP for completada, preenchendo o buffer da aplicação.

Opa opa! Até onde eu sei, drivers normalmente completam IRPs em contexto arbitrário, o que significa que "só Deus sabe em qual contexto de processo". Tudo bem se o driver escrever em um buffer de sistema, o qual é válido para qualquer processo, mas o buffer da aplicação está em User Space e só é acessível no contexto do próprio processo. Como o I/O Manager faria a cópia do buffer de sistema para o buffer da aplicação em contexto arbitrário? Nossa, essa realmente foi uma excelente pergunta. Acho que nem eu teria imaginado uma pergunta tão boa. As IRPs podem ser tratadas tanto sincronamente como assincronamente. O I/O Manager sabe como a IRP foi processada, e no caso síncrono, o I/O Manager já está no contexto do processo que fez a solicitação, e neste caso ele tem acesso a ambos os bufferes, já que o I/O Manager roda em Kernel-Mode. Quando a IRP é tratada assincronamente, o I/O Manager enfila uma APC (Asynchronous Procedure Call), que é uma chamada assincrona executada no contexto de uma dada thread. Essa thread é justamente a thread que iniciou a operação, e que portanto, estará no contexto do processo certo para acessar o User Space da aplicação.

BOOL WINAPI ReadFile(
  __in         HANDLE hFile,
  __out        LPVOID lpBuffer,
  __in         DWORD nNumberOfBytesToRead,
  __out_opt    LPDWORD lpNumberOfBytesRead,
  __inout_opt  LPOVERLAPPED lpOverlapped
);

Na chamada da função ReadFile, o parâmetro nNumberOfBytesToRead indica o tamanho do buffer que a aplicação está oferecendo ao driver. O driver recebe este valor como quantidade máxima de bytes que podem ser retornados à aplicação. Supondo que a aplicação tenha oferecido 1000 bytes, o I/O Manager faz uma alocação de 1000 bytes e repassa o buffer para o driver. Vamos supor que o driver tenha apenas 500 bytes a serem retornados à aplicação, neste caso, o I/O Manager terá de copiar para o buffer da aplicação apenas 500 dos 1000 bytes alocados. O I/O Manager recebe este valor através do campo pIrp->IoStatus.Information, que é preenchido pelo driver antes da IRP ser completada. Desta forma, o I/O Manager copia somente os bytes válidos do buffer de sistema para o buffer da aplicação. Este mesmo valor é retornado à aplicação através do parâmetro lpNumberOfBytesRead.

Utilizar memória não paginada para o manter o buffer de sistema nos assegura que as páginas não serão removidas da RAM por paginação. Isso permite que a página seja acessada mesmo a partir de threads que estejam rodando em alto nível de prioridade. Contudo, o método Buffered é indicado apenas para pequenas movimentações de dados. Imagine que uma aplicação queira fazer uma escrita de 10 MB de uma só vez. O I/O Manager teria que fazer uma alocação em System Space de 10 MB de memória não paginada, o que não seria nada adequado, pois memória não paginada é um recurso escasso. Se o I/O Manager conseguir fazer a alocação, ele ainda terá que fazer uma cópia de 10 MB do buffer da aplicação para o buffer de sistema. Isso até funcionaria, mas teriamos sérios problemas de performace. Neste caso, o mais indicado seria utilizar o método que é visto em seguida.

Travando a memória da Aplicação

No método chamado Direct I/O, como o nome já sugere, o driver faz acesso diretamente às páginas de memória da aplicação sem utilizar um buffer intermedirário. Desta forma, o I/O Manager não faz uma alocação em memória não paginada e também não tem que ficar no BPL-BPC (Buffer pra lá - Buffer pra cá). Ao invés disso, o I/O Manager testa as páginas de memória que compõem o buffer oferecido pela aplicação, cria uma MDL e trava as páginas de memória na RAM. Nossa! Calma aí meu amigo, vamos devagar!

Testa as páginas de memória - Nada impede um programador de fazer besteira. Um buffer inválido pode ser passado para o I/O Manager. Pode ser que o buffer não tenha sido alocado, ou que o buffer seja menor que o valor indicado na chamada às funções ReadFile ou WriteFile, pode ser também que as páginas de memória oferecidas à ReadFile estejam protegidas contra escrita, pode ser também que algumas das páginas utilizadas pelo buffer tenham sido paginadas para o disco. Se um driver tenta acessar uma página inválida ou protegida, uma exceção é gerada e uma tela azul sugirá das trevas. Mas como o I/O Manager vai testar a memória? Se o buffer é passado como parâmetro para a função ReadFile, então o driver fará escritas neste buffer. Para ganhar tempo, o I/O Manager fará uma escrita de um byte de cada página de RAM apenas para testar o acesso a elas. Essa escrita é feita sob um manipulador de exceção. Se o buffer for inválido ou protegido, o manipulador de exceção tratará isso e devolverá um erro para a aplicação. Se o buffer é passado para a função WriteFile, então o buffer será lido pelo driver, e neste caso, o teste seria a leitura de um byte de cada página.

Cria uma MDL - Uma MDL (Memory Descriptor List) é uma estrutura de dados que descreve as várias páginas de memória que compõem um buffer. Estas páginas são as mesmas páginas físicas utilizadas pela aplicação, ou seja, quando o driver escrever nestas páginas, este já estará escrevendo diretamente no buffer da aplicação. Assim o I/O Manager não precisará fazer nenhum BPL-BPC.

Trava as páginas na RAM - Esse passo faz com que as páginas de memória que compõem o buffer da aplicação se tornem não pagináveis. Assim, estas poderão ser acessadas pelo driver em threads que estejam sendo executadas em alto nível de prioridade.

Depois de todo esse ritual, o driver agora recebe o buffer através de pIrp->MdlAddress, mas o que teremos aqui é um ponteiro para uma MDL. Mas o que eu faço com uma MDL? Na maioria das vezes, você vai passar como argumento em um serviço oferecido por outro driver ou componente do sistema. Alguns exemplos são drivers de DMA (Direct Memory Access) que utilizam MDL na chamada para a função MapTransfer, ou mesmo quando uma MDL é repassada para rotinas de controladores USB (Universal Serial Bus), tais como UsbBuildInterruptOrBulkTransferRequest. MDLs são estruturas opacas, mas se você quer ter acesso ao buffer da aplicação, então devemos chamar a função MmGetSystemAddressForMdlSafe para conseguir o endereço para o buffer a ser escrito/lido. Reparem que o endereço retornado por esta função está em System Space, e assim, acessível em qualquer contexto de processo. Mas o buffer da aplicação não está em User Space? Sim, mas o que temos aqui é uma página de memória física sendo mapeada tanto para o espaço de endereçamento da aplicação quanto para o espaço de endereçamemto de sistema.

O tamanho do buffer descrito pela MDL também é obtido pela stack location da IRP, assim como no método Buffered.

Nem Buffered I/O nem Direct I/O

O terceiro método é simplesmente o não uso dos dois primeiros. No método chamado Neither, o I/O Manager não faz uma cópia em um buffer de sistema nem monta uma MDL para descrever o buffer da aplicação. Quando a IRP chega ao seu driver, você tem acesso ao endereço virtual do buffer oferecido pela aplicação por pIrp->UserBuffer. Este endereço aponta para User Space, e por isso, lembre-se que este endereço só é valido no contexto do processo que solicitou o I/O. O uso deste método requer mais cuidado, pois seu driver precisa ser o primeiro driver na pilha de dispositivos, e dessa forma, garantir que a IRP chegue ao seu driver no contexto do prcesso que fez a solicitação de I/O.

Você pode verificar se você está no contexto do processo que solicitou a operação fazendo o teste abaixo.

/****
***     EstouNoContextoDoProcessoQueGerouEssaIrp
**
**      Função com nome ridículo que verifica se o
**      estamos no contexto do processo que gerou
**      a IRP passada como parâmetro.
*/
 
BOOLEAN EstouNoContextoDoProcessoQueGerouEssaIrp(__in PIRP pIrp)
{
    PETHREAD    pEThread;
    PEPROCESS   pEProcess;
 
    //-f--> Obtém a thread que gerou a IRP
    pEThread = pIrp->Tail.Overlay.Thread;
 
    //-f--> Obtém o processo referente a thread
    pEProcess = IoThreadToProcess(pEThread);
 
    //-f--> Aqui comparamos o processo corrente com
    //      o processo que gerou a IRP
    return (PsGetCurrentProcess() == pEProcess);
}

O fato de estar no contexto do processo correto não garante que o buffer passado como parâmetro seja válido. Diferente do método Direct, neste ponto o I/O Manager não testou o buffer antes de passar a IRP para o driver. Teremos que fazer isso por nós mesmos. Lembre-se que, assim como em User-Mode, ao acessar um buffer inválido o driver receberá uma exceção que deve ser manipulada, caso contrário, tudo azul.

Para realizar o teste, teremos que acessar um byte de cada página do buffer que nos foi passado e verificar se o mundo acaba. As rotinas ProbeForRead e ProbeForWrite fazem isso por nós, mas estas devem ser chamadas dentro de um manipulador de exceção. Vale lembrar que em uma operação de leitura, a aplicação nos envia um buffer onde o driver escreverá dados para a aplicação. Já que o driver fará uma escrita neste buffer, teremos que realizar um teste de escrita (ProbeForWrite) nas operações de leitura (ReadFile). De maneira análoga, o driver deverá fazer um teste de leitura (ProbeForRead) nas operações de escrita (WriteFile). Dê uma olhada no exemplo de rotina de leitura que segue abaixo. Como você já deve estar acostumado, leia os comentários que complementam o texto.

/****
***     OnDispatchRead
**
**      Outra função com nominho besta de exemplo.
**      Valida o buffer enviado pela aplicação pelo
**      método Neither e escreve uma seqüência numérica
**      no buffer da aplicação.
*/
 
NTSTATUS OnDispatchRead(__in PDEVICE_OBJECT pDeviceObj,
                        __in PIRP           pIrp)
{
    PIO_STACK_LOCATION  pStack;
    PVOID               pBuffer;
    ULONG               ulLength;
 
    //-f--> Verifica se estamos no contexto do processo
    //      que gerou esta IRP
    if (!EstouNoContextoDoProcessoQueGerouEssaIrp(pIrp))
    {
        //-f--> Sinaliza ao I/O Manager que a casa caiu
        pIrp->IoStatus.Status = STATUS_INVALID_PARAMETER;
        pIrp->IoStatus.Information = 0;
 
        //-f--> Completa a IRP com falha
        IoCompleteRequest(pIrp, IO_NO_INCREMENT);
        return STATUS_INVALID_PARAMETER;
    }
 
    //-f--> Obtém a stack location corrente
    pStack = IoGetCurrentIrpStackLocation(pIrp);
 
    //-f--> Aqui obtemos o endereço do buffer oferecido
    //      pela aplicação bem como seu tamanho.
    //      Note que este buffer deve estar em User Space
    pBuffer = pIrp->UserBuffer;
    ulLength = pStack->Parameters.Read.Length;
 
    //-f--> As funções que testam o buffer lançam exceções
    //      no caso de o buffer ser inválido. Por isso temos
    //      que fazer o teste dentro de um manipulador de exceções
    __try
    {
        //-f--> Se você der uma olhada na referência, verá que
        //      esta rotina retorna VOID, por isso a única
        //      maneira de saber se o buffer é inválido é
        //      manipulando a exceção que será gerada.
        ProbeForWrite(pBuffer,
                      ulLength,
                      1);
    }
    __except(EXCEPTION_EXECUTE_HANDLER)
    {
        NTSTATUS    nts;
 
        //-f--> Ops! Buffer inválido.
        //      Vamos obter o código da exceção e dar um
        //      fim nesse sofrimento
        nts = GetExceptionCode();
 
        pIrp->IoStatus.Status = nts;
        pIrp->IoStatus.Information = 0;
        IoCompleteRequest(pIrp, IO_NO_INCREMENT);
        return nts;
    }
 
    //-f--> Aqui sabemos que o buffer está seguro para receber
    //      escritas. Vamos apenas escrever uma seqüência numérica
    //      só pra...
    for (ULONG i = 0; i < ulLength, i++)
        ((PUCHAR)pBuffer)[i] = (UCHAR)i;
 
    //-f--> Aqui informamos que a operação foi realizada com
    //      sucesso.
    pIrp->IoStatus.Status = STATUS_SUCCESS;
 
    //-f--> Apesar de no método Neither o I/O Manager não
    //      utilizar este número para fazer BPL-BPC, este
    //      número ainda é retornado pela função ReadFile
    //      para informar à aplicação quantos bytes do buffer
    //      são válidos para a aplicação ler.
    pIrp->IoStatus.Information = ulLength;
 
    //-f--> Dá um Fatality na IRP
    IoCompleteRequest(pIrp, IO_NO_INCREMENT);
    return STATUS_SUCCESS;
}

Para todos os métodos, é importante notar que setar o campo pIrp->IoStatus.Information diz à aplicação a quantidade de bytes foram lidos ou escritos no buffer, independente de haver ou não a cópia de buffer de sistema como no caso do método Buffered.

Outra coisa que não vai mudar para os diferentes métodos é a obtenção do tamanho do buffer oferecido pela aplicação. Este valor sempre vem pela stack location como já foi visto nos métodos já discutidos.

Como selecionar o método

Faz todo o sentido que a escolha do método seja feita antes da primeira IRP chegar ao driver. Isso é feito logo depois que o device é criado. Depois que a chamada à função IoCreateDevice termina, recebemos o novo device através de um ponteiro de saída. O membro Flags da estrutura DEVICE_OBJECT é uma máscara de bits e os bits DO_BUFFERED_IO e DO_DIRECT_IO configuram o método de transferência.

Então é fácil assim. Para configurar o método Buffered, setamos o bit DO_BUFFERED_IO, para configurar o método Direct, setamos o bit DO_DIRECT_IO, e finalmente para setar o método Neither, não setamos nenhum destes bits. Já li em algum livro, que não encontro agora, que o comportamento não é previsto se você setar ambos os bits.

Segue mais um exemplinho besta de como setar o device que acaba de ser criado para transferências no método Buffered.

    //-f--> Cria o device que irá receber as IRPs
    nts = IoCreateDevice(pDriverObj,
                         0,
                         &usDeviceName,
                         FILE_DEVICE_UNKNOWN,
                         0,
                         FALSE,
                         &pDeviceObj);
 
    //-f--> Verifica se o device foi criado
    if (!NT_SUCCESS(nts))
        return nts;
 
    //-f--> Aqui já podemos configurar o método
    //      de transferência desejado, que neste
    //      exemplo é o Buffered I/O
    pDeviceObj->Flags |= DO_BUFFERED_IO;

Mas e se uma IRP for entregue ao driver antes de setarmos estes bits? Outra excelente pergunta. As coisas acontecem assim. Sempre quando um novo device é criado, o bit DO_DEVICE_INITIALIZING é setado. As IRPs só começam a ser entregues a este device quando o driver baixar este bit. Isso nos permite inicializar o device antes que qualquer IRP chegue.

Boa tentativa espertão, mas seu exemplo não baixa este bit. Como você explica isso? Você hoje está impossível! Ao termino da rotina DriverEntry, quando o controle volta ao I/O Manager, ele varre a lista de devices criados pelo driver e baixa este bit por nós. É importante lembrar que ainda precisamos baixar este bit quando criamos um novo device depois que a rotina DriverEntry terminou. Um exemplo muito comum são os devices de WDM, que são criados na rotina AddDevice, mas isso vai ficar para uma outra vez. Esse post já ficou muito longo.

Até mais! :-)

Uma pitada de Memória Virtual

fernando@driverentry.com.br (Fernando Roberto da Silva) — Thu, 11 Sep 2008 18:42:00 +0000

Agora vamos deixar de conversinha mole e vamos logo ao que interessa. O exemplo que descrevi em outro post mostra como implementar um driver bem simples que armazena uma lista de strings que são enviadas ao driver através de operações de escrita (WriteFile), e as mesmas strings são retornadas em subseqüentes operações de leitura (ReadFile). Esse é um bom exemplo de como os dados das aplicações vão para os drivers e vice-versa. Existem três maneiras de acessar os dados oferecidos por aplicações a partir de um driver. Neste post vamos dar uma olhadinha em memória virtual para que possamos ter uma base para posts futuros, onde poderei explicar as diferenças entre aquelas tais três maneiras. Vamos nos ater a apenas algumas características básicas da memória virtual para que as coisas que explicarei em seguida façam mais sentido para você, mas se você quiser mais detalhes a respeito de Memória Virtual, você pode ler o Capítulo 7, "Memory Management", do Windows Internals, ou dar uma olhadinha em uma apresentação feita pelo meu amigo Strauss.

O que é uma página de memória

Página de memória é uma unidade utilizada pelo hardware nas proteções de acesso à memória. Mais sobre proteções de páginas de memória aqui. Essa é uma unidade definida pelo hardware que ajuda a subdividir a memória em espaços menores e gerenciáveis. Apesar de existirem dois tamanhos de páginas (uma pequena de 4KB bytes, e outra grande de 4MB), toda referência ao tamanho de página vista na documentação são referentes apenas às páginas pequenas. O tamanho da página de memória varia com a plataforma de hardware. Em sistemas x86 e x64, as paginas são de 4KB enquanto que em sistemas IA64 a página é de 8KB. O tamanho da página pode ser obtido pela constante PAGE_SIZE.

Espaço de endereçamento

De uma maneira bem resumida, memória virtual é um mecanismo, que em um trabalho conjunto entre hardware e software, permite que processos que rodem no Windows tenham seu próprio espaço de endereçamento. Espaço quem? Espaço de endereçamento, ou Address Space como normalmente vimos na referência, permite que cada processo tenha uma visão privada da memória que esteja utilizando. Ou seja, um processo não pode ler ou escrever em páginas de memória de outro processo. Isso evita que um programa mal escrito possa erroneamente escrever em páginas de memória de outro processo ou mesmo em páginas do sistema operacional, comprometendo assim a estabilidade de todo o sistema. Portanto, podemos assumir que o espaço de endereçamento de um processo só é acessível pelo processo ao qual ele pertence.

Nota: É possível compartilhar memória entre processos, mas mesmo neste caso, a mesma página física de memória é referenciada por dois ou mais espaços de endereçamentos diferentes.

Memória Virtual e Memória Física

Logo após a descoberta do fogo, a memória era endereçada diretamente em modo real. Isso significa que um ponteiro utilizado por uma aplicação acessava o dado exatamente onde ele se encontrava fisicamente nos chips de memória RAM. Páginas de memória virtual associadas aos processos refletem páginas físicas de memória através de um endereçamento virtual. Os bits que compõem o endereço virtual mapeam a memória física que se deseja acessar. Ao deferenciar um ponteiro que contem um endereço virtual, o processador, de maneria transparente ao processo, consulta estruturas preenchidas pelo sistema operacional de forma a traduzir o endereço virtual em real, e dessa forma, encontra a página física onde o dado realmente se encontra.

A disposição das páginas de memória virtual não tem relação com sua disposição física. Isso significa que você quando você faz uma grande alocação de memória, que é composta por várias páginas de memória, você ganha um ponteiro que, do ponto de vista da aplicação, aponta para páginas de memória que estão linearmente distribuídas (uma seguida da outra), enquanto que as páginas de memória física podem estar todas espalhadas pelos chips de RAM.

A memória pode não estar na RAM

A memória utilizada pelas aplicações não se limita à quantidade de memória oferecida pelos chips de RAM instalados em sua placa mãe. Quando os processos, cada vez mais sedentos por memória, vão sendo executados, o espaço disponível em RAM vai sendo compartilhado entre os vários processos. Páginas de memória acessadas com menos frequência são removidas dos chips de RAM e vão para disco (para o Pagefile.sys para ser mais preciso), dando lugar à uma outra página de memória que é necessária naquele momento. Esse processo recebe o nome de paginação. Quando a aplicação finalmente acessar o dado que está naquela página agora em disco, o sistema aloca espaço em RAM física para trazer de volta a página do disco para a RAM. Isso pode resultar em outras páginas que estavam em RAM a serem paginadas para o disco.

Para as aplicações, o processo de paginação é completamente transparente. O desenvolvedor não está nem um pouco preocupado se a região de memória que o programa vai acessar está em disco ou está em RAM. É só acessar o dado e o processador junto com o gerenciador de memória resolve isso para você. Infelizmente, a história não é tão florida para os desenvolvedores de drivers. Aplicações sempre rodam em uma prioridade de thread baixa (PASSIVE_LEVEL) e ao acessar um dado que esteja em uma página em disco, a thread é interrompida pelo gerenciador de memória para que este tenha a oportunidade de acionar os drivers de File System e por conseqüência os drivers de disco, aguardar o I/O ser realizado (apesar de levar um cacalhésimo de segundo, ainda temos que esperar) e então a thread é liberada. Embora haja pessoas que não acreditem nessas coisas, a plataforma NT é completamente preemptiva. Isso significa que uma thread pode ser interrompida por outra de maior prioridade. Em Kernel Mode, uma thread pode estar em prioridades superiores à APC_LEVEL, que é a prioridade em que as paginações são realizadas. Se a thread que acessará o dado estiver em um nível de prioridade muito alta (maior ou igual a DISPATCH_LEVEL), o processador não vai conseguir fazer a paginação e uma tela azul irá aflorar aos seus olhos. Um exemplo típico de execução em alta prioridade é o tratamento de interrupções, mas não vamos nos desviar do assunto.

Uma página pode ser acessada não só por um software, mas também por hardware. Hein? Uma aplicação pode passar o ponteiro de uma região de memória para um driver, que por sua vez, irá utilizar um canal de DMA para preencher este buffer. A cópia de um buffer através do processo de DMA não utiliza ciclos de CPU para ser realizada. Preencher um buffer é algo tão simples que até um chimpanzé autista pode fazer. Assim um grupo de chimpanzés autistas engenheiros criaram um chip que faz isso, mas isso não vem ao caso agora. Este chip pode estar na placa mãe ou na própria placa controlada pelo driver. O chip é programado pelo driver e uma transferência é iniciada. Durante a cópia, nem a aplicação, nem o sistema operacional e nem mesmo o processador ficam cientes do que está acontecendo. O sistema pode então determinar que as páginas utilizadas na transferência, que não estão sendo acessadas por nenhum processo, devem ser paginadas para disco. Se isso ocorrer, o chip de DMA continuará tranferido bytes para aquele endereço físico de RAM e... Bom, já sabe né? Para evitar isso, existem meios de avisar o gerenciador de memória que uma ou mais páginas não devem ser paginadas.

Durante o desenvolvimento de um driver, você pode querer alocar um buffer que será utilizado por uma ISR (Interrupt Service Routine). Como uma ISR é executada em alta prioridade, podemos fazer uma alocação de memória solicitando um buffer que não seja paginável, e assim, garantir que o buffer obtido por esta alocação esteja sempre em RAM. Mas vá com calma, memória não paginável é um recurso escasso e deve ser utilizado com parcimônia. Caso contrário, algumas operações vão deixar de ser realizadas pelo sistema por falta de RAM, mesmo que ainda haja muita memória paginável disponível.

User Space e System Space

Adotando um sistema de 32 bits como exemplo, um ponteiro é capaz de endereçar 4 GB de memória. Destes, 2 GB são reservados para endereçar páginas privadas para cada processo, ou seja, vão compor o espaço de endereçamento privado de cada aplicação. Esta faixa, que vai de 0x00000000 ao 0x7FFFFFFF, recebe o nome de User Space e são os endereços que aplicações acessam em User Mode. Conforme vimos, esta faixa compõe o espaço de endereçamento privado de um processo, protegido contra acessos indevidos de outros processos. Um exemplo seria: Somente as threads do Processo A terão acesso ao User Space do Processo A. O mesmo endereço aponta para diferentes páginas físicas de RAM em diferentes processos, dependendo do contexto do processo que faz o acesso. Os outros 2 GB restantes do endereçamento de 32 bits são reservados ao endereçamento de páginas de sistema. A faixa de endereços de 0x80000000 ao 0xFFFFFFFF define o então chamado System Space, que diferente do User Space, endereçam páginas de memória que não são privados a um determinado processo. Isso significa que o mesmo dado (na mesma página física) pode ser acessado através do mesmo endereço virtual em diferentes processos. Um dado em System Space pode ser acessado apenas em Kernel Mode, enquanto que um dado em User Space pode ser acessado tanto em Kernel Mode quanto em User Mode.

Cagamba! Isso foi uma metralhadora de conceitos? Se você apresentar sintomas de visão turva ou vômito seguido de diarréia e tremedeira, larga a mão de ser frouxo e se prepare para os próximos posts. Caso você não tenha apresentado nenhum destes sintomas, não se preocupe, para algumas pessoas o processo é mais demorado. Em posts futuros vou explicar como os drivers acessam os endereços virtuais oferecidos pelas aplicações, como lidam com a paginação de memória e ainda testam buffers oferecidos pelas aplicações. Um driver mal escrito pode permitir que um parâmetro inválido em uma aplicação cause uma tela azul.

Por hoje chega, mas vale lembrar que o que foi apresentado aqui é apenas a ponta do iceberg. Essa pontinha é o que acredito ser o mais relevante para o desevolvimento de drivers, mas ainda existem toneladas de detalhes referentes à memória virtual.

Have fun! :-)

Recife Office

fernando@driverentry.com.br (Fernando Roberto da Silva) — Sun, 24 Aug 2008 18:45:00 +0000

Pode uma pessoa trabalhar do outro lado do país e ainda assim dar um curso de Drivers para Windows? A resposta para essa pergunta é: "Depende se essa pessoa é Home suficiente para isso". O fato de ter recebido a oportunidade de trabalhar em casa me abriu a grande flexibilidade de poder trabalhar fora de casa. Trabalhar pela Internet não significa necessariamente trabalhar em casa.

Fui convidado a ministrar o curso de Drivers em um centro de estudos que fica em Recife - PE. Eu nunca poderia aceitar um convite desses em condições normais de temperatura e pressão, já que trabalho regularmente em uma empresa em São Paulo, e como se não bastasse, ainda estou me graduando em Engenharia da Computação no período noturno. Mas agora que virei Home, as coisas são diferentes. Aproveitando o período de férias da universidade, fui fazer meu Home Office em Recife e dar o curso durante o período noturno.

Uma empresa multi-nacional do ramo de eletrônicos contratou os serviços deste centro de estudo para o desenvolvimento e manutenção dos drivers que se comunicariam via USB com telefones celulares. O driver original foi escrito por ninguém menos que Walter Oney. Fiquei com a missão de ensinar o caminho das telas azuis para este grupo de 10 alunos, minha maior turma até agora. Quantas pessoas que trabalham com drivers você conhece? O número de alunos não foi problema em momento algum, pensei que seria mais difícil gerenciar isso. Todos interessados, esforçados e com vontade de aprender. Difícil mesmo foi ter que ficar duas semanas inteiras hospedado em um Hotel à beira-mar na praia de Boa Viagem e não poder dar um único mergulho (A primeira foto deste post foi tirada da janela do hotel). Um dos motivos é a constante presença de tubarões nas praias Pernambucanas, com algumas exceções. Outro fato foi a carga horária que foi adotada. Um curso básico de drivers é normalmente ministrado em 40 horas, o que é perfeito para duas semanas, sendo 10 aulas de 4 horas. Mas neste caso havia a necessidade de uma especialização em dispositivos USB. Isso nos tomou dois sábados, meio domingo e muita energia. Um curso de três semanas foi dado em duas. Não sei se foi o mais produtivo, mas minha agenda não me permitiu o luxo de descansar aos finais de semana.

Uma pergunta freqüente em meu blog é "Quando será formada a próxima turma?". No começo desse ano eu imaginei poder montar uma turma aberta durante o período de férias, mas a correria que veio em seguida, acentuada com pela minha viagem, não permitiu que eu me organizasse com relação a infra-estrutura e divulgação. O curso destas férias não existiria, mas no caso de Recife, já havia uma turma fechada e a disponibilidade dos recursos oferecidos por eles. A pergunta ainda persiste e a resposta agora será que estou me organizando para montar uma turma aberta para o início de Janeiro. Obviamente vou publicar qualquer novidade referente a isso aqui no blog, mas gostaria de já ter uma noção dos recursos que terei que reservar para isso. Assim, se você tem interesse de participar dessa turma, me envie um e-mail sem compromisso ou deixe um comentário neste post. Meu endereço de e-mail que ninguém encontra, fica na página apontada por este link, que é a página do meu perfil do blogger.

Até mais...

Agora que virei Home

fernando@driverentry.com.br (Fernando Roberto da Silva) — Sat, 12 Jul 2008 10:34:00 +0000

De repente meu gerente me liga e pergunta - "Você é Home, certo?". Fiquei meio constrangido com aquela situação, mas o que eu podia fazer? Eu tinha que responder àquela pergunta. "Olha, ainda não sou completamente, mas estou interessado em virar", respondi. "Então preencha os formulários que eu aprovo". Foi basicamente assim que virei Home Office.

Como funcionário regular, eu ainda tinha o direito de fazer Home Office 2 dias por semana. No início vem um sentimento de culpa. Não dá pra aceitar, assim de cara, que não terei que levantar às cinco e meia da manhã e enfrentar quase duas horas de trânsito para sair de Santo André, pegar a Avenida dos Estados e finalmente chegar ao prédio onde trabalho. Confesso que não sair de casa tão cedo e me sentar em frente ao notebook da empresa usando um moletom causa um certo desconforto no início. Dá a impressão de que não estamos trabalhando, de que estamos fazendo alguma coisa errada.

Depois do sentimento de culpa vem o relaxo. Até hoje eu continuo levantando cedo para poder levar minha esposa até a estação de trem, que fica à exatos 7 minutos de minha casa. Nas primeiras semanas, eu voltava para a cama e dava mais uma dormida até às nove da manhã. Já consegui chegar no trabalho com 30 minutos atraso mesmo estando a vinte metros dele. Tomar café da manhã em frente ao notebook virou rotina. Mas isso passou. Acho que conforme o tempo foi passando, o corpo e a mente vão ficando mais descançados, até uma hora que não dá mais vontade de voltar para a cama. Além do mais, eu ainda tenho uma lista razoável de livros para ler. O tempo que antes eu gastava no trânsito, agora eu gasto lendo e isso está dando muito certo.

Meus vizinhos agora devem pensar que fiquei desempregado e que sou sustentado pela minha esposa. Tem uma pessoa que além limpar minha casa, prepara meu almoço. Assim, eu consigo almoçar em 15 minutos e não vou voltar correndo para o notebook depois disso. Eu preciso fazer minha fotosíntese. Para isso vou tomar um café expresso em uma padaria que fica láááááááá em cima e aproveito para tomar sol caminhando até a padaria. Ter horário para tomar sol até parece programa de presidiário. Às vezes eu levo meus cães para passear durante meu horário de almoço. Eu não culpo meus vizinhos. O que você pensaria se visse uma pessoa de uns trinta anos de idade, com a barba de dias na cara, passeando com cachorros ao meio dia? "Esse aí leva cães para passear para poder conseguir o dinheiro da pinga".

Bom, eu estou mesmo babando e andando para os vizinhos. Complicado é o que seus parentes pensam de você. Para tomar café, eu passo em frente à casa de uma tia. Sabe aquela tia que tudo o que ela conseguiu entender sobre o que você faz é que você trabalha com computadores, ela só não tem certeza se é limpando ou vendendo. Numa dessas idas e vindas do café, acabei me encontrando com ela. "E aí Fernando, está de folga?" - ela pergunta. "Não tia, agora eu trabalho em casa" - eu respondo todo satisfeito, mas olhando sua expressão, dá pra imaginar as engrenagens na cabeça dela - "Vixe tadinho, deve estar fazendo aqueles bicos do tipo Trabalhe em casa, pergunte-me como".

Mais difícil que se convencer de que você pode trabalhar em casa, é convencer os outros de que você está trabalhando em casa. Na época em que eu fazia Home Office apenas 2 vezes por semana, minha esposa sempre me perguntava - "Você vai trabalhar amanhã?", como se eu não trabalhasse em casa. Meu irmão uma vez me disse, " ...mas você não vai ficar em casa amanhã? Então, eu passo lá e a gente vai ver aquela peça do carro".

Trabalhar em casa exige disciplina, embora eu possa fazer meu próprio horário, eu prefiro ter horário fixo para almoçar, começar e parar de trabalhar. Não estou falando apenas de trabalhar menos. Trabalhar demais é um risco maior. Você já está alí com um pepino pra resolver, falta só mais aquele último teste, que é o último há uns 5 testes atrás, você não tem que pegar trânsito, já está no conforto do seu lar e quando você vê já são nove da noite.

Não muda nada para a empresa?

Eu trabalho em um time global. Uns aqui, outros nos Estados Unidos e India. O gerente do time de desenvolvimento está em outro hemisfério. Você acha mesmo que isso vai fazer alguma diferença pra ele? Mesmo quando eu estava trabalhando no prédio, tudo que eu precisava era de um ponto de rede. Apesar de eu ter um notebook, este é utilizado para abrir uma sessão remota em uma das máquinas que servem os laboratórios externos (Brasil e India). As máquinas de teste são virtuais em sua maioria, as reais também são acessadas remotamente. Todas as reuniões são feitas via Web Conference. Seu ramal é desviado para uma ferramenta VOIP no notebook. Você disca um ramal pra falar com alguém do outro lado do planeta. Tudo através de um ponto de rede.

Quando você vira Home Office, a empresa te dá um limite de reembolso para comprar móveis, aparelho e conta telefônica, Internet banda larga, impressora e material de escritório. Obviamente tudo tem que ser devolvido quando você deixar de ser Home Office. Felizmente minha casa já tinha todos os requisitos necessários, e assim, não vou ficar usando uma mesa ou cadeira que não são minhas mesmo. O bom disso é que eu posso trocá-los quando eu quiser.

O que principalmente vai mudar para a empresa, é que agora eles terão mais uma baia livre. Uma empresa deste tamanho não cabe nos prédios onde estamos (isso mesmo, no plural). A empresa incentiva o Home Office. Uma das cláusulas da transição para Home Office é a de que você deve permanecer no mínimo um ano nesta condição. Fiquei preocupado quando li essa parte, então fui perguntar às pessoas que já eram Home Office o que eu não estava conseguindo ler nas entrelinhas. O que acontece é que na empresa que trabalho, a grande maioria dos funcionários são vendedores. Vendedor é o tipo de profissional extrovertido, que fala bastante e preza muito o contato com as pessoas. Para esse tipo de pessoa, ficar enclausurado dentro de casa é a morte. Tanto que muitas pessoas que são Home Office deixam suas casas para disputar baias vagas aos tapas lá no prédio. Minha esposa mesmo, se ficasse em casa, morreria louca mordendo o braço do sofá em menos de um mês.

Pois é, existem pessoas e pessoas. Como você já deve ter percebido, sou desenvolvedor de software. Sou do tipo de pessoa que prefere ter seu tempo para fazer as coisas, gosto de ter meu espaço. Não estou dizendo que tenho alergia a pessoas e que ando com um saco de papel enfiado na cabeça. Só estou dizendo que não me importo de ficar trabalhando sozinho em casa, onvindo meu som preferido enquanto faço tudo pela internet. Aliás, isso me dá um gancho pra falar de um livro que li e que imaginei nunca ter a oportunidade de comentar a respeito neste blog técnico. Este livro fala justamente das diferenças entre pessoas extrovertidas e introvertidas. Explica que apesar de 75% das pessoas serem extrovertidas, não há nada errado em ser introvertido. O livro explica que pessoas introvertidas tem lá suas vantagens. Elas se concentram com maior facilidade. Conhecem menos assuntos, mas com mais profundidade. Tem menos amigos, mas são amizades mais intensas. Achei o livro interessante, com suas estatísticas e fundamentos para explicar o por quê do comportamento das pessoas.

Ainda não falei tudo que poderia falar sobre minha transição para Home Office, mas este post já está ficando longo demais para um Off Topic.
Até mais...

Step into Kernel (Firewire)

fernando@driverentry.com.br (Fernando Roberto da Silva) — Wed, 02 Jul 2008 17:54:00 +0000

Já sei! Seu computador de teste não tem porta serial e você precisa fazer debug de Kernel nele. Creio que depois da porta serial, a maneira mais utilizada para depurar o Kernel do Windows seja utilizando uma interface firewire. Ainda existe a opção de se fazer o debug de Kernel utilizando USB 2.0, mas isso ainda é para poucos, já que além de apenas ser suportado pelo Windows Vista, ainda é necessário ter um cabo especial. Os detalhes sobre debug de Kernel pela porta USB podem ser encontrados neste post. Hoje a história é outra.

Mas eu não tenho porta firewire

Larga a mão de ser chorão. O que importa aqui não é o fato de você ter ou não uma porta firewire em seu micro de desenvolvimento, mas sim o fato da máquina do cliente ter uma porta firewire. Você sabe muito bem que pela Lei de Murphy, aquele problema que você nem sabia que existia só acontece naquela máquina que não tem portas seriais. Então melhor você estar preparado para encontrar esse tipo de coisa. Elas realmente acontecem. Sua reclamação poderia ainda ser diferente: "Mas eu não tenho porta serial". Alguns notebooks que não possuem portas seriais oferecem portas firewire, mas idependente disso, existem placas tanto PCI quanto PCMCIA capazes que disponibilizar a interface IEEE 1394. Desta forma, seja sua máquina um desktop ou um notebook, existem meios delas ganharem portas firewire.

Configurando o lado TARGET

Se você ainda não sabe o que significa lado HOST/TARGET e está completamente perdido sobre o assunto, leia este post introdutório antes de continuar. Configurar o lado TARGET não é muito diferente do que já vimos em outros posts desta série. Podemos editar o aquivo boot.ini, como já vimos neste post para adicionar as seguintes configurações de debug.

[boot loader]
timeout=10
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)<<...>>/fastdetect /debugport=1394 /channel=44
multi(0)disk(0)<<...>>/fastdetect

O número do canal a ser utilizado pode ser qualquer um, mas o valor deve ser o mesmo em ambos os lados TARGET e HOST. Caso você esteja querendo depurar um Windows Vista, o método de configurar as mesmas coisas mudaram um pouco como vimos neste outro post. A figura a seguir mostra os passos para setar o modo de configuração do sistema para interface IEEE 1394.

Lembre-se que aqui estamos apenas configurando a maneira com a qual o sistema seria depurado caso exista uma entrada de debug na lista de boot da máquina. Este post mostra os detalhes de como criar uma entrada adicional nesta lista e configurá-la para debug.

Só isso? Nem doeu!

Para se fazer Kernel Debug utilizando um cabo firewire, ambos os micros devem estar rodando Windows XP ou superior, não necessariamente a mesma versão em ambos os lados. Existe uma particularidade quanto utilizar sistemas anteriores ao Windows XP SP2 ou Windows 2003 Server sem service pack no lado TARGET da história, conforme informa esta página. Para estes sistemas, deve-se desabilitar a controladora do barramento 1394. Isso é necessário porque o Windows, que está sendo depurado inconscientemente, pode querer tentar conversar com a interface Firewire durante o debug, e isso pode fazer com que a conexão com o depurador caia. Para desabilitar essa interface nos sistemas acima citados, você deve simplesmente selecionar o ítem "Disable" no menu de contexto que aparece quando você clica com o botão direito do mouse sobre a controladora firewire.

Posso desabilitar a controladora Firewire independente da versão do Windows? Não, se você desabilitar a controladora em sistemas posteriores aos acima citados, você poderá não conseguir depurar o sistema quando ele mudar entre os estados de energia do sistema. Estados de energia? Você está falando da aura do computador? Supondo que você está querendo depurar seu driver durante as transições energia do sistema que são gerenciadas pelo Power Manager. O Power Manager determina qual barramento pode ser desligado para economizar energia. Assim, o sistema pode decidir desligar a interface firewire durante seu debug de um driver qualquer, e dessa forma, você não vai conseguir acompanhar as IRPs de gerenciamento de energia chegando ao seu driver.

Configurando o lado HOST

Normalmente, para fazer iniciar uma sessão de debug do lado HOST, basta abrir o WinDbg, selecionar o ítem "Kernel Debug..." do menu File, clicar na aba 1394, preencher o número do canal que se deseja utilizar, clicar OK como mostra a figura abaixo e correr para o abraço.

Tudo isso que acabei de descrever continua valendo, mas para que seja possível utilizar firewire do lado HOST, o WinDbg precisa instalar os drivers virtuais de acesso ao barramento IEEE 1394, como mostra nesta página. O WinDbg faz isso automagicamente quando você seleciona as opções acima, mas os drivers só poderão ser instalados se você estiver logado como administrador do sistema. Caso contrário você receberá a seguinte mensagem.

Pô Fernando, sou desenvolvedor de driver! Você acha mesmo que não sou administrador da minha máquina? Tudo bem, você pode até ser, mas mesmo sendo um administrador no Windows Vista você precisará executar o WinDbg clicando com o botão direito do mouse sobre o ícone do WinDbg e selecionar o ítem "Run as Administrator". Aí sim, você repete o procedimento descrito acima para que os drivers virtuais sejam instalados. Esse procedimento é necessário somente na primeira vêz que você utiliza a porta firewire para debug, nas próximas vezes, os drivers já estarão instalados. Para quem estiver utilizando um sistema anterior ao Vista e já estiver utilizando uma conta admininstrativa, é como meu amigo Thiago diz: "Sai na urina". Ou seja, o driver virtual será instalado e você terá a saída como mostra a figura abaixo, que demonstra as mesmas operações realizadas no Windows Vista rodando o WinDbg como Administrador.

Daí em diante é só debug mesmo.

Dump Racing

Aproveitando que estamos todos aqui reunidos, vamos fazer um teste e verificar se a velocidade do firewire ajuda mesmo com relacão à fazer Kernel Debug. Vamos imaginar a situação onde você esteja em visita a um cliente onde obviamente seu driver não está funcionando adequadamente. Lembra daquele bug que você nem sabia que existia? Pois bem, se trata de um deadlock. Deadlock são especialmente queridos na hora de fazer debug, porque você está lá quando o problema acontece, mas tela azul que é bom nada. Nessa situação, você pode gerar um arquivo de dump da máquina e deixar para analizar o problema em casa, afinal de contas, roupa suja se lava em casa, e assim poder liberar a máquina do cliente para uso, já que normalmente nessas situações, ficam umas três pessoas em cima de você perguntando "E aí? Descobriu o problema?" a cada 3 minutos. Configurei meu desktop aqui de casa para fazer debug do Windows Vista por uma porta serial. Esta máquina tem 2GB de memória RAM. Um arquivo de dump full é uma cópia de tudo que esta na memória do computador naquele instante, por isso, nada mais justo que este arquivo tenha aproximadamente 2GB de tamanho. Este arquivo pode ser gerado na máquina HOST durante uma sessão de debug utilizando o comando .dump. Segue abaixo a saída deste comando quando utilizado sobre uma conexão serial.

0: kd> .dump /f c:\Temp\SERIAL.DMP
Creating a full kernel dump over the COM port is a VERY VERY slow operation.
This command may take many HOURS to complete.  Ctrl-C if you want to terminate the command.
Creating c:\Temp\SERIAL.DMP - Full kernel dump
Percent written 0
Percent written 1
Percent written 2
        :
        :

Vocês repararam na mensagem ameaçadora que nos foi exibida? Particularmente penso que estes engenheiros de software são todos uns desesperados, provavelmente por causa quantidade de café que eles consomem por dia. Já posso até imaginar quantos nem esperam o dump começar para já pressionar CTRL+C e interromper o processo. São uns covardes mesmo. Bom, já que isso vai me custar algum tempo, vou aproveitar para dar uma mijada.

Muito, mas muito tempo mesmo depois...

        :
        :
Percent written 97
Percent written 98
Percent written 99
Dump successfully written
0: kd>

OK, tudo bem até aqui. Agora vamos repetir o processo em uma sessão de debug utilizando o cabo firewire. A mesma máquina com a mesma quantidade de memória e até o mesmo comando.

1: kd> .dump /f c:\Temp\FIREWIRE.DMP
Creating c:\Temp\FIREWIRE.DMP - Full kernel dump
Percent written 0
Percent written 5
Percent written 10
        :
        :
Percent written 90
Percent written 95
Dump successfully written
1: kd>

Tá, tudo bem, a contagem vai de cinco em cinco ao invés de um em um como foi com o cabo serial, grande coisa. Não é a toa que demore mais pela porta serial, eles gastam processamento com tudo. Agora podemos comparar as datas de criação e modificação nos atributos de cada arquivo para poder determinar quanto tempo levou para poder gerá-los.

Lembrando que o mês de junho termina no dia 30, podemos concluir que o dump pela porta serial levou aproximadamente 2 dias, 5 horas e 12 minutos. É uma pena essa janela não mostrar os segundos para termos mais precisão aqui. De qualquer forma, lembrando também que cada minuto tem 60 segundos, o mesmo dump gerado pela porta firewire levou aproximadamente 7 minutos. Nossa, foi quase! Se não fosse por essa pequena vantagem de 3187 minutos.

Até mais...

A matéria mais difícil

fernando@driverentry.com.br (Fernando Roberto da Silva) — Tue, 24 Jun 2008 19:23:00 +0000

Como alguns de vocês já estão cansados de saber, estou cursando o quinto ano de Engenharia da Computação. No começo do curso, naturalmente pastei para poder aprender Cálculo, Álgebra, Física e aquelas outras matérias que tiram fumacinha da calculadora.

Como não pude sair do meu colegial técnico e ir direto para uma universidade, trabalhei um pouco na área até eu conseguir pagar a mensalidade de uma faculdade. Estagiário ganha pouco mesmo. Esse tempo, além de me trazer uma graninha extra por mês, também me trouxe um cadim de experiência. Não foi muita, mas o suficiente para identificar possíveis deslises de professores durante as aulas de programação. O curso de Engenharia da Computação tem duração de seis anos, e durante esse tempo eu ainda tinha que trabalhar, mesmo porque eu tinha que pagar a faculdade. Durante esse tempo acabei lendo um livro ou dois, ou três, quatro, cinco, enfim, alguns.

É natural os professores tenderem a não explicar exatamente como as coisas são ou funcionam, e assim, ganhar um pouco de tempo para poder abordar mais assuntos com menos detalhes. Afinal, você não aprende tudo o que precisa na universidade, mas você já consegue ter uma boa noção de onde você está se enfiando quando for trabalhar na área e por onde começar a buscar mais detalhes sobre determinado assunto. Eu mesmo, nos cursos de drivers que já dei, tento explicar o essencial, o que o aluno vai mesmo utilizar, mas sempre tento deixar claro que existem detalhes a serem vistos.

Durante o curso, eu mal podia esperar para ver as matérias técnicas, que me abririam os olhos para uma nova maneira de ver os dispositivos eletrônicos, circuitos integrados e os computadores. Depois de engolir algumas atravessadas de professores de Linguagem C e de Engenharia se Software, finalmente comecei a estudar algo realmente interessante. A matéria de Sistemas Operacionais é mesmo surpreendente. Nela estudamos diferentes sistemas operacionais que rodam sobre diferentes arquiteturas de computadores. Ufa! Pelo menos uma arquitetura e um sistema operacional eu conheço razoavelmente bem.

Tudo bem o professor dizer que Thread e Processo é a mesma coisa, explicar Inter Process Communication sem nem tocar no assunto Memória Virtual e Marshaling, mas foi show tentar engolir a explicação sobre Sincronismo e Gerenciamento de Interrupções dos sistemas operacionais. Tudo bem, eu só posso dizer que o professor escorregou em Windows, eu não conheço todos os outros Sistemas Operacionais. Acho que ele só escolheu o sistema operacional errado na hora de dar um exemplo infeliz. Não me lembro das palavras exatas, mas meu professor nos ensinou que o Windows XP ainda não é um sistema operacional preemptivo, e que as chamadas ao sistema operacional não podiam acontecer concorrentemente. Primeiro uma, depois a outra e assim por diante. Particularmente acho que ele deve ter confundido XP com 9X. Afinal os dois possuem a letra X. Nessa hora eu tive que parar de ler o livro que eu estava lendo e pedir para ele repetir aquilo. Eu poderia ter ouvido errado, mas infelizmente não foi isso que aconteceu. Ele disse aquilo mesmo. Mais tarde na mesma aula ele nos disse que o Windows XP ainda não consegue gerenciar interrupções adequadamente, que se uma interrupção ocorre enquanto um processo está rodando, o sistema normalmente espera o processo inteiro terminar para que só depois ele possa atender à uma interrupção.

Como em toda sala de aula universitária, sempre existe um grupinho de alunos que odeiam o Windows e defendem uma outra opção de Sistema Operacional. Nada contra eles, nem contra a opção deles, mas de vêz em quando me aparece cada figura que é um caso sério. Enfim, estes logo disseram ironicamente aos risos: "É lógico! Porque é o mais inteligente a se fazer". Assim todos na sala começaram a rir desse péssimo exemplo de gerenciamento de interrupções do Windows. Eu nunca falo nada, sou aquele cara que chega uns 30 minutos mais cedo na sala pra poder ler meu livro em paz. Não saio fazendo campanha a favor do Windows nem contra outros sistemas. Não fico explicando como completar uma IRP para cada pessoa que encontro no café, mas essa eu não podia deixar passar em branco. Perguntei ao professor: "Nossa, que interessante isso! Onde foi mesmo que o senhor leu isso?". "Em qualquer livro de Sistemas Operacionais" ele me respondeu. Vejam só que inocência da minha parte, eu imaginava que os livros clássicos de Sistemas Operacionais tinham sido escritos quando o Windows XP ainda nem existia. Então eu disse: "Não é por nada, é que não é isso que tenho visto nos livros que tenho lido. Talvêz eu esteja lendo os livros errados."

	Windows Driver Model (1999) "The operating system can preempt any subroutine at any moment for an arbitrarily long period of time, so we cannot be sure of completing critical tasks without interfere or delay. Even if we take steps to prevent preemption, code executing simultaneously on other CPU in same computer can interfere with our code."
	Windows NT Device Driver Development (1999) "As was mentioned in Chapter 1, Windows NT is a pre-emptive, multithreaded, and multitasking, operating system. It employs a traditional operating system technique to provide this multitasking capability by associating a quantum with each thread when it starts running."
	Desvendando o Windows NT (1998) "Como o Windows NT implementa um escalador preemptivo, se outro thread, com uma prioridade mais alta se aprontar para execução, o thread sendo executado atualmente é solicitado antes de terminar sua fatia de tempo."
	Windows Internals (2005): "Windows implements a priority-driven, preemptive scheduling system the highest priority runnable (ready) thread always runs, with the caveat that thread chosen to run might be limited by the processors on wich the thread is allowed to run, a phenomenom called Processor Afinitty."
	Developing Drivers with Windows Driver Foundation (2007): "Windows is a preemptive multitasking operating system in wich multiple thread can try to aceess shared data or resources concurrently and multiple drivers functions can run concurrently."

Enfim, é óbvio que não vou discutir com meu professor e tornar minha vida acadêmica um inferno. Mais uma vez vou respirar fundo e fazer dizer aquele sonoro "Ahhhh tá...".

É nestes momentos que eu fico preocupado sobre um outro aspecto. Felizmente posso ouvir e filtrar o que professores de programação em Linguagem C e Sistemas Operacionais dizem, mas nada posso fazer quanto aos professores de Eletrônica, Inteligência Artificial, Microcontroladores e outras tantas matérias que estamos aprendendo. Será que estamos ouvindo as mesmas barbaridades e não sabemos?

De qualquer forma, a matéria que pensei que seria a mais fácil, agora é uma das que me atormentam.
Leia sempre...

Utilizando o Registry (Parte 2)

fernando@driverentry.com.br (Fernando Roberto da Silva) — Mon, 23 Jun 2008 19:38:00 +0000

Pois é, como eu estava dizendo na primeira parte deste post. Isso é muito código. Todo esse negócio parece trabalhoso, não? Montar uma UNICODE_STRING para o caminho da chave que se deseja acessar, montar um OBJECT_ATTRIBUTES com ela, abrir handle, determinar o tamanho dos valores a serem lidos, alocar um buffer grande suficiente, ler o valor que se deseja, desalocar qualquer buffer temporário utilizado no processo, e por fim, fechar o handle para a chave do registro. Você pode conferir quanto código utilizamos em nosso exemplo do post anterior para se ler dois valores no registro. Hoje veremos um grupo de rotinas de manipulação de registro que facilita esse processo.

Rotinas RTL de Registro

São apenas cinco as rotinas que compõem esse grupinho. Na referência você encontra uma descrição de cada uma delas. Esse grupo de rotinas tem como característica comum o fato de não termos que utilizar handles para as chaves. Os handles são abertos e fechados para cada operação. Outra característica comum é que você não precisa compor o nome completo da chave na qual estão os valores que você quer ler ou escrever. Essas rotinas trabalham com um esquema de nome de chave relativo a algum lugar pré-definido. Confuso? Vamos dar uma olhada numas das rotinas para que tenhamos um exemplo mais prático. Tentando seguir a mesma idéia do exemplo dado no post anterior, precisamos inicialmente verificar se a chave, onde os valores estão armazenados, existe de fato. Tem uma funçãozinha justamente para isso.

NTSTATUS 
  RtlCheckRegistryKey(
    IN ULONG  RelativeTo,
    IN PWSTR  Path
    );

Notem que o primeiro parâmetro dessa rotina é uma constante que indica qual será a referência a ser aplicada ao segundo parâmetro. Observe a tabela abaixo que foi retirada da referência.

Um exemplo seria o seguinte: Se usarmos RTL_REGISTRY_ABSOLUTE como primeiro parâmetro, o segundo deve ser o caminho completo da chave de registro. Afinal, temos que passar o caminho absoluto da chave. Por outro lado, se utilizarmos RTL_REGISTRY_SERVICES, o segundo parâmetro deveria ser apenas o complemento do caminho referente a chave Services. Foi esta a opção que utilizei no exemplo deste post. Observe como ficou nossa rotina de criação dos parâmetros no registro.

/****
***     CreateParams
**
**      Esta rotina é chamada quando não for detectada a chave
**      que contém os parâmetros. Ela cria a chave e os parâmetros
**      com valores pré-definidos.
*/
NTSTATUS
CreateParams(VOID)
{
    NTSTATUS        nts = STATUS_SUCCESS;
    WCHAR           wzParam[] = L"DriverEntry.com.br";
    ULONG           ulParam = 0x12345678;
 
    __try
    {
        //-f--> Cria a chave onde os parâmetros serão armazenados.
        //      Simples assim.
        nts = RtlCreateRegistryKey(RTL_REGISTRY_SERVICES,
                                   L"KernelReg2\\Parameters");
        if (!NT_SUCCESS(nts))
            ExRaiseStatus(nts);
 
        //-f--> Aqui escrevemos o valor numérico
        nts = RtlWriteRegistryValue(RTL_REGISTRY_SERVICES,
                                    L"KernelReg2\\Parameters",
                                    L"DoubleWord",
                                    REG_DWORD,
                                    &ulParam,
                                    sizeof(ulParam));
        if (!NT_SUCCESS(nts))
            ExRaiseStatus(nts);
 
        //-f--> E aqui a String. Notem que não foi necessário
        //      criar um UNICODE_STRING para isso.
        nts = RtlWriteRegistryValue(RTL_REGISTRY_SERVICES,
                                    L"KernelReg2\\Parameters",
                                    L"String",
                                    REG_SZ,
                                    wzParam,
                                    sizeof(wzParam));
    }
    __except(EXCEPTION_EXECUTE_HANDLER)
    {
        //-f--> Ops!
        nts = GetExceptionCode();
        ASSERT(FALSE);
    }
 
    return nts;
}

Mais uma vêz, o código demonstrado aqui está disponível para download ao final deste post.

O fácil que complica

Pelo que pudemos ver até aqui, esse grupo de rotinas já facilitou um pouco nossa vida. Mas é na rotina de leitura que podemos ver a economia de código acontecer de verdade. O custo disso fica por conta de entender como a rotina de leitura funciona.

NTSTATUS 
  RtlQueryRegistryValues(
    IN ULONG  RelativeTo,
    IN PCWSTR  Path,
    IN PRTL_QUERY_REGISTRY_TABLE  QueryTable,
    IN PVOID  Context,
    IN PVOID  Environment  OPTIONAL
    );

Olhando assim nem parece que ela morde, mas se você der uma olhada na referência, verá que ela pode ser bem flexivel. Flexibilidade as vezes é traduzido por "Difícil de acertar a maneira certa de utilizar". Os dois primeiros parâmetros são os já conhecidos de antes. A coisa começa a mudar com o terceiro parâmetro, que é uma tabela que contém os detalhes dos valores a serem lidos do registro. Não vou entrar nos detalhes de cada parâmetro desta rotina neste post. Vou apenas fazer o código equivalente ao exemplo do post anterior.

/****
***     LoadParams
**
**      Esta rotina carrega as variaveis globais com os
**      valores recuperados do registro.
*/
NTSTATUS
LoadParams(VOID)
{
    NTSTATUS                    nts = STATUS_SUCCESS;
    RTL_QUERY_REGISTRY_TABLE    QueryTable[] =
    {
        { NULL, RTL_QUERY_REGISTRY_DIRECT | RTL_QUERY_REGISTRY_REQUIRED,
          L"DoubleWord", &g_ulParam, REG_NONE, NULL, 0 },
        { NULL, RTL_QUERY_REGISTRY_DIRECT | RTL_QUERY_REGISTRY_REQUIRED,
          L"String", &g_usParam, REG_NONE, NULL, 0 },
        { NULL, 0, NULL, NULL, REG_NONE, 0, NULL }
    };
 
    __try
    {
        //-f--> Caso esta rotina seja chamada mais de uma vez, vamos liberar
        //      o buffer deste parâmetro.
        if (g_usParam.Buffer)
            RtlFreeUnicodeString(&g_usParam);
 
        //-f--> Aqui todos os valores da tabela são lidos
        nts = RtlQueryRegistryValues(RTL_REGISTRY_SERVICES,
                                     L"KernelReg2\\Parameters",
                                     QueryTable,
                                     NULL,
                                     NULL);
        if (!NT_SUCCESS(nts))
            ExRaiseStatus(nts);
    }
    __except(EXCEPTION_EXECUTE_HANDLER)
    {
        //-f--> Ops!
        nts = GetExceptionCode();
        ASSERT(FALSE);
    }
 
    return nts;
}

Não, não está faltando nada. É só isso mesmo. Vamos olhar mais de perto o que fizemos aqui. A tabela que preenchemos tem os dados das leituras a serem realizadas e é definida como mostra abaixo.

typedef struct _RTL_QUERY_REGISTRY_TABLE {
    PRTL_QUERY_REGISTRY_ROUTINE QueryRoutine;
    ULONG Flags;
    PWSTR Name;
    PVOID EntryContext;
    ULONG DefaultType;
    PVOID DefaultData;
    ULONG DefaultLength;
} RTL_QUERY_REGISTRY_TABLE, *PRTL_QUERY_REGISTRY_TABLE;

Olhando cada membro dela temos:

QueryRoutine: Aqui você tem um ponteiro de função que será chamado quando o este ítem da tabela for lido no registro. Não usamos este método em nosso exemplo. Existem algumas coisas interessantes sobre essa rotina de callback. Ela é chamada para cada ítem desta tabela, mas se o valor a ser lido for do tipo REG_MULTI_SZ, a rotina de callback é chamada uma vez para cada string contida neste valor. Consulte a referência para uma completa descrição destes detalhes.
Flags: O flag que utilizamos aqui foi o RTL_REGISTRY_DIRECT que sinaliza que não usaremos o método do callback. Outro flag é o RTL_QUERY_REGISTRY_REQUIRED que indica que o valor descrito nesta linha da tabela é obrigatório. Caso o valor não seja encontrado, RtlQueryRegistryValues retorna erro e os demais valores não serão lidos.
Name: Aqui vem o nome do valor a ser lido. Note que não é um UNICODE_STRING, mas um array de WCHAR terminado em zero.
EntryContext: Em nosso exemplo, este parâmetro é o buffer onde o valor lido será armazenado, mas nos casos onde recebemos a chama pela a rotina de callback, este valor é passado como um dos parâmetros.

Os parâmetros DefaultType, DefaultData e DefaultLengh seriam utilizados caso o valor não existisse e não fosse um valor obrigatório.

Cada valor a ser lido é representado por uma linha nesta tabela. A rotina identifica o fim da tabela quando encontrar os membros QueryRotuine e Name forem NULL.

Calma aí Fernando! Muito bem, nada nessa manga, nada nessa e os valores são lidos? Espertinho você hein? Pensou que ia enganar todo mundo com essa conversinha? Muito bem! Onde é que eu indico o tamanho do buffer oferecido para a leitura?

Muito boa a sua pergunta! Acho até que eu mesmo não teria feito uma pergunta tão boa. O tamanho o buffer é indicado pelo próprio buffer. No caso da string, passamos um ponteiro para um UNICODE_STRING, o tamanho do buffer da string já é descrito por essa estrutura, mas se o buffer desta estrutura for NULL, a rotina aloca o buffer do tamanho necessário. Temos que desalocar esse buffer quando não for mais utilizá-lo. Para leituras onde o buffer resultante é menor ou igual ao sizeof(ULONG) então o valor resultante é armazenado diretamente no lugar apontado por EntryContext. Para demais detalhes consulte a referência.

Esta função é bem flexível e não vou conseguir colocar tudo que essa rotina oferece em um único post, mas sintam-se a vontade para mandar suas dúvidas em relação a ela.

Have fun!

Download KernelReg2.zip