Использование NuMega DriverStudio для написания WDM-драйверов - Александр Тарво

VOID XDSPdrvDevice::StartIo(KIrp I) {

 t << "Entering StartIo, " << I << EOL;

 // Здесь надо проверить, отменен этот запрос или нет. Это производится при помощи вызова

 //метода TestAndSetCancelRoutine. Также этот метод устанавливает новую функцию отмены

 //пакетов, если это необходимо. Адрес новой функции передается вторым параметром. Если

 //он равен NULL,то вызывается старая функция. Если пакет должен быть отменен, функция

 //вернет FALSE.

 if (!I.TestAndSetCancelRoutine(LinkTo(CancelQueuedIrp), NULL, CurrentIrp())) {

  //Пакет отменен.

  return;

 }

 // Начать обработку запроса.

 // Выбрать необходимую функцию

 switch (I.MajorFunction()) {

 case IRP_MJ_READ:

  //Чтение

  SerialRead(I);

  break;

 case IRP_MJ_WRITE:

  //Запись

  SerialWrite(I);

  break;

 case IRP_MJ_DEVICE_CONTROL:

  //IOCTL

  switch (I.IoctlCode()) {

  default:

   //Мы обрабатываем пакет, который не должен быть обработан.

   //Поэтому просто выходим.

   ASSERT(FALSE);

   break;

  }

  break;

 default:

  // Драйвер занес в очередь какой-то непонятный пакет,

  //он не должен быть обработан.

  ASSERT(FALSE);

  PnpNextIrp(I);

  break;

 }

}

Метод Create вызывается, когда пользовательское приложение пытается установить связь с драйвером при помощи вызова API CreateFile(). Обычно этот запрос обрабатывается в нашем объекте устройства и нет смысла пересылать запрос устройству нижнего уровня.

NTSTATUS XDSPdrvDevice::Create(KIrp I) {

 NTSTATUS status;

 t << "Entering XDSPdrvDevice::Create, " << I << EOL;

 //Здесь можно вставить код пользователя, который должен быть вызван при установлении

 //приложением связи с устройством.

 status = I.PnpComplete(this, STATUS_SUCCESS, IO_NO_INCREMENT);

 t << "XDSPdrvDevice::Create Status " << (ULONG)status << EOL;

 return status;

}

Аналогично метод Close вызывается при разрыве связи приложения с драйвером.

NTSTATUS XDSPdrvDevice::Close(KIrp I) {

 NTSTATUS status;

 t << "Entering XDSPdrvDevice::Close, " << I << EOL;

 //Здесь можно вставить код пользователя, который должен быть вызван при разрыве

 //приложением связи с устройством.

 status = I.PnpComplete(this, STATUS_SUCCESS, IO_NO_INCREMENT);

 t << "XDSPdrvDevice::Close Status " << (ULONG)status << EOL;

 return status;

}

В этих методах можно ввести проверки каких-либо условий. Отвлечемся на секунду от нашей PCI-карточки и обратим внимание на другой хороший пример — тот же программатор микроконтроллеров. Предположим, пользователь подключил программатор к компьютеру и начинает записывать в память микроконтроллера разработанную им программу. В принципе, ничто не помешает ему открыть еще одну копию программы и писать в ту же микросхему что-то совсем другое. В результате, в эту несчастную микросхему запишется невообразимая каша. Для того, чтобы избежать такой ситуации, в объекте драйвера надо установить флаг, который будет показывать, свободно ли это устройство, или оно уже кем-то используется. Это может выглядеть так:

NTSTATUS MyPrettyDevice::OnStartDevice(KIrp I) {

 NTSTATUS status = STATUS_SUCCESS;

 I.Information() = 0;

 . . . //Какая-то инициализация – может, PCI,

 //может – какое-то другое оборудование…

 //Устройство только что заработало – конечно, оно свободно…

 m_AlreadyUsed = false;

 return status;

}

NTSTATUS MyPrettyDevice::Create(KIrp I) {

 NTSTATUS status;

 if (m_AlreadyUsed)

  //Это устройство уже используется кем-то. Нельзя допустить его использование

  //несколькими приложениями одновременно.

  //Возвращаем ошибку.

  status = I.PnpComplete(this, STATUS_INVALID_PARAMETER, IO_NO_INCREMENT);

 else {

  //Это устройство свободно. Устанавливаем флаг и возвращаем успех.

  m_AlreadyUsed = false;

  status = I.PnpComplete(this, STATUS_SUCCESS, IO_NO_INCREMENT);

 }

 return status;

}

NTSTATUS MyPrettyDevice::Close(KIrp I) {

 NTSTATUS status;

 //Пользователь закончил работу с устройством, теперь оно свободно.

 //Сбрасываем флаг.

 m_AlreadyUsed = false;

 status = I.PnpComplete(this, STATUS_SUCCESS, IO_NO_INCREMENT);

 return status;

}

