Александр Тарво - Использование 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. Этот код будет возвращен методом