Функция SerialRead вызывается, когда драйвер получает запрос на чтение. Это важная функция. Т.к. мы хотим, чтобы приложение пользователя могло читать и писать в память микросхемы, то именно сюда необходимо добавлять наш код. Все фрагменты кода, добавленные программистом, будут выделены жирным шрифтом:

//This code was added by the programmer

Фактически в данном методе мы должны прочитать содержимое памяти и передать его приложению пользователя. Но тут самое время вспомнить, что плата обменивается с памятью 4– байтными словами. Поэтому для операций с памятью следует применять метод ind/outd.

void XDSPdrvDevice::SerialRead(KIrp I) {

 t << "Entering XDSPdrvDevice::SerialRead, " << I << EOL;

 NTSTATUS status = STATUS_SUCCESS;

 //Здесь мы получаем буфер пользователя. Он передается через Irp.

 KMemory Mem(I.Mdl());

 PUCHAR pBuffer = (PUCHAR) Mem.MapToSystemSpace();

 //Теперь pBuffer – указатель на буфер пользователя.

 //Здесь мы получаем число 4-байтных слов, которое должно быть прочитано. Оно также

 //передается через Irp, как запрашиваемое количество байт для чтения.

 ULONG dwTotalSize = I.ReadSize(CURRENT);

 ULONG dwBytesRead = dwTotalSize;

 //Здесь мы читаем заданное число байт из памяти устройства. Плата XDSP680 обменивается

 //с памятью 4-байтными словами.Начальный адрес – 0, dwTotalSize 4-байтных слов будут

 //прочитаны в буфер pBuffer.

 m_MainMem.ind(0,(ULONG*)pBuffer,dwTotalSize);

 //Возвращаем количество прочитанных слов

 I.Information() = dwBytesRead;

 I.Status() = status;

 //Обработать следующий IRP-пакет.

 PnpNextIrp(I);

}

Метод SerialWrite работает практически так же, только он записывает данные в память устройства, а не считывает их.

void XDSPdrvDevice::SerialWrite(KIrp I) {

 t << "Entering XDSPdrvDevice::SerialWrite, " << I << EOL;

 NTSTATUS status = STATUS_SUCCESS;

 KMemory Mem(I.Mdl());

 PUCHAR pBuffer = (PUCHAR) Mem.MapToSystemSpace();

 ULONG dwTotalSize = I.WriteSize(CURRENT);

 ULONG dwBytesSent = dwTotalSize;

 m_MainMem.outd(0,(ULONG*)pBuffer,dwTotalSize);

 I.Information() = dwBytesSent;

 I.Status() = status;

 PnpNextIrp(I);

}

Как мы упоминали ранее, для большинства драйверов устройств недостаточно функций чтения и записи. Мало-мальски сложное устройство требует еще и множества других операций: получить состояние, получить информацию об устройстве, как-то отконфигурировать его. Для выполнения этих задач служат функции управления вводом-выводом, IO Control; сокращенно — IOCTL. IOCTL предоставляет программисту возможность разработать практически неограниченное количество различных функций управления устройством.

И драйвер, и приложение пользователя различают, какую функцию управления устройством вызвать, при помощи IOCTL-кодов. Такой код представляет собой обыкновенное 32-разрядное число. Для удобства ему директивой #define задают какое-то понятное имя. Например, в нашем случае зададим IOCTL-код, при получении которого драйвер будет возвращать количество памяти "на борту" PCI-устройства.

#define XDSPDRV_IOCTL_GETMEMSIZE 0x800

Если при чтении драйверу посылается IRP-пакет со старшим кодом функции IRP_MJ_READ, при записи — IRP_MJ_WRITE, то при вызове функции DeviceIOControl для нашего устройства драйвер получает пакет со старшим кодом IRP_MJ_IOCONTROL и младшим — код самой IOCTL-функции. Метод DeviceControl вызывается при получении драйвером IRP со старшим кодом IRP_MJ_DEVICE_CONTROL. Она действует подобно методу StartIo. В зависимости от кода IOCTL производится вызов соответствующей функции.

NTSTATUS XDSPdrvDevice::DeviceControl(KIrp I) {

 NTSTATUS status;

 t << "Entering XDSPdrvDevice::Device Control, " << I << EOL;

 switch (I.IoctlCode()) {

 case XDSPDRV_IOCTL_GETMEMSIZE:

  //Получен определенный нами IOCTL-код XDSPDRV_IOCTL_GETMEMSIZE.

  //Вызвать соответствующий обработчик.

  status = XDSPDRV_IOCTL_GETMEMSIZE_Handler(I);

  break;

 default:

  //Этот код не определен.

  status = STATUS_INVALID_PARAMETER;

  break;

 }

 if (status == STATUS_PENDING)

 // Если драйвер по каким-то причинам отложил обработку запроса, переменной status

 //присваивается значение STATUS_PENDING. Этот код будет возвращен методом